pi-feats 0.1.2 → 0.1.4

package/extensions/browser-harness/steel.ts

@@ -0,0 +1,215 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { cdpError, type CdpError } from "./cdp/errors";
+import { err, ok, type Result } from "./util/result";
+
+const STATE_VERSION = 1;
+
+type SteelState = {
+  readonly version: number;
+  readonly piProfile: string;
+  readonly sessionContext?: Record<string, unknown>;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+};
+
+type SteelSession = {
+  readonly id: string;
+  readonly websocketUrl: string;
+  readonly debugUrl: string;
+  readonly debuggerUrl: string;
+  readonly sessionViewerUrl: string;
+};
+
+type SteelConfig = { readonly apiUrl: string; readonly apiKey?: string };
+
+const agentDir = (): string => process.env["PI_CODING_AGENT_DIR"]?.trim() || join(homedir(), ".pi", "agent");
+const activeProfile = (): string => process.env["PI_ACTIVE_PROFILE"]?.trim() || "default";
+const statePath = (): string => join(agentDir(), "steel.json");
+
+const config = (): SteelConfig => ({
+  apiUrl: (process.env["STEEL_API_URL"]?.trim() || "http://127.0.0.1:3000").replace(/\/$/, ""),
+  ...(process.env["STEEL_API_KEY"]?.trim() ? { apiKey: process.env["STEEL_API_KEY"]?.trim() } : {}),
+});
+
+const headers = (value: SteelConfig): HeadersInit => ({
+  "content-type": "application/json",
+  ...(value.apiKey ? { "steel-api-key": value.apiKey } : {}),
+});
+
+const loadState = async (): Promise<SteelState | undefined> => {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(statePath(), "utf8"));
+    if (!parsed || typeof parsed !== "object") return undefined;
+    const value = parsed as Partial<SteelState>;
+    if (value.version !== STATE_VERSION || value.piProfile !== activeProfile()) return undefined;
+    return value as SteelState;
+  } catch { return undefined; }
+};
+
+const saveState = async (sessionContext: Record<string, unknown> | undefined): Promise<void> => {
+  const path = statePath();
+  const now = new Date().toISOString();
+  const existing = await loadState();
+  const state: SteelState = {
+    version: STATE_VERSION,
+    piProfile: activeProfile(),
+    ...(sessionContext ? { sessionContext } : {}),
+    createdAt: existing?.createdAt ?? now,
+    updatedAt: now,
+  };
+  await mkdir(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+  await rename(temporary, path);
+};
+
+const publicSessionUrl = (url: string, apiUrl: string, websocket = false): Result<string, CdpError> => {
+  try {
+    const endpoint = new URL(url);
+    const api = new URL(apiUrl);
+    // Self-hosted Steel can return a container hostname. The API origin is the
+    // endpoint reachable by both Pi and the supervising human.
+    endpoint.hostname = api.hostname;
+    endpoint.port = api.port;
+    endpoint.protocol = websocket ? (api.protocol === "https:" ? "wss:" : "ws:") : api.protocol;
+    return ok(endpoint.toString());
+  } catch {
+    return err(cdpError("invalid_response", "Steel returned an invalid session URL"));
+  }
+};
+
+const interactiveViewerUrl = (url: string): string => {
+  const viewer = new URL(url);
+  viewer.searchParams.set("interactive", "true");
+  return viewer.toString();
+};
+
+const assertNoLiveSession = async (value: SteelConfig): Promise<Result<void, CdpError>> => {
+  try {
+    const response = await fetch(`${value.apiUrl}/v1/sessions`, { headers: headers(value) });
+    const raw: unknown = await response.json();
+    const sessions = raw && typeof raw === "object" ? (raw as { sessions?: unknown }).sessions : undefined;
+    if (Array.isArray(sessions) && sessions.some((session) => session && typeof session === "object" && (session as { status?: unknown }).status === "live")) {
+      return err(cdpError("remote_error", "Steel Browser v0.5.x supports one active session. Release the current browser session before using another Pi Profile."));
+    }
+    return ok(undefined);
+  } catch (error) {
+    return err(cdpError("transport_closed", `Steel API is unavailable: ${error instanceof Error ? error.message : String(error)}`));
+  }
+};
+
+const createSession = async (value: SteelConfig, sessionContext?: Record<string, unknown>): Promise<Result<SteelSession, CdpError>> => {
+  try {
+    const response = await fetch(`${value.apiUrl}/v1/sessions`, {
+      method: "POST",
+      headers: headers(value),
+      body: JSON.stringify({ ...(sessionContext ? { sessionContext } : {}) }),
+    });
+    const raw: unknown = await response.json().catch(() => undefined);
+    if (!response.ok || !raw || typeof raw !== "object") return err(cdpError("remote_error", `Steel session creation failed (${response.status})`));
+    const data = raw as Partial<SteelSession>;
+    if (typeof data.id !== "string" || typeof data.websocketUrl !== "string" || typeof data.debugUrl !== "string" || typeof data.debuggerUrl !== "string" || typeof data.sessionViewerUrl !== "string") {
+      return err(cdpError("invalid_response", "Steel did not return the session and viewer URLs"));
+    }
+    return ok({
+      id: data.id,
+      websocketUrl: data.websocketUrl,
+      debugUrl: data.debugUrl,
+      debuggerUrl: data.debuggerUrl,
+      sessionViewerUrl: data.sessionViewerUrl,
+    });
+  } catch (error) {
+    return err(cdpError("transport_closed", `Steel API is unavailable: ${error instanceof Error ? error.message : String(error)}`));
+  }
+};
+
+const getSessionContext = async (value: SteelConfig, sessionId: string): Promise<Record<string, unknown> | undefined> => {
+  try {
+    const response = await fetch(`${value.apiUrl}/v1/sessions/${encodeURIComponent(sessionId)}/context`, { headers: headers(value) });
+    const data: unknown = await response.json();
+    return data && typeof data === "object" && !Array.isArray(data) ? data as Record<string, unknown> : undefined;
+  } catch { return undefined; }
+};
+
+export type SteelRuntime = {
+  endpoint(): Promise<Result<string, CdpError>>;
+  status(): {
+    readonly sessionId?: string;
+    readonly viewerUrl?: string;
+    readonly debuggerUrl?: string;
+    readonly sessionViewerUrl?: string;
+    readonly hasPersistedContext: boolean;
+  };
+  release(): Promise<void>;
+};
+
+/**
+ * Steel Browser v0.5.x has a session API, not a Profiles API. The active Pi
+ * Profile is therefore represented by a profile-scoped persisted SessionContext
+ * in steel.json. Session lifecycle remains exclusively API-driven; CDP is used
+ * only after the API returns the session websocket endpoint.
+ */
+export const createSteelRuntime = (): SteelRuntime => {
+  let sessionId: string | undefined;
+  let endpointUrl: string | undefined;
+  let viewerUrl: string | undefined;
+  let debuggerUrl: string | undefined;
+  let sessionViewerUrl: string | undefined;
+  let persistedContext = false;
+
+  const endpoint = async (): Promise<Result<string, CdpError>> => {
+    if (endpointUrl) return ok(endpointUrl);
+    const settings = config();
+    const available = await assertNoLiveSession(settings);
+    if (!available.success) return available;
+    const state = await loadState();
+    persistedContext = state?.sessionContext !== undefined;
+    const session = await createSession(settings, state?.sessionContext);
+    if (!session.success) return session;
+    const resolved = publicSessionUrl(session.data.websocketUrl, settings.apiUrl, true);
+    const viewer = publicSessionUrl(session.data.debugUrl, settings.apiUrl);
+    const debuggerEndpoint = publicSessionUrl(session.data.debuggerUrl, settings.apiUrl);
+    const viewerSession = publicSessionUrl(session.data.sessionViewerUrl, settings.apiUrl);
+    if (!resolved.success) return resolved;
+    if (!viewer.success || !debuggerEndpoint.success || !viewerSession.success) {
+      return err(cdpError("invalid_response", "Steel returned invalid viewer URLs"));
+    }
+    sessionId = session.data.id;
+    endpointUrl = resolved.data;
+    viewerUrl = interactiveViewerUrl(viewer.data);
+    debuggerUrl = debuggerEndpoint.data;
+    sessionViewerUrl = viewerSession.data;
+    return resolved;
+  };
+
+  return {
+    endpoint,
+    status: () => ({
+      ...(sessionId ? { sessionId, viewerUrl, debuggerUrl, sessionViewerUrl } : {}),
+      hasPersistedContext: persistedContext,
+    }),
+    async release() {
+      if (!sessionId) return;
+      const settings = config();
+      const id = sessionId;
+      const context = await getSessionContext(settings, id);
+      if (context) {
+        await saveState(context);
+        persistedContext = true;
+      }
+      sessionId = undefined;
+      endpointUrl = undefined;
+      viewerUrl = undefined;
+      debuggerUrl = undefined;
+      sessionViewerUrl = undefined;
+      try {
+        await fetch(`${settings.apiUrl}/v1/sessions/${encodeURIComponent(id)}/release`, {
+          method: "POST",
+          headers: headers(settings),
+        });
+      } catch {}
+    },
+  };
+};

package/extensions/browser-harness/util/debug.ts

@@ -0,0 +1,8 @@
+let flagEnabled = false;
+
+export const setDebugClicks = (on: boolean): void => {
+  flagEnabled = on;
+};
+
+export const debugClicksEnabled = (env: NodeJS.ProcessEnv = process.env): boolean =>
+  flagEnabled || Boolean(env["BH_DEBUG_CLICKS"]);

package/extensions/browser-harness/util/guards.ts

@@ -0,0 +1,30 @@
+export const isRecord = (v: unknown): v is Readonly<Record<string, unknown>> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+export const asRecord = (v: unknown): Readonly<Record<string, unknown>> | undefined =>
+  isRecord(v) ? v : undefined;
+
+export const asString = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
+
+export const asNumber = (v: unknown): number | undefined => (typeof v === "number" ? v : undefined);
+
+export const asBoolean = (v: unknown): boolean | undefined => (typeof v === "boolean" ? v : undefined);
+
+export const asArrayOf = <T>(
+  v: unknown,
+  item: (x: unknown) => T | undefined,
+): ReadonlyArray<T> | undefined => {
+  if (!Array.isArray(v)) return undefined;
+  const out: T[] = [];
+  for (const x of v) {
+    const parsed = item(x);
+    if (parsed === undefined) return undefined;
+    out.push(parsed);
+  }
+  return out;
+};
+
+export const errnoCode = (e: unknown): string | undefined => {
+  if (!(e instanceof Error) || !("code" in e)) return undefined;
+  return asString(e.code);
+};

package/extensions/browser-harness/util/js-template.ts

@@ -0,0 +1,12 @@
+// The ONLY supported way to interpolate untrusted values into evaluation source — never use raw template literals for JS crossing the CDP boundary.
+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/extensions/browser-harness/util/mutex.ts

@@ -0,0 +1,20 @@
+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/extensions/browser-harness/util/paths.ts

@@ -0,0 +1,31 @@
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+// `relative` rather than a string prefix: it is separator-agnostic and carries each platform's
+// own case rules, so a Windows path is not rejected for its backslashes or its drive-letter case.
+export const isPathWithin = (root: string, target: string): boolean => {
+  const absRoot = resolve(root);
+  const absTarget = resolve(target);
+  if (absTarget === absRoot) return true;
+  const rel = relative(absRoot, absTarget);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+};
+
+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/extensions/browser-harness/util/result.ts

@@ -0,0 +1,9 @@
+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;

package/extensions/browser-harness/util/sharp-shim.ts

@@ -0,0 +1,42 @@
+// `sharp` is an optional dependency not installed in every workspace, so the import must stay dynamic and unresolvable to tsc.
+
+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 };
+
+const SHARP_SPECIFIER: string = "sharp";
+
+const MISSING_MODULE_MARKERS: ReadonlyArray<string> = [
+  "Cannot find module",
+  "MODULE_NOT_FOUND",
+  "ERR_MODULE_NOT_FOUND",
+];
+
+export const loadSharp = async (): Promise<SharpLoad> => {
+  let mod: unknown;
+  try {
+    mod = await import(SHARP_SPECIFIER);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (MISSING_MODULE_MARKERS.some((marker) => msg.includes(marker))) 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.
+  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/extensions/browser-harness/util/tool.ts

@@ -0,0 +1,185 @@
+import type { TSchema, Static } from "typebox";
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+  ExtensionContext,
+  Theme,
+  ToolDefinition,
+  ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/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 concurrency: "serialized" | "parallel";
+  readonly ensureAlive?: boolean;
+};
+
+// renderCall accepts `never` so any concrete args type satisfies it via function-parameter contravariance.
+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>>;
+
+type ErrorFlagged<D> = AgentToolResult<D> & { readonly isError?: boolean };
+
+const toToolResult = (
+  r: Result<ToolOk, ToolErr>,
+  toolName: string,
+): ErrorFlagged<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: true,
+    content: [{ type: "text", text: `${toolName} failed (${r.error.kind}): ${r.error.message}` }],
+    details,
+  };
+};
+
+export const registerBrowserTool = (
+  pi: ExtensionAPI,
+  client: BrowserClient,
+  def: AnyBrowserToolDefinition,
+): void => {
+  type S = TSchema;
+  const defRenderCall = def.renderCall;
+  const defRenderResult = def.renderResult;
+  const td: ToolDefinition<S> = {
+    name: def.name,
+    label: def.label,
+    description: def.description,
+    promptSnippet: def.promptSnippet,
+    promptGuidelines: [...def.promptGuidelines],
+    parameters: def.parameters,
+    ...(defRenderCall
+      ? {
+          renderCall: (args: Static<S>, theme: Theme, _ctx: Parameters<NonNullable<ToolDefinition<S>["renderCall"]>>[2]) =>
+            // Sanctioned cast: at runtime args is always the concrete Static<S> value the tool was defined with.
+            (defRenderCall as (args: unknown, theme: Theme) => Component)(args, theme),
+        }
+      : {}),
+    ...(defRenderResult
+      ? {
+          renderResult: (
+            result: AgentToolResult<unknown>,
+            options: ToolRenderResultOptions,
+            theme: Theme,
+            _ctx: Parameters<NonNullable<ToolDefinition<S>["renderResult"]>>[3],
+          ) => defRenderResult(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,
+          );
+        }
+        // A fresh CDP attachment starts on Steel's default target. Never let a
+        // browser tool inspect or mutate that unowned target.
+        if (!client.current() || !client.owns(client.current()!.targetId)) {
+          const tab = await client.newTab("about:blank");
+          if (!tab.success) {
+            return toToolResult(
+              { success: false, error: { kind: "not_connected", message: tab.error.message } },
+              def.name,
+            );
+          }
+        }
+      }
+      let release: (() => void) | undefined;
+      if (def.concurrency !== "parallel") {
+        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) {
+              const update: AgentToolResult<OkDetails> = {
+                content: [{ type: "text", text: u.text }],
+                details: { ok: true, ...(u.details ?? {}) },
+              };
+              onUpdate(update);
+            }
+          },
+          extensionCtx,
+        });
+        return toToolResult(result, def.name);
+      } finally {
+        release?.();
+      }
+    },
+  };
+  pi.registerTool(td);
+};

package/extensions/browser-harness/util/truncate.ts

@@ -0,0 +1,41 @@
+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 "@earendil-works/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 };
+};
+
+export const formatBytes = (n: number): string => {
+  if (n >= 1_048_576) return `${(n / 1_048_576).toFixed(1)} MB`;
+  if (n >= 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${n} B`;
+};