@genesislcap/ai-assistant 15.60.0 → 15.62.0

package/dist/esm/autopilot/autopilot-driver.js

@@ -0,0 +1,906 @@
+import { __awaiter } from "tslib";
+import { BaseDriverDecorator } from '../components/ai-driver/base-driver-decorator';
+import { recordMetaEvent } from '../state/debug-event-log';
+import { getInteractionRegistration, registerInteraction } from '../state/interaction-registry';
+import { logger } from '../utils/logger';
+import { AutopilotSession, positiveOr } from './autopilot-session';
+import { AUTOPILOT_HAND_BACK, HandBackController, handBackAsText, } from './hand-back/hand-back.controller';
+/**
+ * The holder id the autopilot claims interactions as.
+ *
+ * @beta
+ */
+export const AUTOPILOT_CLAIMANT = 'autopilot';
+/** How the working agent is told about a decision when the config gives no phrase. */
+const DEFAULT_DECISION_FRAMING = "Decided on the user's behalf";
+/** How a written answer sent on the user's behalf is framed, when the config gives no phrase. */
+const DEFAULT_REPLY_FRAMING = "Answered on the user's behalf.";
+/**
+ * Written answers the autopilot may send in a row, each answering a question the working agent
+ * ended its turn on, before the next question goes to the person instead: a loop between two agents
+ * talking to each other is a failure, not a conversation.
+ */
+const MAX_CONSECUTIVE_REPLIES = 2;
+/** The transient note that carries the working agent on, after the person said to. */
+const CARRY_ON_PRIMER = '[The user asked you to carry on with the plan on their behalf.]';
+/** Turn failures that are walls with their own UI, not something to offer to retry. */
+const WALLS = new Set([
+    'budget-exhausted',
+    'provider-refused',
+    'ai-service-error',
+]);
+/** Written answers per step before `reply` is withdrawn, unless the config says otherwise. */
+const DEFAULT_MAX_REFINEMENTS = 2;
+/** How long a claimed interaction may go quiet before the watchdog hands it back. */
+const DEFAULT_WATCHDOG_MS = 600000; // 10 minutes
+/** How many times the watchdog looks within one window. */
+const WATCHDOG_CHECKS_PER_WINDOW = 4;
+const DEFAULT_COPY = {
+    running: 'Working on your behalf',
+    paused: 'Paused',
+    selfPaused: "Waiting for your answer: I'll carry on after this",
+    handBackLead: 'I need your input on this one:',
+    toggleLabel: 'Autopilot',
+    description: "Answers the assistant's questions on your behalf, so the work keeps going.",
+    pauseLabel: 'Pause autopilot',
+    resumeLabel: 'Resume autopilot',
+    resumeDecideLabel: 'Resume autopilot and force it to decide this one',
+    keepPausedLabel: 'Keep paused',
+    markLabel: 'Done in autopilot mode',
+    checkInMessage: "I've done a lot in one go, so I've stopped to check in. Shall I carry on?",
+    carryOnLabel: 'Carry on',
+    tooLongMessage: 'This conversation has grown too long for me to carry on as it is.',
+    compactLabel: 'Compact and carry on',
+    failedMessage: 'Something went wrong on that last step.',
+    tryAgainLabel: 'Try again',
+    sendLabel: 'Send',
+    budgetReason: 'This one is taking more working out than I expected, so over to you.',
+    errorReason: 'Something went wrong while I was deciding this one.',
+    noDecisionReason: "I couldn't settle this one.",
+    watchdogReason: 'This is taking longer than expected, so I need you to look at it.',
+};
+/**
+ * Autopilot (GENC-1660): a driver decorator that answers the questions a working agent asks the
+ * user, on their behalf, grounded in the agent's autopilot config (for bootstrap, the brief).
+ *
+ * Neither side calls the other. The working agent asks as it always does; this driver claims the
+ * interactions its policy allows, while it is running for that flow, and answers each in one short
+ * turn on the flow's `AutopilotSession`. It plugs in only through the generic extension points
+ * — an interaction interceptor, a handler capability and the flow lifecycle — so the core knows
+ * nothing about it, and it wraps any `AiDriver`.
+ *
+ * @beta
+ */
+export class AutopilotDriver extends BaseDriverDecorator {
+    constructor(inner, options) {
+        var _a, _b, _c;
+        super(inner);
+        this.listeners = new Set();
+        this.sessions = new Map();
+        /** The flow the mode applies to: set when it is first switched, cleared when that flow ends. */
+        this.onFor = null;
+        this.mode = 'paused';
+        /** What sessions that have ended did, kept for the debug log. */
+        this.endedDiagnostics = [];
+        /** Written answers sent in a row; see `MAX_CONSECUTIVE_REPLIES`. */
+        this.consecutiveReplies = 0;
+        /**
+         * Bumped on every pause and resume, and when its sessions end. A written answer is sent only if
+         * none came between asking for it and its landing: one started before a pause is stale after it,
+         * even once resumed.
+         */
+        this.generation = 0;
+        /** Working turns this driver has started that have not ended yet; see `working`. */
+        this.turnsInFlight = 0;
+        /** Written questions being answered right now; see `working`. */
+        this.answersInFlight = 0;
+        this.agents = options.agents;
+        this.providerRegistry = options.providerRegistry;
+        this.sessionKey = (_a = options.sessionKey) !== null && _a !== void 0 ? _a : '';
+        // The turn-level hand-back is a widget like any other: registered, so it has a controller and a
+        // text form. Once per app, whichever autopilot gets there first.
+        if (!getInteractionRegistration(AUTOPILOT_HAND_BACK)) {
+            registerInteraction(AUTOPILOT_HAND_BACK, {
+                controller: (data, ctx) => new HandBackController(data, ctx),
+                asText: handBackAsText,
+            });
+        }
+        const framing = () => {
+            var _a;
+            const owner = this.flowOwner();
+            return (owner && ((_a = this.bindingFor(owner)) === null || _a === void 0 ? void 0 : _a.config.decisionFraming)) || DEFAULT_DECISION_FRAMING;
+        };
+        // Unset means the platform's own wording.
+        const editFraming = () => {
+            var _a;
+            const owner = this.flowOwner();
+            return (owner && ((_a = this.bindingFor(owner)) === null || _a === void 0 ? void 0 : _a.config.editFraming)) || undefined;
+        };
+        // Every hook on the inner driver is undone by `detach()`, so this decorator can be dropped
+        // while the driver it wrapped lives on.
+        const removeInterceptor = (_b = inner.addInteractionInterceptor) === null || _b === void 0 ? void 0 : _b.call(inner, {
+            id: AUTOPILOT_CLAIMANT,
+            // Read when a claimed interaction settles: the framing of the flow the autopilot serves.
+            get decisionFraming() {
+                return framing();
+            },
+            // Read when the person finishes an interaction the autopilot had changed first.
+            get editFraming() {
+                return editFraming();
+            },
+            onInteractionOpened: (opened) => this.onInteractionOpened(opened),
+        });
+        if (removeInterceptor)
+            this.onDetach(removeInterceptor);
+        const removeCapability = (_c = inner.provideHandlerCapability) === null || _c === void 0 ? void 0 : _c.call(inner, AUTOPILOT_CLAIMANT, (scope) => this.capabilityFor(scope));
+        if (removeCapability)
+            this.onDetach(removeCapability);
+        const onFlowOwnerChanged = (e) => this.onFlowOwnerChanged(e.detail);
+        // Availability can change with the agent's state (a brief being approved), which nothing
+        // announces; the transcript moving is the cheapest reliable nudge to re-read it.
+        const onHistoryUpdated = () => this.notify();
+        inner.addEventListener('flow-owner-changed', onFlowOwnerChanged);
+        inner.addEventListener('history-updated', onHistoryUpdated);
+        this.onDetach(() => {
+            this.disarmWatchdog();
+            inner.removeEventListener('flow-owner-changed', onFlowOwnerChanged);
+            inner.removeEventListener('history-updated', onHistoryUpdated);
+            this.releaseHeld();
+            this.endSessions();
+        });
+    }
+    // -----------------------------------------------------------------------------------------------
+    // AutopilotHost
+    // -----------------------------------------------------------------------------------------------
+    get state() {
+        var _a;
+        const owner = this.flowOwner();
+        const working = this.turnsInFlight > 0 || this.answersInFlight > 0 || this.inner.isBusy();
+        if (!owner || !this.isAvailable(owner)) {
+            return { mode: 'unavailable', status: '', needsUser: false, working };
+        }
+        const mode = this.onFor === owner ? this.mode : 'paused';
+        const copy = this.copyFor(owner);
+        const selfPaused = ((_a = this.pauseState) === null || _a === void 0 ? void 0 : _a.scope) === 'this-interaction';
+        return Object.assign(Object.assign({ mode }, (this.pauseState ? { pause: this.pauseState } : {})), { status: selfPaused ? copy.selfPaused : mode === 'running' ? copy.running : copy.paused, needsUser: selfPaused || !!this.turnHandBack, working });
+    }
+    get copy() {
+        return this.copyFor(this.flowOwner());
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    pause() {
+        var _a, _b;
+        const owner = this.flowOwner();
+        if (!owner || !this.isAvailable(owner))
+            return;
+        this.onFor = owner;
+        this.mode = 'paused';
+        this.pauseState = { scope: 'until-resumed' };
+        this.generation += 1;
+        const held = this.held;
+        if (held && held.opened.ctx.heldBy === AUTOPILOT_CLAIMANT) {
+            held.handedOver = 'pause';
+            (_a = this.sessions.get(held.agentName)) === null || _a === void 0 ? void 0 : _a.abort();
+            held.opened.hold.set('user');
+        }
+        // A written question it is answering is the person's now: its answer is stopped, and would be
+        // dropped if it landed anyway (see `generation`). They answer by typing.
+        if (this.answersInFlight > 0)
+            (_b = this.sessions.get(owner)) === null || _b === void 0 ? void 0 : _b.abort();
+        this.record('autopilot.paused', { scope: 'until-resumed', flow: owner });
+        this.notify();
+    }
+    resume() {
+        var _a;
+        const owner = this.flowOwner();
+        if (!owner || !this.isAvailable(owner))
+            return;
+        const wasSelfPaused = ((_a = this.pauseState) === null || _a === void 0 ? void 0 : _a.scope) === 'this-interaction';
+        this.onFor = owner;
+        this.mode = 'running';
+        this.pauseState = undefined;
+        this.generation += 1;
+        this.record('autopilot.resumed', { flow: owner, decideYourself: wasSelfPaused });
+        const held = this.held;
+        if (held === null || held === void 0 ? void 0 : held.handedOver) {
+            // Pausing handed it over, so take it back; a self-pause the person resumed means "decide it
+            // yourself", so take it back without the option to hand it back again.
+            held.handedOver = undefined;
+            if (held.opened.hold.set('claimant')) {
+                // Watched again, as when it was first claimed: the watchdog stops for good once it hands
+                // an interaction back, and a decision that stalled once may well stall again.
+                this.armWatchdog(held);
+                this.decide(held, { allowHandBack: !wasSelfPaused });
+            }
+        }
+        else if (!held && !this.turnHandBack && !this.inner.isBusy()) {
+            // Resumed with the working agent idle — its turn ended waiting for the person — so carry it
+            // on, or nothing would happen until they typed: answer the question it ended on, if it ended
+            // on one nobody answered, or tell it to carry on. Only on a live Resume, never on a restore.
+            const question = this.lastQuestion();
+            if (question) {
+                this.answerInBackground(owner, question);
+            }
+            else {
+                void this.continueFromHistory([{ role: 'user', content: CARRY_ON_PRIMER }]);
+            }
+        }
+        this.notify();
+    }
+    stop() {
+        var _a, _b;
+        (_b = (_a = this.inner).cancel) === null || _b === void 0 ? void 0 : _b.call(_a);
+        this.pause();
+    }
+    // -----------------------------------------------------------------------------------------------
+    // Persistence (§4.8): the mode is saved with the session and restored with it
+    // -----------------------------------------------------------------------------------------------
+    /** The mode to save with the session, while it is set for the current flow. */
+    getPersistedMode() {
+        const owner = this.flowOwner();
+        if (!owner || this.onFor !== owner)
+            return undefined;
+        return { onFor: owner, mode: this.mode };
+    }
+    /**
+     * Bring back a saved mode. It applies once its flow is the owner again — at once if it already
+     * is, otherwise when the restored flow re-activates. Restoring starts nothing: the autopilot acts
+     * only on live events, such as the working agent's own resume asking a question (§4.10, S3).
+     */
+    restorePersistedMode(saved) {
+        this.restored = saved;
+        const owner = this.flowOwner();
+        if (owner)
+            this.adoptRestored(owner);
+    }
+    adoptRestored(owner) {
+        const saved = this.restored;
+        if (!saved)
+            return;
+        this.restored = undefined;
+        // Another flow took over first, so the saved mode has nothing left to apply to.
+        if (saved.onFor !== owner)
+            return;
+        this.onFor = owner;
+        this.mode = saved.mode;
+        this.pauseState = undefined;
+        this.record(saved.mode === 'running' ? 'autopilot.resumed' : 'autopilot.paused', {
+            trigger: 'restored',
+            flow: owner,
+        });
+        this.notify();
+    }
+    keepPaused(interactionId) {
+        var _a;
+        if (((_a = this.pauseState) === null || _a === void 0 ? void 0 : _a.scope) !== 'this-interaction')
+            return;
+        if (this.pauseState.interactionId !== interactionId)
+            return;
+        this.generation += 1;
+        this.mode = 'paused';
+        this.pauseState = { scope: 'until-resumed' };
+        if (this.held)
+            this.held.handedOver = 'pause';
+        this.record('autopilot.paused', { scope: 'until-resumed', trigger: 'keep-paused' });
+        this.notify();
+    }
+    // -----------------------------------------------------------------------------------------------
+    // Turns: how each working turn ended decides what the autopilot does next (§4.2, §4.10)
+    // -----------------------------------------------------------------------------------------------
+    sendMessage(input, attachments, options) {
+        const _super = Object.create(null, {
+            sendMessage: { get: () => super.sendMessage }
+        });
+        return __awaiter(this, void 0, void 0, function* () {
+            // A message the person typed starts a fresh run of answers on their behalf.
+            if (!(options === null || options === void 0 ? void 0 : options.delegate))
+                this.consecutiveReplies = 0;
+            const result = yield this.whileWorking(() => _super.sendMessage.call(this, input, attachments, options));
+            this.afterTurn(result);
+            return result;
+        });
+    }
+    continueFromHistory(transientPrimer, options) {
+        const _super = Object.create(null, {
+            continueFromHistory: { get: () => super.continueFromHistory }
+        });
+        return __awaiter(this, void 0, void 0, function* () {
+            const result = yield this.whileWorking(() => _super.continueFromHistory.call(this, transientPrimer, options));
+            this.afterTurn(result);
+            return result;
+        });
+    }
+    resumeRestoredFlow(resumeNote, agent) {
+        const _super = Object.create(null, {
+            resumeRestoredFlow: { get: () => super.resumeRestoredFlow }
+        });
+        return __awaiter(this, void 0, void 0, function* () {
+            const result = yield this.whileWorking(() => _super.resumeRestoredFlow.call(this, resumeNote, agent));
+            if (result)
+                this.afterTurn(result);
+            else
+                this.notify();
+            return result;
+        });
+    }
+    /**
+     * Run a working turn, counted for `working` from the moment it is asked for: the wrapped driver
+     * may not say it is busy until some way in. The caller notifies once it has acted on the end.
+     */
+    whileWorking(run) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.turnsInFlight += 1;
+            this.notify();
+            let ended = false;
+            try {
+                const result = yield run();
+                ended = true;
+                return result;
+            }
+            finally {
+                this.turnsInFlight -= 1;
+                if (!ended)
+                    this.notify();
+            }
+        });
+    }
+    /**
+     * Act on how a working turn ended, without holding up whoever awaited it, then notify: idle
+     * unless that started something (an answer, a hand-back), which it does before this returns.
+     */
+    afterTurn(result) {
+        void this.onTurnEnded(result).catch((e) => {
+            logger.error('AutopilotDriver: handling the end of a turn failed:', e);
+            this.record('autopilot.error', { message: e instanceof Error ? e.message : String(e) });
+        });
+        this.notify();
+    }
+    onTurnEnded(result) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const owner = this.flowOwner();
+            // Nothing to do unless the autopilot is running for a flow that is still going.
+            if (!owner || this.onFor !== owner || this.mode !== 'running' || this.pauseState)
+                return;
+            if (this.held || this.turnHandBack || this.inner.isBusy())
+                return;
+            const failure = result.reason === 'done' ? result.failureReason : undefined;
+            if (failure) {
+                // A wall (the budget, a refused account) keeps its own UI and is not the person's to retry.
+                if (WALLS.has(failure))
+                    return;
+                yield this.presentHandBack(failure === 'max-iterations'
+                    ? 'max-iterations'
+                    : failure === 'context-exhausted'
+                        ? 'context-exhausted'
+                        : 'failure');
+                return;
+            }
+            // Ended cleanly with the flow still running: the working agent is waiting for the person to type.
+            const question = this.lastQuestion();
+            if (!question)
+                return;
+            if (this.consecutiveReplies >= MAX_CONSECUTIVE_REPLIES) {
+                yield this.presentHandBack('question', { question });
+                return;
+            }
+            yield this.answer(owner, question);
+        });
+    }
+    /** {@link AutopilotDriver.answer}, from a caller that does not wait for it. */
+    answerInBackground(owner, question) {
+        void this.answer(owner, question).catch((e) => {
+            logger.error('AutopilotDriver: answering a question failed:', e);
+            this.record('autopilot.error', { message: e instanceof Error ? e.message : String(e) });
+        });
+    }
+    /**
+     * Answer a written question the working agent ended its turn on, and send the answer on the
+     * user's behalf, with what writing it cost booked on that message (§4.2).
+     *
+     * Sent only if the question still stands when the answer lands: no pause or resume since it was
+     * asked (Pause stops it, and the question is the person's to answer by typing), the flow still
+     * running, the working agent idle, and the question still the last thing it said. Otherwise the
+     * answer goes nowhere — not sent, not counted, not recorded as acted — and its cost is recorded as
+     * dropped, as it is whenever no reply is sent to carry it.
+     */
+    answer(owner, question) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            const session = this.sessionFor(owner);
+            if (!session)
+                return;
+            const generation = this.generation;
+            const stands = () => this.generation === generation &&
+                this.flowOwner() === owner &&
+                this.onFor === owner &&
+                this.mode === 'running' &&
+                !this.pauseState &&
+                !this.inner.isBusy() &&
+                this.lastQuestion() === question;
+            this.answersInFlight += 1;
+            this.notify();
+            let outcome;
+            try {
+                outcome = yield session.answerQuestion(question, {
+                    allowHandBack: true,
+                    stillWanted: stands,
+                });
+            }
+            catch (e) {
+                this.answersInFlight -= 1;
+                this.notify();
+                throw e;
+            }
+            // Not notified yet: what follows (a reply, a hand-back, or nothing) notifies.
+            this.answersInFlight -= 1;
+            const cost = (_a = outcome.costUsd) !== null && _a !== void 0 ? _a : 0;
+            if (!stands()) {
+                this.dropCost(cost, 'stale');
+                this.notify();
+                return;
+            }
+            if (outcome.kind === 'replied') {
+                this.consecutiveReplies += 1;
+                this.record('autopilot.acted', { action: 'reply', question: true });
+                const framing = (_c = (_b = this.bindingFor(owner)) === null || _b === void 0 ? void 0 : _b.config.decisionFraming) !== null && _c !== void 0 ? _c : DEFAULT_REPLY_FRAMING;
+                yield this.sendMessage(outcome.text, undefined, {
+                    delegate: AUTOPILOT_CLAIMANT,
+                    delegateFraming: framing,
+                    externalCostUsd: cost,
+                });
+                return;
+            }
+            this.dropCost(cost, outcome.kind);
+            if (outcome.kind === 'handed-back') {
+                yield this.presentHandBack('question', { question, reason: outcome.reason });
+            }
+            else {
+                this.notify();
+            }
+        });
+    }
+    /**
+     * Spend on a written answer that no reply carries into the session total — it was handed back,
+     * stopped, or went stale — recorded so it is never lost silently.
+     */
+    dropCost(costUsd, why) {
+        if (costUsd > 0)
+            this.record('autopilot.cost-dropped', { costUsd, why });
+    }
+    /** The working agent's last visible words, when its turn ended on them. */
+    lastQuestion() {
+        var _a, _b, _c, _d;
+        const history = (_c = (_b = (_a = this.inner).getRawHistory) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : [];
+        const last = [...history].reverse().find((m) => m.role !== 'system-event' && !m.thinking);
+        if (!last || last.role !== 'assistant' || last.interaction || last.delegate)
+            return undefined;
+        if (last.excludeFromProvider ||
+            last.category === 'reasoning' ||
+            last.category === 'narration') {
+            return undefined;
+        }
+        return ((_d = last.content) === null || _d === void 0 ? void 0 : _d.trim()) || undefined;
+    }
+    /**
+     * The turn-level hand-back (§4.10): a working turn ended needing the person and there is no
+     * widget to hand over, so the autopilot shows its own, `userOnly`, and acts on the choice.
+     */
+    presentHandBack(why_1) {
+        return __awaiter(this, arguments, void 0, function* (why, opts = {}) {
+            var _a, _b, _c, _d;
+            if (!this.inner.presentInteraction)
+                return;
+            const copy = this.copy;
+            const pauseOption = { id: 'pause', label: copy.pauseLabel };
+            const data = why === 'max-iterations'
+                ? {
+                    message: copy.checkInMessage,
+                    options: [{ id: 'carry-on', label: copy.carryOnLabel }, pauseOption],
+                }
+                : why === 'context-exhausted'
+                    ? {
+                        message: copy.tooLongMessage,
+                        options: [{ id: 'compact', label: copy.compactLabel }, pauseOption],
+                    }
+                    : why === 'failure'
+                        ? {
+                            message: copy.failedMessage,
+                            options: [{ id: 'try-again', label: copy.tryAgainLabel }, pauseOption],
+                        }
+                        : {
+                            message: opts.reason ? `${copy.handBackLead} ${opts.reason}` : copy.handBackLead,
+                            question: opts.question,
+                            freeText: true,
+                            sendLabel: copy.sendLabel,
+                            options: [pauseOption],
+                        };
+            this.turnHandBack = { why };
+            this.consecutiveReplies = 0;
+            this.notify();
+            let result;
+            try {
+                result = yield this.inner.presentInteraction(AUTOPILOT_HAND_BACK, data, {
+                    userOnly: true,
+                });
+            }
+            finally {
+                this.turnHandBack = undefined;
+                this.notify();
+            }
+            const choice = (_a = result === null || result === void 0 ? void 0 : result.payload) === null || _a === void 0 ? void 0 : _a.choice;
+            this.record('autopilot.handback-presented', Object.assign({ why, options: data.options.map((o) => o.id) }, (choice ? { choice } : {})));
+            if (!choice)
+                return;
+            if (choice === 'pause') {
+                this.pause();
+            }
+            else if (choice === 'reply') {
+                // The person's own words: an ordinary message, not one sent on their behalf.
+                yield this.sendMessage((_b = result.payload.text) !== null && _b !== void 0 ? _b : '');
+            }
+            else {
+                if (choice === 'compact')
+                    yield ((_d = (_c = this.inner).compact) === null || _d === void 0 ? void 0 : _d.call(_c));
+                yield this.continueFromHistory([{ role: 'user', content: CARRY_ON_PRIMER }]);
+            }
+        });
+    }
+    /**
+     * The inner driver's diagnostics, then everything the autopilot did (§4.8): diagnostics compose
+     * down the decorator stack, so they reach the downloaded and the persisted debug log through the
+     * host's existing external-diagnostics channel.
+     */
+    getExternalDiagnostics() {
+        return [
+            ...super.getExternalDiagnostics(),
+            ...this.endedDiagnostics,
+            ...[...this.sessions.values()].flatMap((session) => session.diagnostics()),
+        ];
+    }
+    /**
+     * Close every session, keeping what it did for the debug log. An answer one was still writing is
+     * stale from here: it is never sent, and its cost is recorded as dropped when it lands.
+     */
+    endSessions() {
+        this.generation += 1;
+        for (const session of this.sessions.values()) {
+            this.endedDiagnostics.push(...session.diagnostics());
+            session.dispose();
+        }
+        this.sessions.clear();
+    }
+    dispose() {
+        const _super = Object.create(null, {
+            dispose: { get: () => super.dispose }
+        });
+        return __awaiter(this, void 0, void 0, function* () {
+            this.endSessions();
+            yield _super.dispose.call(this);
+        });
+    }
+    // -----------------------------------------------------------------------------------------------
+    // Claiming and deciding
+    // -----------------------------------------------------------------------------------------------
+    onInteractionOpened(opened) {
+        var _a, _b;
+        const decline = (reason) => {
+            this.record('autopilot.declined', {
+                interactionId: opened.interactionId,
+                component: opened.componentName,
+                reason,
+            });
+            return undefined;
+        };
+        const owner = this.flowOwner();
+        if (!owner || this.onFor !== owner || this.mode !== 'running')
+            return decline('paused');
+        if (opened.ownerPath[0] !== owner)
+            return decline('other-flow');
+        // The innermost agent on the path that declares an autopilot answers for it: sub-agents
+        // inherit their flow's.
+        const agentName = [...opened.ownerPath].reverse().find((name) => this.bindingFor(name));
+        const binding = agentName ? this.bindingFor(agentName) : undefined;
+        if (!agentName || !binding)
+            return decline('no-autopilot');
+        if (!this.isAvailable(owner))
+            return decline('unavailable');
+        if (opened.userOnly)
+            return decline('userOnly');
+        if (((_b = (_a = binding.config.widgetPolicy) === null || _a === void 0 ? void 0 : _a[opened.componentName]) !== null && _b !== void 0 ? _b : 'human-first') !== 'allowed') {
+            return decline('policy');
+        }
+        if (opened.ctx.controller === undefined)
+            return decline('no-controller');
+        const held = { opened, agentName };
+        this.held = held;
+        opened.ctx.onDispose(() => this.onSettled(held));
+        this.record('autopilot.claimed', {
+            interactionId: opened.interactionId,
+            component: opened.componentName,
+            ownerPath: opened.ownerPath,
+        });
+        this.armWatchdog(held);
+        // The claim is granted only once this returns, so act on it after.
+        queueMicrotask(() => {
+            opened.ctx.onSurfaceReady(() => {
+                if (this.held === held && opened.ctx.heldBy === AUTOPILOT_CLAIMANT) {
+                    this.decide(held, { allowHandBack: true });
+                }
+            });
+        });
+        return 'claim';
+    }
+    /** Run one decision on the flow's session, and act on how it ended. */
+    decide(held, options) {
+        const session = this.sessionFor(held.agentName);
+        if (!session)
+            return;
+        const key = this.stepKey(held);
+        session
+            .decide(held.opened, Object.assign(Object.assign({}, options), { allowReply: this.mayRefine(held, key), onReply: () => this.countRefinement(held, key) }))
+            .then((outcome) => this.onDecided(held, outcome))
+            .catch((e) => {
+            logger.error('AutopilotDriver: a decision failed:', e);
+            this.record('autopilot.error', {
+                interactionId: held.opened.interactionId,
+                message: e instanceof Error ? e.message : String(e),
+            });
+            this.handBack(held, this.copyFor(held.agentName).errorReason, 'error');
+        });
+    }
+    /** The step a decision belongs to, for the refinement limit (§4.4). */
+    stepKey(held) {
+        var _a, _b, _c;
+        const { stepKey } = (_b = (_a = this.bindingFor(held.agentName)) === null || _a === void 0 ? void 0 : _a.config) !== null && _b !== void 0 ? _b : {};
+        const state = (_c = this.bindingFor(held.agentName)) === null || _c === void 0 ? void 0 : _c.state();
+        try {
+            if (stepKey && state !== undefined)
+                return stepKey({ state });
+        }
+        catch (e) {
+            logger.warn('AutopilotDriver: stepKey threw; using the component name:', e);
+        }
+        return held.opened.componentName;
+    }
+    /** Whether a written answer is still allowed on this step. The count resets when the step changes. */
+    mayRefine(held, key) {
+        var _a;
+        if (((_a = this.refinements) === null || _a === void 0 ? void 0 : _a.key) !== key)
+            this.refinements = { key, count: 0 };
+        return this.refinements.count < this.refinementLimit(held);
+    }
+    countRefinement(held, key) {
+        var _a;
+        if (((_a = this.refinements) === null || _a === void 0 ? void 0 : _a.key) !== key)
+            this.refinements = { key, count: 0 };
+        this.refinements.count += 1;
+        const limit = this.refinementLimit(held);
+        this.record('autopilot.refinement', {
+            interactionId: held.opened.interactionId,
+            stepKey: key,
+            count: this.refinements.count,
+            limitReached: this.refinements.count >= limit,
+        });
+    }
+    /** Written answers allowed per step: the config's when it is a whole number `>= 0`. */
+    refinementLimit(held) {
+        var _a;
+        const limit = (_a = this.bindingFor(held.agentName)) === null || _a === void 0 ? void 0 : _a.config.maxRefinements;
+        return typeof limit === 'number' && Number.isFinite(limit) && limit >= 0
+            ? limit
+            : DEFAULT_MAX_REFINEMENTS;
+    }
+    /**
+     * The watchdog (§4.2, critique S5): a claimed interaction whose work has gone quiet for longer
+     * than `watchdogMs` is handed back rather than left to hang silently. Quiet is either no surface
+     * ready to act on and no heartbeat, or the autopilot's own decision still running with no model
+     * call landing and no heartbeat — a stalled model call, which nothing else times out. It checks a
+     * few times per window, and stops when the interaction settles.
+     */
+    armWatchdog(held) {
+        var _a;
+        this.disarmWatchdog();
+        const windowMs = positiveOr((_a = this.bindingFor(held.agentName)) === null || _a === void 0 ? void 0 : _a.config.watchdogMs, DEFAULT_WATCHDOG_MS);
+        const check = () => {
+            var _a, _b;
+            this.watchdog = undefined;
+            if (this.held !== held)
+                return;
+            const { ctx } = held.opened;
+            const deciding = (_a = this.sessions
+                .get(held.agentName)) === null || _a === void 0 ? void 0 : _a.decisionProgressAt(held.opened.interactionId);
+            const lastSign = Math.max(ctx.lastActivityAt, deciding !== null && deciding !== void 0 ? deciding : 0);
+            const quiet = Date.now() - lastSign > windowMs;
+            const waiting = deciding !== undefined || !((_b = ctx.surface) === null || _b === void 0 ? void 0 : _b.isReady());
+            if (ctx.heldBy === AUTOPILOT_CLAIMANT && waiting && quiet) {
+                this.handBack(held, this.copyFor(held.agentName).watchdogReason, 'watchdog');
+                return;
+            }
+            this.watchdog = setTimeout(check, Math.max(1, Math.floor(windowMs / WATCHDOG_CHECKS_PER_WINDOW)));
+        };
+        this.watchdog = setTimeout(check, Math.max(1, Math.floor(windowMs / WATCHDOG_CHECKS_PER_WINDOW)));
+    }
+    disarmWatchdog() {
+        if (this.watchdog !== undefined)
+            clearTimeout(this.watchdog);
+        this.watchdog = undefined;
+    }
+    onDecided(held, outcome) {
+        if (outcome.kind !== 'handed-back')
+            return;
+        this.handBack(held, outcome.reason, outcome.trigger);
+    }
+    /**
+     * The autopilot's self-pause, for one interaction (§4.10): the person gets it, with the reason as
+     * the banner, and the autopilot carries on by itself once they answer. Only while it is still
+     * the autopilot's to hand back — not settled, not already with the person — and its decision
+     * stops with it, so a decision still running spends nothing more on an interaction it no longer
+     * holds. Every caller (a decision's own hand-back, a failed decision, the watchdog) gets both.
+     */
+    handBack(held, reason, trigger) {
+        var _a;
+        if (this.held !== held || held.opened.ctx.heldBy !== AUTOPILOT_CLAIMANT)
+            return;
+        (_a = this.sessions.get(held.agentName)) === null || _a === void 0 ? void 0 : _a.abort();
+        held.handedOver = 'self';
+        held.opened.hold.set('user');
+        this.pauseState = {
+            scope: 'this-interaction',
+            interactionId: held.opened.interactionId,
+            reason,
+        };
+        this.record('autopilot.handed-back', {
+            interactionId: held.opened.interactionId,
+            reason,
+            trigger,
+        });
+        this.notify();
+    }
+    /**
+     * On detach: hand a claimed interaction the autopilot still holds to the person, stopping its
+     * decision, so the driver it wrapped lives on with nothing held by an autopilot that is gone.
+     */
+    releaseHeld() {
+        var _a;
+        const held = this.held;
+        this.held = undefined;
+        if (!held || held.opened.ctx.heldBy !== AUTOPILOT_CLAIMANT)
+            return;
+        (_a = this.sessions.get(held.agentName)) === null || _a === void 0 ? void 0 : _a.abort();
+        held.opened.hold.set('user');
+        this.record('autopilot.handed-back', {
+            interactionId: held.opened.interactionId,
+            trigger: 'detached',
+        });
+    }
+    /** A claimed interaction settled, whoever settled it. */
+    onSettled(held) {
+        var _a, _b;
+        if (this.held !== held)
+            return;
+        this.held = undefined;
+        this.disarmWatchdog();
+        (_a = this.sessions.get(held.agentName)) === null || _a === void 0 ? void 0 : _a.abort();
+        // The autopilot's own hand-back ends when the person answers: it carries on by itself.
+        if (((_b = this.pauseState) === null || _b === void 0 ? void 0 : _b.scope) === 'this-interaction' &&
+            this.pauseState.interactionId === held.opened.interactionId) {
+            this.pauseState = undefined;
+            this.record('autopilot.resumed', { trigger: 'answered', flow: this.onFor });
+        }
+        this.notify();
+    }
+    onFlowOwnerChanged(owner) {
+        if (owner === this.onFor)
+            return;
+        this.refinements = undefined;
+        // "On" is scoped to the flow it was set for: a new flow, or none, starts paused.
+        this.onFor = null;
+        this.mode = 'paused';
+        this.pauseState = undefined;
+        this.endSessions();
+        if (owner)
+            this.adoptRestored(owner);
+        this.notify();
+    }
+    capabilityFor(scope) {
+        const owner = scope.flowOwner;
+        if (!owner || !this.bindingFor(owner))
+            return undefined;
+        const currentMode = () => {
+            if (!this.isAvailable(owner))
+                return 'unavailable';
+            return this.onFor === owner ? this.mode : 'paused';
+        };
+        return {
+            get mode() {
+                return currentMode();
+            },
+            setMode: (mode) => {
+                if (this.flowOwner() !== owner)
+                    return;
+                if (mode === 'running')
+                    this.resume();
+                else
+                    this.pause();
+            },
+        };
+    }
+    // -----------------------------------------------------------------------------------------------
+    // Helpers
+    // -----------------------------------------------------------------------------------------------
+    flowOwner() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.inner).getFlowOwner) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : null;
+    }
+    bindingFor(agentName) {
+        var _a;
+        return (_a = this.agents.find((a) => a.name === agentName)) === null || _a === void 0 ? void 0 : _a.autopilot;
+    }
+    isAvailable(owner) {
+        const binding = this.bindingFor(owner);
+        if (!binding)
+            return false;
+        const { availableWhen } = binding.config;
+        if (!availableWhen)
+            return true;
+        const state = binding.state();
+        if (state === undefined)
+            return false;
+        try {
+            return availableWhen({ state });
+        }
+        catch (e) {
+            logger.warn('AutopilotDriver: availableWhen threw; treating as unavailable:', e);
+            return false;
+        }
+    }
+    copyFor(owner) {
+        var _a;
+        const custom = owner ? (_a = this.bindingFor(owner)) === null || _a === void 0 ? void 0 : _a.config.copy : undefined;
+        return Object.assign(Object.assign({}, DEFAULT_COPY), custom);
+    }
+    sessionFor(agentName) {
+        const existing = this.sessions.get(agentName);
+        if (existing)
+            return existing;
+        const binding = this.bindingFor(agentName);
+        if (!binding)
+            return undefined;
+        const session = new AutopilotSession({
+            agentName,
+            binding,
+            providerRegistry: this.providerRegistry,
+            sessionKey: this.sessionKey,
+            working: this.inner,
+            claimant: AUTOPILOT_CLAIMANT,
+            copy: this.copyFor(agentName),
+        });
+        this.sessions.set(agentName, session);
+        return session;
+    }
+    record(type, detail) {
+        recordMetaEvent(this.sessionKey, type, detail);
+    }
+    notify() {
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch (e) {
+                logger.error('AutopilotDriver: a subscriber threw', e);
+            }
+        }
+    }
+}
+/**
+ * The autopilot a host installed, if `driver` is one (GENC-1660). The host installs it outermost,
+ * so this is the driver it holds; nothing about the autopilot travels through `AiDriver`.
+ *
+ * @internal
+ */
+export const autopilotOf = (driver) => driver instanceof AutopilotDriver ? driver : undefined;