talon-agent 5.2.2 → 5.4.0

package/src/backend/agy/process/child.ts

@@ -0,0 +1,378 @@
+/**
+ * The per-chat Antigravity child process.
+ *
+ * agy has no SDK: the integration surface is one long-lived
+ * `agy --input-format stream-json` process per chat, fed one
+ * `{"event":"user",...}` line per turn on stdin and read line-by-line
+ * on stdout. That shape is deliberate — the CLI's own docs call it
+ * "significantly faster than running repeated commands with
+ * `--continue`" because the process starts once and the conversation
+ * stays warm.
+ *
+ * What this module owns:
+ *
+ *   - Spawning with the right flag set, cwd and `--conversation` for a
+ *     resume, and tearing the child down through a
+ *     SIGTERM → grace → SIGKILL ladder that never leaves a zombie.
+ *   - Serialising turns: exactly one may be in flight. The dispatcher
+ *     already serialises per chat, so a second concurrent turn is a
+ *     bug, not a queue to build — it is rejected loudly.
+ *   - Settling a turn on its `result` event, or on the child dying,
+ *     whichever comes first.
+ *   - Idle reaping, and the terminator kill: a turn in progress cannot
+ *     be cancelled through the protocol, so `end_turn` kills the child
+ *     and the next turn respawns it with `--conversation <id>`.
+ *   - A stderr ring buffer, because that is the ONLY place the CLI
+ *     reports `authentication required` and permission notices.
+ */
+
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { log, logWarn } from "../../../util/log.js";
+import {
+  parseAgyLine,
+  type AgyEvent,
+  type AgyResult,
+  type AgyStepUpdate,
+} from "../events.js";
+import type { AgyEffort } from "../effort.js";
+import {
+  AGY_BASE_ARGS,
+  AGY_IDLE_REAP_MS,
+  AGY_KILL_GRACE_MS,
+} from "../constants.js";
+
+/** How much stderr to retain for diagnostics. */
+const STDERR_TAIL_CHARS = 4000;
+
+/** Spawn shape for one child. Two children differing here can't be reused. */
+export interface AgySpawnSpec {
+  binary: string;
+  cwd: string;
+  model: string;
+  effort?: AgyEffort;
+  /** Extra roots the agent may touch, passed as `--add-dir`. */
+  addDirs?: readonly string[];
+  /** Resume this conversation instead of starting a new one. */
+  conversationId?: string;
+  env?: NodeJS.ProcessEnv;
+  /** Idle TTL before the child is reaped. Defaults to [AGY_IDLE_REAP_MS]. */
+  idleMs?: number;
+}
+
+export interface AgyTurnHandlers {
+  onStep?: (step: AgyStepUpdate) => void;
+  onEvent?: (event: AgyEvent) => void;
+}
+
+/**
+ * The close a terminator (or a user interrupt) produces. The message
+ * contains "abort" on purpose: every backend's close-out path — and
+ * `handler/message.ts: isTerminatorAbort` here — recognises the
+ * expected end-of-turn close by that word, so a killed-on-purpose turn
+ * settles as a normal completion rather than an error with a retry.
+ */
+export class AgyTurnAborted extends Error {
+  constructor(reason: string) {
+    super(`agy turn aborted (${reason})`);
+    this.name = "AgyTurnAborted";
+  }
+}
+
+/** The child died — with whatever stderr said about why. */
+class AgyProcessExited extends Error {
+  constructor(
+    message: string,
+    readonly code: number | null,
+    readonly stderr: string,
+  ) {
+    super(message);
+    this.name = "AgyProcessExited";
+  }
+}
+
+/** Build the argv for one child, in a stable, assertable order. */
+export function buildAgyArgs(spec: AgySpawnSpec): string[] {
+  const args = [...AGY_BASE_ARGS, "--model", spec.model];
+  if (spec.effort) args.push("--effort", spec.effort);
+  if (spec.conversationId) args.push("--conversation", spec.conversationId);
+  for (const dir of spec.addDirs ?? []) args.push("--add-dir", dir);
+  return args;
+}
+
+/** True when two specs describe the same process and one can be reused. */
+function sameSpec(a: AgySpawnSpec, b: AgySpawnSpec): boolean {
+  return (
+    a.binary === b.binary &&
+    a.cwd === b.cwd &&
+    a.model === b.model &&
+    a.effort === b.effort &&
+    (a.addDirs ?? []).join("\u0000") === (b.addDirs ?? []).join("\u0000")
+  );
+}
+
+interface PendingTurn {
+  resolve: (result: AgyResult) => void;
+  reject: (err: unknown) => void;
+  handlers: AgyTurnHandlers;
+}
+
+export class AgyChild {
+  readonly spec: AgySpawnSpec;
+  private readonly label: string;
+  private proc: ChildProcessWithoutNullStreams | null = null;
+  private stdoutBuf = "";
+  private stderrTail = "";
+  private pending: PendingTurn | null = null;
+  private idleTimer: NodeJS.Timeout | null = null;
+  private exited = false;
+  /** Conversation id announced by `init` / carried on every event. */
+  conversationId: string | undefined;
+  /** Tool names the CLI advertised in `init`. */
+  tools: string[] = [];
+
+  constructor(label: string, spec: AgySpawnSpec) {
+    this.label = label;
+    this.spec = spec;
+    this.conversationId = spec.conversationId;
+  }
+
+  get alive(): boolean {
+    return this.proc !== null && !this.exited;
+  }
+
+  get stderrSnapshot(): string {
+    return this.stderrTail;
+  }
+
+  /** Spawn the process. Idempotent — a live child is left alone. */
+  start(): void {
+    if (this.alive) return;
+    const args = buildAgyArgs(this.spec);
+    log(
+      "agent",
+      `[${this.label}] agy spawn: ${this.spec.binary} ${args.join(" ")}`,
+    );
+    const proc = spawn(this.spec.binary, args, {
+      cwd: this.spec.cwd,
+      env: this.spec.env ?? process.env,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    this.proc = proc;
+    this.exited = false;
+    proc.stdout.setEncoding("utf-8");
+    proc.stderr.setEncoding("utf-8");
+    proc.stdout.on("data", (chunk: string) => this.onStdout(chunk));
+    proc.stderr.on("data", (chunk: string) => this.onStderr(chunk));
+    proc.on("error", (err) => this.onExit(null, err.message));
+    proc.on("close", (code) => this.onExit(code, null));
+    this.armIdleTimer();
+  }
+
+  /**
+   * Run one turn. Resolves with the turn's `result` event; rejects
+   * with [AgyTurnAborted] when the child was killed mid-turn and
+   * [AgyProcessExited] when it died on its own.
+   */
+  runTurn(prompt: string, handlers: AgyTurnHandlers = {}): Promise<AgyResult> {
+    if (this.pending) {
+      return Promise.reject(
+        new Error(
+          `agy: a turn is already in flight for ${this.label} — ` +
+            `the dispatcher is expected to serialise per chat`,
+        ),
+      );
+    }
+    this.start();
+    const proc = this.proc;
+    if (!proc) return Promise.reject(new Error("agy: child failed to spawn"));
+    this.clearIdleTimer();
+
+    return new Promise<AgyResult>((resolve, reject) => {
+      this.pending = { resolve, reject, handlers };
+      const line = `${JSON.stringify({
+        event: "user",
+        message: { content: prompt },
+      })}\n`;
+      proc.stdin.write(line, (err) => {
+        if (err) this.settleReject(err);
+      });
+    });
+  }
+
+  /**
+   * Kill the child. Any in-flight turn rejects with [AgyTurnAborted],
+   * carrying `reason` so the handler can tell a terminator kill from a
+   * reset or an idle reap.
+   */
+  kill(reason: string): void {
+    this.clearIdleTimer();
+    const proc = this.proc;
+    this.settleReject(new AgyTurnAborted(reason));
+    if (!proc || this.exited) {
+      this.proc = null;
+      return;
+    }
+    log("agent", `[${this.label}] agy child kill (${reason})`);
+    try {
+      proc.stdin.end();
+    } catch {
+      /* already closed */
+    }
+    try {
+      proc.kill("SIGTERM");
+    } catch {
+      /* already gone */
+    }
+    const timer = setTimeout(() => {
+      try {
+        if (!this.exited) proc.kill("SIGKILL");
+      } catch {
+        /* already gone */
+      }
+    }, AGY_KILL_GRACE_MS);
+    timer.unref();
+    this.proc = null;
+  }
+
+  // ── Internals ─────────────────────────────────────────────────────────────
+
+  private onStdout(chunk: string): void {
+    this.stdoutBuf += chunk;
+    let nl = this.stdoutBuf.indexOf("\n");
+    while (nl >= 0) {
+      const line = this.stdoutBuf.slice(0, nl);
+      this.stdoutBuf = this.stdoutBuf.slice(nl + 1);
+      this.onLine(line);
+      nl = this.stdoutBuf.indexOf("\n");
+    }
+  }
+
+  private onLine(line: string): void {
+    const event = parseAgyLine(line);
+    if (!event) return;
+    const pending = this.pending;
+    if (event.event === "init") {
+      this.conversationId = event.conversation_id ?? this.conversationId;
+      this.tools = event.init?.tools ?? [];
+    } else if (event.event === "step_update") {
+      const step = event.step_update;
+      if (step?.conversation_id) this.conversationId = step.conversation_id;
+      if (step) pending?.handlers.onStep?.(step);
+    }
+    pending?.handlers.onEvent?.(event);
+    if (event.event === "result") {
+      this.conversationId =
+        event.result?.conversation_id ?? this.conversationId;
+      this.settleResolve(event.result ?? {});
+    }
+  }
+
+  private onStderr(chunk: string): void {
+    this.stderrTail = (this.stderrTail + chunk).slice(-STDERR_TAIL_CHARS);
+  }
+
+  private onExit(code: number | null, error: string | null): void {
+    if (this.exited) return;
+    this.exited = true;
+    this.proc = null;
+    this.clearIdleTimer();
+    if (!this.pending) return;
+    const detail =
+      error ?? this.stderrTail.trim().split("\n").slice(-4).join("\n");
+    this.settleReject(
+      new AgyProcessExited(
+        `agy exited (code ${code ?? "n/a"})${detail ? `: ${detail}` : ""}`,
+        code,
+        this.stderrTail,
+      ),
+    );
+  }
+
+  private settleResolve(result: AgyResult): void {
+    const pending = this.pending;
+    this.pending = null;
+    this.armIdleTimer();
+    pending?.resolve(result);
+  }
+
+  private settleReject(err: unknown): void {
+    const pending = this.pending;
+    if (!pending) return;
+    this.pending = null;
+    pending.reject(err);
+  }
+
+  private armIdleTimer(): void {
+    this.clearIdleTimer();
+    const ms = this.spec.idleMs ?? AGY_IDLE_REAP_MS;
+    if (ms <= 0) return;
+    this.idleTimer = setTimeout(() => {
+      logWarn("agent", `[${this.label}] agy child idle for ${ms}ms — reaping`);
+      this.onIdle?.(this.label);
+      this.kill("idle");
+    }, ms);
+    this.idleTimer.unref();
+  }
+
+  private clearIdleTimer(): void {
+    if (!this.idleTimer) return;
+    clearTimeout(this.idleTimer);
+    this.idleTimer = null;
+  }
+
+  /** Set by the pool so an idle reap can also drop the MCP entries. */
+  onIdle?: (label: string) => void;
+}
+
+// ── Pool ────────────────────────────────────────────────────────────────────
+
+const children = new Map<string, AgyChild>();
+
+/**
+ * The live child for a chat, spawning one if needed.
+ *
+ * A child whose spec has drifted (model or effort changed, workspace
+ * moved) is killed and replaced — those are spawn-time flags with no
+ * runtime equivalent. The replacement inherits the conversation id, so
+ * the conversation survives a model switch.
+ */
+export function ensureChild(chatId: string, spec: AgySpawnSpec): AgyChild {
+  const existing = children.get(chatId);
+  if (existing?.alive && sameSpec(existing.spec, spec)) return existing;
+  if (existing) {
+    const carried = existing.conversationId ?? spec.conversationId;
+    existing.kill(existing.alive ? "respawn" : "dead");
+    children.delete(chatId);
+    spec = { ...spec, conversationId: carried };
+  }
+  const child = new AgyChild(chatId, spec);
+  children.set(chatId, child);
+  child.start();
+  return child;
+}
+
+/** The child for a chat, if one exists (alive or not). */
+export function getChild(chatId: string): AgyChild | undefined {
+  return children.get(chatId);
+}
+
+/** Kill and forget a chat's child. Returns true when one was running. */
+export function killChild(chatId: string, reason: string): boolean {
+  const child = children.get(chatId);
+  if (!child) return false;
+  child.kill(reason);
+  children.delete(chatId);
+  return true;
+}
+
+/** Kill every child — daemon shutdown and the factory cleanup hook. */
+export function killAllChildren(reason: string): void {
+  // Snapshot the keys: killChild mutates the map as we go.
+  const ids = childChatIds();
+  for (const chatId of ids) killChild(chatId, reason);
+}
+
+/** Chat ids with a registered child. Test + diagnostics helper. */
+export function childChatIds(): string[] {
+  return [...children.keys()];
+}

package/src/backend/agy/process/orphans.ts

@@ -0,0 +1,106 @@
+/**
+ * Orphan subprocess eviction for the Antigravity backend.
+ *
+ * A one-shot run spawns a real `agy` process. Abort normally kills it,
+ * but a child wedged in a syscall — or one whose parent lost the
+ * handle across a daemon restart — outlives the run and holds its
+ * workspace and memory. The Claude SDK backend solves this by
+ * sweeping `/proc` for processes tagged with the run's chat id; the
+ * same approach works here, matching on the argv instead of the
+ * environment because agy takes its context from flags, not env.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import { log } from "../../../util/log.js";
+import { AGY_KILL_GRACE_MS } from "../constants.js";
+import { childChatIds, getChild } from "./child.js";
+
+/**
+ * Kill stray `agy` processes belonging to `contextLabel`.
+ *
+ * Two passes: the children this process still tracks (authoritative),
+ * then a `/proc` argv sweep for anything that escaped the pool. Linux
+ * only — `/proc` is where the argv lives; elsewhere the tracked pass
+ * still runs and the sweep is a no-op.
+ */
+export async function evictOrphanSubprocesses(contextLabel: string): Promise<{
+  found: number;
+  termed: number;
+  killed: number;
+}> {
+  const result = { found: 0, termed: 0, killed: 0 };
+
+  for (const chatId of childChatIds()) {
+    if (chatId !== contextLabel) continue;
+    const child = getChild(chatId);
+    if (!child?.alive) continue;
+    result.found++;
+    result.termed++;
+    child.kill("orphan-sweep");
+  }
+
+  const matched = await findOrphanPids(contextLabel);
+  result.found += matched.length;
+  for (const pid of matched) {
+    try {
+      process.kill(pid, "SIGTERM");
+      result.termed++;
+    } catch {
+      /* ESRCH / EPERM — nothing to do */
+    }
+  }
+  if (matched.length > 0) {
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, AGY_KILL_GRACE_MS);
+      timer.unref();
+    });
+    for (const pid of matched) {
+      try {
+        process.kill(pid, 0);
+        process.kill(pid, "SIGKILL");
+        result.killed++;
+      } catch {
+        /* already gone */
+      }
+    }
+  }
+
+  if (result.found > 0) {
+    log(
+      "heartbeat",
+      `agy subprocess sweep (${contextLabel}): found=${result.found} ` +
+        `termed=${result.termed} killed=${result.killed}`,
+    );
+  }
+  return result;
+}
+
+/** `/proc` pids whose argv is an `agy` run carrying `contextLabel`. */
+async function findOrphanPids(contextLabel: string): Promise<number[]> {
+  if (process.platform !== "linux") return [];
+  let entries: string[];
+  try {
+    entries = await readdir("/proc");
+  } catch {
+    return [];
+  }
+  const matched: number[] = [];
+  for (const entry of entries) {
+    const pid = Number(entry);
+    if (!Number.isInteger(pid) || pid === process.pid) continue;
+    try {
+      const argv = (await readFile(`/proc/${pid}/cmdline`, "utf-8")).split(
+        "\0",
+      );
+      // Exact-token matching, never a substring scan: this code can
+      // SIGKILL, so a chat id that happens to appear inside an
+      // unrelated path must not select a victim.
+      if (!argv.some((arg) => arg === "agy" || arg.endsWith("/agy"))) continue;
+      if (argv.includes(contextLabel)) matched.push(pid);
+    } catch {
+      // Exited between readdir and readFile, or not ours. Skip.
+      continue;
+    }
+  }
+  return matched;
+}

package/src/backend/agy/sessions.ts

@@ -0,0 +1,90 @@
+/**
+ * Session lifecycle for the Antigravity backend: reset, warm, and the
+ * hot MCP refresh.
+ *
+ * All three are variations on the same two facts: the child reads its
+ * MCP servers once at spawn, and the conversation lives in agy's own
+ * store keyed by `conversation_id`. So "change the tools" and "start
+ * fresh" both come down to rewriting the config file and respawning.
+ */
+
+import { log } from "../../util/log.js";
+import { dirs } from "../../util/paths.js";
+import { getSession } from "../../storage/sessions.js";
+import { getChatSettings } from "../../storage/chat-settings.js";
+import { getState, agyBinary } from "./state.js";
+import { registerMcpForChat, unregisterMcpForChat } from "./mcp/register.js";
+import { ensureChild, killChild } from "./process/child.js";
+import { toAgyEffort } from "./effort.js";
+import { getDefaultModelId } from "./models.js";
+
+/**
+ * Drop everything this chat holds: kill the child, remove its MCP
+ * entries (and their schema snapshots), and forget the cached usage.
+ * The stored conversation id is cleared by the dispatcher's own
+ * `storage/sessions.ts: resetSession` call.
+ */
+export function resetChat(chatId: string): void {
+  const conversationId = getSession(chatId).sessionId;
+  killChild(chatId, "reset");
+  unregisterMcpForChat(chatId);
+  // The snapshot is filed under both ids (see `settleUsage`).
+  getState().lastUsage.delete(chatId);
+  if (conversationId) getState().lastUsage.delete(conversationId);
+  log("agent", `[${chatId}] agy session reset`);
+}
+
+/**
+ * Pre-spawn the child and register its MCP servers so the first reply
+ * after a `/reset` doesn't serially pay CLI startup plus tool
+ * registration. Best-effort: a warm-up that throws must not surface
+ * as a failed reset.
+ */
+export async function warmSession(chatId: string): Promise<void> {
+  const config = getState().config;
+  if (!config) return;
+  try {
+    registerMcpForChat(chatId);
+    const workspace = config.workspace || dirs.workspace;
+    const settings = getChatSettings(chatId);
+    const session = getSession(chatId);
+    ensureChild(chatId, {
+      binary: agyBinary(config.agyBinary),
+      cwd: workspace,
+      model: settings.model ?? config.model ?? getDefaultModelId(),
+      effort: toAgyEffort(settings.effort),
+      addDirs: [workspace],
+      ...(session.sessionId ? { conversationId: session.sessionId } : {}),
+    });
+    log("agent", `[${chatId}] agy session warmed`);
+  } catch (err) {
+    log(
+      "agent",
+      `[${chatId}] agy warm-up skipped: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}
+
+/**
+ * Re-derive the chat's MCP entries from the live plugin registry and
+ * respawn the child so it picks them up. agy snapshots each server's
+ * tool schemas at registration time and reads the server list once at
+ * process start, so a running child cannot learn a new tool — the
+ * respawn is the refresh.
+ */
+export async function refreshTools(chatId: string): Promise<{
+  added: string[];
+  removed: string[];
+  errors: Record<string, string>;
+}> {
+  const { added, removed } = registerMcpForChat(chatId);
+  const respawned = killChild(chatId, "tool-refresh");
+  log(
+    "agent",
+    `[${chatId}] agy tools refreshed: +${added.length} -${removed.length}` +
+      `${respawned ? " (child respawns on next turn)" : ""}`,
+  );
+  return { added, removed, errors: {} };
+}

package/src/backend/agy/state.ts

@@ -0,0 +1,77 @@
+/**
+ * Per-process state for the Antigravity backend.
+ *
+ * Only the bindings captured at `init` (config, gateway-port resolver,
+ * owning frontend) plus the per-chat usage the `/status` snapshot
+ * reads. Two neighbours own the rest deliberately: `models.ts` holds
+ * its own catalog cache (so the catalog can be read by `talon doctor`
+ * without a live backend), and `process.ts` owns the per-chat children
+ * (they have a spawn / idle-reap / kill lifecycle that does not belong
+ * in a bag of fields).
+ */
+
+import type { TalonConfig } from "../../core/config/index.js";
+import type { FrontendName } from "../../core/agent-runtime/backend-registry.js";
+
+/** What `getSessionSnapshot` answers with, per chat. */
+export interface AgySessionUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheRead: number;
+  cacheWrite: number;
+  contextModelId?: string;
+}
+
+export interface AgyState {
+  config: TalonConfig | null;
+  gatewayPortFn: () => number;
+  frontendName: FrontendName;
+  /**
+   * System prompt for the next NEW conversation, when plugin
+   * hot-reload pushed one through `control.updateSystemPrompt`.
+   * Resumed conversations keep the prompt frozen into their history —
+   * same semantics as codex.
+   */
+  systemPromptOverride: string | null;
+  /** Last cumulative `result.usage` seen per chat. */
+  lastUsage: Map<string, AgySessionUsage>;
+}
+
+const state: AgyState = {
+  config: null,
+  gatewayPortFn: () => 19876,
+  frontendName: "telegram",
+  systemPromptOverride: null,
+  lastUsage: new Map<string, AgySessionUsage>(),
+};
+
+/** Accessor for the shared state object. */
+export function getState(): AgyState {
+  return state;
+}
+
+/** The daemon's loopback bridge URL, as the MCP hub serves it. */
+export function bridgeUrl(): string {
+  return `http://127.0.0.1:${state.gatewayPortFn()}`;
+}
+
+/**
+ * Path to the `agy` executable: config `agyBinary`, else the
+ * `AGY_BINARY` env var, else bare `agy` off PATH. Env wins over config
+ * so a test harness can point at a stub without rewriting the
+ * persisted config — the same precedence `codexBinary` uses.
+ */
+export function agyBinary(configBinary?: string): string {
+  return (
+    process.env.AGY_BINARY || configBinary || state.config?.agyBinary || "agy"
+  );
+}
+
+/** Reset everything — test isolation helper and `cleanup` hook. */
+export function resetState(): void {
+  state.config = null;
+  state.gatewayPortFn = () => 19876;
+  state.frontendName = "telegram";
+  state.systemPromptOverride = null;
+  state.lastUsage.clear();
+}

package/src/backend/builtins.ts

@@ -31,5 +31,6 @@ export async function loadBuiltinBackends(): Promise<void> {
       registerBackend(createRemoteBackendFactory(profile));
   }
   await import("./codex/factory.js");
+  await import("./agy/factory.js");
   await import("./openai-agents/factory.js");
 }

package/src/backend/codex/mcp-config.ts

@@ -29,7 +29,7 @@ import {
   pluginHubUrl,
   hubPluginServerNames,
 } from "../../core/mcp-hub/index.js";
-import type { ToolExclusionConfig } from "../../core/tools/ops/mcp-env.js";
+import type { ToolExclusionConfig } from "../../core/tools/mcp-env.js";
 import { frontendsForChat } from "../runtime/frontends.js";
 
 /**

package/src/backend/openai-agents/mcp-pool.ts

@@ -30,7 +30,7 @@ import {
   pluginHubUrl,
   hubPluginServerNames,
 } from "../../core/mcp-hub/index.js";
-import type { ToolExclusionConfig } from "../../core/tools/ops/mcp-env.js";
+import type { ToolExclusionConfig } from "../../core/tools/mcp-env.js";
 import { frontendsForChat } from "../runtime/frontends.js";
 import { log, logWarn } from "../../util/log.js";
 

package/src/backend/runtime/index.ts

@@ -37,7 +37,7 @@
  *   - SDK-specific event types — those live in each backend.
  *   - Session storage — that's `src/storage/sessions.ts`.
  *   - MCP server registration — backend-specific transport details
- *     (the spawn/env contract they share is `core/tools/ops/mcp-env.ts`).
+ *     (the spawn/env contract they share is `core/tools/mcp-env.ts`).
  */
 
 export { captureDeliveredText } from "./turn/delivered-text.js";