@vellumai/assistant 0.11.4 → 0.11.5-staging.1

package/src/cli/commands/__tests__/plugins.test.ts

@@ -16,6 +16,8 @@
  *   - under --json the consent listing, the prompt, and the cancellation line
  *     all go to stderr, leaving stdout a pure JSON document
  *   - inspect renders the schedules surface block
+ *   - install prints a setup-skill hint when `skills/setup` or
+ *     `skills/<name>-setup` is present on the installed tree
  *
  * The installers are replaced by fakes that stage a fixture tree and run the
  * real `confirmStagedOrAbort` gate, so the command's consent callback is
@@ -76,6 +78,10 @@ let ipcResults: Array<{
 
 let inspectResult: PluginInspection | null = null;
 
+/** On-disk tree returned as the fake install `target` so post-install walks work. */
+let installTarget: string | null = null;
+const installTargetDirs: string[] = [];
+
 // ---------------------------------------------------------------------------
 // Mocks
 // ---------------------------------------------------------------------------
@@ -123,7 +129,7 @@ async function runFakeInstall(
   await stageAndConfirm(name, deps?.confirmStaged);
   return {
     name,
-    target: `/plugins/${name}`,
+    target: installTarget ?? `/plugins/${name}`,
     fileCount: 3,
     ref: "main",
     commit: "a".repeat(40),
@@ -253,6 +259,7 @@ beforeEach(() => {
   upgradePluginCalls = [];
   ipcResults = [];
   inspectResult = null;
+  installTarget = null;
   // Platform features on by default, so a plain name install takes the
   // platform-tarball branch.
   delete process.env.VELLUM_DISABLE_PLATFORM;
@@ -260,6 +267,10 @@ beforeEach(() => {
 });
 
 afterEach(() => {
+  for (const dir of installTargetDirs) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+  installTargetDirs.length = 0;
   if (savedDisablePlatform === undefined) {
     delete process.env.VELLUM_DISABLE_PLATFORM;
   } else {
@@ -346,6 +357,7 @@ describe("plugins install - declared-schedules consent", () => {
     expect(confirmCalls.length).toBe(0);
     expect(r.stdout).not.toContain("declares");
     expect(r.stdout).not.toContain("schedule");
+    expect(r.stdout).not.toContain("to help set up this plugin");
     expect(r.stdout).toContain('Installed plugin "example"');
     expect(r.exitCode).toBe(0);
   });
@@ -690,3 +702,47 @@ describe("plugins inspect - schedules surface", () => {
     expect(r.exitCode).toBe(0);
   });
 });
+
+describe("plugins install - setup skill hint", () => {
+  function writeSetupSkill(skillId: string): void {
+    const dir = mkdtempSync(join(tmpdir(), "plugins-cmd-target-"));
+    installTargetDirs.push(dir);
+    mkdirSync(join(dir, "skills", skillId), { recursive: true });
+    writeFileSync(
+      join(dir, "skills", skillId, "SKILL.md"),
+      "---\nname: setup\ndescription: Set up the plugin.\n---\n",
+    );
+    installTarget = dir;
+  }
+
+  test("points at skills/setup after a successful install", async () => {
+    writeSetupSkill("setup");
+
+    const r = await runCommand(["plugins", "install", "example"]);
+
+    expect(r.stdout).toContain('Installed plugin "example"');
+    expect(r.stdout).toContain(
+      "Load the setup skill to help set up this plugin",
+    );
+    expect(r.exitCode).toBe(0);
+  });
+
+  test("points at skills/<name>-setup when that is the shipped id", async () => {
+    writeSetupSkill("imessage-setup");
+
+    const r = await runCommand(["plugins", "install", "imessage"]);
+
+    expect(r.stdout).toContain(
+      "Load the imessage-setup skill to help set up this plugin",
+    );
+    expect(r.exitCode).toBe(0);
+  });
+
+  test("prints no setup hint when the plugin ships no setup skill", async () => {
+    const r = await runCommand(["plugins", "install", "example"]);
+
+    expect(r.stdout).toContain('Installed plugin "example"');
+    expect(r.stdout).not.toContain("to help set up this plugin");
+    expect(r.exitCode).toBe(0);
+  });
+});

package/src/cli/commands/channel-verification-sessions.help.ts

@@ -10,15 +10,16 @@ export const channelVerificationSessionsHelp: CliCommandHelp = {
   ],
   helpText: `
 Verification sessions are used to verify guardian bindings and trusted
-contacts across channels (telegram, phone, slack, email). Three flows exist:
+contacts across channels (telegram, phone, slack, discord, email). Three
+flows exist:
 
   1. Inbound challenge — the assistant generates a secret code and waits
      for the guardian to send it back on the channel. Used when the
      guardian can already message the assistant.
 
   2. Outbound verification — the assistant sends a verification code to
-     a destination (Telegram handle, phone number, Slack user ID) and
-     waits for confirmation. Used when bootstrapping a new channel.
+     a destination (Telegram handle, phone number, Slack or Discord user
+     ID) and waits for confirmation. Used when bootstrapping a new channel.
 
   3. Trusted contact verification — verifies a contact channel that
      already exists in the contact graph, sending a code to the channel
@@ -36,7 +37,7 @@ Examples:
       options: [
         {
           flags: "--channel <channel>",
-          description: "Channel type (telegram, phone, slack, email)",
+          description: "Channel type (telegram, phone, slack, discord, email)",
         },
         {
           flags: "--destination <destination>",
@@ -72,8 +73,8 @@ Routes between three creation modes based on the provided options:
 
   2. Outbound: --channel <ch> --destination <dest>
      Sends a verification code to the given destination. Supports telegram
-     (handle or chat ID), phone (E.164 number), slack (user ID), and email.
-     Use --rebind to replace an existing guardian binding.
+     (handle or chat ID), phone (E.164 number), slack and discord (user ID),
+     and email. Use --rebind to replace an existing guardian binding.
 
   3. Inbound: --channel <ch> (no --destination)
      Generates a challenge secret for the guardian to send back on the
@@ -91,7 +92,8 @@ Examples:
       options: [
         {
           flags: "--channel <channel>",
-          description: "Channel type (telegram, phone). Defaults to telegram.",
+          description:
+            "Channel type (telegram, phone, slack, discord, email). Defaults to telegram.",
         },
       ],
       helpText: `
@@ -113,7 +115,7 @@ Examples:
       options: [
         {
           flags: "--channel <channel>",
-          description: "Channel type (telegram, phone, slack, email)",
+          description: "Channel type (telegram, phone, slack, discord, email)",
           required: true,
         },
         {
@@ -137,7 +139,7 @@ Examples:
       options: [
         {
           flags: "--channel <channel>",
-          description: "Channel type (telegram, phone, slack, email)",
+          description: "Channel type (telegram, phone, slack, discord, email)",
           required: true,
         },
       ],

package/src/cli/commands/channel-verification-sessions.ts

@@ -1,3 +1,12 @@
+// `cli/no-daemon-internals` forbids hoisting `channels/types.js`, so the CLI
+// reads the vocabulary straight from the contract package that file re-exports.
+// Both sides then validate `--channel` against the same set.
+
+import {
+  CHANNEL_IDS,
+  type ChannelId,
+  isChannelId,
+} from "@vellumai/service-contracts/channels";
 import type { Command } from "commander";
 
 import { cliIpcCall, exitFromIpcResult } from "../../ipc/cli-client.js";
@@ -6,25 +15,6 @@ import { registerCommand } from "../lib/register-command.js";
 import { writeOutput } from "../output.js";
 import { channelVerificationSessionsHelp } from "./channel-verification-sessions.help.js";
 
-// ---------------------------------------------------------------------------
-// Local channel validation (replaces daemon-internal channels/types.js import)
-// ---------------------------------------------------------------------------
-
-const VALID_CHANNEL_IDS = [
-  "telegram",
-  "phone",
-  "vellum",
-  "whatsapp",
-  "slack",
-  "email",
-  "platform",
-] as const;
-type ChannelId = (typeof VALID_CHANNEL_IDS)[number];
-
-function isChannelId(raw: string): raw is ChannelId {
-  return (VALID_CHANNEL_IDS as readonly string[]).includes(raw);
-}
-
 /**
  * Validate the --channel option. Returns the validated ChannelId or writes an
  * error and returns `false`. When `required` is false an absent value is fine
@@ -49,7 +39,7 @@ function validateChannelOpt(
     if (required) {
       writeOutput(cmd, {
         ok: false,
-        error: `The "channel" option is required. Valid values: ${VALID_CHANNEL_IDS.join(", ")}`,
+        error: `The "channel" option is required. Valid values: ${CHANNEL_IDS.join(", ")}`,
       });
       process.exitCode = 1;
       return false;
@@ -59,7 +49,7 @@ function validateChannelOpt(
   if (!isChannelId(raw)) {
     writeOutput(cmd, {
       ok: false,
-      error: `Invalid channel "${raw}". Valid values: ${VALID_CHANNEL_IDS.join(", ")}`,
+      error: `Invalid channel "${raw}". Valid values: ${CHANNEL_IDS.join(", ")}`,
     });
     process.exitCode = 1;
     return false;

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

@@ -12,6 +12,7 @@ running.
 
 Examples:
   $ assistant conversations list
+  $ assistant conversations search "project planning"
   $ assistant conversations new "Project planning"
   $ assistant conversations export
   $ assistant conversations clear`,
@@ -168,6 +169,39 @@ include them.
 Examples:
   $ assistant conversations list
   $ assistant conversations list --include-archived`,
+    },
+    {
+      name: "search",
+      args: "<term>",
+      description: "Search conversations by title and message content",
+      options: [
+        {
+          flags: "--limit <n>",
+          description: "Maximum number of conversations to return (default 20)",
+        },
+        {
+          flags: "--json",
+          description: "Output result as machine-readable JSON",
+        },
+      ],
+      helpText: `
+Arguments:
+  term   Search query. Quote multi-word terms so the shell keeps them as one
+         argument. Matches conversation titles (substring) and message
+         content (full-text). Archived conversations are excluded, matching
+         'assistant conversations list'.
+
+Requires the assistant to be running. Communicates via IPC socket.
+
+Results are grouped by conversation, ordered by most recently updated, and
+capped at 20 conversations unless --limit is set. Each result includes the
+conversation ID, title, relative timestamp, and up to three matching
+message excerpts. Use the ID with rename, export, or wake.
+
+Examples:
+  $ assistant conversations search "project planning"
+  $ assistant conversations search flux --limit 5
+  $ assistant conversations search "quarterly metrics" --json`,
     },
     {
       name: "new",

package/src/cli/commands/conversations.ts

@@ -11,6 +11,7 @@ import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { registerCommand } from "../lib/register-command.js";
 import { timeAgo } from "../lib/time-ago.js";
 import { log } from "../logger.js";
+import { shouldOutputJson, writeError, writeOutput } from "../output.js";
 import { tryResolveConversationId } from "../utils/conversation-id.js";
 import { conversationsHelp } from "./conversations.help.js";
 import { registerConversationsDeferCommand } from "./conversations-defer.js";
@@ -29,6 +30,66 @@ type SlackDetachCliResult = {
   conversationId?: string;
 };
 
+type ConversationSearchMessage = {
+  messageId: string;
+  role: string;
+  excerpt: string;
+  createdAt: number;
+};
+
+type ConversationSearchResult = {
+  conversationId: string;
+  conversationTitle: string | null;
+  conversationUpdatedAt: number;
+  matchingMessages: ConversationSearchMessage[];
+};
+
+type ConversationSearchResponse = {
+  query: string;
+  results: ConversationSearchResult[];
+};
+
+function parsePositiveLimit(
+  raw: string | undefined,
+): { ok: true; value: number | undefined } | { ok: false; error: string } {
+  if (raw === undefined) {
+    return { ok: true, value: undefined };
+  }
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    return {
+      ok: false,
+      error:
+        "Invalid --limit value. Must be a positive integer, e.g. --limit 10.",
+    };
+  }
+  const value = Number(trimmed);
+  if (!Number.isSafeInteger(value) || value < 1) {
+    return {
+      ok: false,
+      error:
+        "Invalid --limit value. Must be a positive integer, e.g. --limit 10.",
+    };
+  }
+  return { ok: true, value };
+}
+
+function formatSearchResultLines(
+  results: ConversationSearchResult[],
+): string[] {
+  const lines: string[] = [];
+  for (const result of results) {
+    lines.push(
+      `  ${result.conversationId}  ${result.conversationTitle ?? "Untitled"}  ${timeAgo(result.conversationUpdatedAt)}`,
+    );
+    for (const message of result.matchingMessages) {
+      const excerpt = message.excerpt.replace(/\s+/g, " ").trim();
+      lines.push(`    ${message.role}  ${excerpt}`);
+    }
+  }
+  return lines;
+}
+
 function outputSlackDetachError(message: string, json?: boolean): void {
   if (json) {
     process.stdout.write(JSON.stringify({ ok: false, error: message }) + "\n");
@@ -200,6 +261,70 @@ export function registerConversationsCommand(program: Command): void {
         },
       );
 
+      // -------------------------------------------------------------------
+      // search
+      // -------------------------------------------------------------------
+
+      subcommand(conversations, "search").action(
+        async (term: string, opts: { limit?: string }, cmd: Command) => {
+          const trimmed = term.trim();
+          if (!trimmed) {
+            writeError(
+              cmd,
+              'Search term must be a non-empty string. Quote multi-word queries, e.g. assistant conversations search "project planning".',
+            );
+            process.exitCode = 1;
+            return;
+          }
+
+          const parsedLimit = parsePositiveLimit(opts.limit);
+          if (!parsedLimit.ok) {
+            writeError(cmd, parsedLimit.error);
+            process.exitCode = 1;
+            return;
+          }
+
+          const queryParams: Record<string, string> = { q: trimmed };
+          if (parsedLimit.value !== undefined) {
+            queryParams.limit = String(parsedLimit.value);
+          }
+
+          const result = await cliIpcCall<ConversationSearchResponse>(
+            "conversations_search",
+            { queryParams },
+          );
+
+          if (!result.ok) {
+            if (shouldOutputJson(cmd)) {
+              writeOutput(cmd, {
+                ok: false,
+                error: result.error ?? "Conversation search failed",
+              });
+              process.exitCode = exitCodeFromIpcResult(result);
+              return;
+            }
+            return exitFromIpcResult(result);
+          }
+
+          const payload = result.result!;
+          if (shouldOutputJson(cmd)) {
+            writeOutput(cmd, payload);
+            return;
+          }
+
+          if (payload.results.length === 0) {
+            process.stdout.write(
+              `No conversations matched "${payload.query}"\n`,
+            );
+            return;
+          }
+
+          process.stdout.write(
+            formatSearchResultLines(payload.results).join("\n") + "\n",
+          );
+        },
+      );
+
       // -------------------------------------------------------------------
       // new
       // -------------------------------------------------------------------

package/src/cli/commands/inference-providers.ts

@@ -38,6 +38,7 @@ interface ProviderConnection {
   name: string;
   provider: string;
   auth: AuthInfo;
+  baseUrl?: string | null;
   createdAt: string;
   updatedAt: string;
 }
@@ -129,10 +130,11 @@ function collectRepeatable(value: string, previous: string[]): string[] {
 }
 
 /**
- * Build the openai-compatible custom-provider fields (`base_url`, `models`)
- * from CLI flags, forwarded to the connection route under its exact field
- * names. The daemon stays authoritative on whether they are required/allowed;
- * the CLI only shape-forwards what the user passed.
+ * Build the custom-provider fields (`base_url`, `models`) from CLI flags,
+ * forwarded to the connection route under its exact field names. The daemon
+ * stays authoritative on whether they are required or allowed (openai-compatible
+ * requires both; ollama accepts an optional base URL); the CLI only
+ * shape-forwards what the user passed.
  */
 function buildCustomProviderFields(opts: {
   baseUrl?: string;
@@ -219,6 +221,9 @@ function attachGetSubcommand(parent: Command): void {
       process.stdout.write(`name:     ${conn.name}\n`);
       process.stdout.write(`provider: ${conn.provider}\n`);
       process.stdout.write(`auth:     ${formatAuth(conn.auth)}\n`);
+      if (conn.baseUrl) {
+        process.stdout.write(`base_url: ${conn.baseUrl}\n`);
+      }
       process.stdout.write(
         `created:  ${new Date(conn.createdAt).toISOString()}\n`,
       );

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

@@ -218,8 +218,12 @@ Examples:
   $ assistant inference providers create local-llm \\
       --provider openai-compatible \\
       --base-url http://localhost:1234/v1 --model my-model
+  $ assistant inference providers create ollama-home \\
+      --provider ollama --base-url http://192.168.1.50:11434/v1
   $ assistant inference providers update anthropic-personal \\
       --credential credential/anthropic/api_key
+  $ assistant inference providers update ollama \\
+      --base-url http://127.0.0.1:11434/v1
   $ assistant inference providers delete anthropic-personal
 
 After creating or updating a provider, validate it with a live call through
@@ -268,7 +272,7 @@ a profile that uses it:
             {
               flags: "--base-url <url>",
               description:
-                "Endpoint base URL (required for --provider openai-compatible)",
+                "Endpoint base URL (required for openai-compatible; optional for ollama)",
             },
           ],
         },
@@ -290,7 +294,8 @@ a profile that uses it:
             },
             {
               flags: "--base-url <url>",
-              description: "Endpoint base URL (openai-compatible providers)",
+              description:
+                "Endpoint base URL (openai-compatible or ollama)",
             },
           ],
         },
@@ -345,7 +350,7 @@ matching \`assistant inference providers <verb>\` command.`,
                 {
                   flags: "--base-url <url>",
                   description:
-                    "Endpoint base URL (required for --provider openai-compatible)",
+                    "Endpoint base URL (required for openai-compatible; optional for ollama)",
                 },
               ],
             },
@@ -367,7 +372,7 @@ matching \`assistant inference providers <verb>\` command.`,
                 {
                   flags: "--base-url <url>",
                   description:
-                    "Endpoint base URL (openai-compatible providers)",
+                    "Endpoint base URL (openai-compatible or ollama)",
                 },
               ],
             },

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

@@ -46,6 +46,13 @@ Examples:
       name: "delete",
       args: "<provider>",
       description: "Delete a stored API key",
+      options: [
+        {
+          flags: "--force",
+          description:
+            "Delete even when LLM provider connections resolve their auth through the key; those connections stop answering until a new key is stored",
+        },
+      ],
       helpText: `
 Arguments:
   provider   Provider name whose key should be removed from secure storage
@@ -53,9 +60,14 @@ Arguments:
 Removes the API key for the given provider from secure local storage. If
 no key exists for the provider, exits with an error.
 
+The delete is refused while an LLM provider connection resolves its auth
+through the key; the error names the connections that depend on it. Run
+'assistant inference providers list' to inspect them, and pass --force to delete
+anyway.
+
 Examples:
   $ assistant keys delete openai
-  $ assistant keys delete anthropic`,
+  $ assistant keys delete anthropic --force`,
     },
   ],
 };

package/src/cli/commands/keys.ts

@@ -123,21 +123,32 @@ Examples:
         },
       );
 
-      subcommand(keys, "delete").action(async (provider: string) => {
-        const { deleteSecureKeyViaDaemon } =
-          await import("../lib/daemon-credential-client.js");
-        const delResult = await deleteSecureKeyViaDaemon("api_key", provider);
-        if (delResult.result === "deleted") {
-          log.info(`Deleted API key for "${provider}"`);
-        } else if (delResult.result === "error") {
-          const detail = delResult.error ? `: ${delResult.error}` : "";
-          log.error(`Failed to delete API key for "${provider}"${detail}`);
-          process.exit(1);
-        } else {
-          log.error(`No API key found for "${provider}"`);
-          process.exit(1);
-        }
-      });
+      subcommand(keys, "delete").action(
+        async (provider: string, opts: { force?: boolean }) => {
+          const { deleteSecureKeyViaDaemon } =
+            await import("../lib/daemon-credential-client.js");
+          const delResult = await deleteSecureKeyViaDaemon(
+            "api_key",
+            provider,
+            opts.force === true,
+          );
+          if (delResult.result === "deleted") {
+            log.info(`Deleted API key for "${provider}"`);
+          } else if (delResult.result === "error") {
+            const detail = delResult.error ? `: ${delResult.error}` : "";
+            log.error(`Failed to delete API key for "${provider}"${detail}`);
+            if (delResult.code === "CREDENTIAL_IN_USE") {
+              log.error(
+                `Run 'assistant inference providers list' to inspect those connections, or 'assistant keys delete ${provider} --force' to delete the key anyway.`,
+              );
+            }
+            process.exit(1);
+          } else {
+            log.error(`No API key found for "${provider}"`);
+            process.exit(1);
+          }
+        },
+      );
     },
   });
 }