@parcha/pi-browser 0.1.0-beta.30 → 0.1.0-beta.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,13 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ## 0.1.0-beta.31 (2026-11-06)
6
+
7
+ - A model granted both web_fetch and the browser is now told which one has cookies. Asked to "Open https://httpbin.org/cookies", a pi run picked web_fetch, which has no cookies, and answered with an empty page; it picked the browser only when told to. The tool descriptions the model reads now say:
8
+ - **web_fetch** has no cookies, sign-ins or session: it reads one page cold, so a page behind a sign-in, or one that depends on an earlier page, needs the browser tool, where this run has it. That holds for serve's web_fetch on every harness and for pi-browser's.
9
+ - **The browser's `run`** keeps this agent's saved sign-ins and cookies, for anything behind a sign-in or a page that depends on an earlier one. It says this only on a run that has a saved sign-in: in serve, a run handed its agent's sign-in; in pi-browser, a host that passes `signIns: true` or a session vault. Without one it says only that the browser keeps cookies across pages, which stays true for a local Chrome, which keeps no saved sign-in.
10
+ - **pi-browser** adds `browserToolsFor(signIns)` (the browser's contracts with `run`'s words for that plane), `BROWSER_KEEPS` (the two sentences), and the durable extension's `signIns` option.
11
+
5
12
  ## 0.1.0-beta.30 (2026-11-05)
6
13
 
7
14
  - Browser minutes count in a run's spend. Each charge of a `browser` session's time is booked as a tool cost, so it is a `Tool cost` line on the run's timeline, part of its `cost.usd`, and `/usage`'s new `browser_time` meter (dollars, and seconds for runs that have ended); capabilities list `browser_time` in `usage.meters`. Under `max_cost_usd`, the browser's time is held before it runs: a browser call that the cap cannot hold is not made, the model gets the cap's words, and the run's session is released, so no browser minute passes the cap.
package/README.md CHANGED
@@ -396,6 +396,9 @@ await browser.reconcile(harness, () => true, context); // settles what a dead
396
396
  - `decisions`: `classifyPage` and `rankChunks`, answered with your judge. Absent, no page is classified and no find is ranked.
397
397
  - `redact.values`: exact strings to scrub besides the built-in shapes.
398
398
  - `section.addendum`: your text after the package's prompt section.
399
+ - `signIns`: `true` when the plane's sessions open on the agent's saved sign-ins (your kept profile or context). `run`'s
400
+ description then tells the model the browser keeps them, for a page behind a sign-in; without it, it says only that the
401
+ browser keeps cookies across pages. Absent, it is whether a `sessionVault` is given.
399
402
  - `workspace`: where `browser_downloads` writes, and where `browser_upload` reads when `files` is absent. Absent, `browser_downloads` is not listed, and `browser_upload` is listed only if `files` is given.
400
403
  - `files`: a `WorkspaceFiles` that resolves `browser_upload` paths. Given, `browser_upload` is listed without a `workspace`.
401
404
  - `handoff`: a `HandoffPort` that reaches a person (`request`, then `outcome` polled until done, cancelled or expired;
@@ -4,7 +4,7 @@ import { mkdtemp, rm } from "node:fs/promises";
4
4
  import os from "node:os";
5
5
  import path from "node:path";
6
6
  import { setTimeout as sleep } from "node:timers/promises";
7
- import { BROWSER_TOOLS, WEB_TOOLS, browserSection, listedFor } from "./core/contract.js";
7
+ import { BROWSER_TOOLS, WEB_TOOLS, browserSection, browserToolsFor, listedFor } from "./core/contract.js";
8
8
  import { BrowserFailureError, closeDriver, custodyTools, FIXED_SESSION_RELAUNCH, fenced, HANDED_BACK, loadedNoPage, moveRecord, newSessionRecord, notices, NOTHING_TO_HOLD, navigationRefusal, profileRefusal, relaunchRefusal, sessionSpec, waitingForHuman, backoffMs, NO_HANDOFF, } from "./core/custody.js";
9
9
  import { browserFailure, classifyBrowserError } from "./core/failures.js";
10
10
  import { workspaceFiles } from "./core/files.js";
@@ -629,7 +629,8 @@ export function createBrowserExtension(options = {}) {
629
629
  },
630
630
  });
631
631
  }
632
- for (const contract of BROWSER_TOOLS)
632
+ // A session vault keeps sign-ins, and run says so; without one it claims cookies across pages only.
633
+ for (const contract of browserToolsFor(!!options.sessionVault))
633
634
  if (listedFor(contract, { downloads: fileTools, upload: fileTools, handoff: !!options.handoff }))
634
635
  registerTool(pi, contract, runtimeOf);
635
636
  registerTool(pi, WEB_TOOLS.find((tool) => tool.name === "web_fetch"), runtimeOf);
@@ -16,6 +16,12 @@ export type ToolContract = {
16
16
  readonly evidence: "none" | "receipt" | "image" | "files" | "urls";
17
17
  readonly listedWhen: "always" | "downloads" | "upload" | "fetch" | "search" | "sites" | "handoff";
18
18
  };
19
+ /** What the browser keeps, as `run`'s description tells the model when it picks between the browser and web_fetch:
20
+ * cookies across pages always, its agent's saved sign-ins only on a plane that has them (a local Chrome keeps none). */
21
+ export declare const BROWSER_KEEPS: Readonly<{
22
+ cookies: "It keeps cookies across pages: use it for a page that depends on an earlier one, or one that sets cookies.";
23
+ signIns: "It keeps this agent's saved sign-ins and cookies: use it for anything behind a sign-in, or a page that depends on an earlier one.";
24
+ }>;
19
25
  /** A hit's snippet is clipped to this many characters, whitespace collapsed, so ten hits stay a few kilobytes. */
20
26
  export declare const WEB_SEARCH_SNIPPET_MAX = 500;
21
27
  /** Whether a host lists a browser tool: one that is always offered, or one whose capability the host has (a workspace to copy downloads
@@ -27,6 +33,9 @@ export declare const listedFor: (contract: ToolContract, offers: {
27
33
  }) => boolean;
28
34
  export declare const BROWSER_TOOLS: readonly ToolContract[];
29
35
  export declare const WEB_TOOLS: readonly ToolContract[];
36
+ /** The browser's contracts as a plane's model reads them: `run` says the plane keeps its agent's saved sign-ins where it
37
+ * has them (a host's kept profile, or a session vault), and only cookies where it has none. */
38
+ export declare const browserToolsFor: (signIns: boolean) => readonly ToolContract[];
30
39
  export declare const BROWSER_TOOL_NAMES: readonly string[];
31
40
  export declare const WEB_TOOL_NAMES: readonly string[];
32
41
  /** Depends only on configuration, never live state, so every request renders the same text and keeps the prompt cache. */
@@ -16,10 +16,18 @@ const snapshot = {
16
16
  parameters: object({ includeIframes: { type: "boolean", default: true } }),
17
17
  effect: "read", replay: "safe", executionMode: "sequential", evidence: "none", listedWhen: "always",
18
18
  };
19
+ /** What the browser keeps, as `run`'s description tells the model when it picks between the browser and web_fetch:
20
+ * cookies across pages always, its agent's saved sign-ins only on a plane that has them (a local Chrome keeps none). */
21
+ export const BROWSER_KEEPS = Object.freeze({
22
+ cookies: "It keeps cookies across pages: use it for a page that depends on an earlier one, or one that sets cookies.",
23
+ signIns: "It keeps this agent's saved sign-ins and cookies: use it for anything behind a sign-in, or a page that depends on an earlier one.",
24
+ });
25
+ const runDescription = (signIns) => `Browse and automate websites in the persistent Stagehand browser. ${signIns ? BROWSER_KEEPS.signIns : BROWSER_KEEPS.cookies} ` +
26
+ 'Navigate with JavaScript such as await page.goto("https://example.com"); there is no separate navigate or start tool. Execute either a JavaScript workflow against the Stagehand Playwright facade or a batch of actions using IDs from the latest snapshot. Code is the body of an async function with page, context and browser in scope: `return` the value you want back. Provide exactly one of code or actions. Each action must use "op" (never "kind") and "id" (never "ref"). Copy the bracketed snapshot ID as a string. Examples: {"actions":[{"op":"click","id":"1-42"}]}, {"actions":[{"op":"fill","id":"2-14","value":"Miami"}]}, {"actions":[{"op":"select","id":"3-9","values":"Lowest price"}]}.';
19
27
  const run = {
20
28
  name: "run",
21
29
  label: "Browser: run",
22
- description: 'Browse and automate websites in the persistent Stagehand browser. Navigate with JavaScript such as await page.goto("https://example.com"); there is no separate navigate or start tool. Execute either a JavaScript workflow against the Stagehand Playwright facade or a batch of actions using IDs from the latest snapshot. Code is the body of an async function with page, context and browser in scope: `return` the value you want back. Provide exactly one of code or actions. Each action must use "op" (never "kind") and "id" (never "ref"). Copy the bracketed snapshot ID as a string. Examples: {"actions":[{"op":"click","id":"1-42"}]}, {"actions":[{"op":"fill","id":"2-14","value":"Miami"}]}, {"actions":[{"op":"select","id":"3-9","values":"Lowest price"}]}.',
30
+ description: runDescription(false),
23
31
  // No top-level oneOf for "exactly one of code or actions": AI-SDK-based clients reject it, so the tool enforces it.
24
32
  parameters: object({
25
33
  code: { type: "string", minLength: 1 },
@@ -133,7 +141,8 @@ const webFetch = {
133
141
  name: "web_fetch",
134
142
  label: "Web fetch",
135
143
  description: "Fetch one URL as clean markdown without a browser session: fast and cheap, and it handles most static and many dynamic pages. " +
136
- "Use it for reading articles, filings, registries, PDFs-as-pages. If it returns blocked or empty content, drive the page with run/snapshot instead. " +
144
+ "It has no cookies, sign-ins or session: it reads one page cold. " +
145
+ "Use it for reading articles, filings, registries, PDFs-as-pages. If it returns blocked or empty content, or the page is behind a sign-in or depends on an earlier page, drive it with run/snapshot instead. " +
137
146
  "A page it returns is filed as evidence: that read, not a search result, is what a claim cites. " +
138
147
  "The result is persisted as evidence with its URL: a query value that is in the URL you asked for stays in it, any other value of the final URL is replaced by a redaction marker (the word redacted in square brackets).",
139
148
  parameters: object({
@@ -159,6 +168,9 @@ const webSearch = {
159
168
  export const listedFor = (contract, offers) => contract.listedWhen === "always" || (contract.listedWhen === "downloads" && offers.downloads) || (contract.listedWhen === "upload" && offers.upload) || (contract.listedWhen === "handoff" && offers.handoff);
160
169
  export const BROWSER_TOOLS = Object.freeze([snapshot, run, screenshot, browserRead, browserRelease, browserRelaunch, browserRequestHandoff, browserDownloads, browserUpload]);
161
170
  export const WEB_TOOLS = Object.freeze([webFetch, webSearch]);
171
+ /** The browser's contracts as a plane's model reads them: `run` says the plane keeps its agent's saved sign-ins where it
172
+ * has them (a host's kept profile, or a session vault), and only cookies where it has none. */
173
+ export const browserToolsFor = (signIns) => signIns ? Object.freeze(BROWSER_TOOLS.map((contract) => (contract === run ? { ...contract, description: runDescription(true) } : contract))) : BROWSER_TOOLS;
162
174
  export const BROWSER_TOOL_NAMES = Object.freeze(BROWSER_TOOLS.map((tool) => tool.name));
163
175
  export const WEB_TOOL_NAMES = Object.freeze(WEB_TOOLS.map((tool) => tool.name));
164
176
  /** Depends only on configuration, never live state, so every request renders the same text and keeps the prompt cache. */
package/dist/durable.d.ts CHANGED
@@ -13,6 +13,9 @@ export type { DriverFactory, DriverOptions } from "./core/custody.js";
13
13
  export type BrowserExtensionOptions<D extends PageDriver = PageDriver> = VaultOptions & {
14
14
  /** Default "browser"; a second plane installs a second extension under another name. */
15
15
  name?: string;
16
+ /** The plane's sessions open on its agent's saved sign-ins (a host's kept profile): `run` tells the model so, for a page
17
+ * behind a sign-in. Default: whether a `sessionVault` is given. Without either, it claims cookies across pages only. */
18
+ signIns?: boolean;
16
19
  /** Called per use: the provider for this conversation's plane. Holds the credentials in its closure; nothing it
17
20
  * returns is committed. */
18
21
  provider: (target: {
package/dist/durable.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { randomUUID } from "node:crypto";
2
2
  import { configure, defineDoc, defineExtension, defineTool } from "@earendil-works/pi-durable";
3
- import { BROWSER_TOOL_NAMES, BROWSER_TOOLS, browserSection, listedFor, WEB_TOOL_NAMES } from "./core/contract.js";
3
+ import { BROWSER_TOOL_NAMES, browserSection, browserToolsFor, listedFor, WEB_TOOL_NAMES } from "./core/contract.js";
4
4
  import { BrowserFailureError, closeDriver, currentRecord, loadedNoPage, custodyTools, FIXED_SESSION_RELAUNCH, fenced, HANDED_BACK, newSessionRecord, notices, NAVIGATION_CAP, NOTHING_TO_HOLD, navigationRefusal, profileRefusal, relaunchRefusal, SESSION_REPLACED, sessionSpec, waitingForHuman, NO_HANDOFF } from "./core/custody.js";
5
5
  import { forModel } from "./durable/result.js";
6
6
  import { EffectObserver, effectDecider, observerFailure } from "./core/effects.js";
@@ -706,7 +706,7 @@ const withSessionTime = (own, charged) => {
706
706
  return { ...charged.usage, ...own, cost: { ...charged.usage.cost, ...ownCost, total: charged.usage.cost.total + (ownCost.total ?? 0) } };
707
707
  };
708
708
  function toolsFor(c, impls) {
709
- return BROWSER_TOOLS
709
+ return browserToolsFor(c.options.signIns ?? !!c.options.sessionVault)
710
710
  .filter((contract) => impls[contract.name] && listedFor(contract, { downloads: !!c.options.workspace, upload: !!(c.options.files || c.options.workspace), handoff: !!c.options.handoff }))
711
711
  .map((contract) => defineTool({
712
712
  name: contract.name,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@parcha/pi-browser",
3
- "version": "0.1.0-beta.30",
3
+ "version": "0.1.0-beta.31",
4
4
  "description": "Your agent gets its own browser, and you can take over and hand it back.",
5
5
  "keywords": [
6
6
  "pi-package",