@vellumai/assistant 0.8.3 → 0.8.5

package/src/agent/loop.ts

@@ -7,6 +7,7 @@ import {
   getCalibrationProviderKey,
 } from "../context/token-estimator.js";
 import { calculateMaxToolResultChars } from "../context/tool-result-truncation.js";
+import type { ToolActivityMetadata } from "../daemon/message-types/web-activity.js";
 import { defaultEmptyResponseTerminal } from "../plugins/defaults/empty-response.js";
 import { defaultToolErrorTerminal } from "../plugins/defaults/tool-error.js";
 import { defaultToolResultTruncateTerminal } from "../plugins/defaults/tool-result-truncate.js";
@@ -68,21 +69,22 @@ export interface CheckpointInfo {
 export type CheckpointDecision = "continue" | "yield";
 
 /**
- * Why an {@link AgentLoop.run} invocation exited its `while (true)` body.
+ * Why an agent turn reached a terminal state.
  *
- * Emitted exactly once per run as part of an {@link AgentEvent} of type
- * `agent_loop_exit`, then persisted onto the **final** `llm_request_logs`
- * row of the run. Rows from intermediate turns keep a NULL
- * `agent_loop_exit_reason`, which is how downstream tooling (and the LLM
- * Context Inspector) distinguishes "loop kept going" from "loop is done".
+ * Emitted as part of an {@link AgentEvent} of type `agent_loop_exit`, then
+ * persisted onto the **final** `llm_request_logs` row of the turn. Rows from
+ * intermediate turns keep a NULL `agent_loop_exit_reason`, which is how
+ * downstream tooling (and the LLM Context Inspector) distinguishes "loop kept
+ * going" from "loop is done".
  *
  * Values are stable wire/DB strings — they are written to SQLite and
  * surfaced over the inspector wire format, so renaming any of them is a
  * breaking change.
  *
- * Cardinality matches the nine `break;`/`throw` sites currently inside the
- * loop body. Keep in sync with `emitExit` call sites in
- * {@link AgentLoop.run}.
+ * Keep in sync with `emitExit` call sites in {@link AgentLoop.run} and the
+ * outer conversation orchestrator paths that terminate after a checkpoint
+ * yield. A checkpoint yield used for budget compaction is intentionally not
+ * a terminal reason — it is a control transfer before re-entering the loop.
  */
 export type AgentLoopExitReason =
   /** `if (signal?.aborted) break;` at the top of the loop. */
@@ -97,8 +99,20 @@ export type AgentLoopExitReason =
   | "aborted_during_tools"
   /** A tool result requested handing back to the user. */
   | "yield_to_user"
-  /** The orchestrator's `onCheckpoint` callback returned `"yield"`. */
-  | "checkpoint_yield"
+  /** The orchestrator yielded at checkpoint to process a queued message. */
+  | "checkpoint_handoff"
+  /** Context-window recovery exhausted and the turn ended with an error. */
+  | "context_too_large"
+  /**
+   * Auto-compress rerun (post-emergency-compaction, post-tier reducer)
+   * still yielded at the mid-loop budget checkpoint — the turn silently
+   * terminated with no further recovery layer to re-enter. Pure
+   * observability signal so the silent stall is attributable instead of
+   * leaving `agent_loop_exit_reason` NULL.
+   */
+  | "budget_yield_unrecovered"
+  /** User cancellation landed after a non-terminal checkpoint yield. */
+  | "aborted_after_checkpoint"
   /** Signal aborted while the catch handler was synthesizing an error turn. */
   | "aborted_via_error"
   /** Catch-block fallback: an unhandled error broke the loop. */
@@ -142,6 +156,7 @@ export type AgentEvent =
       approvalMode?: string;
       approvalReason?: string;
       riskThreshold?: string;
+      activityMetadata?: ToolActivityMetadata;
     }
   | { type: "tool_use_preview_start"; toolUseId: string; toolName: string }
   | {
@@ -161,6 +176,17 @@ export type AgentEvent =
       toolUseId: string;
       isError: boolean;
       content?: unknown[];
+      /**
+       * Finalized input for the server tool (e.g. the actual web-search
+       * query). Carried through so the daemon can populate accurate activity
+       * metadata; Anthropic streams server-tool input via deltas that aren't
+       * resolved at `server_tool_start` time.
+       */
+      resolvedInput?: Record<string, unknown>;
+      /** Provider-specific error code (e.g. `max_uses_exceeded`). */
+      errorCode?: string;
+      /** Optional human-readable error message from the provider. */
+      errorMessage?: string;
     }
   | { type: "error"; error: Error }
   | {
@@ -210,10 +236,11 @@ export type AgentEvent =
     }
   | {
       /**
-       * Emitted exactly once at the end of {@link AgentLoop.run}, after the
-       * loop body has exited (whether via `break;`, an unhandled error in
-       * the catch block, or the empty-response throw path). Consumers
-       * persist `reason` onto the final `llm_request_logs` row for the run;
+       * Emitted when an agent turn reaches a terminal state. Checkpoint
+       * yields used for orchestration (handoff or budget compaction) are not
+       * emitted by {@link AgentLoop.run}; the outer orchestrator emits a
+       * terminal reason only if that control transfer truly ends the turn.
+       * Consumers persist `reason` onto the final `llm_request_logs` row;
        * intermediate rows keep `agent_loop_exit_reason = NULL`, which is the
        * canonical "loop kept going" signal.
        */
@@ -371,6 +398,7 @@ export type LoopToolExecutor = (
   approvalMode?: string;
   approvalReason?: string;
   riskThreshold?: string;
+  activityMetadata?: ToolActivityMetadata;
 }>;
 
 export class AgentLoop {
@@ -458,6 +486,8 @@ export class AgentLoop {
      */
     overrideProfile?: string,
     effectiveMaxInputTokens?: number,
+    resolveOverrideProfile?: () => string | undefined,
+    resolveEffectiveMaxInputTokens?: () => number | undefined,
   ): Promise<Message[]> {
     const history = [...messages];
     const initialHistoryLength = messages.length;
@@ -580,9 +610,14 @@ export class AgentLoop {
         // `activeProfile` and any call-site named profile. Threading it on
         // every send (rather than once at construction) keeps subagents that
         // share an `AgentLoop` instance but ought to inherit a different
-        // profile correct — and matches how `callSite` is plumbed.
-        if (overrideProfile) {
-          providerConfig.overrideProfile = overrideProfile;
+        // profile correct — and matches how `callSite` is plumbed. The
+        // optional resolver lets a turn observe an explicitly confirmed
+        // profile-session switch before the next model call.
+        const effectiveOverrideProfile = resolveOverrideProfile
+          ? resolveOverrideProfile()
+          : overrideProfile;
+        if (effectiveOverrideProfile) {
+          providerConfig.overrideProfile = effectiveOverrideProfile;
         }
 
         // Rate-limit consecutive LLM calls to prevent spin when tools return instantly
@@ -690,6 +725,13 @@ export class AgentLoop {
                   toolUseId: event.toolUseId,
                   isError: event.isError,
                   ...(event.content ? { content: event.content } : {}),
+                  ...(event.resolvedInput
+                    ? { resolvedInput: event.resolvedInput }
+                    : {}),
+                  ...(event.errorCode ? { errorCode: event.errorCode } : {}),
+                  ...(event.errorMessage
+                    ? { errorMessage: event.errorMessage }
+                    : {}),
                 });
               }
             },
@@ -1079,7 +1121,10 @@ export class AgentLoop {
         // truncation strategy (e.g. a summariser) while the default
         // middleware preserves the historical tail-drop behaviour.
         const contextWindowTokens =
-          effectiveMaxInputTokens ?? this.config.maxInputTokens ?? 180_000;
+          resolveEffectiveMaxInputTokens?.() ??
+          effectiveMaxInputTokens ??
+          this.config.maxInputTokens ??
+          180_000;
         const maxChars = calculateMaxToolResultChars(contextWindowTokens);
         const truncateMiddlewares = getMiddlewaresFor("toolResultTruncate");
 
@@ -1155,6 +1200,7 @@ export class AgentLoop {
             approvalMode: result.approvalMode,
             approvalReason: result.approvalReason,
             riskThreshold: result.riskThreshold,
+            activityMetadata: result.activityMetadata,
           });
         }
 
@@ -1236,7 +1282,6 @@ export class AgentLoop {
             history,
           });
           if (decision === "yield") {
-            await emitExit("checkpoint_yield");
             break;
           }
         }

package/src/api/README.md

@@ -0,0 +1,5 @@
+# @vellumai/assistant-api
+
+Public API surface for consumers of the assistant API (web client, gateway,
+evals, future external clients). This directory is the **source of truth** for
+the wire contracts the assistant exposes: schemas, types, and pure helpers.

package/src/api/index.ts

@@ -0,0 +1,4 @@
+export {
+  type RelationshipStateUpdated,
+  RelationshipStateUpdatedSchema,
+} from "../events/relationship-state-updated.js";

package/src/api/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "@vellumai/assistant-api",
+  "version": "0.0.0-source",
+  "description": "Public API surface for consumers of the assistant API (web client, gateway, evals, etc.).",
+  "type": "module",
+  "private": true,
+  "exports": {
+    ".": "./index.ts"
+  }
+}

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

@@ -0,0 +1,233 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+import type { BackgroundWakeIntent } from "./next-wake.js";
+import {
+  clearBackgroundWakeRuntime,
+  registerBackgroundWakeRuntime,
+} from "./runtime-registry.js";
+
+type MockIntent = BackgroundWakeIntent;
+
+let computedIntent: MockIntent | null;
+let computeCalls: number;
+
+const { ROUTES, setBackgroundWakeIntentComputerForTest } =
+  await import("../runtime/routes/background-wake-routes.js");
+
+function findHandler(operationId: string) {
+  const route = ROUTES.find(
+    (candidate) => candidate.operationId === operationId,
+  );
+  if (!route) throw new Error(`Route ${operationId} not found`);
+  return route.handler;
+}
+
+const NOW = 1_800_000_000_000;
+
+describe("background wake runtime routes", () => {
+  beforeEach(() => {
+    clearBackgroundWakeRuntime();
+    computeCalls = 0;
+    computedIntent = intentFixture({ nextWakeAt: Date.now() + 10 * 60_000 });
+    setBackgroundWakeIntentComputerForTest(() => {
+      computeCalls += 1;
+      return computedIntent;
+    });
+  });
+
+  afterEach(() => {
+    setBackgroundWakeIntentComputerForTest(null);
+  });
+
+  test("intent route returns the current computed wake intent", async () => {
+    const handler = findHandler("getBackgroundWakeIntent");
+
+    expect(await handler({})).toEqual({ intent: computedIntent });
+    expect(computeCalls).toBe(1);
+  });
+
+  test("intent route returns null when no wake intent exists", async () => {
+    computedIntent = null;
+    const handler = findHandler("getBackgroundWakeIntent");
+
+    expect(await handler({})).toEqual({ intent: null });
+  });
+
+  test("prepare-sleep defers when the next wake is inside the local window", async () => {
+    computedIntent = intentFixture({ nextWakeAt: Date.now() + 30_000 });
+    const handler = findHandler("prepareBackgroundWakeSleep");
+
+    expect(await handler({})).toEqual({
+      intent: computedIntent,
+      deferSleep: true,
+    });
+  });
+
+  test("prepare-sleep allows sleep when the next wake is outside the local window", async () => {
+    computedIntent = intentFixture({ nextWakeAt: Date.now() + 5 * 60_000 });
+    const handler = findHandler("prepareBackgroundWakeSleep");
+
+    expect(await handler({})).toEqual({
+      intent: computedIntent,
+      deferSleep: false,
+    });
+  });
+
+  test("drain-due fails when the runtime registry is missing", async () => {
+    const handler = findHandler("drainDueBackgroundWake");
+
+    await expect(handler({ body: drainBodyFixture() })).rejects.toThrow(
+      "Background wake runtime is not registered",
+    );
+  });
+
+  test("drain-due invokes due heartbeat and scheduler work", async () => {
+    const heartbeatRunOnce = mock(async () => true);
+    const schedulerRunOnce = mock(async () => 2);
+    registerBackgroundWakeRuntime({
+      heartbeat: {
+        nextRunAt: Date.now() - 1,
+        runOnce: heartbeatRunOnce,
+      },
+      scheduler: {
+        runOnce: schedulerRunOnce,
+      },
+    });
+    computedIntent = intentFixture({
+      nextWakeAt: NOW + 60_000,
+      sourceGeneration: "next-generation",
+    });
+    const handler = findHandler("drainDueBackgroundWake");
+
+    const response = await handler({ body: drainBodyFixture() });
+
+    expect(heartbeatRunOnce).toHaveBeenCalledTimes(1);
+    expect(heartbeatRunOnce).toHaveBeenCalledWith();
+    expect(schedulerRunOnce).toHaveBeenCalledTimes(1);
+    expect(response).toEqual({
+      leaseId: "lease-123",
+      reason: "schedule",
+      sourceGeneration: "source-generation",
+      startedAt: NOW,
+      deadlineAt: NOW + 30_000,
+      counts: {
+        heartbeat: 1,
+        scheduler: 2,
+        total: 3,
+      },
+      nextIntent: computedIntent,
+    });
+  });
+
+  test("drain-due skips heartbeat when it is not due and reports no scheduler work", async () => {
+    const heartbeatRunOnce = mock(async () => true);
+    const schedulerRunOnce = mock(async () => 0);
+    registerBackgroundWakeRuntime({
+      heartbeat: {
+        nextRunAt: Date.now() + 5 * 60_000,
+        runOnce: heartbeatRunOnce,
+      },
+      scheduler: {
+        runOnce: schedulerRunOnce,
+      },
+    });
+    const handler = findHandler("drainDueBackgroundWake");
+
+    const response = (await handler({ body: drainBodyFixture() })) as {
+      counts: { heartbeat: number; scheduler: number; total: number };
+    };
+
+    expect(heartbeatRunOnce).not.toHaveBeenCalled();
+    expect(schedulerRunOnce).toHaveBeenCalledTimes(1);
+    expect(response.counts).toEqual({
+      heartbeat: 0,
+      scheduler: 0,
+      total: 0,
+    });
+  });
+
+  test("drain-due recomputes the next intent after due work drains", async () => {
+    const recomputedIntent = intentFixture({
+      nextWakeAt: NOW + 2 * 60_000,
+      sourceGeneration: "after-drain",
+    });
+    const schedulerRunOnce = mock(async () => {
+      computedIntent = recomputedIntent;
+      return 1;
+    });
+    registerBackgroundWakeRuntime({
+      heartbeat: {
+        nextRunAt: null,
+        runOnce: mock(async () => true),
+      },
+      scheduler: {
+        runOnce: schedulerRunOnce,
+      },
+    });
+    const handler = findHandler("drainDueBackgroundWake");
+
+    const response = (await handler({ body: drainBodyFixture() })) as {
+      nextIntent: MockIntent | null;
+    };
+
+    expect(response.nextIntent).toEqual(recomputedIntent);
+  });
+
+  test("drain-due accepts vembda snake_case payload aliases", async () => {
+    const schedulerRunOnce = mock(async () => 0);
+    registerBackgroundWakeRuntime({
+      heartbeat: {
+        nextRunAt: null,
+        runOnce: mock(async () => false),
+      },
+      scheduler: {
+        runOnce: schedulerRunOnce,
+      },
+    });
+    const handler = findHandler("drainDueBackgroundWake");
+
+    const response = await handler({
+      body: {
+        lease_id: "lease-snake",
+        reason: "refresh",
+        source_generation: "generation-snake",
+        started_at: new Date(NOW).toISOString(),
+        deadline_at: String(NOW + 30_000),
+      },
+    });
+
+    expect(response).toMatchObject({
+      leaseId: "lease-snake",
+      reason: "refresh",
+      sourceGeneration: "generation-snake",
+      startedAt: NOW,
+      deadlineAt: NOW + 30_000,
+    });
+  });
+});
+
+function drainBodyFixture() {
+  return {
+    leaseId: "lease-123",
+    reason: "schedule",
+    sourceGeneration: "source-generation",
+    startedAt: NOW,
+    deadlineAt: NOW + 30_000,
+  };
+}
+
+function intentFixture(overrides: Partial<MockIntent>): MockIntent {
+  const nextWakeAt = overrides.nextWakeAt ?? NOW + 60_000;
+  return {
+    nextWakeAt,
+    actualNextDueAt: nextWakeAt,
+    reason: "schedule",
+    sourceGeneration: "source-generation",
+    computedAt: NOW - 1_000,
+    sourcePayload: {
+      heartbeat: null,
+      schedules: [],
+    },
+    ...overrides,
+  };
+}