Core ランチャー

ランチャーはホストアプリケーションのライフサイクル内で SNA を一緒に起動する場合に使います。Port 選択、プロセス処理、Electron packaging の詳細を隠し、client や React integration が使う server URL を渡せるようにします。

Launcher handle は、サーバー停止と、検出された URL を @sna-sdk/client または @sna-sdk/react へ渡すために十分な情報を公開します。

Options

dbPath は必須です。その他の field は optional です。

type SnaServerOptions = {
  port?: number;
  host?: string;
  appId?: string;
  authToken?: string;
  allowedOrigins?: string[];
  dbPath: string;
  cwd?: string;
  maxSessions?: number;
  permissionMode?: "acceptEdits" | "bypassPermissions" | "default";
  model?: string;
  permissionTimeoutMs?: number;
  nativeBinding?: string;
  env?: Record<string, string>;
  readyTimeout?: number;
  onLog?: (line: string) => void;
  dataDir?: string;
  logLevel?: "info" | "warn" | "error" | "silent";
  runtimePaths?: RuntimePaths;
  langfuse?: { publicKey: string; secretKey: string; baseUrl?: string };
};

type RuntimePaths = {
  claudeCode?: string;
  codex?: string;
  opencode?: string;
  grok?: string;
  cursor?: string;
};

Launcher は authToken と connection: { baseUrl, authToken } を一緒に 返します。Token を保存したり environment variable から組み立てたりせず、 connection を SnaClient または SnaProvider に渡すのが安全です。 生成された token は server handle が所有します。Token rotation が必要な場合は 新しい token でサーバーを起動し直します。

ホストアプリに設定画面がある場合や、ユーザーが選んだ CLI 位置を保存する 場合は runtimePaths を使ってください。env は最後の退避手段として 残り、runtimePaths から生成された値を上書きします。Server identity、 auth、bind host、origin policy は typed launcher field で指定してください。

Forked vs in-process

In-process mode は default agent を自動 spawn しません。Host が HTTP、WebSocket、または返された sessionManager から session を開始します。

Standalone server を直接実行する方法は開発/デバッグ用です。Product integration では startSnaServer() または startSnaServerInProcess() を 優先してください。Token、owner identity、bind host、shutdown lifecycle を host app が所有できます。

関数リファレンス

@sna-sdk/core/node の startSnaServer(options)

通常の Node host から SNA を開始し、接続情報と停止処理を持つ handle を返します。CLI、desktop host、local development process に使います。

const handle = await startSnaServer({
  appId: "my-app",
  dbPath: "/Users/me/Library/Application Support/MyApp/sna.db",
  port: 3099,
  allowedOrigins: ["http://localhost:5173"],
  runtimePaths: {
    claudeCode: "/opt/homebrew/bin/claude",
  },
});

const client = new SnaClient(handle.connection);

handle.stop();

Node launcher は Electron launcher と同じ standalone server implementation を使います。Host が HTTP app を直接 import せず、SNA を sibling process として置きたい場合に適しています。

@sna-sdk/core/electron の startSnaServer(options)

Electron host から SNA を開始します。Packaged application の制約を考慮するため、Electron main process では Node launcher よりこちらを優先してください。

Forked mode で packaged app を作る場合、Node が実行する SDK file を asar の外へ出す必要があります。

// electron-builder example
asarUnpack: ["node_modules/@sna-sdk/core/**"]

Launcher は .asar path を .asar.unpacked へ remap し、NODE_PATH を構成し、better-sqlite3 を探し、log を forward したうえで server が API server ready を出すまで待ちます。

Returns:

type SnaServerHandle = {
  process: ChildProcess;
  port: number;
  host: string;
  appId: string;
  baseUrl: string;
  authToken: string;
  connection: { baseUrl: string; authToken: string };
  stop(): void;
};

startSnaServerInProcess(options)

現在の Electron process 内で SNA を実行します。プロセス分離よりも密なライフサイクル統合が重要な場合だけ使ってください。

Returns:

type InProcessSnaServerHandle = {
  process: null;
  port: number;
  host: string;
  appId: string;
  baseUrl: string;
  authToken: string;
  connection: { baseUrl: string; authToken: string };
  sessionManager: SessionManager;
  httpServer: http.Server;
  initLangfuse(config: { publicKey: string; secretKey: string; baseUrl?: string }): Promise<void>;
  setTracerUser(userId?: string, userEmail?: string): void;
  stop(): Promise<void>;
};

stop() は session を終了し、runtime を dispose し、tracing を flush し、logger callback を整理してから HTTP server を閉じます。Host shutdown path で呼んでください。

resolveClaudeCli(options?)

利用可能な Claude Code CLI path を探します。ランタイムを開始できない理由を setup または diagnostics 画面で説明する場合に使います。

resolveCodexCli(options?)

同じ env/cache/static/shell 順序で利用可能な Codex CLI path を探します。

resolveOpenCodeCli(options?)

同じ env/cache/static/shell 順序で利用可能な OpenCode CLI path を探します。

validateClaudePath(path)

特定の Claude CLI path が利用可能か確認します。ユーザー指定の CLI path を保存する前に使ってください。

cacheClaudePath(path)

解決済み Claude CLI path を後続 launch のため保存します。Validation に成功したあと使ってください。

parseCommandVOutput(output)

shell command discovery output を normalized path result に parse します。主に CLI resolution internals と diagnostics に有用です。