@vellumai/assistant 0.6.4 → 0.6.5

package/src/cli/commands/attachment.ts

@@ -0,0 +1,182 @@
+/**
+ * `assistant attachment` CLI namespace.
+ *
+ * Subcommands: register, lookup — thin wrappers over the daemon's
+ * attachment IPC routes (`attachment/register`, `attachment/lookup`).
+ */
+
+import type { Command } from "commander";
+
+import { cliIpcCall } from "../../ipc/cli-client.js";
+import { log } from "../logger.js";
+import { shouldOutputJson, writeOutput } from "../output.js";
+
+// ── Registration ──────────────────────────────────────────────────────
+
+export function registerAttachmentCommand(program: Command): void {
+  const attachment = program
+    .command("attachment")
+    .description("Manage file attachments for conversations");
+
+  attachment.addHelpText(
+    "after",
+    `
+Attachments come in two flavours:
+
+  File-backed   Large files stored by path reference (no memory copy).
+                The file must remain on disk for the lifetime of the
+                attachment.
+  Inline        Small payloads encoded directly (handled internally).
+
+Use 'register' to record a file-backed attachment and 'lookup' to
+retrieve its stored path by the original source location.
+
+Examples:
+  $ assistant attachment register --path /tmp/clip.mp4 --mime video/mp4
+  $ assistant attachment register --path /tmp/clip.mp4 --mime video/mp4 --filename recording.mp4
+  $ assistant attachment lookup --source /tmp/clip.mp4 --conversation conv_abc123`,
+  );
+
+  // ── register ─────────────────────────────────────────────────────
+
+  attachment
+    .command("register")
+    .description("Register a file-backed attachment with the assistant")
+    .requiredOption("--path <file>", "Absolute path to the file (required)")
+    .requiredOption("--mime <type>", "MIME type of the file (required)")
+    .option(
+      "--filename <name>",
+      "Display filename (defaults to basename of path)",
+    )
+    .option("--json", "Output result as machine-readable JSON.")
+    .addHelpText(
+      "after",
+      `
+Registers a file on disk as a file-backed attachment in the assistant's
+attachment store. The file must exist at the given path and must remain
+on disk for the lifetime of the attachment — the assistant stores a
+path reference, not a copy.
+
+Returns the attachment ID and metadata on success.
+
+Examples:
+  $ assistant attachment register --path /tmp/clip.mp4 --mime video/mp4
+  $ assistant attachment register --path /tmp/screen.png --mime image/png --filename screenshot.png
+  $ assistant attachment register --path /tmp/audio.wav --mime audio/wav --json`,
+    )
+    .action(
+      async (
+        opts: {
+          path: string;
+          mime: string;
+          filename?: string;
+          json?: boolean;
+        },
+        cmd: Command,
+      ) => {
+        const jsonOutput = opts.json || shouldOutputJson(cmd);
+
+        const result = await cliIpcCall<{
+          id: string;
+          originalFilename: string;
+          mimeType: string;
+          sizeBytes: number;
+          kind: string;
+          filePath: string;
+          createdAt: number;
+        }>("attachment/register", {
+          path: opts.path,
+          mimeType: opts.mime,
+          filename: opts.filename,
+        });
+
+        if (!result.ok) {
+          if (jsonOutput) {
+            writeOutput(cmd, { ok: false, error: result.error });
+          } else {
+            log.error(result.error ?? "Unknown error");
+          }
+          process.exitCode = 1;
+          return;
+        }
+
+        const record = result.result!;
+
+        if (jsonOutput) {
+          writeOutput(cmd, { ok: true, ...record });
+        } else {
+          process.stdout.write(`${record.id}\n`);
+          log.info(`Attachment registered: ${record.id}`);
+          log.info(`  Filename: ${record.originalFilename}`);
+          log.info(`  MIME:     ${record.mimeType}`);
+          log.info(`  Size:     ${record.sizeBytes} bytes`);
+          log.info(`  Kind:     ${record.kind}`);
+          log.info(`  Path:     ${record.filePath}`);
+        }
+      },
+    );
+
+  // ── lookup ───────────────────────────────────────────────────────
+
+  attachment
+    .command("lookup")
+    .description("Look up a stored attachment by its original source path")
+    .requiredOption(
+      "--source <path>",
+      "Original source path of the file (required)",
+    )
+    .requiredOption(
+      "--conversation <id>",
+      "Conversation ID to search within (required) — run 'assistant conversations list' to find it",
+    )
+    .option("--json", "Output result as machine-readable JSON.")
+    .addHelpText(
+      "after",
+      `
+Searches for an attachment that was previously registered with the
+given source path, scoped to a specific conversation. Returns the
+stored file path on success.
+
+Attachments are linked to messages within conversations. Use
+'assistant conversations list' to find the conversation ID.
+
+Examples:
+  $ assistant attachment lookup --source /tmp/clip.mp4 --conversation conv_abc123
+  $ assistant attachment lookup --source /path/to/recording.mp4 --conversation conv_xyz --json`,
+    )
+    .action(
+      async (
+        opts: { source: string; conversation: string; json?: boolean },
+        cmd: Command,
+      ) => {
+        const jsonOutput = opts.json || shouldOutputJson(cmd);
+
+        const result = await cliIpcCall<{ filePath: string }>(
+          "attachment/lookup",
+          {
+            sourcePath: opts.source,
+            conversationId: opts.conversation,
+          },
+        );
+
+        if (!result.ok) {
+          if (jsonOutput) {
+            writeOutput(cmd, { ok: false, error: result.error });
+          } else {
+            log.error(result.error ?? "Unknown error");
+          }
+          process.exitCode = 1;
+          return;
+        }
+
+        if (jsonOutput) {
+          writeOutput(cmd, {
+            ok: true,
+            filePath: result.result!.filePath,
+          });
+        } else {
+          process.stdout.write(result.result!.filePath + "\n");
+        }
+      },
+    );
+}

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