@vellumai/assistant 0.8.6 → 0.8.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -39,12 +39,11 @@
     "@modelcontextprotocol/sdk": "1.27.1",
     "@qdrant/js-client-rest": "1.17.0",
     "@resvg/resvg-js": "2.6.2",
-    "@resvg/resvg-js-darwin-arm64": "2.6.2",
-    "@resvg/resvg-js-darwin-x64": "2.6.2",
     "@sentry/node": "10.43.0",
     "@vellumai/ces-client": "file:../packages/ces-client",
     "@vellumai/credential-storage": "file:../packages/credential-storage",
     "@vellumai/egress-proxy": "file:../packages/egress-proxy",
+    "@vellumai/environments": "file:../packages/environments",
     "@vellumai/gateway-client": "file:../packages/gateway-client",
     "@vellumai/ipc-server-utils": "file:../packages/ipc-server-utils",
     "@vellumai/service-contracts": "file:../packages/service-contracts",
@@ -81,6 +80,7 @@
     "@vellumai/credential-storage",
     "@vellumai/service-contracts",
     "@vellumai/egress-proxy",
+    "@vellumai/environments",
     "@vellumai/gateway-client",
     "@vellumai/ipc-server-utils",
     "@vellumai/skill-host-contracts",
@@ -91,6 +91,10 @@
     "lodash": "4.18.1",
     "path-to-regexp": "8.4.2"
   },
+  "optionalDependencies": {
+    "@resvg/resvg-js-darwin-arm64": "2.6.2",
+    "@resvg/resvg-js-darwin-x64": "2.6.2"
+  },
   "devDependencies": {
     "@types/archiver": "7.0.0",
     "@types/bun": "1.3.10",

package/scripts/generate-openapi.ts

@@ -127,11 +127,7 @@ function dropDefaultedFromRequired(node: unknown): void {
   const obj = node as Record<string, unknown>;
   const props = obj.properties;
   const required = obj.required;
-  if (
-    Array.isArray(required) &&
-    props != null &&
-    typeof props === "object"
-  ) {
+  if (Array.isArray(required) && props != null && typeof props === "object") {
     const propsRecord = props as Record<string, unknown>;
     const filtered = required.filter((name) => {
       if (typeof name !== "string") return true;
@@ -496,7 +492,7 @@ function buildSpec(
   }
 
   return {
-    openapi: "3.0.0",
+    openapi: "3.1.0",
     info: {
       title: "Vellum Assistant API",
       version,
@@ -580,14 +576,21 @@ async function main() {
         }
       }
       if (firstDiff >= 0) {
-        const lineNo = (existing.slice(0, firstDiff).match(/\n/g) ?? []).length + 1;
+        const lineNo =
+          (existing.slice(0, firstDiff).match(/\n/g) ?? []).length + 1;
         const winStart = Math.max(0, firstDiff - 120);
         const winEnd = Math.min(maxLen, firstDiff + 120);
-        console.error(`First divergence at byte ${firstDiff} (~line ${lineNo}):`);
+        console.error(
+          `First divergence at byte ${firstDiff} (~line ${lineNo}):`,
+        );
         console.error(`  existing[${winStart}..${winEnd}]:`);
-        console.error(`    ${JSON.stringify(existing.slice(winStart, winEnd))}`);
+        console.error(
+          `    ${JSON.stringify(existing.slice(winStart, winEnd))}`,
+        );
         console.error(`  generated[${winStart}..${winEnd}]:`);
-        console.error(`    ${JSON.stringify(yamlOutput.slice(winStart, winEnd))}`);
+        console.error(
+          `    ${JSON.stringify(yamlOutput.slice(winStart, winEnd))}`,
+        );
       }
       // Also flag which path operations are present in one but not the other —
       // the common failure mode is a missing or duplicated route entry, and
@@ -611,11 +614,15 @@ async function main() {
         );
         if (inGeneratedOnly.length) {
           console.error(`  Only in generated (missing from committed yaml):`);
-          for (const p of inGeneratedOnly.slice(0, 20)) console.error(`    + ${p}`);
+          for (const p of inGeneratedOnly.slice(0, 20))
+            console.error(`    + ${p}`);
         }
         if (inExistingOnly.length) {
-          console.error(`  Only in existing (stale entries in committed yaml):`);
-          for (const p of inExistingOnly.slice(0, 20)) console.error(`    - ${p}`);
+          console.error(
+            `  Only in existing (stale entries in committed yaml):`,
+          );
+          for (const p of inExistingOnly.slice(0, 20))
+            console.error(`    - ${p}`);
         }
       }
       process.exit(1);

package/src/__tests__/agent-loop-callsite-precedence.test.ts

@@ -42,7 +42,6 @@ import type {
   Provider,
   ProviderResponse,
   SendMessageOptions,
-  ToolDefinition,
 } from "../providers/types.js";
 
 const userMessage: Message = {
@@ -72,8 +71,6 @@ function makePipeline(providerName: string): {
     name: providerName,
     async sendMessage(
       _messages: Message[],
-      _tools?: ToolDefinition[],
-      _systemPrompt?: string,
       options?: SendMessageOptions,
     ): Promise<ProviderResponse> {
       captured = options?.config as Record<string, unknown> | undefined;
@@ -103,16 +100,11 @@ describe("AgentLoop — call-site precedence", () => {
     });
 
     const { provider, lastConfig } = makePipeline("anthropic");
-    const loop = new AgentLoop(provider, "system", { maxTokens: 64000 });
+    const loop = new AgentLoop(provider, "system", {
+      config: { maxTokens: 64000 },
+    });
 
-    await loop.run(
-      [userMessage],
-      () => {},
-      undefined,
-      undefined,
-      undefined,
-      "mainAgent",
-    );
+    await loop.run([userMessage], () => {}, { callSite: "mainAgent" });
 
     expect(lastConfig()!.max_tokens).toBe(4096);
   });
@@ -129,18 +121,13 @@ describe("AgentLoop — call-site precedence", () => {
 
     const { provider, lastConfig } = makePipeline("anthropic");
     const loop = new AgentLoop(provider, "system", {
-      maxTokens: 64000,
-      effort: "high",
+      config: {
+        maxTokens: 64000,
+        effort: "high",
+      },
     });
 
-    await loop.run(
-      [userMessage],
-      () => {},
-      undefined,
-      undefined,
-      undefined,
-      "mainAgent",
-    );
+    await loop.run([userMessage], () => {}, { callSite: "mainAgent" });
 
     expect(lastConfig()!.effort).toBe("low");
   });
@@ -157,21 +144,16 @@ describe("AgentLoop — call-site precedence", () => {
 
     const { provider, lastConfig } = makePipeline("anthropic");
     const loop = new AgentLoop(provider, "system", {
-      maxTokens: 64000,
-      effort: "high",
-      // Conversation default is "fast" (which would normally be applied) —
-      // ensure the call-site value is the one that ends up on the wire.
-      speed: "fast",
+      config: {
+        maxTokens: 64000,
+        effort: "high",
+        // Conversation default is "fast" (which would normally be applied) —
+        // ensure the call-site value is the one that ends up on the wire.
+        speed: "fast",
+      },
     });
 
-    await loop.run(
-      [userMessage],
-      () => {},
-      undefined,
-      undefined,
-      undefined,
-      "mainAgent",
-    );
+    await loop.run([userMessage], () => {}, { callSite: "mainAgent" });
 
     expect(lastConfig()!.speed).toBe("fast");
   });
@@ -193,21 +175,16 @@ describe("AgentLoop — call-site precedence", () => {
 
     const { provider, lastConfig } = makePipeline("anthropic");
     const loop = new AgentLoop(provider, "system", {
-      maxTokens: 64000,
-      // Conversation default also has thinking on — without the fix, this
-      // would pre-set `thinking: { type: "adaptive" }` and mask the
-      // call-site override.
-      thinking: { enabled: true },
+      config: {
+        maxTokens: 64000,
+        // Conversation default also has thinking on — without the fix, this
+        // would pre-set `thinking: { type: "adaptive" }` and mask the
+        // call-site override.
+        thinking: { enabled: true },
+      },
     });
 
-    await loop.run(
-      [userMessage],
-      () => {},
-      undefined,
-      undefined,
-      undefined,
-      "mainAgent",
-    );
+    await loop.run([userMessage], () => {}, { callSite: "mainAgent" });
 
     // Call-site override resolves `thinking.enabled: false`, so the
     // RetryProvider normalizer must send Anthropic's explicit disabled shape.
@@ -225,16 +202,11 @@ describe("AgentLoop — call-site precedence", () => {
     });
 
     const { provider, lastConfig } = makePipeline("anthropic");
-    const loop = new AgentLoop(provider, "system", { maxTokens: 64000 });
+    const loop = new AgentLoop(provider, "system", {
+      config: { maxTokens: 64000 },
+    });
 
-    await loop.run(
-      [userMessage],
-      () => {},
-      undefined,
-      undefined,
-      undefined,
-      "mainAgent",
-    );
+    await loop.run([userMessage], () => {}, { callSite: "mainAgent" });
 
     // Must be wire-format `{ type: "adaptive" }` so the Anthropic SDK's
     // `ThinkingConfigParam` accepts it. The schema-shape `{ enabled,
@@ -256,13 +228,15 @@ describe("AgentLoop — call-site precedence", () => {
 
     const { provider, lastConfig } = makePipeline("anthropic");
     const loop = new AgentLoop(provider, "system", {
-      maxTokens: 64000,
-      effort: "high",
-      speed: "fast",
-      thinking: { enabled: true },
+      config: {
+        maxTokens: 64000,
+        effort: "high",
+        speed: "fast",
+        thinking: { enabled: true },
+      },
     });
 
-    await loop.run([userMessage], () => {}, undefined, undefined, undefined);
+    await loop.run([userMessage], () => {});
 
     const config = lastConfig()!;
     expect(config.max_tokens).toBe(64000);
@@ -288,24 +262,12 @@ describe("AgentLoop — call-site precedence", () => {
       maxTokens: 8192,
     });
 
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      { maxTokens: 64000 },
-      [],
-      undefined,
-      undefined,
-      resolveSystemPrompt,
-    );
-
-    await loop.run(
-      [userMessage],
-      () => {},
-      undefined,
-      undefined,
-      undefined,
-      "mainAgent",
-    );
+    const loop = new AgentLoop(provider, "system", {
+      config: { maxTokens: 64000 },
+      resolveSystemPrompt: resolveSystemPrompt,
+    });
+
+    await loop.run([userMessage], () => {}, { callSite: "mainAgent" });
 
     // Per-turn explicit value beats both the call-site (4096) and the
     // default (64000).

package/src/__tests__/agent-loop-exit-reason.test.ts

@@ -14,14 +14,17 @@
  * require deeper provider fakery and are best covered by integration tests
  * once we wire up the empty-response pipeline mock.
  */
-import { describe, expect, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
 
 import type {
   AgentEvent,
   CheckpointDecision,
   CheckpointInfo,
+  MidLoopCompaction,
 } from "../agent/loop.js";
 import { AgentLoop, isMaxTokensStopReason } from "../agent/loop.js";
+import type { TurnContext } from "../plugins/types.js";
+import { PluginTimeoutError } from "../plugins/types.js";
 import type {
   Message,
   Provider,
@@ -42,8 +45,6 @@ function createMockProvider(responses: ProviderResponse[]): {
     name: "mock",
     async sendMessage(
       _messages: Message[],
-      _tools?: ToolDefinition[],
-      _systemPrompt?: string,
       _options?: SendMessageOptions,
     ): Promise<ProviderResponse> {
       const response = responses[callIndex] ?? responses[responses.length - 1];
@@ -101,6 +102,40 @@ const userMessage: Message = {
   content: [{ type: "text", text: "Hello" }],
 };
 
+// A turn context whose `contextWindowManager.maybeCompact` returns a canned
+// result, so the loop's native compaction pipeline runs without the real
+// orchestrator machinery.
+function fakeCompactionTurnContext(result: {
+  compacted: boolean;
+  exhausted: boolean;
+}): TurnContext {
+  return {
+    requestId: "req-compact",
+    conversationId: "conv-compact",
+    turnIndex: 0,
+    trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    contextWindowManager: {
+      maybeCompact: async () => result,
+    },
+  } as unknown as TurnContext;
+}
+
+// A turn context whose compaction call times out, exercising the loop's
+// PluginTimeoutError handling.
+function timeoutCompactionTurnContext(): TurnContext {
+  return {
+    requestId: "req-compact",
+    conversationId: "conv-compact",
+    turnIndex: 0,
+    trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    contextWindowManager: {
+      maybeCompact: async () => {
+        throw new PluginTimeoutError("compaction", "default-compaction", 1);
+      },
+    },
+  } as unknown as TurnContext;
+}
+
 function lastExitEvent(
   events: AgentEvent[],
 ): Extract<AgentEvent, { type: "agent_loop_exit" }> | undefined {
@@ -194,10 +229,12 @@ describe("AgentLoop exit-reason instrumentation", () => {
         stopReason: "max_tokens",
       },
     ]);
-    const loop = new AgentLoop(provider, "system prompt", {}, dummyTools);
+    const loop = new AgentLoop(provider, "system prompt", {
+      tools: dummyTools,
+    });
 
     const events: AgentEvent[] = [];
-    const result = await loop.run([userMessage], (e) => {
+    const { history: result } = await loop.run([userMessage], (e) => {
       events.push(e);
     });
 
@@ -221,7 +258,7 @@ describe("AgentLoop exit-reason instrumentation", () => {
       (e) => {
         events.push(e);
       },
-      controller.signal,
+      { signal: controller.signal },
     );
 
     expect(countExitEvents(events)).toBe(1);
@@ -237,13 +274,10 @@ describe("AgentLoop exit-reason instrumentation", () => {
       isError: false,
       yieldToUser: true,
     });
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
     const events: AgentEvent[] = [];
     await loop.run([userMessage], (e) => {
@@ -260,15 +294,13 @@ describe("AgentLoop exit-reason instrumentation", () => {
       textResponse("never reached"),
     ]);
     const toolExecutor = async () => ({ content: "ok", isError: false });
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
-    const onCheckpoint = (_info: CheckpointInfo): CheckpointDecision => "yield";
+    const onCheckpoint = (_info: CheckpointInfo): CheckpointDecision =>
+      "budget";
 
     const events: AgentEvent[] = [];
     await loop.run(
@@ -276,14 +308,189 @@ describe("AgentLoop exit-reason instrumentation", () => {
       (e) => {
         events.push(e);
       },
-      undefined,
-      undefined,
-      onCheckpoint,
+      { onCheckpoint },
     );
 
     expect(countExitEvents(events)).toBe(0);
   });
 
+  test("yields with 'budget' when the in-loop budget gate trips", async () => {
+    // GIVEN a provider that calls a tool (reaching a checkpoint) before it
+    // would continue with a text response.
+    const { provider } = createMockProvider([
+      toolUseResponse("t1", "read_file", { path: "/a.txt" }),
+      textResponse("never reached"),
+    ]);
+    const toolExecutor = async () => ({ content: "ok", isError: false });
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
+
+    // AND an effective context window so small that any real token estimate
+    // of the running history exceeds the mid-loop threshold.
+    // WHEN the loop checkpoints after the tool results land
+    const result = await loop.run([userMessage], () => {}, {
+      resolveContextWindow: () => ({
+        maxInputTokens: 10,
+        overflowRecovery: { enabled: true, safetyMarginRatio: 0 },
+      }),
+    });
+
+    // THEN it yields for budget before issuing the next provider call.
+    expect(result.exitReason).toBe("budget");
+  });
+
+  test("does not yield for budget when overflow recovery is disabled", async () => {
+    // GIVEN the same tiny context window but overflow recovery disabled — the
+    // agent-wake configuration, which must never yield for budget.
+    const { provider } = createMockProvider([
+      toolUseResponse("t1", "read_file", { path: "/a.txt" }),
+      textResponse("done"),
+    ]);
+    const toolExecutor = async () => ({ content: "ok", isError: false });
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
+
+    // WHEN the loop runs to completion
+    const result = await loop.run([userMessage], () => {}, {
+      resolveContextWindow: () => ({
+        maxInputTokens: 10,
+        overflowRecovery: { enabled: false, safetyMarginRatio: 0 },
+      }),
+    });
+
+    // THEN it never yields for budget.
+    expect(result.exitReason).not.toBe("budget");
+  });
+
+  test("compacts in place and continues when the budget gate trips with a compaction hook", async () => {
+    // GIVEN a tool round that reaches a checkpoint, followed by a plain text
+    // response that ends the run after compaction continues the loop.
+    const { provider } = createMockProvider([
+      toolUseResponse("t1", "read_file", { path: "/a.txt" }),
+      textResponse("done after compaction"),
+    ]);
+    const toolExecutor = async () => ({ content: "ok", isError: false });
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
+
+    let prepared = false;
+    let appliedResult = false;
+    let reinjected = false;
+    const compaction: MidLoopCompaction = {
+      prepare: (history) => {
+        prepared = true;
+        return { rawHistory: history, options: undefined };
+      },
+      applyResult: async () => {
+        appliedResult = true;
+      },
+      reinject: async () => {
+        reinjected = true;
+        return [userMessage];
+      },
+    };
+
+    // WHEN the in-loop budget gate trips at the checkpoint
+    const result = await loop.run([userMessage], () => {}, {
+      resolveContextWindow: () => ({
+        maxInputTokens: 10,
+        overflowRecovery: { enabled: true, safetyMarginRatio: 0 },
+      }),
+      compaction,
+      turnContext: fakeCompactionTurnContext({
+        compacted: true,
+        exhausted: false,
+      }),
+    });
+
+    // THEN the loop runs the compaction ceremony in place and continues to a
+    // clean exit instead of yielding for budget.
+    expect(prepared).toBe(true);
+    expect(appliedResult).toBe(true);
+    expect(reinjected).toBe(true);
+    expect(result.exitReason).not.toBe("budget");
+  });
+
+  test("yields 'budget' when inline compaction times out", async () => {
+    const { provider } = createMockProvider([
+      toolUseResponse("t1", "read_file", { path: "/a.txt" }),
+      textResponse("never reached"),
+    ]);
+    const toolExecutor = async () => ({ content: "ok", isError: false });
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
+
+    const compaction: MidLoopCompaction = {
+      prepare: (history) => ({ rawHistory: history, options: undefined }),
+      applyResult: async () => {},
+      reinject: async () => {
+        throw new Error("reinject must not run after a timeout");
+      },
+    };
+    const recordOutcomeSpy = spyOn(loop.compactionCircuit, "recordOutcome");
+
+    // WHEN the compaction pipeline throws a PluginTimeoutError
+    const result = await loop.run([userMessage], () => {}, {
+      resolveContextWindow: () => ({
+        maxInputTokens: 10,
+        overflowRecovery: { enabled: true, safetyMarginRatio: 0 },
+      }),
+      compaction,
+      turnContext: timeoutCompactionTurnContext(),
+    });
+
+    // THEN the loop records the timeout as a compaction failure against its
+    // own circuit breaker, and yields for budget so the orchestrator can
+    // escalate.
+    expect(recordOutcomeSpy).toHaveBeenCalledTimes(1);
+    expect(recordOutcomeSpy.mock.calls[0]?.[1]).toBe(true);
+    expect(result.exitReason).toBe("budget");
+  });
+
+  test("yields 'budget' when inline compaction reports exhausted", async () => {
+    const { provider } = createMockProvider([
+      toolUseResponse("t1", "read_file", { path: "/a.txt" }),
+      textResponse("never reached"),
+    ]);
+    const toolExecutor = async () => ({ content: "ok", isError: false });
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
+
+    const compaction: MidLoopCompaction = {
+      prepare: (history) => ({ rawHistory: history, options: undefined }),
+      applyResult: async () => {},
+      reinject: async () => {
+        throw new Error("reinject must not run when exhausted");
+      },
+    };
+
+    // WHEN compaction exhausts its retry budget
+    const result = await loop.run([userMessage], () => {}, {
+      resolveContextWindow: () => ({
+        maxInputTokens: 10,
+        overflowRecovery: { enabled: true, safetyMarginRatio: 0 },
+      }),
+      compaction,
+      turnContext: fakeCompactionTurnContext({
+        compacted: false,
+        exhausted: true,
+      }),
+    });
+
+    // THEN the loop yields for budget so the orchestrator can escalate.
+    expect(result.exitReason).toBe("budget");
+  });
+
   test("emits 'error' when provider throws an unhandled error", async () => {
     const provider: Provider = {
       name: "broken",
@@ -314,13 +521,10 @@ describe("AgentLoop exit-reason instrumentation", () => {
       isError: false,
       yieldToUser: true,
     });
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
     const events: AgentEvent[] = [];
     await loop.run([userMessage], (e) => {
@@ -341,13 +545,10 @@ describe("AgentLoop exit-reason instrumentation", () => {
       controller.abort();
       return { content: "ok", isError: false };
     };
-    const loop = new AgentLoop(
-      provider,
-      "system",
-      {},
-      dummyTools,
-      toolExecutor,
-    );
+    const loop = new AgentLoop(provider, "system", {
+      tools: dummyTools,
+      toolExecutor: toolExecutor,
+    });
 
     const events: AgentEvent[] = [];
     await loop.run(
@@ -355,7 +556,7 @@ describe("AgentLoop exit-reason instrumentation", () => {
       (e) => {
         events.push(e);
       },
-      controller.signal,
+      { signal: controller.signal },
     );
 
     expect(countExitEvents(events)).toBe(1);