jeo-code 0.12.1 → 0.12.3

package/src/agent/antigravity-cli.ts

@@ -0,0 +1,499 @@
+import type { ReadableStreamDefaultReader as WebStreamReader } from "node:stream/web";
+
+const DEFAULT_TURN_TIMEOUT_MS = 5 * 60_000;
+const DEFAULT_MODEL_TIMEOUT_MS = 15_000;
+const MAX_TURN_TIMEOUT_MS = DEFAULT_TURN_TIMEOUT_MS;
+const MAX_MODEL_TIMEOUT_MS = DEFAULT_MODEL_TIMEOUT_MS;
+const MAX_STREAM_BYTES = 8 * 1024 * 1024;
+const MAX_MODEL_OUTPUT_BYTES = 256 * 1024;
+const KILL_ESCALATION_MS = 250;
+
+export interface AgyModelOptions {
+  cwd?: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  executable?: string;
+}
+
+export interface AgyUsage {
+  inputTokens: number;
+  outputTokens: number;
+  thinkingTokens?: number;
+  cacheReadTokens?: number;
+}
+
+export interface AgyTurnOptions {
+  model: string;
+  prompt: string;
+  cwd: string;
+  conversationId?: string;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+  mode?: "plan" | "auto" | "accept-edits";
+  executable?: string;
+  onText?: (text: string) => void;
+  onNotice?: (text: string) => void;
+  onConversation?: (id: string) => void | Promise<void>;
+}
+
+export interface AgyTurnResult {
+  model: string;
+  conversationId: string;
+  response: string;
+  steps: number;
+  usage?: AgyUsage;
+}
+
+export type AgyCliErrorKind = "spawn" | "timeout" | "cancelled" | "protocol" | "upstream" | "exit";
+
+export class AgyCliError extends Error {
+  constructor(
+    message: string,
+    readonly kind: AgyCliErrorKind,
+    readonly exitCode?: number | null,
+    readonly stderr?: string,
+  ) {
+    super(message);
+    this.name = "AgyCliError";
+  }
+}
+
+interface InitPayload {
+  model: string;
+}
+
+interface StepPayload {
+  step_type?: unknown;
+  step_index?: unknown;
+  state?: unknown;
+  text_delta?: unknown;
+  tool_name?: unknown;
+  tool_info?: unknown;
+  permission_mode?: unknown;
+  permission?: unknown;
+  [key: string]: unknown;
+}
+
+interface ResultPayload {
+  conversation_id?: unknown;
+  status?: unknown;
+  response?: unknown;
+  error?: unknown;
+  model?: unknown;
+  usage?: unknown;
+  [key: string]: unknown;
+}
+
+interface AgyEvent {
+  event: unknown;
+  conversation_id?: unknown;
+  init?: unknown;
+  step_update?: unknown;
+  result?: unknown;
+}
+
+const asRecord = (value: unknown): Record<string, unknown> | undefined => {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+};
+
+const nonEmptyString = (value: unknown): string | undefined =>
+  typeof value === "string" && value.trim().length > 0 ? value : undefined;
+
+const finiteNonNegative = (value: unknown): number | undefined =>
+  typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+
+const normalizeTimeout = (value: number | undefined, defaultMs: number, maxMs: number): number => {
+  if (value === undefined) return defaultMs;
+  if (!Number.isFinite(value) || value <= 0) throw new AgyCliError("Agy timeout must be a positive finite number of milliseconds.", "protocol");
+  return Math.min(Math.max(1, Math.ceil(value)), maxMs);
+};
+
+
+const canonicalModelParts = (model: string): { canonical: string; slug: string } => {
+  if (typeof model !== "string" || !model.startsWith("agy/")) {
+    throw new AgyCliError(`Agy model must use the explicit agy/<slug> namespace; received ${String(model)}.`, "protocol");
+  }
+  const slug = model.slice("agy/".length);
+  if (!slug || /[\s/]/u.test(slug)) {
+    throw new AgyCliError(`Agy model must contain one non-empty CLI slug; received ${model}.`, "protocol");
+  }
+  return { canonical: `agy/${slug}`, slug };
+};
+
+const decodeError = (error: unknown): string => error instanceof Error ? error.message : String(error);
+
+const appendBounded = (current: string, chunk: string, limit: number): string => {
+  if (!chunk) return current;
+  const next = current + chunk;
+  return next.length <= limit ? next : next.slice(0, limit);
+};
+
+const killProcess = (proc: Pick<Bun.Subprocess, "kill">, signal: "SIGTERM" | "SIGKILL"): void => {
+  try {
+    proc.kill(signal);
+  } catch {
+    // The process may have exited between the liveness check and the signal.
+  }
+};
+
+function parseModelList(stdout: string): string[] {
+  const models: string[] = [];
+  const seen = new Set<string>();
+  for (const [index, rawLine] of stdout.split(/\r?\n/u).entries()) {
+    const line = rawLine.trimEnd();
+    if (!line.trim()) continue;
+    const tab = line.indexOf("\t");
+    if (tab < 0) {
+      throw new AgyCliError(`Malformed agy model list record at line ${index + 1}; expected <slug>\\t<label>.`, "protocol");
+    }
+    const slug = line.slice(0, tab);
+    const label = line.slice(tab + 1);
+    if (!slug.trim() || !label.trim() || /[\s/]/u.test(slug)) {
+      throw new AgyCliError(`Malformed agy model list record at line ${index + 1}; slug and label are required.`, "protocol");
+    }
+    if (seen.has(slug)) continue;
+    seen.add(slug);
+    models.push(`agy/${slug}`);
+  }
+  return models;
+}
+
+export async function listAgyModels(options: AgyModelOptions = {}): Promise<string[]> {
+  const timeoutMs = normalizeTimeout(options.timeoutMs, DEFAULT_MODEL_TIMEOUT_MS, MAX_MODEL_TIMEOUT_MS);
+  if (options.signal?.aborted) throw new AgyCliError("Agy model discovery was aborted before spawn.", "cancelled");
+
+  const executable = options.executable ?? "agy";
+  const cwd = options.cwd ?? process.cwd();
+  let proc: Bun.Subprocess<"ignore", "pipe", "pipe">;
+  try {
+    proc = Bun.spawn([executable, "models"], { cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+  } catch (error) {
+    throw new AgyCliError(`Failed to start agy model discovery: ${decodeError(error)}. Install agy and authenticate it with its own CLI.`, "spawn");
+  }
+
+  let stdout = "";
+  let stderr = "";
+  let stdoutBytes = 0;
+  let stderrBytes = 0;
+  let timedOut = false;
+  let cancelled = false;
+  let killed = false;
+  let escalation: NodeJS.Timeout | undefined;
+  let stdoutReader: WebStreamReader<Uint8Array> | undefined;
+  let stderrReader: WebStreamReader<Uint8Array> | undefined;
+  let streamFailed: unknown;
+
+  const stopProcess = (): void => {
+    if (killed) return;
+    killed = true;
+    void stdoutReader?.cancel().catch(() => {});
+    void stderrReader?.cancel().catch(() => {});
+    killProcess(proc, "SIGTERM");
+    escalation = setTimeout(() => killProcess(proc, "SIGKILL"), KILL_ESCALATION_MS);
+  };
+  const terminate = (reason: "timeout" | "cancelled"): void => {
+    if (reason === "timeout") timedOut = true;
+    else cancelled = true;
+    stopProcess();
+  };
+  const onAbort = (): void => terminate("cancelled");
+  if (options.signal) options.signal.addEventListener("abort", onAbort, { once: true });
+
+  const drain = async (stream: ReadableStream<Uint8Array>, which: "stdout" | "stderr"): Promise<void> => {
+    const reader = stream.getReader();
+    if (which === "stdout") stdoutReader = reader;
+    else stderrReader = reader;
+    const decoder = new TextDecoder();
+    try {
+      for (;;) {
+        const part = await reader.read();
+        if (part.done) break;
+        const text = decoder.decode(part.value, { stream: true });
+        if (which === "stdout") {
+          stdoutBytes += part.value.byteLength;
+          if (stdoutBytes > MAX_MODEL_OUTPUT_BYTES) throw new AgyCliError("Agy model list exceeded the bounded output limit.", "protocol");
+          stdout = appendBounded(stdout, text, MAX_MODEL_OUTPUT_BYTES);
+        } else {
+          stderrBytes += part.value.byteLength;
+          stderr = appendBounded(stderr, text, MAX_MODEL_OUTPUT_BYTES);
+          if (stderrBytes > MAX_MODEL_OUTPUT_BYTES) stderr = `${stderr}\n[agy stderr truncated]`;
+        }
+      }
+      const tail = decoder.decode();
+      if (which === "stdout") stdout = appendBounded(stdout, tail, MAX_MODEL_OUTPUT_BYTES);
+      else stderr = appendBounded(stderr, tail, MAX_MODEL_OUTPUT_BYTES);
+    } finally {
+      reader.releaseLock();
+    }
+  };
+
+  const stdoutPromise = drain(proc.stdout, "stdout").catch(error => { streamFailed = error; stopProcess(); });
+  const stderrPromise = drain(proc.stderr, "stderr").catch(error => { if (!streamFailed) streamFailed = error; stopProcess(); });
+  try {
+    const timer = setTimeout(() => terminate("timeout"), timeoutMs);
+    let exitCode: number | null;
+    try {
+      exitCode = await proc.exited;
+      await Promise.all([stdoutPromise, stderrPromise]);
+    } finally {
+      clearTimeout(timer);
+    }
+    if (cancelled) throw new AgyCliError("Agy model discovery was cancelled.", "cancelled", exitCode, stderr);
+    if (timedOut) throw new AgyCliError(`Agy model discovery timed out after ${timeoutMs}ms.`, "timeout", exitCode, stderr);
+    if (streamFailed) throw streamFailed;
+    if (exitCode !== 0) {
+      const detail = stderr.trim() || `agy models exited with code ${exitCode}`;
+      throw new AgyCliError(`${detail} (exit ${exitCode}).`, "exit", exitCode, stderr);
+    }
+    return parseModelList(stdout);
+  } catch (error) {
+    if (!killed && proc.exitCode === null) stopProcess();
+    if (error instanceof AgyCliError) throw error;
+    throw new AgyCliError(`Agy model discovery failed: ${decodeError(error)}${stderr.trim() ? ` — ${stderr.trim()}` : ""}`, "protocol", proc.exitCode, stderr);
+  } finally {
+    if (options.signal) options.signal.removeEventListener("abort", onAbort);
+    try { await proc.exited; } catch { /* ignore exit read failures during cleanup */ }
+    clearTimeout(escalation);
+    try { await stdoutReader?.cancel(); } catch { /* ignore closed reader */ }
+    try { await stderrReader?.cancel(); } catch { /* ignore closed reader */ }
+  }
+}
+
+function parseUsage(value: unknown): AgyUsage | undefined {
+  const usage = asRecord(value);
+  if (!usage) return undefined;
+  const inputTokens = finiteNonNegative(usage.input_tokens ?? usage.inputTokens);
+  const outputTokens = finiteNonNegative(usage.output_tokens ?? usage.outputTokens);
+  if (inputTokens === undefined || outputTokens === undefined) return undefined;
+  const out: AgyUsage = { inputTokens, outputTokens };
+  const thinkingTokens = finiteNonNegative(usage.thinking_tokens ?? usage.thinkingTokens);
+  const cacheReadTokens = finiteNonNegative(usage.cache_read_tokens ?? usage.cacheReadTokens);
+  if (thinkingTokens !== undefined) out.thinkingTokens = thinkingTokens;
+  if (cacheReadTokens !== undefined) out.cacheReadTokens = cacheReadTokens;
+  return out;
+}
+
+export async function runAgyTurn(options: AgyTurnOptions): Promise<AgyTurnResult> {
+  const { canonical, slug } = canonicalModelParts(options.model);
+  if (typeof options.prompt !== "string") throw new AgyCliError("Agy prompt must be a string.", "protocol");
+  if (!options.cwd) throw new AgyCliError("Agy cwd is required.", "protocol");
+  const timeoutMs = normalizeTimeout(options.timeoutMs, DEFAULT_TURN_TIMEOUT_MS, MAX_TURN_TIMEOUT_MS);
+  if (options.signal?.aborted) throw new AgyCliError("Agy turn was aborted before spawn.", "cancelled");
+
+  const args = [
+    "--input-format", "stream-json",
+    "--output-format", "stream-json",
+    "--model", slug,
+    "--sandbox",
+    "--print-timeout", `${timeoutMs}ms`,
+  ];
+  if (options.conversationId !== undefined) {
+    if (!options.conversationId.trim()) throw new AgyCliError("Agy conversationId must be non-empty when provided.", "protocol");
+    args.push("--conversation", options.conversationId);
+  }
+  if (options.mode !== undefined) args.push("--mode", options.mode);
+
+  const executable = options.executable ?? "agy";
+  let proc: Bun.Subprocess<"pipe", "pipe", "pipe">;
+  try {
+    proc = Bun.spawn([executable, ...args], { cwd: options.cwd, stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+  } catch (error) {
+    throw new AgyCliError(`Failed to start agy: ${decodeError(error)}. Install agy and authenticate it with its own CLI.`, "spawn");
+  }
+
+  let stdoutBytes = 0;
+  let stderr = "";
+  let stderrBytes = 0;
+  let stdoutLine = "";
+  let initModel: string | undefined;
+  let conversationId: string | undefined;
+  let terminal: ResultPayload | undefined;
+  let stepCount = 0;
+  let streamedText = "";
+  let streamFailed: unknown;
+  let timedOut = false;
+  let cancelled = false;
+  let killed = false;
+  let escalation: NodeJS.Timeout | undefined;
+  let stdoutReader: WebStreamReader<Uint8Array> | undefined;
+  let stderrReader: WebStreamReader<Uint8Array> | undefined;
+  const stopProcess = (): void => {
+    if (killed) return;
+    killed = true;
+    void stdoutReader?.cancel().catch(() => {});
+    void stderrReader?.cancel().catch(() => {});
+    killProcess(proc, "SIGTERM");
+    escalation = setTimeout(() => killProcess(proc, "SIGKILL"), KILL_ESCALATION_MS);
+  };
+  const terminate = (reason: "timeout" | "cancelled"): void => {
+    if (reason === "timeout") timedOut = true;
+    else cancelled = true;
+    stopProcess();
+  };
+  const onAbort = (): void => terminate("cancelled");
+  if (options.signal) options.signal.addEventListener("abort", onAbort, { once: true });
+
+  const handleEvent = async (line: string): Promise<void> => {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch (error) {
+      throw new AgyCliError(`Malformed agy NDJSON event: ${decodeError(error)}`, "protocol", proc.exitCode, stderr);
+    }
+    const event = asRecord(parsed) as AgyEvent | undefined;
+    if (!event || typeof event.event !== "string") throw new AgyCliError("Malformed agy NDJSON envelope: missing event type.", "protocol", proc.exitCode, stderr);
+
+    if (event.event === "init") {
+      if (initModel !== undefined) throw new AgyCliError("Agy emitted more than one init event.", "protocol", proc.exitCode, stderr);
+      const init = asRecord(event.init) as InitPayload | undefined;
+      const model = nonEmptyString(init?.model);
+      const id = nonEmptyString(event.conversation_id);
+      if (!init || !model || !id) throw new AgyCliError("Agy init event is missing model or conversation_id.", "protocol", proc.exitCode, stderr);
+      if (model !== slug) throw new AgyCliError(`Agy init model mismatch: expected ${slug}, received ${model}.`, "protocol", proc.exitCode, stderr);
+      if (options.conversationId !== undefined && id !== options.conversationId) {
+        throw new AgyCliError(`Agy init conversation_id mismatch: expected ${options.conversationId}, received ${id}.`, "protocol", proc.exitCode, stderr);
+      }
+      initModel = model;
+      conversationId = id;
+      if (options.onConversation) await options.onConversation(id);
+      return;
+    }
+
+    if (event.event === "step_update") {
+      if (terminal) throw new AgyCliError("Agy emitted step_update after terminal result.", "protocol", proc.exitCode, stderr);
+      if (!initModel || !conversationId) throw new AgyCliError("Agy emitted step_update before init.", "protocol", proc.exitCode, stderr);
+      const step = asRecord(event.step_update) as StepPayload | undefined;
+      if (!step || typeof step.step_index !== "number" || !Number.isInteger(step.step_index) || step.step_index < 0
+        || !nonEmptyString(step.state) || !nonEmptyString(step.step_type)
+        || (step.text_delta !== undefined && typeof step.text_delta !== "string")
+        || (step.tool_name !== undefined && typeof step.tool_name !== "string")
+        || (step.permission_mode !== undefined && typeof step.permission_mode !== "string")
+        || (step.tool_info !== undefined && !asRecord(step.tool_info))
+        || (step.subagent_info !== undefined && !asRecord(step.subagent_info))) {
+        throw new AgyCliError("Malformed agy step_update event.", "protocol", proc.exitCode, stderr);
+      }
+      stepCount++;
+      if (step.conversation_id !== conversationId) {
+        throw new AgyCliError("Agy step_update conversation_id does not match init.", "protocol", proc.exitCode, stderr);
+      }
+      const textDelta = typeof step.text_delta === "string" ? step.text_delta : undefined;
+      if (step.step_type === "agent_response" && textDelta) {
+        streamedText += textDelta;
+        options.onText?.(textDelta);
+      }
+      if (step.step_type === "tool" || step.tool_info !== undefined || step.permission !== undefined || step.permission_mode !== undefined) {
+        const notice = typeof step.tool_name === "string" ? `agy tool: ${step.tool_name}` : `agy ${String(step.step_type ?? "permission")} notice`;
+        options.onNotice?.(notice);
+      }
+      return;
+    }
+
+    if (event.event === "result") {
+      if (terminal) throw new AgyCliError("Agy emitted more than one terminal result event.", "protocol", proc.exitCode, stderr);
+      const result = asRecord(event.result) as ResultPayload | undefined;
+      if (!result) throw new AgyCliError("Malformed agy result event.", "protocol", proc.exitCode, stderr);
+      terminal = result;
+      return;
+    }
+    // Forward-compatible unknown event types are intentionally ignored.
+  };
+
+  const drainStdout = async (): Promise<void> => {
+    const reader = proc.stdout.getReader();
+    stdoutReader = reader;
+    const decoder = new TextDecoder();
+    const consume = async (text: string): Promise<void> => {
+      stdoutLine += text;
+      if (stdoutLine.length > MAX_STREAM_BYTES) throw new AgyCliError("Agy output exceeded the bounded stream limit.", "protocol", proc.exitCode, stderr);
+      let newline = stdoutLine.indexOf("\n");
+      while (newline >= 0) {
+        const line = stdoutLine.slice(0, newline).replace(/\r$/u, "");
+        stdoutLine = stdoutLine.slice(newline + 1);
+        if (line.trim()) await handleEvent(line);
+        newline = stdoutLine.indexOf("\n");
+      }
+    };
+    try {
+      for (;;) {
+        const part = await reader.read();
+        if (part.done) break;
+        stdoutBytes += part.value.byteLength;
+        if (stdoutBytes > MAX_STREAM_BYTES) throw new AgyCliError("Agy output exceeded the bounded stream limit.", "protocol", proc.exitCode, stderr);
+        await consume(decoder.decode(part.value, { stream: true }));
+      }
+      await consume(decoder.decode());
+      if (stdoutLine.trim()) await handleEvent(stdoutLine.trim());
+      stdoutLine = "";
+    } finally {
+      reader.releaseLock();
+    }
+  };
+
+  const drainStderr = async (): Promise<void> => {
+    const reader = proc.stderr.getReader();
+    stderrReader = reader;
+    const decoder = new TextDecoder();
+    try {
+      for (;;) {
+        const part = await reader.read();
+        if (part.done) break;
+        stderrBytes += part.value.byteLength;
+        stderr = appendBounded(stderr, decoder.decode(part.value, { stream: true }), MAX_STREAM_BYTES);
+        if (stderrBytes > MAX_STREAM_BYTES) stderr = `${stderr}\n[agy stderr truncated]`;
+      }
+      stderr = appendBounded(stderr, decoder.decode(), MAX_STREAM_BYTES);
+    } finally {
+      reader.releaseLock();
+    }
+  };
+
+  const stdoutPromise = drainStdout().catch(error => { streamFailed = error; stopProcess(); });
+  const stderrPromise = drainStderr().catch(error => { if (!streamFailed) streamFailed = error; stopProcess(); });
+  const input = `${JSON.stringify({ event: "user", message: { content: options.prompt } })}\n`;
+  const timer = setTimeout(() => terminate("timeout"), timeoutMs);
+  try {
+    await proc.stdin.write(input);
+    await proc.stdin.end();
+    const exitCode = await proc.exited;
+    await Promise.all([stdoutPromise, stderrPromise]);
+    if (cancelled) throw new AgyCliError("Agy turn was cancelled.", "cancelled", exitCode, stderr);
+    if (timedOut) throw new AgyCliError(`Agy turn timed out after ${timeoutMs}ms.`, "timeout", exitCode, stderr);
+    if (streamFailed) throw streamFailed;
+    const terminalStatus = nonEmptyString(terminal?.status)?.toUpperCase();
+    if (exitCode !== 0) {
+      const upstream = terminal?.error;
+      const detail = nonEmptyString(upstream) ?? (stderr.trim() || `agy exited with code ${exitCode}`);
+      throw new AgyCliError(`${detail} (exit ${exitCode}).`, terminalStatus === "ERROR" ? "upstream" : "exit", exitCode, stderr);
+    }
+    if (!initModel || !conversationId) throw new AgyCliError("Agy exited successfully without a valid init event.", "protocol", exitCode, stderr);
+    if (!terminal) throw new AgyCliError("Agy exited successfully without a terminal result event.", "protocol", exitCode, stderr);
+    const status = terminalStatus;
+    const resultConversation = nonEmptyString(terminal.conversation_id);
+    if (!resultConversation || resultConversation !== conversationId) throw new AgyCliError("Agy result conversation_id does not match init.", "protocol", exitCode, stderr);
+    if (status !== "SUCCESS") {
+      const detail = nonEmptyString(terminal.error) ?? `Agy returned terminal status ${status ?? "unknown"}.`;
+      throw new AgyCliError(`${detail}${exitCode === 0 ? " (exit 0)." : ` (exit ${exitCode}).`}`, "upstream", exitCode, stderr);
+    }
+    if (terminal.model !== undefined && terminal.model !== slug) throw new AgyCliError(`Agy result model mismatch: expected ${slug}, received ${String(terminal.model)}.`, "protocol", exitCode, stderr);
+    const response = typeof terminal.response === "string" ? terminal.response : undefined;
+    if (!response || !response.trim()) throw new AgyCliError("Agy returned SUCCESS with an empty response.", "protocol", exitCode, stderr);
+    if (!streamedText && response) options.onText?.(response);
+    else if (streamedText && response.startsWith(streamedText) && response.length > streamedText.length) options.onText?.(response.slice(streamedText.length));
+    return { model: canonical, conversationId, response, steps: stepCount, usage: parseUsage(terminal.usage) };
+  } catch (error) {
+    if (!killed && proc.exitCode === null) stopProcess();
+    if (cancelled) throw new AgyCliError("Agy turn was cancelled.", "cancelled", proc.exitCode, stderr);
+    if (timedOut) throw new AgyCliError(`Agy turn timed out after ${timeoutMs}ms.`, "timeout", proc.exitCode, stderr);
+    if (error instanceof AgyCliError) throw error;
+    if (error instanceof Error && /abort|cancel/i.test(error.message)) throw new AgyCliError(error.message, "cancelled", proc.exitCode, stderr);
+    throw new AgyCliError(`Agy turn failed: ${decodeError(error)}${stderr.trim() ? ` — ${stderr.trim()}` : ""}`, "protocol", proc.exitCode, stderr);
+  } finally {
+    if (options.signal) options.signal.removeEventListener("abort", onAbort);
+    clearTimeout(timer);
+    try { await proc.exited; } catch { /* ignore exit read failures during cleanup */ }
+    clearTimeout(escalation);
+    try { await stdoutReader?.cancel(); } catch { /* ignore closed reader */ }
+    try { await stderrReader?.cancel(); } catch { /* ignore closed reader */ }
+  }
+}

package/src/agent/session.ts

@@ -13,6 +13,8 @@ export interface SessionHeader {
   /** Model id pinned to this session; restored on resume so each session can carry
    *  its own model independent of the global default (per-session model selection). */
   model?: string;
+  /** Latest CLI-owned conversation, folded from append-only metadata records. */
+  agy?: { conversationId: string; messageCount: number };
   /** Unsent input-box draft at last save, restored into the prompt on `/resume`
    *  (gajae-code parity: an in-progress cursor survives a quit + resume instead
    *  of being silently lost). Absent/empty when there was nothing to restore. */
@@ -135,6 +137,26 @@ export async function appendMessages(
   await fs.appendFile(file, chunk, "utf8");
 }
 
+function isAgySessionState(value: unknown): value is NonNullable<SessionHeader["agy"]> {
+  if (!value || typeof value !== "object") return false;
+  const state = value as Record<string, unknown>;
+  return typeof state.conversationId === "string" && state.conversationId.length > 0
+    && state.conversationId.length <= 1024 && !/[\s\u0000-\u001f\u007f]/.test(state.conversationId)
+    && typeof state.messageCount === "number" && Number.isSafeInteger(state.messageCount) && state.messageCount >= 0;
+}
+
+/** Append metadata instead of rewriting a header while transcript messages arrive. */
+export async function appendAgySession(
+  id: string,
+  state: NonNullable<SessionHeader["agy"]>,
+  cwd = process.cwd(),
+): Promise<void> {
+  if (!isAgySessionState(state)) throw new Error("Invalid official CLI session metadata");
+  await fs.appendFile(sessionPath(id, cwd), JSON.stringify({
+    type: "agy_session", timestamp: new Date().toISOString(), state,
+  }) + "\n", "utf8");
+}
+
 export async function appendCompaction(
   id: string,
   seq: number,
@@ -185,6 +207,9 @@ export async function loadSession(
           rawMessages.push(entry.message);
         } else if (entry.type === "compaction") {
           compactions.push(entry as CompactionEntry);
+        } else if (entry.type === "agy_session" && header) {
+          if (isAgySessionState(entry.state)) header.agy = entry.state;
+          else delete header.agy;
         }
       }
     } catch (err) {

package/src/agent/task-tool.ts

@@ -433,6 +433,10 @@ export async function runSubagentOnce(
   // "false positive -> try a different model" design this implements.
   const safetyFallbackAvailable = (): boolean => safetyFallbackCandidates().length > 0;
 
+  // Failover (reroute to an equivalent model) is part of routing: it only runs when
+  // `routing.enabled` is on. `launch.ts` passes the parent session's EFFECTIVE state
+  // (`/route on|off` override ?? config) in `config.routing.enabled`.
+  const failoverEnabled = !!opts.config.routing?.enabled;
   let activeModel = initialModel;
   emit({ role: role.id, kind: "start", detail: taskText, maxSteps, model: activeModel });
   const runOnce = () => {
@@ -448,8 +452,7 @@ export async function runSubagentOnce(
       signal,
       steer,
       tools: subagentToolset(role),
-      rateLimitFallbackAvailable,
-      safetyFallbackAvailable,
+      ...(failoverEnabled ? { rateLimitFallbackAvailable, safetyFallbackAvailable } : {}),
       events: {
         onStep: n => { currentStep = n; },
         // Live reasoning preview (native extended-thinking models only — the JSON-protocol
@@ -494,7 +497,10 @@ export async function runSubagentOnce(
   };
 
   let result = await runOnce();
-  for (let attempt = 0; attempt < MAX_SUBAGENT_REROUTES; attempt++) {
+  // `routing.enabled` off = the model is FIXED: no failover reroute at all (the
+  // engine bail predicates above are withheld too, so a 429 rides its normal
+  // backoff ladder instead of bailing early with nowhere to go).
+  for (let attempt = 0; failoverEnabled && attempt < MAX_SUBAGENT_REROUTES; attempt++) {
     const rateLimited = !result.done && isRateLimitError(new Error(result.doneReason ?? ""));
     const safetyBail = !result.done && !rateLimited && isSafetyFallbackBail(result.doneReason);
     if (!rateLimited && !safetyBail) break;

package/src/ai/model-cache.ts

@@ -100,6 +100,7 @@ export function normalizeCacheEntries(raw: unknown): CachedProviderModels[] {
     const row = entry as Partial<CachedProviderModels>;
     if (!row || typeof row.provider !== "string" || !Array.isArray(row.models)) continue;
     const provider = row.provider as ProviderName;
+    if (provider === "agy") continue;
     const source: ModelCacheSource =
       row.source === "oauth" || row.source === "api_key" || row.source === "keyless" || row.source === "none" ? row.source : "none";
     const baseUrl = typeof row.baseUrl === "string" ? row.baseUrl.replace(/\/+$/, "") : undefined;
@@ -150,7 +151,7 @@ export function isModelCacheStale(cache: ModelCacheFile | null, now = Date.now()
  */
 export function mergeCacheEntries(
   previous: readonly CachedProviderModels[],
-  results: readonly { provider: ProviderName; models: readonly string[]; ok: boolean; source?: ModelCacheSource; baseUrl?: string; accountId?: string; fallback?: boolean }[],
+  results: readonly { provider: ProviderName; models: readonly string[]; ok: boolean; source?: ModelCacheSource | "cli_session"; baseUrl?: string; accountId?: string; fallback?: boolean }[],
 ): CachedProviderModels[] {
   const byKey = new Map<string, CachedProviderModels>();
   const isScopedOAuth = (provider: ProviderName, source: ModelCacheSource): boolean =>
@@ -159,10 +160,12 @@ export function mergeCacheEntries(
     `${provider}\u0000${baseUrl?.replace(/\/+$/, "") ?? ""}\u0000${isScopedOAuth(provider, source ?? "none") ? accountId ?? "" : ""}\u0000${provider === "openai" || provider === "antigravity" ? source ?? "none" : ""}`;
   for (const entry of previous) {
     const scoped = isScopedOAuth(entry.provider, entry.source);
+    if (entry.provider === "agy") continue;
     if ((scoped && !entry.accountId) || (entry.provider === "antigravity" && entry.source !== "oauth")) continue;
     byKey.set(keyOf(entry.provider, entry.baseUrl, entry.accountId, entry.source), entry);
   }
   for (const result of results) {
+    if (result.provider === "agy" || result.source === "cli_session") continue;
     const source: ModelCacheSource = result.source ?? "none";
     const scoped = isScopedOAuth(result.provider, source);
     const isAntigravity = result.provider === "antigravity";
@@ -183,13 +186,14 @@ export function mergeCacheEntries(
 
 /** Persist discovery results (best-effort; never throws, never blocks a turn). */
 export async function writeModelCache(
-  results: readonly { provider: ProviderName; models: readonly string[]; ok: boolean; source?: ModelCacheSource; baseUrl?: string; accountId?: string; fallback?: boolean }[],
+  results: readonly { provider: ProviderName; models: readonly string[]; ok: boolean; source?: ModelCacheSource | "cli_session"; baseUrl?: string; accountId?: string; fallback?: boolean }[],
 ): Promise<void> {
   // Same hermeticity rule as saveGlobalConfig: a test run may only write into an
   // explicitly sandboxed JEO_CONFIG_DIR, never the developer's real ~/.jeo.
   if (process.env.NODE_ENV === "test" && !jeoEnv("CONFIG_DIR")) return;
   // A failed/fallback-only refresh must not make an old snapshot appear fresh.
   const hasFreshResult = results.some(result => {
+    if (result.provider === "agy" || result.source === "cli_session") return false;
     if (!result.ok || result.fallback) return false;
     if (result.provider === "antigravity") return result.source === "oauth" && !!result.accountId?.trim();
     if (result.provider === "openai") return result.models.length > 0 || !(result.source === "oauth" && !result.accountId?.trim());
@@ -220,6 +224,7 @@ export function applyCachedModels(cache: ModelCacheFile | null, openAIOauthAccou
   if (!cache) return 0;
   let applied = 0;
   for (const entry of cache.providers) {
+    if (entry.provider === "agy") continue;
     const isOpenAIOAuth = entry.provider === "openai" && entry.source === "oauth";
     const isAntigravityOAuth = entry.provider === "antigravity" && entry.source === "oauth";
     if (isOpenAIOAuth && (!openAIScope || entry.accountId !== openAIScope)) continue;

package/src/ai/model-catalog-compat.ts

@@ -55,7 +55,11 @@ export function findCatalogEntry(id: string): ModelCatalogEntry | undefined {
   const direct = findCatalogModel(id);
   if (direct) return adapt(direct);
   const n = normalizeModelId(id);
-  const hit = MODEL_CATALOG.find(m => normalizeModelId(m.canonical) === n || normalizeModelId(m.providerModel) === n);
+  const hit = MODEL_CATALOG.find(m =>
+    normalizeModelId(m.canonical) === n
+    || normalizeModelId(`${m.provider}/${m.providerModel}`) === n
+    || (!m.canonical.startsWith(`${m.provider}/`) && normalizeModelId(m.providerModel) === n),
+  );
   return hit ? adapt(hit) : undefined;
 }