@vellumai/assistant 0.10.7-dev.202607101106.c87f4e3 → 0.10.7-dev.202607101343.e727d4c

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.7-dev.202607101106.c87f4e3",
+  "version": "0.10.7-dev.202607101343.e727d4c",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/agent/loop-exclusive-tool.test.ts

@@ -1,16 +1,41 @@
 /**
- * Verifies the agent loop's exclusive-tool dispatch: when a tool the loop is
- * told is exclusive appears in a multi-call turn, only that tool runs and the
+ * Verifies the agent loop's exclusive-tool dispatch: when a tool the registry
+ * marks exclusive appears in a multi-call turn, only that tool runs and the
  * siblings are deferred un-run with a benign result — so the model incorporates
  * the exclusive tool's output before acting on anything else. Drives the REAL
  * loop, mocking only the provider boundary.
  */
-import { describe, expect, test } from "bun:test";
+import { beforeAll, describe, expect, test } from "bun:test";
 
 import { createMockProvider } from "../__tests__/helpers/mock-provider.js";
+import { RiskLevel } from "../permissions/types.js";
 import type { ContentBlock, ProviderResponse } from "../providers/types.js";
+import { registerTool } from "../tools/registry.js";
+import type { ToolContext, ToolExecutionResult } from "../tools/types.js";
 import { AgentLoop } from "./loop.js";
 
+// The loop reads exclusivity straight from the registry (`getTool(name)
+// ?.exclusive`), so seed a registered tool the loop can look up. Other tool
+// names in these turns are absent from the registry, so they read as
+// non-exclusive — exactly the mixed state the deferral logic branches on.
+beforeAll(() => {
+  registerTool({
+    name: "exclusive_tool",
+    description: "Exclusive test tool",
+    category: "test",
+    defaultRiskLevel: RiskLevel.Low,
+    executionTarget: "sandbox",
+    exclusive: true,
+    input_schema: { type: "object", properties: {}, required: [] },
+    async execute(
+      _input: Record<string, unknown>,
+      _context: ToolContext,
+    ): Promise<ToolExecutionResult> {
+      return { content: "ok", isError: false };
+    },
+  });
+});
+
 const endTurn = (text: string): ProviderResponse => ({
   content: [{ type: "text", text }],
   model: "mock-model",
@@ -82,7 +107,6 @@ describe("AgentLoop — exclusive tool deferral", () => {
         executed.push(name);
         return { content: `ran ${name}`, isError: false };
       },
-      isExclusiveTool: (name) => name === "exclusive_tool",
     });
 
     const { history } = await loop.run({
@@ -137,7 +161,6 @@ describe("AgentLoop — exclusive tool deferral", () => {
         executed.push(name);
         return { content: `ran ${name}`, isError: false };
       },
-      isExclusiveTool: (name) => name === "exclusive_tool",
     });
 
     const { history } = await loop.run({

package/src/agent/loop.ts

@@ -43,6 +43,7 @@ import type {
   ToolResultContent,
 } from "../providers/types.js";
 import { isContextOverflowError } from "../providers/types.js";
+import { getTool } from "../tools/registry.js";
 import type { SensitiveOutputBinding } from "../tools/sensitive-output-placeholders.js";
 import {
   applyStreamingSubstitution,
@@ -708,14 +709,6 @@ export interface AgentLoopConstructorOptions {
   tools?: ToolDefinition[];
   toolExecutor?: LoopToolExecutor;
   resolveTools?: (history: Message[]) => ToolDefinition[];
-  /**
-   * Decide whether a tool runs exclusively in its turn (see
-   * {@link ToolDefinition.exclusive}). When it returns true for a tool present
-   * in a multi-call turn, the loop runs only that tool and defers the siblings
-   * un-run. Injected by the conversation wiring, which can read the tool
-   * registry; lightweight loops that omit it never defer.
-   */
-  isExclusiveTool?: (toolName: string) => boolean;
   /**
    * Conversation this loop drives. Scopes the loop-held compaction circuit
    * breaker and is the source of truth the loop's pipeline contexts and
@@ -741,7 +734,6 @@ export class AgentLoop {
   private tools: ToolDefinition[];
   private resolveTools: ((history: Message[]) => ToolDefinition[]) | null;
   private toolExecutor: LoopToolExecutor | null;
-  private isExclusiveTool: ((toolName: string) => boolean) | null;
 
   /**
    * Conversation this loop drives. Source of truth for the `conversationId`
@@ -771,7 +763,6 @@ export class AgentLoop {
       tools,
       toolExecutor,
       resolveTools,
-      isExclusiveTool,
       conversationId,
       resolveConversationDir,
     } = options;
@@ -781,7 +772,6 @@ export class AgentLoop {
     this.tools = tools ?? [];
     this.resolveTools = resolveTools ?? null;
     this.toolExecutor = toolExecutor ?? null;
-    this.isExclusiveTool = isExclusiveTool ?? null;
     this.conversationId = conversationId;
     this.resolveConversationDir = resolveConversationDir ?? null;
     this.compactionCircuit = new CompactionCircuit(this.conversationId);
@@ -2069,9 +2059,9 @@ export class AgentLoop {
         // the siblings with a benign, un-run result so the model re-issues them
         // next turn if still needed. Every tool_use still gets a matching
         // tool_result, so history stays well-formed.
-        const exclusiveBlock = this.isExclusiveTool
-          ? toolUseBlocks.find((block) => this.isExclusiveTool!(block.name))
-          : undefined;
+        const exclusiveBlock = toolUseBlocks.find(
+          (block) => getTool(block.name)?.exclusive === true,
+        );
         const deferSiblings =
           exclusiveBlock !== undefined && toolUseBlocks.length > 1;
         if (deferSiblings) {

package/src/cli/commands/attachment.help.ts

@@ -0,0 +1,100 @@
+/**
+ * Declarative help for the `assistant attachment` command.
+ *
+ * Plain data (no action handlers, imports only the help contract type) so the
+ * memory capability indexer can read it without pulling in the daemon/IPC action
+ * graph. The handlers live in `attachment.ts`, which applies this via
+ * `applyCommandHelp` and attaches them.
+ */
+
+import type { CliCommandHelp } from "../lib/cli-command-help.js";
+
+export const attachmentHelp: CliCommandHelp = {
+  name: "attachment",
+  description: "Manage file attachments for conversations",
+  helpText: `
+Attachments come in two flavours:
+
+  File-backed   Large files stored by path reference (no memory copy).
+                The file must remain on disk for the lifetime of the
+                attachment.
+  Inline        Small payloads encoded directly (handled internally).
+
+Use 'register' to record a file-backed attachment and 'lookup' to
+retrieve its stored path by the original source location.
+
+Examples:
+  $ assistant attachment register --path /tmp/clip.mp4 --mime video/mp4
+  $ assistant attachment register --path /tmp/clip.mp4 --mime video/mp4 --filename recording.mp4
+  $ assistant attachment lookup --source /tmp/clip.mp4 --conversation conv_abc123`,
+  subcommands: [
+    {
+      name: "register",
+      description: "Register a file-backed attachment with the assistant",
+      options: [
+        {
+          flags: "--path <file>",
+          description: "Absolute path to the file (required)",
+          required: true,
+        },
+        {
+          flags: "--mime <type>",
+          description: "MIME type of the file (required)",
+          required: true,
+        },
+        {
+          flags: "--filename <name>",
+          description: "Display filename (defaults to basename of path)",
+        },
+        {
+          flags: "--json",
+          description: "Output result as machine-readable JSON.",
+        },
+      ],
+      helpText: `
+Registers a file on disk as a file-backed attachment in the assistant's
+attachment store. The file must exist at the given path and must remain
+on disk for the lifetime of the attachment — the assistant stores a
+path reference, not a copy.
+
+Returns the attachment ID and metadata on success.
+
+Examples:
+  $ assistant attachment register --path /tmp/clip.mp4 --mime video/mp4
+  $ assistant attachment register --path /tmp/screen.png --mime image/png --filename screenshot.png
+  $ assistant attachment register --path /tmp/audio.wav --mime audio/wav --json`,
+    },
+    {
+      name: "lookup",
+      description: "Look up a stored attachment by its original source path",
+      options: [
+        {
+          flags: "--source <path>",
+          description: "Original source path of the file (required)",
+          required: true,
+        },
+        {
+          flags: "--conversation <id>",
+          description:
+            "Conversation ID to search within (required) — run 'assistant conversations list' to find it",
+          required: true,
+        },
+        {
+          flags: "--json",
+          description: "Output result as machine-readable JSON.",
+        },
+      ],
+      helpText: `
+Searches for an attachment that was previously registered with the
+given source path, scoped to a specific conversation. Returns the
+stored file path on success.
+
+Attachments are linked to messages within conversations. Use
+'assistant conversations list' to find the conversation ID.
+
+Examples:
+  $ assistant attachment lookup --source /tmp/clip.mp4 --conversation conv_abc123
+  $ assistant attachment lookup --source /path/to/recording.mp4 --conversation conv_xyz --json`,
+    },
+  ],
+};

package/src/cli/commands/attachment.ts

@@ -3,189 +3,124 @@
  *
  * Subcommands: register, lookup — thin wrappers over the daemon's
  * attachment routes (`attachment_register`, `attachment_lookup`).
+ *
+ * The command's help structure lives in `attachment.help.ts` (import-safe for
+ * the memory capability indexer); this module applies it and attaches the
+ * action handlers.
  */
 
 import type { Command } from "commander";
 
 import { cliIpcCall } from "../../ipc/cli-client.js";
+import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
 import { shouldOutputJson, writeOutput } from "../output.js";
+import { attachmentHelp } from "./attachment.help.js";
 
 // ── Registration ──────────────────────────────────────────────────────
 
 export function registerAttachmentCommand(program: Command): void {
   registerCommand(program, {
-    name: "attachment",
+    name: attachmentHelp.name,
     transport: "ipc",
-    description: "Manage file attachments for conversations",
+    description: attachmentHelp.description,
     build: (attachment) => {
+      applyCommandHelp(attachment, attachmentHelp);
+
+      // ── register ───────────────────────────────────────────────────
+      subcommand(attachment, "register").action(
+        async (
+          opts: {
+            path: string;
+            mime: string;
+            filename?: string;
+            json?: boolean;
+          },
+          cmd: Command,
+        ) => {
+          const jsonOutput = opts.json || shouldOutputJson(cmd);
+
+          const result = await cliIpcCall<{
+            id: string;
+            originalFilename: string;
+            mimeType: string;
+            sizeBytes: number;
+            kind: string;
+            filePath: string;
+            createdAt: number;
+          }>("attachment_register", {
+            body: {
+              path: opts.path,
+              mimeType: opts.mime,
+              filename: opts.filename,
+            },
+          });
 
-  attachment.addHelpText(
-    "after",
-    `
-Attachments come in two flavours:
-
-  File-backed   Large files stored by path reference (no memory copy).
-                The file must remain on disk for the lifetime of the
-                attachment.
-  Inline        Small payloads encoded directly (handled internally).
-
-Use 'register' to record a file-backed attachment and 'lookup' to
-retrieve its stored path by the original source location.
-
-Examples:
-  $ assistant attachment register --path /tmp/clip.mp4 --mime video/mp4
-  $ assistant attachment register --path /tmp/clip.mp4 --mime video/mp4 --filename recording.mp4
-  $ assistant attachment lookup --source /tmp/clip.mp4 --conversation conv_abc123`,
-  );
-
-  // ── register ─────────────────────────────────────────────────────
-
-  attachment
-    .command("register")
-    .description("Register a file-backed attachment with the assistant")
-    .requiredOption("--path <file>", "Absolute path to the file (required)")
-    .requiredOption("--mime <type>", "MIME type of the file (required)")
-    .option(
-      "--filename <name>",
-      "Display filename (defaults to basename of path)",
-    )
-    .option("--json", "Output result as machine-readable JSON.")
-    .addHelpText(
-      "after",
-      `
-Registers a file on disk as a file-backed attachment in the assistant's
-attachment store. The file must exist at the given path and must remain
-on disk for the lifetime of the attachment — the assistant stores a
-path reference, not a copy.
-
-Returns the attachment ID and metadata on success.
-
-Examples:
-  $ assistant attachment register --path /tmp/clip.mp4 --mime video/mp4
-  $ assistant attachment register --path /tmp/screen.png --mime image/png --filename screenshot.png
-  $ assistant attachment register --path /tmp/audio.wav --mime audio/wav --json`,
-    )
-    .action(
-      async (
-        opts: {
-          path: string;
-          mime: string;
-          filename?: string;
-          json?: boolean;
-        },
-        cmd: Command,
-      ) => {
-        const jsonOutput = opts.json || shouldOutputJson(cmd);
+          if (!result.ok) {
+            if (jsonOutput) {
+              writeOutput(cmd, { ok: false, error: result.error });
+            } else {
+              log.error(result.error ?? "Unknown error");
+            }
+            process.exitCode = 1;
+            return;
+          }
 
-        const result = await cliIpcCall<{
-          id: string;
-          originalFilename: string;
-          mimeType: string;
-          sizeBytes: number;
-          kind: string;
-          filePath: string;
-          createdAt: number;
-        }>("attachment_register", {
-          body: {
-            path: opts.path,
-            mimeType: opts.mime,
-            filename: opts.filename,
-          },
-        });
+          const record = result.result!;
 
-        if (!result.ok) {
           if (jsonOutput) {
-            writeOutput(cmd, { ok: false, error: result.error });
+            writeOutput(cmd, { ok: true, ...record });
           } else {
-            log.error(result.error ?? "Unknown error");
+            process.stdout.write(`${record.id}\n`);
+            log.info(`Attachment registered: ${record.id}`);
+            log.info(`  Filename: ${record.originalFilename}`);
+            log.info(`  MIME:     ${record.mimeType}`);
+            log.info(`  Size:     ${record.sizeBytes} bytes`);
+            log.info(`  Kind:     ${record.kind}`);
+            log.info(`  Path:     ${record.filePath}`);
           }
-          process.exitCode = 1;
-          return;
-        }
-
-        const record = result.result!;
-
-        if (jsonOutput) {
-          writeOutput(cmd, { ok: true, ...record });
-        } else {
-          process.stdout.write(`${record.id}\n`);
-          log.info(`Attachment registered: ${record.id}`);
-          log.info(`  Filename: ${record.originalFilename}`);
-          log.info(`  MIME:     ${record.mimeType}`);
-          log.info(`  Size:     ${record.sizeBytes} bytes`);
-          log.info(`  Kind:     ${record.kind}`);
-          log.info(`  Path:     ${record.filePath}`);
-        }
-      },
-    );
-
-  // ── lookup ───────────────────────────────────────────────────────
-
-  attachment
-    .command("lookup")
-    .description("Look up a stored attachment by its original source path")
-    .requiredOption(
-      "--source <path>",
-      "Original source path of the file (required)",
-    )
-    .requiredOption(
-      "--conversation <id>",
-      "Conversation ID to search within (required) — run 'assistant conversations list' to find it",
-    )
-    .option("--json", "Output result as machine-readable JSON.")
-    .addHelpText(
-      "after",
-      `
-Searches for an attachment that was previously registered with the
-given source path, scoped to a specific conversation. Returns the
-stored file path on success.
-
-Attachments are linked to messages within conversations. Use
-'assistant conversations list' to find the conversation ID.
-
-Examples:
-  $ assistant attachment lookup --source /tmp/clip.mp4 --conversation conv_abc123
-  $ assistant attachment lookup --source /path/to/recording.mp4 --conversation conv_xyz --json`,
-    )
-    .action(
-      async (
-        opts: { source: string; conversation: string; json?: boolean },
-        cmd: Command,
-      ) => {
-        const jsonOutput = opts.json || shouldOutputJson(cmd);
-
-        const result = await cliIpcCall<{ filePath: string }>(
-          "attachment_lookup",
-          {
-            body: {
-              sourcePath: opts.source,
-              conversationId: opts.conversation,
+        },
+      );
+
+      // ── lookup ─────────────────────────────────────────────────────
+      subcommand(attachment, "lookup").action(
+        async (
+          opts: { source: string; conversation: string; json?: boolean },
+          cmd: Command,
+        ) => {
+          const jsonOutput = opts.json || shouldOutputJson(cmd);
+
+          const result = await cliIpcCall<{ filePath: string }>(
+            "attachment_lookup",
+            {
+              body: {
+                sourcePath: opts.source,
+                conversationId: opts.conversation,
+              },
             },
-          },
-        );
+          );
+
+          if (!result.ok) {
+            if (jsonOutput) {
+              writeOutput(cmd, { ok: false, error: result.error });
+            } else {
+              log.error(result.error ?? "Unknown error");
+            }
+            process.exitCode = 1;
+            return;
+          }
 
-        if (!result.ok) {
           if (jsonOutput) {
-            writeOutput(cmd, { ok: false, error: result.error });
+            writeOutput(cmd, {
+              ok: true,
+              filePath: result.result!.filePath,
+            });
           } else {
-            log.error(result.error ?? "Unknown error");
+            process.stdout.write(result.result!.filePath + "\n");
           }
-          process.exitCode = 1;
-          return;
-        }
-
-        if (jsonOutput) {
-          writeOutput(cmd, {
-            ok: true,
-            filePath: result.result!.filePath,
-          });
-        } else {
-          process.stdout.write(result.result!.filePath + "\n");
-        }
-      },
-    );
+        },
+      );
     },
   });
 }

package/src/cli/commands/audit.help.ts

@@ -0,0 +1,40 @@
+/**
+ * Declarative help for the `assistant audit` command.
+ *
+ * Plain data (no action handlers, imports only the help contract type) so the
+ * memory capability indexer can read it without pulling in the daemon/IPC action
+ * graph. The handler lives in `audit.ts`, which applies this via
+ * `applyCommandHelp` and attaches it.
+ */
+
+import type { CliCommandHelp } from "../lib/cli-command-help.js";
+
+export const auditHelp: CliCommandHelp = {
+  name: "audit",
+  description: "Show recent tool invocations",
+  options: [
+    {
+      flags: "-l, --limit <n>",
+      description: "Number of entries to show",
+      defaultValue: "20",
+    },
+    { flags: "--json", description: "Output raw JSON" },
+  ],
+  helpText: `
+Reads from the tool invocation audit log via the daemon. Each row
+represents one tool call the assistant made, including what was invoked,
+how the approval system classified it, and how long it took.
+
+Table columns:
+  Timestamp   When the tool was invoked (UTC, YYYY-MM-DD HH:MM:SS)
+  Tool        Tool name (e.g. bash, read_file, write_file, browser)
+  Input       Truncated summary of the tool input (command, path, etc.)
+  Decision    Approval decision: allow, deny, or ask
+  Risk        Risk classification: none, low, medium, high
+  Duration    Wall-clock execution time (e.g. 120ms, 1.3s)
+
+Examples:
+  $ assistant audit
+  $ assistant audit --limit 50
+  $ assistant audit --json`,
+};