@vellumai/assistant 0.6.3 → 0.6.5

package/src/cli/commands/browser.ts

@@ -0,0 +1,350 @@
+/**
+ * `assistant browser` CLI namespace.
+ *
+ * One subcommand per browser operation, driven from the shared
+ * browser operations contract ({@link BROWSER_OPERATION_META}).
+ * Each subcommand maps CLI kebab-case flags into snake_case input
+ * keys and calls `browser_execute` over the CLI IPC socket.
+ */
+
+import { writeFileSync } from "node:fs";
+
+import { type Command, Option } from "commander";
+
+import { BROWSER_OPERATION_META } from "../../browser/operations.js";
+import type {
+  BrowserOperationMeta,
+  OperationField,
+} from "../../browser/types.js";
+import { cliIpcCall } from "../../ipc/cli-client.js";
+import { log } from "../logger.js";
+
+// ── Naming helpers ───────────────────────────────────────────────────
+
+/**
+ * Convert a snake_case operation name to kebab-case for CLI subcommand
+ * names (e.g. `press_key` -> `press-key`).
+ */
+function toKebab(snakeCase: string): string {
+  return snakeCase.replace(/_/g, "-");
+}
+
+/**
+ * Convert a snake_case field name to a kebab-case CLI option flag
+ * (e.g. `allow_private_network` -> `--allow-private-network`).
+ *
+ * Boolean fields declare only `--flag`; Commander 13 auto-generates
+ * the `--no-flag` negation variant. Declaring both in a single spec
+ * string (e.g. `--flag, --no-flag`) breaks in Commander 13 because
+ * `--flag` still parses to `false`.
+ */
+function fieldToFlag(field: OperationField): string {
+  const kebab = toKebab(field.name);
+  if (field.type === "boolean") {
+    return `--${kebab}`;
+  }
+  return `--${kebab} <${field.type === "number" ? "number" : "value"}>`;
+}
+
+/**
+ * Convert a kebab-case option key back to snake_case for the IPC
+ * input object (e.g. `allowPrivateNetwork` -> `allow_private_network`).
+ *
+ * Commander camelCases option names, so we convert from camelCase
+ * to snake_case.
+ */
+function camelToSnake(camel: string): string {
+  return camel.replace(/[A-Z]/g, (m) => `_${m.toLowerCase()}`);
+}
+
+/**
+ * Resolve conversation ID from CLI execution context.
+ *
+ * Precedence:
+ *   1. `__SKILL_CONTEXT_JSON.conversationId`
+ *   2. `__CONVERSATION_ID`
+ *
+ * Returns undefined when neither source is available.
+ */
+function resolveContextConversationId(): string | undefined {
+  const contextJson = process.env.__SKILL_CONTEXT_JSON;
+  if (contextJson) {
+    try {
+      const parsed = JSON.parse(contextJson) as { conversationId?: unknown };
+      if (
+        typeof parsed.conversationId === "string" &&
+        parsed.conversationId.length > 0
+      ) {
+        return parsed.conversationId;
+      }
+    } catch {
+      // Ignore malformed skill context and fall through.
+    }
+  }
+
+  const envConversationId = process.env.__CONVERSATION_ID;
+  if (envConversationId && envConversationId.length > 0) {
+    return envConversationId;
+  }
+
+  return undefined;
+}
+
+/**
+ * Parse a CLI option value according to its field type.
+ */
+function parseFieldValue(
+  value: unknown,
+  field: OperationField,
+): string | number | boolean {
+  if (field.type === "boolean") return Boolean(value);
+  if (field.type === "number") {
+    const num = Number(value);
+    if (!Number.isFinite(num)) {
+      throw new Error(`Invalid number for --${toKebab(field.name)}: ${value}`);
+    }
+    return num;
+  }
+  return String(value);
+}
+
+// ── IPC response shape ───────────────────────────────────────────────
+
+interface BrowserExecuteResult {
+  content: string;
+  isError: boolean;
+  screenshots?: Array<{ mediaType: string; data: string }>;
+}
+
+// ── Subcommand builder ───────────────────────────────────────────────
+
+/**
+ * Build a Commander subcommand for a single browser operation.
+ */
+function buildSubcommand(parent: Command, meta: BrowserOperationMeta): void {
+  const subcmd = parent
+    .command(toKebab(meta.operation))
+    .description(meta.description);
+
+  // Add per-operation field options
+  for (const field of meta.fields) {
+    const flag = fieldToFlag(field);
+
+    if (field.enum) {
+      // Use Commander's Option class with .choices() for enum-constrained
+      // fields so invalid values are rejected at the CLI level and
+      // --help lists the allowed values.
+      const opt = new Option(flag, field.description).choices([...field.enum]);
+      if (field.required) {
+        opt.makeOptionMandatory(true);
+      }
+      subcmd.addOption(opt);
+    } else if (field.required) {
+      subcmd.requiredOption(flag, field.description);
+    } else {
+      subcmd.option(flag, field.description);
+    }
+  }
+
+  // Append per-operation help text with behavioral notes and examples
+  if (meta.helpText) {
+    subcmd.addHelpText("after", `\n${meta.helpText}`);
+  }
+
+  // screenshot gets an --output <path> option for writing JPEG to disk
+  if (meta.operation === "screenshot") {
+    subcmd.option(
+      "--output <path>",
+      "Write the screenshot JPEG to a file path on disk.",
+    );
+  }
+
+  subcmd.action(async (opts: Record<string, unknown>) => {
+    const parentOpts = parent.opts() as {
+      session?: string;
+      json?: boolean;
+      browserMode?: string;
+    };
+    const sessionId = parentOpts.session ?? "default";
+    const jsonMode = parentOpts.json ?? false;
+    const conversationId = resolveContextConversationId();
+
+    // Map Commander camelCase options back to snake_case input keys,
+    // filtering out parent-level options (session, json, browserMode)
+    // and screenshot ergonomics (output).
+    const input: Record<string, unknown> = {};
+    const excludeKeys = new Set(["session", "json", "output", "browserMode"]);
+
+    // Inject parent-level --browser-mode into the operation input so
+    // the backend receives the mode override for backend pinning.
+    if (parentOpts.browserMode) {
+      input.browser_mode = parentOpts.browserMode;
+    }
+
+    for (const [key, value] of Object.entries(opts)) {
+      if (excludeKeys.has(key)) continue;
+      if (value === undefined) continue;
+
+      const snakeKey = camelToSnake(key);
+      // Find the matching field for type coercion
+      const field = meta.fields.find((f) => f.name === snakeKey);
+      if (field) {
+        input[snakeKey] = parseFieldValue(value, field);
+      } else {
+        input[snakeKey] = value;
+      }
+    }
+
+    // Browser operations can be long-running (page loads, auth
+    // challenges, downloads up to 120s, etc.), so use a generous
+    // IPC timeout that exceeds any server-side operation timeout.
+    const ipcResult = await cliIpcCall<BrowserExecuteResult>(
+      "browser_execute",
+      {
+        operation: meta.operation,
+        input,
+        sessionId,
+        ...(conversationId ? { conversationId } : {}),
+      },
+      { timeoutMs: 180_000 },
+    );
+
+    if (!ipcResult.ok) {
+      if (jsonMode) {
+        process.stdout.write(
+          JSON.stringify({ ok: false, error: ipcResult.error }) + "\n",
+        );
+      } else {
+        log.error(`Error: ${ipcResult.error}`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    const result = ipcResult.result!;
+
+    if (result.isError) {
+      if (jsonMode) {
+        process.stdout.write(
+          JSON.stringify({ ok: false, error: result.content }) + "\n",
+        );
+      } else {
+        log.error(result.content);
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    // Handle screenshot --output: write JPEG to disk
+    if (
+      meta.operation === "screenshot" &&
+      opts.output &&
+      result.screenshots?.length
+    ) {
+      const screenshot = result.screenshots[0];
+      const buffer = Buffer.from(screenshot.data, "base64");
+      try {
+        writeFileSync(String(opts.output), buffer);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (jsonMode) {
+          process.stdout.write(
+            JSON.stringify({
+              ok: false,
+              error: `Failed to write screenshot to ${opts.output}: ${msg}`,
+            }) + "\n",
+          );
+        } else {
+          log.error(`Failed to write screenshot to ${opts.output}: ${msg}`);
+        }
+        process.exitCode = 1;
+        return;
+      }
+      if (!jsonMode) {
+        log.info(`Screenshot saved to ${opts.output}`);
+      }
+    }
+
+    if (jsonMode) {
+      const payload: Record<string, unknown> = {
+        ok: true,
+        content: result.content,
+      };
+      // Include base64 screenshot data in JSON output
+      if (result.screenshots?.length) {
+        payload.screenshots = result.screenshots;
+      }
+      process.stdout.write(JSON.stringify(payload) + "\n");
+    } else {
+      if (result.content) {
+        log.info(result.content);
+      }
+    }
+  });
+}
+
+// ── Registration ─────────────────────────────────────────────────────
+
+/**
+ * Valid browser mode values for the --browser-mode option.
+ * Includes canonical values and compatibility aliases accepted by
+ * `normalizeBrowserMode` (cdp-debugger → cdp-inspect, playwright → local).
+ */
+const BROWSER_MODES = [
+  "auto",
+  "extension",
+  "cdp-inspect",
+  "cdp-debugger",
+  "local",
+  "playwright",
+] as const;
+
+export function registerBrowserCommand(program: Command): void {
+  const browser = program
+    .command("browser")
+    .description("Control the browser via the running assistant.")
+    .option(
+      "--session <id>",
+      "Session ID to preserve browser state across invocations.",
+      "default",
+    )
+    .option("--json", "Output results as machine-readable JSON.")
+    .addOption(
+      new Option(
+        "--browser-mode <mode>",
+        "Browser backend to use. Overrides automatic selection.",
+      ).choices([...BROWSER_MODES]),
+    );
+
+  browser.addHelpText(
+    "after",
+    `
+Browser operations are executed through the running assistant.
+Each subcommand maps to a browser operation and communicates
+with the assistant process.
+
+The --session flag groups sequential commands so they share browser
+state (same page, cookies, etc.). Different session IDs create
+independent browser contexts.
+
+The --browser-mode flag pins the browser backend for all operations
+in the invocation. Valid modes: auto (default), extension, cdp-inspect,
+local. Useful for debugging or when deterministic backend selection
+is required.
+
+Examples:
+  $ assistant browser navigate --url https://example.com
+  $ assistant browser snapshot
+  $ assistant browser click --selector "#login"
+  $ assistant browser type --text "hello" --element-id e14
+  $ assistant browser screenshot --output page.jpg
+  $ assistant browser --session myflow navigate --url https://example.com
+  $ assistant browser --browser-mode local navigate --url http://localhost:3000
+  $ assistant browser --json screenshot`,
+  );
+
+  // Register one subcommand per browser operation
+  for (const meta of BROWSER_OPERATION_META) {
+    buildSubcommand(browser, meta);
+  }
+}

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).`);
+        }
+      }
+    });
+}