masamune_ai_debugger 3.3.1

AI debug overlay and error reporting adapter for Masamune apps.

Masamune AI Debugger

---

[GitHub] | [YouTube] | [Packages] | [X] | [LinkedIn] | [mathru.net]

---

Plug-in packages that add functionality to the Masamune Framework.

For more information about Masamune Framework, please click here.

https://pub.dev/packages/masamune

Usage

A floating UI will be added to the Debug build of the Masamune app that sends instructions, screenshots, and unhandled errors to SamuraiAI. Neither the UI nor the communication will be active in Release/Profile builds. The public controller's lifecycle, upload, send, incident, and log methods are also no-ops outside Debug builds.

import "package:masamune_ai_debugger/masamune_ai_debugger.dart";

final aiDebugger = AIDebuggerMasamuneAdapter(
  manualModel: AIDebugModel.opus,
  manualPermissionMode: AIDebugPermissionMode.plan,
  errorModel: AIDebugModel.opus,
  errorPermissionMode: AIDebugPermissionMode.plan,
  performanceModel: AIDebugModel.opus,
  performancePermissionMode: AIDebugPermissionMode.plan,
  modelLoadTimeout: const Duration(seconds: 5),
  indicatorTimeout: const Duration(seconds: 10),
);

void main() {
  runMasamuneApp(
    (ref) => MasamuneApp(
      masamuneAdapters: [aiDebugger],
      home: const MyHomePage(),
    ),
    masamuneAdapters: [aiDebugger],
  );
}

Create one adapter instance and pass that same instance to both MasamuneApp and runMasamuneApp. projectId is read from MASAMUNE_AI_DEBUGGER_PROJECT_ID by default. You can still pass it directly to the constructor when using a custom integration.

Do not embed the connection target and API key in the source code; specify them during debug startup.

flutter run \
  --dart-define=MASAMUNE_AI_DEBUGGER_PROJECT_ID=Users-mathru-Documents-github-myapp \
  --dart-define=MASAMUNE_AI_DEBUGGER_ENDPOINT=https://your-tailnet-host/__samurai \
  --dart-define=MASAMUNE_AI_DEBUGGER_API_KEY=your-key

APIキーは SamuraiAI の Settings で作成します。Debug APK/IPAにも値は含まれるため、配布せず、不要になったキーは無効化してください。スクリーンショットは手動操作時、未処理エラー検出時、性能閾値超過時だけ送信されます。

projectId / endpoint / apiKey をコンストラクタで省略すると、上記の dart-define が読み込まれます。既定の SamuraiAI コールバックを利用する場合は3つの値が必要です。明示的なコンストラクタ引数は dart-define より優先されます。

フローティングアイコンはタップするとそのまま開き、長押しすると現在画面のスクリーンショットを撮影してから開きます。

メッセージフォーム下部のMode／Modelボタンでは、次に手動送信するセッションの plan / bypassPermissionsとhaiku / sonnet / opus / mythosを選択できます。 設定ボタンでは、未処理エラー時と計測超過時のMode／Model、およびモデル読込と インジケーターの超過判定時間を個別に設定できます。これらの値は端末内へ保存され、 同じproject IDの次回起動時に復元されます。

Custom AI provider

SamuraiAI is the default provider. To connect another AI or backend, pass callbacks for each API operation. Custom callbacks receive semantic values instead of SamuraiAI-specific URLs or JSON payloads, so endpoint and apiKey are not required when all callbacks are supplied.

final customDebugger = AIDebuggerMasamuneAdapter(
  projectId: "my-project",
  registerRun: myRegisterRun,
  heartbeat: myHeartbeat,
  endRun: myEndRun,
  uploadScreenshot: myUploadScreenshot,
  sendRequest: mySendRequest,
  reportIncident: myReportIncident,
  uploadEvents: myUploadEvents,
);

The callback typedefs are AIDebugRegisterRunCallback, AIDebugHeartbeatCallback, AIDebugEndRunCallback, AIDebugUploadScreenshotCallback, AIDebugSendRequestCallback, AIDebugReportIncidentCallback, and AIDebugUploadEventsCallback. To receive the selected model and permission mode, use configuredSendRequest (AIDebugConfiguredSendRequestCallback) and configuredReportIncident (AIDebugConfiguredReportIncidentCallback). The legacy callbacks remain available for integrations that do not use session settings. The corresponding AIDebuggerMasamuneAdapter.default* static functions expose the default SamuraiAI implementations. The existing post callback remains available for replacing only the low-level HTTP transport used by those defaults.

upload() returns the provider-specific screenshot identifier, not a URL. AIDebugHttpException represents a non-2xx response returned by the AI debug API; connection and transport failures may use other exception types.

遅延の自動検出

Debugビルドでは、既存の LoggerAdapter のperformance traceを使って次を自動計測します。

• MasamuneのDocument／Collectionモデルの load・reload・next（既定5秒）
• Future.showIndicator 経由のインジケーター表示（既定10秒）
• MeasuredCircularProgressIndicator / MeasuredLinearProgressIndicator の表示時間（既定10秒）

処理が終わらなくても閾値へ達した時点で、現在画面と直近ログをperformance incidentとして送信し、SamuraiAIにPlan Modeの調査セッションを作成します。同一処理は既存の重複排除と時間当たり上限の対象です。閾値以下で完了した処理は duration_ms の通常ログだけを送ります。

Widgetツリーへ待機表示を直接配置する場合は、固定かつ機密情報を含まないtraceNameを付けた MeasuredCircularProgressIndicatorまたはMeasuredLinearProgressIndicatorを使用してください。 常設の進捗率表示は標準ProgressIndicatorを使い、すでに計測済みのshowIndicatorへ計測版を渡して 二重計測してはいけません。閾値に Duration.zero を指定すると、そのカテゴリの自動incidentを無効化できます。

try-catchで握り潰した例外の報告

自動で設定される runZonedGuarded・FlutterError.onError・PlatformDispatcher.onError の3つは、いずれも 誰にもハンドリングされなかった例外専用のフックです。Dartの仕様上 try-catch でキャッチされた例外は これらに一切到達しないため、握り潰すとAI Debuggerからは完全に不可視になります。

catch節では Logger.error で明示的に報告してください。アプリテンプレートが生成する appLogger を使えば ref や BuildContext なしでどこからでも呼び出せます。

try {
  await something();
} catch (e, stackTrace) {
  await appLogger.error(e, stackTrace);
}

これによりスクリーンショットとスタックトレース付きの exception incidentが送信されます。 LoggerAdapter が一つも設定されていない場合は何もしないため、catch節で無条件に呼び出しても安全です。

報告漏れは masamune_lints の masamune_caught_error_should_report が警告します。 rethrow や throw で伝播させている場合は対象外です。意図的に握り潰す場合は // ignore: masamune_caught_error_should_report を付けてください。

握り潰した例外をincident化せずパンくずログ（severity error）だけに留めたい場合は reportHandledErrors に false を指定します。

AIDebuggerMasamuneAdapter(
  reportHandledErrors: false,
);

GitHub Sponsors

Sponsors are always welcome. Thank you for your support!

https://github.com/sponsors/mathrunet