talon-agent 5.2.2 → 5.4.0

package/README.md

@@ -8,11 +8,11 @@
 [![Bun](https://img.shields.io/badge/bun-1.3%2B-000000?logo=bun&logoColor=white)](https://bun.sh)
 [![TypeScript](https://img.shields.io/badge/TypeScript-7.0-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Frontends](https://img.shields.io/badge/frontends-Telegram_%7C_WhatsApp_%7C_Discord_%7C_Teams_%7C_Terminal_%7C_App-25D366)](#frontends)
-[![Backends](https://img.shields.io/badge/backends-Claude_%7C_Kilo_%7C_OpenCode_%7C_Codex_%7C_OpenAI_Agents-D97706)](#backends)
+[![Backends](https://img.shields.io/badge/backends-Claude_%7C_Kilo_%7C_OpenCode_%7C_Codex_%7C_Antigravity_%7C_OpenAI_Agents-D97706)](#backends)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![CI](https://github.com/dylanneve1/talon/actions/workflows/ci.yml/badge.svg)](https://github.com/dylanneve1/talon/actions/workflows/ci.yml)
 
-Multi-platform agentic AI harness. Runs on **Telegram**, **WhatsApp**, **Discord**, **Microsoft Teams**, the **Terminal**, and a **cross-platform Desktop/Mobile companion app** (Flutter), with a pluggable backend (**Claude Agent SDK**, **Kilo**, **OpenCode**, **Codex**, or **OpenAI Agents**) and full tool access through MCP.
+Multi-platform agentic AI harness. Runs on **Telegram**, **WhatsApp**, **Discord**, **Microsoft Teams**, the **Terminal**, and a **cross-platform Desktop/Mobile companion app** (Flutter), with a pluggable backend (**Claude Agent SDK**, **Kilo**, **OpenCode**, **Codex**, **Antigravity**, or **OpenAI Agents**) and full tool access through MCP.
 
 ---
 
@@ -21,7 +21,7 @@ Multi-platform agentic AI harness. Runs on **Telegram**, **WhatsApp**, **Discord
 |                       |                                                                                                                                              |
 | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Multi-frontend**    | Telegram (grammY + GramJS userbot), WhatsApp (Baileys multi-device), Discord (discord.js), Microsoft Teams (Bot Framework), Terminal with live tool visibility, and a **Desktop/Mobile app** (Flutter) over a local/remote bridge — one or several at once, see [Frontends](#frontends) |
-| **Pluggable backend** | Claude Agent SDK, Kilo, OpenCode, Codex, OpenAI Agents — selectable per-process via `backend` config. Streaming, model fallback, context-overflow recovery. |
+| **Pluggable backend** | Claude Agent SDK, Kilo, OpenCode, Codex, Antigravity, OpenAI Agents — selectable per-process via `backend` config. Streaming, model fallback, context-overflow recovery. |
 | **MCP tools**         | Messaging, media, history, search, web fetch, cron jobs, triggers, goals, stickers, file system, admin controls                              |
 | **Plugins**           | Hot-reloadable plugin system with `talon plugin install/enable/disable` (npm, git, or local sources). Built-in: GitHub, MemPalace, Playwright, Brave Search |
 | **Background agents** | Heartbeat (hourly by default — advances goals, proactively messages when something matters) and Dream (memory consolidation + diary)         |
@@ -63,6 +63,7 @@ npx talon chat        # terminal chat mode
   - `kilo` backend: nothing extra — `@kilocode/sdk` spawns a local server. Free models are accessible without auth; routed models use Kilo's own credentials.
   - `opencode` backend: nothing extra — `@opencode-ai/sdk` spawns a local server.
   - `codex` backend: install the `codex` CLI (`npm i -g @openai/codex`) and authenticate with `codex login`, `CODEX_API_KEY`, `TALON_CODEX_KEY`, or `codexApiKey`. `OPENAI_API_KEY` is used only as a fallback when no Codex login exists.
+  - `agy` backend: install Google's Antigravity CLI so `agy` is on `PATH` (or set `agyBinary` / `AGY_BINARY`), then run `agy` **once interactively** on the host and complete the Google sign-in. There is no API key — headless runs reuse the cached OAuth credentials under `~/.gemini/antigravity-cli/`.
 
 ### Standalone binary
 
@@ -137,6 +138,7 @@ index.ts                    Composition root
   |   +-- kilo/             Kilo HTTP server backend (streaming via SSE)
   |   +-- opencode/         OpenCode HTTP server backend
   |   +-- codex/            Codex CLI backend (`@openai/codex-sdk`)
+  |   +-- agy/              Antigravity CLI backend (headless stream-json)
   |   +-- openai-agents/    OpenAI Agents SDK backend (Responses API)
   |
   +-- frontend/
@@ -157,7 +159,7 @@ index.ts                    Composition root
   +-- util/                 Config, logging, workspace, paths, time, runtime
 ```
 
-**Dependency rule:** `core/` imports nothing from `frontend/` or `backend/`. Frontends and backends depend on core types, never on each other. All five backends (Claude SDK, Kilo, OpenCode, Codex, OpenAI Agents) implement the same `Backend` capability interface from `core/agent-runtime/capabilities.ts`. Frontends mirror this: each implements the `Frontend` contract from `core/frontend-runtime/capabilities.ts` and self-registers in the frontend registry (identity + chat-id routing in a descriptor, lazy `create` in a per-frontend `factory.ts`) — see [docs/frontends.md](docs/frontends.md). Kilo and OpenCode additionally share the `remote-server/` infrastructure because they wrap forks of the same upstream HTTP agent server.
+**Dependency rule:** `core/` imports nothing from `frontend/` or `backend/`. Frontends and backends depend on core types, never on each other. All six backends (Claude SDK, Kilo, OpenCode, Codex, Antigravity, OpenAI Agents) implement the same `Backend` capability interface from `core/agent-runtime/capabilities.ts`. Frontends mirror this: each implements the `Frontend` contract from `core/frontend-runtime/capabilities.ts` and self-registers in the frontend registry (identity + chat-id routing in a descriptor, lazy `create` in a per-frontend `factory.ts`) — see [docs/frontends.md](docs/frontends.md). Kilo and OpenCode additionally share the `remote-server/` infrastructure because they wrap forks of the same upstream HTTP agent server.
 
 **Prompts:** everything the model reads at session start is assembled by `core/prompt/` from the files in `prompts/` — see [prompts/README.md](prompts/README.md) for the assembly order, file ownership (user-editable vs package-owned templates), and the per-backend delivery contracts.
 
@@ -221,9 +223,10 @@ Select via the `backend` field in `~/.talon/config.json`. All backends implement
 | Kilo       | `"kilo"`        | Local HTTP server via `@kilocode/sdk`           | SSE-streamed turns. Routes to many model providers via Kilo's auth.                                                                                                                                              |
 | OpenCode   | `"opencode"`    | Local HTTP server via `@opencode-ai/sdk`        | SSE-streamed turns; same MCP and session shape as Kilo (upstream fork).                                                                                                                                          |
 | Codex      | `"codex"`       | Per-turn subprocess via `@openai/codex-sdk`     | Requires the `codex` CLI from `@openai/codex` and Codex auth (`codex login`, `CODEX_API_KEY`, `TALON_CODEX_KEY`, or `codexApiKey`). MCP servers configured via TOML overrides at thread start. |
+| Antigravity | `"agy"` | Long-lived per-chat subprocess (the `agy` CLI, headless stream-json) | Requires the Antigravity CLI on `PATH` (or `agyBinary` / `AGY_BINARY`) and a one-time interactive `agy` sign-in — subscription OAuth, no API key. MCP servers written into `~/.gemini/config/mcp_config.json` before the child spawns. |
 | OpenAI Agents | `"openai-agents"` | In-process via `@openai/agents` | Responses API (or any OpenAI-compatible endpoint via `TALON_AGENTS_URL` / `openaiBaseUrl`). Persistent per-chat MCP bundles. |
 
-The Kilo and OpenCode backends share infrastructure (`backend/remote-server/`) since the upstream HTTP API is the same; each backend supplies its own SDK client, port, and delivery suffix. Codex is its own integration on top of the Codex CLI's JSONL event stream.
+The Kilo and OpenCode backends share infrastructure (`backend/remote-server/`) since the upstream HTTP API is the same; each backend supplies its own SDK client, port, and delivery suffix. Codex is its own integration on top of the Codex CLI's JSONL event stream, and Antigravity is its own on top of `agy`'s headless NDJSON protocol.
 
 ---
 
@@ -465,9 +468,10 @@ Config file: `~/.talon/config.json`
 | Field                      | Default      | Description                                                                                                             |
 | -------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- |
 | `frontend`                 | `"telegram"` | `"telegram"`, `"whatsapp"`, `"discord"`, `"teams"`, `"terminal"`, `"native"`, or an array ([Frontends](#frontends))      |
-| `backend`                  | `"claude"`   | `"claude"`, `"kilo"`, `"opencode"`, `"codex"`, or `"openai-agents"`                                                     |
+| `backend`                  | `"claude"`   | `"claude"`, `"kilo"`, `"opencode"`, `"codex"`, `"agy"`, or `"openai-agents"`                                            |
 | `botToken`                 | ---          | Telegram bot token                                                                                                      |
 | `model`                    | `"default"`  | Default model. Interpretation depends on the active backend.                                                            |
+| `agyBinary`                | ---          | Path to the Antigravity `agy` executable. `AGY_BINARY` overrides it. |
 | `codexApiKey`              | ---          | Codex-only OpenAI API key. Prefer this over `openaiApiKey` for Codex API-key auth. `codex login` takes precedence over shared `openaiApiKey`. |
 | `concurrency`              | `1`          | Max concurrent AI queries (1--20)                                                                                       |
 | `pulse`                    | `true`       | Periodic group engagement                                                                                               |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.2.2",
+  "version": "5.4.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/src/app.ts

@@ -27,6 +27,7 @@ import {
 } from "./core/background/cron/scheduler.js";
 import { shutdownTriggers } from "./core/background/triggers/index.js";
 import { shutdownAgents } from "./core/agents/index.js";
+import { stopBackupScheduler } from "./core/backup/index.js";
 import { pruneSettledTriggers } from "./storage/triggers.js";
 import { startWatchdog, stopWatchdog } from "./util/watchdog.js";
 import {
@@ -77,11 +78,48 @@ import {
 // the successor will run is importable at all. Nothing has booted yet,
 // so this is both the strongest and the last harmless place to say so.
 // See core/update/self-update.ts for what a failure does instead.
+//
+// This stays ahead of the staged restore below: the smoke run must not
+// touch state, and a restore is the single most destructive thing this
+// file does.
 if (process.argv.includes(BOOT_SMOKE_FLAG)) {
   console.log(BOOT_SMOKE_OK);
   process.exit(0);
 }
 
+/**
+ * A `/backup restore <id>` from chat writes ~/.talon/restore-pending.json
+ * and restarts. It is applied HERE, before anything else: every store
+ * below opens the database, and the database is one of the files this is
+ * about to replace. The pre-restore checkpoint inside needs the current
+ * database, so the handle is closed between the two — which is why the
+ * composition root, and not core/backup, owns that call.
+ *
+ * Never throws: a failed restore still boots the daemon (with the reason
+ * in the log and the request deleted, so the next boot is normal).
+ */
+async function applyStagedRestore(): Promise<string | null> {
+  const { applyPendingRestore, readRestorePending } =
+    await import("./core/backup/index.js");
+  if (!(await readRestorePending())) return null;
+  const { loadConfig } = await import("./core/config/index.js");
+  const { resolveBackupSettings } = await import("./core/backup/plan.js");
+  const { closeDatabase } = await import("./storage/db.js");
+  const report = await applyPendingRestore({
+    settings: resolveBackupSettings(loadConfig().backup),
+    beforeApply: closeDatabase,
+  });
+  if (!report) return null;
+  return (
+    `♻️ Restored snapshot ${report.id}` +
+    (report.checkpointId
+      ? ` (previous state saved as checkpoint ${report.checkpointId})`
+      : "")
+  );
+}
+
+const restoreReport = await bootPhase("staged restore", applyStagedRestore);
+
 const { config } = await bootPhase("bootstrap", () => bootstrap());
 
 // Record this process as the daemon. The gateway port is appended once
@@ -131,6 +169,36 @@ onBackendChange((holder, newBackend, info) => {
 
 // ── Graceful shutdown ────────────────────────────────────────────────────────
 
+/**
+ * Arm the backup scheduler. Here rather than in bootstrap because this is
+ * where the process lifecycle lives — `stopBackupScheduler` is two screens
+ * down in `gracefulShutdown`, and the two belong together. Failure
+ * notifications go to `backup.notifyChatId` when set, otherwise to the
+ * admin, over the same route as the plan alerts.
+ */
+async function startBackups(): Promise<void> {
+  const { initBackup } = await import("./core/backup/index.js");
+  const { resolveBackupSettings } = await import("./core/backup/plan.js");
+  const notifyChatId = config.backup?.notifyChatId;
+  await initBackup({
+    settings: resolveBackupSettings(config.backup),
+    notify: notifyChatId
+      ? async (text: string) => {
+          const { resolveFrontendIdAmong } =
+            await import("./core/frontend-runtime/routing.js");
+          const name = resolveFrontendIdAmong(
+            notifyChatId,
+            frontends.map((frontend) => frontend.name),
+          );
+          const target =
+            frontends.find((frontend) => frontend.name === name) ??
+            frontends[0];
+          if (target) await target.sendMessage(Number(notifyChatId), text);
+        }
+      : undefined,
+  });
+}
+
 let shuttingDown = false;
 let triggerPruneTimer: ReturnType<typeof setInterval> | null = null;
 
@@ -230,6 +298,7 @@ async function gracefulShutdown(signal: string): Promise<void> {
     });
   }
   await shutdownStep("fuse layer", unmountNamespaceFs);
+  await shutdownStep("backup scheduler", stopBackupScheduler);
   await shutdownStep("pulse timer", stopPulseTimer);
   await shutdownStep("heartbeat", async () => {
     stopHeartbeatTimer();
@@ -298,6 +367,7 @@ async function main(): Promise<void> {
   await Promise.all(frontends.map((frontend) => frontend.init()));
   log("bot", "Starting Talon...");
 
+  await startBackups();
   if (config.pulse) startPulseTimer(config.pulseIntervalMs);
   if (config.heartbeat) startHeartbeatTimer(config.heartbeatIntervalMinutes);
   startWatchdog(config.workspace);
@@ -345,6 +415,14 @@ async function main(): Promise<void> {
   // Phase 0 accounting (docs/ts-migration-plan.md): the boot is over the
   // moment the frontends are listening, so the totals are folded into the
   // metrics store here, from the same uptime figure the log line prints.
+  // A restore applied at boot happened before any frontend existed, so the
+  // operator hears about it here, on the first channel that can carry it.
+  if (restoreReport) {
+    const { notifyAdmin } =
+      await import("./core/frontend-runtime/admin-notify.js");
+    await notifyAdmin(restoreReport);
+  }
+
   const bootMs = Math.round(process.uptime() * 1000);
   recordBootMetrics(bootMs);
   startResourceSampler();

package/src/backend/agy/auth.ts

@@ -0,0 +1,128 @@
+/**
+ * Antigravity authentication.
+ *
+ * There is no API key. agy authenticates through a consumer Google
+ * OAuth flow run once interactively, and caches the result at
+ * `~/.gemini/antigravity-cli/antigravity-oauth-token`. Headless runs
+ * reuse that cache; an unauthenticated non-interactive run exits with
+ * an `authentication required` error on stderr rather than hanging.
+ *
+ * Subscription-backed access with no key to configure is the entire
+ * point of this backend, so the only thing Talon can do about auth is
+ * read the cache, report it in `talon doctor`, and — when a turn
+ * fails for it — say plainly that the fix is running `agy` once on
+ * the host.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync } from "node:fs";
+
+/** Where the CLI caches its OAuth token. Env override for tests. */
+function agyTokenPath(override?: string): string {
+  return (
+    override ||
+    process.env.TALON_AGY_TOKEN_FILE ||
+    join(homedir(), ".gemini", "antigravity-cli", "antigravity-oauth-token")
+  );
+}
+
+export interface AgyAuthInfo {
+  /** The token file was found and parsed. */
+  present: boolean;
+  /** `auth_method` from the file — `consumer` on a personal account. */
+  method?: string;
+  /** Access-token expiry, when the file records one. */
+  expiry?: Date;
+  /** True when `expiry` is in the past. */
+  expired: boolean;
+  /** A refresh token is cached, so an expired access token self-heals. */
+  refreshable: boolean;
+  /** Why the file could not be read / parsed. */
+  problem?: string;
+  path: string;
+}
+
+function readExpiry(value: unknown): Date | undefined {
+  if (typeof value !== "string" || !value) return undefined;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
+/**
+ * Read the cached OAuth token.
+ *
+ * The 1.2.x file nests the credential under `token`
+ * (`{access_token, refresh_token, expiry}`) with `auth_method` at the
+ * top level, but older builds wrote `expiry` / `refresh_token` flat.
+ * Both shapes are accepted so a doctor check doesn't go red on a
+ * layout change.
+ */
+export function detectAgyAuth(tokenPath?: string): AgyAuthInfo {
+  const path = agyTokenPath(tokenPath);
+  const base: AgyAuthInfo = {
+    present: false,
+    expired: false,
+    refreshable: false,
+    path,
+  };
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf-8");
+  } catch {
+    return { ...base, problem: "no cached credentials" };
+  }
+  let parsed: Record<string, unknown>;
+  try {
+    const value: unknown = JSON.parse(raw);
+    if (!value || typeof value !== "object") throw new Error("not an object");
+    parsed = value as Record<string, unknown>;
+  } catch (err) {
+    return {
+      ...base,
+      problem: `token file is not valid JSON (${
+        err instanceof Error ? err.message : String(err)
+      })`,
+    };
+  }
+
+  const nested =
+    parsed.token && typeof parsed.token === "object"
+      ? (parsed.token as Record<string, unknown>)
+      : {};
+  const expiry = readExpiry(nested.expiry ?? parsed.expiry);
+  const refreshToken = nested.refresh_token ?? parsed.refresh_token;
+  return {
+    present: true,
+    ...(typeof parsed.auth_method === "string"
+      ? { method: parsed.auth_method }
+      : {}),
+    ...(expiry ? { expiry } : {}),
+    expired: expiry ? expiry.getTime() <= Date.now() : false,
+    refreshable: typeof refreshToken === "string" && refreshToken.length > 0,
+    path,
+  };
+}
+
+/** True for the stderr text an unauthenticated headless run produces. */
+export function isAgyAuthFailure(text: string): boolean {
+  return /authentication required|not (?:yet )?authenticated|please (?:run|sign in|log in)/i.test(
+    text,
+  );
+}
+
+/**
+ * Turn an auth failure into an error that names the fix. The raw CLI
+ * text is a bare `authentication required` with no hint that the
+ * remedy is an interactive login on the host.
+ */
+export function agyAuthError(cause?: unknown): Error {
+  const err = new Error(
+    "Antigravity is not authenticated. Run `agy` once interactively on " +
+      "this host and complete the Google sign-in; headless runs then reuse " +
+      "the cached credentials at " +
+      `${agyTokenPath()}. There is no API key for this backend.`,
+  );
+  if (cause !== undefined) (err as Error & { cause?: unknown }).cause = cause;
+  return err;
+}

package/src/backend/agy/constants.ts

@@ -0,0 +1,88 @@
+/**
+ * Antigravity (`agy`) backend constants.
+ *
+ * The CLI is Google's Antigravity agent driven in headless mode
+ * (`docs/agy/headless-docs.md`). Talon keeps one long-lived
+ * `--input-format stream-json` child per chat and feeds it one
+ * `user` event per turn; everything below is the vocabulary that
+ * child is spawned and framed with.
+ */
+
+import { buildDeliveryContract } from "../runtime/prompt/delivery-contract.js";
+
+/**
+ * System-prompt suffix appended to the user-configured system prompt.
+ *
+ * agy has no system-prompt flag at all, so the assembled prompt rides
+ * in as a fenced block on the FIRST turn of a conversation (see
+ * `handler/message.ts`); resumed conversations inherit it from their
+ * stored history. The contract itself is the shared text-or-tools one:
+ * agy streams `text_delta` for prose AND routes Talon's delivery tools
+ * through MCP, so both delivery routes are live.
+ *
+ * Tool names are frontend-specific (native's send tool is
+ * `send_message`, telegram's is `send`), so the suffix is built per
+ * chat from the chat's owning frontend.
+ */
+export function agySystemPromptSuffix(frontend: string): string {
+  return `\n\n${buildDeliveryContract("text-or-tools", frontend)}\n`;
+}
+
+/** Telegram-shaped default, kept for the one-shot path and tests. */
+export const AGY_SYSTEM_PROMPT_SUFFIX = agySystemPromptSuffix("telegram");
+
+/**
+ * Default model when none is configured.
+ *
+ * `agy models` lists Gemini, Claude and GPT-OSS slugs; the Flash-High
+ * Gemini is the subscription-backed default the interactive CLI uses
+ * and the only one guaranteed present on a consumer account.
+ */
+export const AGY_DEFAULT_MODEL = "gemini-3.8-flash-high";
+
+/** Minimum `agy --version` the backend is known to work against. */
+export const AGY_MIN_VERSION = "1.2.0";
+
+/**
+ * Prefix every MCP server entry Talon writes into agy's shared
+ * `mcp_config.json` carries. Anything under this prefix is ours to
+ * add, rewrite and delete; anything else in that file belongs to the
+ * user and is preserved byte-for-byte.
+ */
+export const AGY_MCP_PREFIX = "__talon__";
+
+/**
+ * How long a per-chat child may sit idle before it is reaped. A warm
+ * child costs a few hundred MB of resident Go process; 10 minutes
+ * matches the MCP hub's own child TTL so a conversation that goes
+ * quiet releases both at roughly the same time.
+ */
+export const AGY_IDLE_REAP_MS = 10 * 60 * 1000;
+
+/** Grace between SIGTERM and SIGKILL when tearing a child down. */
+export const AGY_KILL_GRACE_MS = 2000;
+
+/**
+ * Fixed CLI flags every headless child is spawned with.
+ *
+ *   - `--input-format stream-json`  — many turns in one process; each
+ *     `user` line on stdin runs one turn and yields one `result`.
+ *   - `--output-format stream-json` — required by the input format,
+ *     and the only shape that reports tools and usage live.
+ *   - `--dangerously-skip-permissions` — headless means no operator to
+ *     approve a tool; without it every shell/file call is soft-denied
+ *     with a stderr notice and the turn quietly does nothing. Same
+ *     posture as every other Talon backend (see
+ *     `codex/constants.ts: CODEX_THREAD_PERMISSIONS`).
+ *   - `--print-timeout 0s`          — no ceiling on a turn; Talon owns
+ *     turn timeouts, not the CLI.
+ */
+export const AGY_BASE_ARGS: readonly string[] = [
+  "--input-format",
+  "stream-json",
+  "--output-format",
+  "stream-json",
+  "--dangerously-skip-permissions",
+  "--print-timeout",
+  "0s",
+];

package/src/backend/agy/doctor.ts

@@ -0,0 +1,161 @@
+/**
+ * `talon doctor` checks for the Antigravity backend: the binary, its
+ * version, the cached OAuth credentials, and whether the model
+ * catalog answers.
+ */
+
+import { execFileSync } from "node:child_process";
+import type {
+  DoctorCheck,
+  DoctorConfigSlice,
+} from "../../core/doctor/types.js";
+import { binaryOnPath } from "../../util/binary-on-path.js";
+import { AGY_MIN_VERSION } from "./constants.js";
+import { detectAgyAuth } from "./auth.js";
+import { parseAgyModels } from "./models.js";
+
+/** Resolve the binary the same way the runtime does: env, config, PATH. */
+function resolveBinary(config: DoctorConfigSlice | undefined): string {
+  const configured = (config as { agyBinary?: string } | undefined)?.agyBinary;
+  return process.env.AGY_BINARY || configured || "agy";
+}
+
+/** `1.2.7` → [1, 2, 7]; missing parts are 0. */
+function parseVersion(text: string): number[] {
+  const match = /(\d+)\.(\d+)(?:\.(\d+))?/.exec(text);
+  if (!match) return [];
+  return [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)];
+}
+
+function versionAtLeast(found: number[], required: number[]): boolean {
+  for (let i = 0; i < required.length; i++) {
+    const a = found[i] ?? 0;
+    const b = required[i] ?? 0;
+    if (a !== b) return a > b;
+  }
+  return true;
+}
+
+function run(binary: string, args: string[]): string {
+  return execFileSync(binary, args, {
+    encoding: "utf-8",
+    timeout: 30_000,
+    stdio: ["ignore", "pipe", "pipe"],
+    maxBuffer: 4 * 1024 * 1024,
+  });
+}
+
+function versionCheck(binary: string): DoctorCheck {
+  let output: string;
+  try {
+    output = run(binary, ["--version"]).trim();
+  } catch (err) {
+    return {
+      label: "Antigravity CLI version unreadable",
+      status: "warn",
+      detail: err instanceof Error ? err.message : String(err),
+      issue: true,
+    };
+  }
+  const found = parseVersion(output);
+  const required = parseVersion(AGY_MIN_VERSION);
+  if (found.length === 0) {
+    return {
+      label: "Antigravity CLI version unrecognised",
+      status: "warn",
+      detail: output,
+      issue: true,
+    };
+  }
+  if (!versionAtLeast(found, required)) {
+    return {
+      label: `Antigravity CLI too old (${output})`,
+      status: "fail",
+      detail: `headless stream-json needs >= ${AGY_MIN_VERSION}`,
+    };
+  }
+  return { label: "Antigravity CLI version", status: "ok", detail: output };
+}
+
+function authCheck(): DoctorCheck {
+  const auth = detectAgyAuth();
+  if (!auth.present) {
+    return {
+      label: "Antigravity auth missing",
+      status: "warn",
+      detail: `${auth.problem ?? "no token file"} — run \`agy\` once interactively to sign in`,
+      issue: true,
+    };
+  }
+  if (auth.expired && !auth.refreshable) {
+    return {
+      label: "Antigravity auth expired",
+      status: "warn",
+      detail: `token expired ${auth.expiry?.toISOString() ?? ""} with no refresh token — run \`agy\` again`,
+      issue: true,
+    };
+  }
+  const detail = [
+    auth.method ? `${auth.method} OAuth` : "OAuth",
+    auth.expired ? "access token stale (refreshable)" : undefined,
+    auth.expiry ? `expiry ${auth.expiry.toISOString()}` : undefined,
+  ]
+    .filter(Boolean)
+    .join(", ");
+  return { label: "Antigravity auth", status: "ok", detail };
+}
+
+function modelsCheck(binary: string): DoctorCheck {
+  try {
+    const models = parseAgyModels(run(binary, ["models"]));
+    if (models.length === 0) {
+      return {
+        label: "Antigravity models empty",
+        status: "warn",
+        detail: "`agy models` returned no rows",
+        issue: true,
+      };
+    }
+    return {
+      label: "Antigravity models",
+      status: "ok",
+      detail: `${models.length} available (${models[0].id}…)`,
+    };
+  } catch (err) {
+    return {
+      label: "Antigravity models unavailable",
+      status: "warn",
+      detail: err instanceof Error ? err.message : String(err),
+      issue: true,
+    };
+  }
+}
+
+export async function agyDoctorChecks(
+  config: DoctorConfigSlice | undefined,
+  isActive = true,
+): Promise<DoctorCheck[]> {
+  const binary = resolveBinary(config);
+  const found =
+    binary.includes("/") || binary.includes("\\") ? true : binaryOnPath(binary);
+  if (!found) {
+    return [
+      {
+        label: "Antigravity CLI not found",
+        status: "fail",
+        detail:
+          "install the Antigravity CLI and put `agy` on PATH, or set `agyBinary` / AGY_BINARY",
+      },
+    ];
+  }
+
+  const checks: DoctorCheck[] = [
+    { label: "Antigravity CLI installed", status: "ok", detail: binary },
+    versionCheck(binary),
+    authCheck(),
+  ];
+  // The catalog probe costs a process spawn and a network round-trip,
+  // so it only runs for the backend actually serving chats.
+  if (isActive) checks.push(modelsCheck(binary));
+  return checks;
+}

package/src/backend/agy/effort.ts

@@ -0,0 +1,76 @@
+/**
+ * Antigravity reasoning-effort vocabulary.
+ *
+ * agy expresses effort in two places at once, and the precedence
+ * between them is the whole content of this module:
+ *
+ *   1. **Baked into the model id.** Most slugs carry the level as a
+ *      suffix — `gemini-3.8-flash-high`, `gemini-3.1-pro-low`. Picking
+ *      such an id IS picking an effort.
+ *   2. **The `--effort low|medium|high` flag.** Accepted alongside any
+ *      model.
+ *
+ * Precedence Talon applies: a requested level first tries to re-point
+ * the model id at the sibling slug carrying that suffix (so the CLI
+ * validates the combination for us and the picker keeps showing the
+ * model actually in use); `--effort` is then passed as well, so a
+ * suffix-less id (`claude-sonnet-4-6`, `gpt-oss-120b-medium` has a
+ * baked medium but no siblings) still honours the request. Levels agy
+ * cannot express (`off`, `minimal`, `xhigh`, `max`) fall through to
+ * the model's own default with no flag and no id rewrite — the same
+ * "let the model decide" behaviour codex's mapping produces.
+ */
+
+import type { ReasoningEffortLevel } from "../../core/types.js";
+
+/** The three levels `--effort` accepts. */
+export type AgyEffort = "low" | "medium" | "high";
+
+const AGY_EFFORTS: readonly AgyEffort[] = ["low", "medium", "high"];
+
+/** True for one of the three suffixes agy bakes into model ids. */
+function isAgyEffort(value: string): value is AgyEffort {
+  return (AGY_EFFORTS as readonly string[]).includes(value);
+}
+
+/**
+ * Map a canonical level onto `--effort`, or undefined when agy has no
+ * way to express it (`off` / `minimal` / `xhigh` / `max`, or nothing
+ * requested).
+ */
+export function toAgyEffort(
+  level: ReasoningEffortLevel | undefined,
+): AgyEffort | undefined {
+  if (!level) return undefined;
+  return isAgyEffort(level) ? level : undefined;
+}
+
+/** The effort suffix baked into a model id, if it has one. */
+export function effortSuffixOf(modelId: string): AgyEffort | undefined {
+  const tail = modelId.slice(modelId.lastIndexOf("-") + 1);
+  return isAgyEffort(tail) ? tail : undefined;
+}
+
+/** The model id with any effort suffix stripped. */
+export function modelIdStem(modelId: string): string {
+  const suffix = effortSuffixOf(modelId);
+  return suffix ? modelId.slice(0, -(suffix.length + 1)) : modelId;
+}
+
+/**
+ * Re-point a model id at the sibling slug carrying `effort`, when such
+ * a sibling exists in `catalogIds`. Returns the original id when the
+ * model has no effort suffix, when the sibling isn't offered, or when
+ * no effort was requested — never invents an id the CLI would reject
+ * (headless agy exits non-zero on an unknown `--model`).
+ */
+export function applyEffortToModelId(
+  modelId: string,
+  effort: AgyEffort | undefined,
+  catalogIds: readonly string[],
+): string {
+  if (!effort) return modelId;
+  if (!effortSuffixOf(modelId)) return modelId;
+  const candidate = `${modelIdStem(modelId)}-${effort}`;
+  return catalogIds.includes(candidate) ? candidate : modelId;
+}