@vellumai/assistant 0.6.1 → 0.6.3

package/src/browser-session/manager.ts

@@ -0,0 +1,159 @@
+import { v4 as uuid } from "uuid";
+
+import { consumeInvalidatedTargetId } from "./events.js";
+import type {
+  BrowserBackend,
+  BrowserSession,
+  CdpCommand,
+  CdpResult,
+} from "./types.js";
+
+export interface BrowserSessionManagerOptions {
+  /** Ordered list of backends to try; first available wins. */
+  backends: BrowserBackend[];
+}
+
+export class BrowserSessionManager {
+  private backends: BrowserBackend[];
+  private sessions = new Map<string, BrowserSession>();
+
+  constructor(opts: BrowserSessionManagerOptions) {
+    this.backends = opts.backends;
+  }
+
+  /** Pick an available backend or throw. */
+  selectBackend(): BrowserBackend {
+    const b = this.backends.find((x) => x.isAvailable());
+    if (!b) throw new Error("No available browser backend");
+    return b;
+  }
+
+  createSession(): BrowserSession {
+    const backend = this.selectBackend();
+    const session: BrowserSession = { id: uuid(), backendKind: backend.kind };
+    this.sessions.set(session.id, session);
+    return session;
+  }
+
+  getSession(id: string): BrowserSession | undefined {
+    return this.sessions.get(id);
+  }
+
+  /**
+   * Dispatch a CDP command.
+   *
+   * - If `sessionId` is provided, the session must exist in the manager; otherwise this throws.
+   *   The command is routed through the backend whose `kind` matches the session's `backendKind`,
+   *   ensuring per-session backend isolation and making `disposeSession()` an actual enforcement
+   *   boundary against stale ids. If the session has an opaque `targetId` and the command does
+   *   not already carry its own CDP `sessionId`, the manager injects the session's `targetId`
+   *   as the CDP `sessionId` so backends can multiplex commands across multiple tabs/targets.
+   * - If `sessionId` is `undefined`, the first available backend is selected for one-off
+   *   commands without a session handle (e.g. transport health probes).
+   */
+  async send(
+    sessionId: string | undefined,
+    command: CdpCommand,
+    signal?: AbortSignal,
+  ): Promise<CdpResult> {
+    let backend: BrowserBackend;
+    let outgoing = command;
+    if (sessionId !== undefined) {
+      const session = this.sessions.get(sessionId);
+      if (!session) {
+        throw new Error(`Unknown browser session: ${sessionId}`);
+      }
+      // If the chrome extension has reported this session's target
+      // as detached since the last dispatch, evict the session and
+      // throw so the caller can create a fresh one. Reading (and
+      // consuming) the invalidation flag here keeps the "next
+      // command forces reattach" semantics in lockstep with the
+      // host_browser_session_invalidated envelope handler — without
+      // this check the manager would happily forward a CDP command
+      // against a torn-down target and hit a permanent failure.
+      if (
+        session.targetId !== undefined &&
+        consumeInvalidatedTargetId(session.targetId)
+      ) {
+        this.sessions.delete(sessionId);
+        throw new Error(
+          `Browser session ${sessionId} was invalidated (target ${session.targetId} detached)`,
+        );
+      }
+      const matched = this.backends.find((b) => b.kind === session.backendKind);
+      if (!matched) {
+        throw new Error(
+          `No backend available for session kind: ${session.backendKind}`,
+        );
+      }
+      backend = matched;
+      // If the session has an opaque targetId and the command does not
+      // carry its own CDP sessionId, inject the session's targetId as
+      // the CDP sessionId. Backends that support multi-target routing
+      // will forward it; backends that ignore it will treat the call
+      // as "most-recent-tab" as before.
+      if (session.targetId !== undefined && command.sessionId === undefined) {
+        outgoing = { ...command, sessionId: session.targetId };
+      }
+    } else {
+      backend = this.selectBackend();
+    }
+    return backend.send(outgoing, signal);
+  }
+
+  disposeSession(id: string): void {
+    this.sessions.delete(id);
+  }
+
+  /**
+   * Evict a session that the backend has informed us is no longer
+   * valid — e.g. the chrome extension dispatched a
+   * `host_browser_session_invalidated` envelope after Chrome detached
+   * the debugger from the underlying tab/target.
+   *
+   * Functionally equivalent to {@link disposeSession} today (both
+   * remove the session from the manager's map so a subsequent
+   * `send()` throws "Unknown browser session") but preserved as a
+   * distinct method so call sites can stay explicit about intent.
+   * Callers that receive a detach/invalidated signal should use this
+   * method; callers that are cleaning up at end-of-lifecycle should
+   * use {@link disposeSession}.
+   *
+   * Returns `true` when a session was actually removed, `false` when
+   * no session with that id was tracked. Returning a boolean lets
+   * transport-level dispatchers (see
+   * `resolveHostBrowserSessionInvalidated`) log at the right level
+   * based on whether the invalidation had any effect.
+   */
+  invalidateSession(id: string): boolean {
+    return this.sessions.delete(id);
+  }
+
+  /**
+   * Evict every session whose opaque `targetId` matches the supplied
+   * id. Used by the WS dispatcher when a `host_browser_session_invalidated`
+   * envelope arrives without a manager-level session id: the
+   * extension-side dispatcher only knows its own `tabId` / `targetId`
+   * and does not carry our uuid session handle.
+   *
+   * Returns the number of sessions removed. A zero return does not
+   * necessarily indicate an error — the target may not have a
+   * runtime-side session attached to it yet, or the session may
+   * already have been disposed by its owning tool.
+   */
+  invalidateByTargetId(targetId: string): number {
+    let removed = 0;
+    for (const [id, session] of this.sessions) {
+      if (session.targetId === targetId) {
+        this.sessions.delete(id);
+        removed += 1;
+      }
+    }
+    return removed;
+  }
+
+  disposeAll(): void {
+    for (const b of this.backends) b.dispose();
+    this.sessions.clear();
+  }
+}

package/src/browser-session/types.ts

@@ -0,0 +1,28 @@
+export type BrowserBackendKind = "extension" | "local" | "cdp-inspect";
+
+export interface CdpCommand {
+  method: string;
+  params?: Record<string, unknown>;
+  sessionId?: string;
+}
+
+export interface CdpResult {
+  /** Raw CDP result object; opaque to the manager. */
+  result?: unknown;
+  /** CDP error envelope if the command failed. */
+  error?: { code: number; message: string; data?: unknown };
+}
+
+export interface BrowserSession {
+  id: string;
+  backendKind: BrowserBackendKind;
+  /** Opaque target/sessionId from the backend. Omitted for "most-recent-tab" commands. */
+  targetId?: string;
+}
+
+export interface BrowserBackend {
+  kind: BrowserBackendKind;
+  isAvailable(): boolean;
+  send(command: CdpCommand, signal?: AbortSignal): Promise<CdpResult>;
+  dispose(): void;
+}

package/src/channels/__tests__/types.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  INTERACTIVE_INTERFACES,
+  INTERFACE_IDS,
+  isInterfaceId,
+  supportsHostProxy,
+} from "../types.js";
+
+describe("INTERFACE_IDS", () => {
+  test("includes chrome-extension", () => {
+    expect(
+      (INTERFACE_IDS as readonly string[]).includes("chrome-extension"),
+    ).toBe(true);
+  });
+
+  test("still includes macos and other existing interfaces", () => {
+    for (const id of [
+      "macos",
+      "ios",
+      "cli",
+      "telegram",
+      "phone",
+      "vellum",
+      "whatsapp",
+      "slack",
+      "email",
+    ]) {
+      expect((INTERFACE_IDS as readonly string[]).includes(id)).toBe(true);
+    }
+  });
+});
+
+describe("INTERACTIVE_INTERFACES", () => {
+  test("does NOT include chrome-extension", () => {
+    // Chrome extensions don't render SSE-backed prompter UI, so they must
+    // stay out of the interactive set even though they have an InterfaceId.
+    expect(INTERACTIVE_INTERFACES.has("chrome-extension" as never)).toBe(false);
+  });
+
+  test("still includes macos", () => {
+    expect(INTERACTIVE_INTERFACES.has("macos")).toBe(true);
+  });
+});
+
+describe("isInterfaceId", () => {
+  test("returns true for chrome-extension", () => {
+    expect(isInterfaceId("chrome-extension")).toBe(true);
+  });
+
+  test("returns true for macos", () => {
+    expect(isInterfaceId("macos")).toBe(true);
+  });
+
+  test("returns false for unknown interface", () => {
+    expect(isInterfaceId("safari-extension")).toBe(false);
+  });
+});
+
+describe("supportsHostProxy", () => {
+  // ── macOS: supports host_bash / host_file / host_cu, but NOT host_browser. ──
+  test("macos returns true (no capability)", () => {
+    expect(supportsHostProxy("macos")).toBe(true);
+  });
+
+  test("macos returns true for host_bash", () => {
+    expect(supportsHostProxy("macos", "host_bash")).toBe(true);
+  });
+
+  test("macos returns true for host_file", () => {
+    expect(supportsHostProxy("macos", "host_file")).toBe(true);
+  });
+
+  test("macos returns true for host_cu", () => {
+    expect(supportsHostProxy("macos", "host_cu")).toBe(true);
+  });
+
+  test("macos returns false for host_browser", () => {
+    expect(supportsHostProxy("macos", "host_browser")).toBe(false);
+  });
+
+  // ── chrome-extension: only host_browser. ──
+  test("chrome-extension returns false (no capability)", () => {
+    // Chrome extension does not support "any host proxy at all" — it only
+    // supports host_browser, so the no-arg form must return false to keep
+    // existing call sites that guard desktop-only behavior unchanged.
+    expect(supportsHostProxy("chrome-extension")).toBe(false);
+  });
+
+  test("chrome-extension returns true for host_browser", () => {
+    expect(supportsHostProxy("chrome-extension", "host_browser")).toBe(true);
+  });
+
+  test("chrome-extension returns false for host_bash", () => {
+    expect(supportsHostProxy("chrome-extension", "host_bash")).toBe(false);
+  });
+
+  test("chrome-extension returns false for host_file", () => {
+    expect(supportsHostProxy("chrome-extension", "host_file")).toBe(false);
+  });
+
+  test("chrome-extension returns false for host_cu", () => {
+    expect(supportsHostProxy("chrome-extension", "host_cu")).toBe(false);
+  });
+
+  // ── Non-supporting interfaces: false in all forms. ──
+  test("cli returns false (no capability)", () => {
+    expect(supportsHostProxy("cli")).toBe(false);
+  });
+
+  test("cli returns false for host_bash", () => {
+    expect(supportsHostProxy("cli", "host_bash")).toBe(false);
+  });
+
+  test("cli returns false for host_browser", () => {
+    expect(supportsHostProxy("cli", "host_browser")).toBe(false);
+  });
+
+  test("telegram returns false (no capability)", () => {
+    expect(supportsHostProxy("telegram")).toBe(false);
+  });
+
+  test("telegram returns false for host_browser", () => {
+    expect(supportsHostProxy("telegram", "host_browser")).toBe(false);
+  });
+
+  test("vellum returns false (no capability)", () => {
+    expect(supportsHostProxy("vellum")).toBe(false);
+  });
+
+  test("email returns false for host_browser", () => {
+    expect(supportsHostProxy("email", "host_browser")).toBe(false);
+  });
+});

package/src/channels/types.ts

@@ -48,6 +48,7 @@ export const INTERFACE_IDS = [
   "whatsapp",
   "slack",
   "email",
+  "chrome-extension",
 ] as const;
 
 export type InterfaceId = (typeof INTERFACE_IDS)[number];
@@ -90,6 +91,60 @@ export function isInteractiveInterface(id: InterfaceId): boolean {
   return INTERACTIVE_INTERFACES.has(id);
 }
 
+/**
+ * Host proxy capabilities that an interface can support. The macOS client
+ * supports all four; the chrome-extension interface only supports
+ * host_browser (via the Chrome DevTools Protocol proxy).
+ */
+export type HostProxyCapability =
+  | "host_bash"
+  | "host_file"
+  | "host_cu"
+  | "host_browser";
+
+/**
+ * Interfaces that support the full desktop host-proxy set (all four
+ * `HostProxyCapability` values). This is the capability-level identity used
+ * by the discriminated transport metadata union and by the
+ * `supportsHostProxy(id)` type predicate.
+ *
+ * Extend this literal type AND the `supportsHostProxy` implementation
+ * below in lock-step when adding a new host-capable client (e.g. a native
+ * Linux or Windows desktop).
+ */
+export type HostProxyInterfaceId = "macos";
+
+/**
+ * Whether the interface supports a host proxy capability.
+ *
+ * The no-arg form `supportsHostProxy(id)` asks "is this interface a desktop
+ * host-proxy client?" — it returns `true` only for macOS and is the type
+ * predicate that narrows `InterfaceId` to `HostProxyInterfaceId`. It returns
+ * `false` for chrome-extension because chrome-extension only supports
+ * `host_browser`, and the no-arg form is the gate that legacy desktop-only
+ * call sites use (e.g. preactivating computer-use, restoring host proxies
+ * in the drain queue). Callers that want to check a single capability —
+ * for example, to decide whether to keep `hostBrowserProxy` available for
+ * chrome-extension — should pass the capability explicitly:
+ * `supportsHostProxy(id, "host_browser")`.
+ */
+export function supportsHostProxy(id: InterfaceId): id is HostProxyInterfaceId;
+export function supportsHostProxy(
+  id: InterfaceId,
+  capability: HostProxyCapability,
+): boolean;
+export function supportsHostProxy(
+  id: InterfaceId,
+  capability?: HostProxyCapability,
+): boolean {
+  // host_browser is excluded for macos because the proxy path requires a
+  // Chrome extension that isn't guaranteed to be attached; browser tools
+  // fall back to the local Playwright Chromium instead.
+  if (id === "macos") return capability !== "host_browser";
+  if (id === "chrome-extension" && capability === "host_browser") return true;
+  return false;
+}
+
 export interface TurnInterfaceContext {
   userMessageInterface: InterfaceId;
   assistantMessageInterface: InterfaceId;

package/src/cli/__tests__/run-assistant-command.ts

@@ -1,17 +1,32 @@
+export interface AssistantCommandResult {
+  stdout: string;
+  stderr: string;
+}
+
 /**
  * CLI test utility — run an assistant CLI command via the real program,
- * capturing stdout.
+ * capturing stdout and stderr.
+ *
+ * Returns both stdout and stderr. For backward compatibility, the function
+ * is also callable with just a string return (use `runAssistantCommand`).
  */
-export async function runAssistantCommand(...args: string[]): Promise<string> {
+export async function runAssistantCommandFull(
+  ...args: string[]
+): Promise<AssistantCommandResult> {
   const { buildCliProgram } = await import("../program.js");
-  const program = buildCliProgram();
+  const program = await buildCliProgram();
   program.exitOverride();
-  program.configureOutput({ writeErr: () => {}, writeOut: () => {} });
 
-  const chunks: string[] = [];
+  const stderrChunks: string[] = [];
+  program.configureOutput({
+    writeErr: (str: string) => stderrChunks.push(str),
+    writeOut: () => {},
+  });
+
+  const stdoutChunks: string[] = [];
   const originalWrite = process.stdout.write;
   process.stdout.write = ((chunk: string | Uint8Array) => {
-    chunks.push(
+    stdoutChunks.push(
       typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk),
     );
     return true;
@@ -25,5 +40,17 @@ export async function runAssistantCommand(...args: string[]): Promise<string> {
     process.stdout.write = originalWrite;
   }
 
-  return chunks.join("");
+  return {
+    stdout: stdoutChunks.join(""),
+    stderr: stderrChunks.join(""),
+  };
+}
+
+/**
+ * CLI test utility — run an assistant CLI command via the real program,
+ * capturing stdout (backward-compatible wrapper).
+ */
+export async function runAssistantCommand(...args: string[]): Promise<string> {
+  const result = await runAssistantCommandFull(...args);
+  return result.stdout;
 }

package/src/cli/__tests__/unknown-command.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "bun:test";
+
+import { runAssistantCommandFull } from "./run-assistant-command.js";
+
+describe("unknown command handling", () => {
+  it("reports an error for an unknown subcommand", async () => {
+    const { stderr } = await runAssistantCommandFull("invalid");
+
+    expect(stderr).toContain("unknown command 'invalid'");
+    expect(stderr).toContain("Run 'assistant --help'");
+  });
+
+  it("reports an error for an unknown subcommand with extra arguments", async () => {
+    const { stderr } = await runAssistantCommandFull("invalid", "something");
+
+    expect(stderr).toContain("unknown command 'invalid'");
+    expect(stderr).toContain("Run 'assistant --help'");
+  });
+
+  it("suggests a similar command when the input is close", async () => {
+    const { stderr } = await runAssistantCommandFull("confg");
+
+    expect(stderr).toContain("unknown command 'confg'");
+    expect(stderr).toContain("Did you mean 'config'");
+  });
+
+  it("does not suggest a command when the input is too far off", async () => {
+    const { stderr } = await runAssistantCommandFull("xyzzy");
+
+    expect(stderr).toContain("unknown command 'xyzzy'");
+    expect(stderr).not.toContain("Did you mean");
+  });
+});