@vellumai/assistant 0.5.10 → 0.5.12

package/src/cli/commands/platform/index.ts

@@ -0,0 +1,252 @@
+import type { Command } from "commander";
+
+import {
+  registerCallbackRoute,
+  resolvePlatformCallbackRegistrationContext,
+} from "../../../inbound/platform-callback-registration.js";
+import { credentialKey } from "../../../security/credential-key.js";
+import { getSecureKeyViaDaemon } from "../../lib/daemon-credential-client.js";
+import { log } from "../../logger.js";
+import { shouldOutputJson, writeOutput } from "../../output.js";
+import { CREDENTIAL_KEYS, registerPlatformConnectCommand } from "./connect.js";
+import { registerPlatformDisconnectCommand } from "./disconnect.js";
+
+export function registerPlatformCommand(program: Command): void {
+  const platform = program
+    .command("platform")
+    .description("Manage platform integration for containerized deployments")
+    .option("--json", "Machine-readable compact JSON output");
+
+  platform.addHelpText(
+    "after",
+    `
+The platform subsystem manages the connection to Vellum Platform, callback
+routing, containerized deployment context, and webhook forwarding for
+assistants. Use 'connect', 'status', and 'disconnect' to manage platform
+credentials. When IS_CONTAINERIZED=true with a configured VELLUM_PLATFORM_URL
+and PLATFORM_ASSISTANT_ID, external service callbacks (Telegram webhooks,
+Twilio webhooks, OAuth redirects) route through the platform's gateway proxy
+instead of hitting the assistant directly.
+
+Examples:
+  $ assistant platform status --json
+  $ assistant platform connect
+  $ assistant platform disconnect
+  $ assistant platform callback-routes register --path webhooks/telegram --type telegram --json`,
+  );
+
+  // ---------------------------------------------------------------------------
+  // connect — store platform credentials and validate the connection
+  // ---------------------------------------------------------------------------
+
+  registerPlatformConnectCommand(platform);
+
+  // ---------------------------------------------------------------------------
+  // status — deployment context and connection status combined
+  // ---------------------------------------------------------------------------
+
+  platform
+    .command("status")
+    .description(
+      "Show current platform deployment context and connection status",
+    )
+    .addHelpText(
+      "after",
+      `
+Reads platform-related environment variables and stored credentials to report
+the current containerized deployment context and connection state. Does not
+require the assistant to be running.
+
+Fields:
+  containerized       Whether IS_CONTAINERIZED is set (boolean)
+  baseUrl             VELLUM_PLATFORM_URL — the platform gateway base URL
+  assistantId         PLATFORM_ASSISTANT_ID — this assistant's platform UUID
+  hasInternalApiKey   Whether PLATFORM_INTERNAL_API_KEY is set (boolean,
+                      value not disclosed)
+  hasAssistantApiKey  Whether a stored assistant API key is available
+  available           Whether callback registration prerequisites are satisfied
+  connected           Whether platform credentials are stored (boolean)
+  organizationId      The platform organization ID (from stored credentials)
+  userId              The platform user ID (from stored credentials)
+
+Examples:
+  $ assistant platform status
+  $ assistant platform status --json`,
+    )
+    .action(async (_opts: Record<string, unknown>, cmd: Command) => {
+      try {
+        const context = await resolvePlatformCallbackRegistrationContext();
+
+        const storedBaseUrl =
+          (await getSecureKeyViaDaemon(
+            credentialKey(
+              CREDENTIAL_KEYS.baseUrl.service,
+              CREDENTIAL_KEYS.baseUrl.field,
+            ),
+          )) ?? "";
+        const hasStoredApiKey = !!(await getSecureKeyViaDaemon(
+          credentialKey(
+            CREDENTIAL_KEYS.apiKey.service,
+            CREDENTIAL_KEYS.apiKey.field,
+          ),
+        ));
+        const organizationId =
+          (
+            await getSecureKeyViaDaemon(
+              credentialKey(
+                CREDENTIAL_KEYS.organizationId.service,
+                CREDENTIAL_KEYS.organizationId.field,
+              ),
+            )
+          )?.trim() ?? "";
+        const userId =
+          (
+            await getSecureKeyViaDaemon(
+              credentialKey(
+                CREDENTIAL_KEYS.userId.service,
+                CREDENTIAL_KEYS.userId.field,
+              ),
+            )
+          )?.trim() ?? "";
+
+        const connected = !!storedBaseUrl && hasStoredApiKey;
+
+        const result = {
+          containerized: context.containerized,
+          baseUrl: context.platformBaseUrl,
+          assistantId: context.assistantId,
+          hasInternalApiKey: context.hasInternalApiKey,
+          hasAssistantApiKey: context.hasAssistantApiKey,
+          available: context.enabled,
+          connected,
+          organizationId: organizationId || null,
+          userId: userId || null,
+        };
+
+        writeOutput(cmd, result);
+
+        if (!shouldOutputJson(cmd)) {
+          log.info(`Containerized: ${result.containerized}`);
+          log.info(`Base URL: ${result.baseUrl || "(not set)"}`);
+          log.info(`Assistant ID: ${result.assistantId || "(not set)"}`);
+          log.info(
+            `Internal API key: ${result.hasInternalApiKey ? "set" : "not set"}`,
+          );
+          log.info(
+            `Assistant API key: ${result.hasAssistantApiKey ? "set" : "not set"}`,
+          );
+          log.info(
+            `Callback registration available: ${result.available ? "yes" : "no"}`,
+          );
+          log.info(`Connected: ${connected}`);
+          log.info(`Organization ID: ${organizationId || "(not set)"}`);
+          log.info(`User ID: ${userId || "(not set)"}`);
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+
+  // ---------------------------------------------------------------------------
+  // disconnect — remove stored platform credentials
+  // ---------------------------------------------------------------------------
+
+  registerPlatformDisconnectCommand(platform);
+
+  // ---------------------------------------------------------------------------
+  // callback-routes
+  // ---------------------------------------------------------------------------
+
+  const callbackRoutes = platform
+    .command("callback-routes")
+    .description("Manage platform callback route registrations");
+
+  callbackRoutes.addHelpText(
+    "after",
+    `
+Callback routes tell the platform gateway how to forward inbound provider
+webhooks to the correct containerized assistant instance. Each route maps a
+callback path and type to a stable external URL that external services
+(Telegram, Twilio, OAuth providers) should use.
+
+Examples:
+  $ assistant platform callback-routes register --path webhooks/telegram --type telegram --json
+  $ assistant platform callback-routes register --path webhooks/twilio/voice --type twilio_voice --json`,
+  );
+
+  // ---------------------------------------------------------------------------
+  // callback-routes register
+  // ---------------------------------------------------------------------------
+
+  callbackRoutes
+    .command("register")
+    .description("Register a callback route with the platform gateway")
+    .requiredOption(
+      "--path <path>",
+      "Callback path (e.g. webhooks/telegram, webhooks/twilio/voice)",
+    )
+    .requiredOption(
+      "--type <type>",
+      "Route type identifier (e.g. telegram, twilio_voice, twilio_status, oauth)",
+    )
+    .addHelpText(
+      "after",
+      `
+Registers a callback route with the platform's internal gateway endpoint so
+the platform knows how to forward inbound provider webhooks to this
+containerized assistant instance.
+
+Arguments:
+  --path    The path portion after the ingress base URL. Leading/trailing
+            slashes are stripped by the platform.
+  --type    The route type identifier used by the platform to classify and
+            route the callback.
+
+Known callback path/type combinations:
+  --path webhooks/telegram          --type telegram
+  --path webhooks/twilio/voice      --type twilio_voice
+  --path webhooks/twilio/status     --type twilio_status
+  --path oauth/callback             --type oauth
+
+Requires a containerized environment (IS_CONTAINERIZED=true) with
+VELLUM_PLATFORM_URL and PLATFORM_ASSISTANT_ID configured. Returns the
+platform-provided stable callback URL that external services should use.
+
+Examples:
+  $ assistant platform callback-routes register --path webhooks/telegram --type telegram --json
+  $ assistant platform callback-routes register --path webhooks/twilio/voice --type twilio_voice --json`,
+    )
+    .action(async (opts: { path: string; type: string }, cmd: Command) => {
+      try {
+        const context = await resolvePlatformCallbackRegistrationContext();
+        if (!context.enabled) {
+          writeOutput(cmd, {
+            ok: false,
+            error:
+              "Platform callbacks not available — missing containerized platform registration context",
+          });
+          process.exitCode = 1;
+          return;
+        }
+
+        const callbackUrl = await registerCallbackRoute(opts.path, opts.type);
+
+        writeOutput(cmd, {
+          ok: true,
+          callbackUrl,
+          callbackPath: opts.path,
+          type: opts.type,
+        });
+
+        if (!shouldOutputJson(cmd)) {
+          log.info(`Callback route registered: ${callbackUrl}`);
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(cmd, { ok: false, error: message });
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli/commands/sequence.ts

@@ -142,7 +142,7 @@ Examples:
       "after",
       `
 Arguments:
-  id   The sequence ID (e.g. seq_abc123)
+  id   The sequence ID (e.g. seq_abc123). Run 'assistant sequence list' to find IDs.
 
 Returns full sequence details: name, status, channel, description, exit-on-reply
 setting, all steps with delay and approval configuration, and enrollment
@@ -215,7 +215,7 @@ Examples:
       "after",
       `
 Arguments:
-  id   The sequence ID to pause (e.g. seq_abc123)
+  id   The sequence ID to pause (e.g. seq_abc123). Run 'assistant sequence list' to find IDs.
 
 Pauses a sequence, halting all scheduled step deliveries. Existing active
 enrollments remain in their current state but no new steps will be sent
@@ -246,7 +246,7 @@ Examples:
       "after",
       `
 Arguments:
-  id   The sequence ID to resume (e.g. seq_abc123)
+  id   The sequence ID to resume (e.g. seq_abc123). Run 'assistant sequence list' to find IDs.
 
 Resumes a paused sequence, re-enabling scheduled step deliveries for all
 active enrollments. No-op if the sequence is already active.
@@ -276,7 +276,8 @@ Examples:
       "after",
       `
 Arguments:
-  enrollmentId   The enrollment ID to cancel (e.g. enr_xyz789)
+  enrollmentId   The enrollment ID to cancel (e.g. enr_xyz789). Run 'assistant sequence get <id>'
+                 to see enrollment IDs for a sequence.
 
 Immediately cancels a specific enrollment, stopping all future step
 deliveries for that contact in this sequence. The enrollment status

package/src/cli/commands/shotgun.ts

@@ -101,6 +101,19 @@ export function registerShotgunCommand(program: Command): void {
     .command("shotgun")
     .description("Start and monitor screen-watch (shotgun) sessions via IPC");
 
+  shotgun.addHelpText(
+    "after",
+    `
+Screen-watch sessions capture periodic screenshots and feed them to the
+assistant for observation. The CLI communicates with the running assistant
+via IPC signal files — the assistant must be running for these commands
+to work.
+
+Examples:
+  $ assistant shotgun start --duration 600 --focus "browsing workflow"
+  $ assistant shotgun status <watchId>`,
+  );
+
   shotgun
     .command("start")
     .description("Start a new screen-watch session")
@@ -206,6 +219,9 @@ Examples:
     .addHelpText(
       "after",
       `
+Arguments:
+  watchId   The watch session ID returned by 'assistant shotgun start'.
+
 Queries the status of an existing screen-watch session by watchId.
 
 Output (JSON): { ok, watchId, conversationId, status }

package/src/cli/commands/skills.ts

@@ -1,3 +1,6 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
 import type { Command } from "commander";
 
 import type { CatalogSkill } from "../../skills/catalog-install.js";
@@ -8,7 +11,11 @@ import {
   readLocalCatalog,
   uninstallSkillLocally,
 } from "../../skills/catalog-install.js";
-import type { AuditResponse } from "../../skills/skillssh-registry.js";
+import { filterByQuery } from "../../skills/catalog-search.js";
+import type {
+  AuditResponse,
+  SkillsShSearchResult,
+} from "../../skills/skillssh-registry.js";
 import {
   fetchSkillAudits,
   formatAuditBadges,
@@ -16,6 +23,7 @@ import {
   resolveSkillSource,
   searchSkillsRegistry,
 } from "../../skills/skillssh-registry.js";
+import { getWorkspaceSkillsDir } from "../../util/platform.js";
 import { log } from "../logger.js";
 
 // ---------------------------------------------------------------------------
@@ -49,6 +57,16 @@ Examples:
     .command("list")
     .description("List available catalog skills")
     .option("--json", "Machine-readable JSON output")
+    .addHelpText(
+      "after",
+      `
+Lists all skills available in the Vellum catalog with their ID, name,
+description, and dependency information.
+
+Examples:
+  $ assistant skills list
+  $ assistant skills list --json`,
+    )
     .action(async (opts: { json?: boolean }) => {
       try {
         // In dev mode, use the local catalog as the source of truth
@@ -93,20 +111,20 @@ Examples:
 
   skills
     .command("search <query>")
-    .description("Search the skills.sh community registry")
-    .option("--limit <n>", "Maximum number of results", "10")
+    .description("Search the Vellum catalog and skills.sh community registry")
+    .option("--limit <n>", "Maximum number of community results", "10")
     .option("--json", "Machine-readable JSON output")
     .addHelpText(
       "after",
       `
 Arguments:
   query    Free-text search term matched against skill names, descriptions,
-           and tags in the skills.sh registry.
+           and tags. Searches the Vellum catalog first, then the skills.sh
+           community registry.
 
-Searches the skills.sh community registry and displays matching skills
-with install counts and security audit badges (ATH, Socket, Snyk).
-Audit fetch failures are non-fatal — results are still shown without
-security data.
+Displays results from both sources with clear labels. When a skill ID
+exists in both the Vellum catalog and the community registry, a conflict
+note is shown with guidance on which install command to use.
 
 Examples:
   $ assistant skills search react
@@ -118,36 +136,80 @@ Examples:
       const limit = parseInt(opts.limit, 10) || 10;
 
       try {
-        const results = await searchSkillsRegistry(query, limit);
+        // ── Vellum catalog search ────────────────────────────────────
+        const repoSkillsDir = getRepoSkillsDir();
+        let catalog: CatalogSkill[];
+        if (repoSkillsDir) {
+          catalog = readLocalCatalog(repoSkillsDir);
+        } else {
+          try {
+            catalog = await fetchCatalog();
+          } catch {
+            catalog = [];
+          }
+        }
+
+        const catalogMatches = filterByQuery(catalog, query, [
+          (s) => s.id,
+          (s) => s.name,
+          (s) => s.description,
+        ]);
+
+        // ── Community registry search (non-fatal on failure) ─────────
+        let registryResults: SkillsShSearchResult[] = [];
+        let registryError: string | undefined;
+        try {
+          registryResults = await searchSkillsRegistry(query, limit);
+        } catch (err) {
+          registryError = err instanceof Error ? err.message : String(err);
+        }
+
+        // ── Conflict detection ───────────────────────────────────────
+        const catalogIds = new Set(catalogMatches.map((s) => s.id));
+        const conflictIds = new Set(
+          registryResults
+            .filter((r) => catalogIds.has(r.skillId))
+            .map((r) => r.skillId),
+        );
 
-        if (results.length === 0) {
+        if (catalogMatches.length === 0 && registryResults.length === 0) {
           if (json) {
-            console.log(JSON.stringify({ ok: true, results: [], audits: {} }));
+            console.log(
+              JSON.stringify({
+                ok: true,
+                catalog: [],
+                community: [],
+                audits: {},
+                ...(registryError ? { registryError } : {}),
+              }),
+            );
           } else {
             log.info(`No skills found for "${query}".`);
+            if (registryError) {
+              log.warn(`(skills.sh registry unavailable: ${registryError})`);
+            }
           }
           return;
         }
 
-        // Group skill slugs by source for batch audit lookups
-        const sourceToSlugs = new Map<string, string[]>();
-        for (const r of results) {
-          const slugs = sourceToSlugs.get(r.source) ?? [];
-          slugs.push(r.skillId);
-          sourceToSlugs.set(r.source, slugs);
-        }
-
-        // Fetch audits for each unique source, keyed by source/skillId
-        // to avoid collisions when different sources share the same slug.
+        // ── Fetch audits for community results ───────────────────────
         const allAudits: AuditResponse = {};
-        for (const [source, slugs] of sourceToSlugs) {
-          try {
-            const audits = await fetchSkillAudits(source, slugs);
-            for (const [skillId, auditData] of Object.entries(audits)) {
-              allAudits[`${source}/${skillId}`] = auditData;
+        if (registryResults.length > 0) {
+          const sourceToSlugs = new Map<string, string[]>();
+          for (const r of registryResults) {
+            const slugs = sourceToSlugs.get(r.source) ?? [];
+            slugs.push(r.skillId);
+            sourceToSlugs.set(r.source, slugs);
+          }
+          for (const [source, slugs] of sourceToSlugs) {
+            try {
+              const audits = await fetchSkillAudits(source, slugs);
+              for (const [skillId, auditData] of Object.entries(audits)) {
+                allAudits[`${source}/${skillId}`] = auditData;
+              }
+            } catch {
+              // Audit fetch failures are non-fatal
             }
-          } catch {
-            // Audit fetch failures are non-fatal; display results without audits
           }
         }
 
@@ -155,26 +217,68 @@ Examples:
           console.log(
             JSON.stringify({
               ok: true,
-              results,
+              catalog: catalogMatches,
+              community: registryResults,
               audits: allAudits,
+              ...(registryError ? { registryError } : {}),
             }),
           );
           return;
         }
 
-        log.info(`Search results for "${query}" (${results.length}):\n`);
-        for (const r of results) {
-          log.info(`  ${r.name}`);
-          log.info(`    ID: ${r.skillId}`);
-          log.info(`    Source: ${r.source}`);
-          log.info(`    Installs: ${r.installs}`);
-          const auditData = allAudits[`${r.source}/${r.skillId}`];
-          if (auditData) {
-            log.info(`    ${formatAuditBadges(auditData)}`);
-          } else {
-            log.info("    Security: no audit data");
+        // ── Installed-state detection ─────────────────────────────────
+        const skillsDir = getWorkspaceSkillsDir();
+        const isInstalled = (id: string) =>
+          existsSync(join(skillsDir, id, "SKILL.md"));
+
+        // ── Display catalog results ──────────────────────────────────
+        if (catalogMatches.length > 0) {
+          log.info(`Vellum catalog (${catalogMatches.length}):\n`);
+          for (const s of catalogMatches) {
+            const emoji = s.emoji ? `${s.emoji} ` : "";
+            const installed = isInstalled(s.id);
+            const badge = installed ? " [installed]" : "";
+            log.info(`  ${emoji}${s.name}${badge}`);
+            if (s.name !== s.id) {
+              log.info(`    ID: ${s.id}`);
+            }
+            log.info(`    Description: ${s.description}`);
+            log.info(`    Install: assistant skills install ${s.id}`);
+            if (conflictIds.has(s.id)) {
+              log.info(`    NOTE: Also found in community registry`);
+            }
+            log.info("");
+          }
+        }
+
+        // ── Display community results ────────────────────────────────
+        if (registryResults.length > 0) {
+          log.info(`Community registry (${registryResults.length}):\n`);
+          for (const r of registryResults) {
+            const installed = isInstalled(r.skillId);
+            const badge = installed ? " [installed]" : "";
+            log.info(`  ${r.name}${badge}`);
+            if (r.name !== r.skillId) {
+              log.info(`    ID: ${r.skillId}`);
+            }
+            log.info(`    Source: ${r.source}`);
+            log.info(`    Installs: ${r.installs}`);
+            const auditData = allAudits[`${r.source}/${r.skillId}`];
+            if (auditData) {
+              log.info(`    ${formatAuditBadges(auditData)}`);
+            } else {
+              log.info("    Security: no audit data");
+            }
+            log.info(
+              `    Install: assistant skills add ${r.source}@${r.skillId}`,
+            );
+            if (conflictIds.has(r.skillId)) {
+              log.info(`    NOTE: Conflicts with Vellum catalog skill`);
+            }
+            log.info("");
           }
-          log.info("");
+        } else if (registryError) {
+          log.warn(`\n(skills.sh registry unavailable: ${registryError})`);
         }
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -192,6 +296,21 @@ Examples:
     .description("Install a skill from the catalog")
     .option("--overwrite", "Replace an already installed skill")
     .option("--json", "Machine-readable JSON output")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  skill-id   Skill identifier from the Vellum catalog. Run 'assistant skills list'
+             to see available IDs. For community skills, use 'assistant skills add'.
+
+Downloads and installs the skill into the workspace skills directory. If the
+skill is already installed, use --overwrite to replace it.
+
+Examples:
+  $ assistant skills install weather
+  $ assistant skills install weather --overwrite
+  $ assistant skills install weather --json`,
+    )
     .action(
       async (
         skillId: string,
@@ -244,6 +363,19 @@ Examples:
     .command("uninstall <skill-id>")
     .description("Uninstall a previously installed skill")
     .option("--json", "Machine-readable JSON output")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  skill-id   Skill identifier to remove. Run 'assistant skills list' to see
+             installed skills.
+
+Removes the skill directory from the workspace. This action cannot be undone.
+
+Examples:
+  $ assistant skills uninstall weather
+  $ assistant skills uninstall weather --json`,
+    )
     .action(async (skillId: string, opts: { json?: boolean }) => {
       const json = opts.json ?? false;
 

package/src/cli/commands/usage.ts

@@ -178,11 +178,6 @@ Reads from the local LLM usage event ledger (llm_usage_events table) to
 display token consumption and cost data. Operates on the local SQLite
 database directly — does not require the assistant to be running.
 
-Subcommands:
-  totals       Aggregate totals for a time range (default when no subcommand given)
-  daily        Per-day token and cost breakdown
-  breakdown    Grouped breakdown by actor, provider, or model
-
 Time range can be specified with --range presets (today, week, month, all)
 or explicit --from / --to epoch-millisecond timestamps.
 
@@ -285,12 +280,11 @@ Examples:
     .addHelpText(
       "after",
       `
-Arguments:
-  --group-by <dimension>   One of: actor, provider, model (default: model)
-    actor     Groups by the subsystem that made the call (main_agent,
-              title_generator, etc.)
-    provider  Groups by LLM provider (anthropic, openai, etc.)
-    model     Groups by model name (claude-sonnet-4-20250514, etc.)
+Grouping dimensions:
+  actor     Groups by the subsystem that made the call (main_agent,
+            title_generator, etc.)
+  provider  Groups by LLM provider (anthropic, openai, etc.)
+  model     Groups by model name (claude-sonnet-4-20250514, etc.)
 
 Shows one row per group with input/output tokens, estimated cost, and
 call count. Rows are sorted by cost descending.