@vellumai/assistant 0.8.10 → 0.8.11-staging.1

package/src/cli/commands/schedules.ts

@@ -23,6 +23,7 @@ interface ScheduleRecord {
   maxRetries: number;
   retryBackoffMs: number;
   description: string | null;
+  cadenceDescription: string | null;
   mode: string;
   status: string;
   routingIntent: string;
@@ -64,9 +65,9 @@ export function registerSchedulesCommand(program: Command): void {
 Schedules are recurring or one-shot jobs run by the assistant.
 
 This CLI namespace is intentionally landing incrementally. Today it supports
-listing schedules, viewing recent run history, enabling/disabling schedules,
-manually executing a schedule one time, and cancelling pending one-shot schedules;
-create, delete, and run inspection will follow as separate slices.
+creating schedules, listing schedules, viewing recent run history,
+enabling/disabling schedules, manually executing a schedule one time, cancelling
+pending one-shot schedules, and deleting schedules.
 
 Examples:
   $ assistant schedules list
@@ -318,6 +319,10 @@ Examples:
           "-e, --expression <expr>",
           "Cron or RRULE expression that schedules the fire times",
         )
+        .requiredOption(
+          "-d, --description <text>",
+          "Authored description explaining what the schedule is for",
+        )
         .requiredOption(
           "-m, --message <text>",
           "Message body sent to the assistant on each fire",
@@ -333,6 +338,7 @@ Examples:
           `
 Options:
   -e, --expression <expr>   Cron (e.g. '*/30 * * * *') or RRULE expression.
+  -d, --description <text>  Authored description explaining what the schedule is for.
   -m, --message <text>      Message body sent on each fire.
   -t, --timezone <tz>       IANA timezone applied to the expression.
   --no-enabled              Create the schedule disabled. Defaults to enabled.
@@ -349,13 +355,16 @@ Behavior:
 Examples:
   $ assistant schedules create "Heartbeat" \\
       --expression '*/30 * * * *' \\
+      --description 'Checks service heartbeat every 30 minutes' \\
       --message 'run heartbeat'
   $ assistant schedules create "Morning summary" \\
       --expression '0 9 * * MON-FRI' \\
+      --description 'Summarizes weekday activity' \\
       --timezone America/New_York \\
       --message 'write the morning summary'
   $ assistant schedules create "Drafted" \\
       --expression '0 0 * * *' \\
+      --description 'Placeholder daily schedule' \\
       --message 'placeholder' \\
       --no-enabled --json`,
         )
@@ -364,6 +373,7 @@ Examples:
             name: string,
             opts: {
               expression: string;
+              description: string;
               message: string;
               timezone?: string;
               enabled: boolean;
@@ -383,9 +393,22 @@ Examples:
               return;
             }
 
+            const description = opts.description.trim();
+            if (!description) {
+              const error = "description is required";
+              if (opts.json) {
+                writeOutput(cmd, { ok: false, error });
+              } else {
+                log.error(error);
+              }
+              process.exitCode = 1;
+              return;
+            }
+
             const body: Record<string, unknown> = {
               name: scheduleName,
               expression: opts.expression,
+              description,
               message: opts.message,
               enabled: opts.enabled,
             };
@@ -662,7 +685,7 @@ async function toggleScheduleEnabled(
 
 function describeSchedule(schedule: ScheduleRecord): string {
   if (schedule.isOneShot) return "one-shot";
-  const expression = schedule.description ?? schedule.expression ?? "—";
+  const expression = schedule.cadenceDescription ?? schedule.expression ?? "—";
   return schedule.timezone
     ? `${expression} (${schedule.timezone})`
     : expression;

package/src/cli/commands/skills.ts

@@ -97,6 +97,7 @@ Examples:
               origin: string;
               kind: string;
               status: string;
+              owner?: { kind: string; id: string };
             }>;
           }>("listSkills", { queryParams: {} });
           if (!r.ok)
@@ -104,16 +105,27 @@ Examples:
               { ok: false, error: r.error, statusCode: r.statusCode },
               opts.json ?? false,
             );
+          // Source labels the extension a skill ships from. Plugin-resident
+          // skills are intentionally mapped to kind:bundled/origin:vellum for
+          // older clients, so their real attribution lives on `owner` —
+          // surface it as `plugin:<id>` instead of collapsing to "bundled".
+          const sourceLabel = (s: {
+            origin: string;
+            kind: string;
+            owner?: { kind: string; id: string };
+          }): string => {
+            if (s.owner) return `${s.owner.kind}:${s.owner.id}`;
+            if (s.origin === "vellum" && s.kind === "bundled") return "bundled";
+            return s.origin;
+          };
           const allSkills = r
             .result!.skills.map((s) => ({
               id: s.id,
               name: s.name,
               description: s.description,
               emoji: s.emoji,
-              source:
-                s.origin === "vellum" && s.kind === "bundled"
-                  ? "bundled"
-                  : s.origin,
+              source: sourceLabel(s),
+              owner: s.owner,
               state: s.status,
             }))
             .sort((a, b) => a.id.localeCompare(b.id));
@@ -125,12 +137,22 @@ Examples:
             log.info("No skills available.");
             return;
           }
+          // Align ID / SOURCE / STATE into columns so source is scannable.
+          const idWidth = Math.max(2, ...allSkills.map((s) => s.id.length));
+          const srcWidth = Math.max(
+            6,
+            ...allSkills.map((s) => s.source.length),
+          );
           log.info(`Skills (${allSkills.length}):\n`);
+          log.info(
+            `  ${"ID".padEnd(idWidth)}  ${"SOURCE".padEnd(srcWidth)}  STATE`,
+          );
           for (const s of allSkills) {
             const emoji = s.emoji ? `${s.emoji} ` : "";
-            const tags = [s.source, ...(s.state === "disabled" ? ["disabled"] : [])];
-            log.info(`  ${emoji}${s.id} [${tags.join(", ")}]`);
-            log.info(`    ${s.name} — ${s.description}`);
+            log.info(
+              `  ${s.id.padEnd(idWidth)}  ${s.source.padEnd(srcWidth)}  ${s.state}`,
+            );
+            log.info(`    ${emoji}${s.name} — ${s.description}`);
           }
         });
 
@@ -193,7 +215,8 @@ Examples:
           log.info(`  Source:    ${detail.source}`);
           log.info(`  State:     ${detail.state}`);
           log.info(`  Path:      ${detail.directoryPath}`);
-          if (detail.featureFlag) log.info(`  Flag:      ${detail.featureFlag}`);
+          if (detail.featureFlag)
+            log.info(`  Flag:      ${detail.featureFlag}`);
           if (detail.includes?.length)
             log.info(`  Includes:  ${detail.includes.join(", ")}`);
           if (detail.activationHints?.length)
@@ -228,7 +251,9 @@ Examples:
           }
           if (detail.config) {
             log.info(`\n  Config:`);
-            log.info(`    Enabled:     ${detail.config.enabled ? "yes" : "no"}`);
+            log.info(
+              `    Enabled:     ${detail.config.enabled ? "yes" : "no"}`,
+            );
             if (detail.config.envKeys.length)
               log.info(`    Env vars:    ${detail.config.envKeys.join(", ")}`);
             if (detail.config.configKeys.length)
@@ -262,147 +287,157 @@ Examples:
   $ assistant skills search "file management" --limit 3
   $ assistant skills search deploy --json`,
         )
-        .action(async (query: string, opts: { limit: string; json?: boolean }) => {
-          const json = opts.json ?? false;
-          const limit = parseInt(opts.limit, 10) || 10;
-
-          // Step 1: Vellum catalog (installed + remote available)
-          const catalogR = await cliIpcCall<{
-            skills: Array<{
-              id: string;
-              name: string;
-              description: string;
-              emoji?: string;
-              origin: string;
-              kind: string;
-              status: string;
-              updatedAt?: string;
-            }>;
-          }>("listSkills", { queryParams: { include: "catalog", q: query } });
-          const vellumSkills = catalogR.ok
-            ? catalogR.result!.skills.filter((s) => s.origin === "vellum")
-            : [];
+        .action(
+          async (query: string, opts: { limit: string; json?: boolean }) => {
+            const json = opts.json ?? false;
+            const limit = parseInt(opts.limit, 10) || 10;
+
+            // Step 1: Vellum catalog (installed + remote available)
+            const catalogR = await cliIpcCall<{
+              skills: Array<{
+                id: string;
+                name: string;
+                description: string;
+                emoji?: string;
+                origin: string;
+                kind: string;
+                status: string;
+                updatedAt?: string;
+              }>;
+            }>("listSkills", { queryParams: { include: "catalog", q: query } });
+            const vellumSkills = catalogR.ok
+              ? catalogR.result!.skills.filter((s) => s.origin === "vellum")
+              : [];
+
+            // Step 2: community (skills.sh with audits + clawhub) + local bundled/installed
+            const communityR = await cliIpcCall<{
+              skills: Array<{
+                id: string;
+                name: string;
+                description: string;
+                emoji?: string;
+                origin: string;
+                kind: string;
+                status: string;
+                slug?: string;
+                author?: string;
+                stars?: number;
+                installs?: number;
+                publishedAt?: string;
+                version?: string;
+                sourceRepo?: string;
+              }>;
+            }>("searchSkills", {
+              queryParams: { q: query, limit: String(limit) },
+            });
+            const communitySkills = communityR.ok
+              ? communityR.result!.skills.filter((s) => s.origin !== "vellum")
+              : [];
+
+            // Deduplicate by id — vellum wins
+            const seen = new Set(vellumSkills.map((s) => s.id));
+            const dedupedCommunity = communitySkills.filter((s) => {
+              if (seen.has(s.id)) return false;
+              seen.add(s.id);
+              return true;
+            });
+            const clawhubResults = dedupedCommunity
+              .filter((s) => s.origin === "clawhub")
+              .slice(0, limit);
+            const skillsshResults = dedupedCommunity
+              .filter((s) => s.origin === "skillssh")
+              .slice(0, limit);
+
+            const hasResults =
+              vellumSkills.length > 0 ||
+              clawhubResults.length > 0 ||
+              skillsshResults.length > 0;
 
-          // Step 2: community (skills.sh with audits + clawhub) + local bundled/installed
-          const communityR = await cliIpcCall<{
-            skills: Array<{
-              id: string;
-              name: string;
-              description: string;
-              emoji?: string;
-              origin: string;
-              kind: string;
-              status: string;
-              slug?: string;
-              author?: string;
-              stars?: number;
-              installs?: number;
-              publishedAt?: string;
-              version?: string;
-              sourceRepo?: string;
-            }>;
-          }>("searchSkills", { queryParams: { q: query, limit: String(limit) } });
-          const communitySkills = communityR.ok
-            ? communityR.result!.skills.filter((s) => s.origin !== "vellum")
-            : [];
-
-          // Deduplicate by id — vellum wins
-          const seen = new Set(vellumSkills.map((s) => s.id));
-          const dedupedCommunity = communitySkills.filter((s) => {
-            if (seen.has(s.id)) return false;
-            seen.add(s.id);
-            return true;
-          });
-          const clawhubResults = dedupedCommunity
-            .filter((s) => s.origin === "clawhub")
-            .slice(0, limit);
-          const skillsshResults = dedupedCommunity
-            .filter((s) => s.origin === "skillssh")
-            .slice(0, limit);
-
-          const hasResults =
-            vellumSkills.length > 0 ||
-            clawhubResults.length > 0 ||
-            skillsshResults.length > 0;
-
-          if (json) {
-            console.log(
-              JSON.stringify({
-                ok: true,
-                catalog: vellumSkills,
-                community: skillsshResults,
-                clawhub: clawhubResults,
-                ...(catalogR.ok ? {} : { catalogError: catalogR.error }),
-                ...(communityR.ok ? {} : { communityError: communityR.error }),
-              }),
-            );
-            return;
-          }
+            if (json) {
+              console.log(
+                JSON.stringify({
+                  ok: true,
+                  catalog: vellumSkills,
+                  community: skillsshResults,
+                  clawhub: clawhubResults,
+                  ...(catalogR.ok ? {} : { catalogError: catalogR.error }),
+                  ...(communityR.ok
+                    ? {}
+                    : { communityError: communityR.error }),
+                }),
+              );
+              return;
+            }
 
-          if (!hasResults) {
-            log.info(`No skills found for "${query}".`);
-            if (!catalogR.ok)
-              log.warn(`(Vellum catalog unavailable: ${catalogR.error})`);
-            if (!communityR.ok)
-              log.warn(`(Community registry unavailable: ${communityR.error})`);
-            return;
-          }
+            if (!hasResults) {
+              log.info(`No skills found for "${query}".`);
+              if (!catalogR.ok)
+                log.warn(`(Vellum catalog unavailable: ${catalogR.error})`);
+              if (!communityR.ok)
+                log.warn(
+                  `(Community registry unavailable: ${communityR.error})`,
+                );
+              return;
+            }
 
-          if (vellumSkills.length > 0) {
-            log.info(`Vellum catalog (${vellumSkills.length}):\n`);
-            for (const s of vellumSkills) {
-              const emoji = s.emoji ? `${s.emoji} ` : "";
-              const badge = s.kind === "installed" ? " [installed]" : "";
-              log.info(`  ${emoji}${s.name}${badge}`);
-              if (s.name !== s.id) log.info(`    ID: ${s.id}`);
-              log.info(`    ${s.description}`);
-              if (s.updatedAt) log.info(`    Updated: ${s.updatedAt}`);
-              if (s.kind !== "installed")
-                log.info(`    Install: assistant skills install ${s.id}`);
-              log.info("");
+            if (vellumSkills.length > 0) {
+              log.info(`Vellum catalog (${vellumSkills.length}):\n`);
+              for (const s of vellumSkills) {
+                const emoji = s.emoji ? `${s.emoji} ` : "";
+                const badge = s.kind === "installed" ? " [installed]" : "";
+                log.info(`  ${emoji}${s.name}${badge}`);
+                if (s.name !== s.id) log.info(`    ID: ${s.id}`);
+                log.info(`    ${s.description}`);
+                if (s.updatedAt) log.info(`    Updated: ${s.updatedAt}`);
+                if (s.kind !== "installed")
+                  log.info(`    Install: assistant skills install ${s.id}`);
+                log.info("");
+              }
             }
-          }
 
-          if (skillsshResults.length > 0) {
-            log.info(`Community — skills.sh (${skillsshResults.length}):\n`);
-            for (const r of skillsshResults) {
-              const badge = r.kind === "installed" ? " [installed]" : "";
-              log.info(`  ${r.name}${badge}`);
-              if (r.name !== r.id) log.info(`    ID: ${r.id}`);
-              if (r.sourceRepo) log.info(`    Source: ${r.sourceRepo}`);
-              if (r.installs !== undefined)
-                log.info(`    Installs: ${r.installs}`);
-              if (r.kind !== "installed")
-                // Use the fully-qualified 3-segment id (owner/repo/skill) — this
-                // matches the `owner/repo/skill-name` form accepted by
-                // `resolveSkillSource()`. Building `sourceRepo@slug` fails for
-                // skills.sh because the registry returns `slug` as the full id,
-                // producing `owner/repo@owner/repo/skill` which the parser rejects.
-                log.info(`    Install: assistant skills add ${r.id}`);
-              log.info("");
+            if (skillsshResults.length > 0) {
+              log.info(`Community — skills.sh (${skillsshResults.length}):\n`);
+              for (const r of skillsshResults) {
+                const badge = r.kind === "installed" ? " [installed]" : "";
+                log.info(`  ${r.name}${badge}`);
+                if (r.name !== r.id) log.info(`    ID: ${r.id}`);
+                if (r.sourceRepo) log.info(`    Source: ${r.sourceRepo}`);
+                if (r.installs !== undefined)
+                  log.info(`    Installs: ${r.installs}`);
+                if (r.kind !== "installed")
+                  // Use the fully-qualified 3-segment id (owner/repo/skill) — this
+                  // matches the `owner/repo/skill-name` form accepted by
+                  // `resolveSkillSource()`. Building `sourceRepo@slug` fails for
+                  // skills.sh because the registry returns `slug` as the full id,
+                  // producing `owner/repo@owner/repo/skill` which the parser rejects.
+                  log.info(`    Install: assistant skills add ${r.id}`);
+                log.info("");
+              }
+            } else if (!communityR.ok) {
+              log.warn(
+                `\n(skills.sh registry unavailable: ${communityR.error})`,
+              );
             }
-          } else if (!communityR.ok) {
-            log.warn(
-              `\n(skills.sh registry unavailable: ${communityR.error})`,
-            );
-          }
 
-          if (clawhubResults.length > 0) {
-            log.info(`Community — Clawhub (${clawhubResults.length}):\n`);
-            for (const r of clawhubResults) {
-              const badge = r.kind === "installed" ? " [installed]" : "";
-              log.info(`  ${r.name}${badge}`);
-              if (r.name !== r.id) log.info(`    ID: ${r.id}`);
-              if (r.author) log.info(`    Author: ${r.author}`);
-              if (r.description) log.info(`    ${r.description}`);
-              if (r.stars) log.info(`    Stars: ${r.stars}`);
-              if (r.installs) log.info(`    Installs: ${r.installs}`);
-              if (r.kind !== "installed")
-                log.info(`    Install: npx clawhub install ${r.slug ?? r.id}`);
-              log.info("");
+            if (clawhubResults.length > 0) {
+              log.info(`Community — Clawhub (${clawhubResults.length}):\n`);
+              for (const r of clawhubResults) {
+                const badge = r.kind === "installed" ? " [installed]" : "";
+                log.info(`  ${r.name}${badge}`);
+                if (r.name !== r.id) log.info(`    ID: ${r.id}`);
+                if (r.author) log.info(`    Author: ${r.author}`);
+                if (r.description) log.info(`    ${r.description}`);
+                if (r.stars) log.info(`    Stars: ${r.stars}`);
+                if (r.installs) log.info(`    Installs: ${r.installs}`);
+                if (r.kind !== "installed")
+                  log.info(
+                    `    Install: npx clawhub install ${r.slug ?? r.id}`,
+                  );
+                log.info("");
+              }
             }
-          }
-        });
+          },
+        );
 
       skills
         .command("install <skill-id>")
@@ -433,10 +468,16 @@ Examples:
             const json = opts.json ?? false;
 
             // Restrict to catalog-only; community installs use `skills add`.
-            const installR = await cliIpcCall<{ ok: boolean; skillId?: string }>(
-              "installSkill",
-              { body: { slug: skillId, overwrite: opts.overwrite ?? false, catalogOnly: true } },
-            );
+            const installR = await cliIpcCall<{
+              ok: boolean;
+              skillId?: string;
+            }>("installSkill", {
+              body: {
+                slug: skillId,
+                overwrite: opts.overwrite ?? false,
+                catalogOnly: true,
+              },
+            });
             if (!installR.ok) {
               if (json) {
                 console.log(

package/src/cli/commands/tools.ts

@@ -0,0 +1,106 @@
+/**
+ * `assistant tools` — inspect the tools registered with the running
+ * assistant (core built-ins plus skill-, plugin-, and MCP-contributed
+ * tools).
+ *
+ * Thin `ipc` wrapper: each subcommand forwards to a single daemon route and
+ * renders the response. The registry lives in the daemon, so these commands
+ * require the daemon to be running.
+ */
+
+import type { Command } from "commander";
+
+import { cliIpcCall, exitFromIpcResult } from "../../ipc/cli-client.js";
+import { registerCommand } from "../lib/register-command.js";
+
+interface ToolListEntry {
+  name: string;
+  description: string;
+  riskLevel: string;
+  category: string;
+  source: string;
+}
+
+interface ToolsGetResponse {
+  names: string[];
+  schemas: Record<string, unknown>;
+  tools: ToolListEntry[];
+}
+
+export function registerToolsCommand(program: Command): void {
+  registerCommand(program, {
+    name: "tools",
+    transport: "ipc",
+    description: "Inspect tools registered with the running assistant",
+    build: (tools) => {
+      tools.addHelpText(
+        "after",
+        `
+Tools are registered with the daemon from four sources: core built-ins,
+skills, external plugins, and MCP servers. The "source" column reports the
+origin as "core" or "<kind>:<id>" (e.g. "plugin:echo", "skill:my-skill",
+"mcp:linear"). The risk level is the author-asserted default band used for
+permission gating, not the runtime-classified risk of a specific call.
+
+By default the global registry is listed. Pass --conversation to scope the
+list to the tools available to one conversation as of its most recent turn —
+including skill/MCP tools it registered over its lifecycle.
+
+Examples:
+  $ assistant tools list
+  $ assistant tools ls
+  $ assistant tools list --json
+  $ assistant tools list --conversation conv_abc123`,
+      );
+
+      tools
+        .command("list")
+        .alias("ls")
+        .description(
+          "List all registered tools with their source and risk level",
+        )
+        .option("--json", "Emit machine-readable JSON instead of a table")
+        .option(
+          "--conversation <id>",
+          "Scope to one conversation's tools as of its most recent turn — run 'assistant conversations list' to find the id",
+        )
+        .action(async (opts: { json?: boolean; conversation?: string }) => {
+          const response = await cliIpcCall<ToolsGetResponse>(
+            "tools_get",
+            opts.conversation
+              ? { queryParams: { conversationId: opts.conversation } }
+              : undefined,
+          );
+          if (!response.ok) {
+            return exitFromIpcResult(response);
+          }
+
+          const tools = response.result?.tools ?? [];
+
+          if (opts.json) {
+            console.log(JSON.stringify(tools, null, 2));
+            return;
+          }
+
+          if (tools.length === 0) {
+            console.log("No tools registered.");
+            return;
+          }
+
+          const nameW = Math.max(4, ...tools.map((t) => t.name.length));
+          const sourceW = Math.max(6, ...tools.map((t) => t.source.length));
+          const riskW = Math.max(4, ...tools.map((t) => t.riskLevel.length));
+
+          console.log(
+            `${"NAME".padEnd(nameW)}  ${"SOURCE".padEnd(sourceW)}  ${"RISK".padEnd(riskW)}  DESCRIPTION`,
+          );
+          for (const t of tools) {
+            console.log(
+              `${t.name.padEnd(nameW)}  ${t.source.padEnd(sourceW)}  ${t.riskLevel.padEnd(riskW)}  ${t.description}`,
+            );
+          }
+          console.log(`\n${tools.length} tool(s)`);
+        });
+    },
+  });
+}