@vellumai/assistant 0.8.10-dev.202606100925.28c1cfb → 0.8.10-dev.202606101324.2fc90b3

package/openapi.yaml

@@ -24689,13 +24689,74 @@ paths:
   /v1/tools:
     get:
       operationId: tools_get
-      summary: List tools
-      description: Return available tool names with their descriptions, risk levels, and categories.
+      summary: List registered tools with metadata and schemas
+      description:
+        "Return registered tools. Without `conversationId`, returns every tool in the global registry; `tools`
+        carries per-tool metadata (description, author-asserted risk level, category, and contributing source: core,
+        skill, plugin, or MCP server) and `names`/`schemas` additionally cover skill tools whose manifests are present
+        but not yet loaded, for the permission-simulator catalog. With `conversationId`, scopes the result to the tools
+        available to that conversation as of its most recent turn (including skill/MCP tools registered over its
+        lifecycle); 404 if no such conversation is active."
       tags:
         - tools
       responses:
         "200":
           description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  names:
+                    type: array
+                    items:
+                      type: string
+                  schemas:
+                    type: object
+                    propertyNames:
+                      type: string
+                    additionalProperties:
+                      type: object
+                      propertyNames:
+                        type: string
+                      additionalProperties: {}
+                  tools:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        name:
+                          type: string
+                        description:
+                          type: string
+                        riskLevel:
+                          type: string
+                        category:
+                          type: string
+                        source:
+                          type: string
+                          description:
+                            'Tool origin: "core" for built-ins, otherwise "<kind>:<id>" (e.g. "plugin:echo", "skill:my-skill",
+                            "mcp:server").'
+                      required:
+                        - name
+                        - description
+                        - riskLevel
+                        - category
+                        - source
+                      additionalProperties: false
+                required:
+                  - names
+                  - schemas
+                  - tools
+                additionalProperties: false
+      parameters:
+        - name: conversationId
+          in: query
+          required: false
+          schema:
+            type: string
+          description: When set, scope the tool inventory to this conversation's most recent turn instead of the global registry.
   /v1/tools/simulate-permission:
     post:
       operationId: tools_simulatepermission_post

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.8.10-dev.202606100925.28c1cfb",
+  "version": "0.8.10-dev.202606101324.2fc90b3",
   "license": "MIT",
   "type": "module",
   "exports": {

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

@@ -365,7 +365,7 @@ describe("AgentLoop exit-reason instrumentation", () => {
     });
 
     const onCheckpoint = (_info: CheckpointInfo): CheckpointDecision =>
-      "budget";
+      "handoff";
 
     const events: AgentEvent[] = [];
     await loop.run({
@@ -380,42 +380,9 @@ describe("AgentLoop exit-reason instrumentation", () => {
     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: provider,
-      systemPrompt: "system",
-      conversationId: "test-conversation",
-      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({
-      messages: [userMessage],
-      onEvent: () => {},
-      trust: { sourceChannel: "vellum", trustClass: "unknown" },
-      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.
+  test("runs to a clean exit when overflow recovery is disabled", async () => {
+    // GIVEN a tiny context window but overflow recovery disabled — the
+    // agent-wake configuration, which must never compact mid-loop.
     const { provider } = createMockProvider([
       toolUseResponse("t1", "read_file", { path: "/a.txt" }),
       textResponse("done"),
@@ -440,8 +407,8 @@ describe("AgentLoop exit-reason instrumentation", () => {
       }),
     });
 
-    // THEN it never yields for budget.
-    expect(result.exitReason).not.toBe("budget");
+    // THEN it reaches a clean exit without pausing the loop.
+    expect(result.exitReason).toBeNull();
   });
 
   test("compacts in place and continues when the budget gate trips with a compaction hook", async () => {
@@ -485,52 +452,13 @@ describe("AgentLoop exit-reason instrumentation", () => {
     });
 
     // THEN the loop runs the compaction ceremony in place and continues to a
-    // clean exit instead of yielding for budget. The durable commit is
-    // signalled via a `compaction_completed` event rather than an injected hook.
+    // clean exit. The durable commit is signalled via a `compaction_completed`
+    // event rather than an injected hook.
     expect(events.some((event) => event.type === "compaction_completed")).toBe(
       true,
     );
     expect(reinjected).toBe(true);
-    expect(result.exitReason).not.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: provider,
-      systemPrompt: "system",
-      conversationId: "test-conversation",
-      tools: dummyTools,
-      toolExecutor: toolExecutor,
-    });
-
-    postCompactImpl = async () => {
-      throw new Error(
-        "post-compaction re-injection must not run when exhausted",
-      );
-    };
-
-    // WHEN compaction exhausts its retry budget
-    const result = await loop.run({
-      messages: [userMessage],
-      onEvent: () => {},
-      resolveContextWindow: () => ({
-        maxInputTokens: 10,
-        overflowRecovery: { enabled: true, safetyMarginRatio: 0 },
-      }),
-      compactInPlace: true,
-      ...fakeCompaction("test-conversation", {
-        compacted: false,
-        exhausted: true,
-      }),
-    });
-
-    // THEN the loop yields for budget so the orchestrator can escalate.
-    expect(result.exitReason).toBe("budget");
+    expect(result.exitReason).toBeNull();
   });
 
   test("emits 'error' when provider throws an unhandled error", async () => {

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

@@ -14,6 +14,7 @@ import type {
   ProviderResponse,
   ToolDefinition,
 } from "../providers/types.js";
+import { ContextOverflowError } from "../providers/types.js";
 import {
   createMockProvider,
   textResponse,
@@ -311,6 +312,55 @@ describe("AgentLoop", () => {
     ).toBe("API rate limit exceeded");
   });
 
+  // 5b. Reactive context-overflow recovery
+  //
+  // When recovery is enabled the loop calibrates the estimator from the
+  // rejection, loops back, and the budget gate forwards the overflow signal
+  // into the compaction plugin's reduction ladder. That manager-owned path —
+  // single-rung recovery, multi-rung escalation, and the terminal
+  // `context_too_large` / `budget_yield_unrecovered` exit on exhaustion — is
+  // exercised end-to-end against a manager harness in
+  // `conversation-agent-loop-overflow.test.ts`. Loop-level coverage against a
+  // manager-store stub lands with the suite migration.
+  test.todo(
+    "drives the reduction ladder on a context-overflow rejection",
+    () => {},
+  );
+
+  test("surfaces a context-overflow error when recovery is unavailable", async () => {
+    /**
+     * Overflow recovery is gated on the budget gate being active. When it is
+     * disabled (e.g. agent wakes pass `overflowRecovery.enabled = false`, or no
+     * context window resolves) there is no ladder to drive, so a context
+     * overflow surfaces as an error on the first call rather than looping.
+     */
+
+    // GIVEN a provider that rejects every call as too large and a loop with no
+    // overflow-recovery budget gate
+    const { provider, calls } = createMockProvider([
+      new ContextOverflowError("prompt is too long", "mock", {
+        actualTokens: 250_000,
+      }),
+    ]);
+    const loop = new AgentLoop({
+      provider,
+      systemPrompt: "system",
+      conversationId: "test-conversation",
+    });
+    const events: AgentEvent[] = [];
+
+    // WHEN the loop runs
+    await loop.run({
+      messages: [userMessage],
+      onEvent: collectEvents(events),
+      trust: { sourceChannel: "vellum", trustClass: "unknown" },
+    });
+
+    // THEN it surfaced the error on the first call without retrying
+    expect(calls).toHaveLength(1);
+    expect(events.filter((e) => e.type === "error")).toHaveLength(1);
+  });
+
   // 6. Abort signal — verify the loop respects AbortSignal
   test("stops when abort signal is triggered before provider call", async () => {
     const controller = new AbortController();
@@ -1036,7 +1086,7 @@ describe("AgentLoop", () => {
       toolExecutor: toolExecutor,
     });
 
-    const onCheckpoint = (): CheckpointDecision => "budget";
+    const onCheckpoint = (): CheckpointDecision => "handoff";
 
     const { history } = await loop.run({
       messages: [userMessage],
@@ -1235,7 +1285,7 @@ describe("AgentLoop", () => {
     const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
       checkpoints.push(checkpoint);
       // Yield on turn 3 (0-indexed)
-      return checkpoint.turnIndex === 3 ? "budget" : "continue";
+      return checkpoint.turnIndex === 3 ? "handoff" : "continue";
     };
 
     const events: AgentEvent[] = [];
@@ -1308,7 +1358,7 @@ describe("AgentLoop", () => {
 
     const onCheckpoint = (checkpoint: CheckpointInfo): CheckpointDecision => {
       // Yield on the second turn (turnIndex 1)
-      return checkpoint.turnIndex === 1 ? "budget" : "continue";
+      return checkpoint.turnIndex === 1 ? "handoff" : "continue";
     };
 
     const { history } = await loop.run({

package/src/__tests__/catalog-install-normalize.test.ts

@@ -0,0 +1,141 @@
+/**
+ * Regression tests for catalog entry normalization in catalog-install.ts.
+ *
+ * The platform `/v1/skills/` API flattens skill metadata into top-level
+ * fields (`category`, `display_name`, `icon`) rather than the nested
+ * `metadata.vellum.*` shape used by the local `catalog.json`. Both
+ * `fetchCatalog` (remote) and `readLocalCatalog` (local file) must produce a
+ * canonical `CatalogSkill` whose `metadata.vellum.category` is populated, so
+ * downstream category assignment doesn't fall back to "system" for every skill.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, mock, test } from "bun:test";
+
+mock.module("../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+mock.module("../config/env.js", () => ({
+  getPlatformBaseUrl: () => "https://platform.example.com",
+}));
+
+import { fetchCatalog, readLocalCatalog } from "../skills/catalog-install.js";
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+/**
+ * Build a `fetch` stub that responds with `payload` serialized as JSON.
+ *
+ * `Object.assign` attaches the `preconnect` static that Bun's `fetch` type
+ * requires, so the stub satisfies `typeof fetch` without an `as unknown` cast.
+ */
+function stubFetchJson(payload: unknown): typeof fetch {
+  const respond = async () =>
+    new Response(JSON.stringify(payload), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  return Object.assign(respond, { preconnect: () => {} });
+}
+
+describe("fetchCatalog normalization", () => {
+  test("re-nests the platform's flattened category under metadata.vellum", async () => {
+    globalThis.fetch = stubFetchJson({
+      skills: [
+        {
+          id: "amazon",
+          name: "amazon",
+          display_name: "Amazon",
+          description: "Shop on Amazon",
+          icon: "🛒",
+          category: "commerce",
+          updated_at: "2026-04-19T19:26:17Z",
+        },
+      ],
+    });
+
+    const catalog = await fetchCatalog();
+
+    expect(catalog).toHaveLength(1);
+    const [skill] = catalog;
+    expect(skill.id).toBe("amazon");
+    expect(skill.metadata?.vellum?.category).toBe("commerce");
+    expect(skill.metadata?.vellum?.["display-name"]).toBe("Amazon");
+    expect(skill.icon).toBe("🛒");
+    expect(skill.metadata?.icon).toBe("🛒");
+    expect(skill.updatedAt).toBe("2026-04-19T19:26:17Z");
+  });
+
+  test("leaves category undefined when the API omits it", async () => {
+    globalThis.fetch = stubFetchJson({
+      skills: [{ id: "no-cat", name: "no-cat", description: "d" }],
+    });
+
+    const catalog = await fetchCatalog();
+
+    expect(catalog).toHaveLength(1);
+    expect(catalog[0].metadata?.vellum?.category).toBeUndefined();
+  });
+
+  test("drops malformed entries without throwing", async () => {
+    globalThis.fetch = stubFetchJson({
+      skills: [
+        null,
+        undefined,
+        "not-an-object",
+        { name: "missing-id", description: "d" },
+        { id: 42 },
+        { id: "valid", name: "valid", description: "d", category: "email" },
+      ],
+    });
+
+    const catalog = await fetchCatalog();
+
+    expect(catalog).toHaveLength(1);
+    expect(catalog[0].id).toBe("valid");
+    expect(catalog[0].metadata?.vellum?.category).toBe("email");
+  });
+});
+
+describe("readLocalCatalog normalization", () => {
+  test("reads the nested metadata.vellum.category from catalog.json", () => {
+    const dir = mkdtempSync(join(tmpdir(), "vellum-catalog-"));
+    try {
+      writeFileSync(
+        join(dir, "catalog.json"),
+        JSON.stringify({
+          version: 1,
+          skills: [
+            {
+              id: "tasks",
+              name: "tasks",
+              description: "Task management",
+              metadata: {
+                icon: "✅",
+                vellum: { "display-name": "Tasks", category: "productivity" },
+              },
+            },
+          ],
+        }),
+      );
+
+      const catalog = readLocalCatalog(dir);
+
+      expect(catalog).toHaveLength(1);
+      expect(catalog[0].metadata?.vellum?.category).toBe("productivity");
+      expect(catalog[0].metadata?.vellum?.["display-name"]).toBe("Tasks");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/__tests__/conversation-agent-loop-inference-profile.test.ts

@@ -123,7 +123,7 @@ mock.module(
   }),
 );
 
-mock.module("../daemon/context-overflow-policy.js", () => ({
+mock.module("../plugins/defaults/compaction/overflow-policy.js", () => ({
   resolveOverflowAction: () => "fail_gracefully",
 }));