@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/annotations/capture.js

@@ -0,0 +1,409 @@
+// The terminal's capture surface for page notes (PROP-0017, PROP-0018). A front end captures in
+// one target at a time:
+// - `web`: a visible browser window the person browses in, separate from the agent's browser;
+// - `cdp`: the windows of a desktop app started with a DevTools port (an Electron app, say);
+// - `bridge`: app windows that loaded the page bridge script (a macOS web view has no DevTools port).
+// The person selects text, clicks an element, or inspects with the popover; the front end pulls
+// what they did through the page helper.
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { basename, join } from 'node:path';
+import { readBrowserConfig } from "../browser/config.js";
+import { NetworkPolicy } from "../browser/network.js";
+import { BrowserSession, fileName, launchBrowser } from "../browser/session.js";
+import { NotesBridge } from "./bridge.js";
+import { evaluateIsolated } from "./isolated.js";
+import { pageCall, pageReply } from "./pageScript.js";
+import { validateUrl } from "./store.js";
+/** Where apps started with `--remote-debugging-port` or `--inspect` usually listen. */
+export const DEVTOOLS_PORTS = [9222, 9223, 9224, 9225, 9226, 9227, 9228, 9229, 9230];
+const PROBE_MS = 400;
+const fetchJson = async (url, timeoutMs) => {
+    try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+        return response.ok ? await response.json() : null;
+    }
+    catch {
+        return null;
+    }
+};
+const spawnApp = (command, args) => {
+    // The app is the person's: it keeps running after the terminal ends.
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.on('error', () => undefined);
+    child.unref();
+};
+const freePort = () => new Promise((resolve, reject) => {
+    const server = createServer();
+    server.unref();
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+        const address = server.address();
+        server.close(() => typeof address === 'object' && address ? resolve(address.port) : reject(new Error('No free port.')));
+    });
+});
+/** The program inside a macOS `.app` bundle, or the path itself. */
+export function appExecutable(path) {
+    if (!/\.app\/?$/.test(path))
+        return path;
+    const folder = join(path, 'Contents', 'MacOS');
+    if (!existsSync(folder))
+        throw new Error(`${path} has no Contents/MacOS folder.`);
+    const programs = readdirSync(folder).filter((name) => !name.startsWith('.') && statSync(join(folder, name)).isFile());
+    const named = basename(path.replace(/\/$/, ''), '.app');
+    const program = programs.find((name) => name === named) ?? programs[0];
+    if (!program)
+        throw new Error(`${path} has no program in Contents/MacOS.`);
+    return join(folder, program);
+}
+function describeApp(port, version, list) {
+    const agent = typeof version['User-Agent'] === 'string' ? version['User-Agent'] : '';
+    const electron = /Electron\/([\d.]+)/.exec(agent);
+    const browser = electron ? `Electron/${electron[1]}` : typeof version.Browser === 'string' ? version.Browser : 'DevTools';
+    const pages = Array.isArray(list) ? list.filter((entry) => !!entry && typeof entry === 'object' && entry.type === 'page' && !/^(?:devtools|chrome-extension):/.test(String(entry.url ?? ''))) : [];
+    const title = pages.map((page) => typeof page.title === 'string' ? page.title.trim() : '').find(Boolean);
+    const product = /\)\s+([A-Za-z][\w .-]*?)\/[\d.]+\s+(?:Chrome|Electron)\//.exec(agent)?.[1];
+    return { endpoint: `http://127.0.0.1:${port}`, port, name: (title || product || browser).slice(0, 120), browser, electron: !!electron, windows: pages.length };
+}
+const IDLE_MS = 60 * 60_000;
+const LOOPBACK = /^(?:https?|wss?):\/\/(?:127\.0\.0\.1|localhost|\[::1\])(?::\d+)?(?:\/|$)/;
+const connectApp = async (endpoint) => {
+    const { chromium } = await import('playwright-core');
+    return chromium.connectOverCDP(endpoint);
+};
+/** An app's own windows over its DevTools port. Nothing is routed or opened, and the app is never closed. */
+class CdpTarget {
+    browser;
+    app;
+    kind = 'cdp';
+    ids = new WeakMap();
+    nextId = 1;
+    current = null;
+    constructor(browser, app) {
+        this.browser = browser;
+        this.app = app;
+    }
+    pages() {
+        return this.browser.contexts().flatMap((context) => context.pages()).filter((page) => !/^(?:devtools|chrome-extension):/.test(page.url()));
+    }
+    id(page) {
+        let id = this.ids.get(page);
+        if (!id) {
+            id = `w${this.nextId++}`;
+            this.ids.set(page, id);
+        }
+        return id;
+    }
+    page() {
+        const pages = this.pages();
+        if (this.current && pages.includes(this.current))
+            return this.current;
+        this.current = pages[0] ?? null;
+        if (!this.current)
+            throw new Error('The app has no open window.');
+        return this.current;
+    }
+    async evaluate(operation) {
+        return evaluateIsolated(this.page(), pageCall(operation));
+    }
+    async windows() {
+        const current = this.pages().length ? this.page() : null;
+        return Promise.all(this.pages().map(async (page) => ({ id: this.id(page), url: page.url(), title: await page.title().catch(() => ''), current: page === current })));
+    }
+    select(id) {
+        const page = this.pages().find((candidate) => this.ids.get(candidate) === id);
+        if (!page)
+            throw new Error(`There is no app window ${id}.`);
+        this.current = page;
+        void page.bringToFront().catch(() => undefined);
+    }
+    async close() {
+        // Disconnects; an app we attached to keeps running.
+        await this.browser.close().catch(() => undefined);
+    }
+}
+/** Windows that loaded the page bridge script. Every answer is page data the page could forge. */
+class BridgeTarget {
+    bridge;
+    app;
+    kind = 'bridge';
+    current = null;
+    constructor(bridge, app) {
+        this.bridge = bridge;
+        this.app = app;
+    }
+    window() {
+        const windows = this.bridge.list();
+        if (this.current && windows.some((window) => window.id === this.current))
+            return this.current;
+        this.current = windows.sort((left, right) => right.lastSeen - left.lastSeen)[0]?.id ?? null;
+        if (!this.current)
+            throw new Error('No app window has connected to the page bridge yet. Load the bridge script in the app and reload it.');
+        return this.current;
+    }
+    async evaluate(operation) {
+        return { reply: await this.bridge.call(this.window(), operation), trusted: false };
+    }
+    async windows() {
+        const current = this.bridge.list().length ? this.window() : null;
+        return this.bridge.list().map((window) => ({ id: window.id, url: window.url, title: window.title, current: window.id === current }));
+    }
+    select(id) {
+        if (!this.bridge.list().some((window) => window.id === id))
+            throw new Error(`There is no app window ${id}.`);
+        this.current = id;
+    }
+    async close() { }
+}
+/** The visible browser window, with the helper in an isolated world. */
+class WebTarget {
+    session;
+    kind = 'web';
+    app = null;
+    constructor(session) {
+        this.session = session;
+    }
+    evaluate(operation) {
+        return this.session.run(async () => evaluateIsolated((await this.session.tab()).page, pageCall(operation)));
+    }
+    async windows() {
+        if (!this.session.started)
+            return [];
+        return Promise.all(this.session.list().map(async (tab) => ({ id: tab.id, url: tab.url, title: await (await this.session.tab(tab.id)).page.title().catch(() => ''), current: tab.current })));
+    }
+    select(id) {
+        void this.session.select(id).page.bringToFront().catch(() => undefined);
+    }
+    close() {
+        return this.session.close();
+    }
+}
+export class AnnotationCapture {
+    options;
+    targets = new Map();
+    /** Ports the person attached to or started an app on, checked again by `discover`. */
+    knownPorts = new Set();
+    inspecting = new Map();
+    network;
+    bridge;
+    constructor(options) {
+        this.options = options;
+        this.network = options.network ?? new NetworkPolicy(() => readBrowserConfig(options.stateDir));
+        this.bridge = options.bridge ?? new NotesBridge({ stateDir: options.stateDir });
+    }
+    web(key) {
+        const existing = this.targets.get(key);
+        if (existing instanceof WebTarget)
+            return existing;
+        const session = new BrowserSession({
+            key: `notes-${key}`,
+            profileDir: join(this.options.stateDir, 'browser', 'profiles', 'person'),
+            downloadsDir: join(this.options.stateDir, 'browser', 'downloads', fileName(`notes-${key}`)),
+            // Always a window the person can see and select in.
+            config: () => ({ ...readBrowserConfig(this.options.stateDir), headed: true }),
+            network: this.network,
+            launch: this.options.launch ?? launchBrowser,
+            idleMs: IDLE_MS,
+            onIdle: () => void this.release(key)
+        });
+        const target = new WebTarget(session);
+        this.targets.set(key, target);
+        return target;
+    }
+    target(key) {
+        return this.targets.get(key) ?? this.web(key);
+    }
+    async replace(key, target) {
+        const old = this.targets.get(key);
+        this.targets.set(key, target);
+        this.inspecting.delete(key);
+        if (old && old !== target)
+            await old.close().catch(() => undefined);
+    }
+    async call(key, operation) {
+        return pageReply((await this.target(key).evaluate(operation)).reply);
+    }
+    /** What `key` captures in now, with the script to load while it captures a bridge. */
+    describe(key) {
+        const target = this.targets.get(key);
+        const bridge = target?.kind === 'bridge' ? this.bridge.current() : null;
+        return { kind: target?.kind ?? 'web', app: target?.app ?? null, inspecting: this.inspecting.has(key), ...(bridge ? { bridge: { snippet: bridge.snippet } } : {}) };
+    }
+    /** Captures in an app's windows instead of the browser: over its DevTools port, or the page bridge. */
+    async attach(key, spec) {
+        if (spec.kind === 'web') {
+            if (this.targets.get(key)?.kind !== 'web')
+                await this.replace(key, this.web(key));
+            return { kind: 'web', app: null, windows: await this.target(key).windows() };
+        }
+        if (spec.kind === 'cdp') {
+            if (typeof spec.endpoint !== 'string' || !LOOPBACK.test(spec.endpoint))
+                throw new Error('An app\'s DevTools address must be on this computer, such as http://127.0.0.1:9229.');
+            const browser = await (this.options.connect ?? connectApp)(spec.endpoint);
+            const name = spec.name?.trim() || `App at ${new URL(spec.endpoint).host}`;
+            const target = new CdpTarget(browser, { kind: 'cdp', name: name.slice(0, 200) });
+            await this.replace(key, target);
+            const port = Number(new URL(spec.endpoint).port);
+            if (port)
+                this.knownPorts.add(port);
+            return { kind: 'cdp', app: target.app, windows: await target.windows() };
+        }
+        if (spec.kind === 'bridge') {
+            const bridge = await this.bridge.start();
+            const target = new BridgeTarget(this.bridge, { kind: 'bridge', name: (spec.name?.trim() || 'App window').slice(0, 200) });
+            await this.replace(key, target);
+            return { kind: 'bridge', app: target.app, windows: await target.windows(), bridge };
+        }
+        throw new Error('A capture target is web, cdp or bridge.');
+    }
+    windows(key) {
+        return this.target(key).windows();
+    }
+    /** Apps on this computer that answer on a DevTools port: the usual ports and any used before. */
+    async discover(ports = []) {
+        const probe = this.options.fetchJson ?? fetchJson;
+        const wanted = [...new Set([...DEVTOOLS_PORTS, ...this.knownPorts, ...ports])].filter((port) => Number.isInteger(port) && port > 0 && port < 65536);
+        const found = await Promise.all(wanted.map(async (port) => {
+            const version = await probe(`http://127.0.0.1:${port}/json/version`, PROBE_MS);
+            if (!version || typeof version !== 'object')
+                return null;
+            // A Node `--inspect` port answers too, but has no windows to annotate.
+            if (typeof version.webSocketDebuggerUrl !== 'string' && typeof version.Browser !== 'string')
+                return null;
+            if (/^node(?:\.js)?\//i.test(String(version.Browser ?? '')))
+                return null;
+            return describeApp(port, version, await probe(`http://127.0.0.1:${port}/json/list`, PROBE_MS));
+        }));
+        return found.filter((app) => app !== null).sort((left, right) => left.port - right.port);
+    }
+    /**
+     * Starts the app the person named with a DevTools port and attaches to its windows. A macOS `.app`
+     * bundle starts its own program. The app keeps running when the capture ends.
+     */
+    async launchApp(key, path, args = []) {
+        const program = appExecutable(path.trim());
+        if (!program)
+            throw new Error('Give the path of the app to start.');
+        const port = await (this.options.freePort ?? freePort)();
+        (this.options.spawnApp ?? spawnApp)(program, [...args, `--remote-debugging-port=${port}`]);
+        this.knownPorts.add(port);
+        const endpoint = `http://127.0.0.1:${port}`;
+        const probe = this.options.fetchJson ?? fetchJson;
+        const deadline = Date.now() + (this.options.launchTimeoutMs ?? 20_000);
+        for (;;) {
+            if (await probe(`${endpoint}/json/version`, PROBE_MS))
+                break;
+            if (Date.now() > deadline)
+                throw new Error(`${basename(path)} did not open a DevTools port. Only Chromium and Electron apps can be inspected this way.`);
+            await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+        const name = basename(path.trim().replace(/\/$/, '')).replace(/\.app$/, '');
+        const attached = await this.attach(key, { kind: 'cdp', endpoint, name });
+        return { kind: 'cdp', app: attached.app, windows: attached.windows, endpoint };
+    }
+    /** Switches to another window or tab of the target; an inspector there starts again. */
+    async selectWindow(key, id) {
+        const inspecting = this.inspecting.has(key);
+        if (inspecting)
+            await this.stopInspect(key).catch(() => undefined);
+        this.target(key).select(id);
+        if (inspecting)
+            await this.inspect(key);
+    }
+    /** Shows the capture window, at `url` when given. Captures in the browser again if an app was attached. */
+    async open(key, url) {
+        if (this.targets.get(key) && this.targets.get(key).kind !== 'web')
+            await this.replace(key, this.web(key));
+        const { session } = this.web(key);
+        return session.run(async () => {
+            const tab = await session.tab();
+            if (url) {
+                const address = validateUrl(url);
+                const refusal = await this.network.refusal(address);
+                if (refusal)
+                    throw new Error(refusal);
+                await tab.page.goto(address, { waitUntil: 'domcontentloaded' });
+            }
+            await tab.page.bringToFront().catch(() => undefined);
+            return { url: tab.page.url(), title: await tab.page.title().catch(() => '') };
+        });
+    }
+    identity(key) {
+        return this.call(key, { operation: 'identity' });
+    }
+    /** Starts listening for the person's selection or click. Returns the id `capture` takes. */
+    async begin(key, kind) {
+        this.inspecting.delete(key);
+        const captureId = randomUUID();
+        await this.call(key, { operation: 'begin', kind, captureId });
+        return { captureId };
+    }
+    /** What the person selected, or null when nothing is selected yet. */
+    capture(key, captureId) {
+        return this.call(key, { operation: 'capture', captureId });
+    }
+    async cancel(key, captureId) {
+        if (!this.targets.has(key))
+            return;
+        await this.call(key, { operation: 'cancel', ...(captureId ? { captureId } : {}) });
+    }
+    /** Turns on the inspector in the current window: hover outlines, a click opens the comment popover. */
+    async inspect(key) {
+        const captureId = randomUUID();
+        await this.call(key, { operation: 'begin', kind: 'inspect', captureId });
+        const identity = await this.identity(key).catch(() => null);
+        this.inspecting.set(key, { captureId, documentId: identity?.documentId ?? null });
+        return { captureId };
+    }
+    async stopInspect(key) {
+        const state = this.inspecting.get(key);
+        this.inspecting.delete(key);
+        if (state && this.targets.has(key))
+            await this.call(key, { operation: 'cancel', captureId: state.captureId }).catch(() => undefined);
+    }
+    /**
+     * The next comment the person submitted, if any. A new document (a reload, a link) loses the
+     * inspector; it is turned on again there, so the person can keep going.
+     */
+    async next(key) {
+        const target = this.target(key);
+        const state = this.inspecting.get(key);
+        if (!state)
+            throw new Error('The inspector is off.');
+        const { reply, trusted } = await target.evaluate({ operation: 'next', captureId: state.captureId });
+        const value = pageReply(reply);
+        if (!value.active && this.inspecting.get(key) === state && value.documentId !== state.documentId) {
+            await target.evaluate({ operation: 'begin', kind: 'inspect', captureId: state.captureId });
+            state.documentId = value.documentId;
+            return { ...value, active: true, result: null, trusted, app: target.app };
+        }
+        if (!value.active)
+            this.inspecting.delete(key);
+        return { ...value, trusted, app: target.app };
+    }
+    async toast(key, text) {
+        await this.call(key, { operation: 'toast', text: text.slice(0, 200) });
+    }
+    /** Opens the note's page when another one is showing, then scrolls to and marks its target. */
+    async reveal(key, url, target) {
+        const current = this.targets.get(key);
+        if (!current || current.kind === 'web') {
+            const shown = current?.session.started ? await this.identity(key).catch(() => null) : null;
+            if (shown?.url !== url)
+                await this.open(key, url);
+        }
+        return this.call(key, { operation: 'reveal', target });
+    }
+    async release(key) {
+        const target = this.targets.get(key);
+        this.targets.delete(key);
+        this.inspecting.delete(key);
+        await target?.close();
+    }
+    async close() {
+        await Promise.all([...this.targets.keys()].map((key) => this.release(key)));
+        await this.bridge.close();
+    }
+}

package/dist/sdk/annotations/delivery.d.ts

@@ -0,0 +1,79 @@
+import type { Bus } from "../core/bus.js";
+import * as store from "./store.js";
+export interface TerminalSender {
+    has(sessionId: string): boolean;
+    send(input: {
+        sessionId: string;
+        text: string;
+    }): Promise<{
+        runId: string;
+    }>;
+}
+export type SendResult = {
+    state: 'sent';
+    runId: string;
+    ids: string[];
+} | {
+    state: 'busy';
+    ids: string[];
+} | {
+    state: 'host';
+    text: string;
+    ids: string[];
+} | {
+    state: 'empty';
+    ids: [];
+    unconfirmed: number;
+};
+export type NoteAction = 'save' | 'send';
+export interface NoteDeliveryOptions {
+    root: () => string;
+    bus: Bus;
+    terminals: () => TerminalSender | null;
+    /** Waits between tries to send notes held back while a run ends; tests shorten it. */
+    retryDelays?: readonly number[];
+}
+export declare class NoteDeliveries {
+    private readonly options;
+    private readonly sending;
+    private readonly retrying;
+    private readonly again;
+    constructor(options: NoteDeliveryOptions);
+    private changed;
+    /** Shares a saved note with the session; it waits there, unsent. */
+    share(id: string, expectedVersion: number | undefined, sessionId: string): store.Note;
+    /**
+     * Creates a note and acts on it in one step: what the popover's two buttons do. With a session the
+     * note is always shared with it. `trusted` is false when the comment came from a script the page
+     * could reach; it then waits for the person to confirm it before it is ever sent.
+     */
+    createAndAct(input: store.NoteInput, action: NoteAction, sessionId: string | null, trusted: boolean): Promise<{
+        note: store.Note;
+        send: SendResult | null;
+    }>;
+    /** The person confirms a note the page could have forged; it is then sent with the next send. */
+    confirm(id: string, expectedVersion: number | undefined): store.Note;
+    /** Confirms every page-origin note of the session at once; the person checked them in one prompt. */
+    confirmAll(sessionId: string): store.Note[];
+    /** `/annotate:clear`: the session's unsent notes are resolved and stop being shared with it. */
+    clear(sessionId: string): store.Note[];
+    private sendable;
+    /** The message for the session's unsent notes (or the given ones), for a host that runs it itself. */
+    compose(sessionId: string, ids?: string[] | null, prompt?: string | null): {
+        text: string;
+        ids: string[];
+    };
+    /** A host started `runId` with composed notes. */
+    delivered(ids: string[], sessionId: string, runId: string): store.Note[];
+    /** Sends the session's unsent notes (or the given ones) as one run, with the person's own request when given. */
+    send(sessionId: string, filter?: {
+        ids?: string[] | null;
+        auto?: boolean;
+        prompt?: string | null;
+    }): Promise<SendResult>;
+    /**
+     * A run of the session ended: notes waiting for it to be idle go out now. The terminal can still
+     * report the turn as active for a moment, so a busy answer is tried again a few times.
+     */
+    runEnded(sessionId: string | null | undefined): Promise<void>;
+}

package/dist/sdk/annotations/delivery.js

@@ -0,0 +1,163 @@
+import { HarnessError, invalid } from "../core/errors.js";
+import { compose, MAX_SEND } from "./queue.js";
+import * as store from "./store.js";
+const RETRY_DELAYS = [250, 1_000, 3_000, 8_000];
+const wait = (ms) => new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+});
+export class NoteDeliveries {
+    options;
+    sending = new Set();
+    retrying = new Set();
+    again = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    changed(sessionId, ids) {
+        this.options.bus.emit({ type: 'annotations.changed', sessionId, ids });
+    }
+    /** Shares a saved note with the session; it waits there, unsent. */
+    share(id, expectedVersion, sessionId) {
+        const note = store.markPending(this.options.root(), id, expectedVersion, sessionId);
+        this.changed(sessionId, [id]);
+        return note;
+    }
+    /**
+     * Creates a note and acts on it in one step: what the popover's two buttons do. With a session the
+     * note is always shared with it. `trusted` is false when the comment came from a script the page
+     * could reach; it then waits for the person to confirm it before it is ever sent.
+     */
+    async createAndAct(input, action, sessionId, trusted) {
+        if (action !== 'save' && action !== 'send')
+            throw invalid('action is save or send.');
+        if (action === 'send' && !sessionId)
+            throw invalid('Sending a note needs a session.');
+        const root = this.options.root();
+        let note = store.create(root, input);
+        if (!sessionId) {
+            this.changed(null, [note.id]);
+            return { note, send: null };
+        }
+        // A send that cannot go out yet (busy, or waiting for confirmation) goes when the session is idle.
+        note = store.markPending(root, note.id, undefined, sessionId, { ...(action === 'send' ? { autoSend: true } : {}), ...(trusted ? {} : { confirm: true }) });
+        this.changed(sessionId, [note.id]);
+        if (action === 'save' || !trusted)
+            return { note, send: null };
+        const send = await this.send(sessionId);
+        return { note: store.read(root, note.id), send };
+    }
+    /** The person confirms a note the page could have forged; it is then sent with the next send. */
+    confirm(id, expectedVersion) {
+        const root = this.options.root();
+        const note = store.read(root, id);
+        if (note.delivery?.state !== 'pending')
+            throw invalid('This note is not waiting to be sent.');
+        const confirmed = store.markPending(root, id, expectedVersion, note.delivery.sessionId, { confirmed: true });
+        this.changed(confirmed.delivery.sessionId, [id]);
+        return confirmed;
+    }
+    /** Confirms every page-origin note of the session at once; the person checked them in one prompt. */
+    confirmAll(sessionId) {
+        const notes = store.pending(this.options.root(), sessionId).filter((note) => note.delivery?.confirm);
+        return notes.map((note) => this.confirm(note.id, note.version));
+    }
+    /** `/annotate:clear`: the session's unsent notes are resolved and stop being shared with it. */
+    clear(sessionId) {
+        const cleared = store.clearPending(this.options.root(), sessionId);
+        if (cleared.length)
+            this.changed(sessionId, cleared.map((note) => note.id));
+        return cleared;
+    }
+    sendable(sessionId, filter) {
+        const waiting = store.pending(this.options.root(), sessionId, { ids: filter.ids ?? null, auto: filter.auto === true });
+        if (filter.ids != null && waiting.some((note) => note.delivery?.confirm))
+            throw invalid('Confirm page-origin notes before sending them.');
+        const unconfirmed = waiting.filter((note) => note.delivery?.confirm === true).length;
+        return { notes: waiting.filter((note) => note.delivery?.confirm !== true).slice(0, MAX_SEND), unconfirmed };
+    }
+    /** The message for the session's unsent notes (or the given ones), for a host that runs it itself. */
+    compose(sessionId, ids, prompt) {
+        const { notes } = this.sendable(sessionId, { ids: ids ?? null });
+        if (!notes.length)
+            throw invalid('No confirmed notes are waiting for this session.');
+        return { text: compose(notes, prompt), ids: notes.map((note) => note.id) };
+    }
+    /** A host started `runId` with composed notes. */
+    delivered(ids, sessionId, runId) {
+        const sent = store.markSent(this.options.root(), ids, sessionId, runId);
+        this.changed(sessionId, ids);
+        return sent;
+    }
+    /** Sends the session's unsent notes (or the given ones) as one run, with the person's own request when given. */
+    async send(sessionId, filter = {}) {
+        const root = this.options.root();
+        const { notes, unconfirmed } = this.sendable(sessionId, filter);
+        if (!notes.length)
+            return { state: 'empty', ids: [], unconfirmed };
+        const ids = notes.map((note) => note.id);
+        const text = compose(notes, filter.prompt);
+        const terminals = this.options.terminals();
+        if (!terminals?.has(sessionId)) {
+            // A host's session: the host starts the run and reports it with `delivered`.
+            if (filter.auto)
+                this.options.bus.emit({ type: 'annotations.ready', sessionId, ids });
+            return { state: 'host', text, ids };
+        }
+        if (this.sending.has(sessionId))
+            return { state: 'busy', ids };
+        this.sending.add(sessionId);
+        try {
+            const { runId } = await terminals.send({ sessionId, text });
+            store.markSent(root, ids, sessionId, runId);
+            this.changed(sessionId, ids);
+            return { state: 'sent', runId, ids };
+        }
+        catch (error) {
+            if (error instanceof HarnessError && error.code === 'session_busy') {
+                // Send it when the run ends. A request typed with /annotate:submit is not kept: the notes stay
+                // unsent and the person submits again.
+                if (filter.prompt?.trim())
+                    return { state: 'busy', ids };
+                for (const note of notes)
+                    if (!note.delivery?.autoSend)
+                        store.markPending(root, note.id, undefined, sessionId, { autoSend: true });
+                this.changed(sessionId, ids);
+                return { state: 'busy', ids };
+            }
+            throw error;
+        }
+        finally {
+            this.sending.delete(sessionId);
+        }
+    }
+    /**
+     * A run of the session ended: notes waiting for it to be idle go out now. The terminal can still
+     * report the turn as active for a moment, so a busy answer is tried again a few times.
+     */
+    async runEnded(sessionId) {
+        if (!sessionId)
+            return;
+        if (this.retrying.has(sessionId)) {
+            // Another run ended while we were still trying: start over once the current tries finish.
+            this.again.add(sessionId);
+            return;
+        }
+        this.retrying.add(sessionId);
+        try {
+            for (const delay of this.options.retryDelays ?? RETRY_DELAYS) {
+                await wait(delay);
+                if (!store.pending(this.options.root(), sessionId, { auto: true }).length)
+                    return;
+                const result = await this.send(sessionId, { auto: true });
+                if (result.state !== 'busy')
+                    return;
+            }
+        }
+        finally {
+            this.retrying.delete(sessionId);
+            if (this.again.delete(sessionId))
+                void this.runEnded(sessionId).catch(() => undefined);
+        }
+    }
+}

package/dist/sdk/annotations/inspect.d.ts

@@ -0,0 +1,10 @@
+import type { AnnotationCapture, InspectState } from "./capture.js";
+import type { NoteDeliveries, SendResult } from "./delivery.js";
+import type { Note } from "./store.js";
+export interface InspectStep extends Omit<InspectState, 'result'> {
+    note: Note | null;
+    send: SendResult | null;
+    /** What the person was told in the page. */
+    message: string | null;
+}
+export declare function inspectStep(capture: AnnotationCapture, notes: NoteDeliveries, key: string, sessionId: string | null, surface: string): Promise<InspectStep>;