@genesislcap/ai-assistant 15.86.1 → 15.87.0

package/dist/esm/headless/headless-session.js

@@ -0,0 +1,808 @@
+import { __awaiter } from "tslib";
+import { byNumberOf, fieldsExample, invokeArgsFor } from '../autopilot/autopilot-session';
+import { capRead, visibleTranscript } from '../autopilot/decision-message';
+import { recordMetaEvent } from '../state/debug-event-log';
+import { checkArgs, unavailableReason } from '../state/decision-surface';
+import { logger } from '../utils/logger';
+import { sumUsage } from '../utils/sum-usage';
+import { describeInteraction } from './describe-interaction';
+import { headlessCurrentDebugLog } from './headless-debug';
+/** The holder id the session's interceptor is installed under: it observes, and never claims. */
+const HEADLESS_INTERCEPTOR_ID = 'headless';
+/**
+ * Stands in for a claimant when the transcript is rendered: the session is nobody's delegate, so
+ * every message reads as the person sees it, and none is dropped as "its own".
+ */
+const NOT_A_CLAIMANT = HEADLESS_INTERCEPTOR_ID;
+/** How long one `message` line or a turn's text may run, in characters. */
+const LINE_CAP_CHARS = 4000;
+/** How many events the log keeps; the oldest go first. A `wait` cursor older than that resumes at the oldest. */
+const MAX_EVENTS = 5000;
+/** How often an open turn is checked for having ended, when there is no bus to say so. */
+const TURN_POLL_MS = 50;
+/** The longest delay a timer holds: a larger one fires at once, with a warning. */
+const MAX_TIMER_MS = 2147483647;
+/** `text` for a log line, cut to the cap, with its full length when it was. */
+const capped = (text) => text.length > LINE_CAP_CHARS
+    ? { text: `${text.slice(0, LINE_CAP_CHARS)}…`, chars: text.length }
+    : { text };
+/** A wait's `maxWaitMs` as a timer can take it: not a number is 0, and it is cut to what a timer holds. */
+const timerMs = (ms) => Number.isNaN(Number(ms)) ? 0 : Math.min(Math.max(0, Number(ms)), MAX_TIMER_MS);
+const messageOf = (e) => (e instanceof Error ? e.message : String(e));
+/** Whether `value` has the shape of an autopilot: what `AutopilotHost` asks for, less its copy. */
+const isAutopilotLike = (value) => {
+    const v = value;
+    return (!!v &&
+        typeof v === 'object' &&
+        typeof v.subscribe === 'function' &&
+        typeof v.pause === 'function' &&
+        typeof v.resume === 'function' &&
+        typeof v.stop === 'function' &&
+        typeof v.state === 'object' &&
+        v.state !== null);
+};
+/**
+ * A driver with no screen: a way for a host with no browser (a coding agent behind a small HTTP
+ * server, a test) to run a whole assistant journey as the person (GENC-1660).
+ *
+ * It watches the driver for interactions and turns the conversation into an append-only log of
+ * plain-data events (see {@link HeadlessEvent}): `decision` when the person has something to
+ * answer, `working` when someone else has it, `settled`, the visible `message`s, the end of each
+ * `turn`, the autopilot's state, and the host's own `probe`. The caller reads the log with
+ * {@link HeadlessSession.wait}, a long poll cursored by `seq`, so nothing is lost between calls.
+ * It answers with {@link HeadlessSession.act}, which runs a widget's action as a click would, with
+ * the same numbered options the autopilot is shown.
+ *
+ * It only observes: its interceptor never claims an interaction, so an autopilot on the same
+ * driver works as it always does, and what the session reports as a `decision` is what the autopilot
+ * has handed to the person. Plain classes only: no DOM, no FAST.
+ *
+ * @beta
+ */
+export class HeadlessSession {
+    constructor(driver, options = {}) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        this.driver = driver;
+        this.options = options;
+        this.events = [];
+        this.seq = 0;
+        this.tracked = new Map();
+        /** What the session did to an interaction itself, for `settled` to say when the driver reports it. */
+        this.origin = new Map();
+        this.waiters = new Set();
+        this.teardown = [];
+        this.lastProbe = {};
+        this.lastAutopilot = '';
+        this.disposed = false;
+        if (typeof driver.addInteractionInterceptor !== 'function') {
+            throw new Error('HeadlessSession needs a driver that supports interaction interceptors (addInteractionInterceptor), and this one does not.');
+        }
+        this.sessionKey = (_c = (_a = options.sessionKey) !== null && _a !== void 0 ? _a : (_b = options.persistence) === null || _b === void 0 ? void 0 : _b.stateKey) !== null && _c !== void 0 ? _c : '';
+        this.allowRaw = (_d = options.allowRaw) !== null && _d !== void 0 ? _d : true;
+        this.clock = (_e = options.clock) !== null && _e !== void 0 ? _e : Date.now;
+        this.seen = this.history().length;
+        this.base = this.seen;
+        this.lastProbe = this.readProbe();
+        this.teardown.push(driver.addInteractionInterceptor({
+            id: HEADLESS_INTERCEPTOR_ID,
+            onInteractionOpened: (opened) => {
+                this.onOpened(opened);
+                // An observer: it never claims.
+                return undefined;
+            },
+        }));
+        this.listen('history-updated', () => this.onHistory());
+        this.listen('interaction-settled', (e) => this.onSettled(e
+            .detail));
+        // Turns end whoever started them: heard on the bus when the host shares it, else seen by
+        // watching the history and asking the driver whether it is busy.
+        if (options.activityBus) {
+            this.teardown.push(options.activityBus.subscribe('tool-loop-start', () => this.observe()), options.activityBus.subscribe('tool-loop-end', (detail) => {
+                if ((detail === null || detail === void 0 ? void 0 : detail.failureReason) && this.open)
+                    this.open.failureReason = detail.failureReason;
+                this.observe();
+            }));
+        }
+        const autopilot = (_f = options.autopilot) !== null && _f !== void 0 ? _f : (isAutopilotLike(driver) ? driver : undefined);
+        this.autopilotHost = autopilot;
+        if (autopilot) {
+            this.lastAutopilot = this.autopilotSignature();
+            this.teardown.push(autopilot.subscribe(() => this.onAutopilot()));
+        }
+        // After the listeners above, so the persister sees every change the log does.
+        this.persistence = (_g = options.persistence) === null || _g === void 0 ? void 0 : _g.attach({ driver, sessionKey: this.sessionKey });
+        recordMetaEvent(this.sessionKey, 'headless.attached', options.label !== undefined ? { label: options.label } : undefined);
+    }
+    // ---------------------------------------------------------------------------------------------
+    // The calls
+    // ---------------------------------------------------------------------------------------------
+    /**
+     * Send the person's message, and start the turn. Returns as soon as the turn has started, not
+     * when it ends: a turn includes every interaction parked on the person, so it can run as long as
+     * the journey. Its end is the `turn` event.
+     *
+     * Refused, never thrown, when the message is empty, or a turn is already running.
+     */
+    send(text, options = {}) {
+        var _a;
+        if (this.disposed)
+            return { ok: false, error: 'This session has been disposed.' };
+        if (typeof text !== 'string' || !text.trim()) {
+            return { ok: false, error: 'There is nothing to send: the message is empty.' };
+        }
+        if (this.turn || this.driver.isBusy()) {
+            return {
+                ok: false,
+                error: 'A turn is already running. Wait for it to end (the turn event), or answer what it is waiting on.',
+            };
+        }
+        // Idle, but its turn not yet reported: report it before this one begins.
+        this.closeTurn();
+        const start = this.history().length;
+        this.open = { start };
+        this.startPolling();
+        (_a = this.persistence) === null || _a === void 0 ? void 0 : _a.notePrompt(text);
+        let running;
+        try {
+            running = this.driver
+                .sendMessage(text, options.attachments, options.agent !== undefined ? { agent: options.agent } : undefined)
+                .then((result) => {
+                this.turn = undefined;
+                if (this.open) {
+                    this.open.reason = result.reason;
+                    this.open.failureReason = result.failureReason;
+                }
+                this.observe();
+            }, (e) => {
+                this.turn = undefined;
+                this.log({ type: 'error', where: 'turn', message: messageOf(e) });
+                if (this.open)
+                    this.open.reason = 'error';
+                this.observe();
+            });
+        }
+        catch (e) {
+            this.open = undefined;
+            this.stopPolling();
+            return { ok: false, error: messageOf(e) };
+        }
+        this.turn = running;
+        return { ok: true };
+    }
+    /**
+     * Run one of a pending interaction's actions as the person, as a click would (the answer is
+     * credited `answeredBy: 'user'`). `action` is a number from the description's actions, or an
+     * action's name; `args` carry the text, the options (numbers or labels) or the form's fields it
+     * takes. Refused, with the reason and what is enabled, when a claimant holds the interaction,
+     * the action is unknown or disabled, or its arguments do not fit: nothing runs then.
+     *
+     * The result is the driver's `InvokeResult`, plus `description` of the interaction when it is
+     * still open.
+     */
+    act(interactionId_1, action_1) {
+        return __awaiter(this, arguments, void 0, function* (interactionId, action, args = {}) {
+            var _a;
+            if (typeof this.driver.invokeAsUser !== 'function') {
+                return {
+                    ok: false,
+                    error: 'no-surface',
+                    message: 'This driver cannot run an action as the person (it has no invokeAsUser).',
+                };
+            }
+            const t = this.tracked.get(interactionId);
+            const requested = String(action !== null && action !== void 0 ? action : '').trim();
+            let name = requested;
+            let invokeArgs = args;
+            if (t === null || t === void 0 ? void 0 : t.ctx.surface) {
+                const surface = t.ctx.surface;
+                // The numbers as the description shows them now: the list's order is stable, so this is the
+                // list the caller read.
+                const numbering = this.describe(t)
+                    .actions.filter((a) => a.n !== undefined)
+                    .map((a) => a.name);
+                const byNumber = byNumberOf(numbering);
+                name = (_a = byNumber(requested)) !== null && _a !== void 0 ? _a : requested;
+                const listed = surface.actions().find((a) => a.name === name);
+                const built = invokeArgsFor(listed, args, byNumber);
+                if (!built.ok) {
+                    return {
+                        ok: false,
+                        error: 'invalid-args',
+                        message: `fields is not valid JSON. ${fieldsExample(name, listed === null || listed === void 0 ? void 0 : listed.argsSchema)}`,
+                    };
+                }
+                invokeArgs = built.args;
+            }
+            const result = yield this.driver.invokeAsUser(interactionId, name, invokeArgs);
+            if (t)
+                this.evaluate(t);
+            const still = this.tracked.get(interactionId);
+            return still && !still.settled ? Object.assign(Object.assign({}, result), { description: this.describe(still) }) : result;
+        });
+    }
+    /**
+     * Settle a pending interaction raw, with `result` as the widget would have resolved it,
+     * bypassing its actions and everything they check: an escape hatch for a widget with no
+     * controller, or one that cannot be acted on. Logs `settled` with `raw: true` and records
+     * `headless.raw-resolved`. Refused when `allowRaw` is `false`, when the interaction is not
+     * pending, or when a claimant holds it: as for `act`, the person takes it back first.
+     */
+    resolve(interactionId, result) {
+        if (!this.allowRaw) {
+            return { ok: false, error: 'Settling an interaction raw is not allowed in this session.' };
+        }
+        const t = this.tracked.get(interactionId);
+        if (!t || t.settled) {
+            return { ok: false, error: `No pending interaction "${interactionId}".` };
+        }
+        if (t.ctx.heldBy !== 'user') {
+            return {
+                ok: false,
+                error: 'Another agent holds this interaction, so it was not resolved. The person has to take it back first, for example by pausing the autopilot.',
+            };
+        }
+        this.origin.set(interactionId, { raw: true });
+        try {
+            this.driver.resolveInteraction(interactionId, result);
+        }
+        catch (e) {
+            this.origin.delete(interactionId);
+            return { ok: false, error: messageOf(e) };
+        }
+        recordMetaEvent(this.sessionKey, 'headless.raw-resolved', {
+            interactionId,
+            component: t.componentName,
+        });
+        return { ok: true };
+    }
+    /**
+     * Read from a pending interaction without changing it: one of its views, or (with `tool`) one of
+     * the widget tools given to the session. The text is capped. A view the surface does not list is
+     * refused, naming those it does, as the autopilot's `widget_read` does.
+     */
+    read(interactionId_1) {
+        return __awaiter(this, arguments, void 0, function* (interactionId, request = {}) {
+            var _a, _b;
+            const t = this.tracked.get(interactionId);
+            if (!t || t.settled)
+                return { ok: false, error: `No pending interaction "${interactionId}".` };
+            if (request.tool !== undefined && request.view !== undefined) {
+                return { ok: false, error: 'Ask for a view or a tool, not both.' };
+            }
+            if (request.tool !== undefined)
+                return this.readTool(t, request.tool, request.args);
+            const { surface } = t.ctx;
+            if (!surface)
+                return { ok: false, error: 'This widget has nothing to read: it has no surface.' };
+            // A blank view is no view, as for the autopilot.
+            const view = typeof request.view === 'string' && request.view.trim() ? request.view.trim() : undefined;
+            const names = Object.keys((_a = surface.views) !== null && _a !== void 0 ? _a : {});
+            if (view !== undefined && names.length && !names.includes(view)) {
+                return { ok: false, error: `No view "${view}" here. Views: ${names.join(', ')}.` };
+            }
+            let state;
+            try {
+                state = surface.read ? surface.read(view) : surface.facts();
+            }
+            catch (e) {
+                return { ok: false, error: `Could not read: ${messageOf(e)}` };
+            }
+            if (state === undefined) {
+                return {
+                    ok: false,
+                    error: `Nothing to read without a view.${names.length ? ` Views: ${names.join(', ')}.` : ''}`,
+                };
+            }
+            return { ok: true, content: capRead((_b = JSON.stringify(state)) !== null && _b !== void 0 ? _b : 'null') };
+        });
+    }
+    /**
+     * Wait for the log to say something, then return what it said. Resolves as soon as an event in
+     * `until` is in the log after `since` (immediately, when one already is), or at `maxWaitMs` with
+     * status `'working'`. Either way it returns every event after `since`, and `nextSeq`, the cursor
+     * for the next call: poll with it and nothing is lost.
+     */
+    wait(request) {
+        var _a;
+        const since = (_a = request.since) !== null && _a !== void 0 ? _a : 0;
+        const { until } = request;
+        if (this.events.some((e) => e.seq > since && wanted(e, until))) {
+            return Promise.resolve(this.waited(since, 'ready'));
+        }
+        if (this.disposed)
+            return Promise.resolve(this.waited(since, 'closed'));
+        const { signal } = request;
+        if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+            return Promise.resolve(this.waited(since, 'working'));
+        return new Promise((resolve) => {
+            const onAbort = () => waiter.finish('working');
+            const waiter = {
+                since,
+                until,
+                finish: (status) => {
+                    clearTimeout(timer);
+                    signal === null || signal === void 0 ? void 0 : signal.removeEventListener('abort', onAbort);
+                    this.waiters.delete(waiter);
+                    resolve(this.waited(since, status));
+                },
+            };
+            this.waiters.add(waiter);
+            const timer = setTimeout(() => waiter.finish('working'), timerMs(request.maxWaitMs));
+            signal === null || signal === void 0 ? void 0 : signal.addEventListener('abort', onAbort, { once: true });
+        });
+    }
+    /** Every event logged after `since` (default: all the log keeps), without waiting. */
+    eventsSince(since = 0) {
+        return this.events.filter((e) => e.seq > since);
+    }
+    /**
+     * What is going on now: whether a turn runs, the interaction the person should answer first (and
+     * the others open behind it), the autopilot, what it has cost, and the host's probe.
+     */
+    state() {
+        var _a;
+        const open = [...this.tracked.values()].filter((t) => t.armed && !t.settled);
+        const described = open.map((t) => ({ t, d: this.describe(t) }));
+        const mine = described.find(({ d }) => d.heldBy === 'user' && d.ready);
+        const others = described
+            .filter((entry) => entry !== mine)
+            .map(({ d }) => ({
+            interactionId: d.interactionId,
+            component: d.component,
+            heldBy: d.heldBy,
+            ready: d.ready,
+        }));
+        const host = this.autopilotHost;
+        return Object.assign(Object.assign({ busy: this.turn !== undefined || this.driver.isBusy() || (host === null || host === void 0 ? void 0 : host.state.working) === true, pending: (_a = mine === null || mine === void 0 ? void 0 : mine.d) !== null && _a !== void 0 ? _a : null, others }, (host
+            ? {
+                autopilot: {
+                    mode: host.state.mode,
+                    status: host.state.status,
+                    needsUser: host.state.needsUser,
+                    working: host.state.working,
+                },
+            }
+            : {})), { cost: sumUsage(this.history()), probe: this.readProbe(), lastSeq: this.seq });
+    }
+    /**
+     * Save the session now: the snapshot, and the diagnostics appended since the last flush, rather
+     * than at the next throttled save. A no-op without `persistence`.
+     */
+    flush() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            yield ((_a = this.persistence) === null || _a === void 0 ? void 0 : _a.flush());
+        });
+    }
+    /**
+     * The debug log, the document the browser's Download gives. With `persistence`, the log of the
+     * whole session stitched from the stored stream with a fresh `meta-snapshot` (`lifetimeDebugLog`,
+     * the same code); without, the current page's, from `buildDiagnosticEntries`. Never throws.
+     */
+    debugLog() {
+        if (this.persistence)
+            return this.persistence.debugLog();
+        return Promise.resolve(headlessCurrentDebugLog(this.driver, this.sessionKey, this.options.debug));
+    }
+    /** Stop the running turn, when the driver can. */
+    stop() {
+        if (typeof this.driver.cancel !== 'function') {
+            return { ok: false, error: 'This driver cannot cancel a turn.' };
+        }
+        this.driver.cancel();
+        return { ok: true };
+    }
+    /**
+     * Pause, resume or stop the autopilot, when there is one. Pausing hands what it holds to the
+     * person, which then appears as a `decision`.
+     *
+     * `'keepPaused'` is the hand-back banner's "Keep paused": it turns the autopilot's own hand-back
+     * of one interaction into an ordinary pause, so it does not take the question back once it is
+     * answered. `interactionId` names the interaction handed back; omitted, it is the one the
+     * autopilot's own pause is waiting on (`state().autopilot`'s hand-back, the `decision` it left
+     * with the person). Refused, with why, when the autopilot has handed nothing back, when
+     * `interactionId` is not the one it handed back, or when the host cannot keep paused; the host's
+     * own `keepPaused` would do nothing in those cases without saying so.
+     */
+    autopilot(mode, interactionId) {
+        const host = this.autopilotHost;
+        if (!host)
+            return { ok: false, error: 'There is no autopilot on this driver.' };
+        try {
+            if (mode === 'keepPaused')
+                return this.keepPaused(host, interactionId);
+            host[mode]();
+        }
+        catch (e) {
+            return { ok: false, error: messageOf(e) };
+        }
+        return { ok: true };
+    }
+    keepPaused(host, interactionId) {
+        if (typeof host.keepPaused !== 'function') {
+            return { ok: false, error: 'This autopilot cannot keep paused.' };
+        }
+        const pause = host.state.pause;
+        if ((pause === null || pause === void 0 ? void 0 : pause.scope) !== 'this-interaction' || !pause.interactionId) {
+            return {
+                ok: false,
+                error: 'The autopilot has not handed a question back, so there is nothing to keep paused.',
+            };
+        }
+        const handedBack = pause.interactionId;
+        if (interactionId !== undefined && interactionId !== handedBack) {
+            return {
+                ok: false,
+                error: `The autopilot handed back ${handedBack}, not ${interactionId}.`,
+            };
+        }
+        host.keepPaused(handedBack);
+        return { ok: true };
+    }
+    /** Detach: remove the interceptor and every subscription, and release anyone waiting. */
+    dispose() {
+        var _a;
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const t of this.tracked.values())
+            this.release(t);
+        clearTimeout(this.quiesceTimer);
+        this.stopPolling();
+        (_a = this.persistence) === null || _a === void 0 ? void 0 : _a.dispose();
+        for (const off of this.teardown.splice(0)) {
+            try {
+                off();
+            }
+            catch (e) {
+                logger.warn('HeadlessSession: a teardown threw:', e);
+            }
+        }
+        for (const waiter of this.waiters)
+            waiter.finish('closed');
+    }
+    // ---------------------------------------------------------------------------------------------
+    // Watching the driver
+    // ---------------------------------------------------------------------------------------------
+    listen(type, handler) {
+        this.driver.addEventListener(type, handler);
+        this.teardown.push(() => this.driver.removeEventListener(type, handler));
+    }
+    history() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.driver).getRawHistory) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : [];
+    }
+    /** An interaction opened: watch it. Who holds it is not decided yet, so it is reported later. */
+    onOpened(opened) {
+        if (this.disposed)
+            return;
+        const { ctx } = opened;
+        const t = {
+            id: opened.interactionId,
+            ctx,
+            componentName: opened.componentName,
+            data: opened.data,
+            ownerPath: opened.ownerPath,
+            unsubs: [],
+            armed: false,
+            settled: false,
+            autoTried: false,
+        };
+        this.tracked.set(t.id, t);
+        // Holder changes (a claimant handing back), working and readiness all notify.
+        t.unsubs.push(ctx.subscribe(() => this.evaluate(t)));
+        t.unsubs.push(ctx.onSurfaceReady(() => this.evaluate(t)));
+        ctx.onDispose(() => this.onEnded(t));
+        // After the open has completed: the interceptors after this one may yet claim it, and the
+        // driver holds a resolution made before its message exists, but is not relied on here.
+        queueMicrotask(() => {
+            if (this.disposed || t.settled)
+                return;
+            t.armed = true;
+            this.evaluate(t);
+        });
+    }
+    /** The driver says an interaction settled, by whatever route. */
+    onSettled(detail) {
+        const t = this.tracked.get(detail.interactionId);
+        if (!t || t.settled)
+            return;
+        const origin = this.origin.get(t.id);
+        this.settle(t, Object.assign(Object.assign(Object.assign(Object.assign({}, (detail.answeredBy ? { answeredBy: detail.answeredBy } : {})), (detail.resolvedItself ? { resolvedItself: true } : {})), ((origin === null || origin === void 0 ? void 0 : origin.auto) ? { auto: true } : {})), ((origin === null || origin === void 0 ? void 0 : origin.raw) ? { raw: true } : {})));
+    }
+    /** The interaction's context was disposed: if nothing said it settled, say it did. */
+    onEnded(t) {
+        if (!t.settled)
+            this.settle(t, {});
+    }
+    settle(t, how) {
+        t.settled = true;
+        if (!this.disposed) {
+            this.log(Object.assign({ type: 'settled', interactionId: t.id, component: t.componentName }, how));
+        }
+        this.release(t);
+    }
+    release(t) {
+        for (const off of t.unsubs.splice(0)) {
+            try {
+                off();
+            }
+            catch (_a) {
+                // Already gone with its context.
+            }
+        }
+        t.settled = true;
+        this.tracked.delete(t.id);
+        this.origin.delete(t.id);
+    }
+    /** New messages in the driver's history: report what the person would see of them. */
+    onHistory() {
+        if (this.disposed)
+            return;
+        this.reportMessages();
+        this.observe();
+    }
+    reportMessages() {
+        const history = this.history();
+        // Shorter than before: a compaction replaced it. Carry on from its end.
+        if (history.length < this.seen) {
+            this.seen = history.length;
+            return;
+        }
+        const fresh = history.slice(this.seen);
+        this.seen = history.length;
+        // Interactions are reported as decisions and settlements, not as lines.
+        const lines = visibleTranscript(fresh.filter((m) => !m.interaction), { claimant: NOT_A_CLAIMANT });
+        for (const line of lines)
+            this.log(Object.assign({ type: 'message' }, capped(line)));
+    }
+    onAutopilot() {
+        var _a;
+        if (this.disposed || !this.autopilotHost)
+            return;
+        const signature = this.autopilotSignature();
+        if (signature === this.lastAutopilot)
+            return;
+        this.lastAutopilot = signature;
+        const { state } = this.autopilotHost;
+        this.log(Object.assign({ type: 'autopilot', mode: state.mode, status: state.status, needsUser: state.needsUser, working: state.working }, (((_a = state.pause) === null || _a === void 0 ? void 0 : _a.reason) ? { reason: state.pause.reason } : {})));
+    }
+    autopilotSignature() {
+        var _a;
+        const s = (_a = this.autopilotHost) === null || _a === void 0 ? void 0 : _a.state;
+        return s ? JSON.stringify([s.mode, s.status, s.needsUser, s.working]) : '';
+    }
+    // ---------------------------------------------------------------------------------------------
+    // Reporting an interaction
+    // ---------------------------------------------------------------------------------------------
+    describe(t) {
+        return describeInteraction({ ctx: t.ctx, componentName: t.componentName, data: t.data });
+    }
+    /**
+     * Report where an interaction stands, when that has changed. A `decision` when the person holds
+     * it and can act; `working` when a claimant holds it or it is not ready yet. A `decision` is
+     * logged again only when its description changed materially: who holds it, whether it is ready
+     * or has a controller, or which actions are enabled. The text and facts alone do not count.
+     */
+    evaluate(t) {
+        var _a, _b;
+        if (this.disposed || !t.armed || t.settled)
+            return;
+        if (this.autoSettle(t))
+            return;
+        let d;
+        try {
+            d = this.describe(t);
+        }
+        catch (e) {
+            this.log({ type: 'error', where: 'describe', message: messageOf(e) });
+            return;
+        }
+        if (d.heldBy === 'user' && d.ready) {
+            const sig = JSON.stringify([d.controller, d.actions.map((a) => [a.name, a.enabled])]);
+            if (((_a = t.last) === null || _a === void 0 ? void 0 : _a.kind) === 'decision' && t.last.sig === sig)
+                return;
+            t.last = { kind: 'decision', sig };
+            this.log(Object.assign(Object.assign({ type: 'decision' }, d), (t.ownerPath.length ? { ownerPath: t.ownerPath } : {})));
+            return;
+        }
+        const sig = `${d.heldBy}|${d.ready}`;
+        if (((_b = t.last) === null || _b === void 0 ? void 0 : _b.kind) === 'working' && t.last.sig === sig)
+            return;
+        t.last = { kind: 'working', sig };
+        this.log({
+            type: 'working',
+            interactionId: t.id,
+            component: t.componentName,
+            heldBy: d.heldBy,
+        });
+    }
+    /**
+     * Settle a widget that settles itself in a browser, as it would on mounting. Once, and only when
+     * the person holds it. Returns whether it settled it.
+     */
+    autoSettle(t) {
+        var _a;
+        const result = (_a = this.options.autoSettle) === null || _a === void 0 ? void 0 : _a[t.componentName];
+        if (!result || t.autoTried || t.ctx.heldBy !== 'user')
+            return false;
+        t.autoTried = true;
+        try {
+            const value = result(t.data);
+            this.origin.set(t.id, { auto: true });
+            this.driver.resolveInteraction(t.id, value);
+            return true;
+        }
+        catch (e) {
+            this.origin.delete(t.id);
+            this.log({
+                type: 'error',
+                where: 'auto-settle',
+                message: `${t.componentName}: ${messageOf(e)}`,
+            });
+            return false;
+        }
+    }
+    readTool(t, name, args) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const sets = ((_a = this.options.widgetTools) !== null && _a !== void 0 ? _a : []).filter((s) => s.componentName === t.componentName);
+            const names = sets.flatMap((s) => Object.keys(s.tools)).sort();
+            const spec = sets
+                .map((s) => (Object.prototype.hasOwnProperty.call(s.tools, name) ? s.tools[name] : undefined))
+                .find((s) => s !== undefined);
+            if (!spec) {
+                return {
+                    ok: false,
+                    error: names.length
+                        ? `No tool "${name}" for the "${t.componentName}" widget. Tools: ${names.join(', ')}.`
+                        : `The "${t.componentName}" widget has no tools.`,
+                };
+            }
+            const { controller } = t.ctx;
+            if (controller === undefined) {
+                return { ok: false, error: `The "${t.componentName}" widget has nothing to read from.` };
+            }
+            const why = unavailableReason(spec.unavailable, controller);
+            if (why !== undefined)
+                return { ok: false, error: `Not available right now: ${name}: ${why}.` };
+            const problem = checkArgs(args !== null && args !== void 0 ? args : {}, spec.definition.parameters);
+            if (problem)
+                return { ok: false, error: `Not done: ${name}: ${problem}` };
+            try {
+                const output = yield spec.run(controller, args !== null && args !== void 0 ? args : {});
+                return {
+                    ok: true,
+                    content: capRead(typeof output === 'string' ? output : ((_b = JSON.stringify(output)) !== null && _b !== void 0 ? _b : 'null')),
+                };
+            }
+            catch (e) {
+                return { ok: false, error: `Could not read: ${messageOf(e)}` };
+            }
+        });
+    }
+    // ---------------------------------------------------------------------------------------------
+    // The log
+    // ---------------------------------------------------------------------------------------------
+    /**
+     * Notice a turn begin or end, whoever started it. The driver being busy (or a `send` in flight)
+     * is a turn; once it has been idle for a beat the turn is over and is reported, once. The beat
+     * covers the gaps inside one turn, such as a hand-off continuing it, which are a microtask long.
+     * A turn that begins the instant another ends, with no idle between, is reported as one.
+     */
+    observe() {
+        if (this.disposed)
+            return;
+        if (this.turn || this.driver.isBusy()) {
+            clearTimeout(this.quiesceTimer);
+            this.quiesceTimer = undefined;
+            if (!this.open) {
+                this.open = { start: this.base };
+                this.startPolling();
+            }
+            return;
+        }
+        if (this.open && this.quiesceTimer === undefined) {
+            this.quiesceTimer = setTimeout(() => {
+                this.quiesceTimer = undefined;
+                this.closeTurn();
+            }, 0);
+        }
+    }
+    /** Report the open turn as ended, unless the driver is busy again. */
+    closeTurn() {
+        var _a;
+        const { open } = this;
+        if (this.disposed || !open || this.turn || this.driver.isBusy())
+            return;
+        clearTimeout(this.quiesceTimer);
+        this.quiesceTimer = undefined;
+        this.open = undefined;
+        this.stopPolling();
+        this.logTurn((_a = open.reason) !== null && _a !== void 0 ? _a : 'done', open.failureReason, open.start);
+        this.base = this.history().length;
+    }
+    /** Without a shared bus nothing says a turn ended, so while one is open the driver is asked. */
+    startPolling() {
+        var _a, _b;
+        if (this.options.activityBus || this.poller !== undefined)
+            return;
+        this.poller = setInterval(() => this.observe(), TURN_POLL_MS);
+        (_b = (_a = this.poller).unref) === null || _b === void 0 ? void 0 : _b.call(_a);
+    }
+    stopPolling() {
+        if (this.poller !== undefined)
+            clearInterval(this.poller);
+        this.poller = undefined;
+    }
+    logTurn(reason, failureReason, start) {
+        const text = finalText(this.history().slice(start));
+        this.log(Object.assign(Object.assign({ type: 'turn', reason }, (failureReason ? { failureReason } : {})), (text !== undefined ? capped(text) : {})));
+    }
+    log(event) {
+        this.append(event);
+        this.checkProbe();
+    }
+    append(event) {
+        this.seq += 1;
+        const entry = Object.assign(Object.assign({}, event), { seq: this.seq, at: new Date(this.clock()).toISOString() });
+        this.events.push(entry);
+        if (this.events.length > MAX_EVENTS)
+            this.events.splice(0, this.events.length - MAX_EVENTS);
+        for (const waiter of this.waiters) {
+            if (wanted(entry, waiter.until))
+                waiter.finish('ready');
+        }
+    }
+    readProbe() {
+        var _a, _b;
+        try {
+            const read = (_b = (_a = this.options).probe) === null || _b === void 0 ? void 0 : _b.call(_a);
+            return read ? Object.assign({}, read) : {};
+        }
+        catch (e) {
+            logger.warn('HeadlessSession: the probe threw:', e);
+            return {};
+        }
+    }
+    /** Read the probe again; a change in any top-level value is a `probe` event. */
+    checkProbe() {
+        if (!this.options.probe || this.disposed)
+            return;
+        const now = this.readProbe();
+        const keys = new Set([...Object.keys(this.lastProbe), ...Object.keys(now)]);
+        const changed = [...keys].filter((k) => JSON.stringify(this.lastProbe[k]) !== JSON.stringify(now[k]));
+        this.lastProbe = now;
+        if (changed.length)
+            this.append({ type: 'probe', probe: now, changed });
+    }
+    waited(since, status) {
+        return { events: this.eventsSince(since), status, nextSeq: this.seq };
+    }
+}
+/** Whether `event` ends a wait on `until`; by default, anything that needs the caller. */
+function wanted(event, until) {
+    if (until)
+        return until.includes(event.type);
+    return (event.type === 'decision' ||
+        event.type === 'turn' ||
+        event.type === 'error' ||
+        (event.type === 'autopilot' && event.needsUser));
+}
+/** What the assistant last said that the person sees: its final text for the turn, if any. */
+function finalText(messages) {
+    var _a, _b;
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const m = messages[i];
+        if (m.role === 'assistant' &&
+            !m.interaction &&
+            !((_a = m.toolCalls) === null || _a === void 0 ? void 0 : _a.length) &&
+            !m.thinking &&
+            m.category !== 'reasoning' &&
+            m.category !== 'narration' &&
+            ((_b = m.content) === null || _b === void 0 ? void 0 : _b.trim())) {
+            return m.content;
+        }
+    }
+    return undefined;
+}