@vellumai/assistant 0.5.11 → 0.5.13

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.

package/src/cli/lib/daemon-credential-client.ts

@@ -88,34 +88,6 @@ async function daemonFetch(
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Derive the canonical credential storage key from a "service:field" name.
- * Mirrors the parsing in secret-routes.ts handleAddSecret / handleDeleteSecret.
- *
- * Uses lastIndexOf to split on the *last* colon so compound service names
- * (e.g. "integration:google") are preserved intact while the single-segment
- * field name is extracted correctly.
- */
-function deriveCredentialStorageKey(name: string): string {
-  // Already a canonical storage key (credential/service/field) — return as-is
-  // to avoid double-encoding (e.g. "credential/integration:google/access_token"
-  // would otherwise become "credential/credential/integration/google/access_token").
-  if (name.startsWith("credential/")) {
-    return name;
-  }
-
-  const colonIdx = name.lastIndexOf(":");
-  if (colonIdx < 1 || colonIdx === name.length - 1) {
-    // Malformed — return raw name so the caller stores *something*.
-    // The daemon would reject this with a 400, so this only fires in
-    // the offline fallback path with bad input.
-    return name;
-  }
-  const service = name.slice(0, colonIdx);
-  const field = name.slice(colonIdx + 1);
-  return credentialKey(service, field);
-}
-
 function deriveReadSecretRequest(account: string): {
   type: "api_key" | "credential";
   name: string;
@@ -227,11 +199,17 @@ export async function setSecureKeyViaDaemon(
   }
 
   // Daemon unreachable — fall back to direct write.
-  // For credentials, derive the canonical storage key (credential/service/field)
-  // to match the daemon path which uses credentialKey().
-  const storageKey =
-    type === "credential" ? deriveCredentialStorageKey(name) : name;
-  return setSecureKeyAsync(storageKey, value);
+  // For credentials, convert "service:field" to the canonical
+  // "credential/service/field" storage key using credentialKey().
+  if (type === "credential" && !name.startsWith("credential/")) {
+    const colonIdx = name.lastIndexOf(":");
+    if (colonIdx > 0 && colonIdx < name.length - 1) {
+      const service = name.slice(0, colonIdx);
+      const field = name.slice(colonIdx + 1);
+      return setSecureKeyAsync(credentialKey(service, field), value);
+    }
+  }
+  return setSecureKeyAsync(name, value);
 }
 
 /**
@@ -260,11 +238,17 @@ export async function deleteSecureKeyViaDaemon(
   }
 
   // Daemon unreachable — fall back to direct delete.
-  // For credentials, derive the canonical storage key (credential/service/field)
-  // to match the daemon path which uses credentialKey().
-  const storageKey =
-    type === "credential" ? deriveCredentialStorageKey(name) : name;
-  return deleteSecureKeyAsync(storageKey);
+  // For credentials, convert "service:field" to the canonical
+  // "credential/service/field" storage key using credentialKey().
+  if (type === "credential" && !name.startsWith("credential/")) {
+    const colonIdx = name.lastIndexOf(":");
+    if (colonIdx > 0 && colonIdx < name.length - 1) {
+      const service = name.slice(0, colonIdx);
+      const field = name.slice(colonIdx + 1);
+      return deleteSecureKeyAsync(credentialKey(service, field));
+    }
+  }
+  return deleteSecureKeyAsync(name);
 }
 
 /**

package/src/cli/program.ts

@@ -25,7 +25,7 @@ import { registerMcpCommand } from "./commands/mcp.js";
 import { registerMemoryCommand } from "./commands/memory.js";
 import { registerNotificationsCommand } from "./commands/notifications.js";
 import { registerOAuthCommand } from "./commands/oauth/index.js";
-import { registerPlatformCommand } from "./commands/platform.js";
+import { registerPlatformCommand } from "./commands/platform/index.js";
 import { registerSequenceCommand } from "./commands/sequence.js";
 import { registerShotgunCommand } from "./commands/shotgun.js";
 import { registerSkillsCommand } from "./commands/skills.js";

package/src/config/assistant-feature-flags.ts

@@ -18,10 +18,10 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
-import { getBaseDataDir, getIsContainerized } from "./env-registry.js";
+import { getRootDir } from "../util/platform.js";
+import { getIsContainerized } from "./env-registry.js";
 import type { AssistantConfig } from "./schema.js";
 
 // ---------------------------------------------------------------------------
@@ -135,17 +135,13 @@ interface FeatureFlagFileData {
  *
  * Docker: `GATEWAY_SECURITY_DIR/feature-flags.json`
  * Local:  `~/.vellum/protected/feature-flags.json`
- *
- * Uses `BASE_DATA_DIR` when set (multi-instance mode) so per-instance
- * feature flag files are correctly scoped.
  */
 function getFeatureFlagOverridesPath(): string {
   const securityDir = process.env.GATEWAY_SECURITY_DIR;
   if (securityDir) {
     return join(securityDir, "feature-flags.json");
   }
-  const root = join(getBaseDataDir() || homedir(), ".vellum");
-  return join(root, "protected", "feature-flags.json");
+  return join(getRootDir(), "protected", "feature-flags.json");
 }
 
 /**

package/src/config/bundled-skills/contacts/tools/google-contacts.ts

@@ -44,7 +44,7 @@ export async function run(
   }
 
   try {
-    const connection = await resolveOAuthConnection("integration:google", {
+    const connection = await resolveOAuthConnection("google", {
       account,
     });
     switch (action) {

package/src/config/bundled-skills/conversations/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: conversations
+description: Manage conversation threads (rename)
+compatibility: "Designed for Vellum personal assistants"
+metadata:
+  emoji: "\U0001F4AC"
+  vellum:
+    display-name: "Conversations"
+---
+
+Tools for managing conversation threads.
+
+## Renaming
+
+Use the `rename_conversation` tool to rename the current conversation thread when:
+- The topic has shifted significantly from the original title
+- The auto-generated title is generic or unhelpful
+- The user explicitly asks to rename the thread
+
+Keep titles concise (under 60 characters) and descriptive of the current topic.

package/src/config/bundled-skills/conversations/TOOLS.json

@@ -0,0 +1,23 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "rename_conversation",
+      "description": "Rename the current conversation thread. Use this when the conversation topic has shifted significantly from the original title, or when you notice the title is generic/unhelpful and you can provide a better one based on what has been discussed.",
+      "category": "conversation",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "The new title for the conversation. Should be concise (under 60 characters) and descriptive of the current topic."
+          }
+        },
+        "required": ["title"]
+      },
+      "executor": "tools/rename-conversation.ts",
+      "execution_target": "host"
+    }
+  ]
+}

package/src/config/bundled-skills/conversations/tools/rename-conversation.ts

@@ -0,0 +1,66 @@
+import {
+  getConversation,
+  updateConversationTitle,
+} from "../../../../memory/conversation-crud.js";
+import { buildAssistantEvent } from "../../../../runtime/assistant-event.js";
+import { assistantEventHub } from "../../../../runtime/assistant-event-hub.js";
+import { DAEMON_INTERNAL_ASSISTANT_ID } from "../../../../runtime/assistant-scope.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+import { getLogger } from "../../../../util/logger.js";
+
+const log = getLogger("rename-conversation");
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const title = input.title;
+  if (typeof title !== "string" || title.trim() === "") {
+    return {
+      content: "Error: title must be a non-empty string.",
+      isError: true,
+    };
+  }
+
+  const trimmedTitle = title.trim();
+  const conversationId = context.conversationId;
+
+  const conversation = getConversation(conversationId);
+  if (!conversation) {
+    return {
+      content: `Error: conversation ${conversationId} not found.`,
+      isError: true,
+    };
+  }
+
+  // Persist with isAutoTitle = 0 so auto-generation won't overwrite it
+  updateConversationTitle(conversationId, trimmedTitle, 0);
+
+  // Notify connected clients so the UI updates immediately
+  const assistantId = context.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID;
+  assistantEventHub
+    .publish(
+      buildAssistantEvent(
+        assistantId,
+        {
+          type: "conversation_title_updated",
+          conversationId,
+          title: trimmedTitle,
+        },
+        conversationId,
+      ),
+    )
+    .catch((err) => {
+      log.warn({ err }, "Failed to publish conversation_title_updated event");
+    });
+
+  log.info({ conversationId, title: trimmedTitle }, "Conversation renamed");
+
+  return {
+    content: `Conversation renamed to "${trimmedTitle}".`,
+    isError: false,
+  };
+}