@agentex/agent 0.0.24 → 0.0.26

package/src/providers/codex/codec.ts

@@ -0,0 +1,50 @@
+import type { SessionCodec } from "../../types.js";
+
+function readNonEmptyString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function parseAsObject(raw: unknown): Record<string, unknown> | null {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  return raw as Record<string, unknown>;
+}
+
+export const codexSessionCodec: SessionCodec = {
+  deserialize(raw: unknown): Record<string, unknown> | null {
+    const obj = parseAsObject(raw);
+    if (!obj) return null;
+    const sessionId =
+      readNonEmptyString(obj["sessionId"]) ??
+      readNonEmptyString(obj["session_id"]) ??
+      readNonEmptyString(obj["thread_id"]);
+    if (!sessionId) return null;
+    const cwd = readNonEmptyString(obj["cwd"]);
+    return {
+      sessionId,
+      ...(cwd ? { cwd } : {}),
+    };
+  },
+
+  serialize(params: Record<string, unknown> | null): Record<string, unknown> | null {
+    if (!params) return null;
+    const sessionId =
+      readNonEmptyString(params["sessionId"]) ??
+      readNonEmptyString(params["session_id"]) ??
+      readNonEmptyString(params["thread_id"]);
+    if (!sessionId) return null;
+    const cwd = readNonEmptyString(params["cwd"]);
+    return {
+      sessionId,
+      ...(cwd ? { cwd } : {}),
+    };
+  },
+
+  getDisplayId(params: Record<string, unknown> | null): string | null {
+    if (!params) return null;
+    return (
+      readNonEmptyString(params["sessionId"]) ??
+      readNonEmptyString(params["session_id"]) ??
+      readNonEmptyString(params["thread_id"])
+    );
+  },
+};

package/src/providers/codex/execute.ts

@@ -0,0 +1,337 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExecutionContext, ExecutionResult } from "../../types.js";
+import { findBinary } from "../../utils/binary.js";
+import { buildEnv, ensurePathInEnv } from "../../utils/env.js";
+import { translateEndpoint } from "../../utils/endpoint.js";
+import { runChildProcess, deriveErrorCode } from "../../utils/process.js";
+import { detectAuth } from "../../utils/auth.js";
+import { injectWorkspaceSkills } from "../../utils/skills.js";
+import { resolveInstructions } from "../../utils/instructions.js";
+import { createToolNameTracker } from "../../utils/tool-names.js";
+import { prepareWorkspace } from "../../utils/workspace.js";
+import type { PreparedWorkspace } from "../../utils/workspace.js";
+import { uuidv7 } from "../../utils/uuid.js";
+import {
+  parseCodexJsonl,
+  parseCodexStreamLine,
+  stripCodexRolloutNoise,
+  isCodexAuthRequired,
+  isCodexUnknownSessionError,
+} from "./parse.js";
+import { withPlanModePreamble } from "./plan-mode.js";
+import { scanCodexSessionUsage } from "./usage-scanner.js";
+
+export async function executeCodexProvider(ctx: ExecutionContext): Promise<ExecutionResult> {
+  const runId = ctx.runId ?? uuidv7();
+  let cwd = ctx.cwd ?? process.cwd();
+  const model = ctx.model ?? ctx.config?.model;
+  const config = ctx.config ?? {};
+  const startedAt = new Date().toISOString();
+
+  // 1. Resolve binary
+  ctx.onLifecycle?.({ phase: "preparing", step: "binary" });
+  let resolvedBinary;
+  try {
+    resolvedBinary = await findBinary("codex", config.command);
+  } catch (err) {
+    const errorMessage = err instanceof Error ? err.message : "Binary not found";
+    ctx.onLifecycle?.({ phase: "error", message: errorMessage });
+    return {
+      runId,
+      exitCode: null,
+      signal: null,
+      status: "failed" as const,
+      startedAt,
+      completedAt: new Date().toISOString(),
+      durationMs: Date.now() - new Date(startedAt).getTime(),
+      errorMessage,
+      errorCode: "binary_not_found",
+      costUsd: null,
+      model: null,
+      summary: null,
+      sessionParams: null,
+      sessionDisplayId: null,
+      clearSession: false,
+      billingType: null,
+    };
+  }
+
+  // 2. Workspace isolation
+  let workspace: PreparedWorkspace | undefined;
+  if (config.workspace) {
+    ctx.onLifecycle?.({ phase: "preparing", step: "workspace" });
+    workspace = await prepareWorkspace(cwd, config.workspace);
+    cwd = workspace.cwd;
+  }
+
+  // 3. Build env & resolve instructions
+  ctx.onLifecycle?.({ phase: "preparing", step: "instructions" });
+  const env = buildEnv(ctx.env);
+  ensurePathInEnv(env);
+  // Custom endpoint (BYOK / gateway / alt model) — codex needs both a
+  // synthesized model_providers block (`-c` args, added in buildArgs) and the
+  // key in env. `unset` is empty for codex (the ambient key never routes here).
+  const endpointTx = translateEndpoint("codex", config.endpoint);
+  Object.assign(env, endpointTx.env);
+  for (const key of endpointTx.unset) delete env[key];
+
+  // 3. Resolve instructions. In plan mode, prepend a preamble that tells the
+  //    agent to investigate-and-propose rather than attempt-and-fail — Codex
+  //    has no native plan-mode UX, so the system prompt is what makes plan
+  //    mode actually work as a planning flow.
+  const baseInstructions = await resolveInstructions(config.instructionsFile);
+  const instructions = config.planMode
+    ? withPlanModePreamble(baseInstructions)
+    : baseInstructions;
+  const fullPrompt = instructions ? `${instructions}\n\n${ctx.prompt}` : ctx.prompt;
+
+  // 4. Inject skills into workspace
+  ctx.onLifecycle?.({ phase: "preparing", step: "skills" });
+  if (config.skillDirs && config.skillDirs.length > 0) {
+    try {
+      await injectWorkspaceSkills(config.skillDirs, cwd);
+    } catch {
+      // Non-fatal
+    }
+  }
+
+  // Detect auth/billing. Codex prefers its stored subscription (`codex login`)
+  // over OPENAI_API_KEY when both exist, so env-only detection would wrongly
+  // predict "api" whenever OPENAI_API_KEY is set. Check the auth.json stat:
+  // if the subscription file is present, billing is "subscription" regardless.
+  ctx.onLifecycle?.({ phase: "preparing", step: "auth" });
+  const codexAuthPath = path.join(
+    process.env["CODEX_HOME"] || path.join(os.homedir(), ".codex"),
+    "auth.json",
+  );
+  const hasCodexSubscription = await fs.stat(codexAuthPath).then(
+    (s) => s.isFile(),
+    () => false,
+  );
+  // A custom base URL is external/BYOK billing, not the codex subscription.
+  const billingType = config.endpoint?.baseUrl
+    ? "api"
+    : hasCodexSubscription
+    ? "subscription"
+    : detectAuth("codex", env).billingType;
+
+  // 4. Determine session resume
+  const sessionParams = ctx.sessionParams ?? null;
+  const sessionId = (() => {
+    if (!sessionParams) return null;
+    const id =
+      (sessionParams["sessionId"] as string | undefined) ??
+      (sessionParams["session_id"] as string | undefined) ??
+      (sessionParams["thread_id"] as string | undefined);
+    if (!id || typeof id !== "string") return null;
+    const sessionCwd = sessionParams["cwd"] as string | undefined;
+    if (sessionCwd && path.resolve(sessionCwd) !== path.resolve(cwd)) return null;
+    return id;
+  })();
+
+  // 5. Build args
+  const buildArgs = (resumeSessionId: string | null): string[] => {
+    const args = [...resolvedBinary.prefixArgs];
+    if (config.search) args.push("--search");
+    args.push("exec", "--json");
+    // planMode and skipPermissions are mutually exclusive — planMode wins.
+    if (config.planMode) {
+      args.push("--sandbox", "read-only");
+    } else if (config.skipPermissions) {
+      args.push("--dangerously-bypass-approvals-and-sandbox");
+    }
+    if (model) args.push("--model", model);
+    if (config.effort) args.push("-c", `model_reasoning_effort=${JSON.stringify(config.effort)}`);
+    // Custom endpoint model_providers overrides — before extraArgs so hosts can override.
+    if (endpointTx.args.length > 0) args.push(...endpointTx.args);
+    if (config.extraArgs) args.push(...config.extraArgs);
+    if (resumeSessionId) {
+      args.push("resume", resumeSessionId, "-");
+    } else {
+      args.push("-");
+    }
+    return args;
+  };
+
+  // 6. Run attempt
+  const runAttempt = async (resumeSessionId: string | null) => {
+    const args = buildArgs(resumeSessionId);
+    let lineBuffer = "";
+    // Track thread_id across lines — Codex only emits it once (thread.started)
+    // but downstream events need it attached for DB correlation.
+    let streamThreadId: string | null = resumeSessionId;
+    // Correlates tool_call → tool_result so emitted tool_result events carry
+    // toolName. One tracker per attempt (a retry restarts the stream).
+    const trackToolName = createToolNameTracker();
+
+    const handleLine = async (trimmed: string) => {
+      if (!trimmed) return;
+      if (streamThreadId === null) {
+        try {
+          const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+          if (parsed && parsed["type"] === "thread.started" && typeof parsed["thread_id"] === "string") {
+            streamThreadId = parsed["thread_id"];
+          }
+        } catch { /* ignore */ }
+      }
+      if (!ctx.onEvent) return;
+      const event = parseCodexStreamLine(trimmed, streamThreadId);
+      if (event) {
+        try { await ctx.onEvent(trackToolName(event)); } catch { /* swallow */ }
+      }
+    };
+
+    ctx.onLifecycle?.({ phase: "spawning" });
+    const proc = await runChildProcess({
+      runId,
+      command: resolvedBinary.bin,
+      args,
+      cwd,
+      env,
+      stdin: fullPrompt,
+      timeoutSec: config.timeoutSec,
+      graceSec: config.graceSec,
+      onStart: (pid) => {
+        ctx.onLifecycle?.({ phase: "running", pid });
+        ctx.onStart?.(pid);
+      },
+      signal: ctx.signal,
+      onOutput: async (stream, chunk) => {
+        if (stream === "stderr") {
+          // Filter rollout noise before forwarding
+          const cleaned = stripCodexRolloutNoise(chunk);
+          if (cleaned.trim() && ctx.onOutput) {
+            try { await ctx.onOutput(stream, cleaned); } catch { /* swallow */ }
+          }
+        } else {
+          if (ctx.onOutput) {
+            try { await ctx.onOutput(stream, chunk); } catch { /* swallow */ }
+          }
+
+          // Parse stdout lines for stream events
+          lineBuffer += chunk;
+          const lines = lineBuffer.split("\n");
+          lineBuffer = lines.pop() ?? "";
+          for (const line of lines) {
+            await handleLine(line.trim());
+          }
+        }
+      },
+    });
+
+    if (lineBuffer.trim()) {
+      await handleLine(lineBuffer.trim());
+    }
+
+    return proc;
+  };
+
+  // 7. Initial attempt
+  let proc = await runAttempt(sessionId);
+  let clearSession = false;
+
+  // Check for unknown session — retry once
+  if (
+    sessionId &&
+    !proc.timedOut &&
+    (proc.exitCode ?? 0) !== 0 &&
+    isCodexUnknownSessionError(proc.stdout, proc.stderr)
+  ) {
+    proc = await runAttempt(null);
+    clearSession = true;
+  }
+
+  const parsed = parseCodexJsonl(proc.stdout);
+  const processErrorCode = deriveErrorCode(proc);
+
+  let errorCode = processErrorCode;
+  if (!errorCode && isCodexAuthRequired(proc.stdout, proc.stderr)) {
+    errorCode = "auth_required";
+    // Codex emits `type: "error"` / `type: "turn.failed"` events but those
+    // are generic — the auth-vs-rate-limit distinction lives in the text.
+    // Surface an auth_required stream event so consumers wired to onEvent
+    // get the same uniform signal as Claude.
+    if (ctx.onEvent) {
+      try {
+        await ctx.onEvent({
+          type: "auth_required",
+          httpStatus: null,
+          reason: parsed.errorMessage && /invalid.*api.*key/i.test(parsed.errorMessage) ? "invalid" : "missing",
+          loginCommand: "codex login",
+          message: parsed.errorMessage,
+          timestamp: new Date().toISOString(),
+          providerType: "codex",
+          sessionId: parsed.sessionId,
+          messageId: null,
+          eventId: null,
+          turnId: null,
+          parentToolCallId: null,
+          raw: parsed.finalEvent ?? {},
+        });
+      } catch { /* swallow */ }
+    }
+  }
+
+  const errorMessage = (() => {
+    if (proc.timedOut) return `Timed out after ${config.timeoutSec ?? 0}s`;
+    if (errorCode === "auth_required") return "Codex requires OPENAI_API_KEY.";
+    if ((proc.exitCode ?? 0) !== 0) {
+      return parsed.errorMessage ?? stripCodexRolloutNoise(proc.stderr).split(/\r?\n/).map((l) => l.trim()).find(Boolean) ?? `Codex exited with code ${proc.exitCode ?? -1}`;
+    }
+    if (parsed.isError) return parsed.errorMessage;
+    return null;
+  })();
+
+  const resolvedSessionId = parsed.sessionId;
+  const resultSessionParams = resolvedSessionId
+    ? { sessionId: resolvedSessionId, cwd }
+    : null;
+
+  const completedAt = new Date().toISOString();
+  const resolvedModel = parsed.model ?? model ?? null;
+  const status = proc.aborted ? "aborted" as const
+    : proc.timedOut ? "timeout" as const
+    : (errorCode || errorMessage) ? "failed" as const
+    : "completed" as const;
+
+  if (status === "completed") {
+    ctx.onLifecycle?.({ phase: "completed" });
+  } else if (status === "aborted") {
+    ctx.onLifecycle?.({ phase: "cancelled" });
+  } else {
+    ctx.onLifecycle?.({ phase: "error", message: errorMessage ?? "Unknown error" });
+  }
+
+  return {
+    runId,
+    exitCode: proc.exitCode,
+    signal: proc.signal ?? null,
+    status,
+    startedAt,
+    completedAt,
+    durationMs: new Date(completedAt).getTime() - new Date(startedAt).getTime(),
+    errorMessage,
+    errorCode,
+    usage: parsed.usage && resolvedModel
+      ? { [resolvedModel]: {
+          inputTokens: parsed.usage.inputTokens,
+          outputTokens: parsed.usage.outputTokens,
+          ...(parsed.usage.cachedInputTokens !== undefined ? { cachedInputTokens: parsed.usage.cachedInputTokens } : {}),
+        } }
+      : await scanCodexSessionUsage({
+          startedAfter: new Date(startedAt),
+          threadId: resolvedSessionId ?? undefined,
+        }),
+    costUsd: null,
+    model: resolvedModel,
+    summary: parsed.summary,
+    sessionParams: resultSessionParams,
+    sessionDisplayId: resolvedSessionId,
+    clearSession,
+    billingType,
+    raw: parsed.finalEvent,
+    workspace,
+  };
+}

package/src/providers/codex/goal-capability.ts

@@ -0,0 +1,19 @@
+import type { GoalCapability } from "../../types.js";
+
+/**
+ * Codex carries goals as durable thread state mutated by model tools
+ * (create_goal/update_goal/get_goal). Advisory — the model self-reports; no
+ * turn-end gate. Goal mode is experimental and feature-gated upstream, so the
+ * native arm is best-effort and falls back to emulation (see spec §7.2).
+ *
+ * Lives in its own leaf module (not `session.ts`) so `index.ts` can read the
+ * static `capabilities.goals` field without pulling the heavy session machinery
+ * into the module graph (spec §5.1).
+ */
+export const codexGoalCapability: GoalCapability = {
+  mechanism: "model-tools",
+  enforced: false,
+  statuses: ["active", "paused", "met", "blocked", "cleared"],
+  clears: "manual",
+  telemetry: true,
+};

package/src/providers/codex/index.ts

@@ -0,0 +1,57 @@
+import type { ProviderModule, SessionContext, AgentSession } from "../../types.js";
+import { codexSessionCodec } from "./codec.js";
+import { resolveAuthForProvider } from "../../utils/auth.js";
+import { codexTranscriptOps } from "./transcript.js";
+import { codexGoalCapability } from "./goal-capability.js";
+
+export const codexProvider: ProviderModule = {
+  type: "codex",
+  capabilities: {
+    sessions: true,
+    modelDiscovery: false,
+    quotaProbing: false,
+    mcp: false,
+    skills: true,
+    skillInventory: "local-discovery",
+    skillInvocation: "expanded-prompt",
+    instructions: true,
+    workspace: true,
+    planMode: true,
+    concurrentSend: true,
+    cancelQueuedMessage: false,
+    stopTask: false,
+    modes: true,
+    goals: codexGoalCapability,
+    durableSessions: true,
+  },
+  // Heavy machinery (execute.ts, session.ts, modes.ts, attach.ts) loads lazily
+  // on first use — every ProviderModule method is already async.
+  execute: async (ctx) => (await import("./execute.js")).executeCodexProvider(ctx),
+  createSession: async (ctx: SessionContext): Promise<AgentSession> =>
+    (await import("./session.js")).createCodexSession(ctx),
+  resolveAuth: (ctx) => resolveAuthForProvider("codex", ctx),
+  sessionCodec: codexSessionCodec,
+  transcript: codexTranscriptOps,
+  listModes: async (opts) => (await import("./modes.js")).listCodexModes(opts),
+  attachSession: async (record, opts) =>
+    (await import("./attach.js")).attachCodexSession(record, opts),
+};
+
+export {
+  getCodexTranscriptPath,
+  readCodexTranscript,
+  peekCodexTranscript,
+  readCodexCwd,
+  codexTranscriptOps,
+  parseCodexLine,
+  resolveCodexHome,
+} from "./transcript.js";
+export { codexLineToStreamEvents } from "./transcript-normalize.js";
+export type {
+  GetCodexTranscriptPathOptions,
+  CodexTranscriptLocation,
+  ReadCodexTranscriptOptions,
+  CodexTranscriptYield,
+  CodexTranscriptLine,
+  CodexPeekResult,
+} from "./transcript.js";

package/src/providers/codex/modes.ts

@@ -0,0 +1,159 @@
+import { spawn } from "node:child_process";
+import type { AgentMode, ListModesOptions } from "../../types.js";
+import { findBinary } from "../../utils/binary.js";
+import { buildEnv, ensurePathInEnv } from "../../utils/env.js";
+
+/**
+ * A raw Codex "collaboration mode" entry as returned by the app-server's
+ * `collaborationMode/list` RPC. Codex's collaboration modes (e.g. Auto, Plan,
+ * Read Only) are the cross-provider equivalent of agentex `AgentMode`s.
+ */
+export interface CodexCollaborationMode {
+  name: string;
+  mode: string | null;
+  model: string | null;
+  reasoning_effort: string | null;
+  developer_instructions: string | null;
+}
+
+/** Parse a `collaborationMode/list` response into raw entries (tolerant of
+ *  missing fields; drops entries without a name). */
+export function parseCollaborationModes(response: unknown): CodexCollaborationMode[] {
+  const data =
+    response && typeof response === "object" && Array.isArray((response as Record<string, unknown>)["data"])
+      ? ((response as Record<string, unknown>)["data"] as unknown[])
+      : [];
+  const out: CodexCollaborationMode[] = [];
+  for (const entry of data) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const r = entry as Record<string, unknown>;
+    const name = typeof r["name"] === "string" ? r["name"] : "";
+    if (!name) continue;
+    out.push({
+      name,
+      mode: typeof r["mode"] === "string" ? r["mode"] : null,
+      model: typeof r["model"] === "string" ? r["model"] : null,
+      reasoning_effort: typeof r["reasoning_effort"] === "string" ? r["reasoning_effort"] : null,
+      developer_instructions:
+        typeof r["developer_instructions"] === "string" ? r["developer_instructions"] : null,
+    });
+  }
+  return out;
+}
+
+/** Convert raw collaboration modes into the cross-provider `AgentMode` shape.
+ *  `id` is the mode string (the value passed back via `config.modeId`); falls
+ *  back to the name when codex doesn't supply a distinct mode value. */
+export function toAgentModes(modes: CodexCollaborationMode[]): AgentMode[] {
+  return modes.map((m) => ({
+    id: m.mode ?? m.name,
+    name: m.name,
+    ...(m.developer_instructions ? { description: m.developer_instructions } : {}),
+  }));
+}
+
+/** Build the `thread/start` / `thread/resume` `collaborationMode` parameter for
+ *  a chosen mode id, mirroring the shape codex's app-server expects. Returns
+ *  null when the id doesn't match any known mode. */
+export function resolveCollaborationModeParam(
+  modes: CodexCollaborationMode[],
+  modeId: string,
+): { mode: string; settings: Record<string, unknown> } | null {
+  const match = modes.find((m) => m.mode === modeId) ?? modes.find((m) => m.name === modeId);
+  if (!match) return null;
+  const settings: Record<string, unknown> = {};
+  if (match.model) settings["model"] = match.model;
+  if (match.reasoning_effort) settings["reasoning_effort"] = match.reasoning_effort;
+  if (match.developer_instructions) settings["developer_instructions"] = match.developer_instructions;
+  return { mode: match.mode ?? match.name, settings };
+}
+
+/**
+ * Minimal one-shot JSON-RPC over a child's stdio: send `initialize`, then the
+ * `target` method, resolve with the target's result, and tear the process down.
+ * Used by `listCodexModes` so callers can discover modes without opening a full
+ * session.
+ */
+function oneShotRpc(
+  proc: ReturnType<typeof spawn>,
+  target: string,
+  timeoutMs: number,
+): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    if (!proc.stdin || !proc.stdout) {
+      reject(new Error("codex app-server stdio unavailable"));
+      return;
+    }
+    let buffer = "";
+    let settled = false;
+    const initId = 1;
+    const targetId = 2;
+
+    const timer = setTimeout(() => finish(new Error(`codex ${target} timed out`)), timeoutMs);
+
+    function finish(err: Error | null, value?: unknown): void {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { proc.kill(); } catch { /* ignore */ }
+      if (err) reject(err);
+      else resolve(value);
+    }
+
+    proc.stdout.setEncoding("utf-8");
+    proc.stdout.on("data", (chunk: string) => {
+      buffer += chunk;
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        let msg: Record<string, unknown>;
+        try { msg = JSON.parse(trimmed) as Record<string, unknown>; } catch { continue; }
+        if (msg["id"] === initId && !("method" in msg)) {
+          // initialize acknowledged → request the target.
+          proc.stdin!.write(JSON.stringify({ jsonrpc: "2.0", id: targetId, method: target, params: {} }) + "\n");
+        } else if (msg["id"] === targetId && !("method" in msg)) {
+          if (msg["error"]) {
+            const e = msg["error"] as { message?: string };
+            finish(new Error(`codex ${target} error: ${e.message ?? "unknown"}`));
+          } else {
+            finish(null, msg["result"] ?? {});
+          }
+        }
+      }
+    });
+    proc.on("error", (err) => finish(err instanceof Error ? err : new Error(String(err))));
+    proc.on("exit", (code) => {
+      if (!settled) finish(new Error(`codex app-server exited (code=${code}) before responding`));
+    });
+
+    proc.stdin.write(
+      JSON.stringify({ jsonrpc: "2.0", id: initId, method: "initialize", params: { clientInfo: { name: "agentex", version: "1.0.0" }, capabilities: {} } }) + "\n",
+    );
+  });
+}
+
+/**
+ * Discover Codex's collaboration modes by spawning a throwaway `codex
+ * app-server`, running the initialize handshake, requesting
+ * `collaborationMode/list`, and closing. Returns [] on any failure (modes are
+ * advisory — a discovery failure shouldn't surface as a hard error).
+ */
+export async function listCodexModes(options?: ListModesOptions): Promise<AgentMode[]> {
+  const config = options?.config ?? {};
+  const resolved = await findBinary("codex", config.command);
+  const env = buildEnv(options?.env);
+  ensurePathInEnv(env);
+  const proc = spawn(resolved.bin, [...resolved.prefixArgs, "app-server"], {
+    cwd: options?.cwd ?? process.cwd(),
+    env,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  try {
+    const response = await oneShotRpc(proc, "collaborationMode/list", config.timeoutSec ? config.timeoutSec * 1000 : 15_000);
+    return toAgentModes(parseCollaborationModes(response));
+  } catch {
+    return [];
+  }
+}