@parcha/pi-browser 0.1.0-beta.13 → 0.1.0-beta.14

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/dist/durable.js CHANGED
@@ -1,9 +1,10 @@
1
- import { configure, defineDoc, defineExtension, defineTool } from "@earendil-works/pi-durable";
1
+ import { randomUUID } from "node:crypto";
2
+ import { configure, defineDoc, defineExtension, defineTool, ToolResultEntry } from "@earendil-works/pi-durable";
2
3
  import { BROWSER_TOOL_NAMES, BROWSER_TOOLS, browserSection, WEB_TOOL_NAMES } from "./core/contract.js";
3
4
  import { BrowserFailureError, closeDriver, currentRecord, custodyTools, newSessionRecord, notices, NAVIGATION_CAP, relaunchRefusal, SESSION_REPLACED, sessionSpec } from "./core/custody.js";
4
5
  import { forModel } from "./durable-result.js";
5
6
  import { EffectObserver, effectDecider, observerFailure } from "./core/effects.js";
6
- import { classifyBrowserError } from "./core/failures.js";
7
+ import { browserFailure, classifyBrowserError } from "./core/failures.js";
7
8
  import { pageTools } from "./core/tools.js";
8
9
  import { useWebsite, useWebsiteContract } from "./core/sites.js";
9
10
  import { leaseTag } from "./core/lease.js";
@@ -15,360 +16,421 @@ export { createWebExtension } from "./web.js";
15
16
  export { CONFIRM_POLLS, RELEASE_ATTEMPTS } from "./store.js";
16
17
  const PLANE = "default";
17
18
  const UNCONFIGURED = { label: "", run: "", policy: DEFAULT_BROWSER_POLICY };
18
- const NOT_CONFIGURED = new BrowserFailureError({ ok: false, code: "browser_unavailable", retryable: false, effect: "none", message: "This conversation has no browser configuration, so no browser can be launched here; use web_fetch or another source." });
19
+ const NOT_CONFIGURED = new BrowserFailureError(browserFailure("browser_unavailable", "This conversation has no browser configuration, so no browser can be launched here; use web_fetch or another source."));
20
+ const emptySessions = () => ({ current: {}, sessions: [], notice: null });
21
+ async function drainReleases(name, harness, context, signal) {
22
+ signal?.throwIfAborted();
23
+ const drained = (async () => {
24
+ for (;;) {
25
+ const live = (await harness.inspect(context)).tasks.filter((task) => task.record.kind === `${name}.release`);
26
+ if (!live.length)
27
+ return;
28
+ await Promise.all(live.map((task) => harness.waitForTask(task.record.id, context)));
29
+ }
30
+ })();
31
+ if (!signal)
32
+ return drained;
33
+ const done = new AbortController();
34
+ try {
35
+ await Promise.race([drained, new Promise((_, reject) => signal.addEventListener("abort", () => reject(signal.reason), { once: true, signal: done.signal }))]);
36
+ }
37
+ finally {
38
+ done.abort();
39
+ }
40
+ }
19
41
  const open = (record) => record?.state === "live" || record?.state === "creating";
20
42
  // A child gets the browser and web tools only, never use_website, so it cannot start children of its own.
21
43
  const CHILD_TOOLS = new Set([...BROWSER_TOOL_NAMES, ...WEB_TOOL_NAMES]);
22
- export function createBrowserExtension(options) {
23
- const name = options.name ?? "browser";
24
- const redact = createRedactor(() => providerKeyValues(process.env, options.redact?.values));
25
- const Config = defineDoc({ kind: `${name}.config`, version: 1, scope: "conversation", history: "latest", fork: "current", initial: () => structuredClone(UNCONFIGURED) });
26
- // A fork starts with no sessions: it never shares a live browser.
27
- const Children = defineDoc({ kind: `${name}.children`, version: 1, scope: "conversation", history: "latest", fork: "current", initial: () => ({ byRequest: {} }) });
28
- const Sessions = defineDoc({ kind: `${name}.sessions`, version: 1, scope: "conversation", history: "latest", fork: "initial", initial: () => ({ current: {}, sessions: [], notice: null }) });
29
- const attachments = new Map();
30
- const observers = new Map();
31
- const { run: serialize } = keyedSerializer();
32
- const idle = idleTracker({ idleMs: DEFAULT_BROWSER_POLICY.idleReleaseS * 1000, onIdle: (cid, fired, idleMs) => void releaseIdle(cid, fired, idleMs).catch(() => undefined) });
33
- let opened = null;
34
- const configOf = async (read, cid, context) => {
35
- const config = await read.snapshot(Config, cid, context);
36
- if (!config?.run)
37
- throw NOT_CONFIGURED;
38
- return config;
39
- };
40
- const providerOf = async (read, cid, plane, context) => options.provider({ conversationId: cid, plane, config: await configOf(read, cid, context) });
41
- const rowOf = (cid, record) => ({ tag: record.tag, conversationId: cid, plane: record.plane, provider: record.provider, resourceId: record.resourceId, state: record.state });
42
- async function emitObserver(row) {
43
- try {
44
- await options.onObserver?.(row);
45
- }
46
- catch { }
44
+ class Attachments {
45
+ drivers = new Map();
46
+ observers = new Map();
47
+ driver(tag) {
48
+ return this.drivers.get(tag);
47
49
  }
48
- async function emit(cid, label, record, change, provider) {
49
- if (!options.onSession)
50
- return;
51
- try {
52
- const ref = record.resourceId === null ? null : { id: record.resourceId, tag: record.tag };
53
- const view = change !== "released" && ref && provider?.liveView ? await provider.liveView(ref) : null;
54
- // The live view's own URLs go to the host as they are (it needs their token); a browsed page's URL and title are
55
- // scrubbed, since its query can carry a credential.
56
- const liveView = view && { ...view, pages: view.pages.map((page) => ({ ...page, url: page.url === null ? null : scrubPageUrl(page.url, redact), title: page.title === null ? null : redact(page.title) })) };
57
- await options.onSession({ conversationId: cid, label, session: record, liveView }, change);
58
- }
59
- catch { }
50
+ observer(tag) {
51
+ return this.observers.get(tag);
60
52
  }
61
- /** Class name and redacted message only: a vendor SDK's error text can repeat the request's credentials. */
62
- const scrubbed = (error) => Object.assign(new Error(redact(error instanceof Error ? error.message : String(error))), { name: error instanceof Error ? error.name : "Error" });
63
- const prices = resolvePrices(options.prices);
64
- const priceState = prices.sessionUsdPerHour === null ? "unpriced" : "priced";
65
- const meter = (spent, at, final = false) => {
66
- const charged = sessionCharge(spent, at, prices, priceState, final);
67
- return { spent: { ...charged.spent, state: charged.usage.state }, usage: charged.usage };
68
- };
69
- const { Inventory, move, addNotice, begin, requestRelease, bindByTag, emitReleased, ReleaseTask, reconcileAll } = custodyStore({ name, Config, Sessions, providerOf, emit, meter, scrubbed, createDeadlineMs: options.createDeadlineMs ?? CREATE_DEADLINE_MS });
70
- const stateOf = async (scope) => (await scope.read.snapshot(Sessions, scope.cid, scope.context)) ?? { current: {}, sessions: [], notice: null };
71
- const failure = (error, scope) => error instanceof BrowserFailureError ? error : new BrowserFailureError(classifyBrowserError(error, false, { aborted: scope.signal.aborted }));
72
- async function detach(tag) {
73
- const driver = attachments.get(tag);
74
- attachments.delete(tag);
75
- observers.get(tag)?.close();
76
- observers.delete(tag);
53
+ attach(tag, driver, observer) {
54
+ this.observers.set(tag, observer);
55
+ this.drivers.set(tag, driver);
56
+ }
57
+ async detach(tag) {
58
+ const driver = this.drivers.get(tag);
59
+ this.drivers.delete(tag);
60
+ this.observers.get(tag)?.close();
61
+ this.observers.delete(tag);
77
62
  if (driver)
78
63
  await closeDriver(driver);
79
64
  }
80
65
  /** Let go of a dead driver connection and nothing else: a healthy observer stays attached, so a page that sends
81
66
  * something before the next call is still held. When the observer is dead too, both go. */
82
- async function detachDriver(tag) {
83
- if (observers.get(tag)?.closed)
84
- return detach(tag);
85
- const driver = attachments.get(tag);
86
- attachments.delete(tag);
67
+ async detachDriver(tag) {
68
+ if (this.observers.get(tag)?.closed)
69
+ return this.detach(tag);
70
+ const driver = this.drivers.get(tag);
71
+ this.drivers.delete(tag);
87
72
  if (driver)
88
73
  await closeDriver(driver);
89
74
  }
90
- async function attachLive(scope, record) {
91
- const held = attachments.get(record.tag);
92
- // An observer whose socket closed holds nothing: driver and observer are attached again together.
93
- if (held && !observers.get(record.tag)?.closed)
94
- return held;
95
- if (held)
96
- await detach(record.tag);
97
- const provider = await providerOf(scope.read, scope.cid, scope.plane, scope.context);
98
- const ref = { id: record.resourceId, tag: record.tag };
99
- try {
100
- return await connect(scope, provider, ref);
101
- }
102
- catch (error) {
103
- if (!(await markEnded(scope, record, provider)))
104
- throw failure(error, scope);
105
- return null;
106
- }
75
+ tags() {
76
+ return [...new Set([...this.drivers.keys(), ...this.observers.keys()])];
107
77
  }
108
- async function connect(scope, provider, ref) {
109
- const config = await configOf(scope.read, scope.cid, scope.context);
110
- const { actions: policy, batchTimeoutMs } = config.policy;
111
- const target = await provider.attach(ref, scope.signal);
112
- const driver = await options.driver(target, scope.signal, { batchTimeoutMs });
113
- let unattached = null;
114
- // A healthy observer that outlived its driver's connection is kept, not opened a second time.
115
- const kept = observers.get(ref.tag);
116
- const open = options.openObserver ?? EffectObserver.open.bind(EffectObserver);
117
- const observer = kept && !kept.closed ? kept : policy ? await open(target, policy === "allow" ? null : effectDecider(policy, options.decisions), batchTimeoutMs).catch((error) => { unattached = error; return null; }) : null;
118
- // A policy that holds requests never degrades to browsing without the hold.
119
- if (policy && policy !== "allow" && !observer) {
120
- await closeDriver(driver);
121
- throw new BrowserFailureError({ ok: false, code: "browser_unavailable", retryable: true, effect: "none", message: "The browser's request observer could not attach, and this run's action policy needs it to hold requests; the browser is not used without it." });
122
- }
123
- observers.set(ref.tag, observer);
124
- attachments.set(ref.tag, driver);
125
- if (policy === "allow" && !observer)
126
- await emitObserver({ conversationId: scope.cid, label: config.label, tag: ref.tag, session_id: ref.id, policy, code: observerFailure(unattached) });
127
- return driver;
78
+ }
79
+ async function configOf(c, read, cid, context) {
80
+ const config = await read.snapshot(c.Config, cid, context);
81
+ if (!config?.run)
82
+ throw NOT_CONFIGURED;
83
+ return config;
84
+ }
85
+ async function providerOf(c, read, cid, plane, context) {
86
+ return c.options.provider({ conversationId: cid, plane, config: await configOf(c, read, cid, context) });
87
+ }
88
+ const rowOf = (cid, record) => ({ tag: record.tag, conversationId: cid, plane: record.plane, provider: record.provider, resourceId: record.resourceId, state: record.state });
89
+ async function emitObserver(c, row) {
90
+ try {
91
+ await c.options.onObserver?.(row);
128
92
  }
129
- async function markEnded(scope, record, provider) {
130
- const status = await provider.status({ id: record.resourceId, tag: record.tag }, scope.signal).catch(() => "running");
131
- if (status !== "gone" && status !== "stopped")
132
- return false;
133
- await scope.commit((tx) => move(tx, rowOf(scope.cid, record), { state: "released", reason: "ended", at: now() }));
134
- await detach(record.tag);
135
- await emitReleased(scope.cid, record.tag, scope.read, scope.context);
136
- return true;
93
+ catch { }
94
+ }
95
+ async function emit(c, cid, label, record, change, provider) {
96
+ if (!c.options.onSession)
97
+ return;
98
+ try {
99
+ const ref = record.resourceId === null ? null : { id: record.resourceId, tag: record.tag };
100
+ const view = change !== "released" && ref && provider?.liveView ? await provider.liveView(ref) : null;
101
+ // The live view's own URLs go to the host as they are (it needs their token); a browsed page's URL and title are
102
+ // scrubbed, since its query can carry a credential.
103
+ const liveView = view && { ...view, pages: view.pages.map((page) => ({ ...page, url: page.url === null ? null : scrubPageUrl(page.url, c.redact), title: page.title === null ? null : c.redact(page.title) })) };
104
+ await c.options.onSession({ conversationId: cid, label, session: record, liveView }, change);
137
105
  }
138
- async function settleCreating(scope, record) {
139
- const provider = await providerOf(scope.read, scope.cid, scope.plane, scope.context);
140
- try {
141
- await bindByTag(provider, rowOf(scope.cid, record), scope.commit, scope.signal);
142
- }
143
- catch (error) {
106
+ catch { }
107
+ }
108
+ async function stateOf(c, scope) {
109
+ return (await scope.read.snapshot(c.Sessions, scope.cid, scope.context)) ?? emptySessions();
110
+ }
111
+ const failure = (error, scope) => error instanceof BrowserFailureError ? error : new BrowserFailureError(classifyBrowserError(error, false, { aborted: scope.signal.aborted }));
112
+ async function attachLive(c, scope, record) {
113
+ const held = c.held.driver(record.tag);
114
+ // An observer whose socket closed holds nothing: driver and observer are attached again together.
115
+ if (held && !c.held.observer(record.tag)?.closed)
116
+ return held;
117
+ if (held)
118
+ await c.held.detach(record.tag);
119
+ const provider = await providerOf(c, scope.read, scope.cid, scope.plane, scope.context);
120
+ const ref = { id: record.resourceId, tag: record.tag };
121
+ try {
122
+ return await connect(c, scope, provider, ref);
123
+ }
124
+ catch (error) {
125
+ if (!(await markEnded(c, scope, record, provider)))
144
126
  throw failure(error, scope);
145
- }
127
+ return null;
146
128
  }
147
- async function create(scope, overrides, presetTag) {
148
- const config = await configOf(scope.read, scope.cid, scope.context);
149
- const provider = await options.provider({ conversationId: scope.cid, plane: scope.plane, config });
150
- const tag = presetTag ?? leaseTag("ar", config.run, scope.cid, (await stateOf(scope)).sessions.length + 1);
151
- const spec = sessionSpec(config, tag, overrides);
152
- const record = newSessionRecord({ plane: scope.plane, tag, provider: provider.name, spec, at: now() });
153
- const row = rowOf(scope.cid, record);
154
- await scope.commit(async (tx) => {
155
- const state = await tx.doc(Sessions, scope.cid);
156
- state.sessions.push(record);
157
- state.current[scope.plane] = state.sessions.length - 1;
158
- await begin(tx, row);
159
- });
160
- // An answer lost on the way back is not a session that never started: it is settled by its tag.
161
- const ref = await provider.create(spec, scope.signal).then(async (made) => { await scope.commit((tx) => move(tx, row, { state: "live", resourceId: made.id, at: now() })); return made; }, async (error) => (await bindByTag(provider, row, scope.commit, scope.signal, await provider.findByTag(tag, scope.signal).catch(() => []))) ?? Promise.reject(failure(error, scope)));
162
- const live = { ...record, state: "live", resourceId: ref.id };
163
- try {
164
- const driver = await connect(scope, provider, ref);
165
- await emit(scope.cid, config.label, live, "launched", provider);
166
- return { record: live, driver };
129
+ }
130
+ async function connect(c, scope, provider, ref) {
131
+ const config = await configOf(c, scope.read, scope.cid, scope.context);
132
+ const { actions: policy, batchTimeoutMs } = config.policy;
133
+ const target = await provider.attach(ref, scope.signal);
134
+ const driver = await c.options.driver(target, scope.signal, { batchTimeoutMs });
135
+ let unattached = null;
136
+ // A healthy observer that outlived its driver's connection is kept, not opened a second time.
137
+ const kept = c.held.observer(ref.tag);
138
+ const open = c.options.openObserver ?? EffectObserver.open.bind(EffectObserver);
139
+ const observer = kept && !kept.closed ? kept : policy ? await open(target, policy === "allow" ? null : effectDecider(policy, c.options.decisions), batchTimeoutMs).catch((error) => { unattached = error; return null; }) : null;
140
+ // A policy that holds requests never degrades to browsing without the hold.
141
+ if (policy && policy !== "allow" && !observer) {
142
+ await closeDriver(driver);
143
+ throw new BrowserFailureError(browserFailure("browser_unavailable", "The browser's request observer could not attach, and this run's action policy needs it to hold requests; the browser is not used without it.", { retryable: true }));
144
+ }
145
+ c.held.attach(ref.tag, driver, observer);
146
+ if (policy === "allow" && !observer)
147
+ await emitObserver(c, { conversationId: scope.cid, label: config.label, tag: ref.tag, session_id: ref.id, policy, code: observerFailure(unattached) });
148
+ return driver;
149
+ }
150
+ async function markEnded(c, scope, record, provider) {
151
+ const status = await provider.status({ id: record.resourceId, tag: record.tag }, scope.signal).catch(() => "running");
152
+ if (status !== "gone" && status !== "stopped")
153
+ return false;
154
+ await scope.commit((tx) => c.store.move(tx, rowOf(scope.cid, record), { state: "released", reason: "ended", at: now() }));
155
+ await c.held.detach(record.tag);
156
+ await c.store.emitReleased(scope.cid, record.tag, scope.read, scope.context);
157
+ return true;
158
+ }
159
+ async function settleCreating(c, scope, record) {
160
+ const provider = await providerOf(c, scope.read, scope.cid, scope.plane, scope.context);
161
+ try {
162
+ await c.store.bindByTag(provider, rowOf(scope.cid, record), scope.commit, scope.signal);
163
+ }
164
+ catch (error) {
165
+ throw failure(error, scope);
166
+ }
167
+ }
168
+ async function create(c, scope, overrides, presetTag) {
169
+ const config = await configOf(c, scope.read, scope.cid, scope.context);
170
+ const provider = await c.options.provider({ conversationId: scope.cid, plane: scope.plane, config });
171
+ const tag = presetTag ?? leaseTag("ar", config.run, scope.cid, (await stateOf(c, scope)).sessions.length + 1);
172
+ const spec = sessionSpec(config, tag, overrides);
173
+ const record = newSessionRecord({ plane: scope.plane, tag, provider: provider.name, spec, at: now(), honours: provider.caps.settings });
174
+ const row = rowOf(scope.cid, record);
175
+ await scope.commit(async (tx) => {
176
+ const state = await tx.doc(c.Sessions, scope.cid);
177
+ state.sessions.push(record);
178
+ state.current[scope.plane] = state.sessions.length - 1;
179
+ await c.store.begin(tx, row);
180
+ });
181
+ // An answer lost on the way back is not a session that never started: it is settled by its tag.
182
+ const ref = await provider.create(spec, scope.signal).then(async (made) => { await scope.commit((tx) => c.store.move(tx, row, { state: "live", resourceId: made.id, at: now() })); return made; }, async (error) => (await c.store.bindByTag(provider, row, scope.commit, scope.signal, await provider.findByTag(tag, scope.signal).catch(() => []))) ?? Promise.reject(failure(error, scope)));
183
+ const live = { ...record, state: "live", resourceId: ref.id };
184
+ try {
185
+ const driver = await connect(c, scope, provider, ref);
186
+ await emit(c, scope.cid, config.label, live, "launched", provider);
187
+ return { record: live, driver };
188
+ }
189
+ catch (error) {
190
+ throw failure(error, scope);
191
+ }
192
+ }
193
+ async function acquire(c, scope) {
194
+ let note = null;
195
+ for (let turn = 0; turn < 4; turn += 1) {
196
+ const record = currentRecord(await stateOf(c, scope), scope.plane);
197
+ if (record?.state === "live") {
198
+ const driver = await attachLive(c, scope, record);
199
+ if (driver)
200
+ return { record, driver, note };
201
+ note = notices.ended(record.lastUrl);
167
202
  }
168
- catch (error) {
169
- throw failure(error, scope);
203
+ else if (record?.state === "creating") {
204
+ await settleCreating(c, scope, record);
205
+ }
206
+ else {
207
+ return { ...(await create(c, scope, {})), note };
170
208
  }
171
209
  }
172
- async function acquire(scope) {
173
- let note = null;
174
- for (let turn = 0; turn < 4; turn += 1) {
175
- const record = currentRecord(await stateOf(scope), scope.plane);
176
- if (record?.state === "live") {
177
- const driver = await attachLive(scope, record);
178
- if (driver)
179
- return { record, driver, note };
180
- note = notices.ended(record.lastUrl);
181
- }
182
- else if (record?.state === "creating") {
183
- await settleCreating(scope, record);
184
- }
185
- else {
186
- return { ...(await create(scope, {})), note };
210
+ throw new Error(`browser custody for conversation ${scope.cid} did not settle`);
211
+ }
212
+ /** Custody's notice is kept in the call's memo before it is cleared, so a call rerun after a crash still tells it. */
213
+ async function attached(c, scope, record, driver, note) {
214
+ const state = await stateOf(c, scope);
215
+ const notice = await scope.keep("notice", [note, state.notice].filter(Boolean).join(" "));
216
+ if (state.notice !== null)
217
+ await scope.commit(async (tx) => { (await tx.doc(c.Sessions, scope.cid)).notice = null; });
218
+ const fresh = state.sessions.find((r) => r.tag === record.tag) ?? record;
219
+ const interrupted = await cutOf(c, scope, journalOf(state, scope.plane));
220
+ const recorded = Boolean((await providerOf(c, scope.read, scope.cid, scope.plane, scope.context)).recordings);
221
+ return { driver, tag: record.tag, sessionId: fresh.resourceId, record: fresh, notice: notice || null, interrupted, recorded, effects: c.held.observer(record.tag) ?? null };
222
+ }
223
+ async function releaseRecord(c, scope, record, reason) {
224
+ await scope.commit((tx) => c.store.requestRelease(tx, rowOf(scope.cid, record), reason, now()));
225
+ await c.held.detach(record.tag);
226
+ }
227
+ const editState = (c, scope, edit) => scope.commit(async (tx) => edit(await tx.doc(c.Sessions, scope.cid)));
228
+ const journalOf = (state, plane) => [...state.sessions].reverse().find((r) => r.plane === plane && r.pendingEffect !== null)?.pendingEffect ?? null;
229
+ const clearJournal = (c, scope, callId) => editState(c, scope, (state) => { for (const record of state.sessions)
230
+ if (record.plane === scope.plane && record.pendingEffect?.callId === callId)
231
+ record.pendingEffect = null; });
232
+ /** Whether a journaled action's own answer was committed as a success: its result, found by pi's typed tool-result
233
+ * entry. The scan covers only the entry's conversation from where it was journaled on, never the whole history. */
234
+ async function answered(scope, pending) {
235
+ const after = pending.after;
236
+ if (after === undefined)
237
+ return false;
238
+ return scope.commit(async (tx) => {
239
+ let cursor;
240
+ do {
241
+ const page = await tx.scanEntries({ conversationId: scope.cid, minEntryId: after, order: "ascending" }, 100, cursor);
242
+ for (const entry of page.items) {
243
+ const message = ToolResultEntry.is(entry) ? entry.model?.[0] : undefined;
244
+ if (message?.role === "toolResult" && message.toolCallId === pending.callId)
245
+ return message.isError !== true;
187
246
  }
247
+ cursor = page.next;
248
+ } while (cursor !== undefined);
249
+ return false;
250
+ });
251
+ }
252
+ /** The cut a call answers for. In this process an entry is in flight or answered, never cut; one an earlier process
253
+ * wrote is a cut unless its action finished and pi committed its answer, which only then is looked up. */
254
+ async function cutOf(c, scope, pending) {
255
+ if (!pending || pending.incarnation === c.incarnation)
256
+ return null;
257
+ if (!pending.finished || pending.told || !(await answered(scope, pending)))
258
+ return pending;
259
+ await clearJournal(c, scope, pending.callId);
260
+ return null;
261
+ }
262
+ async function relaunchOn(c, scope, api, slot, overrides) {
263
+ const config = await configOf(c, scope.read, scope.cid, scope.context);
264
+ const refusal = relaunchRefusal(config.policy, overrides);
265
+ if (refusal)
266
+ throw new BrowserFailureError(refusal);
267
+ // The relaunch's session is chosen in a memo before its create commits: a rerun runs on it or says
268
+ // session_replaced, never a second launch; a memo with no record yet is an uncommitted create and goes ahead.
269
+ const find = async (tag) => (await stateOf(c, scope)).sessions.find((r) => r.tag === tag);
270
+ const launched = await api.memo(slot, scope.context);
271
+ let mine = await find(launched);
272
+ if (mine) {
273
+ if (mine.state === "creating") {
274
+ await settleCreating(c, scope, mine);
275
+ mine = await find(launched);
188
276
  }
189
- throw new Error(`browser custody for conversation ${scope.cid} did not settle`);
190
- }
191
- /** Custody's notice is kept in the call's memo before it is cleared, so a call rerun after a crash still tells it. */
192
- async function attached(scope, record, driver, note) {
193
- const state = await stateOf(scope);
194
- const notice = await scope.keep("notice", [note, state.notice].filter(Boolean).join(" "));
195
- if (state.notice !== null)
196
- await scope.commit(async (tx) => { (await tx.doc(Sessions, scope.cid)).notice = null; });
197
- const fresh = state.sessions.find((r) => r.tag === record.tag) ?? record;
198
- const interrupted = [...state.sessions].reverse().find((r) => r.plane === scope.plane && r.pendingEffect !== null)?.pendingEffect ?? null;
199
- const recorded = Boolean((await providerOf(scope.read, scope.cid, scope.plane, scope.context)).recordings);
200
- return { driver, tag: record.tag, sessionId: fresh.resourceId, record: fresh, notice: notice || null, interrupted, recorded, effects: observers.get(record.tag) ?? null };
277
+ const driver = mine?.state === "live" ? await attachLive(c, scope, mine) : null;
278
+ if (!mine || !driver)
279
+ throw new BrowserFailureError(SESSION_REPLACED);
280
+ return attached(c, scope, mine, driver, null);
201
281
  }
202
- async function releaseRecord(scope, record, reason) {
203
- await scope.commit((tx) => requestRelease(tx, rowOf(scope.cid, record), reason, now()));
204
- await detach(record.tag);
205
- }
206
- const editRecords = (scope, edit) => scope.commit(async (tx) => { const state = await tx.doc(Sessions, scope.cid); edit(state.sessions.filter((r) => r.plane === scope.plane), state); });
207
- function portFor(api, context) {
208
- const memo = (slot) => `${name}:${slot}:${PLANE}`;
209
- const scope = { cid: api.conversationId, plane: PLANE, context, read: api, signal: context.abortSignal ?? new AbortController().signal, commit: (change) => api.commit(change, context), keep: async (slot, value) => {
210
- // An earlier attempt's text comes first; an empty one is never memoized, so it cannot shadow a later notice.
211
- const prior = await api.memo(memo(slot), context);
212
- if (prior !== undefined)
213
- return [prior, value].filter(Boolean).join(" ");
214
- return value ? api.memo(memo(slot), value, context) : "";
215
- } };
216
- const key = `${scope.cid}:${scope.plane}`;
217
- return {
218
- session: () => serialize(key, async () => {
219
- const ran = await api.memo(memo("ran"), context);
220
- if (ran !== undefined) {
221
- const record = (await stateOf(scope)).sessions.find((r) => r.tag === ran);
222
- const driver = record?.state === "live" ? await attachLive(scope, record) : null;
223
- if (!record || !driver)
224
- throw new BrowserFailureError(SESSION_REPLACED);
225
- return attached(scope, record, driver, null);
226
- }
227
- const { record, driver, note } = await acquire(scope);
228
- await api.memo(memo("ran"), record.tag, context);
229
- return attached(scope, record, driver, note);
230
- }),
231
- relaunch: (overrides) => serialize(key, async () => {
232
- const config = await configOf(scope.read, scope.cid, scope.context);
233
- const refusal = relaunchRefusal(config.policy, overrides);
234
- if (refusal)
235
- throw new BrowserFailureError(refusal);
236
- // The relaunch's session is chosen in a memo before its create commits: a rerun runs on it or says
237
- // session_replaced, never a second launch; a memo with no record yet is an uncommitted create and goes ahead.
238
- const find = async (tag) => (await stateOf(scope)).sessions.find((r) => r.tag === tag);
239
- const launched = await api.memo(memo("relaunch"), context);
240
- let mine = await find(launched);
241
- if (mine) {
242
- if (mine.state === "creating") {
243
- await settleCreating(scope, mine);
244
- mine = await find(launched);
245
- }
246
- const driver = mine?.state === "live" ? await attachLive(scope, mine) : null;
247
- if (!mine || !driver)
248
- throw new BrowserFailureError(SESSION_REPLACED);
249
- return attached(scope, mine, driver, null);
250
- }
251
- const state = await stateOf(scope);
252
- const tag = launched ?? await api.memo(memo("relaunch"), leaseTag("ar", config.run, scope.cid, state.sessions.length + 1), context);
253
- const old = currentRecord(state, scope.plane);
254
- if (old && open(old) && old.tag !== tag)
255
- await releaseRecord(scope, old, "relaunch");
256
- const made = await create(scope, overrides, tag);
257
- return attached(scope, made.record, made.driver, null);
258
- }),
259
- release: () => serialize(key, async () => {
260
- const record = currentRecord(await stateOf(scope), scope.plane);
261
- if (!record || !open(record))
262
- return { released: record?.state === "releasing", sessionId: record?.resourceId ?? null };
263
- await releaseRecord(scope, record, "tool");
264
- return { released: true, sessionId: record.resourceId };
265
- }),
266
- dispatching: (effect) => editRecords(scope, (records, state) => {
282
+ const state = await stateOf(c, scope);
283
+ const tag = launched ?? await api.memo(slot, leaseTag("ar", config.run, scope.cid, state.sessions.length + 1), scope.context);
284
+ const old = currentRecord(state, scope.plane);
285
+ if (old && open(old) && old.tag !== tag)
286
+ await releaseRecord(c, scope, old, "relaunch");
287
+ const made = await create(c, scope, overrides, tag);
288
+ return attached(c, scope, made.record, made.driver, null);
289
+ }
290
+ function portFor(c, api, context) {
291
+ const memo = (slot) => `${c.name}:${slot}:${PLANE}`;
292
+ const scope = { cid: api.conversationId, plane: PLANE, context, read: api, signal: context.abortSignal ?? new AbortController().signal, commit: (change) => api.commit(change, context), keep: async (slot, value) => {
293
+ // An earlier attempt's text comes first; an empty one is never memoized, so it cannot shadow a later notice.
294
+ const prior = await api.memo(memo(slot), context);
295
+ if (prior !== undefined)
296
+ return [prior, value].filter(Boolean).join(" ");
297
+ return value ? api.memo(memo(slot), value, context) : "";
298
+ } };
299
+ const key = `${scope.cid}:${scope.plane}`;
300
+ return {
301
+ session: () => c.serial.run(key, async () => {
302
+ const ran = await api.memo(memo("ran"), context);
303
+ if (ran !== undefined) {
304
+ const record = (await stateOf(c, scope)).sessions.find((r) => r.tag === ran);
305
+ const driver = record?.state === "live" ? await attachLive(c, scope, record) : null;
306
+ if (!record || !driver)
307
+ throw new BrowserFailureError(SESSION_REPLACED);
308
+ return attached(c, scope, record, driver, null);
309
+ }
310
+ const { record, driver, note } = await acquire(c, scope);
311
+ await api.memo(memo("ran"), record.tag, context);
312
+ return attached(c, scope, record, driver, note);
313
+ }),
314
+ relaunch: (overrides) => c.serial.run(key, () => relaunchOn(c, scope, api, memo("relaunch"), overrides)),
315
+ release: () => c.serial.run(key, async () => {
316
+ const record = currentRecord(await stateOf(c, scope), scope.plane);
317
+ if (!record || !open(record))
318
+ return { released: record?.state === "releasing", sessionId: record?.resourceId ?? null };
319
+ await releaseRecord(c, scope, record, "tool");
320
+ return { released: true, sessionId: record.resourceId };
321
+ }),
322
+ dispatching: (effect) => scope.commit(async (tx) => {
323
+ const record = currentRecord(await tx.doc(c.Sessions, scope.cid), scope.plane);
324
+ if (!record)
325
+ return;
326
+ const newest = (await tx.scanEntries({ conversationId: scope.cid, order: "descending" }, 1)).items[0]?.id;
327
+ record.pendingEffect = { ...effect, url: effect.url === null ? null : scrubPageUrl(effect.url, c.redact), at: now(), sent: [], incarnation: c.incarnation, ...(newest === undefined ? {} : { after: newest }) };
328
+ }),
329
+ journal: (row) => editState(c, scope, (state) => {
330
+ const pending = currentRecord(state, scope.plane)?.pendingEffect;
331
+ if (!pending)
332
+ return;
333
+ const sent = pending.sent ?? (pending.sent = []);
334
+ const scrubbed = { ...row, origin: c.redact(row.origin), path: c.redact(row.path) };
335
+ const at = sent.findIndex((r) => r.requestId === row.requestId);
336
+ if (at === -1)
337
+ sent.push(scrubbed);
338
+ else
339
+ sent[at] = scrubbed;
340
+ }),
341
+ mark: (step, callId) => editState(c, scope, (state) => {
342
+ const pending = state.sessions.find((r) => r.plane === scope.plane && r.pendingEffect?.callId === callId)?.pendingEffect;
343
+ if (pending)
344
+ pending[step] = true;
345
+ }),
346
+ settle: (callId) => clearJournal(c, scope, callId),
347
+ navigated: async (page) => {
348
+ // A page URL can carry a credential in any query value, its fragment or its userinfo: scrubbed before it is
349
+ // committed or reported.
350
+ const url = scrubPageUrl(page, c.redact);
351
+ await editState(c, scope, (state) => {
267
352
  const record = currentRecord(state, scope.plane);
268
- if (record)
269
- record.pendingEffect = { ...effect, url: effect.url === null ? null : scrubPageUrl(effect.url, redact), at: now(), sent: [] };
270
- }),
271
- journal: (row) => editRecords(scope, (records, state) => {
272
- const pending = currentRecord(state, scope.plane)?.pendingEffect;
273
- if (!pending)
274
- return;
275
- const sent = pending.sent ?? (pending.sent = []);
276
- const scrubbed = { ...row, origin: redact(row.origin), path: redact(row.path) };
277
- const at = sent.findIndex((r) => r.requestId === row.requestId);
278
- if (at === -1)
279
- sent.push(scrubbed);
280
- else
281
- sent[at] = scrubbed;
282
- }),
283
- settle: async () => {
284
- if (!(await stateOf(scope)).sessions.some((r) => r.plane === scope.plane && r.pendingEffect !== null))
353
+ if (!record)
285
354
  return;
286
- await editRecords(scope, (records) => { for (const record of records)
287
- record.pendingEffect = null; });
288
- },
289
- navigated: async (page) => {
290
- // A page URL can carry a credential in any query value, its fragment or its userinfo: scrubbed before it is
291
- // committed or reported.
292
- const url = scrubPageUrl(page, redact);
293
- await editRecords(scope, (records, state) => {
294
- const record = currentRecord(state, scope.plane);
295
- if (!record)
296
- return;
297
- record.navigation.push({ at: now(), url });
298
- if (record.navigation.length > NAVIGATION_CAP)
299
- record.navigation.splice(0, record.navigation.length - NAVIGATION_CAP);
300
- record.lastUrl = url;
301
- });
302
- const record = currentRecord(await stateOf(scope), scope.plane);
303
- if (record)
304
- await emit(scope.cid, (await configOf(scope.read, scope.cid, scope.context)).label, record, "updated", await providerOf(scope.read, scope.cid, scope.plane, scope.context));
305
- },
306
- dropped: () => serialize(key, async () => {
307
- const record = currentRecord(await stateOf(scope), scope.plane);
308
- if (record)
309
- await detachDriver(record.tag);
310
- }),
311
- ended: async () => {
312
- const record = currentRecord(await stateOf(scope), scope.plane);
313
- if (record?.state !== "live")
314
- return false;
315
- return markEnded(scope, record, await providerOf(scope.read, scope.cid, scope.plane, scope.context));
316
- },
317
- };
318
- }
319
- /** A plane nobody calls for its idle window is released, never mid-call. A dead process's timers die with it, and the
320
- * provider's own idle bound takes over. */
321
- async function releaseIdle(cid, fired, idleMs) {
322
- const conversation = opened && await opened.harness.conversation(cid, opened.context);
323
- if (!conversation)
324
- return;
325
- // Only the still-current timer releases, checked inside the commit: a call since, even one that ran while the
326
- // lookup above waited, replaced it.
327
- await releasePlane(conversation, "idle", opened.context, () => idle.isCurrent(cid, fired), Math.round(idleMs / 1000));
328
- }
329
- /** A release the model did not ask for (idle, close) commits its notice with it, so whichever call next attaches a
330
- * session tells it, even when the call that opened the replacement failed or died. */
331
- async function releasePlane(conversation, reason, context, still = () => true, idleS = 0) {
332
- const key = `${conversation.id}:${PLANE}`;
333
- const released = await serialize(key, async () => {
334
- const tags = await conversation.commit(async (tx) => {
335
- const state = await tx.doc(Sessions, conversation.id);
336
- const record = still() ? currentRecord(state, PLANE) : null;
337
- if (!record || !open(record))
338
- return [];
339
- await requestRelease(tx, rowOf(conversation.id, record), reason, now());
340
- if (reason === "idle" || reason === "close")
341
- addNotice(state, notices.released(reason, record.lastUrl, idleS));
342
- return [record.tag];
343
- }, context);
344
- for (const tag of tags)
345
- await detach(tag);
346
- return tags.length > 0;
347
- });
348
- if (released)
349
- idle.cancel(conversation.id);
350
- }
351
- async function chargeCall(api, context) {
352
- if (currentRecord(await api.snapshot(Sessions, api.conversationId, context), PLANE)?.state !== "live")
353
- return null;
354
- return api.commit(async (tx) => {
355
- const record = currentRecord(await tx.doc(Sessions, api.conversationId), PLANE);
355
+ record.navigation.push({ at: now(), url });
356
+ if (record.navigation.length > NAVIGATION_CAP)
357
+ record.navigation.splice(0, record.navigation.length - NAVIGATION_CAP);
358
+ record.lastUrl = url;
359
+ });
360
+ const record = currentRecord(await stateOf(c, scope), scope.plane);
361
+ if (record)
362
+ await emit(c, scope.cid, (await configOf(c, scope.read, scope.cid, scope.context)).label, record, "updated", await providerOf(c, scope.read, scope.cid, scope.plane, scope.context));
363
+ },
364
+ dropped: () => c.serial.run(key, async () => {
365
+ const record = currentRecord(await stateOf(c, scope), scope.plane);
366
+ if (record)
367
+ await c.held.detachDriver(record.tag);
368
+ }),
369
+ ended: async () => {
370
+ const record = currentRecord(await stateOf(c, scope), scope.plane);
356
371
  if (record?.state !== "live")
357
- return null;
358
- const { spent, usage } = meter(record.spent, now());
359
- record.spent = spent;
360
- return usage;
372
+ return false;
373
+ return markEnded(c, scope, record, await providerOf(c, scope.read, scope.cid, scope.plane, scope.context));
374
+ },
375
+ };
376
+ }
377
+ /** A plane nobody calls for its idle window is released, never mid-call. A dead process's timers die with it, and the
378
+ * provider's own idle bound takes over. */
379
+ async function releaseIdle(c, cid, fired, idleMs) {
380
+ const conversation = c.opened && await c.opened.harness.conversation(cid, c.opened.context);
381
+ if (!conversation)
382
+ return;
383
+ // Only the still-current timer releases, checked inside the commit: a call since, even one that ran while the
384
+ // lookup above waited, replaced it.
385
+ await releasePlane(c, conversation, "idle", c.opened.context, () => c.idle.isCurrent(cid, fired), Math.round(idleMs / 1000));
386
+ }
387
+ /** A release the model did not ask for (idle, close) commits its notice with it, so whichever call next attaches a
388
+ * session tells it, even when the call that opened the replacement failed or died. */
389
+ async function releasePlane(c, conversation, reason, context, still = () => true, idleS = 0) {
390
+ const key = `${conversation.id}:${PLANE}`;
391
+ const released = await c.serial.run(key, async () => {
392
+ const tags = await conversation.commit(async (tx) => {
393
+ const state = await tx.doc(c.Sessions, conversation.id);
394
+ const record = still() ? currentRecord(state, PLANE) : null;
395
+ if (!record || !open(record))
396
+ return [];
397
+ await c.store.requestRelease(tx, rowOf(conversation.id, record), reason, now());
398
+ if (reason === "idle" || reason === "close")
399
+ c.store.addNotice(state, notices.released(reason, record.lastUrl, idleS));
400
+ return [record.tag];
361
401
  }, context);
402
+ for (const tag of tags)
403
+ await c.held.detach(tag);
404
+ return tags.length > 0;
405
+ });
406
+ if (reason === "close") {
407
+ c.idle.forget(conversation.id);
408
+ c.guards.delete(conversation.id);
362
409
  }
363
- const withSessionTime = (own, charged) => {
364
- if (!charged)
365
- return own;
366
- const ownCost = (own?.cost ?? {});
367
- return { ...charged.usage, ...own, cost: { ...charged.usage.cost, ...ownCost, total: charged.usage.cost.total + (ownCost.total ?? 0) } };
368
- };
369
- const impls = { ...custodyTools, ...pageTools(), ...options.tools };
370
- const tools = BROWSER_TOOLS
371
- .filter((contract) => impls[contract.name] && (contract.listedWhen !== "downloads" || options.workspace))
410
+ else if (released)
411
+ c.idle.cancel(conversation.id);
412
+ }
413
+ async function chargeCall(c, api, context) {
414
+ if (currentRecord(await api.snapshot(c.Sessions, api.conversationId, context), PLANE)?.state !== "live")
415
+ return null;
416
+ return api.commit(async (tx) => {
417
+ const record = currentRecord(await tx.doc(c.Sessions, api.conversationId), PLANE);
418
+ if (record?.state !== "live")
419
+ return null;
420
+ const { spent, usage } = c.meter(record.spent, now());
421
+ record.spent = spent;
422
+ return usage;
423
+ }, context);
424
+ }
425
+ const withSessionTime = (own, charged) => {
426
+ if (!charged)
427
+ return own;
428
+ const ownCost = (own?.cost ?? {});
429
+ return { ...charged.usage, ...own, cost: { ...charged.usage.cost, ...ownCost, total: charged.usage.cost.total + (ownCost.total ?? 0) } };
430
+ };
431
+ function toolsFor(c, impls) {
432
+ return BROWSER_TOOLS
433
+ .filter((contract) => impls[contract.name] && (contract.listedWhen !== "downloads" || c.options.workspace))
372
434
  .map((contract) => defineTool({
373
435
  name: contract.name,
374
436
  description: contract.description,
@@ -376,45 +438,57 @@ export function createBrowserExtension(options) {
376
438
  replay: contract.replay,
377
439
  executionMode: contract.executionMode,
378
440
  execute: async (args, api, context) => {
379
- const config = await api.snapshot(Config, api.conversationId, context);
380
- idle.activity(api.conversationId, +1, (config?.policy.idleReleaseS ?? 0) * 1000);
441
+ const config = await api.snapshot(c.Config, api.conversationId, context);
442
+ c.idle.activity(api.conversationId, +1, (config?.policy.idleReleaseS ?? 0) * 1000);
381
443
  try {
382
- const call = { callId: api.callId, conversationId: api.conversationId, signal: context.abortSignal, label: config?.label ?? "", redact, evidence: options.evidence, classifyPage: options.decisions?.classifyPage };
444
+ const call = { callId: api.callId, conversationId: api.conversationId, signal: context.abortSignal, label: config?.label ?? "", redact: c.redact, evidence: c.options.evidence, classifyPage: c.options.decisions?.classifyPage };
383
445
  // Inside an async function, so a host tool that throws before it returns a promise is caught too.
384
- const out = await (async () => impls[contract.name](args, portFor(api, context), call))().catch((error) => {
446
+ const out = await (async () => impls[contract.name](args, portFor(c, api, context), call))().catch((error) => {
385
447
  // A throw would reach pi's diagnostic unscrubbed: every failure comes back as the typed envelope, redacted.
386
448
  const typed = error instanceof BrowserFailureError ? error.failure : classifyBrowserError(error, contract.effect === "effect", { aborted: context.abortSignal?.aborted === true });
387
449
  return { content: [{ type: "text", text: JSON.stringify(typed) }], isError: true };
388
450
  });
389
451
  // A charge that cannot be committed now is carried by the next one.
390
- const usage = withSessionTime(out.usage, await chargeCall(api, context).catch(() => null));
452
+ const usage = withSessionTime(out.usage, await chargeCall(c, api, context).catch(() => null));
391
453
  return {
392
- ...forModel(out.content.map((item) => item.type === "text" ? { ...item, text: redact(item.text) } : item)),
454
+ ...forModel(out.content.map((item) => item.type === "text" ? { ...item, text: c.redact(item.text) } : item)),
393
455
  ...(out.isError ? { isError: true } : {}),
394
- ...(out.details ? { details: redactDeep(out.details, redact) } : {}),
456
+ ...(out.details ? { details: redactDeep(out.details, c.redact) } : {}),
395
457
  ...(usage ? { usage: usage } : {}),
396
458
  };
397
459
  }
398
460
  finally {
399
- idle.activity(api.conversationId, -1);
461
+ c.idle.activity(api.conversationId, -1);
400
462
  }
401
463
  },
402
464
  }));
403
- const names = new Set(tools.map((tool) => tool.name));
404
- const childConversation = (api, context) => async (task) => {
405
- const config = await api.snapshot(Config, api.conversationId, context);
465
+ }
466
+ function sectionFor(c, names) {
467
+ return {
468
+ key: c.name,
469
+ async render(input, context) {
470
+ if (!input.agent.tools.some((tool) => names.has(tool.name)))
471
+ return undefined;
472
+ const config = await input.read.snapshot(c.Config, input.conversationId, context);
473
+ return [browserSection({ idleReleaseS: config?.policy.idleReleaseS ?? UNCONFIGURED.policy.idleReleaseS }), c.options.section?.addendum].filter(Boolean).join("\n\n");
474
+ },
475
+ };
476
+ }
477
+ function childConversation(c, api, context) {
478
+ return async (task) => {
479
+ const config = await api.snapshot(c.Config, api.conversationId, context);
406
480
  const childTools = (await api.agent(context)).tools.filter((tool) => CHILD_TOOLS.has(tool.name));
407
481
  // One child per request, recorded in the commit that creates it: a replay or a repeated call finds it again, and
408
482
  // its submission is deduplicated by request_id.
409
483
  const id = await api.commit(async (tx) => {
410
- const children = await tx.doc(Children, api.conversationId);
484
+ const children = await tx.doc(c.Children, api.conversationId);
411
485
  const key = `${task.site}:${task.requestId}`;
412
486
  const known = children.byRequest[key];
413
487
  if (known !== undefined)
414
488
  return known;
415
489
  const child = await tx.createConversation({ ownership: { kind: "task", taskId: api.taskId } });
416
490
  await configure(tx, child.id, { tools: childTools, instructions: null });
417
- Object.assign(await tx.doc(Config, child.id), config ?? UNCONFIGURED);
491
+ Object.assign(await tx.doc(c.Config, child.id), config ?? UNCONFIGURED);
418
492
  children.byRequest[key] = child.id;
419
493
  return child.id;
420
494
  }, context);
@@ -440,45 +514,69 @@ export function createBrowserExtension(options) {
440
514
  return report;
441
515
  }
442
516
  finally {
443
- await releasePlane({ id, commit: (change, ctx) => api.commit(change, ctx) }, "close", context).catch(() => undefined);
517
+ await releasePlane(c, { id, commit: (change, ctx) => api.commit(change, ctx) }, "close", context).catch(() => undefined);
444
518
  }
445
519
  };
446
- const siteTools = options.sites ? [((sites) => {
447
- const contract = useWebsiteContract(sites.listing);
448
- return defineTool({
449
- name: contract.name,
450
- description: contract.description,
451
- parameters: contract.parameters,
452
- replay: contract.replay,
453
- executionMode: contract.executionMode,
454
- execute: async (args, api, context) => {
455
- const out = await useWebsite(args, sites.port, sites.listing, { signal: context.abortSignal ?? new AbortController().signal, runChild: childConversation(api, context) });
456
- return { ...forModel(out.content.map((item) => item.type === "text" ? { ...item, text: redact(item.text) } : item)), ...(out.isError ? { isError: true } : {}) };
457
- },
458
- });
459
- })(options.sites)] : [];
460
- const section = {
461
- key: name,
462
- async render(input, context) {
463
- if (!input.agent.tools.some((tool) => names.has(tool.name)))
464
- return undefined;
465
- const config = await input.read.snapshot(Config, input.conversationId, context);
466
- return [browserSection({ idleReleaseS: config?.policy.idleReleaseS ?? UNCONFIGURED.policy.idleReleaseS }), options.section?.addendum].filter(Boolean).join("\n\n");
520
+ }
521
+ function siteTool(c, sites) {
522
+ const contract = useWebsiteContract(sites.listing);
523
+ return defineTool({
524
+ name: contract.name,
525
+ description: contract.description,
526
+ parameters: contract.parameters,
527
+ replay: contract.replay,
528
+ executionMode: contract.executionMode,
529
+ execute: async (args, api, context) => {
530
+ const out = await useWebsite(args, sites.port, sites.listing, { signal: context.abortSignal ?? new AbortController().signal, runChild: childConversation(c, api, context) });
531
+ return { ...forModel(out.content.map((item) => item.type === "text" ? { ...item, text: c.redact(item.text) } : item)), ...(out.isError ? { isError: true } : {}) };
467
532
  },
533
+ });
534
+ }
535
+ export function createBrowserExtension(options) {
536
+ const name = options.name ?? "browser";
537
+ const redact = createRedactor(() => providerKeyValues(process.env, options.redact?.values));
538
+ const Config = defineDoc({ kind: `${name}.config`, version: 1, scope: "conversation", history: "latest", fork: "current", initial: () => structuredClone(UNCONFIGURED) });
539
+ const Children = defineDoc({ kind: `${name}.children`, version: 1, scope: "conversation", history: "latest", fork: "current", initial: () => ({ byRequest: {} }) });
540
+ // A fork starts with no sessions: it never shares a live browser.
541
+ const Sessions = defineDoc({ kind: `${name}.sessions`, version: 1, scope: "conversation", history: "latest", fork: "initial", initial: emptySessions });
542
+ const readers = { options, redact, Config };
543
+ /** Class name and redacted message only: a vendor SDK's error text can repeat the request's credentials. */
544
+ const scrubbed = (error) => Object.assign(new Error(redact(error instanceof Error ? error.message : String(error))), { name: error instanceof Error ? error.name : "Error" });
545
+ const prices = resolvePrices(options.prices);
546
+ const priceState = prices.sessionUsdPerHour === null ? "unpriced" : "priced";
547
+ const meter = (spent, at, final = false) => {
548
+ const charged = sessionCharge(spent, at, prices, priceState, final);
549
+ return { spent: { ...charged.spent, state: charged.usage.state }, usage: charged.usage };
550
+ };
551
+ const store = custodyStore({
552
+ name, Config, Sessions, meter, scrubbed, createDeadlineMs: options.createDeadlineMs ?? CREATE_DEADLINE_MS,
553
+ providerOf: (read, cid, plane, context) => providerOf(readers, read, cid, plane, context),
554
+ emit: (cid, label, record, change) => emit(readers, cid, label, record, change),
555
+ });
556
+ const c = {
557
+ ...readers, name, Sessions, Children, store, meter, held: new Attachments(), serial: keyedSerializer(), guards: new Map(), opened: null, incarnation: randomUUID(),
558
+ idle: idleTracker({ idleMs: DEFAULT_BROWSER_POLICY.idleReleaseS * 1000, onIdle: (cid, fired, idleMs) => void releaseIdle(c, cid, fired, idleMs).catch(() => undefined) }),
468
559
  };
560
+ const own = { ...custodyTools, ...pageTools({ guards: c.guards }), ...options.tools };
561
+ // pi checks a call's arguments against the tool's schema before execute, so each implementation receives its own shape.
562
+ const tools = toolsFor(c, own);
563
+ const names = new Set(tools.map((tool) => tool.name));
564
+ const siteTools = options.sites ? [siteTool(c, options.sites)] : [];
469
565
  return {
470
- extension: defineExtension({ name, tools: [...tools, ...siteTools], sections: [section], tasks: [ReleaseTask] }),
471
- docs: { Config, Sessions, Inventory, Children },
566
+ extension: defineExtension({ name, tools: [...tools, ...siteTools], sections: [sectionFor(c, names)], tasks: [store.ReleaseTask] }),
567
+ docs: { Config, Sessions, Inventory: store.Inventory, Children },
472
568
  tools: [...tools, ...siteTools],
473
- release: (conversation, reason, context) => releasePlane(conversation, reason, context),
569
+ release: (conversation, reason, context) => releasePlane(c, conversation, reason, context),
474
570
  async reconcile(harness, isActive, context) {
475
- opened = { harness, context };
476
- return reconcileAll(harness, isActive, context);
571
+ c.opened = { harness, context };
572
+ return store.reconcileAll(harness, isActive, context);
477
573
  },
574
+ drain: (harness, context, signal) => drainReleases(name, harness, context, signal),
478
575
  async close() {
479
- idle.clear();
576
+ c.idle.clear();
480
577
  // A session whose driver was let go and not yet replaced still has its observer attached: close both kinds.
481
- await Promise.all([...new Set([...attachments.keys(), ...observers.keys()])].map(detach));
578
+ await Promise.all(c.held.tags().map((tag) => c.held.detach(tag)));
482
579
  },
580
+ retained: () => new Set([...c.guards.keys(), ...c.idle.keys(), ...c.serial.keys().map((key) => Number(key.slice(0, key.indexOf(":"))))]).size,
483
581
  };
484
582
  }