@parcha/pi-browser 0.0.0-stage → 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.
Files changed (108) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +33 -0
  4. package/README.md +348 -2
  5. package/dist/coding-agent-local.d.ts +16 -0
  6. package/dist/coding-agent-local.js +138 -0
  7. package/dist/coding-agent.d.ts +79 -0
  8. package/dist/coding-agent.js +448 -0
  9. package/dist/core/contract.d.ts +26 -0
  10. package/dist/core/contract.js +154 -0
  11. package/dist/core/custody.d.ts +117 -0
  12. package/dist/core/custody.js +126 -0
  13. package/dist/core/decisions.d.ts +43 -0
  14. package/dist/core/decisions.js +4 -0
  15. package/dist/core/downloads.d.ts +35 -0
  16. package/dist/core/downloads.js +131 -0
  17. package/dist/core/effects.d.ts +63 -0
  18. package/dist/core/effects.js +256 -0
  19. package/dist/core/evidence.d.ts +43 -0
  20. package/dist/core/evidence.js +6 -0
  21. package/dist/core/failures.d.ts +36 -0
  22. package/dist/core/failures.js +68 -0
  23. package/dist/core/find.d.ts +32 -0
  24. package/dist/core/find.js +179 -0
  25. package/dist/core/guard.d.ts +6 -0
  26. package/dist/core/guard.js +25 -0
  27. package/dist/core/host.d.ts +328 -0
  28. package/dist/core/host.js +2 -0
  29. package/dist/core/images.d.ts +37 -0
  30. package/dist/core/images.js +60 -0
  31. package/dist/core/lease.d.ts +16 -0
  32. package/dist/core/lease.js +30 -0
  33. package/dist/core/receipts.d.ts +19 -0
  34. package/dist/core/receipts.js +22 -0
  35. package/dist/core/redact.d.ts +13 -0
  36. package/dist/core/redact.js +83 -0
  37. package/dist/core/session-control.d.ts +25 -0
  38. package/dist/core/session-control.js +75 -0
  39. package/dist/core/sites.d.ts +33 -0
  40. package/dist/core/sites.js +102 -0
  41. package/dist/core/tools.d.ts +72 -0
  42. package/dist/core/tools.js +200 -0
  43. package/dist/core/uri.d.ts +11 -0
  44. package/dist/core/uri.js +37 -0
  45. package/dist/core/usage.d.ts +19 -0
  46. package/dist/core/usage.js +44 -0
  47. package/dist/core/web.d.ts +98 -0
  48. package/dist/core/web.js +327 -0
  49. package/dist/driver/extension-worker.d.ts +6 -0
  50. package/dist/driver/extension-worker.js +121 -0
  51. package/dist/driver/stagehand.d.ts +25 -0
  52. package/dist/driver/stagehand.js +91 -0
  53. package/dist/durable-result.d.ts +6 -0
  54. package/dist/durable-result.js +2 -0
  55. package/dist/durable.d.ts +79 -0
  56. package/dist/durable.js +582 -0
  57. package/dist/index.d.ts +19 -0
  58. package/dist/index.js +20 -0
  59. package/dist/providers/browserbase-net.d.ts +13 -0
  60. package/dist/providers/browserbase-net.js +96 -0
  61. package/dist/providers/browserbase.d.ts +152 -0
  62. package/dist/providers/browserbase.js +262 -0
  63. package/dist/providers/cdp-call.d.ts +6 -0
  64. package/dist/providers/cdp-call.js +25 -0
  65. package/dist/providers/cdp.d.ts +55 -0
  66. package/dist/providers/cdp.js +423 -0
  67. package/dist/providers/http.d.ts +2 -0
  68. package/dist/providers/http.js +21 -0
  69. package/dist/providers/kernel.d.ts +49 -0
  70. package/dist/providers/kernel.js +246 -0
  71. package/dist/providers/shared.d.ts +47 -0
  72. package/dist/providers/shared.js +82 -0
  73. package/dist/recorder/credential.d.ts +9 -0
  74. package/dist/recorder/credential.js +49 -0
  75. package/dist/recorder/follow.d.ts +26 -0
  76. package/dist/recorder/follow.js +138 -0
  77. package/dist/recorder/frames.d.ts +80 -0
  78. package/dist/recorder/frames.js +309 -0
  79. package/dist/recorder/index.d.ts +4 -0
  80. package/dist/recorder/index.js +7 -0
  81. package/dist/recorder/jpeg.d.ts +8 -0
  82. package/dist/recorder/jpeg.js +70 -0
  83. package/dist/recorder/track.d.ts +107 -0
  84. package/dist/recorder/track.js +259 -0
  85. package/dist/store.d.ts +56 -0
  86. package/dist/store.js +196 -0
  87. package/dist/testing/backend.d.ts +231 -0
  88. package/dist/testing/backend.js +414 -0
  89. package/dist/testing/driver.d.ts +28 -0
  90. package/dist/testing/driver.js +32 -0
  91. package/dist/testing/index.d.ts +4 -0
  92. package/dist/testing/index.js +4 -0
  93. package/dist/testing/pages.d.ts +3 -0
  94. package/dist/testing/pages.js +10 -0
  95. package/dist/testing/sentinels.d.ts +29 -0
  96. package/dist/testing/sentinels.js +38 -0
  97. package/dist/vendor/stagehand-facade/contract.d.ts +348 -0
  98. package/dist/vendor/stagehand-facade/contract.js +155 -0
  99. package/dist/vendor/stagehand-facade/runtime.d.ts +90 -0
  100. package/dist/vendor/stagehand-facade/runtime.js +1640 -0
  101. package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +15 -0
  102. package/dist/vendor/stagehand-facade/screenshot-transport.js +51 -0
  103. package/dist/vendor/stagehand-facade/tools.d.ts +31 -0
  104. package/dist/vendor/stagehand-facade/tools.js +139 -0
  105. package/dist/web.d.ts +41 -0
  106. package/dist/web.js +38 -0
  107. package/package.json +123 -4
  108. package/src/vendor/stagehand-facade/UPSTREAM.json +24 -0
@@ -0,0 +1,259 @@
1
+ import { spawn } from "node:child_process";
2
+ import { createHash } from "node:crypto";
3
+ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
4
+ import os from "node:os";
5
+ import path from "node:path";
6
+ import { jpegSampling, jpegSize } from "./jpeg.js";
7
+ export class TrackExportError extends Error {
8
+ code;
9
+ constructor(code, message) {
10
+ super(message);
11
+ this.name = "TrackExportError";
12
+ this.code = code;
13
+ }
14
+ }
15
+ const even = (n) => (n % 2 === 0 ? n : n + 1);
16
+ /** The timeline of one session's lines. Each frame is shown until the next one; a gap puts the slate up (from the moment it was written, except
17
+ * `process_killed`, which starts at the last frame the earlier process saved: nothing is known after it) until the next frame or the end.
18
+ * Null when the session has no frame. `skip` names frames whose picture could not be read: they show the slate and are not listed. */
19
+ export function planTrack(lines, options = {}) {
20
+ const fps = options.fps ?? 10;
21
+ const one = Math.max(1, Math.round(1000 / fps));
22
+ const rows = [...lines].map((row, order) => ({ row: row, order })).filter(({ row }) => (row.kind === "frame" || row.kind === "frame.gap") && typeof row.t === "number" && row.data && typeof row.data.session === "string");
23
+ const byTime = [...rows].sort((a, b) => a.row.t - b.row.t || a.order - b.order);
24
+ const first = byTime.find(({ row }) => row.kind === "frame");
25
+ if (!first)
26
+ return null;
27
+ const session = first.row.data.session;
28
+ const events = byTime.filter(({ row }) => row.data.session === session);
29
+ const from = first.row.t;
30
+ const segments = [];
31
+ const frames = [];
32
+ const gaps = [];
33
+ const state = { current: null, gap: null };
34
+ const close = (at) => {
35
+ const cur = state.current;
36
+ if (cur && at > cur.start)
37
+ segments.push({ start: cur.start, end: at, sha256: cur.sha256, ...(cur.reason ? { reason: cur.reason } : {}) });
38
+ state.current = null;
39
+ };
40
+ const closeGap = (at) => { if (state.gap)
41
+ gaps.push({ ...state.gap, to: at }); state.gap = null; };
42
+ let last = from;
43
+ for (const { row } of events) {
44
+ const t = row.t;
45
+ last = Math.max(last, t);
46
+ if (t < from)
47
+ continue; // a gap written before the first frame has no place in the track
48
+ if (row.kind === "frame") {
49
+ const sha = row.blobs?.[0] ?? "";
50
+ close(t);
51
+ closeGap(t);
52
+ if (options.skip?.has(sha)) {
53
+ state.current = { start: t, sha256: null, reason: "frame_unreadable" };
54
+ state.gap = { from: t, reason: "frame_unreadable" };
55
+ }
56
+ else {
57
+ state.current = { start: t, sha256: sha };
58
+ frames.push({ t, ms: t - from, sha256: sha, w: row.data.w, h: row.data.h });
59
+ }
60
+ continue;
61
+ }
62
+ const data = row.data;
63
+ const cur = state.current;
64
+ if (!cur)
65
+ continue;
66
+ const opened = (at) => { state.gap = { from: at, reason: data.reason, ...(data.detail ? { detail: data.detail } : {}) }; };
67
+ if (cur.sha256 === null) {
68
+ closeGap(t);
69
+ opened(t);
70
+ continue;
71
+ } // the slate is already up
72
+ const at = data.reason === "process_killed" ? Math.min(t, Math.max(cur.start, data.from)) : t;
73
+ close(at);
74
+ state.current = { start: at, sha256: null, reason: data.reason };
75
+ opened(at);
76
+ }
77
+ // The track ends where the recording does; only a track that would have no length at all is given one frame's time.
78
+ let to = Math.max(options.endAt ?? 0, last);
79
+ if (to - from < one)
80
+ to = from + one;
81
+ close(to);
82
+ closeGap(to);
83
+ const width = even(frames.reduce((max, f) => Math.max(max, f.w), 2));
84
+ const height = even(frames.reduce((max, f) => Math.max(max, f.h), 2));
85
+ return { session, conv: first.row.conv, fps, from, to, width, height, segments, frames, gaps };
86
+ }
87
+ const SLATE_COLOR = "0x1f2933";
88
+ const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
89
+ /** One WebM (VP9) and one index per session that has a frame. A session's pictures are read one at a time and written straight to a private temporary
90
+ * directory made for the session and removed after, so memory holds one picture at a time (not every picture of the recording), and ffmpeg reads
91
+ * only files there: it is started with a short environment, not given a URL, and nothing it writes reaches the recording but the video. `readBlob`
92
+ * may be asked for the same blob again by another session. */
93
+ export async function exportFrameTracks(options) {
94
+ const fps = options.fps ?? 10;
95
+ const lines = [...options.lines];
96
+ // The end of the recording is the last line of any kind, the same for every session.
97
+ const recordingEnd = lines.reduce((end, row) => (typeof row?.t === "number" && row.t > end ? row.t : end), 0);
98
+ const endAt = options.endAt ?? recordingEnd;
99
+ const sessions = new Map();
100
+ for (const row of lines) {
101
+ const session = row?.data?.session;
102
+ if ((row?.kind === "frame" || row?.kind === "frame.gap") && typeof session === "string")
103
+ (sessions.get(session) ?? sessions.set(session, []).get(session)).push(row);
104
+ }
105
+ const tracks = [];
106
+ for (const [, rows] of sessions) {
107
+ throwIfAborted(options.signal);
108
+ // One deadline for the session's whole export (every ffmpeg call of it): each call gets the time that is left.
109
+ const deadline = Date.now() + (options.timeoutMs ?? 120_000);
110
+ const dir = await mkdtemp(path.join(os.tmpdir(), "pib-track-"));
111
+ try {
112
+ const names = new Map();
113
+ const skip = new Set();
114
+ const skipped = [];
115
+ let n = 0;
116
+ for (const row of rows) {
117
+ if (row.kind !== "frame")
118
+ continue;
119
+ const hash = row.blobs?.[0];
120
+ if (!hash || names.has(hash) || skip.has(hash))
121
+ continue;
122
+ let bytes;
123
+ try {
124
+ bytes = await options.readBlob(hash);
125
+ }
126
+ catch {
127
+ bytes = null;
128
+ }
129
+ throwIfAborted(options.signal);
130
+ const reason = !bytes ? "missing" : sha256(bytes) !== hash ? "hash_mismatch" : jpegSize(bytes) === null ? "not_a_jpeg" : null;
131
+ if (reason || !bytes) {
132
+ skip.add(hash);
133
+ skipped.push({ sha256: hash, reason: reason ?? "missing" });
134
+ continue;
135
+ }
136
+ const file = path.join(dir, `f${n++}.jpg`);
137
+ await writeFile(file, bytes);
138
+ const size = jpegSize(bytes);
139
+ names.set(hash, { file, w: size.w, h: size.h, sampling: jpegSampling(bytes) });
140
+ }
141
+ let plan = null;
142
+ let webm = null;
143
+ for (let attempt = 0;; attempt += 1) {
144
+ plan = planTrack(rows, { fps, endAt, skip });
145
+ if (!plan)
146
+ break;
147
+ throwIfAborted(options.signal);
148
+ try {
149
+ webm = await encode(plan, names, dir, options, deadline);
150
+ break;
151
+ }
152
+ catch (error) {
153
+ // A picture whose header reads but whose data does not decode fails the whole encode: find it, show the slate for it, try once more.
154
+ if (attempt > 0 || !(error instanceof TrackExportError) || error.code !== "ffmpeg_failed")
155
+ throw error;
156
+ const undecodable = await findUndecodable(names, dir, options, deadline);
157
+ if (undecodable.length === 0)
158
+ throw error;
159
+ for (const hash of undecodable) {
160
+ names.delete(hash);
161
+ skip.add(hash);
162
+ skipped.push({ sha256: hash, reason: "not_a_jpeg" });
163
+ }
164
+ }
165
+ }
166
+ if (!plan || !webm)
167
+ continue;
168
+ const index = { version: 1, session: plan.session, fps: plan.fps, from: plan.from, to: plan.to, width: plan.width, height: plan.height, codec: "vp9", frames: plan.frames, gaps: plan.gaps };
169
+ const indexBytes = Buffer.from(`${JSON.stringify(index)}\n`, "utf8");
170
+ const files = { webm: sha256(webm), index: sha256(indexBytes) };
171
+ tracks.push({
172
+ line: { channel: "live", source: "browser", kind: "frame.track", t: plan.to, conv: plan.conv, data: { session: plan.session, fps: plan.fps, from: plan.from, to: plan.to }, blobs: [files.webm, files.index] },
173
+ blobs: { [files.webm]: webm, [files.index]: indexBytes },
174
+ files, index, skipped,
175
+ });
176
+ }
177
+ finally {
178
+ await rm(dir, { recursive: true, force: true });
179
+ }
180
+ }
181
+ return tracks.sort((a, b) => a.line.data.from - b.line.data.from);
182
+ }
183
+ const throwIfAborted = (signal) => { if (signal?.aborted)
184
+ throw new TrackExportError("aborted", "the export was aborted"); };
185
+ const quote = (file) => `'${file.replaceAll("'", "'\\''")}'`;
186
+ /** The layout a browser's JPEG has, and the one every picture is brought to: 4:2:0. */
187
+ const COMMON_SAMPLING = "22,11,11";
188
+ /** The pictures ffmpeg cannot decode, found one at a time (only after an encode has failed). */
189
+ async function findUndecodable(names, dir, options, deadline) {
190
+ const bad = [];
191
+ for (const [hash, picture] of names) {
192
+ throwIfAborted(options.signal);
193
+ try {
194
+ await run(options.ffmpeg ?? "ffmpeg", ["-hide_banner", "-loglevel", "error", "-nostdin", "-xerror", "-i", path.basename(picture.file), "-f", "null", "-"], dir, options, deadline);
195
+ }
196
+ catch (error) {
197
+ if (error instanceof TrackExportError && error.code === "ffmpeg_failed")
198
+ bad.push(hash);
199
+ else
200
+ throw error;
201
+ }
202
+ }
203
+ return bad;
204
+ }
205
+ async function encode(plan, names, dir, options, deadline) {
206
+ // The slate is made at the canvas's own size, so no frame is ever scaled: a smaller frame is centred on the canvas at the size it was recorded.
207
+ const slate = path.join(dir, "slate.jpg");
208
+ await run(options.ffmpeg ?? "ffmpeg", ["-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-f", "lavfi", "-i", `color=c=${SLATE_COLOR}:s=${plan.width}x${plan.height}`, "-frames:v", "1", "slate.jpg"], dir, options, deadline);
209
+ // ffmpeg reconfigures its filter graph when a picture's size or pixel layout differs from the one before, and the picture it was holding is lost (the
210
+ // video then shows the next picture for its time). So every picture reaches the concat as the canvas's size and 4:2:0: one that is not is padded to
211
+ // the canvas, at the size it was recorded and centred, and converted, first.
212
+ const ready = new Map();
213
+ let fixed = 0;
214
+ for (const [hash, picture] of names) {
215
+ if (picture.w === plan.width && picture.h === plan.height && picture.sampling === COMMON_SAMPLING) {
216
+ ready.set(hash, picture.file);
217
+ continue;
218
+ }
219
+ throwIfAborted(options.signal);
220
+ const out = `n${fixed++}.jpg`;
221
+ await run(options.ffmpeg ?? "ffmpeg", ["-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", path.basename(picture.file), "-vf", `pad=${plan.width}:${plan.height}:(ow-iw)/2:(oh-ih)/2:color=${SLATE_COLOR},format=yuvj420p`, "-frames:v", "1", "-q:v", "2", out], dir, options, deadline);
222
+ ready.set(hash, path.join(dir, out));
223
+ }
224
+ const list = [];
225
+ const file = (sha) => (sha === null ? slate : ready.get(sha));
226
+ for (const segment of plan.segments)
227
+ list.push(`file ${quote(file(segment.sha256))}`, `duration ${((segment.end - segment.start) / 1000).toFixed(3)}`);
228
+ list.push(`file ${quote(file(plan.segments.at(-1).sha256))}`); // the concat demuxer ignores the last duration unless its file is named again
229
+ await writeFile(path.join(dir, "list.txt"), `${list.join("\n")}\n`);
230
+ const filter = `fps=${plan.fps},format=yuv420p`;
231
+ const args = ["-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-f", "concat", "-safe", "0", "-i", "list.txt", "-vf", filter, "-fps_mode", "cfr", "-c:v", "libvpx-vp9", "-b:v", "0", "-crf", "40", "-row-mt", "1", "-deadline", "good", "-cpu-used", "5", "-an", "out.webm"];
232
+ await run(options.ffmpeg ?? "ffmpeg", args, dir, options, deadline);
233
+ return new Uint8Array(await readFile(path.join(dir, "out.webm")));
234
+ }
235
+ function run(program, args, cwd, options, deadline) {
236
+ return new Promise((resolve, reject) => {
237
+ if (options.signal?.aborted)
238
+ return reject(new TrackExportError("aborted", "the export was aborted"));
239
+ const left = deadline - Date.now();
240
+ if (left <= 0)
241
+ return reject(new TrackExportError("ffmpeg_timeout", `the export did not finish within ${options.timeoutMs ?? 120_000} ms`));
242
+ // Only a short list of names reaches the program: not the host's keys.
243
+ const child = spawn(program, args, { cwd, env: { PATH: process.env.PATH ?? "/usr/bin:/bin", LANG: "C", LC_ALL: "C", HOME: cwd }, stdio: ["ignore", "ignore", "pipe"] });
244
+ let stderr = "";
245
+ let settled = false;
246
+ const finish = (error) => { if (settled)
247
+ return; settled = true; clearTimeout(timer); options.signal?.removeEventListener("abort", onAbort); if (error)
248
+ reject(error);
249
+ else
250
+ resolve(); };
251
+ const timer = setTimeout(() => { child.kill("SIGKILL"); finish(new TrackExportError("ffmpeg_timeout", `ffmpeg did not finish within ${options.timeoutMs ?? 120_000} ms of the session's export`)); }, left);
252
+ const onAbort = () => { child.kill("SIGKILL"); finish(new TrackExportError("aborted", "the export was aborted")); };
253
+ options.signal?.addEventListener("abort", onAbort, { once: true });
254
+ child.stderr.on("data", (chunk) => { if (stderr.length < 4_000)
255
+ stderr += chunk.toString("utf8"); });
256
+ child.once("error", (error) => finish(new TrackExportError("ffmpeg_missing", `could not start ffmpeg (${program}): ${error.code ?? error.message}`)));
257
+ child.once("close", (code) => finish(code === 0 ? undefined : new TrackExportError("ffmpeg_failed", `ffmpeg exited with ${code}: ${stderr.trim().slice(0, 1_000)}`)));
258
+ });
259
+ }
@@ -0,0 +1,56 @@
1
+ import type { Context } from "@earendil-works/chord";
2
+ import { type ConversationDocToken, type ConversationId, type DocumentReader, type Harness, type Tx } from "@earendil-works/pi-durable";
3
+ import type { BrowserConfig, BrowserProvider, InventoryRow, ReconcileReport, ReleaseReason, SessionChange, SessionRecord, SessionsState } from "./core/host.js";
4
+ import type { LeaseRef, LeaseState } from "./core/lease.js";
5
+ export declare const now: () => string;
6
+ /** Release attempts before custody is given up as `lost`, and status polls before a release is sent again. */
7
+ export declare const RELEASE_ATTEMPTS = 6;
8
+ export declare const CONFIRM_POLLS = 5;
9
+ type Move = {
10
+ state: LeaseState;
11
+ resourceId?: string;
12
+ reason?: ReleaseReason;
13
+ at: string;
14
+ notice?: "kept" | "lost";
15
+ };
16
+ type ReleaseInput = {
17
+ row: InventoryRow;
18
+ notBefore?: number;
19
+ };
20
+ type ReleaseState = {
21
+ phase: "release";
22
+ attempt: number;
23
+ } | {
24
+ phase: "confirm";
25
+ attempt: number;
26
+ ids: string[];
27
+ polls: number;
28
+ };
29
+ export type StoreDeps = {
30
+ name: string;
31
+ Config: ConversationDocToken<BrowserConfig>;
32
+ Sessions: ConversationDocToken<SessionsState>;
33
+ providerOf(read: DocumentReader, cid: ConversationId, plane: string, context: Context): Promise<BrowserProvider>;
34
+ emit(cid: ConversationId, label: string, record: SessionRecord, change: SessionChange): Promise<void>;
35
+ meter(spent: SessionRecord["spent"], at: string, final?: boolean): {
36
+ spent: SessionRecord["spent"];
37
+ };
38
+ scrubbed(error: unknown): Error;
39
+ createDeadlineMs: number;
40
+ };
41
+ export declare function custodyStore({ name, Config, Sessions, providerOf, emit, meter, scrubbed, createDeadlineMs }: StoreDeps): {
42
+ Inventory: import("@earendil-works/pi-durable").SessionDocToken<{
43
+ rows: Record<string, InventoryRow>;
44
+ }>;
45
+ move: (tx: Tx, row: InventoryRow, next: Move) => Promise<void>;
46
+ addNotice: (state: SessionsState, text: string) => void;
47
+ begin: (tx: Tx, row: InventoryRow) => Promise<void>;
48
+ requestRelease: (tx: Tx, row: InventoryRow, reason: ReleaseReason, at: string, notBefore?: number) => Promise<void>;
49
+ bindByTag: (provider: BrowserProvider, row: InventoryRow, commit: (change: (tx: Tx) => Promise<void>) => Promise<unknown>, signal?: AbortSignal, found?: LeaseRef[]) => Promise<LeaseRef | null>;
50
+ emitReleased: (cid: ConversationId, tag: string, read: DocumentReader, context: Context, at?: string) => Promise<void>;
51
+ ReleaseTask: import("@earendil-works/pi-durable").Task<ReleaseInput, ReleaseState, {
52
+ released: number;
53
+ }, object>;
54
+ reconcileAll: (harness: Harness, isActive: (conversationId: ConversationId) => boolean, context: Context) => Promise<ReconcileReport>;
55
+ };
56
+ export {};
package/dist/store.js ADDED
@@ -0,0 +1,196 @@
1
+ import { defineDoc, defineTask } from "@earendil-works/pi-durable";
2
+ import { moveRecord, notices } from "./core/custody.js";
3
+ export const now = () => new Date().toISOString();
4
+ const iso = (ms) => new Date(ms).toISOString();
5
+ const cidOf = (row) => row.conversationId;
6
+ /** Release attempts before custody is given up as `lost`, and status polls before a release is sent again. */
7
+ export const RELEASE_ATTEMPTS = 6;
8
+ export const CONFIRM_POLLS = 5;
9
+ const backoffMs = (n) => Math.min(30_000, 500 * 2 ** n);
10
+ export function custodyStore({ name, Config, Sessions, providerOf, emit, meter, scrubbed, createDeadlineMs }) {
11
+ const Inventory = defineDoc({ kind: `${name}.inventory`, version: 1, scope: "session", initial: () => ({ rows: {} }) });
12
+ /** One state change: the record and the open-session inventory move in the same commit. */
13
+ async function move(tx, row, next) {
14
+ const inventory = await tx.doc(Inventory);
15
+ // A lost one stays: custody gave up releasing it, not looking for it (reconcile releases it again at run open).
16
+ if (next.state === "released")
17
+ delete inventory.rows[row.tag];
18
+ else
19
+ inventory.rows[row.tag] = { ...row, state: next.state, resourceId: next.resourceId ?? row.resourceId };
20
+ const state = await tx.doc(Sessions, cidOf(row));
21
+ const record = state.sessions.find((r) => r.tag === row.tag);
22
+ if (!record)
23
+ return;
24
+ moveRecord(record, next);
25
+ if (next.state === "released" && record.resourceId !== null)
26
+ record.spent = meter(record.spent, next.at, true).spent;
27
+ if (next.notice) {
28
+ for (const stale of [notices.kept(record.lastUrl), notices.lost(record.lastUrl)])
29
+ state.notice = state.notice?.replace(stale, "").replace(/\s+/g, " ").trim() || null;
30
+ addNotice(state, notices[next.notice](record.lastUrl));
31
+ }
32
+ }
33
+ /** A later notice never erases one not yet told, and the same one is never added twice (a second restart before any
34
+ * call). */
35
+ const addNotice = (state, text) => { if (!state.notice?.includes(text))
36
+ state.notice = [state.notice, text].filter(Boolean).join(" "); };
37
+ const begin = async (tx, row) => { (await tx.doc(Inventory)).rows[row.tag] = { ...row, state: "creating", resourceId: null }; };
38
+ async function requestRelease(tx, row, reason, at, notBefore) {
39
+ await move(tx, row, { state: "releasing", reason, at });
40
+ await tx.createTask(ReleaseTask, { row: { ...row, state: "releasing" }, ...(notBefore ? { notBefore } : {}) }, { ownership: { kind: "conversation" }, conversationId: cidOf(row), background: true });
41
+ }
42
+ /** A create no tag lookup finds may still land (a crashed or fenced holder's call in flight): the release task looks
43
+ * again by tag after the create deadline and releases whatever landed. */
44
+ const unknownCreate = (tx, row, at) => requestRelease(tx, row, "create_failed", at, Date.now() + createDeadlineMs);
45
+ async function releaseAll(row, provider, signal) {
46
+ const ids = [...new Set([row.resourceId, ...(await provider.findByTag(row.tag, signal)).map((ref) => ref.id)].filter((id) => id !== null))];
47
+ for (const id of ids)
48
+ await provider.release({ id, tag: row.tag }, signal);
49
+ return ids;
50
+ }
51
+ const anyRunning = async (provider, row, ids, signal) => {
52
+ for (const id of ids)
53
+ if (["pending", "running"].includes(await provider.status({ id, tag: row.tag }, signal)))
54
+ return true;
55
+ return false;
56
+ };
57
+ const releasedAll = async (provider, row, signal) => !(await anyRunning(provider, row, await releaseAll(row, provider, signal), signal));
58
+ /** Its error goes to the host's report, scrubbed, and `fallback` stands in; an abort is rethrown. */
59
+ async function step(runtime, run, fallback) {
60
+ try {
61
+ return await run();
62
+ }
63
+ catch (error) {
64
+ if (runtime.signal.aborted)
65
+ throw error;
66
+ runtime.report(scrubbed(error));
67
+ return fallback;
68
+ }
69
+ }
70
+ /** A create whose answer never came, settled by its tag: the first session found is kept and committed `live`; extras
71
+ * (a create retried behind the provider's API) are released. */
72
+ async function bindByTag(provider, row, commit, signal, found) {
73
+ const refs = found ?? await provider.findByTag(row.tag, signal);
74
+ for (const extra of refs.slice(1))
75
+ await provider.release(extra, signal).catch(() => undefined);
76
+ const kept = refs[0] ?? null;
77
+ await commit((tx) => kept ? move(tx, row, { state: "live", resourceId: kept.id, at: now() }) : unknownCreate(tx, row, now()));
78
+ return kept;
79
+ }
80
+ async function emitReleased(cid, tag, read, context, at = now()) {
81
+ const [state, config] = await Promise.all([read.snapshot(Sessions, cid, context), read.snapshot(Config, cid, context)]);
82
+ const record = state?.sessions.find((r) => r.tag === tag);
83
+ const spent = record && record.resourceId !== null ? meter(record.spent, at, true).spent : record?.spent;
84
+ if (record && spent)
85
+ await emit(cid, config?.label ?? "", { ...record, state: "released", endedAt: record.endedAt ?? at, spent }, "released");
86
+ }
87
+ /** The row stays in the inventory until a run open's reconcile sees nothing under its tag running. */
88
+ async function retry(runtime, row, attempt, context) {
89
+ if (attempt + 1 >= RELEASE_ATTEMPTS) {
90
+ await runtime.commit(async (tx) => {
91
+ await move(tx, row, { state: "lost", reason: "lost", at: iso(runtime.now()) });
92
+ return { status: "terminal", outcome: { status: "failed", error: { code: "release_failed", message: `${row.tag}: not released after ${RELEASE_ATTEMPTS} attempts` } } };
93
+ }, context);
94
+ return;
95
+ }
96
+ await runtime.sleep(runtime.now() + backoffMs(attempt), context);
97
+ await runtime.commit(() => ({ status: "running", checkpoint: { phase: "release", attempt: attempt + 1 } }), context);
98
+ }
99
+ const ReleaseTask = defineTask({
100
+ name: `${name}.release`,
101
+ version: 1,
102
+ initial: () => ({ phase: "release", attempt: 0 }),
103
+ phases: {
104
+ release: async (task, runtime, context) => {
105
+ const { row, notBefore } = task.input;
106
+ const { attempt } = task.state.checkpoint;
107
+ if (attempt === 0 && notBefore && runtime.now() < notBefore)
108
+ await runtime.sleep(notBefore, context);
109
+ const ids = await step(runtime, async () => releaseAll(row, await providerOf(runtime, cidOf(row), row.plane, context), runtime.signal), null);
110
+ if (!ids)
111
+ return retry(runtime, row, attempt, context);
112
+ await runtime.commit(() => ({ status: "running", checkpoint: { phase: "confirm", attempt, ids, polls: 0 } }), context);
113
+ },
114
+ confirm: async (task, runtime, context) => {
115
+ const { row } = task.input;
116
+ const { attempt, ids, polls } = task.state.checkpoint;
117
+ const running = await step(runtime, async () => anyRunning(await providerOf(runtime, cidOf(row), row.plane, context), row, ids, runtime.signal), true);
118
+ if (running && polls + 1 < CONFIRM_POLLS) {
119
+ await runtime.sleep(runtime.now() + backoffMs(polls), context);
120
+ await runtime.commit(() => ({ status: "running", checkpoint: { phase: "confirm", attempt, ids, polls: polls + 1 } }), context);
121
+ return;
122
+ }
123
+ if (running)
124
+ return retry(runtime, row, attempt, context);
125
+ // The host hears the release before the task's last commit, so at least once, with the bill that commit
126
+ // records.
127
+ const at = iso(runtime.now());
128
+ await emitReleased(cidOf(row), row.tag, runtime, context, at);
129
+ await runtime.commit(async (tx) => {
130
+ await move(tx, row, { state: "released", at });
131
+ return { status: "terminal", outcome: { status: "completed", result: { released: ids.length } } };
132
+ }, context);
133
+ },
134
+ },
135
+ // After the abort mark: release and check once. It cannot wait or retry, so a release it cannot confirm is handed
136
+ // to a successor task in the same commit.
137
+ abort: async (task, runtime, context) => {
138
+ const { row, notBefore } = task.input;
139
+ let stopped = false;
140
+ // Before the create deadline nothing found is proof of nothing: the successor keeps the delayed lookup.
141
+ if (!(notBefore && runtime.now() < notBefore))
142
+ stopped = await providerOf(runtime, cidOf(row), row.plane, context).then((provider) => releasedAll(provider, row, context.abortSignal)).catch(() => false);
143
+ await runtime.commit(async (tx) => {
144
+ if (stopped)
145
+ await move(tx, row, { state: "released", at: iso(runtime.now()) });
146
+ else
147
+ await tx.createTask(ReleaseTask, task.input, { ownership: { kind: "conversation" }, conversationId: cidOf(row), background: true });
148
+ return { status: "terminal", outcome: { status: "aborted", reason: stopped ? "released by the abort handler" : "release handed to a successor task" } };
149
+ }, context);
150
+ },
151
+ });
152
+ async function reconcileAll(harness, isActive, context) {
153
+ const report = { released: [], kept: [], lost: [], unreachable: [] };
154
+ for (const row of Object.values((await harness.snapshot(Inventory, context))?.rows ?? {})) {
155
+ if (row.state === "releasing")
156
+ continue;
157
+ const at = now();
158
+ const commit = (change) => harness.commit(change, context);
159
+ const outcome = async (kind, change) => { if (change)
160
+ await commit(change); report[kind].push(row.tag); };
161
+ try {
162
+ const provider = await providerOf(harness, cidOf(row), row.plane, context);
163
+ if (row.state === "lost") {
164
+ await ((await releasedAll(provider, row)) ? outcome("released", async (tx) => {
165
+ delete (await tx.doc(Inventory)).rows[row.tag];
166
+ const record = (await tx.doc(Sessions, cidOf(row))).sessions.find((r) => r.tag === row.tag);
167
+ if (record && record.resourceId !== null)
168
+ record.spent = meter(record.spent, at, true).spent;
169
+ }) : outcome("lost"));
170
+ continue;
171
+ }
172
+ let live = row;
173
+ if (row.state === "creating") {
174
+ const kept = await bindByTag(provider, row, commit);
175
+ if (!kept) {
176
+ await outcome("lost");
177
+ continue;
178
+ }
179
+ live = { ...row, state: "live", resourceId: kept.id };
180
+ }
181
+ const status = await provider.status({ id: live.resourceId, tag: live.tag });
182
+ if (status === "gone" || status === "stopped")
183
+ await outcome("lost", (tx) => move(tx, live, { state: "released", reason: "ended", at, notice: "lost" }));
184
+ else if (isActive(cidOf(row)))
185
+ await outcome("kept", (tx) => move(tx, live, { state: "live", at, notice: "kept" }));
186
+ else
187
+ await outcome("released", (tx) => requestRelease(tx, live, "lost", at));
188
+ }
189
+ catch {
190
+ report.unreachable.push(row.tag);
191
+ }
192
+ }
193
+ return report;
194
+ }
195
+ return { Inventory, move, addNotice, begin, requestRelease, bindByTag, emitReleased, ReleaseTask, reconcileAll };
196
+ }