@vellumai/assistant 0.10.7-dev.202607101106.c87f4e3 → 0.10.7-dev.202607101252.74ea83d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.7-dev.202607101106.c87f4e3",
+  "version": "0.10.7-dev.202607101252.74ea83d",
   "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`,
+};

package/src/cli/commands/audit.ts

@@ -1,8 +1,10 @@
 import type { Command } from "commander";
 
 import { cliIpcCall, exitFromIpcResult } from "../../ipc/cli-client.js";
+import { applyCommandHelp } from "../lib/cli-command-help.js";
 import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
+import { auditHelp } from "./audit.help.js";
 
 interface ToolInvocationRow {
   toolName: string;
@@ -15,100 +17,78 @@ interface ToolInvocationRow {
 
 export function registerAuditCommand(program: Command): void {
   registerCommand(program, {
-    name: "audit",
+    name: auditHelp.name,
     transport: "ipc",
-    description: "Show recent tool invocations",
+    description: auditHelp.description,
     build: (audit) => {
-      audit
-        .option("-l, --limit <n>", "Number of entries to show", "20")
-        .option("--json", "Output raw JSON")
-        .addHelpText(
-          "after",
-          `
-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)
+      applyCommandHelp(audit, auditHelp);
+      audit.action(async (opts: { limit: string; json?: boolean }) => {
+        const limit = parseInt(opts.limit, 10) || 20;
+        const response = await cliIpcCall<{
+          invocations: ToolInvocationRow[];
+        }>("audit_list", {
+          queryParams: { limit: String(limit) },
+        });
+        if (!response.ok) {
+          return exitFromIpcResult(response);
+        }
+        const rows = response.result!.invocations;
 
-Examples:
-  $ assistant audit
-  $ assistant audit --limit 50
-  $ assistant audit --json`,
-        )
-        .action(async (opts: { limit: string; json?: boolean }) => {
-          const limit = parseInt(opts.limit, 10) || 20;
-          const response = await cliIpcCall<{
-            invocations: ToolInvocationRow[];
-          }>("audit_list", {
-            queryParams: { limit: String(limit) },
-          });
-          if (!response.ok) {
-            return exitFromIpcResult(response);
-          }
-          const rows = response.result!.invocations;
+        if (opts.json) {
+          console.log(JSON.stringify(rows, null, 2));
+          return;
+        }
 
-          if (opts.json) {
-            console.log(JSON.stringify(rows, null, 2));
-            return;
+        if (rows.length === 0) {
+          log.info("No tool invocations recorded");
+          return;
+        }
+        const tsW = 20;
+        const toolW = 14;
+        const inputW = 30;
+        const decW = 8;
+        const riskW = 8;
+        const durW = 8;
+        log.info(
+          "Timestamp".padEnd(tsW) +
+            "Tool".padEnd(toolW) +
+            "Input".padEnd(inputW) +
+            "Decision".padEnd(decW) +
+            "Risk".padEnd(riskW) +
+            "Duration",
+        );
+        log.info("-".repeat(tsW + toolW + inputW + decW + riskW + durW));
+        for (const r of rows) {
+          const ts = new Date(r.createdAt)
+            .toISOString()
+            .slice(0, 19)
+            .replace("T", " ");
+          let inputSummary = "";
+          try {
+            const parsed = JSON.parse(r.input);
+            if (parsed.command) inputSummary = parsed.command;
+            else if (parsed.path) inputSummary = parsed.path;
+            else inputSummary = r.input;
+          } catch {
+            inputSummary = r.input;
           }
-
-          if (rows.length === 0) {
-            log.info("No tool invocations recorded");
-            return;
+          if (inputSummary.length > inputW - 2) {
+            inputSummary = inputSummary.slice(0, inputW - 4) + "..";
           }
-          const tsW = 20;
-          const toolW = 14;
-          const inputW = 30;
-          const decW = 8;
-          const riskW = 8;
-          const durW = 8;
+          const dur =
+            r.durationMs < 1000
+              ? `${r.durationMs}ms`
+              : `${(r.durationMs / 1000).toFixed(1)}s`;
           log.info(
-            "Timestamp".padEnd(tsW) +
-              "Tool".padEnd(toolW) +
-              "Input".padEnd(inputW) +
-              "Decision".padEnd(decW) +
-              "Risk".padEnd(riskW) +
-              "Duration",
+            ts.padEnd(tsW) +
+              r.toolName.padEnd(toolW) +
+              inputSummary.padEnd(inputW) +
+              r.decision.padEnd(decW) +
+              r.riskLevel.padEnd(riskW) +
+              dur,
           );
-          log.info("-".repeat(tsW + toolW + inputW + decW + riskW + durW));
-          for (const r of rows) {
-            const ts = new Date(r.createdAt)
-              .toISOString()
-              .slice(0, 19)
-              .replace("T", " ");
-            let inputSummary = "";
-            try {
-              const parsed = JSON.parse(r.input);
-              if (parsed.command) inputSummary = parsed.command;
-              else if (parsed.path) inputSummary = parsed.path;
-              else inputSummary = r.input;
-            } catch {
-              inputSummary = r.input;
-            }
-            if (inputSummary.length > inputW - 2) {
-              inputSummary = inputSummary.slice(0, inputW - 4) + "..";
-            }
-            const dur =
-              r.durationMs < 1000
-                ? `${r.durationMs}ms`
-                : `${(r.durationMs / 1000).toFixed(1)}s`;
-            log.info(
-              ts.padEnd(tsW) +
-                r.toolName.padEnd(toolW) +
-                inputSummary.padEnd(inputW) +
-                r.decision.padEnd(decW) +
-                r.riskLevel.padEnd(riskW) +
-                dur,
-            );
-          }
-        });
+        }
+      });
     },
   });
 }

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

@@ -0,0 +1,46 @@
+/**
+ * Declarative help for the `assistant auth` 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 `auth.ts`, which applies this via `applyCommandHelp`
+ * and attaches them.
+ */
+
+import type { CliCommandHelp } from "../lib/cli-command-help.js";
+
+export const authHelp: CliCommandHelp = {
+  name: "auth",
+  description: "Manage platform authentication and identity",
+  options: [
+    { flags: "--json", description: "Machine-readable compact JSON output" },
+  ],
+  helpText: `
+The auth namespace manages the assistant's authentication state with the
+Vellum platform. It provides commands to inspect identity and connection
+status, helping diagnose configuration issues.
+
+Examples:
+  $ assistant auth info
+  $ assistant auth info --json`,
+  subcommands: [
+    {
+      name: "info",
+      description: "Show platform identity and authentication status",
+      helpText: `
+Fields:
+  platformUrl         The Vellum platform base URL this assistant connects to
+  assistantId         This assistant's platform UUID
+  organizationId      The organization this assistant belongs to (from PLATFORM_ORGANIZATION_ID)
+  userId              The user who owns this assistant (from PLATFORM_USER_ID)
+  authenticated       Whether all prerequisites for platform authentication are met
+                      (platform URL and assistant API key both present)
+
+When not authenticated, a message field provides guidance on next steps.
+
+Examples:
+  $ assistant auth info
+  $ assistant auth info --json`,
+    },
+  ],
+};

package/src/cli/commands/auth.ts

@@ -1,9 +1,11 @@
 import type { Command } from "commander";
 
 import { cliIpcCall, exitFromIpcResult } 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 { authHelp } from "./auth.help.js";
 
 interface AuthInfoResponse {
   platformUrl: string | null;
@@ -16,51 +18,15 @@ interface AuthInfoResponse {
 
 export function registerAuthCommand(program: Command): void {
   registerCommand(program, {
-    name: "auth",
+    name: authHelp.name,
     transport: "ipc",
-    description: "Manage platform authentication and identity",
+    description: authHelp.description,
     build: (auth) => {
-      auth.option("--json", "Machine-readable compact JSON output");
+      applyCommandHelp(auth, authHelp);
 
-      auth.addHelpText(
-        "after",
-        `
-The auth namespace manages the assistant's authentication state with the
-Vellum platform. It provides commands to inspect identity and connection
-status, helping diagnose configuration issues.
-
-Examples:
-  $ assistant auth info
-  $ assistant auth info --json`,
-      );
-
-      // -----------------------------------------------------------------------
-      // info
-      // -----------------------------------------------------------------------
-
-      auth
-        .command("info")
-        .description("Show platform identity and authentication status")
-        .addHelpText(
-          "after",
-          `
-Fields:
-  platformUrl         The Vellum platform base URL this assistant connects to
-  assistantId         This assistant's platform UUID
-  organizationId      The organization this assistant belongs to (from PLATFORM_ORGANIZATION_ID)
-  userId              The user who owns this assistant (from PLATFORM_USER_ID)
-  authenticated       Whether all prerequisites for platform authentication are met
-                      (platform URL and assistant API key both present)
-
-When not authenticated, a message field provides guidance on next steps.
-
-Examples:
-  $ assistant auth info
-  $ assistant auth info --json`,
-        )
-        .action(async (_opts: Record<string, unknown>, cmd: Command) => {
-          const response =
-            await cliIpcCall<AuthInfoResponse>("auth_info");
+      subcommand(auth, "info").action(
+        async (_opts: Record<string, unknown>, cmd: Command) => {
+          const response = await cliIpcCall<AuthInfoResponse>("auth_info");
 
           if (!response.ok) {
             return exitFromIpcResult(response);
@@ -89,7 +55,8 @@ Examples:
               log.info(result.message);
             }
           }
-        });
+        },
+      );
     },
   });
 }

package/src/cli/index.help.ts

@@ -0,0 +1,23 @@
+/**
+ * Aggregated declarative help for the top-level `assistant` CLI commands that
+ * have adopted the static-help split (`<command>.help.ts`).
+ *
+ * Plugins — notably the memory capability indexer — import this to read command
+ * help without importing `cli/program.ts`, which pulls every command's action
+ * handler (and its daemon/IPC deps) into the import graph. Entries are pure data
+ * (see {@link ./lib/cli-command-help.CliCommandHelp}); consumers iterate them.
+ *
+ * Extend this as commands adopt the split. Once every command is listed here,
+ * the memory indexer no longer needs `buildCliProgramTree()`.
+ */
+
+import { attachmentHelp } from "./commands/attachment.help.js";
+import { auditHelp } from "./commands/audit.help.js";
+import { authHelp } from "./commands/auth.help.js";
+import type { CliCommandHelp } from "./lib/cli-command-help.js";
+
+export const CLI_COMMAND_HELP: readonly CliCommandHelp[] = [
+  attachmentHelp,
+  auditHelp,
+  authHelp,
+];

package/src/cli/lib/cli-command-help.ts

@@ -0,0 +1,80 @@
+import type { Command } from "commander";
+
+/**
+ * Fully declarative description of a top-level `assistant` CLI command and its
+ * subcommands. Plain data by design — no action handlers — so plugins (e.g. the
+ * memory capability indexer) can import a command's help and iterate over it
+ * without dragging in the CLI's daemon/IPC action graph. Command modules apply
+ * the same data via {@link applyCommandHelp}, then attach their handlers.
+ */
+export interface CliCommandHelp {
+  name: string;
+  description: string;
+  /** Options declared directly on the top-level command. */
+  options?: CliOptionHelp[];
+  /** Extra help appended after the option list (`addHelpText("after", …)`). */
+  helpText?: string;
+  subcommands?: CliSubcommandHelp[];
+}
+
+export interface CliSubcommandHelp {
+  name: string;
+  description: string;
+  options?: CliOptionHelp[];
+  /** Extra help appended after the option list (`addHelpText("after", …)`). */
+  helpText?: string;
+}
+
+export interface CliOptionHelp {
+  /** Commander flag spec, e.g. `"--path <file>"` or `"-l, --limit <n>"`. */
+  flags: string;
+  description: string;
+  /** When true, applied via `requiredOption` (missing → error) rather than `option`. */
+  required?: boolean;
+  /** Default value passed to `option(flags, description, defaultValue)`. */
+  defaultValue?: string;
+}
+
+function applyOptions(command: Command, options?: CliOptionHelp[]): void {
+  for (const option of options ?? []) {
+    if (option.required) {
+      command.requiredOption(option.flags, option.description);
+    } else if (option.defaultValue !== undefined) {
+      command.option(option.flags, option.description, option.defaultValue);
+    } else {
+      command.option(option.flags, option.description);
+    }
+  }
+}
+
+/**
+ * Configure a Commander command from its declarative {@link CliCommandHelp}:
+ * top-level options, appended help text, and subcommands (with their options).
+ * Does not set the top-level name/description — `registerCommand` owns those —
+ * and does not attach action handlers; the command module attaches those to the
+ * command or its subcommands.
+ */
+export function applyCommandHelp(command: Command, help: CliCommandHelp): void {
+  applyOptions(command, help.options);
+  if (help.helpText) {
+    command.addHelpText("after", help.helpText);
+  }
+  for (const sub of help.subcommands ?? []) {
+    const child = command.command(sub.name).description(sub.description);
+    applyOptions(child, sub.options);
+    if (sub.helpText) {
+      child.addHelpText("after", sub.helpText);
+    }
+  }
+}
+
+/** Return a subcommand by name, throwing if absent. */
+export function subcommand(parent: Command, name: string): Command {
+  const found = parent.commands.find((c) => c.name() === name);
+  if (!found) {
+    throw new Error(
+      `Subcommand "${name}" not found on "${parent.name()}" — is it declared in the command's .help module?`,
+    );
+  }
+  return found;
+}

package/src/daemon/conversation.ts

@@ -74,7 +74,7 @@ import {
   type SystemPromptPersonaOverride,
 } from "../prompts/system-prompt.js";
 import type { ContentBlock, Message } from "../providers/types.js";
-import type { Provider } from "../providers/types.js";
+import type { Provider, ToolDefinition } from "../providers/types.js";
 import { type TrustClass } from "../runtime/actor-trust-resolver.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import type { AuthContext } from "../runtime/auth/types.js";
@@ -768,9 +768,6 @@ export class Conversation {
       tools: toolDefs.length > 0 ? toolDefs : undefined,
       toolExecutor: toolDefs.length > 0 ? toolExecutor : undefined,
       resolveTools,
-      // A tool the registry marks exclusive (e.g. `advisor`) runs alone in its
-      // turn; the loop defers any sibling calls until the next turn.
-      isExclusiveTool: (name) => getTool(name)?.exclusive === true,
       resolveConversationDir: () => {
         const conv = getConversation(this.conversationId);
         if (!conv) {
@@ -2379,6 +2376,26 @@ export class Conversation {
     return new Set(this.lastResolvedToolNames ?? this.coreToolNames);
   }
 
+  /**
+   * The {@link getRegisteredToolNames} inventory resolved to full definitions
+   * (name, description, input schema), sorted by name. Resolution reads the
+   * live registry so skill/MCP tools — whose definitions are not in the base
+   * turn snapshot — are included. Consumers (e.g. turn-trace telemetry) read
+   * this instead of reaching into the tool registry themselves.
+   */
+  getRegisteredToolDefinitions(): ToolDefinition[] {
+    return Array.from(this.getRegisteredToolNames())
+      .sort((a, b) => a.localeCompare(b))
+      .map((name) => {
+        const tool = getTool(name);
+        return {
+          name,
+          description: tool?.description ?? "",
+          input_schema: tool?.input_schema ?? {},
+        };
+      });
+  }
+
   // ── History ──────────────────────────────────────────────────────
 
   getMessages(): Message[] {

package/src/plugin-api/index.ts

@@ -180,6 +180,11 @@ export {
   getAssistantName,
   resolveUserName,
 } from "../daemon/identity-helpers.js";
+// Declarative help for the top-level `assistant` CLI commands that have adopted
+// the static-help split. Plugins (e.g. the memory capability indexer) read this
+// to embed CLI command capabilities without importing the CLI action graph.
+// Pure data — iterate the fields directly.
+export { CLI_COMMAND_HELP } from "../cli/index.help.js";
 // Embeddings — self-contained operations on the host's shared embedding /
 // vector-store subsystem. Host-resolved: each reads the live workspace config
 // internally, so plugins hold no config. Async because the facade loads the

package/src/plugins/defaults/memory/v2/__tests__/cli-command-store.test.ts

@@ -109,6 +109,12 @@ mock.module("../../../../../cli/program.js", () => ({
   },
 }));
 
+// Keep the suite driven entirely by the mocked program tree above: no commands
+// are sourced from the declarative `cli/index.help.ts` aggregate.
+mock.module("../../../../../cli/index.help.js", () => ({
+  CLI_COMMAND_HELP: [],
+}));
+
 mock.module(
   "../../../../../persistence/embeddings/embedding-backend.js",
   () => ({

package/src/plugins/defaults/memory/v2/cli-command-content.ts

@@ -10,6 +10,12 @@
  * size without trouble, and trimming would drop the very examples and flag
  * descriptions that make commands semantically findable.
  */
+
+import type { CLI_COMMAND_HELP } from "@vellumai/plugin-api";
+
+/** Element type of the plugin-api's declarative CLI help constant. */
+type CliCommandHelp = (typeof CLI_COMMAND_HELP)[number];
+
 export function buildCliCommandContent(
   name: string,
   description: string,
@@ -17,3 +23,49 @@ export function buildCliCommandContent(
 ): string {
   return `The "assistant ${name}" CLI command is available. ${description}.\n\nFull help:\n${helpText}`;
 }
+
+/**
+ * Render capability content from a command's declarative {@link CliCommandHelp}
+ * (flags, subcommands, help prose) for commands that have adopted the static-help
+ * split. Produces the same prose lead-in as {@link buildCliCommandContent} with a
+ * data-derived help body, so commands read declaratively are indexed the same way
+ * as those still read from the Commander tree.
+ */
+export function buildCliCommandHelpContent(help: CliCommandHelp): string {
+  const sections: string[] = [];
+  const topOptions = renderOptionLines(help.options);
+  if (topOptions) {
+    sections.push(topOptions);
+  }
+  if (help.helpText) {
+    sections.push(help.helpText.trim());
+  }
+  for (const sub of help.subcommands ?? []) {
+    const lines = [`${help.name} ${sub.name} — ${sub.description}`];
+    const options = renderOptionLines(sub.options);
+    if (options) {
+      lines.push(options);
+    }
+    if (sub.helpText) {
+      lines.push(sub.helpText.trim());
+    }
+    sections.push(lines.join("\n"));
+  }
+  return buildCliCommandContent(
+    help.name,
+    help.description,
+    sections.join("\n\n"),
+  );
+}
+
+function renderOptionLines(options: CliCommandHelp["options"]): string | null {
+  if (!options?.length) {
+    return null;
+  }
+  return options
+    .map(
+      (option) =>
+        `  ${option.flags}${option.required ? " (required)" : ""}  ${option.description}`,
+    )
+    .join("\n");
+}

package/src/plugins/defaults/memory/v2/cli-command-store.ts

@@ -20,12 +20,17 @@
 //   - No MCP-style augmentation — Commander's description is the canonical
 //     summary.
 
+import { CLI_COMMAND_HELP } from "@vellumai/plugin-api";
+
 import { getConfig } from "../../../../config/loader.js";
 import { generateSparseEmbedding } from "../../../../persistence/embeddings/embedding-backend.js";
 import { applyCorrectionIfCalibrated } from "../anisotropy.js";
 import { embedWithBackend } from "../embeddings.js";
 import { getLogger } from "../logging.js";
-import { buildCliCommandContent } from "./cli-command-content.js";
+import {
+  buildCliCommandContent,
+  buildCliCommandHelpContent,
+} from "./cli-command-content.js";
 import { invalidatePageIndex } from "./page-index.js";
 import {
   backfillKindOnPointsWithPrefix,
@@ -135,21 +140,37 @@ function resolveSeedWaiters(): void {
 async function runSeedV2CliCommandEntries(generation: number): Promise<void> {
   try {
     const config = getConfig();
-    // Dynamic import so callers that only need `getCliCommandCapability` or
-    // `listCliCommandEntries` (e.g. the render path inside `injection.ts` and
-    // the `page-index.ts` dependency loader) never drag the full CLI command
-    // graph into their import tree. The CLI tree pulls in many provider and
-    // workspace modules whose presence has been a recurring source of test-
-    // mock cascades and circular-import surprises.
+    const seeds: CliCommandEntry[] = [];
+    const declarativeNames = new Set<string>();
+
+    // Commands that have adopted the static-help split are read from their
+    // declarative help (exposed via `@vellumai/plugin-api`) — pure data, no CLI
+    // action graph. Content is rendered from that data here in the plugin.
+    for (const help of CLI_COMMAND_HELP) {
+      declarativeNames.add(help.name);
+      seeds.push({
+        id: help.name,
+        description: help.description,
+        content: buildCliCommandHelpContent(help),
+      });
+    }
+
+    // Remaining commands still come from the Commander tree. Dynamic import so
+    // callers that only need `getCliCommandCapability` or `listCliCommandEntries`
+    // (e.g. the render path inside `injection.ts` and the `page-index.ts`
+    // dependency loader) never drag the full CLI command graph into their import
+    // tree. The CLI tree pulls in many provider and workspace modules whose
+    // presence has been a recurring source of test-mock cascades and
+    // circular-import surprises.
     const { buildCliProgramTree } = await import("../../../../cli/program.js");
     const program = buildCliProgramTree();
 
-    const seeds: CliCommandEntry[] = [];
     for (const cmd of program.commands) {
       const name = cmd.name();
       // Skip the `help` builtin Commander adds automatically — it carries no
-      // capability information of its own and is uniform across commands.
-      if (name === "help") continue;
+      // capability information of its own — and commands already sourced
+      // declaratively above.
+      if (name === "help" || declarativeNames.has(name)) continue;
       const description = cmd.description();
       const content = buildCliCommandContent(
         name,

package/src/telemetry/turn-trace-store.test.ts

@@ -26,28 +26,17 @@ let mockLiveConversation:
   | {
       isProcessing: () => boolean;
       getCurrentSystemPrompt?: () => string;
-      getRegisteredToolNames?: () => Set<string>;
+      getRegisteredToolDefinitions?: () => Array<{
+        name: string;
+        description: string;
+        input_schema: object;
+      }>;
     }
   | undefined;
 mock.module("../daemon/conversation-registry.js", () => ({
   findConversation: () => mockLiveConversation,
 }));
 
-// Stub the tool registry so trace assembly can resolve descriptions without
-// loading the real tool graph. Returns `undefined` by default; tests override
-// for specific tool names.
-let mockToolDescriptions: Record<string, string> = {};
-mock.module("../tools/registry.js", () => ({
-  getTool: (name: string) =>
-    mockToolDescriptions[name]
-      ? { description: mockToolDescriptions[name], input_schema: {} }
-      : undefined,
-  resolveTool: (name: string) =>
-    mockToolDescriptions[name]
-      ? { description: mockToolDescriptions[name], input_schema: {} }
-      : undefined,
-}));
-
 import { createConversation } from "../persistence/conversation-crud.js";
 import { getDb } from "../persistence/db-connection.js";
 import { initializeDb } from "../persistence/db-init.js";
@@ -72,7 +61,6 @@ function purge(): void {
 beforeEach(() => {
   purge();
   mockLiveConversation = undefined;
-  mockToolDescriptions = {};
 });
 
 interface MessageSeed {
@@ -238,16 +226,16 @@ describe("assembleTurnTrace", () => {
       createdAt: 1100,
     });
 
+    // The conversation resolves + sorts its registered tools; trace assembly
+    // just maps them into the trace, so feed it already-resolved definitions.
     mockLiveConversation = {
       isProcessing: () => false,
       getCurrentSystemPrompt: () => "You are a helpful assistant.",
-      getRegisteredToolNames: () =>
-        new Set(["web_search", "file_read", "notify_parent"]),
-    };
-    mockToolDescriptions = {
-      web_search: "Search the web",
-      file_read: "Read a file",
-      // notify_parent intentionally not in the map — description should be ""
+      getRegisteredToolDefinitions: () => [
+        { name: "file_read", description: "Read a file", input_schema: {} },
+        { name: "notify_parent", description: "", input_schema: {} },
+        { name: "web_search", description: "Search the web", input_schema: {} },
+      ],
     };
 
     const trace = assembleTurnTrace(boundary(conv.id, "m-user-1", 1000));

package/src/telemetry/turn-trace-store.ts

@@ -3,7 +3,6 @@ import { and, asc, eq, gt, lt, lte, or, sql } from "drizzle-orm";
 import { findConversation } from "../daemon/conversation-registry.js";
 import { getDb } from "../persistence/db-connection.js";
 import { messages, toolInvocations } from "../persistence/schema/index.js";
-import { getTool } from "../tools/registry.js";
 import { getLogger } from "../util/logger.js";
 import type {
   TurnTrace,
@@ -315,16 +314,11 @@ export function assembleTurnTrace(boundary: TurnTraceBoundary): TurnTrace {
   const systemPrompt = conversation?.getCurrentSystemPrompt() ?? null;
 
   const toolDefinitions: TurnTraceToolDefinition[] = conversation
-    ? Array.from(conversation.getRegisteredToolNames())
-        .sort((a, b) => a.localeCompare(b))
-        .map((name) => {
-          const tool = getTool(name);
-          return {
-            name,
-            description: tool?.description ?? "",
-            input_schema: (tool?.input_schema ?? {}) as Record<string, unknown>,
-          };
-        })
+    ? conversation.getRegisteredToolDefinitions().map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        input_schema: tool.input_schema as Record<string, unknown>,
+      }))
     : [];
 
   return {