@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5682

package/dist/preview/agent-address.d.ts

@@ -0,0 +1,34 @@
+import type { AgentGrant, RunContext } from './host.ts';
+import type { PreviewHostLike } from './registration.ts';
+/**
+ * The agent's preview browser address (hearsay-tools/cezarion#784, spec
+ * 2026-10-26-preview-agent-cdp): the cockpit's own bound origin as `ws:`, at the CDP proxy route,
+ * with the grant's token. Undefined when the origin is not a URL.
+ */
+export declare function previewCdpUrl(cockpitOrigin: string, token: string): string | undefined;
+/**
+ * A session's tool capability with the CDP address added: `CEZ_PREVIEW_CDP_URL` joins its env, and
+ * its `revoke` also revokes the grant, so every site that ends the tools closes the agent's browser
+ * sockets too.
+ */
+export declare function withPreviewCdp<S extends {
+    env: Record<string, string>;
+    revoke(): void;
+}>(session: S, grant: AgentGrant, cockpitOrigin: string, rebrand?: boolean): S;
+/**
+ * `withPreviewCdp` behind its gate: only with `CEZ_PREVIEW=1`, a host that can grant, a cockpit
+ * origin (none under `cez run`) and a worktree. Every runner's session goes through here, so the
+ * harness parity cell R125 reads the same decision RunManager makes.
+ */
+export declare function previewCdpSession<S extends {
+    env: Record<string, string>;
+    revoke(): void;
+}>(session: S, opts: {
+    host?: Pick<PreviewHostLike, 'grantAgent'> | undefined;
+    cockpitOrigin?: string | undefined;
+    runId: string;
+    worktree: boolean;
+    context: () => RunContext | undefined;
+}): S;
+/** The preview host's view of a run with a live worktree, read when the agent connects. */
+export declare function previewRunContext(store: RunContext['store'], dataDir: string, runId: string): RunContext | undefined;

package/dist/preview/agent-address.js

@@ -0,0 +1,52 @@
+import { productEnvEntries } from '../core/product-env.js';
+import { existsSync } from 'node:fs';
+import { previewToolEnabled } from '../ci-wait/tools.js';
+/**
+ * The agent's preview browser address (hearsay-tools/cezarion#784, spec
+ * 2026-10-26-preview-agent-cdp): the cockpit's own bound origin as `ws:`, at the CDP proxy route,
+ * with the grant's token. Undefined when the origin is not a URL.
+ */
+export function previewCdpUrl(cockpitOrigin, token) {
+    let address;
+    try {
+        address = new URL(cockpitOrigin);
+    }
+    catch {
+        return undefined;
+    }
+    address.protocol = address.protocol === 'https:' ? 'wss:' : 'ws:';
+    address.pathname = `/api/v1/preview/cdp/${token}`;
+    address.search = address.hash = '';
+    return address.toString();
+}
+/**
+ * A session's tool capability with the CDP address added: `CEZ_PREVIEW_CDP_URL` joins its env, and
+ * its `revoke` also revokes the grant, so every site that ends the tools closes the agent's browser
+ * sockets too.
+ */
+export function withPreviewCdp(session, grant, cockpitOrigin, rebrand) {
+    const url = previewCdpUrl(cockpitOrigin, grant.token);
+    if (!url) {
+        grant.revoke();
+        return session;
+    }
+    return { ...session, env: { ...session.env, ...productEnvEntries('PREVIEW_CDP_URL', url, rebrand) }, revoke: () => { session.revoke(); grant.revoke(); } };
+}
+/**
+ * `withPreviewCdp` behind its gate: only with `CEZ_PREVIEW=1`, a host that can grant, a cockpit
+ * origin (none under `cez run`) and a worktree. Every runner's session goes through here, so the
+ * harness parity cell R125 reads the same decision RunManager makes.
+ */
+export function previewCdpSession(session, opts) {
+    if (!previewToolEnabled() || !opts.host?.grantAgent || !opts.cockpitOrigin || !opts.worktree)
+        return session;
+    return withPreviewCdp(session, opts.host.grantAgent(opts.runId, opts.context), opts.cockpitOrigin);
+}
+/** The preview host's view of a run with a live worktree, read when the agent connects. */
+export function previewRunContext(store, dataDir, runId) {
+    const run = store.getRun(runId);
+    if (!run?.worktreePath || !existsSync(run.worktreePath))
+        return undefined;
+    return { runId, title: run.title, worktreePath: run.worktreePath, dataDir, store };
+}
+//# sourceMappingURL=agent-address.js.map

package/dist/preview/agent-address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-address.js","sourceRoot":"","sources":["../../src/preview/agent-address.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAIzD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,aAAqB,EAAE,KAAa;IAChE,IAAI,OAAY,CAAC;IACjB,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;IAClE,OAAO,CAAC,QAAQ,GAAG,uBAAuB,KAAK,EAAE,CAAC;IAClD,OAAO,CAAC,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,EAAE,CAAC;IACnC,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAA4D,OAAU,EAAE,KAAiB,EAAE,aAAqB,EAAE,OAAiB;IAC/J,MAAM,GAAG,GAAG,aAAa,CAAC,aAAa,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACtD,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,KAAK,CAAC,MAAM,EAAE,CAAC;QACf,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,EAAE,GAAG,OAAO,EAAE,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,iBAAiB,CAAC,iBAAiB,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC7J,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAU,EACV,IAA6K;IAE7K,IAAI,CAAC,kBAAkB,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,IAAI,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,CAAC,QAAQ;QAAE,OAAO,OAAO,CAAC;IAC7G,OAAO,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;AACrG,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,iBAAiB,CAAC,KAA0B,EAAE,OAAe,EAAE,KAAa;IAC1F,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,CAAC,GAAG,EAAE,YAAY,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1E,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AACrF,CAAC"}

package/dist/preview/agent-marker.d.ts

@@ -0,0 +1,17 @@
+import type { RunContext } from './host.ts';
+/** Before `connected` is appended: a crash after this line still leaves a marker to reconcile. */
+export declare function markAgentConnected(dataDir: string, runId: string): void;
+/** After `disconnected` is appended. */
+export declare function clearAgentMarker(dataDir: string, runId: string): void;
+/**
+ * Appends `preview.agent-browser` for a run that exists, with its marker around it. Best effort: it
+ * runs inside a socket's close, so a failed write never stops that cleanup, and a `disconnected` it
+ * could not write keeps the marker for the next boot. Answers whether the event is written.
+ */
+export declare function recordAgentBrowser(ctx: Pick<RunContext, 'runId' | 'store' | 'dataDir'>, state: 'connected' | 'disconnected'): boolean;
+/**
+ * Boot: every marker this process does not own is a crash's. Its run gets the `disconnected` it
+ * missed, then the marker goes; a crash between the two only appends `disconnected` again.
+ * Synchronous, so it finishes before the agent's CDP route can accept a connection.
+ */
+export declare function reconcileAgentMarkers(dataDir: string, store: RunContext['store'], live: (runId: string) => boolean): number;

package/dist/preview/agent-marker.js

@@ -0,0 +1,71 @@
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * A run's `preview.agent-browser` state across a crash (hearsay-tools/cezarion#784): the marker
+ * `<dataDir>/preview/<runId>/agent-connected` exists from just before `connected` is appended until
+ * just after `disconnected` is. A cezar killed with an agent connected leaves the marker, and the
+ * next boot appends the missing `disconnected`, so the cockpit never lists a page no agent drives.
+ */
+const MARKER = 'agent-connected';
+function markerPath(dataDir, runId) {
+    return join(dataDir, 'preview', runId, MARKER);
+}
+/** Before `connected` is appended: a crash after this line still leaves a marker to reconcile. */
+export function markAgentConnected(dataDir, runId) {
+    try {
+        mkdirSync(join(dataDir, 'preview', runId), { recursive: true });
+        writeFileSync(markerPath(dataDir, runId), '');
+    }
+    catch { /* a read-only data dir: the state then lives only as long as this process */ }
+}
+/** After `disconnected` is appended. */
+export function clearAgentMarker(dataDir, runId) {
+    try {
+        rmSync(markerPath(dataDir, runId), { force: true });
+    }
+    catch { /* the next boot finds the marker and appends `disconnected` again */ }
+}
+/**
+ * Appends `preview.agent-browser` for a run that exists, with its marker around it. Best effort: it
+ * runs inside a socket's close, so a failed write never stops that cleanup, and a `disconnected` it
+ * could not write keeps the marker for the next boot. Answers whether the event is written.
+ */
+export function recordAgentBrowser(ctx, state) {
+    const { runId, store, dataDir } = ctx;
+    try {
+        const run = store.getRun(runId);
+        if (run && state === 'connected')
+            markAgentConnected(dataDir, runId);
+        if (run)
+            store.appendEvent(runId, { type: 'preview.agent-browser', state });
+    }
+    catch {
+        return false;
+    }
+    if (state === 'disconnected')
+        clearAgentMarker(dataDir, runId);
+    return true;
+}
+/**
+ * Boot: every marker this process does not own is a crash's. Its run gets the `disconnected` it
+ * missed, then the marker goes; a crash between the two only appends `disconnected` again.
+ * Synchronous, so it finishes before the agent's CDP route can accept a connection.
+ */
+export function reconcileAgentMarkers(dataDir, store, live) {
+    let runIds;
+    try {
+        runIds = readdirSync(join(dataDir, 'preview'));
+    }
+    catch {
+        return 0;
+    }
+    let reconciled = 0;
+    for (const runId of runIds) {
+        if (!existsSync(markerPath(dataDir, runId)) || live(runId))
+            continue;
+        if (recordAgentBrowser({ runId, store, dataDir }, 'disconnected'))
+            reconciled += 1;
+    }
+    return reconciled;
+}
+//# sourceMappingURL=agent-marker.js.map

package/dist/preview/agent-marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-marker.js","sourceRoot":"","sources":["../../src/preview/agent-marker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACpF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGjC;;;;;GAKG;AAEH,MAAM,MAAM,GAAG,iBAAiB,CAAC;AAEjC,SAAS,UAAU,CAAC,OAAe,EAAE,KAAa;IAChD,OAAO,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AACjD,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,KAAa;IAC/D,IAAI,CAAC;QACH,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChE,aAAa,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC,CAAC,6EAA6E,CAAC,CAAC;AAC3F,CAAC;AAED,wCAAwC;AACxC,MAAM,UAAU,gBAAgB,CAAC,OAAe,EAAE,KAAa;IAC7D,IAAI,CAAC;QACH,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC,CAAC,qEAAqE,CAAC,CAAC;AACnF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAoD,EAAE,KAAmC;IAC1H,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC;IACtC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,GAAG,IAAI,KAAK,KAAK,WAAW;YAAE,kBAAkB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACrE,IAAI,GAAG;YAAE,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,uBAAuB,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,KAAK,KAAK,cAAc;QAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC/D,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe,EAAE,KAA0B,EAAE,IAAgC;IACjH,IAAI,MAAgB,CAAC;IACrB,IAAI,CAAC;QACH,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC;YAAE,SAAS;QACrE,IAAI,kBAAkB,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,cAAc,CAAC;YAAE,UAAU,IAAI,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/preview/browser-launch.d.ts

@@ -0,0 +1,28 @@
+import type { Home } from '../home/home.ts';
+import { z } from 'zod';
+import type { Cdp, CdpConnection } from './cdp.ts';
+export type BrowserExit = {
+    signal?: string;
+    exitCode?: number;
+    stderrTail: string;
+};
+/** A launched Chromium: its page's CDP session, and the browser connection the agent's proxy
+ *  opens its own sessions on (hearsay-tools/cezarion#784). `exited` settles when the process is gone. */
+export type BrowserHandle = {
+    cdp: Cdp;
+    connection: CdpConnection;
+    pageTargetId?: string | undefined;
+    exited: Promise<BrowserExit>;
+    close(): void;
+};
+/** No Chromium anywhere `resolveChromium` looks: the pane offers the download or the OS command. */
+export declare class ChromiumMissingError extends Error {
+}
+export declare const attachedSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+/** A closed browser's exit, bounded: a profile is deleted only once Chromium let go of it. */
+export declare function waitForExit(browser: BrowserHandle): Promise<void>;
+/** resolve → launch → a flat session on the page target. */
+export declare function launchBrowser(profileDir: string, env: NodeJS.ProcessEnv, home: Home): Promise<BrowserHandle>;
+export declare function readOsRelease(): string;

package/dist/preview/browser-launch.js

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+import { ChromiumError, launchChromium, resolveChromium } from './chromium.js';
+/** A task's Chromium as the preview host launches it (hearsay-tools/cezarion#781): resolve, launch, attach to its page. Split out of `host.ts`. */
+const PROFILE_RELEASE_WAIT_MS = 5_000;
+/** How long a closed Chromium may take to exit before it gets SIGKILL. */
+const BROWSER_KILL_GRACE_MS = 5_000;
+const STDERR_TAIL_CHARS = 4096;
+/** No Chromium anywhere `resolveChromium` looks: the pane offers the download or the OS command. */
+export class ChromiumMissingError extends Error {
+}
+const targetsSchema = z.object({ targetInfos: z.array(z.object({ type: z.string(), targetId: z.string() }).passthrough()) });
+export const attachedSchema = z.object({ sessionId: z.string() });
+/** A closed browser's exit, bounded: a profile is deleted only once Chromium let go of it. */
+export async function waitForExit(browser) {
+    let timer;
+    await Promise.race([browser.exited, new Promise(resolve => (timer = setTimeout(resolve, PROFILE_RELEASE_WAIT_MS)))]);
+    clearTimeout(timer);
+}
+/** resolve → launch → a flat session on the page target. */
+export async function launchBrowser(profileDir, env, home) {
+    const bin = resolveChromium(undefined, env, undefined, undefined, home);
+    if (!bin)
+        throw new ChromiumMissingError('No Chromium found');
+    const { proc, browser: connection } = await launchChromium(bin, profileDir, env);
+    let tail = '';
+    proc.stderr?.on('data', (chunk) => {
+        tail = (tail + chunk.toString('utf8')).slice(-STDERR_TAIL_CHARS);
+    });
+    const exited = new Promise(resolve => proc.once('exit', (code, signal) => resolve({ ...(signal ? { signal } : code !== null ? { exitCode: code } : {}), stderrTail: tail })));
+    try {
+        const root = connection.session(undefined);
+        const { targetInfos } = targetsSchema.parse(await root.send('Target.getTargets'));
+        const page = targetInfos.find(target => target.type === 'page');
+        if (!page)
+            throw new ChromiumError('exited', tail, 'Chromium opened no page');
+        const { sessionId } = attachedSchema.parse(await root.send('Target.attachToTarget', { targetId: page.targetId, flatten: true }));
+        const cdp = connection.session(sessionId);
+        // A Chromium that ignores the termination signal is killed after the grace, so no closed
+        // browser outlives its run (idle close, run deletion, a stale or failed launch).
+        const close = () => {
+            connection.close();
+            proc.kill();
+            const kill = setTimeout(() => { proc.kill('SIGKILL'); }, BROWSER_KILL_GRACE_MS);
+            kill.unref?.();
+            void exited.then(() => { clearTimeout(kill); });
+        };
+        return { cdp, connection, pageTargetId: page.targetId, exited, close };
+    }
+    catch (error) {
+        connection.close();
+        proc.kill('SIGKILL');
+        throw error;
+    }
+}
+export function readOsRelease() {
+    try {
+        return readFileSync('/etc/os-release', 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+//# sourceMappingURL=browser-launch.js.map

package/dist/preview/browser-launch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-launch.js","sourceRoot":"","sources":["../../src/preview/browser-launch.ts"],"names":[],"mappings":"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"}

package/dist/preview/cdp-proxy.d.ts

@@ -0,0 +1,54 @@
+import type { CdpConnection } from './cdp.ts';
+/**
+ * One agent connection to the task's Chromium (hearsay-tools/cezarion#784, spec
+ * 2026-10-26-preview-agent-cdp). Chromium has no debug port, only cezar's pipe; each agent socket
+ * gets its own browser session on that pipe (`Target.attachToBrowserTarget`), so its Target domain
+ * state, its ids and its events stay apart from cezar's own page session and from other agents.
+ *
+ * - A message without `sessionId` is the agent's root: it goes to its browser session.
+ * - A message naming a session goes through only when this link opened that session.
+ * - Replies and events come back in the order the browser sent them, the browser session's without
+ *   a `sessionId`, as a client of a root WebSocket expects.
+ * - Commands that would end the owner's browser or the page the pane streams are refused, and so
+ *   is `Target.sendMessageToTarget`, which would carry such a command past these checks.
+ * - Each target the agent creates, attaches to or activates is reported (`onTarget`): the pane's
+ *   "agent's page" follows it, because `agent-browser --pin-tab` drives a fresh tab of its own.
+ */
+/** The agent's side of the link: an open WebSocket, as the proxy route hands it over. */
+export type AgentClient = {
+    send(text: string): void;
+    close(code: number, reason: string): void;
+};
+export declare class AgentCdpLink {
+    private readonly connection;
+    private readonly client;
+    private readonly browserSession;
+    private readonly protectedTargetId;
+    private readonly onClose;
+    private readonly onTarget;
+    /** Child sessions this link opened, each with the target it is attached to. */
+    private readonly owned;
+    private readonly offEvent;
+    private closed;
+    private constructor();
+    /**
+     * Opens the agent's browser session. `protectedTargetId` is the page the owner's pane streams:
+     * the agent may drive it but not close it. Rejects when the browser refuses the session.
+     */
+    static open(connection: CdpConnection, client: AgentClient, opts?: {
+        protectedTargetId?: string | undefined;
+        onClose?: () => void;
+        onTarget?: (targetId: string) => void;
+    }): Promise<AgentCdpLink>;
+    /** One message from the agent's socket. */
+    fromClient(text: string): void;
+    /** The agent's socket closed, or the link is closing it: the browser session goes, and with it every child. */
+    close(code?: number, reason?: string): void;
+    private refusal;
+    private fromBrowser;
+    /** The target a successful command made the agent's: created, attached to, or brought to front. */
+    private reportTarget;
+    private adopt;
+    private forget;
+    private deliver;
+}

package/dist/preview/cdp-proxy.js

@@ -0,0 +1,152 @@
+import { productName } from '../home/display.js';
+/** End the browser for everyone: the owner's pane and every other agent share it. */
+const BROWSER_ENDING = new Set(['Browser.close', 'Browser.crash', 'Browser.crashGpuProcess']);
+/** Commands that close a target or a session given in their params. */
+const CLOSES_TARGET = new Set(['Target.closeTarget']);
+const CLOSES_PAGE = new Set(['Page.close']);
+/** The legacy tunnel: its session and command sit inside `params`, where no guard here reads them. */
+const TUNNEL = 'Target.sendMessageToTarget';
+/** JSON-RPC's code for a request the server will not run: CDP uses it for unknown sessions too. */
+const REFUSED_CODE = -32000;
+export class AgentCdpLink {
+    connection;
+    client;
+    browserSession;
+    protectedTargetId;
+    onClose;
+    onTarget;
+    /** Child sessions this link opened, each with the target it is attached to. */
+    owned = new Map();
+    offEvent;
+    closed = false;
+    constructor(connection, client, browserSession, protectedTargetId, onClose, onTarget) {
+        this.connection = connection;
+        this.client = client;
+        this.browserSession = browserSession;
+        this.protectedTargetId = protectedTargetId;
+        this.onClose = onClose;
+        this.onTarget = onTarget;
+        this.offEvent = connection.onEvent(msg => this.fromBrowser(msg));
+        void connection.closed.then(() => this.close(1011, 'The preview browser exited'));
+    }
+    /**
+     * Opens the agent's browser session. `protectedTargetId` is the page the owner's pane streams:
+     * the agent may drive it but not close it. Rejects when the browser refuses the session.
+     */
+    static async open(connection, client, opts = {}) {
+        const reply = await connection.call('Target.attachToBrowserTarget', {}, undefined);
+        const sessionId = reply.result?.sessionId;
+        if (reply.error || typeof sessionId !== 'string')
+            throw new Error(`Target.attachToBrowserTarget: ${reply.error?.message ?? 'no session'}`);
+        return new AgentCdpLink(connection, client, sessionId, opts.protectedTargetId, opts.onClose ?? (() => { }), opts.onTarget ?? (() => { }));
+    }
+    /** One message from the agent's socket. */
+    fromClient(text) {
+        if (this.closed)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        if (typeof msg.id !== 'number' || typeof msg.method !== 'string')
+            return;
+        const { id, method } = msg;
+        const named = typeof msg.sessionId === 'string' ? msg.sessionId : undefined;
+        const reply = (body) => this.deliver({ id, ...body, ...(named ? { sessionId: named } : {}) });
+        if (named !== undefined && !this.owned.has(named))
+            return reply({ error: { code: REFUSED_CODE, message: 'Session with given id not found.' } });
+        const refusal = this.refusal(method, msg.params, named);
+        if (refusal)
+            return reply({ error: { code: REFUSED_CODE, message: refusal } });
+        this.connection.request(method, msg.params ?? {}, named ?? this.browserSession, answer => {
+            if (method === 'Target.attachToTarget' && !answer.error)
+                this.adopt(answer.result, msg.params?.targetId);
+            if (method === 'Target.detachFromTarget' && !answer.error)
+                this.forget(msg.params?.sessionId);
+            reply(answer.error ? { error: answer.error } : { result: answer.result ?? {} });
+            if (!answer.error)
+                this.reportTarget(method, msg.params, answer.result);
+        });
+    }
+    /** The agent's socket closed, or the link is closing it: the browser session goes, and with it every child. */
+    close(code = 1000, reason = '') {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.offEvent();
+        this.connection.request('Target.detachFromTarget', { sessionId: this.browserSession }, undefined, () => { });
+        this.client.close(code, reason);
+        this.onClose();
+    }
+    refusal(method, params, named) {
+        if (BROWSER_ENDING.has(method))
+            return `${productName('cezar')} refuses ${method}: the owner's preview pane shares this browser.`;
+        if (method === TUNNEL)
+            return `${productName('cezar')} refuses ${TUNNEL}: use flat sessions (attach with flatten: true).`;
+        const p = (params ?? {});
+        if (CLOSES_TARGET.has(method) && this.protectedTargetId !== undefined && p.targetId === this.protectedTargetId) {
+            return `${productName('cezar')} refuses ${method} on the page the owner's preview pane shows.`;
+        }
+        if (CLOSES_PAGE.has(method) && named !== undefined && this.owned.get(named) === this.protectedTargetId && this.protectedTargetId !== undefined) {
+            return `${productName('cezar')} refuses ${method} on the page the owner's preview pane shows.`;
+        }
+        // Only this link's sessions: a foreign id could be cezar's own page session.
+        if (method === 'Target.detachFromTarget' && typeof p.sessionId === 'string' && !this.owned.has(p.sessionId)) {
+            return 'Session with given id not found.';
+        }
+        return undefined;
+    }
+    fromBrowser(msg) {
+        if (this.closed || typeof msg.sessionId !== 'string')
+            return;
+        const own = msg.sessionId === this.browserSession;
+        if (!own && !this.owned.has(msg.sessionId))
+            return;
+        if (msg.method === 'Target.attachedToTarget')
+            this.adopt(msg.params, undefined);
+        if (msg.method === 'Target.detachedFromTarget')
+            this.forget(msg.params?.sessionId);
+        if (own) {
+            const { sessionId: _browserSession, ...rest } = msg;
+            this.deliver(rest);
+        }
+        else {
+            this.deliver(msg);
+        }
+    }
+    /** The target a successful command made the agent's: created, attached to, or brought to front. */
+    reportTarget(method, params, result) {
+        if (this.closed)
+            return;
+        const fromParams = params?.targetId;
+        const target = method === 'Target.createTarget'
+            ? result?.targetId
+            : method === 'Target.attachToTarget' || method === 'Target.activateTarget' ? fromParams : undefined;
+        if (typeof target === 'string')
+            this.onTarget(target);
+    }
+    adopt(attached, targetId) {
+        if (typeof attached?.sessionId !== 'string')
+            return;
+        const target = attached.targetInfo?.targetId ?? targetId;
+        this.owned.set(attached.sessionId, typeof target === 'string' ? target : undefined);
+    }
+    forget(sessionId) {
+        if (typeof sessionId === 'string')
+            this.owned.delete(sessionId);
+    }
+    deliver(msg) {
+        if (this.closed)
+            return;
+        try {
+            this.client.send(JSON.stringify(msg));
+        }
+        catch {
+            this.close(1011, 'The agent socket failed');
+        }
+    }
+}
+//# sourceMappingURL=cdp-proxy.js.map

package/dist/preview/cdp-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-proxy.js","sourceRoot":"","sources":["../../src/preview/cdp-proxy.ts"],"names":[],"mappings":"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"}

package/dist/preview/cdp.d.ts

@@ -0,0 +1,49 @@
+import type { Readable, Writable } from 'node:stream';
+/**
+ * A minimal Chrome DevTools Protocol client (hearsay-tools/cezarion#781). Raw CDP never leaves the server process except
+ * through the agent's CDP proxy (`cdp-proxy.ts`, hearsay-tools/cezarion#784), which gives each agent
+ * connection its own browser session on this same connection.
+ */
+export interface Cdp {
+    send<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
+    /** Subscribe to a CDP event; returns the unsubscribe. */
+    on<T = unknown>(event: string, fn: (params: T) => void): () => void;
+    close(): void;
+    /** Settles when the connection is gone, whoever closed it. */
+    closed: Promise<void>;
+}
+/** One CDP message as it crosses the wire. Flat sessions name their session in `sessionId`. */
+export type CdpMessage = {
+    id?: number;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: {
+        code?: number;
+        message?: string;
+        data?: unknown;
+    };
+    sessionId?: string;
+};
+/** The browser-level connection: flat sessions over one transport (the pipe, hearsay-tools/cezarion#784). */
+export interface CdpConnection {
+    /** A page or browser session's client. Undefined is the root session. */
+    session(sessionId: string | undefined): Cdp;
+    /** Sends one command and settles with its raw reply, error included: the proxy forwards it as it came. */
+    call(method: string, params: unknown, sessionId: string | undefined): Promise<CdpMessage>;
+    /** `call` with a callback run in wire order, before any message read after the reply: a proxy
+     *  that forwards replies and events keeps the order the browser sent them in. */
+    request(method: string, params: unknown, sessionId: string | undefined, onReply: (msg: CdpMessage) => void): void;
+    /** Every event on every session, as it came; returns the unsubscribe. */
+    onEvent(fn: (msg: CdpMessage) => void): () => void;
+    close(): void;
+    closed: Promise<void>;
+}
+/** One page target's WebSocket. The tests' fake CDP servers speak it. */
+export declare function connectCdp(wsUrl: string): Promise<Cdp>;
+/**
+ * Chromium's `--remote-debugging-pipe` (hearsay-tools/cezarion#784): commands go into fd 3 and
+ * replies come out of fd 4, each message ended by a NUL byte. No port exists, so only this process
+ * reaches the browser.
+ */
+export declare function cdpOverPipe(toBrowser: Writable, fromBrowser: Readable): CdpConnection;