@vellumai/assistant 0.7.0 → 0.7.1

package/src/cli/commands/cache.ts

@@ -5,12 +5,11 @@
  * 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";
+import { existsSync, readFileSync } from "./cache-fs.js";
 
 // ── Constants ─────────────────────────────────────────────────────────
 
@@ -63,7 +62,37 @@ function parseTtl(raw: string | undefined): number | undefined {
   return ms;
 }
 
-// ── Stdin helpers ─────────────────────────────────────────────────────
+// ── Payload helpers ──────────────────────────────────────────────────
+
+/**
+ * Parse and validate a raw JSON string, emitting a size warning to stderr
+ * if it exceeds 1 MB.
+ */
+function parseJsonPayload(raw: string, source: string): unknown {
+  if (!raw.trim()) {
+    throw new Error(
+      `Empty input from ${source}. Provide valid JSON.\n` +
+        '  Example: assistant cache set --value \'{"key":"value"}\'',
+    );
+  }
+
+  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 from ${source}. Provide a valid JSON value.\n` +
+        '  Example: assistant cache set --value \'{"key":"value"}\'',
+    );
+  }
+}
 
 /**
  * Read JSON payload from stdin when piped. Throws when stdin is a TTY
@@ -73,8 +102,9 @@ function parseTtl(raw: string | undefined): number | undefined {
 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',
+      "No input provided. Pipe JSON into stdin, or use --value / --file.\n" +
+        '  Example: echo \'{"key":"value"}\' | assistant cache set\n' +
+        '  Example: assistant cache set --value \'{"key":"value"}\'',
     );
   }
 
@@ -83,35 +113,55 @@ function readPayloadFromStdin(): unknown {
     raw = readFileSync("/dev/stdin", "utf-8");
   } catch (err) {
     throw new Error(
-      `Failed to read stdin: ${err instanceof Error ? err.message : String(err)}`,
+      `Failed to read stdin: ${err instanceof Error ? err.message : String(err)}.\n` +
+        "Use --value or --file as an alternative when stdin is unavailable.",
     );
   }
 
-  if (!raw.trim()) {
-    throw new Error(
-      "Empty input on stdin. Pipe valid JSON.\n" +
-        '  Example: echo \'{"key":"value"}\' | assistant cache set',
-    );
+  return parseJsonPayload(raw, "stdin");
+}
+
+/**
+ * Read JSON payload from a file path. Throws on missing file or invalid JSON.
+ */
+function readPayloadFromFile(filePath: string): unknown {
+  if (!existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
   }
 
-  // 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`,
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, "utf-8");
+  } catch (err) {
+    throw new Error(
+      `Failed to read file "${filePath}": ${err instanceof Error ? err.message : String(err)}`,
     );
   }
 
-  try {
-    return JSON.parse(raw);
-  } catch {
+  return parseJsonPayload(raw, `file "${filePath}"`);
+}
+
+/**
+ * Resolve the JSON payload from whichever input method was specified.
+ * Priority: --value > --file > stdin.
+ * Throws if multiple explicit sources are provided (--value + --file).
+ */
+function resolvePayload(opts: { value?: string; file?: string }): unknown {
+  if (opts.value !== undefined && opts.file !== undefined) {
     throw new Error(
-      "Invalid JSON on stdin. Provide a valid JSON value.\n" +
-        '  Example: echo \'{"key":"value"}\' | assistant cache set',
+      "Cannot use both --value and --file. Provide exactly one input source.",
     );
   }
+
+  if (opts.value !== undefined) {
+    return parseJsonPayload(opts.value, "--value");
+  }
+
+  if (opts.file !== undefined) {
+    return readPayloadFromFile(opts.file);
+  }
+
+  return readPayloadFromStdin();
 }
 
 // ── Registration ──────────────────────────────────────────────────────
@@ -132,8 +182,9 @@ 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:
+  $ assistant cache set --value '{"result": [1,2,3]}' --ttl 5m
+  $ assistant cache set --file /tmp/data.json --key my-key --ttl 1h
   $ 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`,
   );
@@ -142,7 +193,7 @@ Examples:
 
   cache
     .command("set")
-    .description("Store a JSON value in the cache (reads payload from stdin)")
+    .description("Store a JSON value in the cache")
     .option(
       "--key <key>",
       "Cache key for idempotent upsert. Omit to auto-generate.",
@@ -151,18 +202,29 @@ Examples:
       "--ttl <duration>",
       "Time-to-live (minimum 1s). Units: ms, s, m, h (e.g. 1000ms, 30s, 5m, 2h). Defaults to 30m if omitted.",
     )
+    .option(
+      "--value <json>",
+      "JSON payload to store. Alternative to piping via stdin.",
+    )
+    .option(
+      "--file <path>",
+      "Path to a file containing the JSON payload. Alternative to piping via stdin.",
+    )
     .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.
+Stores a JSON payload in the cache and prints the assigned key. The payload
+can be provided via --value, --file, or piped through stdin. 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)
+Input sources (mutually exclusive, checked in this order):
+  --value <json>    Inline JSON string.
+  --file <path>     Path to a JSON file.
+  (stdin)           Piped input (fallback when neither flag is given).
 
 Options:
   --key <key>       Cache key string. Omit to auto-generate a random hex key.
@@ -171,71 +233,80 @@ Options:
   --json            Output as JSON: { "ok": true, "key": "..." }
 
 Examples:
+  $ assistant cache set --value '{"scores":[98,85,72]}' --ttl 5m
+  $ assistant cache set --file /tmp/payload.json --key scores --ttl 10m
   $ 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);
+    .action(
+      async (opts: {
+        key?: string;
+        ttl?: string;
+        value?: string;
+        file?: string;
+        json?: boolean;
+      }) => {
+        let data: unknown;
+        try {
+          data = resolvePayload(opts);
+        } 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;
         }
-        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);
+        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;
         }
-        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", {
-        body: params,
-      });
+        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", {
+          body: 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 (!result.ok) {
         if (opts.json) {
           process.stdout.write(
-            JSON.stringify({ ok: false, error: result.error }) + "\n",
+            JSON.stringify({ ok: true, key: result.result!.key }) + "\n",
           );
         } else {
-          log.error(`Error: ${result.error}`);
+          log.info(`Cached with key: ${result.result!.key}`);
         }
-        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 ───────────────────────────────────────────────────────────
 

package/src/cli/commands/clients.ts

@@ -1,19 +1,30 @@
 import type { Command } from "commander";
 
 import { cliIpcCall } from "../../ipc/cli-client.js";
-import type { ClientEntryJSON } from "../../runtime/client-registry.js";
 import { optsToQueryParams } from "../lib/ipc-params.js";
 import { log } from "../logger.js";
 import { writeOutput } from "../output.js";
 
+interface ClientEntryJSON {
+  clientId: string;
+  interfaceId: string;
+  capabilities: string[];
+  connectedAt: string;
+  lastActiveAt: string;
+}
+
 interface ListClientsResponse {
   clients: ClientEntryJSON[];
 }
 
+interface DisconnectClientResponse {
+  disconnected: number;
+}
+
 export function registerClientsCommand(program: Command): void {
   const clients = program
     .command("clients")
-    .description("Discover connected clients and their capabilities");
+    .description("Discover and manage connected clients");
 
   clients.addHelpText(
     "after",
@@ -24,9 +35,10 @@ 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`,
+  $ 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
+  $ assistant clients disconnect <clientId>            Force-disconnect a client`,
   );
 
   clients
@@ -121,6 +133,52 @@ Examples:
         }
       },
     );
+
+clients
+  .command("disconnect <clientId>")
+  .description("Force-disconnect a client by its ID")
+  .option("--json", "Machine-readable compact JSON output")
+  .addHelpText(
+    "after",
+    `
+Arguments:
+clientId   The UUID of the client to disconnect (from \`clients list\`).
+
+Force-disposes all hub subscribers for the given client, closing their
+SSE streams. The client will observe a broken connection and may
+reconnect automatically depending on its implementation.
+
+Examples:
+$ assistant clients disconnect a1a30bde-6679-406c-bc32-d5a0d2a7a99e
+$ assistant clients disconnect a1a30bde-6679-406c-bc32-d5a0d2a7a99e --json`,
+  )
+  .action(
+    async (
+      clientId: string,
+      opts: { json?: boolean },
+      cmd: Command,
+    ) => {
+      const result = await cliIpcCall<DisconnectClientResponse>(
+        "disconnect_client",
+        { body: { clientId } },
+      );
+
+      if (!result.ok) {
+        log.error(result.error ?? "Failed to disconnect client");
+        process.exitCode = 1;
+        return;
+      }
+
+      if (opts.json) {
+        writeOutput(cmd, result.result!);
+        return;
+      }
+
+      log.info(
+        `Disconnected client ${clientId} (${result.result!.disconnected} subscriber${result.result!.disconnected === 1 ? "" : "s"} disposed)`,
+      );
+    },
+  );
 }
 
 function formatRelativeTime(iso: string): string {

package/src/cli/commands/completions.ts

@@ -38,7 +38,7 @@ Examples:
         conversations: ["list", "new", "export", "clear"],
         config: ["set", "get", "list", "validate-allowlist"],
         keys: ["list", "set", "delete"],
-        trust: ["list", "add", "update", "remove"],
+        trust: ["list"],
         memory: ["status", "backfill", "cleanup", "query", "rebuild-index"],
         contacts: ["list", "invites", "get", "merge"],
         autonomy: ["get", "set"],
@@ -125,7 +125,7 @@ _assistant() {
         'conversations:Manage conversations'
         'config:Manage configuration'
         'keys:Manage API keys in secure storage'
-        'trust:Manage trust rules'
+        'trust:View trust rules'
         'memory:Manage long-term memory'
         'contacts:Manage the contact graph'
         'autonomy:View and configure autonomy tiers'
@@ -164,7 +164,7 @@ function generateFishCompletion(
     conversations: "Manage conversations",
     config: "Manage configuration",
     keys: "Manage API keys in secure storage",
-    trust: "Manage trust rules",
+    trust: "View trust rules",
     memory: "Manage long-term memory",
     contacts: "Manage the contact graph",
     autonomy: "View and configure autonomy tiers",