ai_co_discuss 0.3.11 → 0.3.13

package/runner/adapters/codex_cli.mjs

@@ -0,0 +1,286 @@
+/**
+ * Codex CLI adapter: one headless `codex exec` turn per execution resuming the bound thread, under a per-run permission
+ * profile. Its rollout files and app server also serve the Codex App adapter for sessions and models.
+ */
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { cli_delivery } from './cli.mjs';
+import { CALL_TIMEOUT_MS, launch_directory, log_entries, marked, model_entry, json_line, newest_record, not_sent,
+  project_directory, prompt_text, query_catalog } from './common.mjs';
+
+/** Codex exec may linger after its final event; the finished turn is already saved, so stop it to free the session. */
+const CLI_EXIT_GRACE_MS = 1500;
+const CODEX_PERMISSIONS_MIN_MINOR = 163;
+const FORK_TIMEOUT_MS = 60_000;
+
+/** Build a per-invocation profile without inheriting a user's custom profile of the same name. */
+export function codex_permissions(config, task, platform = process.platform) {
+  // 全放开 runs without approval or sandbox, so there is no profile to build or check.
+  if (config.project_access === 'full') return { name: '', args: ['--dangerously-bypass-approvals-and-sandbox'] };
+  const name = `codiscuss-${randomUUID()}`;
+  // A taken-over manual member writes like 可写: its own config may sandbox read-only and then could not save its answer draft.
+  const base = ['auto', 'own'].includes(config.project_access) || (project_directory(config) && config.project_access === 'write')
+    ? ':workspace' : ':read-only';
+  const drafts = resolve(task.draft_directory).replaceAll('\\', '/');
+  const filesystem = { ':root': 'read', [resolve(task.directory).replaceAll('\\', '/')]: 'read', [drafts]: 'write' };
+  const rules = Object.entries(filesystem).map(([path, access]) => `${JSON.stringify(path)}=${JSON.stringify(access)}`).join(',');
+  const profile = `{extends=${JSON.stringify(base)},filesystem={${rules}},network={enabled=true}}`;
+  // The Windows sandbox account cannot write the user's TEMP, so PowerShell starts in ConstrainedLanguage and Codex's
+  // UTF-8 output setup fails silently, garbling Chinese; a TEMP inside the writable drafts keeps FullLanguage.
+  const temp = platform === 'win32' ? ['-c', `shell_environment_policy.set.TEMP=${JSON.stringify(drafts)}`,
+    '-c', `shell_environment_policy.set.TMP=${JSON.stringify(drafts)}`] : [];
+  // 自动 is what `codex exec --approve-for-me` sets (that flag is missing on `exec resume`): the model asks to escalate
+  // and Codex's automatic review answers instead of a person (tested 0.163).
+  const approval = config.project_access === 'auto' ? ['-c', 'approval_policy="on-request"', '-c', 'approvals_reviewer="auto_review"']
+    : ['-c', 'approval_policy="never"'];
+  return { name, args: ['-c', `default_permissions=${JSON.stringify(name)}`, '-c', `permissions.${name}=${profile}`, ...approval, ...temp] };
+}
+
+/** Read effective Codex config through its local CLI; no thread or model is started. */
+function read_codex_config(config, task, permissions, spawn_process) {
+  return new Promise((resolve_config, reject) => {
+    const child = spawn_process(config.executable, ['app-server', ...permissions.args], {
+      cwd: launch_directory(config, task), windowsHide: true, shell: false, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    task.on_process(child);
+    const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+    let settled = false;
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer); lines.close();
+      const complete = () => error ? reject(not_sent(error)) : resolve_config(value);
+      if (child.exitCode !== null || child.signalCode !== null) complete();
+      else { child.once('close', complete); child.kill(); }
+    };
+    const timer = setTimeout(() => finish(new Error('Codex 权限配置检查超时，未交付讨论任务')), CALL_TIMEOUT_MS);
+    const send = (id, method, params) => child.stdin.write(`${JSON.stringify({ id, method, params })}\n`);
+    child.once('error', error => finish(error));
+    child.once('close', () => finish(new Error('Codex 无法读取权限配置，请使用支持 permission profiles 的 CLI')));
+    child.stdin.on('error', error => finish(error));
+    child.stderr.resume();
+    lines.on('line', line => {
+      let response;
+      try { response = JSON.parse(line); } catch { return; }
+      if (![1, 2].includes(response.id)) return;
+      if (response.error) return finish(new Error(`Codex 权限配置检查失败：${response.error.message}`));
+      if (response.id === 1) {
+        const version = response.result?.userAgent?.match(/\/(\d+)\.(\d+)\.\d+\b/);
+        if (!version || (Number(version[1]) === 0 && Number(version[2]) < CODEX_PERMISSIONS_MIN_MINOR)) {
+          return finish(new Error('本次权限配置需要 Codex CLI 0.163.0 或更新版本，未交付讨论任务'));
+        }
+        send(2, 'config/read', { cwd: launch_directory(config, task), includeLayers: false });
+      }
+      else finish(null, response.result?.config);
+    });
+    send(1, 'initialize', { clientInfo: { name: 'codiscuss', version: '0.1.0' } });
+  });
+}
+
+/** Reject legacy overrides that would silently replace the requested filesystem policy. */
+async function check_codex_permissions(config, task, permissions, spawn_process) {
+  const effective = await read_codex_config(config, task, permissions, spawn_process).catch(error => { throw not_sent(error); });
+  if (effective?.sandbox_mode != null || effective?.sandbox_workspace_write != null) {
+    throw not_sent(new Error('Codex 配置含旧 sandbox_mode / sandbox_workspace_write，会覆盖本次权限；请移除旧配置后重试，未交付讨论任务'));
+  }
+  if (effective?.default_permissions !== permissions.name || !effective?.permissions?.[permissions.name]) {
+    throw not_sent(new Error('Codex 未采用本次 permission profile，未交付讨论任务；请更新 CLI'));
+  }
+}
+
+/** Native `codex exec` arguments; every continuation names the exact bound thread. */
+function invocation(config, binding, task) {
+  const permissions = codex_permissions(config, task);
+  const args = ['exec', '--cd', launch_directory(config, task)];
+  if (binding.session_id) args.push('resume', binding.session_id);
+  args.push(...permissions.args, '--json', '--skip-git-repo-check', ...(config.model ? ['-m', config.model] : []),
+    ...(config.effort ? ['-c', `model_reasoning_effort="${config.effort}"`] : []), '-');
+  return { args, input: task.prompt,
+    ...(permissions.name ? { check: spawn_process => check_codex_permissions(config, task, permissions, spawn_process) } : {}) };
+}
+
+/** Keep the actual resume failure even when later model-refresh logs replace the diagnostic tail. */
+function remember_writer_conflict(state, diagnostic) {
+  if (/thread-store conflict:[\s\S]*already has an active writer/.test(diagnostic)) state.writer_conflict = true;
+}
+
+/** Consume only documented lifecycle events, not text produced by agent tools. */
+function lifecycle(state, event, task, bind) {
+  if (event.type === 'thread.started') bind(event.thread_id);
+  if (event.type === 'turn.completed') { state.completed = true; state.finish_timer = setTimeout(() => { state.finished = true; task.on_trace?.('kill_after_completed'); state.child.kill(); }, CLI_EXIT_GRACE_MS); }
+  if (event.type === 'turn.failed') state.error = event.error?.message || 'Codex CLI 执行失败';
+  if (event.type === 'error') state.diagnostic = event.message || 'Codex CLI 返回错误';
+  remember_writer_conflict(state, state.error || state.diagnostic);
+}
+
+/** A thread another process writes to cannot be resumed here; retrying does not release it. */
+function exit_error(state) {
+  return state.writer_conflict ? `Codex 会话 ${state.session_id} 已被另一进程持有（active writer），CLI 无法接管。若为 App 中的聊天，请使用 Codex App 接入；独立 CLI 须使用未被占用的会话。重复点击重试不会解除占用` : '';
+}
+
+/** What `codex exec --json` events say the agent is doing, which tool it starts, and text it wrote to the user. */
+const events = {
+  phase(event) {
+    if (event.type === 'turn.started') return 'thinking';
+    const kind = event.item?.type;
+    if (event.type === 'item.started') {
+      return { command_execution: 'command', file_change: 'editing', mcp_tool_call: 'tool', web_search: 'tool', reasoning: 'thinking' }[kind] || '';
+    }
+    if (event.type === 'item.completed') return kind === 'agent_message' ? 'writing' : 'thinking';
+    return '';
+  },
+  tool(event) {
+    if (event.type !== 'item.started') return '';
+    return event.item?.type === 'mcp_tool_call' ? String(event.item.tool || '') : event.item?.type === 'web_search' ? 'web_search' : '';
+  },
+  note(event) { return event.type === 'item.completed' && event.item?.type === 'agent_message' ? String(event.item.text || '').trim() : ''; },
+};
+
+/** Where Codex keeps one thread's rollout, or '' when this machine has none by that ID; shared by the App adapter. */
+export function session_path(session_id, env = process.env, home = homedir()) {
+  const sessions = join(env.CODEX_HOME || join(home, '.codex'), 'sessions');
+  if (!existsSync(sessions)) return '';
+  const found = readdirSync(sessions, { recursive: true }).map(String).find(path => path.endsWith(`-${session_id}.jsonl`));
+  return found ? join(sessions, found) : '';
+}
+
+/** Codex turns in order, and the index of the first turn whose user prompt carries a marker (-1 when none does). */
+function codex_turns(file, markers) {
+  const turns = [];
+  let cut = -1;
+  for (const entry of log_entries(file)) {
+    const payload = entry.payload || {};
+    if (entry.type === 'event_msg' && payload.type === 'task_started' && payload.turn_id) turns.push(payload.turn_id);
+    else if (cut < 0 && turns.length && entry.type === 'response_item' && payload.type === 'message' && payload.role === 'user'
+      && marked(prompt_text(payload.content), markers)) cut = turns.length - 1;
+  }
+  return { turns, cut };
+}
+
+/** Ask Codex's app server to fork a thread, through `last_turn` when given; returns the new thread's ID. */
+function codex_fork(profile, thread_id, last_turn, spawn_process) {
+  return new Promise((resolve_fork, reject) => {
+    const child = spawn_process(profile.executable, ['app-server'], { windowsHide: true, shell: false, stdio: ['pipe', 'pipe', 'pipe'] });
+    const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+    let settled = false;
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer); lines.close(); child.stdin.destroy(); child.kill();
+      if (error) reject(error); else resolve_fork(value);
+    };
+    const timer = setTimeout(() => finish(new Error('Codex 分叉会话超时')), FORK_TIMEOUT_MS);
+    const send = value => child.stdin.write(`${JSON.stringify(value)}\n`);
+    child.once('error', error => finish(error));
+    child.once('close', () => finish(new Error('Codex app-server 未完成分叉就退出了')));
+    child.stdin.on('error', error => finish(error));
+    child.stderr.resume();
+    lines.on('line', line => {
+      let reply;
+      try { reply = JSON.parse(line); } catch { return; }
+      if (reply.error && [1, 2].includes(reply.id)) return finish(new Error(`Codex 分叉会话失败：${reply.error.message}`));
+      if (reply.id === 1) {
+        send({ method: 'initialized', params: {} });
+        send({ id: 2, method: 'thread/fork', params: { threadId: thread_id, excludeTurns: true, ...(last_turn ? { lastTurnId: last_turn } : {}) } });
+      } else if (reply.id === 2) {
+        const id = reply.result?.thread?.id;
+        finish(id ? null : new Error('Codex 分叉会话没有返回新会话 ID'), id);
+      }
+    });
+    send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'codiscuss', version: '0.1.0' } } });
+  });
+}
+
+/** Fork through the turn before the first marked one; a cut at the first turn starts anew. Shared by the App adapter. */
+export async function branch(profile, session_id, markers, { always, env, home, spawn_process = spawn }) {
+  const file = session_path(session_id, env, home);
+  if (!file) throw new Error(`本机找不到 Codex 会话 ${session_id}`);
+  const { turns, cut } = codex_turns(file, markers);
+  if (cut < 0 && !always) return null;
+  if (cut === 0) return { session_id: '' };
+  return { session_id: await codex_fork(profile, session_id, cut > 0 ? turns[cut - 1] : '', spawn_process) };
+}
+
+/** Whether a stored thread was started in the Codex desktop, which resumes it through the App rather than the CLI. */
+export function desktop_thread(session_id, options = {}) {
+  const file = session_path(session_id, options.env, options.home);
+  return Boolean(file) && /"originator":"Codex Desktop"/.test(readFileSync(file, 'utf8').split('\n', 1)[0]);
+}
+
+/** Whether Codex stored a thread by that ID on this machine. */
+export function session_exists(session_id, { env = process.env, home = homedir() } = {}) {
+  return Boolean(session_id && session_path(session_id, env, home));
+}
+
+/** The model and effort a thread last ran with, from its rollout; no turn is started. Shared by the App adapter. */
+export function session_settings(session_id, { env = process.env, home = homedir() } = {}) {
+  const file = session_path(session_id, env, home);
+  if (!file) return null;
+  return newest_record(file, '"turn_context"', record => record.type === 'turn_context' && typeof record.payload?.model === 'string'
+    ? { model: record.payload.model, effort: String(record.payload.effort || record.payload.collaboration_mode?.settings?.reasoning_effort || '') } : null);
+}
+
+/** Read the string keys of a TOML file by table; Codex settings need nothing richer. */
+function toml_strings(text) {
+  const tables = { '': {} };
+  let table = '';
+  for (const line of text.split(/\r?\n/)) {
+    const header = line.match(/^\s*\[\s*([^\]]+?)\s*\]\s*(?:#.*)?$/);
+    if (header) { table = header[1].replaceAll('"', ''); tables[table] ||= {}; continue; }
+    const pair = line.match(/^\s*([A-Za-z0-9_-]+)\s*=\s*"([^"]*)"/);
+    if (pair) tables[table][pair[1]] = pair[2];
+  }
+  return tables;
+}
+
+/** Codex's user config: what it runs with when the card leaves model or effort empty. */
+function defaults(profile, { env = process.env, home = homedir() } = {}) {
+  try {
+    const tables = toml_strings(readFileSync(join(env.CODEX_HOME || join(home, '.codex'), 'config.toml'), 'utf8'));
+    const top = tables[''], chosen = top.profile ? tables[`profiles.${top.profile}`] || {} : {};
+    return { model: chosen.model || top.model || '', effort: chosen.model_reasoning_effort || top.model_reasoning_effort || '' };
+  } catch { return { model: '', effort: '' }; }
+}
+
+/** Codex's catalog is paginated; initialize before querying and never create a thread or turn. */
+function models(profile, options) {
+  return query_catalog(profile, ['app-server', '--listen', 'stdio://'], (send, finish) => {
+    const list = [];
+    let request_id = 1;
+    return {
+      start: () => send({ id: 0, method: 'initialize', params: { clientInfo: { name: 'codiscuss', title: 'AI CoDiscuss', version: '0.2.1' } } }),
+      line: line => {
+        const reply = json_line(line);
+        if (!reply || (reply.id !== 0 && reply.id !== request_id)) return;
+        if (reply.error) return finish(new Error('Codex 模型目录查询失败，请检查 CLI 版本与登录'));
+        if (reply.id === 0) {
+          send({ method: 'initialized', params: {} });
+          send({ id: request_id, method: 'model/list', params: { limit: 100, includeHidden: false } });
+          return;
+        }
+        for (const model of reply.result?.data || []) {
+          if (!model.hidden) list.push(model_entry(model.model || model.id, model.displayName,
+            model.supportedReasoningEfforts?.map(item => item.reasoningEffort)));
+        }
+        const cursor = reply.result?.nextCursor;
+        if (cursor) send({ id: ++request_id, method: 'model/list', params: { limit: 100, includeHidden: false, cursor } });
+        else finish(null, list);
+      },
+    };
+  }, options);
+}
+
+/** Codex CLI's behaviour; its static facts are in profiles.mjs. */
+export const codex_cli = {
+  id: 'codex_cli', catalog_source: 'codex-app-server',
+  deliver: (config, binding, task, spawn_process, user_home) => cli_delivery(codex_cli, config, binding, task, spawn_process, user_home),
+  invocation, lifecycle, exit_error, events,
+  on_stderr: remember_writer_conflict,
+  session: { path: session_path, exists: session_exists, owns: (id, options) => session_exists(id, options) && !desktop_thread(id, options),
+    branch, settings: session_settings },
+  models: { list: models, defaults },
+};

package/runner/adapters/common.mjs

@@ -0,0 +1,196 @@
+/** Parts every software adapter shares: running programs, ending process trees, reading session logs and model catalogs. */
+import { spawn, spawnSync } from 'node:child_process';
+import { closeSync, existsSync, fstatSync, openSync, readFileSync, readSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createInterface } from 'node:readline';
+import { TASK_SUBCOMMANDS } from '../expert_prompts.mjs';
+import { atomic_json } from '../files.mjs';
+
+// The room defines which website subcommands a task may run; adapters turn them into each software's permission rules.
+export { TASK_SUBCOMMANDS };
+export const CALL_TIMEOUT_MS = 30_000;
+/** Tool names that edit files, across the softwares' event streams. */
+export const EDIT_TOOLS = /^(Edit|MultiEdit|Write|NotebookEdit|write_file|write_to_file|replace_file_content|multi_replace_file_content)$/;
+/** A refused operation's detail and rule are cut to this length; a run reports at most this many. */
+export const DENIAL_FIELD = 300;
+export const MAX_DENIALS = 20;
+
+/** Only failures before a software invocation are safe for automatic redelivery. */
+export function not_sent(error) { return Object.assign(error, { delivery_status: 'not_sent' }); }
+
+/** Run an executable directly; user text is always an argv value, never shell code. */
+export function run_program(executable, args, options = {}) {
+  return new Promise((resolve_result, reject) => {
+    let child;
+    try { child = spawn(executable, args, { windowsHide: true, shell: false, ...options }); }
+    catch (error) { reject(not_sent(error)); return; }
+    let spawned = false;
+    child.once('spawn', () => { spawned = true; });
+    let output = '';
+    let error_text = '';
+    child.stdout?.on('data', chunk => { output += chunk; });
+    child.stderr?.on('data', chunk => { error_text += chunk; });
+    child.once('error', error => reject(spawned ? error : not_sent(error)));
+    child.once('close', code => code === 0 ? resolve_result(output) : reject(new Error(`软件退出码 ${code}: ${error_text.slice(-500)}`)));
+    if (options.input !== undefined) child.stdin.end(options.input);
+    else child.stdin?.end();
+  });
+}
+
+/** Bind returned software identities back to the private credential file. */
+export function bind_access(path, session_id) {
+  const access = JSON.parse(readFileSync(path, 'utf8'));
+  atomic_json(path, { ...access, session_id });
+}
+
+/** Compare local directory identities without assuming case sensitivity on Windows. */
+export function same_path(left, right) {
+  if (!left || !right) return false;
+  const normalize = value => process.platform === 'win32' ? resolve(value).toLowerCase() : resolve(value);
+  return normalize(left) === normalize(right);
+}
+
+/** The participant's discussion project directory; workdir is the legacy field name. */
+export function project_directory(config) { return config.cwd || config.workdir || ''; }
+
+/** Keep the requested project as cwd; without a project, use the separate answer directory. */
+export function launch_directory(config, task) {
+  return project_directory(config) || task.draft_directory;
+}
+
+/** Read optional native settings; malformed settings must not silently disable a permission check. */
+export function read_json(path) { return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : {}; }
+
+/**
+ * Windows leaves a killed process's descendants running, so a stopped Claude turn kept its tool commands working.
+ * End the whole tree there; elsewhere, or when taskkill cannot run, use the plain kill.
+ */
+export function kill_process_tree(child, plain_kill, platform = process.platform, run = spawnSync) {
+  if (platform === 'win32' && child.pid && child.exitCode === null && child.signalCode === null) {
+    try {
+      if (run('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, timeout: CALL_TIMEOUT_MS }).status === 0) return true;
+    } catch { /* Fall through to the plain kill. */ }
+  }
+  return plain_kill();
+}
+
+/** Make a delivered process's kill end its whole tree on Windows, so a stopped turn leaves no tool commands running. */
+export function tree_killable(child) {
+  if (typeof child.kill === 'function') {
+    const plain_kill = child.kill.bind(child);
+    child.kill = () => kill_process_tree(child, plain_kill);
+  }
+  return child;
+}
+
+/**
+ * Report the phase and any progress note of each complete JSON line, as the adapter's `events` read them; malformed
+ * lines are left to the caller's own parsing.
+ */
+export function watch_events(adapter, stream, task) {
+  if (!task.on_activity && !task.on_note) return;
+  createInterface({ input: stream, crlfDelay: Infinity }).on('line', line => {
+    let event;
+    try { event = JSON.parse(line); } catch { return; }
+    const phase = adapter.events.phase(event);
+    if (phase) task.on_activity?.(phase, adapter.events.tool(event));
+    const note = adapter.events.note(event);
+    if (note) task.on_note?.(note);
+  });
+}
+
+/** The task file name an execution's prompt carries; it marks where that execution entered a session. */
+export const execution_marker = id => `free-${id}.task.json`;
+
+/** JSON lines of a session log; lines the software wrote in another shape are skipped. */
+export function log_entries(file) {
+  return readFileSync(file, 'utf8').split('\n').flatMap(line => { try { return [JSON.parse(line)]; } catch { return []; } });
+}
+
+/** The text of a prompt as the software stored it: a string, or text parts (tool results carry no prompt). */
+export function prompt_text(content) {
+  if (typeof content === 'string') return content;
+  return Array.isArray(content) ? content.filter(part => ['text', 'input_text'].includes(part?.type)).map(part => part.text || '').join('\n') : '';
+}
+
+/** Whether a prompt names any of the execution markers. */
+export const marked = (text, markers) => markers.some(marker => text.includes(marker));
+
+// Only the end of a session log is read; the latest request is there and long sessions stay cheap.
+const SESSION_TAIL_BYTES = 4 * 1024 * 1024;
+
+/** The lines at the end of a file, newest first; a line cut at the start of the tail fails to parse and is skipped. */
+function tail_lines(file) {
+  const fd = openSync(file, 'r');
+  try {
+    const size = fstatSync(fd).size, length = Math.min(size, SESSION_TAIL_BYTES), buffer = Buffer.alloc(length);
+    readSync(fd, buffer, 0, length, size - length);
+    return buffer.toString('utf8').split('\n').reverse();
+  } finally { closeSync(fd); }
+}
+
+/** Parse the newest log record that `pick` turns into settings. */
+export function newest_record(file, marker, pick) {
+  for (const line of tail_lines(file)) {
+    if (!line.includes(marker)) continue;
+    try { const found = pick(JSON.parse(line)); if (found) return found; } catch { /* A cut or foreign line says nothing. */ }
+  }
+  return null;
+}
+
+const QUERY_TIMEOUT_MS = 30000;
+const MAX_OUTPUT_BYTES = 1024 * 1024;
+export const MODEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:/@[\]-]*$/;
+
+/** Return only model identifiers, display names and supported effort values. */
+export function model_entry(id, label, efforts) {
+  if (typeof id !== 'string' || !MODEL_PATTERN.test(id)) return null;
+  return { id, label: typeof label === 'string' && label.trim() ? label : id,
+    ...(Array.isArray(efforts) ? { efforts: [...new Set(efforts.filter(item => typeof item === 'string'))] } : {}) };
+}
+
+/** Ignore non-protocol diagnostics while leaving malformed or missing catalogs visibly unavailable. */
+export function json_line(line) {
+  try { return JSON.parse(line); } catch { return null; }
+}
+
+/**
+ * Read one catalog through the software's own CLI without an agent turn: `args` start it noninteractively and
+ * `reader(send, finish)` speaks its protocol. Its temporary process is killed on every outcome; size and time are bounded.
+ */
+export function query_catalog(profile, args, reader, options = {}) {
+  return new Promise((resolve_result, reject) => {
+    const env = { ...process.env };
+    delete env.CLAUDECODE;
+    const child = (options.spawn || spawn)(profile.executable, args, {
+      cwd: tmpdir(), env, shell: false, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let finished = false, bytes = 0;
+    const finish = (error, models) => {
+      if (finished) return;
+      finished = true; clearTimeout(timer); lines.close(); child.stdin.destroy(); child.kill();
+      if (error) reject(error); else resolve_result(models);
+    };
+    const timer = setTimeout(() => finish(new Error('读取模型列表超时，请检查软件登录和网络后重试')), options.timeout_ms ?? QUERY_TIMEOUT_MS);
+    const lines = createInterface({ input: child.stdout });
+    const send = value => child.stdin.write(`${JSON.stringify(value)}\n`);
+    const receive = reader(send, finish);
+    child.once('error', () => finish(new Error('无法启动模型查询，请检查 CLI 路径')));
+    child.stdin.on('error', () => finish(new Error('模型查询连接已关闭')));
+    child.stderr.on('data', () => {}); // CLI diagnostics can contain private account or configuration data.
+    child.stdout.on('data', chunk => {
+      bytes += chunk.length;
+      if (bytes > MAX_OUTPUT_BYTES) finish(new Error('模型目录响应超出大小限制'));
+    });
+    lines.on('line', line => {
+      if (finished) return;
+      try { receive.line(line); } catch { finish(new Error('软件模型目录格式无法识别，请检查 CLI 版本')); }
+    });
+    child.once('close', code => {
+      if (!finished && code === 0 && receive.complete) finish(null, receive.complete());
+      else if (!finished) finish(new Error(`软件未返回模型目录（退出码 ${code ?? '未知'}），请检查版本、登录与网络`));
+    });
+    receive.start();
+  });
+}

package/runner/adapters/index.mjs

@@ -0,0 +1,143 @@
+/**
+ * The adapter layer's only entry for the rest of the runner. Each supported software has two parts:
+ *
+ * - its static facts in `profiles.mjs` (label, platform, config fields, efforts, access levels, capabilities), plain data
+ *   the web page reads as well;
+ * - its behaviour in its own module, a descriptor with the same shape for every software:
+ *   - `deliver(config, binding, task, spawn_process, user_home)` → `{session_id, status, capabilities}`, where
+ *     `capabilities` `{stoppable, progress}` says what this one delivery can do;
+ *   - `session`: `{path, exists, branch, settings}` for the software's own session store, or null;
+ *   - `models`: `{list, effort?, defaults}` read from the installed software, or null when it is chosen inside the App;
+ *   - optional `receipt(config, id)` for deliveries confirmed later (`status: 'sidecar_pending'`),
+ *     `into_window(profile, binding)` (this delivery goes into the member's own open window) and `cleanup(directory)`
+ *     (remove what a deleted room left in the software).
+ *
+ * `adapter_of` merges the two. The room runner, launch settings and the website use these, never a software name
+ * (AGENTS.md red line 9).
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute } from 'node:path';
+import { antigravity } from './antigravity_app.mjs';
+import { antigravity_cli } from './antigravity_cli.mjs';
+import { api } from './api.mjs';
+import { claude } from './claude.mjs';
+import { codex } from './codex_app.mjs';
+import { codex_cli } from './codex_cli.mjs';
+import { execution_marker, MODEL_PATTERN } from './common.mjs';
+import { adapter_capabilities, adapter_profile, ADAPTER_IDS } from './profiles.mjs';
+
+export { execution_marker };
+export { adapter_capabilities as capabilities_of };
+
+export const ADAPTERS = Object.fromEntries([codex_cli, codex, claude, antigravity_cli, antigravity, api]
+  .map(behaviour => [behaviour.id, { ...adapter_profile(behaviour.id), ...behaviour }]));
+const SESSION_PATTERN = /^[0-9A-Za-z_-]{8,128}$/;
+
+/** The descriptor of a configured adapter, or null for a value this version does not support. */
+export function adapter_of(id) { return ADAPTERS[id] || null; }
+
+/**
+ * Which adapter holds an existing conversation of the software a manual member registered with (`client`): the one
+ * whose store owns it, else the CLI that would resume it. '' when no adapter takes over that software.
+ */
+export function adoption_adapter(client, session_id, options = {}) {
+  const candidates = Object.values(ADAPTERS).filter(adapter => adapter.client === client && adapter.adopt);
+  return (candidates.find(adapter => adapter.session?.owns?.(session_id, options))
+    || candidates.find(adapter => adapter.kind === 'cli') || candidates[0])?.id || '';
+}
+
+/** Check one configured software member: a supported adapter, its installed software located, and what it alone requires. */
+export function validate_participant(participant) {
+  const adapter = adapter_of(participant.adapter);
+  if (!adapter) throw new Error(`适配器只能为 ${ADAPTER_IDS.join('/')}`);
+  if (adapter.location === 'executable' && !existsSync(participant.executable ?? '')) throw new Error('请指定实际原生可执行文件');
+  adapter.validate?.(participant);
+}
+
+/** Remove what a deleted room's members left inside their software, e.g. agy's private projects. */
+export function cleanup_room(directory) {
+  for (const adapter of Object.values(ADAPTERS)) adapter.cleanup?.(directory);
+}
+
+/** Deliver one task through its member's adapter; only allowlisted adapters run. */
+export async function deliver_task(config, binding, task, spawn_process = spawn, user_home = homedir()) {
+  const adapter = adapter_of(config.adapter);
+  if (!adapter) throw new Error('不支持的软件适配器');
+  return adapter.deliver(config, binding, task, spawn_process, user_home);
+}
+
+/** A delivery's later receipt (`status: 'sidecar_pending'`), or null while none has arrived. */
+export function delivery_receipt(config, id) {
+  return adapter_of(config.adapter)?.receipt?.(config, id) ?? null;
+}
+
+/** Read a persisted delivery, including the delivery names written by the pre-capability runner. */
+export function stored_delivery(value) {
+  const legacy = { process: { stoppable: true, progress: true }, api: { stoppable: true, progress: true },
+    window: { stoppable: false, progress: false }, app: { stoppable: false, progress: false }, sidecar: { stoppable: false, progress: false } };
+  return Object.hasOwn(legacy, value) ? legacy[value] : JSON.parse(value);
+}
+
+/** Adapters whose sessions this machine can cut or branch; the website lists taken-back executions only for these. */
+export const BRANCHABLE_ADAPTERS = Object.values(ADAPTERS).filter(adapter => adapter.session?.branch).map(adapter => adapter.id);
+
+/** Whether a session exists on this machine, e.g. to tell if a pending Claude fork already happened. */
+export function session_exists(adapter_id, session_id, options = {}) {
+  return Boolean(adapter_of(adapter_id)?.session?.exists(session_id, options));
+}
+
+/**
+ * Branch a session before the first of some taken-back executions it contains, leaving the original untouched.
+ *
+ * @param {object} profile The member's local software profile (`adapter`, `executable`).
+ * @param {string} session_id The session the member is bound to.
+ * @param {number[]} executions Execution IDs whose turns the branch must not contain.
+ * @param {object} options `always` branches even when none of them is in the session (a forked room needs its own copy).
+ * @returns {Promise<null|{session_id: string, fork?: {from: string, at: string}}>} null when nothing needs cutting;
+ *   an empty session_id starts a new conversation; `fork` asks Claude's next turn to fork into session_id.
+ */
+export async function branch_session(profile, session_id, executions, { always = false, env = process.env, home = homedir(), spawn_process = spawn } = {}) {
+  const branch = adapter_of(profile.adapter)?.session?.branch;
+  if (!branch) throw new Error(`${profile.adapter} 的会话不能由本机截断`);
+  return branch(profile, session_id, executions.map(execution_marker), { always, env, home, spawn_process });
+}
+
+/**
+ * The model and effort a session last ran with, read from the software's own session store; no AI turn is started.
+ * These are each software's internal formats, so anything unreadable yields empty strings rather than an error.
+ */
+export function session_settings(adapter_id, session_id, options = {}) {
+  const none = { model: '', effort: '' };
+  if (typeof session_id !== 'string' || !SESSION_PATTERN.test(session_id)) return none;
+  try { return adapter_of(adapter_id)?.session?.settings(session_id, options) || none; }
+  catch { return none; }
+}
+
+/** Public model metadata only; failures leave the original-software default available to the UI. */
+export async function software_models(profile, options = {}) {
+  const adapter = adapter_of(profile.adapter);
+  const result = { adapter: profile.adapter, models: [], source: adapter?.catalog_source || 'original-software' };
+  if (!adapter?.models) return { ...result, error: '此入口的模型在原软件内设置' };
+  if (typeof profile.executable !== 'string' || !isAbsolute(profile.executable)) return { ...result, error: '请先配置 CLI 的完整路径，再读取模型列表' };
+  try {
+    const models = (await adapter.models.list(profile, options)).filter(Boolean);
+    result.models = [...new Map(models.map(model => [model.id, model])).values()];
+    if (!result.models.length) result.error = '软件未返回可选模型，请检查版本、登录与网络；仍可使用软件默认模型';
+  } catch (error) { result.error = error.message; }
+  return result;
+}
+
+/** The effort levels the software offers for the selected model, where it can tell without an agent turn. */
+export async function software_effort(profile, options = {}) {
+  const effort = adapter_of(profile.adapter)?.models?.effort;
+  if (!effort || !isAbsolute(profile.executable || '') || (profile.model && !MODEL_PATTERN.test(profile.model))) return { error: '无法读取所选模型的思考档位' };
+  try { return { levels: await effort(profile, options) }; }
+  catch { return { error: '无法读取原生思考档位；保留 CLI 默认值，或检查软件版本后重试' }; }
+}
+
+/** What a CLI runs with when the card leaves model or effort empty. */
+export async function software_defaults(profile, options = {}) {
+  return (await adapter_of(profile.adapter)?.models?.defaults(profile, options)) || { model: '', effort: '' };
+}