pi-browser-harness 0.2.0 → 0.3.1

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