pi-browser-harness 0.2.0 → 0.3.2

package/src/state.ts

@@ -1,77 +1,45 @@
 /**
  * Session persistence for pi-browser-harness.
  *
- * Persists daemon namespace, tab history, and preferences across
- * session reloads and branch navigation.
+ * Persists the daemon namespace and (when applicable) the remote browser ID
+ * across session reloads and branch navigation.
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 
-// ── Types ────────────────────────────────────────────────────────────────────
+export type BrowserState = {
+  readonly namespace: string;
+  readonly remoteBrowserId?: string;
+};
 
-export interface BrowserState {
-  /** Daemon namespace (BU_NAME) for this session */
-  namespace: string;
-  /** Recently active tab target IDs */
-  tabHistory: string[];
-  /** Cloud browser ID (for remote sessions) */
-  remoteBrowserId?: string;
-  /** Screenshot output directory */
-  screenshotDir: string;
-  /** Whether debug click overlay is enabled */
-  debugClicks: boolean;
-}
+export const defaultState = (namespace = "default"): BrowserState => ({ namespace });
 
-// ── Defaults ─────────────────────────────────────────────────────────────────
-
-export function defaultState(namespace = "default"): BrowserState {
-  return {
-    namespace,
-    tabHistory: [],
-    screenshotDir: "",
-    debugClicks: false,
-  };
-}
-
-// ── Persist ──────────────────────────────────────────────────────────────────
-
-export function persistState(pi: ExtensionAPI, state: BrowserState): void {
+export const persistState = (pi: ExtensionAPI, state: BrowserState): void => {
   pi.appendEntry<BrowserState>("browser-harness-state", state);
-}
-
-// ── Restore ──────────────────────────────────────────────────────────────────
+};
 
 /**
  * Find the last browser-harness-state entry in the current branch
  * and return the restored state, merged with defaults.
+ *
+ * If `currentNamespace` is supplied (e.g. from the --browser-namespace flag),
+ * it overrides whatever is in the persisted entry.
  */
-export function restoreState(ctx: ExtensionContext, currentNamespace?: string): BrowserState {
+export const restoreState = (ctx: ExtensionContext, currentNamespace?: string): BrowserState => {
   const branchEntries = ctx.sessionManager.getBranch();
-  const defaults = defaultState(currentNamespace);
-
-  // Walk branch from newest to oldest to find last persisted state
+  const fallback = defaultState(currentNamespace);
   for (let i = branchEntries.length - 1; i >= 0; i--) {
     const entry = branchEntries[i];
-    if (entry.type === "custom" && entry.customType === "browser-harness-state") {
+    if (entry?.type === "custom" && entry.customType === "browser-harness-state") {
       const data = entry.data as Partial<BrowserState> | undefined;
       if (data) {
-        // Merge persisted data onto defaults, but always keep the current
-        // namespace (which comes from the --browser-namespace flag or auto-gen).
-        return { ...defaults, ...data, namespace: currentNamespace || data.namespace || defaults.namespace };
+        return {
+          ...fallback,
+          ...data,
+          namespace: currentNamespace ?? data.namespace ?? fallback.namespace,
+        };
       }
     }
   }
-
-  return defaults;
-}
-
-// ── Merge helpers ────────────────────────────────────────────────────────────
-
-export function addToTabHistory(state: BrowserState, targetId: string): BrowserState {
-  const filtered = state.tabHistory.filter((id) => id !== targetId);
-  return { ...state, tabHistory: [targetId, ...filtered].slice(0, 20) };
-}
-
-export function setRemoteBrowser(state: BrowserState, browserId: string): BrowserState {
-  return { ...state, remoteBrowserId: browserId };
-}
+  return fallback;
+};

package/src/util/js-template.ts

@@ -0,0 +1,27 @@
+/**
+ * Build a JavaScript source string with safely-interpolated values.
+ * Every interpolated value is JSON.stringify'd, so strings, numbers,
+ * objects, and special characters all become valid JS literals.
+ *
+ * This is the ONLY supported way to interpolate untrusted values into
+ * evaluation source — never use raw template literals for JS that
+ * crosses the CDP boundary. The static parts of the template (the
+ * `strings` array) must remain hard-coded; only the `${...}` slots
+ * are sanitized.
+ *
+ * Values must be JSON-serializable: BigInt and Symbol throw at runtime;
+ * functions and undefined serialize to `undefined`/omitted, which yields
+ * a ReferenceError when evaluated. Pass strings, numbers, booleans,
+ * plain objects, or arrays.
+ */
+export const safeJs = (
+  strings: TemplateStringsArray,
+  ...values: ReadonlyArray<unknown>
+): string => {
+  let out = strings[0] ?? "";
+  for (let i = 0; i < values.length; i++) {
+    out += JSON.stringify(values[i]);
+    out += strings[i + 1] ?? "";
+  }
+  return out;
+};

package/src/util/keycodes.ts

@@ -0,0 +1,10 @@
+const VIRTUAL_KEY_CODES: Readonly<Record<string, number>> = {
+  Enter: 13, Tab: 9, Backspace: 8, Escape: 27, Delete: 46, " ": 32,
+  ArrowLeft: 37, ArrowUp: 38, ArrowRight: 39, ArrowDown: 40,
+  Home: 36, End: 35, PageUp: 33, PageDown: 34,
+};
+
+export const SPECIAL_KEYS: ReadonlyArray<string> = Object.keys(VIRTUAL_KEY_CODES);
+
+export const virtualKeyCode = (key: string): number =>
+  VIRTUAL_KEY_CODES[key] ?? (key.length === 1 ? key.charCodeAt(0) : 0);

package/src/util/mutex.ts

@@ -0,0 +1,25 @@
+/**
+ * Lightweight async mutex (~10 lines). Acquire returns a release function.
+ * When the mutex is free, acquire() resolves immediately. When held,
+ * callers are queued and execute serially in FIFO order.
+ */
+export type Mutex = {
+  acquire(): Promise<() => void>;
+};
+
+export const createMutex = (): Mutex => {
+  let queue = Promise.resolve<unknown>(undefined);
+
+  return {
+    async acquire(): Promise<() => void> {
+      let release = () => {};
+      const next = new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      const prev = queue;
+      queue = prev.then(() => next);
+      await prev;
+      return release;
+    },
+  };
+};

package/src/util/paths.ts

@@ -0,0 +1,21 @@
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const NAMESPACE_RE = /^[a-zA-Z0-9_-]+$/;
+
+const requireValidNamespace = (namespace: string): void => {
+  if (!NAMESPACE_RE.test(namespace)) {
+    throw new Error(`Invalid namespace (must match ${NAMESPACE_RE}): ${JSON.stringify(namespace)}`);
+  }
+};
+
+export const screenshotPath = (namespace: string, ext: "png" | "jpeg" = "png"): string => {
+  requireValidNamespace(namespace);
+  return join(tmpdir(), `pi-browser-screenshot-${namespace}-${randomUUID()}.${ext}`);
+};
+
+export const pdfPath = (namespace: string): string => {
+  requireValidNamespace(namespace);
+  return join(tmpdir(), `pi-browser-pdf-${namespace}-${randomUUID()}.pdf`);
+};

package/src/util/result.ts

@@ -0,0 +1,15 @@
+export type Result<T, E> =
+  | { readonly success: true; readonly data: T }
+  | { readonly success: false; readonly error: E };
+
+export const ok = <T>(data: T): Result<T, never> => ({ success: true, data });
+export const err = <E>(error: E): Result<never, E> => ({ success: false, error });
+
+export const map = <T, U, E>(r: Result<T, E>, f: (t: T) => U): Result<U, E> =>
+  r.success ? ok(f(r.data)) : r;
+
+export const andThen = <T, U, E>(r: Result<T, E>, f: (t: T) => Result<U, E>): Result<U, E> =>
+  r.success ? f(r.data) : r;
+
+export const mapErr = <T, E, F>(r: Result<T, E>, f: (e: E) => F): Result<T, F> =>
+  r.success ? r : err(f(r.error));

package/src/util/sharp-shim.ts

@@ -0,0 +1,49 @@
+// Typed minimal shim for the optional `sharp` dependency. Sharp is a heavy
+// native module not installed in every workspace; we import dynamically and
+// distinguish "missing" (no install) from "error" (installed but threw).
+//
+// We declare only the surface we use. The dynamic import returns `unknown`
+// at the boundary; the cast inside loadSharp() is the documented escape
+// hatch — every other consumer sees the typed SharpFactory.
+
+export type SharpInstance = {
+  metadata(): Promise<{ width?: number; height?: number }>;
+  composite(layers: ReadonlyArray<{ input: Buffer; top: number; left: number }>): SharpInstance;
+  resize(width: number, height: number, opts?: { fit?: "inside" }): SharpInstance;
+  toFile(path: string): Promise<unknown>;
+};
+
+export type SharpFactory = (input: string | Buffer) => SharpInstance;
+
+export type SharpLoad =
+  | { readonly kind: "ok"; readonly sharp: SharpFactory }
+  | { readonly kind: "missing" }
+  | { readonly kind: "error"; readonly message: string };
+
+export const loadSharp = async (): Promise<SharpLoad> => {
+  let mod: unknown;
+  try {
+    // sharp is an optional dependency; it may not be installed.
+    // @ts-ignore — optional peer dependency not required at compile time
+    mod = await import("sharp");
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (
+      msg.includes("Cannot find module") ||
+      msg.includes("MODULE_NOT_FOUND") ||
+      msg.includes("ERR_MODULE_NOT_FOUND")
+    ) {
+      return { kind: "missing" };
+    }
+    return { kind: "error", message: msg };
+  }
+  if (mod === null || mod === undefined) return { kind: "missing" };
+  // The CommonJS sharp module's default export IS the factory. ESM-wrapped
+  // sharp puts it on .default. Probe both.
+  const m = mod as { default?: unknown };
+  const candidate: unknown = typeof m.default === "function" ? m.default : mod;
+  if (typeof candidate !== "function") {
+    return { kind: "error", message: "sharp module did not expose a callable factory" };
+  }
+  return { kind: "ok", sharp: candidate as SharpFactory };
+};

package/src/util/time.ts

@@ -0,0 +1,29 @@
+export const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
+  new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new Error("aborted"));
+      return;
+    }
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(signal?.reason ?? new Error("aborted"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+
+export type Deadline = {
+  readonly remainingMs: () => number;
+  readonly expired: () => boolean;
+};
+
+export const deadline = (totalMs: number): Deadline => {
+  const end = Date.now() + totalMs;
+  return {
+    remainingMs: () => Math.max(0, end - Date.now()),
+    expired: () => Date.now() >= end,
+  };
+};

package/src/util/tool.ts

@@ -0,0 +1,193 @@
+import type { TSchema, Static } from "typebox";
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+  ToolDefinition,
+  ToolRenderResultOptions,
+} from "@mariozechner/pi-coding-agent";
+import type { Component } from "@mariozechner/pi-tui";
+import type { BrowserClient } from "../client";
+import type { Result } from "./result";
+
+export type ToolOk = {
+  readonly text: string;
+  readonly details?: Readonly<Record<string, unknown>>;
+};
+
+export type ToolErrKind =
+  | "not_connected"
+  | "cdp_error"
+  | "timeout"
+  | "invalid_state"
+  | "io_error"
+  | "internal";
+
+export type ToolErr = {
+  readonly kind: ToolErrKind;
+  readonly message: string;
+  readonly details?: Readonly<Record<string, unknown>>;
+};
+
+export type HandlerContext = {
+  readonly client: BrowserClient;
+  readonly signal: AbortSignal | undefined;
+  readonly onUpdate: (update: ToolOk) => void;
+  readonly extensionCtx: ExtensionContext;
+};
+
+export type ToolHandler<S extends TSchema> = (
+  args: Static<S>,
+  ctx: HandlerContext,
+) => Promise<Result<ToolOk, ToolErr>>;
+
+export type BrowserToolDefinition<S extends TSchema> = {
+  readonly name: string;
+  readonly label: string;
+  readonly description: string;
+  readonly promptSnippet: string;
+  readonly promptGuidelines: ReadonlyArray<string>;
+  readonly parameters: S;
+  readonly handler: ToolHandler<S>;
+  readonly renderCall?: (args: Static<S>, theme: Theme) => Component;
+  readonly renderResult?: (result: AgentToolResult<unknown>, expanded: boolean, theme: Theme) => Component;
+  /** If true, the tool acquires the client's mutation mutex before executing.
+   *  This ensures that two serialized tools never run concurrently,
+   *  preventing race conditions on shared CDP session/page state. */
+  readonly serialized?: boolean;
+  readonly ensureAlive?: boolean;
+};
+
+// Type-erased entry for the registry's heterogeneous TOOLS array.
+// renderCall accepts `never` so any concrete args type satisfies it via
+// function-parameter contravariance (a handler that takes SpecificT is
+// assignable to one that takes never, because never is a subtype of everything).
+export type AnyBrowserToolDefinition = Omit<BrowserToolDefinition<TSchema>, "renderCall" | "renderResult"> & {
+  readonly renderCall?: (args: never, theme: Theme) => Component;
+  readonly renderResult?: (result: AgentToolResult<unknown>, expanded: boolean, theme: Theme) => Component;
+};
+
+export const defineBrowserTool = <S extends TSchema>(
+  def: BrowserToolDefinition<S>,
+): BrowserToolDefinition<S> => def;
+
+type OkDetails = { readonly ok: true } & Readonly<Record<string, unknown>>;
+type ErrDetails = { readonly ok: false; readonly kind: ToolErrKind; readonly message: string } & Readonly<Record<string, unknown>>;
+
+const toToolResult = (
+  r: Result<ToolOk, ToolErr>,
+  toolName: string,
+): AgentToolResult<OkDetails | ErrDetails> => {
+  if (r.success) {
+    const details: OkDetails = { ok: true, ...(r.data.details ?? {}) };
+    return {
+      content: [{ type: "text", text: r.data.text }],
+      details,
+    };
+  }
+  const details: ErrDetails = {
+    ok: false,
+    kind: r.error.kind,
+    message: r.error.message,
+    ...(r.error.details ?? {}),
+  };
+  return {
+    // isError is an extension the pi-coding-agent runtime picks up from the result object;
+    // AgentToolResult<T> itself doesn't declare it but the runtime reads it via duck-typing.
+    // We cast through unknown to avoid widening the return type.
+    ...(({ isError: true }) as unknown as object),
+    content: [{ type: "text", text: `${toolName} failed (${r.error.kind}): ${r.error.message}` }],
+    details,
+  };
+};
+
+export const registerBrowserTool = (
+  pi: ExtensionAPI,
+  client: BrowserClient,
+  def: AnyBrowserToolDefinition,
+): void => {
+  // AnyBrowserToolDefinition is type-erased; we recover the schema-typed surface
+  // by casting def to the generic form. The cast is safe because defineBrowserTool
+  // ensures the handler, parameters, and renderCall were all created with the same S.
+  type S = TSchema;
+  const td: ToolDefinition<S> = {
+    name: def.name,
+    label: def.label,
+    description: def.description,
+    promptSnippet: def.promptSnippet,
+    promptGuidelines: [...def.promptGuidelines],
+    parameters: def.parameters,
+    ...(def.renderCall
+      ? {
+          renderCall: (args: Static<S>, theme: Theme, _ctx: Parameters<NonNullable<ToolDefinition<S>["renderCall"]>>[2]) =>
+            // Non-null assertion safe: this branch only runs when renderCall was provided.
+            // Cast from never->Component to unknown->Component: safe because at runtime
+            // args is always the concrete Static<S> value the tool was defined with.
+            (def.renderCall as (args: unknown, theme: Theme) => Component)(args, theme),
+        }
+      : {}),
+    ...(def.renderResult
+      ? {
+          renderResult: (
+            result: AgentToolResult<unknown>,
+            options: ToolRenderResultOptions,
+            theme: Theme,
+            _ctx: Parameters<NonNullable<ToolDefinition<S>["renderResult"]>>[3],
+          ) =>
+            // Non-null assertion safe: this branch only runs when renderResult was provided.
+            def.renderResult!(result, options.expanded ?? false, theme),
+        }
+      : {}),
+    async execute(_toolCallId, args, signal, onUpdate, extensionCtx) {
+      if (def.ensureAlive !== false) {
+        const alive = await client.ensureAlive();
+        if (!alive.success) {
+          return toToolResult(
+            { success: false, error: { kind: "not_connected", message: alive.error.message } },
+            def.name,
+          );
+        }
+      }
+      // Serialized tools acquire the client's mutation mutex so that only one
+      // mutation tool runs at a time. Observation tools skip this and run freely
+      // in parallel. AbortSignal is checked after acquiring the lock so that a
+      // cancelled task doesn't hold the mutex forever.
+      let release: (() => void) | undefined;
+      if (def.serialized) {
+        const acquire = await client.mutationMutex().acquire();
+        release = acquire;
+        if (signal?.aborted) {
+          release();
+          return toToolResult(
+            { success: false, error: { kind: "invalid_state", message: "Tool execution aborted before entering serialized lane" } },
+            def.name,
+          );
+        }
+      }
+      try {
+        const result = await def.handler(args, {
+          client,
+          signal,
+          onUpdate: (u) => {
+            if (onUpdate) {
+              // AgentToolUpdateCallback expects AgentToolResult<TDetails>; we use unknown for TDetails.
+              const update: AgentToolResult<OkDetails> = {
+                content: [{ type: "text", text: u.text }],
+                details: { ok: true, ...(u.details ?? {}) },
+              };
+              // Cast needed: onUpdate is AgentToolUpdateCallback<unknown> (generic TDetails).
+              (onUpdate as AgentToolUpdateCallback<OkDetails>)(update);
+            }
+          },
+          extensionCtx,
+        });
+        return toToolResult(result, def.name);
+      } finally {
+        release?.();
+      }
+    },
+  };
+  pi.registerTool(td);
+};

package/src/util/truncate.ts

@@ -0,0 +1,35 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+  truncateHead,
+  withFileMutationQueue,
+} from "@mariozechner/pi-coding-agent";
+
+const tempDirs: string[] = [];
+
+export const cleanupTempDirs = async (): Promise<void> => {
+  const dirs = tempDirs.splice(0);
+  await Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true }).catch(() => {})));
+};
+
+export type TruncatedOutput = {
+  readonly text: string;
+  readonly fullOutputPath?: string;
+  readonly wasTruncated: boolean;
+};
+
+export const applyTruncation = async (output: string, prefix: string): Promise<TruncatedOutput> => {
+  const t = truncateHead(output, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES });
+  if (!t.truncated) return { text: t.content, wasTruncated: false };
+  const dir = await mkdtemp(join(tmpdir(), `pi-bh-${prefix}-`));
+  tempDirs.push(dir);
+  const file = join(dir, "output.txt");
+  await withFileMutationQueue(file, async () => { await writeFile(file, output, "utf8"); });
+  const omitted = t.totalBytes - t.outputBytes;
+  const text = `${t.content}\n\n[Output truncated: ${t.outputLines} of ${t.totalLines} lines (${formatSize(t.outputBytes)} of ${formatSize(t.totalBytes)}). ${formatSize(omitted)} omitted. Full output: ${file}]`;
+  return { text, fullOutputPath: file, wasTruncated: true };
+};

package/tsconfig.json

@@ -4,9 +4,18 @@
     "module": "ESNext",
     "moduleResolution": "bundler",
     "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "forceConsistentCasingInFileNames": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
     "outDir": "./dist",
     "rootDir": "./src",
     "declaration": true,