@vellumai/assistant 0.11.3 → 0.11.4-staging.1

package/src/acp/agent-process.ts

@@ -20,16 +20,11 @@ import type {
 import * as acp from "@agentclientprotocol/sdk";
 
 import { getLogger } from "../util/logger.js";
+import { AcpAuthRequiredError, isAcpAuthRequired } from "./auth-required.js";
 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;
-
 /**
  * Rough byte cap for retained stderr. Oldest lines are evicted once the sum of
  * retained line lengths exceeds this, so the stderr ring (read via stderrSince)
@@ -37,19 +32,6 @@ const AUTH_REQUIRED_CODE = -32000;
  */
 const STDERR_RETENTION_BYTES = 4096;
 
-/**
- * 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" } {
@@ -296,7 +278,7 @@ export class AcpAgentProcess {
     try {
       return await op();
     } catch (err) {
-      if (!isAuthRequiredError(err)) {
+      if (!isAcpAuthRequired(err)) {
         throw err;
       }
 
@@ -306,12 +288,23 @@ export class AcpAgentProcess {
 
       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, " +
-            "collect it securely via 'assistant credentials prompt --service acp --field <field> --label \"<label>\"', " +
-            "or complete the agent's own login flow in the workspace.",
+        // Typed so the session manager can tell an auth failure from a crash
+        // and surface a re-authentication path. The remediation text is split
+        // by what the agent advertises: env-var and `credentials prompt`
+        // advice only helps when an env_var method exists to satisfy, and for
+        // terminal-login-only adapters it sends the user chasing a CLI
+        // workaround for a credential the app repairs on its own.
+        throw new AcpAuthRequiredError(
+          this.agentId,
+          this.hasEnvVarAuthMethod()
+            ? `ACP agent "${this.agentId}" requires authentication. ` +
+                `Advertised methods: ${this.describeAuthMethods()}. ` +
+                "Set the required env var under acp.agents.<id>.env in config.json, " +
+                "or collect it securely via 'assistant credentials prompt --service acp --field <field> --label \"<label>\"'."
+            : `ACP agent "${this.agentId}" requires authentication and its ` +
+                "stored credential was not accepted. Advertised methods: " +
+                `${this.describeAuthMethods()}. None can be completed headlessly, ` +
+                "so the credential has to be reconnected.",
         );
       }
 
@@ -325,6 +318,16 @@ export class AcpAgentProcess {
     }
   }
 
+  /**
+   * Whether the agent advertises any `env_var` auth method at all, satisfiable
+   * or not. Distinguishes "we could not satisfy the env var it wants" from
+   * "env vars are not how this agent authenticates", which are different
+   * problems with different fixes.
+   */
+  private hasEnvVarAuthMethod(): boolean {
+    return this.authMethods.some(isEnvVarMethod);
+  }
+
   /**
    * 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)`.

package/src/acp/auth-required.ts

@@ -0,0 +1,102 @@
+/**
+ * Detection of Claude authentication failures on ACP runs.
+ *
+ * These failures reach the daemon in two shapes, and both are needed:
+ *
+ * 1. No credentials at all: the adapter raises a structured ACP
+ *    `auth_required` rejection (JSON-RPC -32000). {@link isAcpAuthRequired}.
+ * 2. Credentials present but rejected (the expired/revoked case): the CLI
+ *    surfaces the API 401 as an error message it authors, and the adapter
+ *    relays it as a generic -32603 internal error, NOT as `auth_required`.
+ *    {@link isClaudeAuthFailureMessage}.
+ *
+ * A positive detection becomes {@link ACP_CLAUDE_AUTH_REQUIRED_CODE} on the
+ * `acp_auth_required` event, which the client turns into the inline
+ * "Connect Claude Code" card.
+ */
+
+export { ACP_CLAUDE_AUTH_REQUIRED_CODE } from "../api/events/acp-auth-required.js";
+
+/**
+ * JSON-RPC error code agents use to signal that authentication is required
+ * (matches the ACP SDK's `RequestError.authRequired()`).
+ */
+export const AUTH_REQUIRED_CODE = -32000;
+
+/**
+ * An agent rejected an operation with `auth_required` and the daemon has no
+ * way to satisfy it. A distinct type so the classification survives to the
+ * session manager, where the failure becomes an event the UI can act on.
+ */
+export class AcpAuthRequiredError extends Error {
+  constructor(
+    readonly agentId: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "AcpAuthRequiredError";
+  }
+}
+
+/**
+ * Detects the structured auth-required signal in either shape it travels: the
+ * raw JSON-RPC rejection from the agent, or our own
+ * {@link AcpAuthRequiredError}. Checks the `code` property rather than an
+ * `instanceof` so plain JSON-RPC error objects are recognized too.
+ */
+export function isAcpAuthRequired(err: unknown): boolean {
+  if (err instanceof AcpAuthRequiredError) {
+    return true;
+  }
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as { code?: unknown }).code === AUTH_REQUIRED_CODE
+  );
+}
+
+/**
+ * The Claude CLI's own auth-failure phrasings. Unanchored (no ^/$) because
+ * the messages arrive with adapter framing ("Internal error: ...") or as a
+ * line `deriveFailureError` picked out of stderr.
+ */
+const CLAUDE_AUTH_FAILURE_PATTERNS: readonly RegExp[] = [
+  /Failed to authenticate\b/,
+  /Please run \/login/,
+  /\bNot logged in\b/,
+];
+
+/**
+ * Whether a failure message is a Claude authentication failure. Callers gate
+ * on the adapter (`claude-agent-acp`) BEFORE consulting this: the patterns
+ * are Claude-specific, and the marker built on them promises a repair only
+ * the Connect Claude flow can perform.
+ */
+export function isClaudeAuthFailureMessage(
+  message: string | undefined,
+): boolean {
+  return (
+    message != null &&
+    CLAUDE_AUTH_FAILURE_PATTERNS.some((pattern) => pattern.test(message))
+  );
+}
+
+/** The adapter whose auth failures the Connect Claude flow can repair. */
+export const CLAUDE_ACP_COMMAND = "claude-agent-acp";
+
+/**
+ * Model-facing text accompanying a Claude auth failure wherever the inline
+ * Connect card is raised (the tool result for a pre-spawn rejection, the
+ * parent notification for a post-spawn one), so the model points at the card
+ * instead of inventing a remedy (CLI commands, pasted tokens, or a card that
+ * is not there). Bans placement words because card position is a UI detail
+ * the model cannot see.
+ */
+export const ACP_AUTH_RECOVERY_GUIDANCE =
+  "The Claude Code connection needs to be re-authorized. The app shows the " +
+  'user an inline "Connect Claude Code" card. Reply with ONE short sentence: ' +
+  "ask them to click Connect to sign in again, and tell them you'll continue " +
+  "automatically once they are connected. Do NOT say where the card is; never " +
+  'say "below", "above", "at the bottom", or "here". Do NOT tell them to run ' +
+  "`claude setup-token`, paste a token in chat, run credential CLI commands, " +
+  "or re-run the agent yourself; the card and auto-continue handle it.";

package/src/acp/session-manager.test.ts

@@ -5,6 +5,7 @@ import {
   deleteConversation,
   setConversation,
 } from "../daemon/conversation-registry.js";
+import { hasAcpConnectCardRaised } from "./acp-connect-card-state.js";
 import { VellumAcpClientHandler } from "./client-handler.js";
 import { AcpSessionManager } from "./session-manager.js";
 
@@ -310,3 +311,121 @@ describe("AcpSessionManager parent notification", () => {
     expect((manager.getStatus() as unknown[]).length).toBe(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Auth-required recovery surface
+// ---------------------------------------------------------------------------
+
+describe("AcpSessionManager auth-required recovery surface", () => {
+  /** The live-captured shape of a rejected-credential failure. */
+  const authFailure = () =>
+    Promise.reject(
+      new Error(
+        "Internal error: Failed to authenticate. API Error: 401 OAuth access token has been revoked.",
+      ),
+    );
+
+  /** Drives an auth-shaped prompt failure through firePromptInBackground. */
+  async function driveAuthFailure(opts: {
+    id: string;
+    command: string;
+    parentToolUseId?: string;
+    cancelled?: boolean;
+  }) {
+    const manager = new AcpSessionManager(1);
+    const parentId = `parent-${opts.id}`;
+    const { conversation, persistUserMessage, loopRan } = mockConversation();
+    setConversation(parentId, conversation);
+    registered.push(parentId);
+
+    const entry = injectSession(
+      manager,
+      opts.id,
+      parentId,
+      fakeProcess(authFailure),
+    );
+    entry.command = opts.command;
+    (entry as { parentToolUseId?: string }).parentToolUseId =
+      opts.parentToolUseId;
+    if (opts.cancelled) {
+      entry.state.status = "cancelled";
+    }
+
+    await fire(manager, opts.id, entry).catch(() => {});
+    if (!opts.cancelled) {
+      await loopRan;
+    }
+
+    const events = (
+      entry.sendToVellum as ReturnType<typeof mock>
+    ).mock.calls.map((c) => c[0] as { type: string } & Record<string, unknown>);
+    const firstPersist = persistUserMessage.mock.calls[0] as unknown as
+      | [{ content: string }]
+      | undefined;
+    return {
+      parentId,
+      authEvent: events.find((e) => e.type === "acp_auth_required"),
+      persistedContent: firstPersist?.[0].content,
+    };
+  }
+
+  test("claude failure with an anchor raises the full surface: event, registry mark, guidance", async () => {
+    const r = await driveAuthFailure({
+      id: "sess-auth-anchor",
+      command: "claude-agent-acp",
+      parentToolUseId: "tool-anchor-1",
+    });
+
+    expect(r.authEvent).toMatchObject({
+      acpSessionId: "sess-auth-anchor",
+      authCode: "acp_claude_auth_required",
+      agent: "claude",
+      parentToolUseId: "tool-anchor-1",
+    });
+    // The credential-prompt route consults this registry to redirect a
+    // redundant secure prompt at the card instead of stacking a second one.
+    expect(hasAcpConnectCardRaised(r.parentId)).toBe(true);
+    expect(r.persistedContent).toContain("Connect Claude Code");
+  });
+
+  test("claude failure without an anchor keeps the plain failure: no event, no mark, no guidance", async () => {
+    // No spawning tool call means no transcript row to render the card under;
+    // guidance would point the model at a card that cannot appear.
+    const r = await driveAuthFailure({
+      id: "sess-auth-noanchor",
+      command: "claude-agent-acp",
+    });
+
+    expect(r.authEvent).toBeUndefined();
+    expect(hasAcpConnectCardRaised(r.parentId)).toBe(false);
+    expect(r.persistedContent).not.toContain("Connect Claude Code");
+  });
+
+  test("a run the user already stopped raises nothing: no event, no registry mark, no parent turn", async () => {
+    // The client never renders a card for a cancelled run, and the
+    // prompt-dedup registry is never cleared, so marking it here would
+    // suppress the secure token prompt for the daemon's lifetime against a
+    // card that does not exist.
+    const r = await driveAuthFailure({
+      id: "sess-auth-cancelled",
+      command: "claude-agent-acp",
+      parentToolUseId: "tool-anchor-3",
+      cancelled: true,
+    });
+
+    expect(r.authEvent).toBeUndefined();
+    expect(hasAcpConnectCardRaised(r.parentId)).toBe(false);
+    expect(r.persistedContent).toBeUndefined();
+  });
+
+  test("a non-claude adapter never raises the surface, even on an auth-shaped failure", async () => {
+    const r = await driveAuthFailure({
+      id: "sess-auth-codex",
+      command: "codex-acp",
+      parentToolUseId: "tool-anchor-2",
+    });
+
+    expect(r.authEvent).toBeUndefined();
+    expect(hasAcpConnectCardRaised(r.parentId)).toBe(false);
+  });
+});

package/src/acp/session-manager.ts

@@ -15,7 +15,15 @@ import { getDb } from "../persistence/db-connection.js";
 import { acpSessionHistory } from "../persistence/schema/index.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
 import { getLogger } from "../util/logger.js";
+import { markAcpConnectCardRaised } from "./acp-connect-card-state.js";
 import { AcpAgentProcess } from "./agent-process.js";
+import {
+  ACP_AUTH_RECOVERY_GUIDANCE,
+  ACP_CLAUDE_AUTH_REQUIRED_CODE,
+  CLAUDE_ACP_COMMAND,
+  isAcpAuthRequired,
+  isClaudeAuthFailureMessage,
+} from "./auth-required.js";
 import { resolveAgentWithAutoInstall } from "./auto-install.js";
 import { VellumAcpClientHandler } from "./client-handler.js";
 import { deriveFailureError } from "./failure-error.js";
@@ -26,6 +34,30 @@ import type { AcpAgentConfig, AcpSessionState } from "./types.js";
 
 const log = getLogger("acp:session-manager");
 
+/**
+ * The `authCode` for a run that failed on its Claude credential, or undefined
+ * for any other failure. Adapter-gated first: the signals are Claude-specific,
+ * and the marker promises a repair only the Connect Claude flow can perform.
+ * Checks both auth-failure shapes (see `auth-required.ts`) against both the
+ * raw rejection and the derived failure message, since `deriveFailureError`
+ * may replace one with the other.
+ */
+function claudeAuthRequiredCode(
+  err: unknown,
+  failureMessage: string,
+  entry: { command: string },
+): string | undefined {
+  if (entry.command !== CLAUDE_ACP_COMMAND) {
+    return undefined;
+  }
+  const rawMessage = err instanceof Error ? err.message : String(err);
+  return isAcpAuthRequired(err) ||
+    isClaudeAuthFailureMessage(rawMessage) ||
+    isClaudeAuthFailureMessage(failureMessage)
+    ? ACP_CLAUDE_AUTH_REQUIRED_CODE
+    : undefined;
+}
+
 /**
  * The manager's "unknown session id" error. Thrown whenever an operation
  * references an acpSessionId with no in-memory entry (and, for resume, no
@@ -1093,6 +1125,11 @@ export class AcpSessionManager {
             err.message,
             current.process.stderrSince(stderrMark),
           );
+          const errorCode = claudeAuthRequiredCode(
+            err,
+            failureMessage,
+            current,
+          );
           if (current.state.status !== "cancelled") {
             current.state.status = "failed";
             current.state.completedAt = Date.now();
@@ -1100,14 +1137,40 @@ export class AcpSessionManager {
           }
           current.currentPrompt = null;
           log.error(
-            { acpSessionId, error: err.message, failureMessage },
+            { acpSessionId, error: err.message, failureMessage, errorCode },
             "ACP prompt failed",
           );
+          // `acp_session_error` keeps its pre-existing shape so older packaged
+          // clients still parse it; the recovery signal rides its own event
+          // below (see `api/events/acp-auth-required.ts`).
           current.sendToVellum({
             type: "acp_session_error",
             acpSessionId,
             error: failureMessage,
           });
+          // The recovery surface (event, model guidance, prompt-dedup marker)
+          // is raised as a unit, and only when a spawning tool call exists to
+          // anchor the card AND the user did not already stop the run. A
+          // cancelled run renders no card (the client guards it), so marking
+          // the never-cleared prompt-dedup registry here would suppress the
+          // secure token prompt against a card that never appears.
+          const recoveryAnchor =
+            errorCode !== undefined && current.state.status !== "cancelled"
+              ? current.parentToolUseId
+              : undefined;
+          if (errorCode !== undefined && recoveryAnchor !== undefined) {
+            current.sendToVellum({
+              type: "acp_auth_required",
+              acpSessionId,
+              authCode: errorCode,
+              agent: current.state.agentId,
+              parentToolUseId: recoveryAnchor,
+            });
+            // Same registry as the missing-token spawn path, so the
+            // credential-prompt route redirects a redundant secure prompt at
+            // the card instead of stacking a second one.
+            markAcpConnectCardRaised(current.parentConversationId);
+          }
 
           // Persist the terminal row before teardown clears the buffer.
           this.persistTerminal(acpSessionId, current);
@@ -1123,7 +1186,10 @@ export class AcpSessionManager {
           if (current.state.status !== "cancelled") {
             this.notifyParent(
               current,
-              `[ACP agent "${current.state.agentId}" failed]\n\n${failureMessage}`,
+              `[ACP agent "${current.state.agentId}" failed]\n\n${failureMessage}` +
+                (recoveryAnchor !== undefined
+                  ? `\n\n${ACP_AUTH_RECOVERY_GUIDANCE}`
+                  : ""),
             );
           }
         }

package/src/api/events/acp-auth-required.ts

@@ -0,0 +1,55 @@
+/**
+ * `acp_auth_required` SSE event.
+ *
+ * Server to client notification that an ACP run failed because the agent
+ * rejected its stored credential and the client can offer a re-authentication
+ * affordance. Always emitted immediately AFTER the `acp_session_error` that
+ * carries the human-readable failure.
+ *
+ * It is a separate event rather than a field on `acp_session_error` because
+ * every event schema here is `.strict()` and clients fall back to an inert
+ * `unknown` event when parsing fails: a new FIELD makes an older packaged
+ * client (iOS/macOS bundle the web app) reject the whole error event and
+ * render the run as still active, while an unknown event TYPE is simply
+ * ignored. Additive signals on existing events need their own event type for
+ * the same reason.
+ *
+ * Canonical wire-contract source. Re-exported to external consumers via
+ * `@vellumai/assistant-api` (the `api/index.ts` barrel).
+ */
+
+import { z } from "zod";
+
+/**
+ * The code for a `claude-agent-acp` run whose Claude credential needs to be
+ * reconnected: the `authCode` on this event for post-spawn failures, and the
+ * `errorCode` on the failed `acp_spawn` tool result for pre-spawn ones.
+ * Single source for both sides of the wire: the daemon re-exports it via
+ * `acp/auth-required.ts`, the web client via
+ * `domains/chat/utils/acp-connect.ts`.
+ */
+export const ACP_CLAUDE_AUTH_REQUIRED_CODE = "acp_claude_auth_required";
+
+export const AcpAuthRequiredEventSchema = z
+  .object({
+    type: z.literal("acp_auth_required"),
+    acpSessionId: z.string(),
+    /**
+     * Machine-readable classification of what kind of re-authentication is
+     * needed, so clients branch on a stable value rather than on the failure
+     * text (which varies by adapter and failure mode). Currently only
+     * {@link ACP_CLAUDE_AUTH_REQUIRED_CODE}.
+     */
+    authCode: z.string(),
+    /** Agent id the run was spawned with, for display. */
+    agent: z.string(),
+    /**
+     * Tool-use id of the `acp_spawn` call that started this run, so the
+     * client anchors the inline affordance to the right transcript row.
+     * Absent when the run was not started by a tool call.
+     */
+    parentToolUseId: z.string().optional(),
+  })
+  .strict();
+
+export type AcpAuthRequiredEvent = z.infer<typeof AcpAuthRequiredEventSchema>;

package/src/api/index.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 
+import { AcpAuthRequiredEventSchema } from "./events/acp-auth-required.js";
 import { AcpSessionCompletedEventSchema } from "./events/acp-session-completed.js";
 import { AcpSessionErrorEventSchema } from "./events/acp-session-error.js";
 import { AcpSessionSpawnedEventSchema } from "./events/acp-session-spawned.js";
@@ -149,6 +150,11 @@ export {
   SSE_REPLAY_RING_COUNT_LIMIT,
 } from "./constants/sse-replay.js";
 export { DEFAULT_TOOL_EXECUTION_TIMEOUT_SEC } from "./constants/tool-execution.js";
+export {
+  ACP_CLAUDE_AUTH_REQUIRED_CODE,
+  type AcpAuthRequiredEvent,
+  AcpAuthRequiredEventSchema,
+} from "./events/acp-auth-required.js";
 export {
   type AcpSessionCompletedEvent,
   AcpSessionCompletedEventSchema,
@@ -895,6 +901,7 @@ export {
  * migration recipe.
  */
 export const AssistantEventSchema = z.discriminatedUnion("type", [
+  AcpAuthRequiredEventSchema,
   AcpSessionCompletedEventSchema,
   AcpSessionErrorEventSchema,
   AcpSessionSpawnedEventSchema,

package/src/apps/app-store.ts

@@ -1422,6 +1422,9 @@ export function backfillAppConversationIds(): void {
   }
 
   try {
+    // Unfinalized rows cannot match: their content is a { ref } pointer,
+    // never inline surface JSON, so this scan sees finalized content only by
+    // shape. No completeness predicate needed.
     const rows = rawAll<{ conversation_id: string; content: string }>(
       "apps:backfillConversationIds",
       `SELECT conversation_id, content FROM messages WHERE content LIKE '%"type":"ui_surface"%'`,

package/src/bundler/package-resolver.ts

@@ -6,7 +6,7 @@
  */
 
 import { existsSync } from "node:fs";
-import { mkdir, stat } from "node:fs/promises";
+import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 
 import { ensureBun } from "../util/bun-runtime.js";
@@ -24,8 +24,8 @@ export const ALLOWED_PACKAGES: readonly string[] = [
   "clsx",
 ] as const;
 
+/** Bounds a runaway install; the allowlist above bounds what may be installed. */
 const INSTALL_TIMEOUT_MS = 10_000;
-const MAX_PACKAGE_SIZE_BYTES = 5 * 1024 * 1024; // 5 MB
 
 /** In-flight install promises keyed by package name, to deduplicate concurrent requests. */
 const inflight = new Map<string, Promise<string | null>>();
@@ -148,37 +148,9 @@ async function installPackage(
       return null;
     }
 
-    // Enforce max size
-    if (existsSync(pkgDir)) {
-      const size = await dirSize(pkgDir);
-      if (size > MAX_PACKAGE_SIZE_BYTES) {
-        log.warn({ pkg, size }, "Package exceeds size limit, removing");
-        const { rm } = await import("node:fs/promises");
-        await rm(pkgDir, { recursive: true, force: true });
-        return null;
-      }
-    }
-
     return existsSync(pkgDir) ? nodeModulesDir : null;
   } catch (err) {
     log.warn({ pkg, err }, "Package resolution failed");
     return null;
   }
 }
-
-/** Recursively sum file sizes under a directory. */
-async function dirSize(dir: string): Promise<number> {
-  const { readdir } = await import("node:fs/promises");
-  const entries = await readdir(dir, { withFileTypes: true });
-  let total = 0;
-  for (const entry of entries) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      total += await dirSize(full);
-    } else {
-      const s = await stat(full);
-      total += s.size;
-    }
-  }
-  return total;
-}