pi-feats 0.1.2 → 0.1.4

package/extensions/browser-harness/profile/list.ts

@@ -0,0 +1,131 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { parseJson } from "../schemas/parse";
+
+export type BrowserProfile = {
+  readonly dir: string;
+  readonly name: string;
+  readonly email?: string;
+  readonly label: string;
+  readonly lastUsed: boolean;
+};
+
+const NON_PROFILE_DIRS: ReadonlySet<string> = new Set([
+  "System Profile",
+  "Guest Profile",
+]);
+
+export const formatProfileLabel = (name: string, email: string | undefined, dir: string): string =>
+  `${name} (${email && email.length > 0 ? email : dir})`;
+
+const JsonObject = Type.Record(Type.String(), Type.Unknown());
+
+const jsonObjectValidator = Compile(JsonObject);
+
+const readJsonFile = async (path: string): Promise<Record<string, unknown> | null> => {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+  const parsed = parseJson(raw, jsonObjectValidator);
+  return parsed.success ? parsed.data : null;
+};
+
+const asRecord = (v: unknown): Record<string, unknown> | null =>
+  jsonObjectValidator.Check(v) ? v : null;
+
+const asString = (v: unknown): string | undefined =>
+  typeof v === "string" && v.length > 0 ? v : undefined;
+
+const orderDirs = (dirs: ReadonlyArray<string>, order: ReadonlyArray<string>): ReadonlyArray<string> => {
+  const known = order.filter((d) => dirs.includes(d));
+  const rest = dirs.filter((d) => !known.includes(d)).sort((a, b) => a.localeCompare(b));
+  return [...known, ...rest];
+};
+
+const buildProfile = (
+  dir: string,
+  name: string | undefined,
+  email: string | undefined,
+  lastUsed: boolean,
+): BrowserProfile => {
+  const displayName = name ?? dir;
+  return {
+    dir,
+    name: displayName,
+    ...(email !== undefined ? { email } : {}),
+    label: formatProfileLabel(displayName, email, dir),
+    lastUsed,
+  };
+};
+
+const listFromLocalState = async (userDataDir: string): Promise<ReadonlyArray<BrowserProfile>> => {
+  const localState = await readJsonFile(join(userDataDir, "Local State"));
+  if (!localState) return [];
+  const profileNode = asRecord(localState["profile"]);
+  if (!profileNode) return [];
+  const infoCache = asRecord(profileNode["info_cache"]);
+  if (!infoCache) return [];
+
+  const rawOrder = profileNode["profiles_order"];
+  const order = Array.isArray(rawOrder) ? rawOrder.filter((v): v is string => typeof v === "string") : [];
+  const lastUsed = asString(profileNode["last_used"]);
+
+  const entries: Array<{ dir: string; entry: Record<string, unknown> }> = [];
+  for (const [dir, value] of Object.entries(infoCache)) {
+    if (NON_PROFILE_DIRS.has(dir)) continue;
+    const entry = asRecord(value);
+    if (!entry) continue;
+    // Ephemeral (guest-like) profiles vanish when their window closes, so they can never be a durable pin.
+    if (entry["is_ephemeral"] === true) continue;
+    entries.push({ dir, entry });
+  }
+
+  const ordered = orderDirs(entries.map((e) => e.dir), order);
+  const byDir = new Map(entries.map((e) => [e.dir, e.entry]));
+
+  return ordered.flatMap((dir) => {
+    const entry = byDir.get(dir);
+    if (!entry) return [];
+    const name = asString(entry["name"]) ?? asString(entry["gaia_name"]);
+    const email = asString(entry["user_name"]);
+    return [buildProfile(dir, name, email, dir === lastUsed)];
+  });
+};
+
+const listFromPreferencesScan = async (userDataDir: string): Promise<ReadonlyArray<BrowserProfile>> => {
+  let dirents;
+  try {
+    dirents = await readdir(userDataDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const candidates = dirents
+    .filter((d) => d.isDirectory() && !NON_PROFILE_DIRS.has(d.name))
+    .map((d) => d.name)
+    .sort((a, b) => a.localeCompare(b));
+
+  const profiles: BrowserProfile[] = [];
+  for (const dir of candidates) {
+    const prefs = await readJsonFile(join(userDataDir, dir, "Preferences"));
+    if (!prefs) continue;
+    const profileNode = asRecord(prefs["profile"]);
+    const name = profileNode ? asString(profileNode["name"]) : undefined;
+    const accounts = prefs["account_info"];
+    const firstAccount = Array.isArray(accounts) ? asRecord(accounts[0]) : null;
+    const email = firstAccount ? asString(firstAccount["email"]) : undefined;
+    profiles.push(buildProfile(dir, name, email, false));
+  }
+  return profiles;
+};
+
+export const listProfiles = async (userDataDir: string): Promise<ReadonlyArray<BrowserProfile>> => {
+  const fromLocalState = await listFromLocalState(userDataDir);
+  if (fromLocalState.length > 0) return fromLocalState;
+  return listFromPreferencesScan(userDataDir);
+};

package/extensions/browser-harness/profile/paths.ts

@@ -0,0 +1,103 @@
+// pi's `getAgentDir()` is replicated rather than imported: a runtime import of the host package does not resolve for extensions installed via `pi install npm:...`.
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const ENV_AGENT_DIR = "PI_CODING_AGENT_DIR";
+
+// Deliberately mirrors pi's expandTildePath (never `~\…`) rather than improving on it, or the pin lands somewhere pi does not look.
+const expandTildePiCompatible = (path: string): string => {
+  if (path === "~") return homedir();
+  if (path.startsWith("~/")) return homedir() + path.slice(1);
+  return path;
+};
+
+const expandTildeLenient = (path: string): string => {
+  if (path === "~") return homedir();
+  if (path.startsWith("~/") || path.startsWith("~\\")) return join(homedir(), path.slice(2));
+  return path;
+};
+
+export const agentDir = (): string => {
+  const fromEnv = process.env[ENV_AGENT_DIR];
+  if (fromEnv) return expandTildePiCompatible(fromEnv);
+  return join(homedir(), ".pi", "agent");
+};
+
+export const pinFilePath = (): string => join(agentDir(), "browser-harness.json");
+
+const localAppData = (): string => process.env["LOCALAPPDATA"] ?? join(homedir(), "AppData", "Local");
+
+export const userDataDirCandidates = (): ReadonlyArray<string> => {
+  const home = homedir();
+  const dirs: string[] = [];
+
+  const envOverride = process.env["CHROME_USER_DATA_DIR"];
+  if (envOverride) dirs.push(expandTildeLenient(envOverride));
+
+  if (process.platform === "darwin") {
+    const support = join(home, "Library", "Application Support");
+    dirs.push(
+      join(support, "Google/Chrome"),
+      join(support, "Google/Chrome Beta"),
+      join(support, "Google/Chrome Dev"),
+      join(support, "Google/Chrome Canary"),
+      join(support, "Chromium"),
+      join(support, "BraveSoftware/Brave-Browser"),
+      join(support, "BraveSoftware/Brave-Browser-Beta"),
+      join(support, "BraveSoftware/Brave-Browser-Nightly"),
+      join(support, "BraveSoftware/Brave-Browser-Dev"),
+      join(support, "Microsoft Edge"),
+      join(support, "Microsoft Edge Beta"),
+      join(support, "Microsoft Edge Dev"),
+      join(support, "Microsoft Edge Canary"),
+    );
+  } else if (process.platform === "win32") {
+    const lad = localAppData();
+    dirs.push(
+      join(lad, "Google/Chrome/User Data"),
+      join(lad, "Google/Chrome Beta/User Data"),
+      join(lad, "Google/Chrome Dev/User Data"),
+      join(lad, "Google/Chrome SxS/User Data"),
+      join(lad, "Chromium/User Data"),
+      join(lad, "BraveSoftware/Brave-Browser/User Data"),
+      join(lad, "BraveSoftware/Brave-Browser-Beta/User Data"),
+      join(lad, "Microsoft/Edge/User Data"),
+      join(lad, "Microsoft/Edge Beta/User Data"),
+      join(lad, "Microsoft/Edge Dev/User Data"),
+      join(lad, "Microsoft/Edge SxS/User Data"),
+    );
+  } else {
+    dirs.push(
+      join(home, ".config/google-chrome"),
+      join(home, ".config/google-chrome-beta"),
+      join(home, ".config/google-chrome-unstable"),
+      join(home, ".config/chromium"),
+      join(home, ".config/chromium-browser"),
+      join(home, ".config/BraveSoftware/Brave-Browser"),
+      join(home, ".config/BraveSoftware/Brave-Browser-Beta"),
+      join(home, ".config/BraveSoftware/Brave-Browser-Nightly"),
+      join(home, ".config/microsoft-edge"),
+      join(home, ".config/microsoft-edge-beta"),
+      join(home, ".config/microsoft-edge-dev"),
+      join(home, "snap/chromium/common/chromium"),
+      join(home, ".var/app/org.chromium.Chromium/config/chromium"),
+      join(home, ".var/app/com.google.Chrome/config/google-chrome"),
+      join(home, ".var/app/com.brave.Browser/config/BraveSoftware/Brave-Browser"),
+      join(home, ".var/app/com.microsoft.Edge/config/microsoft-edge"),
+    );
+  }
+
+  return Array.from(new Set(dirs));
+};
+
+export const browserNameForUserDataDir = (userDataDir: string): string => {
+  const p = userDataDir.replace(/\\/g, "/");
+  const has = (needle: string): boolean => p.toLowerCase().includes(needle);
+  if (has("brave")) return "Brave";
+  if (has("edge")) return "Edge";
+  if (has("chromium")) return "Chromium";
+  if (has("chrome")) return "Chrome";
+  const last = p.split("/").filter(Boolean).pop();
+  return last ?? userDataDir;
+};

package/extensions/browser-harness/profile/store.ts

@@ -0,0 +1,84 @@
+// A `browserContextId` is deliberately NOT persisted: Chrome mints fresh context ids per browser run, so a stored one could point into the wrong profile.
+
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import { Type } from "typebox";
+import { Compile } from "typebox/compile";
+import { parseJson } from "../schemas/parse";
+import { type Result, err, ok } from "../util/result";
+import { pinFilePath } from "./paths";
+
+export type ProfilePin = {
+  readonly userDataDir: string;
+  readonly profileDir: string;
+  readonly label: string;
+  readonly savedAt: string;
+};
+
+type PinFile = {
+  readonly version: 1;
+  readonly profile: ProfilePin | null;
+};
+
+const CURRENT_VERSION = 1;
+
+const PinFileSchema = Type.Object(
+  {
+    version: Type.Literal(CURRENT_VERSION),
+    profile: Type.Union([
+      Type.Object(
+        {
+          userDataDir: Type.String({ minLength: 1 }),
+          profileDir: Type.String({ minLength: 1 }),
+          label: Type.Optional(Type.Unknown()),
+          savedAt: Type.Optional(Type.Unknown()),
+        },
+        { additionalProperties: true },
+      ),
+      Type.Null(),
+    ]),
+  },
+  { additionalProperties: true },
+);
+
+const pinFileValidator = Compile(PinFileSchema);
+
+export const readPin = async (): Promise<ProfilePin | null> => {
+  let raw: string;
+  try {
+    raw = await readFile(pinFilePath(), "utf8");
+  } catch {
+    return null;
+  }
+  const parsed = parseJson(raw, pinFileValidator);
+  if (!parsed.success) return null;
+  const profile = parsed.data.profile;
+  if (profile === null) return null;
+  const { userDataDir, profileDir, label, savedAt } = profile;
+  return {
+    userDataDir,
+    profileDir,
+    label: typeof label === "string" && label.length > 0 ? label : profileDir,
+    savedAt: typeof savedAt === "string" ? savedAt : "",
+  };
+};
+
+const writePinFile = async (profile: ProfilePin | null): Promise<Result<void, string>> => {
+  const target = pinFilePath();
+  const tmp = `${target}.${randomUUID()}.tmp`;
+  const payload: PinFile = { version: CURRENT_VERSION, profile };
+  try {
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(tmp, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    await rename(tmp, target);
+    return ok(undefined);
+  } catch (e) {
+    await unlink(tmp).catch(() => {});
+    return err(`could not save profile selection to ${target}: ${e instanceof Error ? e.message : String(e)}`);
+  }
+};
+
+export const writePin = (pin: ProfilePin): Promise<Result<void, string>> => writePinFile(pin);
+
+export const clearPin = (): Promise<Result<void, string>> => writePinFile(null);

package/extensions/browser-harness/prompt.ts

@@ -0,0 +1,16 @@
+export function getBrowserSystemPrompt(): string {
+  return `
+## Steel Browser Control
+
+The browser belongs to the persistent Steel Profile of the active Pi Profile. Use only
+\`browser_*\` tools for browser work. The harness owns its tabs and never uses a desktop
+browser profile.
+
+Call \`browser_snapshot\` first to inspect a page. It returns stable accessibility refs
+such as \`[e7]\`; use those refs with click, fill, select, focus, and keyboard tools.
+Prefer \`browser_fill\` to typing, use \`browser_wait_for\` instead of sleeping, and take a
+fresh snapshot when a ref is stale. Use screenshots only to validate visual rendering.
+
+Do not enter credentials, bypass authentication, solve CAPTCHAs, or submit a sensitive
+transaction without the user's explicit participation.\n`;
+}

package/extensions/browser-harness/registry.ts

@@ -0,0 +1,80 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { BrowserClient } from "./client";
+import { type AnyBrowserToolDefinition, registerBrowserTool } from "./util/tool";
+import { clickTool } from "./domains/click";
+import { typeTool, pressKeyTool, dispatchKeyTool } from "./domains/keyboard";
+import { fillTool, selectOptionTool, focusTool, setCheckedTool } from "./domains/form";
+import { fillFormTool } from "./domains/form-batch";
+import { pageInfoTool, waitTool, waitForLoadTool, waitForTool } from "./domains/page";
+import { scrollTool } from "./domains/scroll";
+import { handleDialogTool } from "./domains/dialog";
+import { screenshotTool } from "./domains/screenshot";
+import { navigateTool, openUrlsTool } from "./domains/navigate";
+import { goBackTool, goForwardTool, reloadTool } from "./domains/history";
+import { listTabsTool, currentTabTool, switchTabTool, newTabTool, closeTabTool } from "./domains/tabs";
+import { uploadFileTool, downloadTool, printToPdfTool } from "./domains/files";
+import { viewportResizeTool } from "./domains/viewport";
+import { dragAndDropTool } from "./domains/drag";
+import { httpGetTool, networkRequestsTool } from "./domains/network";
+import { clearHeadersTool, setHeadersTool } from "./domains/headers";
+import { consoleTool } from "./domains/console";
+import { snapshotTool } from "./domains/snapshot";
+import { executeJsTool } from "./domains/js";
+import { createSetupTool, setupTool } from "./domains/setup";
+import type { ViewerUrlProvider } from "./setup";
+import { webSearchTool } from "./domains/search/web-search";
+import { readPageTool } from "./domains/readpage/read-page";
+
+export const ALL_TOOLS: ReadonlyArray<AnyBrowserToolDefinition> = [
+  setupTool,
+  clickTool,
+  typeTool,
+  fillTool,
+  fillFormTool,
+  selectOptionTool,
+  setCheckedTool,
+  focusTool,
+  pressKeyTool,
+  dispatchKeyTool,
+  scrollTool,
+  pageInfoTool,
+  waitTool,
+  waitForTool,
+  waitForLoadTool,
+  handleDialogTool,
+  screenshotTool,
+  navigateTool,
+  openUrlsTool,
+  goBackTool,
+  goForwardTool,
+  reloadTool,
+  listTabsTool,
+  currentTabTool,
+  switchTabTool,
+  newTabTool,
+  closeTabTool,
+  uploadFileTool,
+  downloadTool,
+  printToPdfTool,
+  viewportResizeTool,
+  dragAndDropTool,
+  httpGetTool,
+  networkRequestsTool,
+  setHeadersTool,
+  clearHeadersTool,
+  consoleTool,
+  snapshotTool,
+  executeJsTool,
+  webSearchTool,
+  readPageTool,
+];
+
+export const registerAllTools = (
+  pi: ExtensionAPI,
+  client: BrowserClient,
+  viewerUrl?: ViewerUrlProvider,
+): void => {
+  for (const tool of ALL_TOOLS) {
+    registerBrowserTool(pi, client, tool === setupTool ? createSetupTool(viewerUrl) : tool);
+  }
+};

package/extensions/browser-harness/schemas/common.ts

@@ -0,0 +1,11 @@
+import { Type } from "typebox";
+
+export const Coords = Type.Object({
+  x: Type.Number({ description: "X coordinate in CSS pixels from left edge of viewport" }),
+  y: Type.Number({ description: "Y coordinate in CSS pixels from top edge of viewport" }),
+});
+
+export const MouseButton = Type.Union(
+  [Type.Literal("left"), Type.Literal("right"), Type.Literal("middle")],
+  { description: 'Mouse button: "left", "right", or "middle"' },
+);

package/extensions/browser-harness/schemas/parse.ts

@@ -0,0 +1,23 @@
+import type { Static, TSchema } from "typebox";
+import type { Validator } from "typebox/compile";
+import { type Result, err, ok } from "../util/result";
+
+export const parseJson = <S extends TSchema>(
+  raw: string,
+  validator: Validator<{}, S>,
+): Result<Static<S>, string> => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return err(`JSON parse failed: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (!validator.Check(parsed)) {
+    const messages = validator
+      .Errors(parsed)
+      .map((x) => x.message)
+      .join("; ");
+    return err(messages.length > 0 ? messages : "JSON did not match the expected shape");
+  }
+  return ok(parsed);
+};

package/extensions/browser-harness/setup.ts

@@ -0,0 +1,47 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { BrowserClient } from "./client";
+
+export type ViewerUrlProvider = () => string | undefined;
+
+export function registerSetupCommand(
+  pi: ExtensionAPI,
+  client: BrowserClient,
+  viewerUrl?: ViewerUrlProvider,
+): void {
+  pi.registerCommand("browser-setup", {
+    description: "Start a Steel API session for the active Pi Profile",
+    handler: async (_args, ctx) => {
+      const result = await performSetup(client, ctx, viewerUrl);
+      ctx.ui.notify(result.success ? result.data : result.error, result.success ? "info" : "error");
+    },
+  });
+}
+
+export type SetupResult = { success: true; data: string } | { success: false; error: string };
+
+export async function performSetup(
+  client: BrowserClient,
+  _ctx?: ExtensionContext,
+  viewerUrl?: ViewerUrlProvider,
+): Promise<SetupResult> {
+  const wasConnected = client.status().alive;
+  const started = await client.start();
+  if (!started.success) return { success: false, error: `Steel browser connection failed: ${started.error.message}` };
+
+  if (!wasConnected) {
+    const tab = await client.newTab("about:blank");
+    if (!tab.success) return { success: false, error: `Steel browser connected but could not open an agent tab: ${tab.error.message}` };
+  }
+
+  const info = await client.pageInfo();
+  const page = info.success && !("dialog" in info.data) ? info.data.url : "about:blank";
+  const viewer = viewerUrl?.();
+  return {
+    success: true,
+    data: [
+      `Steel browser ${wasConnected ? "already connected" : "connected"}.`,
+      `Current page: ${page}`,
+      ...(viewer ? [`Live viewer: ${viewer}`] : []),
+    ].join("\n"),
+  };
+}

package/extensions/browser-harness/state.ts

@@ -0,0 +1,51 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { asArrayOf, asNumber, asString, isRecord } from "./util/guards";
+
+export type BrowserState = {
+  readonly namespace: string;
+  readonly ownedTargetIds?: ReadonlyArray<string>;
+  readonly harnessWindowTargetId?: string;
+  readonly harnessWindowId?: number;
+};
+
+export const defaultState = (namespace = "default"): BrowserState => ({
+  namespace,
+  ownedTargetIds: [],
+});
+
+export const persistState = (pi: ExtensionAPI, state: BrowserState): void => {
+  pi.appendEntry<BrowserState>("browser-harness-state", state);
+};
+
+const asPersistedState = (v: unknown): Partial<BrowserState> | undefined => {
+  if (!isRecord(v)) return undefined;
+  const namespace = asString(v["namespace"]);
+  const ownedTargetIds = asArrayOf(v["ownedTargetIds"], asString);
+  const harnessWindowTargetId = asString(v["harnessWindowTargetId"]);
+  const harnessWindowId = asNumber(v["harnessWindowId"]);
+  return {
+    ...(namespace !== undefined ? { namespace } : {}),
+    ...(ownedTargetIds !== undefined ? { ownedTargetIds } : {}),
+    ...(harnessWindowTargetId !== undefined ? { harnessWindowTargetId } : {}),
+    ...(harnessWindowId !== undefined ? { harnessWindowId } : {}),
+  };
+};
+
+export const restoreState = (ctx: ExtensionContext, currentNamespace?: string): BrowserState => {
+  const branchEntries = ctx.sessionManager.getBranch();
+  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") {
+      const data = asPersistedState(entry.data);
+      if (data) {
+        return {
+          ...fallback,
+          ...data,
+          namespace: currentNamespace ?? data.namespace ?? fallback.namespace,
+        };
+      }
+    }
+  }
+  return fallback;
+};