@minimalcorp/tsunagi 0.3.3 → 0.4.0

package/dist/server/lib/agents/cli.js

@@ -0,0 +1,57 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const execFileAsync = promisify(execFile);
+/**
+ * エージェント CLI を実行するときの環境変数。プロファイルのログインを見るよう設定ディレクトリを付け、
+ * ログインより優先される認証情報の環境変数は取り除く。システム既定は外側 Terminal の環境のまま
+ * （普段ターミナルで CLI を使うときと同じ）。
+ */
+export function agentCliEnv(profile, configDir) {
+    const env = { ...process.env };
+    if (configDir) {
+        env[profile.configDirEnvKey] = configDir;
+        for (const key of profile.authEnvKeys)
+            delete env[key];
+    }
+    return env;
+}
+export async function runAgentCli(cli, args, env) {
+    return execFileAsync(cli, args, { env, timeout: 15_000 });
+}
+function isAtLeast(version, min) {
+    for (let i = 0; i < min.length; i++) {
+        if (version[i] !== min[i])
+            return version[i] > min[i];
+    }
+    return true;
+}
+/** CLI の更新を拾えるよう、短時間だけ結果を使い回す */
+const AVAILABILITY_TTL_MS = 30_000;
+const availabilityCache = new Map();
+async function detectAvailability(adapter) {
+    const minVersion = adapter.minVersion.join('.');
+    try {
+        const { stdout } = await runAgentCli(adapter.cli, ['--version'], process.env);
+        const match = /(\d+)\.(\d+)\.(\d+)/.exec(stdout);
+        const version = match ? match.slice(1).map(Number) : null;
+        return {
+            agent: adapter.id,
+            installed: true,
+            version: version?.join('.'),
+            supported: version !== null && isAtLeast(version, adapter.minVersion),
+            minVersion,
+        };
+    }
+    catch {
+        return { agent: adapter.id, installed: false, supported: false, minVersion };
+    }
+}
+/** `<cli> --version` で導入状況を確認する */
+export function getAgentAvailability(adapter) {
+    const cached = availabilityCache.get(adapter.id);
+    if (cached && Date.now() - cached.at < AVAILABILITY_TTL_MS)
+        return cached.value;
+    const value = detectAvailability(adapter);
+    availabilityCache.set(adapter.id, { at: Date.now(), value });
+    return value;
+}

package/dist/server/lib/agents/codex.d.ts

@@ -0,0 +1,2 @@
+import type { AgentAdapter } from './types.js';
+export declare const codexAdapter: AgentAdapter;

package/dist/server/lib/agents/codex.js

@@ -0,0 +1,285 @@
+import { createHash, randomUUID } from 'crypto';
+import { mkdir, readFile, rename, writeFile } from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { getStateDir } from '../data-path.js';
+import { prisma } from '../db.js';
+import { planToTodos } from '../tab-todos.js';
+import { agentCliEnv, runAgentCli } from './cli.js';
+// Fastify(API) の公開ポート。index.ts と同じ既定値・同じ環境変数を見る
+const SERVER_PORT = Number(process.env.TSUNAGI_SERVER_PORT) || 2791;
+const SERVER_URL = `http://localhost:${SERVER_PORT}`;
+/** hook の送信元タブを示すヘッダー（Codex のセッションIDはタブIDと別のため PTY の env から渡す） */
+const TAB_ID_HEADER = 'x-tsunagi-tab-id';
+/**
+ * hook のコマンド。タブごとの値は PTY の env（TSUNAGI_API_BASE / TSUNAGI_SESSION_ID）で渡し、
+ * 文字列自体は固定にする（trust のハッシュが変わらないように）。
+ * Codex は一部の hook の stdout を JSON の指示として読むため捨て、送信に失敗しても 0 で終える。
+ * `${VAR}` 形式は Codex が置換するため使わない
+ */
+const HOOK_COMMAND = `curl -s -m 5 -X POST "$TSUNAGI_API_BASE/api/hooks/codex"` +
+    ` -H "X-Tsunagi-Tab-Id: $TSUNAGI_SESSION_ID" -H 'Content-Type: application/json'` +
+    ` --data-binary @- >/dev/null 2>&1 || true`;
+/**
+ * 登録する hook と、その trust 用ラベル（hooks.state のキーとハッシュに使う）。
+ * SessionEnd / Interrupt は Codex 側で timeout が最大 3 秒に制限される
+ */
+const HOOK_EVENTS = [
+    { event: 'SessionStart', label: 'session_start', timeout: 10 },
+    { event: 'UserPromptSubmit', label: 'user_prompt_submit', timeout: 10 },
+    { event: 'PermissionRequest', label: 'permission_request', timeout: 10 },
+    { event: 'PostToolUse', label: 'post_tool_use', timeout: 10 },
+    { event: 'Stop', label: 'stop', timeout: 10 },
+    { event: 'Interrupt', label: 'interrupt', timeout: 3 },
+    { event: 'SessionEnd', label: 'session_end', timeout: 3 },
+];
+const SIMPLE_EVENTS = {
+    UserPromptSubmit: 'prompt',
+    PermissionRequest: 'permission',
+    Stop: 'stop',
+    // Esc での中断
+    Interrupt: 'interrupt',
+    // /exit・Ctrl+C 等
+    SessionEnd: 'session-end',
+};
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** TOML のキー・文字列（JSON の文字列表現は TOML の basic string として読める） */
+const tomlString = (value) => JSON.stringify(value);
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((key) => [key, sortKeys(value[key])]));
+    }
+    return value;
+}
+/**
+ * `-c` で渡した hook を承認済みにするハッシュ。Codex は正規化した hook 定義（キーを整列した JSON）の
+ * sha256 を trust の照合に使う（codex-rs/hooks/src/engine/discovery.rs の hook_hash）
+ */
+function hookTrustHash(label, timeout) {
+    const identity = {
+        event_name: label,
+        hooks: [{ type: 'command', command: HOOK_COMMAND, timeout, async: false }],
+    };
+    return `sha256:${createHash('sha256')
+        .update(JSON.stringify(sortKeys(identity)))
+        .digest('hex')}`;
+}
+/**
+ * tsunagi 連携用の `-c` 引数。ユーザーの config.toml には書き込まない（このプロセスだけに効く）
+ * - hooks: 状態遷移・todos の通知。`-c` で渡した hook の trust は `<session-flags>` のキーで照合される。
+ *   キーにドットを含むため、`hooks.state` はインラインテーブルで丸ごと渡す
+ * - tools.update_plan: 計画ツール（todos の元）を有効にする
+ * - mcp_servers.tsunagi: タスク管理の MCP
+ */
+function tsunagiConfigArgs(extra) {
+    const args = ['--dangerously-bypass-approvals-and-sandbox'];
+    const state = [];
+    for (const { event, label, timeout } of HOOK_EVENTS) {
+        args.push('-c', `hooks.${event}=[{hooks=[{type="command",command=${tomlString(HOOK_COMMAND)},timeout=${timeout}}]}]`);
+        state.push(`${tomlString(`/<session-flags>/config.toml:${label}:0:0`)}={trusted_hash=${tomlString(hookTrustHash(label, timeout))}}`);
+    }
+    args.push('-c', `hooks.state={${state.join(',')}}`);
+    args.push('-c', 'tools.update_plan.enabled=true');
+    args.push('-c', `mcp_servers.tsunagi.url=${tomlString(`${SERVER_URL}/api/mcp`)}`);
+    if (extra.developerInstructions) {
+        args.push('-c', `developer_instructions=${tomlString(extra.developerInstructions)}`);
+    }
+    if (extra.agentRoleFile) {
+        args.push('-c', `agents.tsunagi-task-curator={description=${tomlString(CURATOR_DESCRIPTION)},config_file=${tomlString(extra.agentRoleFile)}}`);
+    }
+    return args;
+}
+const CURATOR_DESCRIPTION = 'tsunagiタスクの並び替え（優先度変更）・棚卸し（backlog整理）を専門に行うエージェント。' +
+    '「優先度を並び替えて」「棚卸しして」「backlogを整理して」等の要望があった時に使用する。';
+/**
+ * Claude Code 用のプラグイン（TSUNAGI_PLUGIN_DIR = <marketplace>/plugins/tsunagi-plugin）からの相対パスで
+ * Codex 向けの本文を読む。skill は Codex 向けに書き直したもの（<marketplace>/codex）、
+ * subagent は vendor 中立のためプラグインのものを共用する
+ */
+async function readPluginFile(...segments) {
+    const pluginDir = process.env.TSUNAGI_PLUGIN_DIR;
+    if (!pluginDir)
+        return undefined;
+    try {
+        return await readFile(path.resolve(pluginDir, ...segments), 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Markdown 先頭の YAML frontmatter を外す */
+function stripFrontmatter(markdown) {
+    return markdown.replace(/^---\n[\s\S]*?\n---\n/, '').trimStart();
+}
+/** 複数タブの同時起動で書きかけのファイルを読まないよう、書き終えてから置き換える */
+async function writeAtomic(file, content) {
+    await mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${randomUUID()}.tmp`;
+    await writeFile(tmp, content);
+    await rename(tmp, file);
+}
+/** subagent の role ファイル（Codex の設定レイヤー）を state ディレクトリに書き出す */
+async function writeCuratorRole() {
+    const markdown = await readPluginFile('agents', 'tsunagi-task-curator.md');
+    if (!markdown)
+        return undefined;
+    const file = path.join(getStateDir(), 'codex', 'tsunagi-task-curator.toml');
+    await writeAtomic(file, `developer_instructions = ${tomlString(stripFrontmatter(markdown))}\n`);
+    return file;
+}
+/**
+ * codex の起動スクリプトを書き出し、そのパスを返す。`sh <script> [<codex-session-id>]` で起動する。
+ * Codex にはセッションIDを指定して新規作成する手段がないため、タブには前回の Codex のセッションIDを
+ * 保存しておき（SessionStart hook）、その会話記録が CODEX_HOME にあれば resume、なければ新規作成する。
+ * 引数は長く、PTY の1行上限（MAX_CANON）で切り捨てられるためスクリプトに閉じ込める
+ */
+async function writeLauncher() {
+    const [developerInstructions, agentRoleFile] = await Promise.all([
+        readPluginFile('..', '..', 'codex', 'tsunagi-task.md'),
+        writeCuratorRole(),
+    ]);
+    const args = tsunagiConfigArgs({ developerInstructions, agentRoleFile }).map(shellQuote);
+    const script = `#!/bin/sh
+# usage: launch-codex.sh [<codex-session-id>]
+session_id=$1
+# 作業フォルダの信頼確認を出さない（Claude の --dangerously-skip-permissions と揃える）。
+# -c のキーはドットで区切られパスを書けないため、projects をインラインテーブルで渡す
+cwd_key=$(pwd -P | sed 's/[\\\\"]/\\\\&/g')
+set -- ${args.join(' \\\n  ')} \\
+  -c "projects={\\"$cwd_key\\"={trust_level=\\"trusted\\"}}"
+codex_home=\${CODEX_HOME:-$HOME/.codex}
+if [ -n "$session_id" ] &&
+  [ -n "$(find "$codex_home/sessions" -name "rollout-*-$session_id.jsonl" 2>/dev/null | head -n 1)" ]; then
+  exec codex resume "$@" "$session_id"
+fi
+exec codex "$@"
+`;
+    const file = path.join(getStateDir(), 'launch-codex.sh');
+    await writeAtomic(file, script);
+    return file;
+}
+/** JWT の payload を読む（署名は検証しない。表示用） */
+function decodeJwtPayload(token) {
+    if (typeof token !== 'string')
+        return undefined;
+    const payload = token.split('.')[1];
+    if (!payload)
+        return undefined;
+    try {
+        return JSON.parse(Buffer.from(payload, 'base64url').toString('utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** ChatGPT ログインのアカウント情報（auth.json の id_token）。keyring 保存などで読めなければ空 */
+async function readChatgptAccount(codexHome) {
+    try {
+        const auth = JSON.parse(await readFile(path.join(codexHome, 'auth.json'), 'utf-8'));
+        const claims = decodeJwtPayload(auth.tokens?.id_token);
+        if (!claims)
+            return {};
+        const openai = claims['https://api.openai.com/auth'];
+        return {
+            ...(typeof claims.email === 'string' && { email: claims.email }),
+            ...(typeof openai?.chatgpt_plan_type === 'string' && {
+                subscriptionType: openai.chatgpt_plan_type,
+            }),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+const codexProfile = {
+    envKey: 'TSUNAGI_CODEX_PROFILE',
+    configDirEnvKey: 'CODEX_HOME',
+    // auth.json のログインより優先される認証情報
+    authEnvKeys: ['CODEX_API_KEY', 'CODEX_ACCESS_TOKEN'],
+    defaultConfigDir: '~/.codex',
+    // ブラウザでの OAuth（127.0.0.1:1455 で待ち受け）。戻れない環境ではユーザーが --device-auth に切り替える
+    loginCommand: 'codex login',
+    // codex login はブラウザでの認証の戻りを 127.0.0.1:1455（使用中なら 1457）で待つ
+    loginCallbackPorts: [1455, 1457],
+    // `codex login status` は終了コードでログイン状態を返し、stderr に1行だけ方式を出す
+    async getAuthStatus(configDir) {
+        const env = agentCliEnv(codexProfile, configDir);
+        const codexHome = configDir ?? process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex');
+        try {
+            const { stdout, stderr } = await runAgentCli('codex', ['login', 'status'], env);
+            const line = `${stderr}\n${stdout}`.trim().split('\n').pop() ?? '';
+            const method = /^Logged in using (.+?)(?: - .*)?$/.exec(line)?.[1];
+            return {
+                loggedIn: true,
+                authMethod: method,
+                ...(method === 'ChatGPT' && (await readChatgptAccount(codexHome))),
+            };
+        }
+        catch (err) {
+            // 未ログインは終了コード 1（"Not logged in"）
+            const code = err.code;
+            if (typeof code === 'number')
+                return { loggedIn: false };
+            return { loggedIn: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    },
+    async logout(configDir) {
+        await runAgentCli('codex', ['logout'], agentCliEnv(codexProfile, configDir));
+    },
+};
+export const codexAdapter = {
+    id: 'codex',
+    label: 'Codex',
+    cli: 'codex',
+    // tsunagi が使う `-c` キー（hooks.state / tools.update_plan 等）を確認したバージョン
+    minVersion: [0, 162, 0],
+    profile: codexProfile,
+    async resolveLaunchEnv() {
+        return { env: {}, unsetKeys: [] };
+    },
+    // CODEX_HOME は存在しないと codex が起動しない（プロファイル作成時に作るが、消されていた場合に備える）
+    async prepareLaunch(env) {
+        if (env.CODEX_HOME)
+            await mkdir(env.CODEX_HOME, { recursive: true });
+    },
+    async buildCommand(tabId) {
+        const [launcher, tab] = await Promise.all([
+            writeLauncher(),
+            prisma.tab.findUnique({ where: { tabId }, select: { agentSessionId: true } }),
+        ]);
+        const sessionId = tab?.agentSessionId;
+        return sessionId
+            ? `sh ${shellQuote(launcher)} ${shellQuote(sessionId)}`
+            : `sh ${shellQuote(launcher)}`;
+    },
+    normalizeHook({ body, headers }) {
+        const header = headers[TAB_ID_HEADER];
+        const tabId = Array.isArray(header) ? header[0] : header;
+        const { hook_event_name: eventName, session_id: sessionId } = body;
+        if (!tabId || !eventName)
+            return null;
+        if (eventName === 'SessionStart') {
+            return { tabId, kind: 'session-start', ...(sessionId && { agentSessionId: sessionId }) };
+        }
+        const kind = SIMPLE_EVENTS[eventName];
+        if (kind)
+            return { tabId, kind };
+        if (eventName === 'PostToolUse') {
+            const { tool_name: toolName, tool_input: input } = body;
+            return {
+                tabId,
+                kind: 'tool-post',
+                toolName,
+                // update_plan は毎回計画全体が渡されるため全置換する
+                ...(toolName === 'update_plan' && { applyTodos: () => planToTodos(input) }),
+            };
+        }
+        return null;
+    },
+};

package/dist/server/lib/agents/index.d.ts

@@ -0,0 +1,11 @@
+import type { TabMode } from '@minimalcorp/tsunagi-shared';
+import type { AgentAdapter } from './types.js';
+export * from './types.js';
+export { getAgentAvailability } from './cli.js';
+export declare const AGENTS: readonly AgentAdapter[];
+export declare function getAgent(id: string): AgentAdapter | undefined;
+/**
+ * タブの mode で起動するエージェント。local（旧 ollama / lmstudio 含む）はローカルLLMに繋いだ claude。
+ * terminal は自動では起動しないが、Run ボタンで起動するのは claude
+ */
+export declare function getAgentForMode(mode: TabMode | undefined): AgentAdapter;

package/dist/server/lib/agents/index.js

@@ -0,0 +1,19 @@
+import { claudeAdapter } from './claude.js';
+import { codexAdapter } from './codex.js';
+export * from './types.js';
+export { getAgentAvailability } from './cli.js';
+const ADAPTERS = {
+    claude: claudeAdapter,
+    codex: codexAdapter,
+};
+export const AGENTS = Object.values(ADAPTERS);
+export function getAgent(id) {
+    return Object.hasOwn(ADAPTERS, id) ? ADAPTERS[id] : undefined;
+}
+/**
+ * タブの mode で起動するエージェント。local（旧 ollama / lmstudio 含む）はローカルLLMに繋いだ claude。
+ * terminal は自動では起動しないが、Run ボタンで起動するのは claude
+ */
+export function getAgentForMode(mode) {
+    return mode === 'codex' ? codexAdapter : claudeAdapter;
+}

package/dist/server/lib/agents/login-callback.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ブラウザでの OAuth の戻り先（CLI が 127.0.0.1 で待ち受ける）にブラウザから届かない環境か。
+ * コンテナ内の CLI にはホストのブラウザから届かない（ホストのポートを公開すると、ホストで動く CLI の
+ * ログインとポートを取り合うため公開しない）
+ */
+export declare function needsLoginCallbackPaste(): boolean;
+/**
+ * ブラウザが開けなかった戻り先の URL（http://127.0.0.1:<port>/auth/callback?code=…）を、
+ * 同じマシンで待ち受けている CLI に渡す。失敗したらエラーメッセージを返す
+ */
+export declare function forwardLoginCallback(rawUrl: string, ports: number[]): Promise<string | null>;

package/dist/server/lib/agents/login-callback.js

@@ -0,0 +1,47 @@
+import { existsSync } from 'fs';
+/**
+ * ブラウザでの OAuth の戻り先（CLI が 127.0.0.1 で待ち受ける）にブラウザから届かない環境か。
+ * コンテナ内の CLI にはホストのブラウザから届かない（ホストのポートを公開すると、ホストで動く CLI の
+ * ログインとポートを取り合うため公開しない）
+ */
+export function needsLoginCallbackPaste() {
+    return existsSync('/.dockerenv');
+}
+/**
+ * ブラウザが開けなかった戻り先の URL（http://127.0.0.1:<port>/auth/callback?code=…）を、
+ * 同じマシンで待ち受けている CLI に渡す。失敗したらエラーメッセージを返す
+ */
+export async function forwardLoginCallback(rawUrl, ports) {
+    let url;
+    try {
+        url = new URL(rawUrl.trim());
+    }
+    catch {
+        return 'URL の形式が正しくありません';
+    }
+    const port = Number(url.port);
+    if (url.protocol !== 'http:' ||
+        !['127.0.0.1', 'localhost'].includes(url.hostname) ||
+        !ports.includes(port)) {
+        return `http://127.0.0.1:${ports[0]}/… の URL を貼り付けてください`;
+    }
+    const get = (target) => fetch(target, { redirect: 'manual', signal: AbortSignal.timeout(30_000) });
+    try {
+        const res = await get(`http://127.0.0.1:${port}${url.pathname}${url.search}`);
+        if (res.status < 400) {
+            // 成功すると完了ページへリダイレクトされる。CLI はローカルの完了ページが開かれてから終了するため、
+            // 同じ待ち受け先へのリダイレクトだけ辿る（外部のページは開かない）
+            const location = res.headers.get('location');
+            const next = location ? new URL(location, `http://127.0.0.1:${port}`) : null;
+            if (next && ['127.0.0.1', 'localhost'].includes(next.hostname) && next.port === url.port) {
+                await get(`http://127.0.0.1:${port}${next.pathname}${next.search}`).catch(() => undefined);
+            }
+            return null;
+        }
+        const body = (await res.text().catch(() => '')).replace(/<[^>]+>/g, ' ').trim();
+        return `ログインに失敗しました (${res.status})${body ? `: ${body.slice(0, 200)}` : ''}`;
+    }
+    catch (err) {
+        return `ログインの待ち受けに接続できません: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}

package/dist/server/lib/agents/types.d.ts

@@ -0,0 +1,77 @@
+import type { AgentAuthStatus, AgentId, TabMode, Todo } from '@minimalcorp/tsunagi-shared';
+export type { AgentId };
+/** エージェントの起動に必要な設定が足りないなど、起動前に分かる失敗 */
+export declare class AgentLaunchError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+/**
+ * vendor ごとの hook を tsunagi の状態遷移に正規化したもの。
+ * tabId は tsunagi のタブID（Claude はセッションID = タブID、それ以外は PTY の TSUNAGI_SESSION_ID）
+ */
+export type NormalizedHookEvent = {
+    tabId: string;
+    kind: 'session-start';
+    /** エージェント側のセッションID（タブIDと別の ID を振るエージェントのみ）。resume 用に保存する */
+    agentSessionId?: string;
+} | {
+    tabId: string;
+    kind: 'prompt' | 'permission' | 'stop' | 'stop-failure' | 'interrupt' | 'session-end';
+} | {
+    tabId: string;
+    kind: 'tool-post';
+    toolName?: string;
+    /** todos を更新するツールなら、現在の todos に適用する関数（解釈できなければ null を返す） */
+    applyTodos?: (current: Todo[]) => Todo[] | null;
+};
+export interface HookRequest {
+    body: Record<string, unknown>;
+    headers: Record<string, string | string[] | undefined>;
+}
+/** PTY に渡すエージェント固有の環境変数 */
+export interface AgentLaunchEnv {
+    env: Record<string, string>;
+    unsetKeys: string[];
+}
+/** プロファイル（エージェントの設定ディレクトリ）の扱い */
+export interface AgentProfileSpec {
+    /** タブで使うプロファイルの割り当てを保存する予約キー（global → owner → repo で継承） */
+    envKey: string;
+    /** 設定ディレクトリを指す環境変数（CLAUDE_CONFIG_DIR / CODEX_HOME） */
+    configDirEnvKey: string;
+    /**
+     * プロファイルのログインより優先される認証情報の環境変数。
+     * プロファイルを選んだタブでは外側 Terminal から継承した値も取り除く
+     */
+    authEnvKeys: string[];
+    /** システム既定の設定ディレクトリ（表示用） */
+    defaultConfigDir: string;
+    /** ログイン用 PTY に書き込むコマンド */
+    loginCommand: string;
+    /**
+     * ブラウザでの OAuth の戻り先として CLI が 127.0.0.1 で待ち受けるポート（使用中のときの予備を含む）。
+     * ブラウザから届かない環境（コンテナ内）では、ブラウザで開けなかった URL を貼り付けて CLI に渡す（login-callback.ts）
+     */
+    loginCallbackPorts?: number[];
+    /** configDir が undefined ならシステム既定 */
+    getAuthStatus(configDir: string | undefined): Promise<AgentAuthStatus>;
+    logout(configDir: string): Promise<void>;
+}
+export interface AgentAdapter {
+    id: AgentId;
+    /** 表示名 */
+    label: string;
+    /** CLI のコマンド名 */
+    cli: string;
+    /** tsunagi が必要とする最低バージョン */
+    minVersion: readonly [number, number, number];
+    profile: AgentProfileSpec;
+    /** タブの mode に応じた追加の環境変数（DB の環境変数より後に適用する） */
+    resolveLaunchEnv(mode: TabMode): Promise<AgentLaunchEnv>;
+    /** 起動前の補正（設定ファイルの修正など）。env は PTY に渡す環境変数 */
+    prepareLaunch(env: Record<string, string>): Promise<void>;
+    /** PTY に書き込む起動コマンド（既存セッションがあれば resume） */
+    buildCommand(tabId: string, mode: TabMode): Promise<string>;
+    /** hook の受信内容を正規化する。状態遷移に関係しないイベントは null */
+    normalizeHook(request: HookRequest): NormalizedHookEvent | null;
+}

package/dist/server/lib/agents/types.js

@@ -0,0 +1,8 @@
+/** エージェントの起動に必要な設定が足りないなど、起動前に分かる失敗 */
+export class AgentLaunchError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+    }
+}

package/dist/server/lib/pty-env-sync.js

@@ -70,7 +70,7 @@ async function respawn(session) {
     try {
         await startPtySession(sessionId, launch, {
             request: session.options.request ?? {},
-            launchClaude: session.options.launchClaude ?? false,
+            launchAgent: session.options.launchAgent ?? false,
         });
     }
     catch (err) {

package/dist/server/lib/pty-launch.d.ts

@@ -1,5 +1,6 @@
 import type { TabMode } from '@minimalcorp/tsunagi-shared';
 import { type PtySession } from '../pty-manager.js';
+import { AgentLaunchError as PtyLaunchError } from './agents/index.js';
 /** PTY 起動時にクライアントが指定する値（環境変数の自動反映で作り直すときも同じ値を使う） */
 export interface PtyLaunchRequest {
     cwd?: string;
@@ -13,24 +14,21 @@ export interface PtyLaunch {
     env: Record<string, string>;
     unsetKeys: string[];
 }
-export declare class PtyLaunchError extends Error {
-    readonly statusCode: number;
-    constructor(message: string, statusCode: number);
-}
+export { PtyLaunchError };
 /**
  * sessionId(=tab_id) から PTY の作業ディレクトリと環境変数を解決する。
- * 環境変数の優先順位: リクエストで渡されたenv > ローカルLLMのprovider env >
- * DB env(global/owner/repo、Claude プロファイルを CLAUDE_CONFIG_DIR に変換) > tsunagi独自のEDITOR設定
+ * 環境変数の優先順位: リクエストで渡されたenv > エージェント固有のenv（ローカルLLMの provider 等） >
+ * DB env(global/owner/repo、エージェントのプロファイルを設定ディレクトリに変換) > tsunagi独自のEDITOR設定
  */
 export declare function resolvePtyLaunch(sessionId: string, request: PtyLaunchRequest): Promise<PtyLaunch>;
 /**
- * 解決済みの launch で PTY を作り、claude を起動する。
+ * 解決済みの launch で PTY を作り、エージェントを起動する。
  * 新規作成（POST /terminal/sessions）と環境変数変更時の作り直し（pty-env-sync）で共用する。
  */
 export declare function startPtySession(sessionId: string, launch: PtyLaunch, options: {
     request: PtyLaunchRequest;
-    launchClaude: boolean;
+    launchAgent: boolean;
     command?: string;
 }): Promise<PtySession>;
-/** 既存 PTY で claude を（再）起動する前の補正。PTY 作成時の環境変数のプロファイルを対象にする */
-export declare function prepareClaudeConfigForSession(session: PtySession): Promise<void>;
+/** 既存 PTY でエージェントを（再）起動する前の補正。PTY 作成時の環境変数のプロファイルを対象にする */
+export declare function prepareAgentLaunchForSession(session: PtySession, mode: TabMode | undefined): Promise<void>;