@vellumai/assistant 0.8.2 → 0.8.4

package/src/cli/commands/notifications.ts

@@ -1,9 +1,14 @@
 import type { Command } from "commander";
 
-import { cliIpcCall } from "../../ipc/cli-client.js";
+import {
+  cliIpcCall,
+  exitCodeFromIpcResult,
+  exitFromIpcResult,
+} from "../../ipc/cli-client.js";
 import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
 import { shouldOutputJson, writeOutput } from "../output.js";
+import { tryResolveConversationId } from "../utils/conversation-id.js";
 
 // ---------------------------------------------------------------------------
 // Command registration
@@ -26,11 +31,14 @@ source channel, event name, and attention hints. The decision engine evaluates
 whether and where to deliver the notification based on connected channels,
 urgency, and user preferences.
 
+Minimal usage: only --message is required. Add --urgent for a push + visual
+flag in the inbox. Source channel/event name fall back to assistant_tool /
+assistant.share when omitted.
+
 Examples:
-  $ assistant notifications send --source-channel assistant_tool --source-event-name user.send_notification --message "Build finished"
-  $ assistant notifications send --source-channel scheduler --source-event-name schedule.notify --message "Stand-up in 5 minutes" --urgency high
-  $ assistant notifications send --source-channel watcher --source-event-name watcher.notification --message "File changed" --no-requires-action --is-async-background
-  $ assistant notifications send --source-channel assistant_tool --source-event-name user.send_notification --message "Deploy complete" --preferred-channels vellum,telegram --json`,
+  $ assistant notifications send --message "Build finished"
+  $ assistant notifications send --message "Pager: prod is down" --urgent
+  $ assistant notifications send --message "Build green" --conversation-id 649c4645-3a6f-4ded-a713-504f02ca806b`,
       );
 
       // -------------------------------------------------------------------------
@@ -40,28 +48,33 @@ Examples:
       notifications
         .command("send")
         .description(
-          "Send a notification through the unified notification router",
+          "Send a notification through the unified notification router. Only --message is required; pass --urgent for a push + visual flag.",
         )
         .requiredOption(
+          "--message <message>",
+          "Notification message the user should receive",
+        )
+        .option(
+          "--urgent",
+          "Mark this notification as urgent (fires push + visual flag in inbox)",
+          false,
+        )
+        .option(
           "--source-channel <channel>",
-          "Source channel producing this notification",
+          "Source channel producing this notification (default: assistant_tool)",
         )
-        .requiredOption(
+        .option(
           "--source-event-name <name>",
-          "Event name for audit, routing, and dedupe grouping",
-        )
-        .requiredOption(
-          "--message <message>",
-          "Notification message the user should receive",
+          "Event name for audit, routing, and dedupe grouping (default: assistant.share)",
         )
         .option("--title <title>", "Optional notification title")
         .option(
           "--urgency <urgency>",
-          "Urgency hint: low, medium, high, critical (default: medium)",
+          "Urgency hint: low, medium, high, critical (default: low; use --urgent for critical)",
         )
         .option(
           "--requires-action",
-          "Whether the notification expects user action (default: true)",
+          "Whether the notification expects user action (default: false; use --urgent to force true)",
         )
         .option(
           "--no-requires-action",
@@ -111,15 +124,16 @@ Examples:
           "after",
           `
 Arguments:
-  --source-channel     One of the registered source channels (see "assistant notifications --help")
-  --source-event-name  One of the registered event names (see "assistant notifications --help")
   --message            The notification body text (required, must be non-empty)
+  --urgent             Shortcut that maps to urgency=critical + requires-action=true
 
 Behavioral notes:
   - The signal is emitted through the full notification pipeline: event store,
     decision engine, deterministic checks, and channel dispatch.
-  - --requires-action defaults to true; use --no-requires-action to disable.
-  - --urgency defaults to medium if not specified.
+  - --urgent overrides --urgency and --requires-action defaults so the signal
+    is treated as critical and requires user action. Explicit --urgency /
+    --requires-action flags still win for back-compat.
+  - Without --urgent, --urgency defaults to low and --requires-action to false.
   - --preferred-channels are hints only; the decision engine may override them.
   - --dedupe-key suppresses duplicate signals with the same key.
   - --conversation-id pins delivery to an existing vellum conversation
@@ -127,20 +141,20 @@ Behavioral notes:
     binding-based pairing for their external threads.
 
 Examples:
-  $ assistant notifications send --source-channel assistant_tool --source-event-name user.send_notification --message "Task complete"
-  $ assistant notifications send --source-channel scheduler --source-event-name schedule.notify --message "Meeting in 5 min" --urgency high --title "Reminder"
-  $ assistant notifications send --source-channel watcher --source-event-name watcher.notification --message "Detected change" --no-requires-action --is-async-background --json
-  $ assistant notifications send --source-channel assistant_tool --source-event-name user.send_notification --message "Build green" --conversation-id 649c4645-3a6f-4ded-a713-504f02ca806b`,
+  $ assistant notifications send --message "Task complete"
+  $ assistant notifications send --message "Pager: prod is down" --urgent
+  $ assistant notifications send --message "Build green" --conversation-id 649c4645-3a6f-4ded-a713-504f02ca806b`,
         )
         .action(
           async (
             opts: {
-              sourceChannel: string;
-              sourceEventName: string;
+              sourceChannel?: string;
+              sourceEventName?: string;
               message: string;
+              urgent: boolean;
               title?: string;
               urgency?: string;
-              requiresAction: boolean;
+              requiresAction?: boolean;
               isAsyncBackground: boolean;
               visibleInSourceNow: boolean;
               deadlineAt?: string;
@@ -153,6 +167,11 @@ Examples:
             cmd: Command,
           ) => {
             try {
+              // Apply defaults for optional source fields (minimal-surface
+              // ergonomics; explicit values from the CLI still win).
+              const sourceChannel = opts.sourceChannel ?? "assistant_tool";
+              const sourceEventName = opts.sourceEventName ?? "assistant.share";
+
               // Validate --message (keep basic validation for immediate CLI feedback)
               const message = opts.message.trim();
               if (message.length === 0) {
@@ -164,8 +183,15 @@ Examples:
                 return;
               }
 
+              // --urgent is a shortcut for urgency=critical + requiresAction=true.
+              // Explicit --urgency / --requires-action flags still win so the
+              // back-compat path keeps working during the deprecation window.
+              const urgentDefaults = opts.urgent
+                ? { urgency: "critical", requiresAction: true }
+                : { urgency: "low", requiresAction: false };
+
               // Validate --urgency
-              const urgency = opts.urgency ?? "medium";
+              const urgency = opts.urgency ?? urgentDefaults.urgency;
               if (
                 urgency !== "low" &&
                 urgency !== "medium" &&
@@ -179,6 +205,8 @@ Examples:
                 process.exitCode = 1;
                 return;
               }
+              const requiresAction =
+                opts.requiresAction ?? urgentDefaults.requiresAction;
 
               // Parse --deadline-at
               let deadlineAt: number | undefined;
@@ -221,8 +249,6 @@ Examples:
                 }
               }
 
-              const sourceContextId = opts.sessionId ?? `cli-${Date.now()}`;
-
               // Validate --conversation-id if provided
               const conversationId = opts.conversationId?.trim();
               if (opts.conversationId != null && !conversationId) {
@@ -234,6 +260,26 @@ Examples:
                 return;
               }
 
+              // Picks up __CONVERSATION_ID / __SKILL_CONTEXT_JSON env vars
+              // so deferred-emit can buffer notifications when called from a
+              // background job that hasn't confirmed success yet.
+              const originatingConversationId = tryResolveConversationId();
+
+              // The signal's `sourceContextId` doubles as the home-feed's
+              // navigation target — `resolveHomeFeedMirror` looks it up via
+              // `getConversation()` and only renders a "Go to Convo" button
+              // when it resolves to a real row. Prefer the conversation the
+              // CLI was invoked from (env-derived) so notifications emitted
+              // by background jobs and skills link back to their producing
+              // convo; an explicit --session-id still wins to preserve
+              // caller intent, and --conversation-id is the last resort
+              // before the unresolvable `cli-<ts>` sentinel.
+              const sourceContextId =
+                opts.sessionId ??
+                originatingConversationId ??
+                conversationId ??
+                `cli-${Date.now()}`;
+
               const result = await cliIpcCall<{
                 signalId: string;
                 dispatched: boolean;
@@ -241,11 +287,11 @@ Examples:
                 reason: string;
               }>("emit_notification_signal", {
                 body: {
-                  sourceChannel: opts.sourceChannel,
-                  sourceEventName: opts.sourceEventName,
+                  sourceChannel,
+                  sourceEventName,
                   sourceContextId,
                   attentionHints: {
-                    requiresAction: opts.requiresAction ?? true,
+                    requiresAction,
                     urgency,
                     deadlineAt,
                     isAsyncBackground: opts.isAsyncBackground ?? false,
@@ -253,7 +299,7 @@ Examples:
                   },
                   contextPayload: {
                     requestedMessage: message,
-                    requestedBySource: opts.sourceChannel,
+                    requestedBySource: sourceChannel,
                     ...(opts.title ? { requestedTitle: opts.title } : {}),
                     ...(preferredChannels?.length ? { preferredChannels } : {}),
                     ...(deepLinkMetadata ? { deepLinkMetadata } : {}),
@@ -262,14 +308,20 @@ Examples:
                   ...(conversationId
                     ? { conversationAffinityHint: { vellum: conversationId } }
                     : {}),
+                  ...(originatingConversationId
+                    ? { originatingConversationId }
+                    : {}),
                   throwOnError: true,
                 },
               });
 
               if (!result.ok) {
-                writeOutput(cmd, { ok: false, error: result.error });
-                process.exitCode = 1;
-                return;
+                if (shouldOutputJson(cmd)) {
+                  writeOutput(cmd, { ok: false, error: result.error });
+                  process.exitCode = exitCodeFromIpcResult(result);
+                  return;
+                }
+                return exitFromIpcResult(result);
               }
 
               const signal = result.result!;
@@ -382,7 +434,7 @@ Examples:
 
               if (!result.ok) {
                 writeOutput(cmd, { ok: false, error: result.error });
-                process.exitCode = 1;
+                process.exitCode = exitCodeFromIpcResult(result);
                 return;
               }
 

package/src/cli/commands/plugins.ts

@@ -19,6 +19,10 @@ import {
 } from "../lib/install-from-github.js";
 import { listInstalledPlugins } from "../lib/list-installed-plugins.js";
 import { registerCommand } from "../lib/register-command.js";
+import {
+  InvalidSearchPatternError,
+  searchPlugins,
+} from "../lib/search-plugins.js";
 import {
   PluginNotInstalledError,
   uninstallPlugin,
@@ -42,6 +46,9 @@ Examples:
   $ assistant plugins install simple-memory --ref my-feature-branch
   $ assistant plugins list
   $ assistant plugins list --json
+  $ assistant plugins search memory
+  $ assistant plugins search "^simple"
+  $ assistant plugins search memory --json
   $ assistant plugins uninstall simple-memory`,
       );
 
@@ -134,6 +141,66 @@ Examples:
           );
         });
 
+      plugins
+        .command("search <query>")
+        .description(
+          "Search vellum-ai/vellum-assistant/experimental/plugins for plugin names matching <query> (case-insensitive regex)",
+        )
+        .option("--json", "Emit machine-readable JSON instead of a table")
+        .action(async (query: string, opts: { json?: boolean }) => {
+          try {
+            const result = await searchPlugins(
+              { query },
+              { fetch: globalThis.fetch.bind(globalThis) },
+            );
+
+            // Log on every success path — JSON output, empty results, and
+            // populated tables alike — so observability doesn't depend on
+            // which formatting branch the caller landed in.
+            log.info(
+              {
+                query: result.query,
+                ref: result.ref,
+                matchCount: result.matches.length,
+              },
+              "external plugin search",
+            );
+
+            if (opts.json) {
+              process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+              return;
+            }
+
+            if (result.matches.length === 0) {
+              console.log(`No plugins matched "${result.query}".`);
+              return;
+            }
+
+            const nameW = Math.max(
+              4,
+              ...result.matches.map((m) => m.name.length),
+            );
+            const pad = (s: string, w: number) => s + " ".repeat(w - s.length);
+            console.log(`${pad("NAME", nameW)}  PATH`);
+            for (const m of result.matches) {
+              console.log(`${pad(m.name, nameW)}  ${m.path}`);
+            }
+            console.log("");
+            console.log(
+              `${result.matches.length} match${result.matches.length === 1 ? "" : "es"} for "${result.query}".`,
+            );
+          } catch (err) {
+            if (err instanceof InvalidSearchPatternError) {
+              console.error(err.message);
+              process.exitCode = 1;
+              return;
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`Plugin search failed: ${message}`);
+            process.exitCode = 1;
+          }
+        });
+
       plugins
         .command("uninstall <name>")
         .description("Remove a plugin from <workspaceDir>/plugins/<name>/")

package/src/cli/commands/schedules.ts

@@ -1,6 +1,7 @@
 import type { Command } from "commander";
 
 import { cliIpcCall, exitFromIpcResult } from "../../ipc/cli-client.js";
+import { confirmPrompt } from "../lib/confirm-prompt.js";
 import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
 import { writeOutput } from "../output.js";
@@ -60,18 +61,21 @@ export function registerSchedulesCommand(program: Command): void {
       schedules.addHelpText(
         "after",
         `
-Schedules are recurring or one-shot jobs run by the assistant daemon.
+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, and manually executing a schedule
-one time; create, delete, enable/disable, and run inspection will follow as
-separate slices.
+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.
 
 Examples:
   $ assistant schedules list
   $ assistant schedules list --all
   $ assistant schedules runs <schedule-id>
   $ assistant schedules runs <schedule-id> --limit 25 --json
+  $ assistant schedules disable <schedule-id>
+  $ assistant schedules enable <schedule-id>
+  $ assistant schedules cancel <schedule-id>
   $ assistant schedules execute <schedule-id>`,
       );
 
@@ -203,7 +207,7 @@ Examples:
           "after",
           `
 Options:
-  --limit <count>   Max runs to return. The daemon clamps values to 1-100.
+  --limit <count>   Max runs to return. The assistant clamps values to 1-100.
   --json            Output the raw run list as compact JSON.
 
 Arguments:
@@ -307,6 +311,271 @@ Examples:
           },
         );
 
+      schedules
+        .command("create <name>")
+        .description("Create a new recurring schedule")
+        .requiredOption(
+          "-e, --expression <expr>",
+          "Cron or RRULE expression that schedules the fire times",
+        )
+        .requiredOption(
+          "-m, --message <text>",
+          "Message body sent to the assistant on each fire",
+        )
+        .option(
+          "-t, --timezone <tz>",
+          "IANA timezone for the expression (e.g. America/New_York)",
+        )
+        .option("--no-enabled", "Create the schedule in a disabled state")
+        .option("--json", "Machine-readable compact JSON output")
+        .addHelpText(
+          "after",
+          `
+Options:
+  -e, --expression <expr>   Cron (e.g. '*/30 * * * *') or RRULE expression.
+  -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.
+  --json                    Output the updated schedule list as compact JSON.
+
+Arguments:
+  <name>   Display name for the schedule.
+
+Behavior:
+  Creates a recurring schedule in 'execute' mode. The IPC endpoint is
+  currently locked to execute mode; notify/script/wake schedules remain
+  reachable only through the in-assistant schedule_create LLM tool.
+
+Examples:
+  $ assistant schedules create "Heartbeat" \\
+      --expression '*/30 * * * *' \\
+      --message 'run heartbeat'
+  $ assistant schedules create "Morning summary" \\
+      --expression '0 9 * * MON-FRI' \\
+      --timezone America/New_York \\
+      --message 'write the morning summary'
+  $ assistant schedules create "Drafted" \\
+      --expression '0 0 * * *' \\
+      --message 'placeholder' \\
+      --no-enabled --json`,
+        )
+        .action(
+          async (
+            name: string,
+            opts: {
+              expression: string;
+              message: string;
+              timezone?: string;
+              enabled: boolean;
+              json?: boolean;
+            },
+            cmd: Command,
+          ) => {
+            const scheduleName = name.trim();
+            if (!scheduleName) {
+              const error = "name 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,
+              message: opts.message,
+              enabled: opts.enabled,
+            };
+            if (opts.timezone != null) body.timezone = opts.timezone;
+
+            const result = await cliIpcCall<ListSchedulesResponse>(
+              "createSchedule",
+              { body },
+            );
+
+            if (!result.ok) return exitFromIpcResult(result, cmd);
+
+            const response = result.result ?? { schedules: [] };
+            if (opts.json) {
+              writeOutput(cmd, response);
+              return;
+            }
+
+            log.info(`Created schedule: ${scheduleName}`);
+          },
+        );
+
+      schedules
+        .command("enable <id>")
+        .description("Enable a schedule")
+        .option("--json", "Machine-readable compact JSON output")
+        .addHelpText(
+          "after",
+          `
+Options:
+  --json   Output the updated schedule list as compact JSON.
+
+Arguments:
+  <id>   Schedule ID (UUID) — run 'assistant schedules list --all' to find it.
+
+Behavior:
+  Enables the schedule so it can run on future matching times. This does not
+  execute the schedule immediately; use 'assistant schedules execute <id>' for
+  manual run-now behavior.
+
+Examples:
+  $ assistant schedules enable 9f2c4f3a-3f1a-41e4-88e7-abc123
+  $ assistant schedules enable 9f2c4f3a-3f1a-41e4-88e7-abc123 --json`,
+        )
+        .action(async (id: string, opts: { json?: boolean }, cmd: Command) => {
+          await toggleScheduleEnabled(id, true, opts, cmd);
+        });
+
+      schedules
+        .command("disable <id>")
+        .description("Disable a schedule")
+        .option("--json", "Machine-readable compact JSON output")
+        .addHelpText(
+          "after",
+          `
+Options:
+  --json   Output the updated schedule list as compact JSON.
+
+Arguments:
+  <id>   Schedule ID (UUID) — run 'assistant schedules list --all' to find it.
+
+Behavior:
+  Disables the schedule so future scheduled fires are skipped until it is
+  enabled again. Existing run history is preserved.
+
+Examples:
+  $ assistant schedules disable 9f2c4f3a-3f1a-41e4-88e7-abc123
+  $ assistant schedules disable 9f2c4f3a-3f1a-41e4-88e7-abc123 --json`,
+        )
+        .action(async (id: string, opts: { json?: boolean }, cmd: Command) => {
+          await toggleScheduleEnabled(id, false, opts, cmd);
+        });
+
+      schedules
+        .command("cancel <id>")
+        .description("Cancel a pending one-shot schedule")
+        .option("--json", "Machine-readable compact JSON output")
+        .addHelpText(
+          "after",
+          `
+Options:
+  --json   Output the updated schedule list as compact JSON.
+
+Arguments:
+  <id>   Schedule ID (UUID) — run 'assistant schedules list --all' to find
+         pending one-shot/deferred schedules.
+
+Behavior:
+  Cancels a pending one-shot schedule. Recurring schedules are not cancellable;
+  use 'assistant schedules disable <id>' to pause recurring schedules.
+
+Examples:
+  $ assistant schedules cancel 9f2c4f3a-3f1a-41e4-88e7-abc123
+  $ assistant schedules cancel 9f2c4f3a-3f1a-41e4-88e7-abc123 --json`,
+        )
+        .action(async (id: string, opts: { json?: boolean }, cmd: Command) => {
+          const scheduleId = id.trim();
+          const result = await cliIpcCall<ListSchedulesResponse>(
+            "cancelSchedule",
+            { pathParams: { id: scheduleId } },
+          );
+
+          if (!result.ok) return exitFromIpcResult(result, cmd);
+
+          const response = result.result ?? { schedules: [] };
+          if (opts.json) {
+            writeOutput(cmd, response);
+            return;
+          }
+
+          log.info(`Cancelled schedule: ${scheduleId}`);
+        });
+
+      schedules
+        .command("delete <id>")
+        .description("Permanently delete a schedule and its run history")
+        .option("--force", "Skip the confirmation prompt")
+        .option("--json", "Machine-readable compact JSON output")
+        .addHelpText(
+          "after",
+          `
+Options:
+  --force  Skip the destructive y/N confirmation prompt. Required when stdin
+           is not a TTY (e.g. in scripts and CI).
+  --json   Output the updated schedule list as compact JSON.
+
+Arguments:
+  <id>   Schedule ID (UUID) — run 'assistant schedules list --all' to find it.
+
+Behavior:
+  Permanently removes the schedule and its run history. This cannot be undone.
+  To temporarily pause a recurring schedule, use
+  'assistant schedules disable <id>' instead.
+
+Examples:
+  $ assistant schedules delete 9f2c4f3a-3f1a-41e4-88e7-abc123
+  $ assistant schedules delete 9f2c4f3a-3f1a-41e4-88e7-abc123 --force
+  $ assistant schedules delete 9f2c4f3a-3f1a-41e4-88e7-abc123 --force --json`,
+        )
+        .action(
+          async (
+            id: string,
+            opts: { force?: boolean; json?: boolean },
+            cmd: Command,
+          ) => {
+            const scheduleId = id.trim();
+            if (!scheduleId) {
+              const error = "Schedule ID is required";
+              if (opts.json) {
+                writeOutput(cmd, { ok: false, error });
+              } else {
+                log.error(error);
+              }
+              process.exitCode = 1;
+              return;
+            }
+
+            if (!opts.force) {
+              const decision = await confirmPrompt({
+                question: `Delete schedule "${scheduleId}"? [y/N] `,
+                isTTY: Boolean(process.stdin.isTTY),
+                refuseNonInteractiveMessage: `Refusing to delete schedule "${scheduleId}" non-interactively. Pass --force to confirm.`,
+              });
+              if (decision === "non-interactive") {
+                process.exitCode = 1;
+                return;
+              }
+              if (decision === "denied") {
+                log.info("Delete cancelled.");
+                return;
+              }
+            }
+
+            const result = await cliIpcCall<ListSchedulesResponse>(
+              "deleteSchedule",
+              { pathParams: { id: scheduleId } },
+            );
+
+            if (!result.ok) return exitFromIpcResult(result, cmd);
+
+            const response = result.result ?? { schedules: [] };
+            if (opts.json) {
+              writeOutput(cmd, response);
+              return;
+            }
+
+            log.info(`Deleted schedule: ${scheduleId}`);
+          },
+        );
+
       schedules
         .command("execute <id>")
         .description("Execute a schedule one time immediately")
@@ -368,6 +637,29 @@ Examples:
   });
 }
 
+async function toggleScheduleEnabled(
+  id: string,
+  enabled: boolean,
+  opts: { json?: boolean },
+  cmd: Command,
+): Promise<void> {
+  const scheduleId = id.trim();
+  const result = await cliIpcCall<ListSchedulesResponse>("toggleSchedule", {
+    pathParams: { id: scheduleId },
+    body: { enabled },
+  });
+
+  if (!result.ok) return exitFromIpcResult(result, cmd);
+
+  const response = result.result ?? { schedules: [] };
+  if (opts.json) {
+    writeOutput(cmd, response);
+    return;
+  }
+
+  log.info(`${enabled ? "Enabled" : "Disabled"} schedule: ${scheduleId}`);
+}
+
 function describeSchedule(schedule: ScheduleRecord): string {
   if (schedule.isOneShot) return "one-shot";
   const expression = schedule.description ?? schedule.expression ?? "—";