@vellumai/assistant 0.8.10-dev.202606101122.0de2aff → 0.8.10-dev.202606101436.d73da44

package/docs/workspace-tools.md

@@ -0,0 +1,196 @@
+# Workspace Tool Overrides
+
+Workspace tool overrides let the operator replace a core assistant tool (or
+add a brand-new one) by dropping a single file under their
+`<workspaceDir>/tools/` directory. The override survives assistant restarts,
+takes effect during the same startup phase as core tool initialization,
+and is recoverable: removing the file restores the original core behavior.
+When the `workspace-tools-watcher` feature flag is enabled, overrides are
+also hot-reloaded by a filesystem watcher (no restart required after the
+initial boot).
+
+This page explains the file convention, lifecycle position, and the
+"single canonical source per name" invariant the design is built around.
+
+## File convention
+
+```
+<workspaceDir>/
+  tools/
+    skill_load.ts        ← name="skill_load" via .ts default export
+    my_tool.js           ← name="my_tool" via compiled .js
+    data_lookup.json     ← name="data_lookup" via JSON spec
+    host_bash.removed    ← name="host_bash" — strip from registry
+```
+
+Rules:
+
+- The **filename stem** is the registered tool name verbatim. There is no
+  derivation, no basename transformation, no directory layer.
+- The loader looks for `.js` first, then `.ts`, then `.json`. The
+  `.js`-preferred ordering matches compiled-binary semantics: a release
+  build that ships compiled artifacts next to source runs the compiled
+  file.
+- `.json` files load as declarative specs — they describe schema and
+  metadata but cannot supply an `execute` function. Calling a
+  JSON-sourced tool returns an `isError` result; they exist for stubs
+  and override placeholders.
+- A `<name>.removed` sentinel file (any contents, typically empty)
+  strips the same-named core tool from the registry without
+  substituting a replacement. Removing the sentinel file restores the
+  core tool on the next reconcile.
+- Filename stems must satisfy `isProviderSafeToolName`
+  (`/^[a-zA-Z0-9_-]{1,64}$/`). A stem with spaces or punctuation is
+  logged at error and skipped; the loader never silently rewrites the
+  name with a hash suffix that would be unfindable.
+- Stems starting with `.` are skipped (so `.gitignore`, `.DS_Store`
+  cannot accidentally register a tool).
+- If `<name>.ts` and `<name>.js` (or any other shadow combination)
+  coexist for the same stem, the winning extension is used and the
+  shadowed siblings are logged at warn.
+
+## Tool file shape
+
+The default export is a generic `ToolDefinition` — the same shape every
+tool surface in the assistant uses. All four normally-required fields
+fall back to documented defaults if omitted, so a misconfigured tool
+still loads cleanly and surfaces its problem at call time rather than
+blocking assistant boot.
+
+```ts
+// /workspace/tools/skill_load.ts
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "@vellumai/plugin-api";
+
+const tool: ToolDefinition = {
+  description: "Skill loader (custom workspace implementation)",
+  defaultRiskLevel: "low",
+  input_schema: {
+    type: "object",
+    properties: { skill_id: { type: "string" } },
+    required: ["skill_id"],
+  },
+  async execute(
+    input: { skill_id: string },
+    ctx: ToolContext,
+  ): Promise<ToolExecutionResult> {
+    return { content: `loaded ${input.skill_id}`, isError: false };
+  },
+};
+
+export default tool;
+```
+
+Defaults applied when fields are omitted:
+
+| Field              | Default                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------------------- |
+| `description`      | `""`                                                                                        |
+| `defaultRiskLevel` | `"high"`                                                                                    |
+| `executionTarget`  | `"sandbox"`                                                                                 |
+| `input_schema`     | `{ type: "object", properties: {}, additionalProperties: false }`                           |
+| `execute`          | Returns `{ content: "workspace tool <name> has no execute implementation", isError: true }` |
+
+## Override semantics
+
+Workspace tools are the highest-priority origin in the tool registry:
+
+- **Same name as a core tool** → the original core tool is moved into an
+  internal stash (`getCoreToolOverride(name)`) and the workspace tool takes
+  its place. Removing the workspace file causes the watcher to restore
+  the original — workspace tools are not destructive to the core baseline.
+- **Brand-new name** → registers as a net-new entry. No stash.
+- **`<name>.removed` sentinel for a core tool** → the core tool is
+  stripped (stashed in the same map as override-style stashing) and no
+  replacement is registered. Deleting the sentinel restores the core
+  tool. Stripping a name that doesn't exist is a logged no-op.
+- **Collision with a skill / plugin / MCP tool of the same name** → the
+  workspace registration throws. Workspace tools must register before
+  other extension categories; seeing one of these owners during a
+  workspace registration means the assistant startup order regressed.
+
+Subsequent (post-workspace-load) registrations from plugins, skills, or
+MCP servers that try to claim a name a workspace tool already owns (or
+has stripped via `.removed`) are **warn-and-skipped**. Plugins, skills,
+and MCP servers cannot bypass this by registering before workspace
+tools load — the lifecycle pins workspace tools to register first.
+
+Skill / plugin / MCP collisions with a workspace tool name across the
+distinct namespacing those surfaces enforce are impossible — each runs
+in its own owner-scoped registry path, and the workspace registration's
+stamping is authoritative regardless of pre-existing ownership fields
+on the incoming tool.
+
+## Lifecycle position
+
+```
+initializeTools()             # core tools register
+  → loadWorkspaceTools()      # initial workspace tool scan
+    → MCP tool registration
+    → loadUserPlugins()
+    → bootstrapPlugins()
+
+# after providers-setup completes:
+DaemonServer.start()
+  → WorkspaceToolsWatcher.getInstance().start()   # hot register/unregister via fs.watch
+```
+
+Workspace tools register _after_ core tools and _before_ every other
+extension surface during the initial scan so that every subsequent
+registration sees the workspace tool as already-owned. The initial scan
+(`loadWorkspaceTools()`) always runs, so workspace tools load from disk
+at every boot regardless of the flag.
+
+The filesystem watcher is gated on the `workspace-tools-watcher` feature
+flag (default off). When enabled, it runs for the lifetime of the
+assistant, picking up add/change/delete events on `<workspaceDir>/tools/`
+and reconciling the registry without requiring a restart. When disabled,
+no watch loop is mounted and live edits to `<workspaceDir>/tools/` take
+effect only on the next daemon restart. The flag is read at startup, so
+toggling it takes effect on restart rather than mid-process.
+
+The watcher debounces per filename stem and reconciles by re-deriving
+the world from disk ("given what's on disk right now for `<stem>.*`,
+what registry state should the assistant be in?") rather than routing
+on `fs.watch`'s unreliable add/change/rename event types. This is the
+same eventual-consistency pattern the plugin source watcher uses.
+
+## Per-tool isolation
+
+A single broken workspace tool must never block assistant boot. The
+loader applies the same per-tool isolation contract as the user-plugin
+loader:
+
+- A `.ts` / `.js` whose module body throws during import is logged at
+  error and skipped — the loader proceeds to the next file.
+- A `.ts` / `.js` whose default export is missing or not an object is
+  logged at error and skipped.
+- A `.json` that doesn't parse, or doesn't decode to an object, is
+  logged at error and skipped.
+- A `.ts` / `.js` whose module evaluation hangs is bounded by a
+  10-second timeout. The abandoned import continues running in the
+  background but the loader has already moved on. Bun's `import()`
+  cannot be cancelled, so the registry guards against late-arriving
+  registrations by the time-bounded path.
+
+The registry's batch validation runs ahead of any mutation, so a single
+late-discovered conflict (e.g. duplicate name within the batch) aborts
+the whole call without partially populating the registry.
+
+## Unregistering
+
+Deleting `<workspaceDir>/tools/<name>.{ts,js,json}` triggers the file
+watcher's reconcile, which calls `unregisterWorkspaceTool(name)` and
+restores the stashed core tool when one exists, or simply deletes the
+entry when the workspace tool was net-new. No assistant restart is
+required.
+
+To strip a core tool without substituting a replacement, drop an empty
+`<workspaceDir>/tools/<name>.removed` file. Removing that sentinel
+restores the core tool on the next reconcile. The two states (override
+vs. strip) are mutually exclusive — placing both `<name>.ts` and
+`<name>.removed` for the same stem causes the watcher to tear down
+both states until the conflict is resolved on disk.

package/openapi.yaml

@@ -24691,9 +24691,12 @@ paths:
       operationId: tools_get
       summary: List registered tools with metadata and schemas
       description:
-        "Return every registered tool. `tools` carries per-tool metadata (description, author-asserted risk level,
-        category, and contributing source: core, skill, plugin, or MCP server). `names`/`schemas` additionally cover
-        skill tools whose manifests are present but not yet loaded, for the permission-simulator catalog."
+        "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:
@@ -24747,6 +24750,13 @@ paths:
                   - 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.202606101122.0de2aff",
+  "version": "0.8.10-dev.202606101436.d73da44",
   "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 () => {