@vellumai/assistant 0.8.11 → 0.8.12-staging.2

package/src/acp/agent-process.ts

@@ -10,6 +10,8 @@ import { Readable, Writable } from "node:stream";
 
 import type {
   Agent,
+  AuthMethod,
+  AuthMethodEnvVar,
   Client,
   InitializeResponse,
   NewSessionResponse,
@@ -22,6 +24,31 @@ import type { AcpAgentConfig } from "./types.js";
 
 const log = getLogger("acp");
 
+/**
+ * JSON-RPC error code agents use to signal that authentication is required
+ * (matches the SDK's RequestError.authRequired()).
+ */
+const AUTH_REQUIRED_CODE = -32000;
+
+/**
+ * Detects the ACP auth-required error. Checks the `code` property rather than
+ * `instanceof acp.RequestError` so plain JSON-RPC error objects are also
+ * recognized.
+ */
+function isAuthRequiredError(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as { code?: unknown }).code === AUTH_REQUIRED_CODE
+  );
+}
+
+function isEnvVarMethod(
+  method: AuthMethod,
+): method is AuthMethodEnvVar & { type: "env_var" } {
+  return "type" in method && method.type === "env_var";
+}
+
 /**
  * Factory function type for creating ACP client handlers.
  * PR 5 will provide the real VellumAcpClientHandler implementation.
@@ -35,6 +62,12 @@ export class AcpAgentProcess {
   private proc: ChildProcess | null = null;
   private connection: acp.ClientSideConnection | null = null;
   private initializeResponse: InitializeResponse | null = null;
+  /**
+   * Merged env captured at spawn() so auth satisfiability checks match the
+   * env the child process actually received, even if process.env changes
+   * afterwards.
+   */
+  private spawnedEnv: NodeJS.ProcessEnv | null = null;
 
   constructor(
     public readonly agentId: string,
@@ -51,10 +84,11 @@ export class AcpAgentProcess {
       "Spawning ACP agent process",
     );
 
+    this.spawnedEnv = { ...process.env, ...this.config.env };
     this.proc = spawn(this.config.command, this.config.args, {
       cwd,
       stdio: ["pipe", "pipe", "pipe"],
-      env: { ...process.env, ...this.config.env },
+      env: this.spawnedEnv,
     });
 
     const stream = acp.ndJsonStream(
@@ -94,13 +128,11 @@ export class AcpAgentProcess {
    * Initializes the ACP connection by negotiating protocol version and capabilities.
    */
   async initialize(): Promise<InitializeResponse> {
-    if (!this.connection) {
-      throw new Error(`ACP agent "${this.agentId}" is not spawned`);
-    }
+    const connection = this.requireConnection();
 
     log.info({ agentId: this.agentId }, "Initializing ACP connection");
 
-    const response = await this.connection.initialize({
+    const response = await connection.initialize({
       protocolVersion: acp.PROTOCOL_VERSION,
       clientInfo: { name: "vellum", version: "1.0.0" },
       clientCapabilities: {
@@ -133,20 +165,119 @@ export class AcpAgentProcess {
   }
 
   /**
-   * Creates a new ACP session in the specified working directory.
-   * Returns the session ID.
+   * Authentication methods the agent advertised at initialize.
+   * Returns an empty array before initialize() resolves.
    */
-  async createSession(cwd: string): Promise<string> {
+  private get authMethods(): AuthMethod[] {
+    return this.initializeResponse?.authMethods ?? [];
+  }
+
+  /**
+   * Selects the first advertised env_var auth method whose required variables
+   * are all present (non-empty) in the env the agent process was spawned with.
+   *
+   * Terminal-type and agent-driven (untyped) methods are never selected:
+   * auto-triggering an interactive login would hang the headless daemon.
+   */
+  private selectEnvVarAuthMethod(): AuthMethod | undefined {
+    const env = this.spawnedEnv;
+    if (!env) return undefined;
+
+    return this.authMethods.find((method) => {
+      if (!isEnvVarMethod(method)) return false;
+
+      // `vars` is required by the SDK type, but agent responses aren't
+      // runtime-validated — tolerate an out-of-spec agent omitting it so the
+      // caller gets the friendly auth error instead of a TypeError.
+      const requiredVars = (method.vars ?? []).filter((v) => !v.optional);
+      if (requiredVars.length === 0) return false;
+
+      return requiredVars.every((v) => {
+        const value = env[v.name];
+        return typeof value === "string" && value.length > 0;
+      });
+    });
+  }
+
+  /**
+   * Returns the live connection, throwing the standard not-spawned error if
+   * the agent was never spawned or its process has since exited.
+   */
+  private requireConnection(): acp.ClientSideConnection {
     if (!this.connection) {
       throw new Error(`ACP agent "${this.agentId}" is not spawned`);
     }
+    return this.connection;
+  }
+
+  /**
+   * Runs an operation, and if the agent rejects with the ACP auth-required
+   * error, authenticates via a satisfiable env_var auth method and retries
+   * the operation exactly once.
+   */
+  private async withAuthRetry<T>(op: () => Promise<T>): Promise<T> {
+    try {
+      return await op();
+    } catch (err) {
+      if (!isAuthRequiredError(err)) throw err;
+
+      // The agent may have exited between the auth_required rejection and
+      // this retry path; fail with the standard not-spawned error.
+      const connection = this.requireConnection();
+
+      const method = this.selectEnvVarAuthMethod();
+      if (!method) {
+        throw new Error(
+          `ACP agent "${this.agentId}" requires authentication. ` +
+            `Advertised methods: ${this.describeAuthMethods()}. ` +
+            "Set the required env var under acp.agents.<id>.env in config.json, " +
+            "store it via 'assistant credentials set --service acp --field <field>', " +
+            "or complete the agent's own login flow in the workspace.",
+        );
+      }
+
+      log.info(
+        { agentId: this.agentId, methodId: method.id },
+        "ACP agent returned auth_required; authenticating with env_var method",
+      );
 
+      await connection.authenticate({ methodId: method.id });
+      return await op();
+    }
+  }
+
+  /**
+   * Renders the agent's advertised auth methods for error messages, e.g.
+   * `"Login with ChatGPT" (chatgpt), "Use OPENAI_API_KEY" (env var OPENAI_API_KEY)`.
+   */
+  private describeAuthMethods(): string {
+    if (this.authMethods.length === 0) return "none";
+
+    return this.authMethods
+      .map((method) => {
+        // `vars ?? []`: tolerate out-of-spec agents omitting the field —
+        // this renders inside the friendly auth error, which must not
+        // itself throw a TypeError.
+        const varNames = isEnvVarMethod(method)
+          ? (method.vars ?? []).map((v) => v.name).join(", ")
+          : "";
+        return varNames
+          ? `"${method.name}" (env var ${varNames})`
+          : `"${method.name}" (${method.id})`;
+      })
+      .join(", ");
+  }
+
+  /**
+   * Creates a new ACP session in the specified working directory.
+   * Returns the session ID.
+   */
+  async createSession(cwd: string): Promise<string> {
     log.info({ agentId: this.agentId, cwd }, "Creating ACP session");
 
-    const result: NewSessionResponse = await this.connection.newSession({
-      cwd,
-      mcpServers: [],
-    });
+    const result: NewSessionResponse = await this.withAuthRetry(() =>
+      this.requireConnection().newSession({ cwd, mcpServers: [] }),
+    );
 
     return result.sessionId;
   }
@@ -160,13 +291,11 @@ export class AcpAgentProcess {
    * VellumAcpClientHandler.beginReplaySuppression).
    */
   async loadSession(sessionId: string, cwd: string): Promise<void> {
-    if (!this.connection) {
-      throw new Error(`ACP agent "${this.agentId}" is not spawned`);
-    }
-
     log.info({ agentId: this.agentId, sessionId, cwd }, "Loading ACP session");
 
-    await this.connection.loadSession({ sessionId, cwd, mcpServers: [] });
+    await this.withAuthRetry(() =>
+      this.requireConnection().loadSession({ sessionId, cwd, mcpServers: [] }),
+    );
   }
 
   /**
@@ -177,13 +306,15 @@ export class AcpAgentProcess {
    * (see supportsSessionResume).
    */
   async resumeSession(sessionId: string, cwd: string): Promise<void> {
-    if (!this.connection) {
-      throw new Error(`ACP agent "${this.agentId}" is not spawned`);
-    }
-
     log.info({ agentId: this.agentId, sessionId, cwd }, "Resuming ACP session");
 
-    await this.connection.resumeSession({ sessionId, cwd, mcpServers: [] });
+    await this.withAuthRetry(() =>
+      this.requireConnection().resumeSession({
+        sessionId,
+        cwd,
+        mcpServers: [],
+      }),
+    );
   }
 
   /**
@@ -191,35 +322,31 @@ export class AcpAgentProcess {
    * Returns the prompt response (includes stopReason).
    */
   async prompt(sessionId: string, text: string): Promise<PromptResponse> {
-    if (!this.connection) {
-      throw new Error(`ACP agent "${this.agentId}" is not spawned`);
-    }
-
     log.info(
       { agentId: this.agentId, sessionId },
       "Sending prompt to ACP agent",
     );
 
-    return this.connection.prompt({
-      sessionId,
-      prompt: [{ type: "text", text }],
-    });
+    return this.withAuthRetry(() =>
+      this.requireConnection().prompt({
+        sessionId,
+        prompt: [{ type: "text", text }],
+      }),
+    );
   }
 
   /**
    * Cancels an ongoing prompt in the specified session.
    */
   async cancel(sessionId: string): Promise<void> {
-    if (!this.connection) {
-      throw new Error(`ACP agent "${this.agentId}" is not spawned`);
-    }
+    const connection = this.requireConnection();
 
     log.info(
       { agentId: this.agentId, sessionId },
       "Cancelling ACP session prompt",
     );
 
-    await this.connection.cancel({ sessionId });
+    await connection.cancel({ sessionId });
   }
 
   /**
@@ -234,6 +361,7 @@ export class AcpAgentProcess {
     }
     this.connection = null;
     this.initializeResponse = null;
+    this.spawnedEnv = null;
   }
 
   /**
@@ -265,5 +393,6 @@ export class AcpAgentProcess {
     this.proc = null;
     this.connection = null;
     this.initializeResponse = null;
+    this.spawnedEnv = null;
   }
 }

package/src/acp/prepare-agent-env.ts

@@ -93,6 +93,32 @@ async function injectCredential(
   return result.success ? undefined : result.reason;
 }
 
+/**
+ * Inject an OPTIONAL credential: skip when the env var is already set
+ * (config.json override wins), and treat a vault miss as non-fatal — the
+ * adapter has its own login fallback, so spawning without the key is fine.
+ */
+async function injectOptionalCredential(
+  env: Record<string, string>,
+  field: string,
+  envVar: string,
+  usageDescription: string,
+): Promise<void> {
+  if (env[envVar]) return;
+  const missReason = await injectCredential(
+    env,
+    field,
+    envVar,
+    usageDescription,
+  );
+  if (missReason !== undefined) {
+    log.debug(
+      { reason: missReason },
+      `${envVar} unavailable from the vault; spawning without it`,
+    );
+  }
+}
+
 /**
  * Returns a NEW config with any required credentials merged into `env`.
  * Does NOT mutate the input. Throws `FailedDependencyError` if a required
@@ -123,6 +149,13 @@ async function injectCredential(
  * ways (config.json override wins, vault field `gemini_api_key` second),
  * but it is OPTIONAL: the Gemini CLI supports its own OAuth login, so a
  * vault miss proceeds without the key instead of failing the spawn.
+ *
+ * For `codex-acp` the env vars are `OPENAI_API_KEY` (vault field
+ * `acp/openai_api_key`) and `CODEX_API_KEY` (vault field
+ * `acp/codex_api_key`), provisioned the same two ways (config.json
+ * override wins, vault second). Both are OPTIONAL: codex also supports
+ * ChatGPT login (`codex login` pre-seeding `auth.json` in the workspace),
+ * so a vault miss proceeds without the key instead of failing the spawn.
  */
 export async function prepareAgentEnv(
   agentConfig: AcpAgentConfig,
@@ -150,22 +183,29 @@ export async function prepareAgentEnv(
       );
     }
   } else if (adapterCommand === "gemini") {
-    if (!env.GEMINI_API_KEY) {
-      const missReason = await injectCredential(
+    await injectOptionalCredential(
+      env,
+      "gemini_api_key",
+      "GEMINI_API_KEY",
+      "Gemini API key for ACP agent authentication",
+    );
+  } else if (adapterCommand === "codex-acp") {
+    // The two reads target independent vault fields and write disjoint env
+    // keys, so running them concurrently is safe.
+    await Promise.all([
+      injectOptionalCredential(
         env,
-        "gemini_api_key",
-        "GEMINI_API_KEY",
-        "Gemini API key for ACP agent authentication",
-      );
-      if (missReason !== undefined) {
-        // Optional credential: Gemini CLI can authenticate via its own
-        // OAuth login, so a vault miss must not fail the spawn.
-        log.debug(
-          { reason: missReason },
-          "Gemini API key unavailable from the vault; spawning without GEMINI_API_KEY",
-        );
-      }
-    }
+        "openai_api_key",
+        "OPENAI_API_KEY",
+        "OpenAI API key for Codex ACP agent authentication",
+      ),
+      injectOptionalCredential(
+        env,
+        "codex_api_key",
+        "CODEX_API_KEY",
+        "Codex API key for Codex ACP agent authentication",
+      ),
+    ]);
   }
 
   return { ...agentConfig, env };

package/src/agent/loop.ts

@@ -11,6 +11,7 @@ import {
   estimateToolsTokens,
   getCalibrationProviderKey,
 } from "../context/token-estimator.js";
+import { spoolAndStubOversizedToolResults } from "../context/tool-result-spool.js";
 import type { ToolActivityMetadata } from "../daemon/message-types/web-activity.js";
 import { parseActualTokensFromError } from "../daemon/parse-actual-tokens-from-error.js";
 import type { TrustContext } from "../daemon/trust-context.js";
@@ -298,25 +299,27 @@ export type AgentEvent =
       /** The running history before injection stripping and compaction. */
       messages: Message[];
     }
-  | {
+  | ({
       /**
        * Emitted after the loop's inline mid-loop compaction pipeline runs,
        * immediately before re-injection — whether or not the pipeline actually
-       * compacted. The daemon's event dispatcher always commits `messages` (the
-       * stripped pre-compaction history) as the conversation's durable message
-       * state, so re-injection (the post-compaction hook) re-applies
-       * injections onto the stripped base rather than stacking on top of the
-       * still-injected messages. When `result.compacted` is set it
-       * additionally commits the durable compaction result (DB-record fields,
-       * graph-memory side effects, SSE) and flips the per-turn re-injection
-       * guards on the handler state.
+       * compacted. Carries the pipeline's `ContextWindowResult` unnested into
+       * the event, so `messages` here is the pipeline's output history. The
+       * pre-compaction history lives on the paired `context_compacting` start
+       * event (correlated by `compactionId`); consumers that need the
+       * stripped pre-compaction base re-derive it from the start event via
+       * `stripInjectionsForCompaction`.
+       *
+       * The daemon's event dispatcher commits the stripped pre-compaction
+       * base as the conversation's durable message state, so re-injection
+       * (the post-compaction hook) re-applies injections onto the stripped
+       * base rather than stacking on top of the still-injected messages.
+       * When `compacted` is set it additionally commits the durable
+       * compaction result (DB-record fields, graph-memory side effects, SSE)
+       * and projects Slack provenance from the pre-compaction base.
        *
        * Treated as a critical event: a failed durable commit re-throws so the
        * turn aborts rather than re-injecting against half-applied state.
-       *
-       * `messages` is the stripped pre-compaction history the summary was
-       * built from; the dispatcher uses it to project Slack provenance onto
-       * the compacted result.
        */
       type: "compaction_completed";
       /** Correlates this end event with its `context_compacting` pair. */
@@ -330,9 +333,7 @@ export type AgentEvent =
       startedAt: number;
       /** Epoch ms when the compaction pipeline returned. */
       finishedAt: number;
-      result: ContextWindowResult;
-      messages: Message[];
-    }
+    } & ContextWindowResult)
   | {
       /**
        * Emitted right after the loop strips runtime injections from the
@@ -595,6 +596,16 @@ export interface AgentLoopConstructorOptions {
    * post-compaction re-injection resolve the live conversation through.
    */
   conversationId: string;
+  /**
+   * Resolve the conversation's on-disk directory, used to spool oversized
+   * tool results to `.tool-results/` and swap the inline copy for the
+   * post-turn pass's stub at result time — before the result joins history,
+   * so the provider-bound prefix stays append-only for prompt caching.
+   * Returns `null` while the directory cannot be resolved (e.g. the
+   * conversation row is not yet persisted); the loop then skips the
+   * result-time pass and the post-turn truncation covers the turn instead.
+   */
+  resolveConversationDir?: () => string | null;
 }
 
 export class AgentLoop {
@@ -616,6 +627,9 @@ export class AgentLoop {
    */
   private readonly conversationId: string;
 
+  /** See {@link AgentLoopConstructorOptions.resolveConversationDir}. */
+  private readonly resolveConversationDir: (() => string | null) | null;
+
   /**
    * Loop-held compaction circuit breaker. The loop has a 1:1 lifetime with its
    * conversation, so it is the source of truth for the cross-turn failure
@@ -635,6 +649,7 @@ export class AgentLoop {
       resolveTools,
       resolveSystemPrompt,
       conversationId,
+      resolveConversationDir,
     } = options;
     this.provider = provider;
     this.systemPrompt = systemPrompt;
@@ -644,6 +659,7 @@ export class AgentLoop {
     this.resolveSystemPrompt = resolveSystemPrompt ?? null;
     this.toolExecutor = toolExecutor ?? null;
     this.conversationId = conversationId;
+    this.resolveConversationDir = resolveConversationDir ?? null;
     this.compactionCircuit = new CompactionCircuit(this.conversationId);
   }
 
@@ -782,10 +798,10 @@ export class AgentLoop {
         onEvent,
       );
     }
-    // Emit unconditionally: the dispatcher commits the stripped `messages` as the
-    // durable message base whether or not the pipeline compacted (re-injection
-    // reads it), and runs the durable compaction commit only when
-    // `result.compacted`.
+    // Emit unconditionally: the dispatcher commits the stripped pre-compaction
+    // base (re-derived from the start event) as the durable message base
+    // whether or not the pipeline compacted (re-injection reads it), and runs
+    // the durable compaction commit only when `compacted`.
     await onEvent({
       type: "compaction_completed",
       compactionId,
@@ -793,8 +809,7 @@ export class AgentLoop {
       trigger,
       startedAt,
       finishedAt: Date.now(),
-      result: compactResult,
-      messages: rawHistory,
+      ...compactResult,
     });
     const exhausted = compactResult.exhausted ?? false;
     const autoCompressApplied = compactResult.autoCompressApplied ?? false;
@@ -886,6 +901,19 @@ export class AgentLoop {
     let overflowAutoCompressApplied = false;
     const rlog = log.child({ requestId });
 
+    // Conversation directory for the result-time tool-result spool/stub pass.
+    // Resolved once per run; `null` disables the pass for this run and the
+    // post-turn truncation covers the turn instead.
+    let conversationDir: string | null = null;
+    try {
+      conversationDir = this.resolveConversationDir?.() ?? null;
+    } catch (err) {
+      rlog.warn(
+        { err },
+        "Resolving conversation dir for tool-result spooling failed (non-fatal)",
+      );
+    }
+
     // Resolve the inference-profile override that applies right now. The
     // optional resolver lets a turn observe a confirmed mid-turn profile switch
     // before the next model call; absent a resolver the turn-start value holds.
@@ -1724,11 +1752,39 @@ export class AgentLoop {
           }),
         );
 
+        // Spool oversized results to `.tool-results/` and swap the inline
+        // copy for the post-turn pass's stub now — on the raw blocks, before
+        // the post-tool-use hooks, event emission, and history append. Running
+        // ahead of the hooks means the spooled file holds the tool's full
+        // output rather than the truncate plugin's tail-dropped copy, and the
+        // hooks then see the stub. Stubbing before the first send keeps the
+        // provider-bound history strictly append-only (rewriting an earlier
+        // message between calls would invalidate the prompt-cache prefix on
+        // every iteration).
+        if (conversationDir) {
+          const toolNameByUseId = new Map(
+            toolUseBlocks.map((tu) => [tu.id, tu.name]),
+          );
+          try {
+            spoolAndStubOversizedToolResults(rawResultBlocks, {
+              conversationDir,
+              toolNameById: (id) => toolNameByUseId.get(id),
+            });
+          } catch (err) {
+            rlog.warn(
+              { err, turn: toolUseTurns },
+              "Spooling oversized tool results to disk failed (non-fatal)",
+            );
+          }
+        }
+
         // Run the `post-tool-use` hook once per tool result, after the tool
         // returns and before the result joins the provider-bound history.
         // The default tool-result-truncate plugin tail-drops oversized output
-        // to fit the context window; user hooks can swap in a smarter strategy
-        // (e.g. a summariser) or observe results for side effects.
+        // to fit the context window (spool-stubbed results are already tiny;
+        // spool-exempt ones still rely on it); user hooks can swap in a
+        // smarter strategy (e.g. a summariser) or observe results for side
+        // effects.
         const contextWindowTokens =
           resolveContextWindow?.().maxInputTokens ??
           this.config.maxInputTokens ??
@@ -1746,6 +1802,7 @@ export class AgentLoop {
             toolResponse: block as ToolResultContent,
             messages: history,
             additionalContext: null,
+            model: response.model,
             maxInputTokens: contextWindowTokens,
             logger: rlog,
           };

package/src/api/events/usage-progress.ts

@@ -0,0 +1,28 @@
+/**
+ * `usage_progress` SSE event.
+ *
+ * Emitted after each LLM call with per-call token deltas and estimated
+ * cost. Clients accumulate these additively for live-updating usage
+ * metrics (e.g. inline subagent token counters). A UI-only hint — it
+ * does not persist to the DB or affect billing.
+ *
+ * Unlike `usage_update`, which carries the conversation's running
+ * totals, this event carries only the deltas for a single LLM call.
+ *
+ * Canonical wire-contract source. Daemon code imports the type
+ * directly from this file; external consumers import via
+ * `@vellumai/assistant-api`.
+ */
+
+import { z } from "zod";
+
+export const UsageProgressEventSchema = z.object({
+  type: z.literal("usage_progress"),
+  conversationId: z.string(),
+  inputTokens: z.number(),
+  outputTokens: z.number(),
+  estimatedCost: z.number(),
+  model: z.string(),
+});
+
+export type UsageProgressEvent = z.infer<typeof UsageProgressEventSchema>;

package/src/api/index.ts

@@ -49,6 +49,7 @@ import { UISurfaceCompleteEventSchema } from "./events/ui-surface-complete.js";
 import { UISurfaceDismissEventSchema } from "./events/ui-surface-dismiss.js";
 import { UISurfaceShowEventSchema } from "./events/ui-surface-show.js";
 import { UISurfaceUpdateEventSchema } from "./events/ui-surface-update.js";
+import { UsageProgressEventSchema } from "./events/usage-progress.js";
 import { UsageUpdateEventSchema } from "./events/usage-update.js";
 import { UserMessageEchoEventSchema } from "./events/user-message-echo.js";
 
@@ -310,6 +311,10 @@ export {
   type UISurfaceUpdateEvent,
   UISurfaceUpdateEventSchema,
 } from "./events/ui-surface-update.js";
+export {
+  type UsageProgressEvent,
+  UsageProgressEventSchema,
+} from "./events/usage-progress.js";
 export {
   type UsageUpdateEvent,
   UsageUpdateEventSchema,
@@ -497,6 +502,7 @@ export const AssistantEventSchema = z.discriminatedUnion("type", [
   UISurfaceDismissEventSchema,
   UISurfaceShowEventSchema,
   UISurfaceUpdateEventSchema,
+  UsageProgressEventSchema,
   UsageUpdateEventSchema,
   UserMessageEchoEventSchema,
 ]);

package/src/background-wake/wake-intent-hooks.test.ts

@@ -52,6 +52,8 @@ mock.module("../util/platform.js", () => ({
   getWorkspaceRoutesDir: () => workspacePath("routes"),
   vellumRoot: () => testWorkspaceDir,
   getDataDir: () => workspacePath("data"),
+  getConfigQuarantineNoticePath: () =>
+    workspacePath("data", "config-quarantine-notice.json"),
   getDbPath: () => workspacePath("data", "db", "assistant.db"),
   ensureDataDir: () => {
     mkdirSync(workspacePath("data", "db"), { recursive: true });