@vellumai/assistant 0.8.7-dev.202606052232.2ddc989 → 0.8.8

package/src/acp/types.ts

@@ -12,14 +12,6 @@ export interface AcpAgentConfig {
   args: string[];
   description?: string;
   env?: Record<string, string>;
-  /**
-   * Canonical adapter identity (e.g. "claude-agent-acp"), set by the
-   * resolver. It survives the bunx rewrite, where `command` becomes "bun"
-   * and the adapter package moves into `args`. Optional because plain user
-   * configs that bypass the resolver never set it; consumers fall back to
-   * the command basename via `adapterCommandOf` in `resolve-agent.ts`.
-   */
-  adapterCommand?: string;
 }
 
 /**

package/src/agent/compaction-circuit.ts

@@ -1,15 +1,27 @@
-import type { CompactionCircuitEvent } from "../plugins/types.js";
+import type { TrustContext } from "../daemon/trust-context.js";
+import { FALLBACK_TURN_TRUST } from "../daemon/trust-context.js";
+import { DEFAULT_TIMEOUTS, runPipeline } from "../plugins/pipeline.js";
+import { getMiddlewaresFor } from "../plugins/registry.js";
+import type {
+  CircuitBreakerArgs,
+  CircuitBreakerResult,
+  CompactionCircuitEvent,
+  TurnContext,
+} from "../plugins/types.js";
 
 /**
- * Consecutive summary-LLM failures required to trip the breaker.
+ * Turn-scoped identifiers the circuit pipeline runner needs to populate its
+ * log records and plugin attribution. They are supplied per call because they
+ * belong to the active turn, not to the circuit's durable state — non-turn
+ * callers (e.g. `Conversation.forceCompact`) leave the optional fields unset
+ * and fall back to stable placeholders.
  */
-export const COMPACTION_CIRCUIT_FAILURE_THRESHOLD = 3;
-
-/**
- * Cooldown window after the breaker trips, during which auto-compaction is
- * suspended.
- */
-export const COMPACTION_CIRCUIT_COOLDOWN_MS = 60 * 60 * 1000;
+export interface CircuitTurnInfo {
+  currentRequestId?: string;
+  currentTurnTrustContext?: TrustContext;
+  trustContext?: TrustContext;
+  turnCount: number;
+}
 
 /**
  * Per-conversation compaction circuit breaker: three consecutive summary-LLM
@@ -18,10 +30,12 @@ export const COMPACTION_CIRCUIT_COOLDOWN_MS = 60 * 60 * 1000;
  * resets on process restart, the intended "one free retry after restart"
  * behavior.
  *
- * The dev-only playground routes (`POST /playground/reset-compaction-circuit`,
- * `POST /playground/inject-compaction-failures`) read and mutate
- * `consecutiveCompactionFailures` and `compactionCircuitOpenUntil` directly on
- * this object.
+ * The breaker's threshold/cooldown semantics live in the `circuitBreaker`
+ * plugin (`plugins/defaults/circuit-breaker/register.ts`), which mutates this
+ * object in place via the `CircuitBreakerArgs.state` container. This class is
+ * that container plus the methods the rest of the daemon uses to query and
+ * update it, so the dev-only playground routes can read and write the same
+ * fields directly.
  */
 export class CompactionCircuit {
   readonly conversationId: string;
@@ -37,62 +51,90 @@ export class CompactionCircuit {
    * transition event. Callers must only invoke this when the summary LLM
    * actually ran (`summaryFailed !== undefined`) so early-return paths don't
    * silently reset the 3-strike counter.
-   *
-   * A run of three failures trips the breaker; any success resets both the
-   * counter and the cooldown timestamp. `compaction_circuit_open` fires once
-   * when the counter first reaches the threshold while the circuit is dormant;
-   * `compaction_circuit_closed` fires only on the open→closed transition.
    */
   async recordOutcome(
+    turn: CircuitTurnInfo,
     summaryFailed: boolean,
     onEvent: (msg: CompactionCircuitEvent) => void,
   ): Promise<void> {
-    if (summaryFailed) {
-      this.consecutiveCompactionFailures += 1;
-      // Treat a stale/expired open-until timestamp the same as null so a new
-      // 3-strike window can re-open the circuit after the prior cooldown
-      // elapses. Without this, subsequent trips would no-op because
-      // `compactionCircuitOpenUntil` remains set to a past timestamp even
-      // though the breaker is effectively closed.
-      const circuitDormant =
-        this.compactionCircuitOpenUntil === null ||
-        Date.now() >= this.compactionCircuitOpenUntil;
-      if (
-        this.consecutiveCompactionFailures >=
-          COMPACTION_CIRCUIT_FAILURE_THRESHOLD &&
-        circuitDormant
-      ) {
-        const openUntil = Date.now() + COMPACTION_CIRCUIT_COOLDOWN_MS;
-        this.compactionCircuitOpenUntil = openUntil;
-        onEvent({
-          type: "compaction_circuit_open",
-          conversationId: this.conversationId,
-          reason: "3_consecutive_failures",
-          openUntil,
-        });
-      }
-    } else {
-      // Emit only on the open→closed transition; firing on the common
-      // closed→closed case would be noise.
-      const wasOpen = this.compactionCircuitOpenUntil !== null;
-      this.consecutiveCompactionFailures = 0;
-      this.compactionCircuitOpenUntil = null;
-      if (wasOpen) {
-        onEvent({
-          type: "compaction_circuit_closed",
-          conversationId: this.conversationId,
-        });
-      }
-    }
+    await this.run(turn, {
+      outcome: summaryFailed ? "failure" : "success",
+      onEvent,
+    });
   }
 
   /**
    * Query-only: is the breaker currently open? Auto-compaction paths gate on
-   * `!isOpen()`; forced paths admit regardless. An expired open-until
-   * timestamp reads as closed — it is the only source of truth for the gate.
+   * `!isOpen(...)`; forced paths admit regardless of the decision.
    */
-  async isOpen(): Promise<boolean> {
-    const openUntil = this.compactionCircuitOpenUntil;
-    return openUntil !== null && Date.now() < openUntil;
+  async isOpen(turn: CircuitTurnInfo): Promise<boolean> {
+    const decision = await this.run(turn, {});
+    return decision.open;
+  }
+
+  /**
+   * Clear the breaker: zero the failure counter and close the circuit,
+   * emitting `compaction_circuit_closed` on the open→closed transition.
+   * Equivalent to recording a successful outcome.
+   */
+  async reset(
+    turn: CircuitTurnInfo,
+    onEvent?: (msg: CompactionCircuitEvent) => void,
+  ): Promise<void> {
+    await this.run(turn, {
+      outcome: "success",
+      ...(onEvent ? { onEvent } : {}),
+    });
+  }
+
+  private async run(
+    turn: CircuitTurnInfo,
+    args: {
+      outcome?: "success" | "failure";
+      onEvent?: (msg: CompactionCircuitEvent) => void;
+    },
+  ): Promise<CircuitBreakerResult> {
+    const turnContext = this.buildTurnContext(turn);
+    return runPipeline<CircuitBreakerArgs, CircuitBreakerResult>(
+      "circuitBreaker",
+      getMiddlewaresFor("circuitBreaker"),
+      async (terminalArgs) => {
+        // No plugin in the chain produced a decision. This should be
+        // unreachable in production because the default plugin registers a
+        // `circuitBreaker` middleware that always returns a decision, but we
+        // defensively derive the state here so test setups that intentionally
+        // omit the default plugin still get a sensible response.
+        const openUntil = terminalArgs.state.compactionCircuitOpenUntil;
+        const now = Date.now();
+        if (openUntil !== null && now < openUntil) {
+          return { open: true, cooldownRemainingMs: openUntil - now };
+        }
+        return { open: false };
+      },
+      {
+        key: `compaction:${this.conversationId}`,
+        // Pass this circuit as the mutable state container. The
+        // `CircuitBreakerArgs.state` shape matches its `conversationId` /
+        // `consecutiveCompactionFailures` / `compactionCircuitOpenUntil`
+        // fields so plugins mutate the same object the playground routes read.
+        state: this,
+        ...(args.outcome !== undefined ? { outcome: args.outcome } : {}),
+        ...(args.onEvent ? { onEvent: args.onEvent } : {}),
+      },
+      turnContext,
+      DEFAULT_TIMEOUTS.circuitBreaker,
+    );
+  }
+
+  private buildTurnContext(turn: CircuitTurnInfo): TurnContext {
+    return {
+      requestId: turn.currentRequestId ?? "circuit-breaker",
+      conversationId: this.conversationId,
+      turnIndex: turn.turnCount,
+      trust:
+        turn.currentTurnTrustContext ??
+        turn.trustContext ??
+        FALLBACK_TURN_TRUST,
+    };
   }
 }

package/src/agent/loop.ts

@@ -12,14 +12,17 @@ import type { ContextWindowResult } from "../context/window-manager.js";
 import type { ToolActivityMetadata } from "../daemon/message-types/web-activity.js";
 import { HOOKS } from "../plugin-api/constants.js";
 import type { PostToolUseContext, StopContext } from "../plugin-api/types.js";
-import {
-  DEFAULT_COMPACTION_PLUGIN_NAME,
-  defaultCompact,
-} from "../plugins/defaults/compaction/compact.js";
+import { defaultCompactionTerminal } from "../plugins/defaults/compaction/terminal.js";
 import type { PostCompactionHookInput } from "../plugins/defaults/memory-retrieval/hooks/post-compact.js";
-import { runHook } from "../plugins/pipeline.js";
-import type { CompactionCircuitEvent, TurnContext } from "../plugins/types.js";
-import { PluginExecutionError } from "../plugins/types.js";
+import { DEFAULT_TIMEOUTS, runHook, runPipeline } from "../plugins/pipeline.js";
+import { getMiddlewaresFor } from "../plugins/registry.js";
+import type {
+  CompactionArgs,
+  CompactionCircuitEvent,
+  CompactionResult,
+  TurnContext,
+} from "../plugins/types.js";
+import { PluginTimeoutError } from "../plugins/types.js";
 import { normalizeThinkingConfigForWire } from "../providers/thinking-config.js";
 import type {
   ContentBlock,
@@ -454,7 +457,7 @@ export interface ResolvedSystemPrompt {
 /**
  * Orchestrator-supplied hook the loop invokes when the mid-loop budget gate
  * trips and inline compaction runs. The loop owns the trigger, the
- * compaction call, the result interpretation (circuit-breaker
+ * `compaction` pipeline call, the result interpretation (circuit-breaker
  * bookkeeping + the exhaustion decision), and the inline continue; this hook
  * bridges the injection state the loop is intentionally blind to. Durable
  * persistence is signalled out-of-band via the `history_stripped` (marker)
@@ -677,7 +680,15 @@ export class AgentLoop {
     onEvent: (event: AgentEvent) => void | Promise<void>,
   ): Promise<void> {
     try {
-      await this.compactionCircuit.recordOutcome(summaryFailed, onEvent);
+      await this.compactionCircuit.recordOutcome(
+        {
+          currentRequestId: turnContext.requestId,
+          currentTurnTrustContext: turnContext.trust,
+          turnCount: turnContext.turnIndex,
+        },
+        summaryFailed,
+        onEvent,
+      );
     } catch (recordError) {
       log.error(
         { err: recordError, requestId: turnContext.requestId },
@@ -689,10 +700,11 @@ export class AgentLoop {
   /**
    * Compact the running history in place when the mid-loop budget gate trips.
    *
-   * Calls the default compaction plugin on the stripped history, then
-   * re-applies injections via the supplied hooks. Returns the history to
-   * continue from, or `null` when the compactor exhausted its retry budget so
-   * the caller yields `exitReason = "budget"` and the orchestrator escalates.
+   * Runs the `compaction` pipeline natively (like {@link estimateTokens}) on
+   * the stripped history, then re-applies injections via the supplied hooks.
+   * Returns the history to continue from, or `null` when the compactor timed
+   * out or exhausted its retry budget so the caller yields
+   * `exitReason = "budget"` and the orchestrator escalates.
    */
   private async compact(
     history: Message[],
@@ -709,27 +721,42 @@ export class AgentLoop {
     // Record the history-stripped marker right after stripping, before the
     // pipeline runs.
     await onEvent({ type: "history_stripped" });
-    const manager = turnContext.contextWindowManager;
-    if (manager == null) {
-      throw new PluginExecutionError(
-        "default-compaction: turnContext.contextWindowManager is missing — orchestrator must attach it before invoking compaction",
-        DEFAULT_COMPACTION_PLUGIN_NAME,
+    let result: CompactionResult;
+    try {
+      result = await runPipeline<CompactionArgs, CompactionResult>(
+        "compaction",
+        getMiddlewaresFor("compaction"),
+        (args) => defaultCompactionTerminal(args, turnContext),
+        // The mid-loop budget gate is reached only when this turn decides to
+        // compact in place, so `force` the pipeline past its auto-threshold
+        // check. `actorTrustClass` comes from the turn context (the actor whose
+        // turn triggered compaction) so the compactor's image manifest excludes
+        // guardian-only attachments for untrusted actors. `overrideProfile` is
+        // the turn's resolved inference-profile override for the summary call.
+        {
+          messages: rawHistory,
+          signal,
+          options: {
+            force: true,
+            actorTrustClass: turnContext.trust.trustClass,
+            overrideProfile,
+          },
+        },
+        turnContext,
+        DEFAULT_TIMEOUTS.compaction,
       );
+    } catch (error) {
+      if (error instanceof PluginTimeoutError) {
+        // A timeout counts as a compaction failure against the circuit breaker.
+        await this.recordCompactionOutcome(turnContext, true, onEvent);
+        return null;
+      }
+      throw error;
     }
-    // The mid-loop budget gate is reached only when this turn decides to
-    // compact in place, so `force` past the auto-threshold check.
-    // `actorTrustClass` comes from the turn context (the actor whose turn
-    // triggered compaction) so the compactor's image manifest excludes
-    // guardian-only attachments for untrusted actors. `overrideProfile` is the
-    // turn's resolved inference-profile override for the summary call.
-    const compactResult = await defaultCompact({
-      manager,
-      messages: rawHistory,
-      signal,
-      force: true,
-      actorTrustClass: turnContext.trust.trustClass,
-      overrideProfile,
-    });
+    // `CompactionResult` is intentionally `unknown` at the plugin boundary so
+    // plugin consumers don't import the window manager; the loop ran the
+    // pipeline, so it interprets the concrete result here.
+    const compactResult = result as ContextWindowResult;
     // `force: true` bypasses the auto-threshold gate, but early returns
     // for "no eligible messages" / "insufficient messages" still leave
     // `summaryFailed` undefined. Only record an outcome when the summary LLM

package/src/api/responses/conversation-message.ts

@@ -335,13 +335,7 @@ export const ConversationMessageSchema = z.object({
    * assistant messages were consolidated for history rendering.
    */
   mergedMessageIds: z.array(z.string()).optional(),
-  /**
-   * Renderable conversation roles only. The messages endpoint emits a
-   * UI-facing transcript, so it excludes the `system` rows that the
-   * underlying `MessageRole` column also permits — those are agent-context
-   * scaffolding, never a displayed turn.
-   */
-  role: z.enum(["user", "assistant"]),
+  role: z.string(),
   /**
    * Flat plain-text body (joined text segments). Redundant with
    * `textSegments`/`contentOrder` for clients that render from the positional

package/src/approvals/guardian-request-resolvers.ts

@@ -14,7 +14,7 @@
 import { answerCall } from "../calls/call-domain.js";
 import { findContactChannel } from "../contacts/contact-store.js";
 import { upsertContactChannel } from "../contacts/contacts-write.js";
-import { findConversation } from "../daemon/conversation-registry.js";
+import { findConversation } from "../daemon/conversation-store.js";
 import {
   type CanonicalGuardianRequest,
   getCanonicalGuardianRequest,

package/src/background-wake/next-wake.ts

@@ -97,7 +97,6 @@ function getHeartbeatWakeSource(now: number): HeartbeatWakeSource | null {
 
   const service = HeartbeatService.getInstance();
   if (service?.isConsecutiveRunCapReached) return null;
-  if (service?.isDailyCapReached) return null;
 
   const serviceNextRunAt = service?.nextRunAt ?? null;
   let nextRunAt = serviceNextRunAt;

package/src/config/__tests__/feature-flag-registry-guard.test.ts

@@ -85,8 +85,8 @@ describe("unified feature flag registry guard", () => {
       ) {
         violations.push(`${prefix}: missing or non-string 'description'`);
       }
-      if (typeof flag.defaultEnabled !== "boolean" && typeof flag.defaultEnabled !== "string") {
-        violations.push(`${prefix}: missing or invalid 'defaultEnabled' (expected boolean or string)`);
+      if (typeof flag.defaultEnabled !== "boolean") {
+        violations.push(`${prefix}: missing or non-boolean 'defaultEnabled'`);
       }
     }
 

package/src/config/acp-defaults.test.ts

@@ -10,7 +10,6 @@ describe("DEFAULT_ACP_AGENT_PROFILES", () => {
     expect(Object.keys(DEFAULT_ACP_AGENT_PROFILES).sort()).toEqual([
       "claude",
       "codex",
-      "gemini",
     ]);
   });
 
@@ -30,14 +29,6 @@ describe("DEFAULT_ACP_AGENT_PROFILES", () => {
     });
   });
 
-  test("gemini profile speaks native ACP via gemini --acp (no adapter binary)", () => {
-    expect(DEFAULT_ACP_AGENT_PROFILES.gemini).toEqual({
-      command: "gemini",
-      args: ["--acp"],
-      description: "Google Gemini CLI (native ACP via gemini --acp)",
-    });
-  });
-
   test("is deeply frozen so mutation throws in strict mode", () => {
     expect(Object.isFrozen(DEFAULT_ACP_AGENT_PROFILES)).toBe(true);
     for (const profile of Object.values(DEFAULT_ACP_AGENT_PROFILES)) {
@@ -55,7 +46,6 @@ describe("DEFAULT_AGENT_NPM_PACKAGES", () => {
     expect(DEFAULT_AGENT_NPM_PACKAGES).toEqual({
       "claude-agent-acp": "@agentclientprotocol/claude-agent-acp",
       "codex-acp": "@zed-industries/codex-acp",
-      gemini: "@google/gemini-cli",
     });
   });
 

package/src/config/acp-defaults.ts

@@ -30,11 +30,6 @@ export const DEFAULT_ACP_AGENT_PROFILES: Readonly<
     args: FROZEN_EMPTY_ARGS,
     description: "OpenAI Codex CLI (via @zed-industries/codex-acp)",
   }),
-  gemini: Object.freeze({
-    command: "gemini",
-    args: Object.freeze(["--acp"]) as unknown as string[],
-    description: "Google Gemini CLI (native ACP via gemini --acp)",
-  }),
 });
 
 /**
@@ -49,5 +44,4 @@ export const DEFAULT_AGENT_NPM_PACKAGES: Readonly<Record<string, string>> =
   Object.freeze({
     "claude-agent-acp": "@agentclientprotocol/claude-agent-acp",
     "codex-acp": "@zed-industries/codex-acp",
-    gemini: "@google/gemini-cli",
   });

package/src/config/bundled-skills/acp/SKILL.md

@@ -7,30 +7,29 @@ metadata:
   vellum:
     display-name: "ACP"
     activation-hints:
-      - "User asks to use Claude Code, Codex, or Gemini to do something"
-      - "User wants to delegate a coding task to Claude Code, Codex, Gemini, or another ACP agent"
-      - "User wants to hand a coding task to another agent and check on it later"
+      - "User wants to delegate a coding task to Claude Code, Codex, or another ACP agent"
       - "User wants to spawn an external coding agent that runs autonomously and streams results back"
-      - "User mentions ACP, claude-agent-acp, codex-acp, gemini --acp, or running multiple coding agents in parallel"
+      - "User mentions ACP, claude-agent-acp, codex-acp, or running multiple coding agents in parallel"
     avoid-when:
-      - "Task is small enough to do inline with the assistant's own tools - no need for an external agent"
+      - "Task is small enough to do inline with the assistant's own tools — no need for an external agent"
 ---
 
-ACP agent orchestration - spawn external coding agents (Claude Code, Codex, Gemini) to work on tasks via the Agent Client Protocol. Each agent runs as its own subprocess speaking ACP over stdio and streams results back into the conversation.
+ACP agent orchestration - spawn external coding agents (Claude Code, Codex, etc.) to work on tasks via the Agent Client Protocol. Each agent runs as its own subprocess speaking ACP over stdio and streams results back into the conversation.
 
 ## Usage
 
 Use `acp_spawn` to delegate a coding task to an external agent. The agent runs as a subprocess speaking the ACP protocol over stdio and streams results back.
 
-Users can refer to agents by natural names: "claude code", "codex cli", "openai codex", "gemini cli", and "google gemini" all resolve to the canonical `claude`, `codex`, and `gemini` ids (unless the user's config defines an agent literally keyed by that name, which always wins).
-
 ## First-time setup
 
-When the user first tries to use ACP and it's not enabled, set it up automatically:
+When the user first tries to use ACP and it's not configured, set it up automatically:
 
-1. **Enable the `acp` feature flag** (the primary enablement path). Either PATCH it via the gateway feature-flags endpoint or direct the user to toggle "ACP Coding Agents" in the client's feature flags UI. Flag changes are hot-refreshed in the assistant - no restart needed.
+1. **Check if `claude-agent-acp` is installed** by running `which claude-agent-acp`. If not found, install it:
+   ```bash
+   npm i -g @agentclientprotocol/claude-agent-acp
+   ```
 
-   As a supported alternative, edit the workspace config file to add the `acp` section. Default profiles for `claude`, `codex`, and `gemini` ship out-of-box, so the minimal config is just:
+2. **Enable ACP in the workspace config** by editing the config file to add the `acp` section. Default profiles for `claude` and `codex` ship out-of-box, so the minimal config is just:
    ```json
    {
      "acp": {
@@ -39,108 +38,57 @@ When the user first tries to use ACP and it's not enabled, set it up automatical
      }
    }
    ```
-   If you go the config route, **wait a few seconds** for the config watcher to pick up the change (it hot-reloads automatically - no restart needed).
-
-2. Then retry the `acp_spawn` call. Do NOT run `vellum sleep && vellum wake` - that kills the conversation.
-
-No manual binary installation is needed first: missing adapter binaries are run on demand via bun, or installed automatically (see below).
-
-## Automatic adapter availability
-
-When `acp_spawn` finds the agent's binary missing from PATH, the assistant runs the adapter through bun instead (`bun x --bun <package>`). Bun fetches the package into its cache on first use, so there is no global install and it works on hosts without node or npm (platform-hosted assistants ship bun only). When bun itself is not on PATH, the assistant falls back to silently installing the matching npm package globally and proceeds in the same call.
-
-Only the allowlisted out-of-box packages are ever run or installed this way (`@agentclientprotocol/claude-agent-acp`, `@zed-industries/codex-acp`, `@google/gemini-cli`); user-configured agents with custom commands are never fetched or installed automatically.
 
-Manual installation is fallback guidance for unusual setups: bun and npm both unavailable, restricted global installs, or an auto-install failure (the failure reason is surfaced in the tool result).
+3. **Wait a few seconds** for the config watcher to pick up the change (it hot-reloads automatically - no restart needed).
 
-```bash
-npm i -g @agentclientprotocol/claude-agent-acp   # claude
-npm i -g @zed-industries/codex-acp               # codex
-npm i -g @google/gemini-cli                      # gemini
-```
-
-## Claude setup
-
-The `claude-agent-acp` adapter requires a Claude OAuth token. Store it once in the credential store and every spawn injects it as `CLAUDE_CODE_OAUTH_TOKEN` automatically:
-
-```bash
-assistant credentials set --service acp --field claude_oauth_token <token>
-```
-
-When the token is missing, do NOT ask the user to paste it into chat. Collect it via the secret-request flow instead: `credential_store` with action `prompt`, service `acp`, field `claude_oauth_token`. That prompts the user through a secure UI so the token never enters the conversation or the workspace config. Users generate the token by running `claude setup-token` on a machine where they are logged in to Claude.
+4. Then retry the `acp_spawn` call. Do NOT run `vellum sleep && vellum wake` - that kills the conversation.
 
 ## Codex setup
 
-The `codex-acp` adapter is fetched automatically when missing, but it shells out to the underlying `codex` CLI, which must also be on PATH:
+To use Codex via ACP, both the `codex-acp` adapter and the underlying `codex` CLI must be on PATH:
+
+1. **Install the ACP adapter:**
+   ```bash
+   npm i -g @zed-industries/codex-acp
+   ```
+   This provides the `codex-acp` binary that the assistant spawns.
 
-1. **Install the Codex CLI** (version 0.111 or higher) via OpenAI's distribution channel of choice. The adapter will fail if `codex` isn't on PATH.
+2. **Install the Codex CLI** (version 0.111 or higher) via OpenAI's distribution channel of choice. The `codex-acp` adapter shells out to `codex` under the hood and will fail if it isn't on PATH.
 
-2. **Authenticate.** The `codex-acp` adapter inherits whatever auth the underlying `codex` CLI uses. Typical flows:
+3. **Authenticate.** The `codex-acp` adapter inherits whatever auth the underlying `codex` CLI uses. Typical flows:
    - `codex login` (OAuth)
    - `CODEX_API_KEY` environment variable
    - `OPENAI_API_KEY` environment variable
 
-## Gemini setup
-
-Gemini CLI speaks ACP natively (`gemini --acp`) - there is no separate adapter binary. The CLI itself is fetched from `@google/gemini-cli` when missing.
-
-**Authenticate** with an API key through the credential store (the primary path):
-
-```bash
-assistant credentials set --service acp --field gemini_api_key <key>
-```
-
-Or collect the key via the secret-request flow: `credential_store` with action `prompt`, service `acp`, field `gemini_api_key`. Either way the key never appears in chat or workspace config, and every spawn injects it as `GEMINI_API_KEY` automatically. The key is optional - a spawn proceeds without it when the vault has no entry.
-
-The alternative is browser OAuth: run `gemini` once interactively and complete the sign-in flow. This is impractical on hosted assistants (no browser), so prefer the credential store there.
-
-Do NOT put API keys (or any secret) in the workspace config file - secrets never belong in the workspace directory. Use the credential store instead.
-
-A workspace `acp.agents.gemini` override is only for non-secret customization (custom binary path, extra args, non-secret env vars). It must spell out the full `command` and `args` - see "Critical: correct agent command" below for the replace-not-merge rule:
-  ```json
-  {
-    "acp": {
-      "agents": {
-        "gemini": {
-          "command": "gemini",
-          "args": ["--acp"],
-          "env": { "NO_COLOR": "1" }
-        }
-      }
-    }
-  }
-  ```
+If `codex-acp` isn't on PATH when the user asks for it, the assistant will surface the install hint via `acp_list_agents`.
 
 ## Critical: correct agent command
 
-- Three agents are supported out-of-box: `claude` (via the `claude-agent-acp` adapter), `codex` (via the `codex-acp` adapter), and `gemini` (via `gemini --acp` - Gemini speaks ACP natively, no adapter binary).
-- NEVER use `claude`, `claude -p`, `claude --acp`, or the bare `codex` CLI as the ACP `command`. Claude and Codex only speak the protocol through their dedicated `*-acp` adapters. Gemini is the exception: the `gemini` CLI itself speaks ACP when launched with `--acp`.
-- Default profiles for all three ship out-of-box. Users only need an `agents.<id>` entry in config if they want to override the defaults (e.g. point to a custom binary path or pass extra args/env). An `acp.agents.<id>` entry replaces the bundled default entirely (no field merge), so any override must spell out the full `command` and `args`, not just the field being changed.
-- NEVER change an existing ACP config to use a different command. If the config already has `claude-agent-acp`, `codex-acp`, or `gemini`, leave it alone.
+- `claude-agent-acp` and `codex-acp` are the two supported adapter binaries today. They are what speak the ACP JSON-RPC protocol.
+- NEVER use `claude`, `claude -p`, `claude --acp`, the bare `codex` CLI, or any other command as the ACP `command`. Only the dedicated `*-acp` adapters speak the protocol.
+- Default profiles for `claude` and `codex` ship out-of-box. Users only need an `agents.<id>` entry in config if they want to override the defaults (e.g. point to a custom binary path or pass extra args).
+- NEVER change an existing ACP config to use a different command. If the config already has `claude-agent-acp` or `codex-acp`, leave it alone.
 
-## Updating an adapter
+## Updating the adapter
 
-This applies only to adapters installed globally via npm; adapters run via bun are fetched on first use and have no global install to update. If `acp_spawn` reports that an adapter is outdated, ask the user before updating. To update:
+If `acp_spawn` reports that an adapter is outdated, ask the user before updating. To update:
 
 ```bash
 npm i -g @agentclientprotocol/claude-agent-acp@latest
 # or
 npm i -g @zed-industries/codex-acp@latest
-# or
-npm i -g @google/gemini-cli@latest
 ```
 
 Then retry the `acp_spawn` call.
 
 ## When to use acp_steer vs acp_spawn
 
-- **On a running session, `acp_steer` interrupts the in-flight prompt.** Use it to course-correct ("stop, do X instead"). It cancels whatever the agent is currently working on and replaces it with the new instruction. Queued follow-ups behind a running prompt are not supported - wait for the `acp_session_completed` notification instead.
-- **On a completed (or assistant-restarted) session, `acp_steer` transparently resumes it.** The session is restored from persisted history via ACP session loading when the agent supports it, and the new instruction runs with the agent's full prior context. This is the primary way to do follow-up work on an existing session id - prefer it over spawning a fresh session that would lose context.
-- If resume isn't possible (the session was recorded before resume support and has no working directory, or the agent lacks the capability), the error explains why; fall back to `acp_spawn`. For claude sessions, the completion message also includes a `claude --resume <id>` CLI hint for resuming outside the assistant.
+- **`acp_steer` interrupts the in-flight prompt.** Use it to course-correct a running agent ("stop, do X instead"). It cancels whatever the agent is currently working on and replaces it with the new instruction.
+- **For follow-ups after the current task** ("also do Y when you're done"), do NOT use `acp_steer`. Wait for the `acp_session_completed` notification and call `acp_spawn` again with the new task. Queued follow-ups in the same session are not yet supported.
 
 ## Discoverability
 
-Use `acp_list_agents` to see what's set up and what's missing. It returns each available agent profile, whether ACP is enabled, whether the agent is runnable (its binary is on PATH, or the assistant can run it via bun), and an install hint if not. This is the right tool to call when deciding between `claude`, `codex`, and `gemini`, or when the user asks "what coding agents do I have?"
+Use `acp_list_agents` to see what's set up and what's missing. It returns each available agent profile, whether ACP is enabled, whether the agent's binary is on PATH, and an install hint if not. This is the right tool to call when deciding between `claude` and `codex`, or when the user asks "what coding agents do I have?"
 
 ## Working directory