@vellumai/assistant 0.8.4 → 0.8.5

package/src/runtime/routes/acp-routes.test.ts

@@ -4,6 +4,10 @@
  * Suites:
  *  - POST /v1/acp/spawn — the three failure paths produced by
  *    `resolveAcpAgent` (acp_disabled, unknown_agent, binary_not_found).
+ *  - POST /v1/acp/spawn (env injection) — CLAUDE_CODE_OAUTH_TOKEN is read
+ *    from the secure store under the canonical
+ *    `credential/acp/claude_oauth_token` key (built by `credentialKey()`)
+ *    and merged into `agentConfig.env` ONLY for the `claude` agent.
  *  - DELETE /v1/acp/sessions?status=completed — the bulk-clear route that
  *    wipes terminal-state rows (completed/failed/cancelled) from
  *    `acp_session_history` while leaving running/initializing rows intact.
@@ -42,10 +46,21 @@ afterAll(() => {
 });
 
 // Stub `getAcpSessionManager` so the DELETE /:id tests can drive the
-// in-memory-status check without spawning real ACP processes. Stored in
-// a mutable map so individual tests can plant arbitrary states.
+// in-memory-status check without spawning real ACP processes, and so the
+// env-injection spawn tests can capture the `agentConfig` arg without
+// launching a real subprocess. Stored in mutable state so individual tests
+// can plant arbitrary states / inspect capture.
 const inMemoryStates = new Map<string, AcpSessionState>();
 
+interface CapturedSpawn {
+  agent: string;
+  agentConfig: { env?: Record<string, string> };
+  task: string;
+  conversationId: string;
+}
+
+const capturedSpawns: CapturedSpawn[] = [];
+
 mock.module("../../acp/index.js", () => ({
   getAcpSessionManager: () => ({
     getStatus: (id?: string) => {
@@ -56,9 +71,27 @@ mock.module("../../acp/index.js", () => ({
       if (!state) throw new Error(`ACP session "${id}" not found`);
       return state;
     },
+    spawn: async (
+      agent: string,
+      agentConfig: { env?: Record<string, string> },
+      task: string,
+      _cwd: string | undefined,
+      conversationId: string,
+    ) => {
+      capturedSpawns.push({ agent, agentConfig, task, conversationId });
+      return { acpSessionId: "acp-test", protocolSessionId: "proto-test" };
+    },
   }),
 }));
 
+// Stub secure-keys so env-injection tests can plant a known token (or
+// absence). Driven via `secureKeyStore` per test in beforeEach.
+const secureKeyStore = new Map<string, string>();
+
+mock.module("../../security/secure-keys.js", () => ({
+  getSecureKeyAsync: async (key: string) => secureKeyStore.get(key),
+}));
+
 import { eq } from "drizzle-orm";
 
 import { getDb, getSqlite } from "../../memory/db-connection.js";
@@ -79,6 +112,8 @@ function getSpawnHandler() {
 beforeEach(() => {
   config.setConfig({});
   which.setWhich((cmd) => `/usr/local/bin/${cmd}`);
+  capturedSpawns.length = 0;
+  secureKeyStore.clear();
 });
 
 // ---------------------------------------------------------------------------
@@ -146,6 +181,212 @@ describe("POST /v1/acp/spawn", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// POST /v1/acp/spawn — CLAUDE_CODE_OAUTH_TOKEN env injection + preflight
+//
+// claude-agent-acp authenticates via CLAUDE_CODE_OAUTH_TOKEN. The route
+// accepts the token from two provisioning routes:
+//   1. Secure store under the canonical `credential/acp/claude_oauth_token`
+//      key (built by `credentialKey()`), populated by
+//      `assistant credentials set --service acp --field claude_oauth_token`.
+//   2. `acp.agents.claude.env.CLAUDE_CODE_OAUTH_TOKEN` in the user's
+//      config.json, surfaced on `resolved.agent.env` by the resolver.
+// After merging the secure-store value into `agentConfig.env`, the route
+// preflights for the token and throws `FailedDependencyError` if it is
+// still absent. The "fail-fast" behavior is symmetric with the existing
+// `binary_not_found` preflight and avoids the zombie-subprocess footgun
+// where claude-agent-acp launches, crashes on auth, and leaves the
+// caller with no useful signal.
+//
+// These tests pin both the happy paths and the throw path so a future
+// drift in the key path, the env-override route, or the preflight check
+// fails the suite loudly.
+// ---------------------------------------------------------------------------
+
+describe("POST /v1/acp/spawn — CLAUDE_CODE_OAUTH_TOKEN injection", () => {
+  test("injects CLAUDE_CODE_OAUTH_TOKEN from credential/acp/claude_oauth_token for the claude agent", async () => {
+    secureKeyStore.set(
+      "credential/acp/claude_oauth_token",
+      "test-token-abc123",
+    );
+
+    const handler = getSpawnHandler();
+    await handler({
+      body: {
+        agent: "claude",
+        task: "do a thing",
+        conversationId: "conv-1",
+      },
+    });
+
+    expect(capturedSpawns).toHaveLength(1);
+    expect(capturedSpawns[0]?.agent).toBe("claude");
+    expect(capturedSpawns[0]?.agentConfig.env?.CLAUDE_CODE_OAUTH_TOKEN).toBe(
+      "test-token-abc123",
+    );
+  });
+
+  test("accepts CLAUDE_CODE_OAUTH_TOKEN from acp.agents.claude.env (config.json override) without a secure-store entry", async () => {
+    // The user-supplied config.json env override is the first-priority
+    // provisioning route. resolveAcpAgent returns it on `resolved.agent.env`,
+    // which the route then preserves on `agentConfig.env`. The preflight
+    // should accept this path with no secure-store entry needed.
+    config.setConfig({
+      agents: {
+        claude: {
+          command: "claude-agent-acp",
+          args: [],
+          env: { CLAUDE_CODE_OAUTH_TOKEN: "config-token-xyz789" },
+        },
+      },
+    });
+
+    const handler = getSpawnHandler();
+    await handler({
+      body: {
+        agent: "claude",
+        task: "do a thing",
+        conversationId: "conv-1",
+      },
+    });
+
+    expect(capturedSpawns).toHaveLength(1);
+    expect(capturedSpawns[0]?.agentConfig.env?.CLAUDE_CODE_OAUTH_TOKEN).toBe(
+      "config-token-xyz789",
+    );
+  });
+
+  test("config.json env override wins over a secure-store token (precedence pin)", async () => {
+    // Codex review feedback (PR #31901 / P2): when a user explicitly sets
+    // CLAUDE_CODE_OAUTH_TOKEN under `acp.agents.<id>.env` (per-workspace,
+    // rotated, scoped credential, etc.), the secure-store value must NOT
+    // silently overwrite it. Vault is fallback, not override.
+    secureKeyStore.set("credential/acp/claude_oauth_token", "vault-token-AAA");
+    config.setConfig({
+      agents: {
+        claude: {
+          command: "claude-agent-acp",
+          args: [],
+          env: { CLAUDE_CODE_OAUTH_TOKEN: "config-token-BBB" },
+        },
+      },
+    });
+
+    const handler = getSpawnHandler();
+    await handler({
+      body: {
+        agent: "claude",
+        task: "do a thing",
+        conversationId: "conv-1",
+      },
+    });
+
+    expect(capturedSpawns).toHaveLength(1);
+    expect(capturedSpawns[0]?.agentConfig.env?.CLAUDE_CODE_OAUTH_TOKEN).toBe(
+      "config-token-BBB",
+    );
+  });
+
+  test("injects via command match for a user-defined agent id aliased to claude-agent-acp", async () => {
+    // Codex review feedback (PR #31901 / P2): gating is keyed off the
+    // resolved command (basename), not the agent id. A custom agent id
+    // pointing at claude-agent-acp still needs CLAUDE_CODE_OAUTH_TOKEN,
+    // so injection + preflight must fire regardless of the id string.
+    secureKeyStore.set("credential/acp/claude_oauth_token", "vault-token-zzz");
+    config.setConfig({
+      agents: {
+        "my-claude": {
+          command: "claude-agent-acp",
+          args: [],
+        },
+      },
+    });
+
+    const handler = getSpawnHandler();
+    await handler({
+      body: {
+        agent: "my-claude",
+        task: "do a thing",
+        conversationId: "conv-1",
+      },
+    });
+
+    expect(capturedSpawns).toHaveLength(1);
+    expect(capturedSpawns[0]?.agent).toBe("my-claude");
+    expect(capturedSpawns[0]?.agentConfig.env?.CLAUDE_CODE_OAUTH_TOKEN).toBe(
+      "vault-token-zzz",
+    );
+  });
+
+  test("throws FailedDependencyError when no CLAUDE_CODE_OAUTH_TOKEN is available from any source", async () => {
+    // secureKeyStore intentionally empty AND no agentConfig.env override —
+    // simulates a fresh install where the user hasn't provisioned a token
+    // via either route. Fail-fast preflight surfaces this immediately
+    // instead of letting claude-agent-acp launch, crash on auth, and leave
+    // a zombie subprocess behind.
+
+    const handler = getSpawnHandler();
+    await expect(
+      handler({
+        body: {
+          agent: "claude",
+          task: "do a thing",
+          conversationId: "conv-1",
+        },
+      }),
+    ).rejects.toThrow(/CLAUDE_CODE_OAUTH_TOKEN/);
+    expect(capturedSpawns).toHaveLength(0);
+  });
+
+  test("does NOT inject CLAUDE_CODE_OAUTH_TOKEN for agents whose command is not claude-agent-acp", async () => {
+    // Token-injection AND preflight are scoped to claude-agent-acp by
+    // command basename. A codex-acp spawn with the secure-store key set
+    // must still launch without that env var — and must not be blocked
+    // by claude's preflight.
+    secureKeyStore.set(
+      "credential/acp/claude_oauth_token",
+      "test-token-abc123",
+    );
+
+    const handler = getSpawnHandler();
+    await handler({
+      body: {
+        agent: "codex",
+        task: "do a thing",
+        conversationId: "conv-1",
+      },
+    });
+
+    expect(capturedSpawns).toHaveLength(1);
+    expect(capturedSpawns[0]?.agent).toBe("codex");
+    expect(
+      capturedSpawns[0]?.agentConfig.env?.CLAUDE_CODE_OAUTH_TOKEN,
+    ).toBeUndefined();
+  });
+
+  test("does NOT pick up a token planted at the legacy non-`credential/` key path", async () => {
+    // Regression guard: the original implementation used the raw key
+    // "acp/claude/oauth_token". The fix routes through `credentialKey()`
+    // so the CLI (`assistant credentials set --service acp --field
+    // claude_oauth_token`) is the canonical provisioning path. Pin this
+    // by planting the token ONLY under the legacy key — the preflight
+    // should fail-fast because the canonical path is empty.
+    secureKeyStore.set("acp/claude/oauth_token", "legacy-token-should-miss");
+
+    const handler = getSpawnHandler();
+    await expect(
+      handler({
+        body: {
+          agent: "claude",
+          task: "do a thing",
+          conversationId: "conv-1",
+        },
+      }),
+    ).rejects.toThrow(/CLAUDE_CODE_OAUTH_TOKEN/);
+    expect(capturedSpawns).toHaveLength(0);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // DELETE /v1/acp/sessions?status=completed — bulk-clear terminal rows
 // ---------------------------------------------------------------------------
@@ -205,7 +446,9 @@ describe("DELETE /v1/acp/sessions?status=completed", () => {
     seedHistoryRow("row-initializing", "initializing", 5000);
 
     const handler = getBulkDeleteHandler();
-    const result = (await handler({ queryParams: { status: "completed" } })) as {
+    const result = (await handler({
+      queryParams: { status: "completed" },
+    })) as {
       deleted: number;
     };
     expect(result.deleted).toBe(3);
@@ -221,7 +464,9 @@ describe("DELETE /v1/acp/sessions?status=completed", () => {
     seedHistoryRow("row-running", "running", 1000);
 
     const handler = getBulkDeleteHandler();
-    const result = (await handler({ queryParams: { status: "completed" } })) as {
+    const result = (await handler({
+      queryParams: { status: "completed" },
+    })) as {
       deleted: number;
     };
     expect(result.deleted).toBe(0);
@@ -244,7 +489,9 @@ describe("DELETE /v1/acp/sessions?status=completed", () => {
     seedHistoryRow("row-completed", "completed", 1000);
 
     const handler = getBulkDeleteHandler();
-    expect(() => handler({ queryParams: { status: "failed" } })).toThrow("status");
+    expect(() => handler({ queryParams: { status: "failed" } })).toThrow(
+      "status",
+    );
     expect(listRows()).toHaveLength(1);
   });
 });
@@ -297,7 +544,9 @@ describe("DELETE /v1/acp/sessions/:id", () => {
     insertHistoryRow({ id: "sess-completed", status: "completed" });
 
     const handler = getDeleteSessionHandler();
-    const result = (await handler({ pathParams: { id: "sess-completed" } })) as {
+    const result = (await handler({
+      pathParams: { id: "sess-completed" },
+    })) as {
       deleted: boolean;
     };
     expect(result.deleted).toBe(true);

package/src/runtime/routes/acp-routes.ts

@@ -8,6 +8,7 @@ import { desc, eq, inArray } from "drizzle-orm";
 import { z } from "zod";
 
 import { getAcpSessionManager } from "../../acp/index.js";
+import { prepareAgentEnv } from "../../acp/prepare-agent-env.js";
 import { resolveAcpAgent } from "../../acp/resolve-agent.js";
 import type { AcpSessionState } from "../../acp/types.js";
 import { getDb } from "../../memory/db-connection.js";
@@ -81,6 +82,12 @@ async function spawnSession({ body }: RouteHandlerArgs) {
     }
   }
 
+  // Inject required env vars and preflight via the shared helper. See
+  // `acp/prepare-agent-env.ts` for the full rationale; calling it here
+  // keeps the HTTP route in lockstep with the skill-tool spawn path
+  // (`tools/acp/spawn.ts`).
+  const agentConfig = await prepareAgentEnv(resolved.agent);
+
   log.info(
     { agent, task: task.slice(0, 100), conversationId },
     "ACP spawn request received",
@@ -89,7 +96,7 @@ async function spawnSession({ body }: RouteHandlerArgs) {
   const manager = getAcpSessionManager();
   const { acpSessionId, protocolSessionId } = await manager.spawn(
     agent,
-    resolved.agent,
+    agentConfig,
     task,
     cwd,
     conversationId,

package/src/runtime/routes/avatar-routes.ts

@@ -40,7 +40,7 @@ function handleGetCharacterComponents() {
   return getCharacterComponents();
 }
 
-function handleRenderFromTraits({ body }: RouteHandlerArgs) {
+function handleRenderFromTraits({ body, headers }: RouteHandlerArgs) {
   const traits = body as CharacterTraits | undefined;
 
   if (
@@ -69,11 +69,11 @@ function handleRenderFromTraits({ body }: RouteHandlerArgs) {
   }
 
   updateIdentityAvatarSection(null, log);
-  publishAvatarChanged();
+  publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
   return { ok: true };
 }
 
-async function handleGenerateAvatar({ body }: RouteHandlerArgs) {
+async function handleGenerateAvatar({ body, headers }: RouteHandlerArgs) {
   const description = (body as Record<string, unknown>)?.description as
     | string
     | undefined;
@@ -109,11 +109,11 @@ async function handleGenerateAvatar({ body }: RouteHandlerArgs) {
   }
 
   updateIdentityAvatarSection(null, log);
-  publishAvatarChanged();
+  publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
   return { ok: true, message: result.content };
 }
 
-function handleSetAvatar({ body }: RouteHandlerArgs) {
+function handleSetAvatar({ body, headers }: RouteHandlerArgs) {
   const imagePath = (body as Record<string, unknown>)?.imagePath as
     | string
     | undefined;
@@ -142,11 +142,11 @@ function handleSetAvatar({ body }: RouteHandlerArgs) {
   copyFileSync(normalized, avatarPath);
 
   updateIdentityAvatarSection(null, log);
-  publishAvatarChanged();
+  publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
   return { ok: true };
 }
 
-function handleRemoveAvatar(_args: RouteHandlerArgs) {
+function handleRemoveAvatar({ headers }: RouteHandlerArgs) {
   const avatarPath = getAvatarImagePath();
 
   if (!existsSync(avatarPath)) {
@@ -172,7 +172,7 @@ function handleRemoveAvatar(_args: RouteHandlerArgs) {
     "Default character avatar (no custom image set)",
     log,
   );
-  publishAvatarChanged();
+  publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
   return { ok: true, hadAvatar: true };
 }
 
@@ -286,8 +286,8 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "notify_avatar_updated",
     endpoint: "avatar/notify-updated",
     method: "POST",
-    handler: () => {
-      publishAvatarChanged();
+    handler: ({ headers }: RouteHandlerArgs) => {
+      publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
       return { ok: true };
     },
     summary: "Notify avatar updated",

package/src/runtime/routes/background-wake-routes.ts

@@ -0,0 +1,188 @@
+import { z } from "zod";
+
+import { computeNextBackgroundWakeIntent } from "../../background-wake/next-wake.js";
+import { getBackgroundWakeRuntime } from "../../background-wake/runtime-registry.js";
+import { BadRequestError, ServiceUnavailableError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+const PREPARE_SLEEP_DEFER_WINDOW_MS = 60_000;
+const HEARTBEAT_DUE_TOLERANCE_MS = 1_000;
+
+let computeWakeIntent = computeNextBackgroundWakeIntent;
+const timestampInputSchema = z.union([z.number(), z.string()]);
+
+const wakeIntentSchema = z
+  .object({
+    nextWakeAt: z.number(),
+    actualNextDueAt: z.number(),
+    reason: z.enum(["heartbeat", "schedule", "mixed"]),
+    sourceGeneration: z.string(),
+    computedAt: z.number(),
+    sourcePayload: z.record(z.string(), z.unknown()),
+  })
+  .nullable();
+
+const normalizedDrainDueRequestSchema = z.object({
+  leaseId: z.string().min(1),
+  reason: z.string().min(1),
+  sourceGeneration: z.string().min(1),
+  startedAt: z.number(),
+  deadlineAt: z.number(),
+});
+
+const drainDueRequestSchema = z.union([
+  z.object({
+    leaseId: z.string().min(1),
+    reason: z.string().min(1),
+    sourceGeneration: z.string().min(1),
+    startedAt: timestampInputSchema,
+    deadlineAt: timestampInputSchema,
+  }),
+  z.object({
+    lease_id: z.string().min(1),
+    reason: z.string().min(1),
+    source_generation: z.string().min(1),
+    started_at: timestampInputSchema,
+    deadline_at: timestampInputSchema,
+  }),
+]);
+
+function normalizeDrainDueBody(body: Record<string, unknown>) {
+  return {
+    leaseId: body.leaseId ?? body.lease_id,
+    reason: body.reason,
+    sourceGeneration: body.sourceGeneration ?? body.source_generation,
+    startedAt: normalizeTimestamp(body.startedAt ?? body.started_at),
+    deadlineAt: normalizeTimestamp(body.deadlineAt ?? body.deadline_at),
+  };
+}
+
+function normalizeTimestamp(value: unknown): unknown {
+  if (typeof value === "number") return value;
+  if (typeof value !== "string") return value;
+  const numeric = Number(value);
+  if (Number.isFinite(numeric)) return numeric;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : value;
+}
+
+function parseDrainDueBody(body: Record<string, unknown>) {
+  const parsed = normalizedDrainDueRequestSchema.safeParse(
+    normalizeDrainDueBody(body),
+  );
+  if (!parsed.success) {
+    throw new BadRequestError(
+      "leaseId, reason, sourceGeneration, startedAt, and deadlineAt are required",
+    );
+  }
+  return parsed.data;
+}
+
+function handleGetIntent() {
+  return { intent: computeWakeIntent() };
+}
+
+function handlePrepareSleep() {
+  const now = Date.now();
+  const intent = computeWakeIntent(now);
+  return {
+    intent,
+    deferSleep:
+      intent != null &&
+      intent.nextWakeAt <= now + PREPARE_SLEEP_DEFER_WINDOW_MS,
+  };
+}
+
+async function handleDrainDue(body: Record<string, unknown>) {
+  const request = parseDrainDueBody(body);
+  const runtime = getBackgroundWakeRuntime();
+  if (!runtime) {
+    throw new ServiceUnavailableError(
+      "Background wake runtime is not registered",
+    );
+  }
+
+  const now = Date.now();
+  const heartbeatDue =
+    runtime.heartbeat.nextRunAt != null &&
+    runtime.heartbeat.nextRunAt <= now + HEARTBEAT_DUE_TOLERANCE_MS;
+  const heartbeatRan = heartbeatDue ? await runtime.heartbeat.runOnce() : false;
+  const scheduledCount = await runtime.scheduler.runOnce();
+
+  return {
+    leaseId: request.leaseId,
+    reason: request.reason,
+    sourceGeneration: request.sourceGeneration,
+    startedAt: request.startedAt,
+    deadlineAt: request.deadlineAt,
+    counts: {
+      heartbeat: heartbeatRan ? 1 : 0,
+      scheduler: scheduledCount,
+      total: (heartbeatRan ? 1 : 0) + scheduledCount,
+    },
+    nextIntent: computeWakeIntent(),
+  };
+}
+
+/** @internal Test helper for route-only tests. */
+export function setBackgroundWakeIntentComputerForTest(
+  nextCompute: typeof computeNextBackgroundWakeIntent | null,
+): void {
+  computeWakeIntent = nextCompute ?? computeNextBackgroundWakeIntent;
+}
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "getBackgroundWakeIntent",
+    endpoint: "background-wake/intent",
+    method: "GET",
+    policyKey: "background-wake",
+    summary: "Get background wake intent",
+    description: "Return the current computed background wake intent.",
+    tags: ["background-wake"],
+    responseBody: z.object({
+      intent: wakeIntentSchema,
+    }),
+    handler: () => handleGetIntent(),
+  },
+  {
+    operationId: "prepareBackgroundWakeSleep",
+    endpoint: "background-wake/prepare-sleep",
+    method: "POST",
+    policyKey: "background-wake",
+    summary: "Prepare for assistant sleep",
+    description:
+      "Return the current background wake intent and whether sleep should be deferred.",
+    tags: ["background-wake"],
+    responseBody: z.object({
+      intent: wakeIntentSchema,
+      deferSleep: z.boolean(),
+    }),
+    handler: () => handlePrepareSleep(),
+  },
+  {
+    operationId: "drainDueBackgroundWake",
+    endpoint: "background-wake/drain-due",
+    method: "POST",
+    policyKey: "background-wake",
+    summary: "Drain due background wake work",
+    description:
+      "Run due heartbeat and scheduler work for a background wake lease.",
+    tags: ["background-wake"],
+    requestBody: drainDueRequestSchema,
+    responseBody: z.object({
+      leaseId: z.string(),
+      reason: z.string(),
+      sourceGeneration: z.string(),
+      startedAt: z.number(),
+      deadlineAt: z.number(),
+      counts: z.object({
+        heartbeat: z.number(),
+        scheduler: z.number(),
+        total: z.number(),
+      }),
+      nextIntent: wakeIntentSchema,
+    }),
+    handler: ({ body }: RouteHandlerArgs) => handleDrainDue(body ?? {}),
+  },
+];