@vellumai/assistant 0.6.4 → 0.6.6

package/src/cli/commands/cache.ts

@@ -0,0 +1,341 @@
+/**
+ * `assistant cache` CLI namespace.
+ *
+ * Subcommands: set, get, delete — thin wrappers over the daemon's
+ * cache IPC routes (`cache/set`, `cache/get`, `cache/delete`).
+ */
+
+import { readFileSync } from "node:fs";
+
+import type { Command } from "commander";
+
+import { cliIpcCall } from "../../ipc/cli-client.js";
+import { log } from "../logger.js";
+
+// ── Constants ─────────────────────────────────────────────────────────
+
+/** Warn (stderr) when a raw payload exceeds this byte count. */
+const MAX_PAYLOAD_BYTES = 1_000_000; // 1 MB
+
+// ── TTL parsing ───────────────────────────────────────────────────────
+
+const TTL_PATTERN = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h)$/;
+
+const TTL_MULTIPLIERS: Record<string, number> = {
+  ms: 1,
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+};
+
+/**
+ * Parse a human-friendly duration string (e.g. `"30s"`, `"5m"`, `"2h"`)
+ * into milliseconds. Returns `undefined` when the input is `undefined`.
+ * Throws on empty/whitespace-only or malformed input so the CLI can
+ * surface actionable errors.
+ */
+function parseTtl(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  if (!raw.trim()) {
+    throw new Error(
+      `Invalid --ttl value "${raw}". Expected a number followed by a unit: ms, s, m, or h (e.g. "1000ms", "30s", "5m", "2h"). Minimum 1s.`,
+    );
+  }
+  const match = TTL_PATTERN.exec(raw.trim());
+  if (!match) {
+    throw new Error(
+      `Invalid --ttl value "${raw}". Expected a number followed by a unit: ms, s, m, or h (e.g. "1000ms", "30s", "5m", "2h"). Minimum 1s.`,
+    );
+  }
+  const value = Number(match[1]);
+  const unit = match[2] as keyof typeof TTL_MULTIPLIERS;
+  const ms = Math.round(value * TTL_MULTIPLIERS[unit]);
+  if (ms <= 0) {
+    throw new Error(`--ttl must resolve to a positive duration, got ${ms}ms.`);
+  }
+  if (ms < 1000) {
+    throw new Error(
+      `--ttl must be at least 1s (got ${ms}ms). Sub-second TTLs are not ` +
+        `supported because CLI round-trip overhead would cause entries to ` +
+        `expire before they can be read.`,
+    );
+  }
+  return ms;
+}
+
+// ── Stdin helpers ─────────────────────────────────────────────────────
+
+/**
+ * Read JSON payload from stdin when piped. Throws when stdin is a TTY
+ * (no piped input) or when the input is empty/invalid JSON, so the CLI
+ * can surface actionable parse errors.
+ */
+function readPayloadFromStdin(): unknown {
+  if (process.stdin.isTTY) {
+    throw new Error(
+      "No input provided. Pipe JSON into stdin.\n" +
+        '  Example: echo \'{"key":"value"}\' | assistant cache set',
+    );
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync("/dev/stdin", "utf-8");
+  } catch (err) {
+    throw new Error(
+      `Failed to read stdin: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  if (!raw.trim()) {
+    throw new Error(
+      "Empty input on stdin. Pipe valid JSON.\n" +
+        '  Example: echo \'{"key":"value"}\' | assistant cache set',
+    );
+  }
+
+  // Warn on large payloads (but do not fail).
+  // Write directly to stderr so --json stdout output stays clean.
+  const byteLength = Buffer.byteLength(raw, "utf-8");
+  if (byteLength > MAX_PAYLOAD_BYTES) {
+    const sizeMb = (byteLength / 1_000_000).toFixed(2);
+    process.stderr.write(
+      `Warning: payload size (${sizeMb} MB) exceeds 1 MB. Large payloads may impact cache performance.\n`,
+    );
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error(
+      "Invalid JSON on stdin. Provide a valid JSON value.\n" +
+        '  Example: echo \'{"key":"value"}\' | assistant cache set',
+    );
+  }
+}
+
+// ── Registration ──────────────────────────────────────────────────────
+
+export function registerCacheCommand(program: Command): void {
+  const cache = program
+    .command("cache")
+    .description("Interact with the assistant's in-memory key/value cache");
+
+  cache.addHelpText(
+    "after",
+    `
+The cache is a TTL-aware, LRU-evicting in-memory store managed by the
+running assistant. Data is scoped to the assistant process lifetime and
+is not persisted across restarts.
+
+Keys are opaque strings. If no key is provided on set, the assistant
+generates one and returns it. Values can be any JSON-serializable data.
+
+Examples:
+  $ echo '{"result": [1,2,3]}' | assistant cache set --ttl 5m
+  $ echo '{"result": [1,2,3]}' | assistant cache set --key my-key --ttl 1h
+  $ assistant cache get my-key
+  $ assistant cache delete my-key`,
+  );
+
+  // ── set ───────────────────────────────────────────────────────────
+
+  cache
+    .command("set")
+    .description("Store a JSON value in the cache (reads payload from stdin)")
+    .option(
+      "--key <key>",
+      "Cache key for idempotent upsert. Omit to auto-generate.",
+    )
+    .option(
+      "--ttl <duration>",
+      "Time-to-live (minimum 1s). Units: ms, s, m, h (e.g. 1000ms, 30s, 5m, 2h). Defaults to 30m if omitted.",
+    )
+    .option("--json", "Output result as machine-readable JSON.")
+    .addHelpText(
+      "after",
+      `
+Reads a JSON payload from stdin, stores it in the cache, and prints the
+assigned key. If --key is provided, the entry is upserted (created or
+replaced). If omitted, a new unique key is generated.
+
+Payloads exceeding 1 MB emit a warning to stderr but are still stored.
+
+Arguments:
+  (none — payload is read from stdin)
+
+Options:
+  --key <key>       Cache key string. Omit to auto-generate a random hex key.
+  --ttl <duration>  Expiry duration (minimum 1s). Units: ms, s, m, h.
+                    Examples: 1000ms, 30s, 5m, 2h. Defaults to 30m if omitted.
+  --json            Output as JSON: { "ok": true, "key": "..." }
+
+Examples:
+  $ echo '{"scores":[98,85,72]}' | assistant cache set
+  $ echo '{"scores":[98,85,72]}' | assistant cache set --key scores --ttl 10m
+  $ echo '"simple string"' | assistant cache set --ttl 1h --json`,
+    )
+    .action(async (opts: { key?: string; ttl?: string; json?: boolean }) => {
+      let data: unknown;
+      try {
+        data = readPayloadFromStdin();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (opts.json) {
+          process.stdout.write(
+            JSON.stringify({ ok: false, error: msg }) + "\n",
+          );
+        } else {
+          log.error(msg);
+        }
+        process.exitCode = 1;
+        return;
+      }
+
+      let ttl_ms: number | undefined;
+      try {
+        ttl_ms = parseTtl(opts.ttl);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (opts.json) {
+          process.stdout.write(
+            JSON.stringify({ ok: false, error: msg }) + "\n",
+          );
+        } else {
+          log.error(msg);
+        }
+        process.exitCode = 1;
+        return;
+      }
+
+      const params: Record<string, unknown> = { data };
+      if (ttl_ms !== undefined) params.ttl_ms = ttl_ms;
+      if (opts.key) params.key = opts.key;
+
+      const result = await cliIpcCall<{ key: string }>("cache/set", params);
+
+      if (!result.ok) {
+        if (opts.json) {
+          process.stdout.write(
+            JSON.stringify({ ok: false, error: result.error }) + "\n",
+          );
+        } else {
+          log.error(`Error: ${result.error}`);
+        }
+        process.exitCode = 1;
+        return;
+      }
+
+      if (opts.json) {
+        process.stdout.write(
+          JSON.stringify({ ok: true, key: result.result!.key }) + "\n",
+        );
+      } else {
+        log.info(`Cached with key: ${result.result!.key}`);
+      }
+    });
+
+  // ── get ───────────────────────────────────────────────────────────
+
+  cache
+    .command("get <key>")
+    .description("Retrieve a cached value by key")
+    .option("--json", "Output result as machine-readable JSON.")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  key   The cache key to look up. Run 'assistant cache set' to store a
+        value and receive its key.
+
+Fetches the value associated with the given key. If the key does not
+exist or has expired, reports not-found. In --json mode, a miss returns
+{ "ok": true, "data": null }.
+
+Examples:
+  $ assistant cache get my-key
+  $ assistant cache get my-key --json`,
+    )
+    .action(async (key: string, opts: { json?: boolean }) => {
+      const result = await cliIpcCall<{ data: unknown } | null>("cache/get", {
+        key,
+      });
+
+      if (!result.ok) {
+        if (opts.json) {
+          process.stdout.write(
+            JSON.stringify({ ok: false, error: result.error }) + "\n",
+          );
+        } else {
+          log.error(`Error: ${result.error}`);
+        }
+        process.exitCode = 1;
+        return;
+      }
+
+      if (opts.json) {
+        process.stdout.write(
+          JSON.stringify({
+            ok: true,
+            data: result.result ? result.result.data : null,
+          }) + "\n",
+        );
+      } else {
+        if (result.result == null) {
+          log.info(`No cache entry found for key "${key}".`);
+        } else {
+          log.info(JSON.stringify(result.result.data, null, 2));
+        }
+      }
+    });
+
+  // ── delete ────────────────────────────────────────────────────────
+
+  cache
+    .command("delete <key>")
+    .description("Remove a cached entry by key")
+    .option("--json", "Output result as machine-readable JSON.")
+    .addHelpText(
+      "after",
+      `
+Arguments:
+  key   The cache key to remove. Run 'assistant cache get <key>' to
+        verify a key exists before deleting.
+
+Removes the entry from the cache. Idempotent — exits 0 whether the key
+existed or not, but reports whether an entry was actually removed.
+
+Examples:
+  $ assistant cache delete my-key
+  $ assistant cache delete my-key --json`,
+    )
+    .action(async (key: string, opts: { json?: boolean }) => {
+      const result = await cliIpcCall<{ deleted: boolean }>("cache/delete", {
+        key,
+      });
+
+      if (!result.ok) {
+        if (opts.json) {
+          process.stdout.write(
+            JSON.stringify({ ok: false, error: result.error }) + "\n",
+          );
+        } else {
+          log.error(`Error: ${result.error}`);
+        }
+        process.exitCode = 1;
+        return;
+      }
+
+      const deleted = result.result!.deleted;
+
+      if (opts.json) {
+        process.stdout.write(JSON.stringify({ ok: true, deleted }) + "\n");
+      } else {
+        if (deleted) {
+          log.info(`Deleted cache entry "${key}".`);
+        } else {
+          log.info(`No cache entry "${key}" (nothing to delete).`);
+        }
+      }
+    });
+}

package/src/cli/commands/clients.ts

@@ -0,0 +1,138 @@
+import type { Command } from "commander";
+
+import { cliIpcCall } from "../../ipc/cli-client.js";
+import type { ClientEntryJSON } from "../../runtime/client-registry.js";
+import { log } from "../logger.js";
+import { writeOutput } from "../output.js";
+
+interface ListClientsResponse {
+  clients: ClientEntryJSON[];
+}
+
+export function registerClientsCommand(program: Command): void {
+  const clients = program
+    .command("clients")
+    .description("Discover connected clients and their capabilities");
+
+  clients.addHelpText(
+    "after",
+    `
+Clients are the applications currently connected to the assistant —
+macOS desktop, iOS, web, Chrome extension, or CLI. Each client has a
+set of capabilities (e.g. host_bash, host_file) that determine which
+tools the assistant can route through it.
+
+Examples:
+  $ assistant clients list                       List all connected clients
+  $ assistant clients list --json                Machine-readable JSON output
+  $ assistant clients list --capability host_bash  Show only clients that can run host commands`,
+  );
+
+  clients
+    .command("list")
+    .description("List all currently connected clients")
+    .option("--json", "Machine-readable compact JSON output")
+    .option(
+      "--capability <name>",
+      "Filter to clients supporting this capability (e.g. host_bash, host_file, host_cu, host_browser)",
+    )
+    .addHelpText(
+      "after",
+      `
+Options:
+  --json                Output as compact JSON instead of a table.
+  --capability <name>   Only show clients that support the named capability.
+                        Valid values: host_bash, host_file, host_cu, host_browser.
+
+The table shows each client's ID, interface type, capabilities,
+connection timestamps, and host environment (when available).
+Clients are sorted by most recently active first.
+
+Examples:
+  $ assistant clients list
+  $ assistant clients list --capability host_bash
+  $ assistant clients list --json | jq '.clients[0].capabilities'`,
+    )
+    .action(
+      async (opts: { json?: boolean; capability?: string }, cmd: Command) => {
+        const params: Record<string, unknown> = {};
+        if (opts.capability) {
+          params.capability = opts.capability;
+        }
+
+        const result = await cliIpcCall<ListClientsResponse>(
+          "list_clients",
+          Object.keys(params).length > 0 ? params : undefined,
+        );
+
+        if (!result.ok) {
+          log.error(result.error ?? "Failed to list clients");
+          process.exitCode = 1;
+          return;
+        }
+
+        const response = result.result!;
+        const { clients: entries } = response;
+
+        if (opts.json) {
+          writeOutput(cmd, response);
+          return;
+        }
+
+        if (entries.length === 0) {
+          log.info("No clients connected.");
+          return;
+        }
+
+        // Table output
+        const header = [
+          "CLIENT ID",
+          "INTERFACE",
+          "CAPABILITIES",
+          "CONNECTED",
+          "LAST ACTIVE",
+          "HOST",
+        ];
+        const rows: string[][] = entries.map((e: ClientEntryJSON) => [
+          e.clientId.length > 20 ? `${e.clientId.slice(0, 17)}...` : e.clientId,
+          e.interfaceId,
+          e.capabilities.length > 0 ? e.capabilities.join(", ") : "—",
+          formatRelativeTime(e.connectedAt),
+          formatRelativeTime(e.lastActiveAt),
+          e.hostUsername
+            ? `${e.hostUsername}${e.hostHomeDir ? ` (${e.hostHomeDir})` : ""}`
+            : "—",
+        ]);
+
+        // Calculate column widths
+        const colWidths = header.map((h: string, i: number) =>
+          Math.max(h.length, ...rows.map((r: string[]) => r[i].length)),
+        );
+
+        const pad = (s: string, w: number) => s.padEnd(w);
+        const line = header
+          .map((h: string, i: number) => pad(h, colWidths[i]))
+          .join("  ");
+        log.info(line);
+        log.info(colWidths.map((w: number) => "─".repeat(w)).join("  "));
+        for (const row of rows) {
+          log.info(
+            row.map((c: string, i: number) => pad(c, colWidths[i])).join("  "),
+          );
+        }
+      },
+    );
+}
+
+function formatRelativeTime(iso: string): string {
+  const ms = Date.now() - new Date(iso).getTime();
+  if (ms < 0) return "just now";
+  const sec = Math.floor(ms / 1000);
+  if (sec < 60) return `${sec}s ago`;
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  const days = Math.floor(hr / 24);
+  return `${days}d ago`;
+}

package/src/cli/commands/completions.ts

@@ -40,7 +40,6 @@ Examples:
         keys: ["list", "set", "delete"],
         trust: ["list", "remove", "clear"],
         memory: ["status", "backfill", "cleanup", "query", "rebuild-index"],
-        hooks: ["list", "enable", "disable", "install", "remove"],
         contacts: ["list", "invites", "get", "merge"],
         autonomy: ["get", "set"],
       };
@@ -50,11 +49,9 @@ Examples:
         "keys",
         "trust",
         "memory",
-        "hooks",
         "contacts",
         "autonomy",
         "audit",
-        "doctor",
         "completions",
         "help",
       ];
@@ -64,7 +61,7 @@ Examples:
           process.stdout.write(generateBashCompletion(topLevel, subcommands));
           break;
         case "zsh":
-          process.stdout.write(generateZshCompletion(topLevel, subcommands));
+          process.stdout.write(generateZshCompletion(subcommands));
           break;
         case "fish":
           process.stdout.write(generateFishCompletion(topLevel, subcommands));
@@ -114,10 +111,7 @@ complete -F _assistant_completions assistant
 `;
 }
 
-function generateZshCompletion(
-  topLevel: string[],
-  subcommands: Record<string, string[]>,
-): string {
+function generateZshCompletion(subcommands: Record<string, string[]>): string {
   const subcmdCases = Object.entries(subcommands)
     .map(([cmd, subs]) => `        ${cmd}) compadd ${subs.join(" ")} ;;`)
     .join("\n");
@@ -133,11 +127,9 @@ _assistant() {
         'keys:Manage API keys in secure storage'
         'trust:Manage trust rules'
         'memory:Manage long-term memory'
-        'hooks:Manage hooks'
         'contacts:Manage the contact graph'
         'autonomy:View and configure autonomy tiers'
         'audit:Show recent tool invocations'
-        'doctor:Run diagnostic checks'
         'completions:Generate shell completion script'
         'help:Display help'
     )
@@ -174,11 +166,9 @@ function generateFishCompletion(
     keys: "Manage API keys in secure storage",
     trust: "Manage trust rules",
     memory: "Manage long-term memory",
-    hooks: "Manage hooks",
     contacts: "Manage the contact graph",
     autonomy: "View and configure autonomy tiers",
     audit: "Show recent tool invocations",
-    doctor: "Run diagnostic checks",
     completions: "Generate shell completion script",
     help: "Display help",
   };

package/src/cli/commands/config.ts

@@ -54,9 +54,9 @@ and "assistant keys set <provider> <key>" to view and manage API keys.
 
 Examples:
   $ assistant config list
-  $ assistant config get services.inference.provider
+  $ assistant config get llm.default.provider
   $ assistant config schema services
-  $ assistant config set services.inference.provider anthropic
+  $ assistant config set llm.default.provider anthropic
   $ assistant config set calls.enabled true`,
   );
 
@@ -69,7 +69,7 @@ Examples:
       "after",
       `
 Arguments:
-  key     Dotted path to the config key (e.g. services.inference.provider,
+  key     Dotted path to the config key (e.g. llm.default.provider,
           calls.enabled, twilio.accountSid). Intermediate objects are created
           automatically.
   value   The value to store. Parsed as JSON first (so "true" becomes boolean
@@ -81,7 +81,7 @@ After writing the value to config.json, the change takes effect immediately.
 To manage API keys, use "assistant keys set <provider> <key>" instead.
 
 Examples:
-  $ assistant config set services.inference.provider anthropic
+  $ assistant config set llm.default.provider anthropic
   $ assistant config set calls.enabled true`,
     )
     .action(
@@ -114,7 +114,7 @@ Examples:
       "after",
       `
 Arguments:
-  key   Dotted path to the config key (e.g. services.inference.provider,
+  key   Dotted path to the config key (e.g. llm.default.provider,
         calls.enabled)
 
 Prints the value at the given key path. If the key is not set, prints
@@ -123,7 +123,7 @@ Prints the value at the given key path. If the key is not set, prints
 To view API keys, use "assistant keys list" instead.
 
 Examples:
-  $ assistant config get services.inference.provider
+  $ assistant config get llm.default.provider
   $ assistant config get calls.enabled`,
     )
     .action((key: string) => {