@genesislcap/ai-assistant 15.61.0 → 15.63.0

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

@@ -0,0 +1,449 @@
+import { __awaiter } from "tslib";
+import { NOOP_ACTIVITY_BUS } from '../channel/ai-activity-bus';
+import { ChatDriver } from '../components/chat-driver/chat-driver';
+import { clearSession, getMetaEvents, recordMetaEvent } from '../state/debug-event-log';
+import { buildTimelineEntries } from '../state/persistence/build-timeline-entries';
+import { logger } from '../utils/logger';
+import { sumUsage } from '../utils/sum-usage';
+import { AUTOPILOT_TOOL_DEFINITIONS, HAND_BACK, WIDGET_ACT, WIDGET_READ } from './autopilot-tools';
+import { renderActions, renderDecision, renderQuestion, visibleTranscript, } from './decision-message';
+/** Model calls a decision may take before it is handed back, unless the config says otherwise. */
+const DEFAULT_MAX_ITERATIONS_PER_DECISION = 6;
+/** The autopilot's own history, in characters, past which it is rebuilt short (§4.7, N3). */
+const DEFAULT_HISTORY_BUDGET_CHARS = 120000;
+/**
+ * The share of the history budget a rebuilt digest may fill, so the rebuilt history leaves room for
+ * the decisions that follow and does not pass the budget again straight away.
+ */
+const DIGEST_SHARE_OF_BUDGET = 0.5;
+/** Sessions created so far: each one's debug-log key is its own (see `ownSessionKey`). */
+let sessionCount = 0;
+/**
+ * A numeric guard from an autopilot's config: the value when it is a positive, finite number, the
+ * fallback otherwise — so `0`, a negative or `NaN` cannot turn a guard into a hair trigger.
+ */
+export const positiveOr = (value, fallback) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+/**
+ * The newest `lines` that fit in `maxChars`, after one line saying how many earlier ones were left
+ * out: a transcript cut to size from the old end, since what the autopilot decides next turns on the
+ * recent past.
+ */
+export function newestThatFit(lines, maxChars) {
+    let used = 0;
+    let first = lines.length;
+    while (first > 0 && used + lines[first - 1].length + 1 <= maxChars) {
+        first -= 1;
+        used += lines[first].length + 1;
+    }
+    return first > 0 ? [`[${first} earlier entries omitted]`, ...lines.slice(first)] : [...lines];
+}
+/** Characters in a history: content and tool arguments, which is what grows. */
+const historyChars = (messages) => messages.reduce((n, m) => {
+    var _a, _b, _c, _d;
+    return n +
+        ((_b = (_a = m.content) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) +
+        ((_d = (_c = m.toolResult) === null || _c === void 0 ? void 0 : _c.content.length) !== null && _d !== void 0 ? _d : 0) +
+        (m.toolCalls ? JSON.stringify(m.toolCalls.map((c) => c.args)).length : 0);
+}, 0);
+/** When the head compaction summary of `history` was made, if it has one. */
+const compactedAtOf = (history) => { var _a, _b; return (_b = (_a = history.find((m) => m.role === 'compacted-summary')) === null || _a === void 0 ? void 0 : _a.compaction) === null || _b === void 0 ? void 0 : _b.createdAt; };
+/** The last message of `history`, as the next decision finds it again. */
+function seenThrough(history) {
+    var _a;
+    const index = history.length - 1;
+    if (index < 0)
+        return undefined;
+    const last = history[index];
+    return Object.assign(Object.assign({}, (last.timestamp && last.role !== 'compacted-summary' ? { timestamp: last.timestamp } : {})), { role: last.role, content: last.content, interactionId: (_a = last.interaction) === null || _a === void 0 ? void 0 : _a.interactionId, index, compactedAt: compactedAtOf(history) });
+}
+/**
+ * Where to read `history` from: just after the message last seen, or `undefined` when there is none
+ * or it is gone — a compaction removed it — and the autopilot has to catch up.
+ */
+function readFrom(history, seen) {
+    var _a;
+    if (!seen)
+        return undefined;
+    if (seen.timestamp === undefined) {
+        // Saved before messages were stamped: the index holds only while nothing was compacted since.
+        const unmoved = compactedAtOf(history) === seen.compactedAt && seen.index < history.length;
+        return unmoved ? seen.index + 1 : undefined;
+    }
+    // From the end: several messages can share a millisecond, and the one seen was the last then.
+    for (let i = history.length - 1; i >= 0; i -= 1) {
+        const m = history[i];
+        if (m.role !== 'compacted-summary' &&
+            m.timestamp === seen.timestamp &&
+            m.role === seen.role &&
+            m.content === seen.content &&
+            ((_a = m.interaction) === null || _a === void 0 ? void 0 : _a.interactionId) === seen.interactionId) {
+            return i + 1;
+        }
+    }
+    return undefined;
+}
+/** Resolve a static-or-function config field against the working agent's live state. */
+const resolveWith = (input, ctx, state) => __awaiter(void 0, void 0, void 0, function* () {
+    return typeof input === 'function'
+        ? input(Object.assign(Object.assign({}, ctx), { state }))
+        : input;
+});
+/**
+ * One autopilot for one flow (GENC-1660): its own `ChatDriver`, its own history, and the last
+ * message of what the person has seen that it was told about. Each decision is one short turn on
+ * that driver, which ends when the autopilot acts or hands back.
+ *
+ * Its history holds only its own conversation — the decisions it was sent, its tool calls and
+ * their results — never the working agent's. What happened without it (answers the person gave,
+ * messages they typed, what the assistant showed) arrives at the top of the next decision as a
+ * `<since-last>` block, built from the working history by code. Its own messages in the working
+ * history (what it sent on the user's behalf) are left out of that block while its history holds
+ * them, and labelled as its own whenever it does not: on its first decision (after a reload, too),
+ * after a size rebuild, and when a compaction removed the last message it saw.
+ */
+export class AutopilotSession {
+    constructor(deps) {
+        this.deps = deps;
+        /** The tail of the decision queue: decisions run one after another, never interleaved. */
+        this.queue = Promise.resolve();
+        /** Its own messages a size-bounded rebuild dropped, kept for the debug log. */
+        this.archived = [];
+        const { config } = deps.binding;
+        sessionCount += 1;
+        this.ownKey = `${deps.sessionKey}::autopilot::${deps.agentName}::${sessionCount}`;
+        this.driver = new ChatDriver(deps.providerRegistry, {
+            sessionKey: this.ownSessionKey,
+            // Its own, inert activity channel: the host's loading state, halo and budget wall follow the
+            // working driver only.
+            activityBus: NOOP_ACTIVITY_BUS,
+            maxToolIterations: positiveOr(config.maxIterationsPerDecision, DEFAULT_MAX_ITERATIONS_PER_DECISION),
+        });
+        // Forced tool use, and the `completeSubAgent` early exit that ends a turn on an act or a
+        // hand-back.
+        this.driver.markAsSubAgent();
+        this.driver.installAgent(this.agentConfig());
+    }
+    /**
+     * Decide one interaction this autopilot holds. Resolves when the autopilot's turn ends, however it
+     * ended; the interaction itself is settled (or handed back) by then, unless the turn was aborted.
+     *
+     * Queued behind any decision still unwinding — an aborted one finishes its in-flight call before
+     * it can stop — so a Resume straight after a Pause is not lost. Checked again when its turn
+     * comes: if the autopilot no longer holds the interaction, nothing is sent.
+     */
+    decide(opened, options) {
+        return this.enqueue(() => __awaiter(this, void 0, void 0, function* () {
+            const surface = opened.ctx.surface;
+            if (!surface || opened.ctx.heldBy !== this.deps.claimant)
+                return { kind: 'aborted' };
+            const decision = renderDecision({
+                interactionId: opened.interactionId,
+                componentName: opened.componentName,
+                data: opened.data,
+                surface,
+                decideYourself: !options.allowHandBack,
+                withholdReply: !options.allowReply,
+            });
+            return this.runTurn(Object.assign(Object.assign({}, options), { opened, numbering: decision.numbering }), decision.text, opened.interactionId);
+        }));
+    }
+    /**
+     * Answer a written question the working agent ended its turn on (GENC-1660 §4.2): `replied` with
+     * the text to send on the user's behalf, or `handed-back`. Either way the outcome carries what it
+     * cost (see `DecisionOutcome`).
+     *
+     * Queued like `decide`, and checked again when its turn comes: if `stillWanted` says no — the
+     * person paused since it was asked — nothing is sent and it ends `aborted`.
+     */
+    answerQuestion(question, options) {
+        return this.enqueue(() => __awaiter(this, void 0, void 0, function* () {
+            if (options.stillWanted && !options.stillWanted())
+                return { kind: 'aborted' };
+            return this.runTurn({ allowHandBack: options.allowHandBack, allowReply: true, question, numbering: [] }, renderQuestion(question, { decideYourself: !options.allowHandBack }));
+        }));
+    }
+    /**
+     * Everything the autopilot did, as debug-log entries (§4.8): its turns (prompt, tools, model,
+     * usage), its messages (the decisions it was sent, its calls and their results) and its own
+     * events, tagged `delegate` and breadcrumbed with the agent it serves, so a replay can follow one
+     * decision from what it was shown to what it did and what it cost.
+     */
+    diagnostics() {
+        const label = `${this.deps.agentName} › Autopilot`;
+        return buildTimelineEntries({
+            turnSnapshots: this.driver.getTurnSnapshots(),
+            messages: [...this.archived, ...this.driver.getRawHistory()],
+            metaEvents: getMetaEvents(this.ownSessionKey),
+        }).map((entry) => (Object.assign(Object.assign({}, entry), { delegate: this.deps.claimant, agentName: label })));
+    }
+    /**
+     * The autopilot's own debug-log key: under the working session's, named for the agent it serves,
+     * and unique to this session, so two agents' autopilots never relabel each other's events and a
+     * later flow's session never reads an ended one's again. Cleared when the session is disposed,
+     * after the driver has harvested it.
+     */
+    get ownSessionKey() {
+        return this.ownKey;
+    }
+    /**
+     * When the decision on `interactionId` last showed progress (it started, or a model call or tool
+     * result landed); `undefined` when no decision on it is running. Read by the watchdog.
+     */
+    decisionProgressAt(interactionId) {
+        var _a, _b;
+        return ((_b = (_a = this.current) === null || _a === void 0 ? void 0 : _a.opened) === null || _b === void 0 ? void 0 : _b.interactionId) === interactionId ? this.progressAt : undefined;
+    }
+    /** Stop the decision in progress: the person took it back, or it ended another way. */
+    abort() {
+        var _a;
+        var _b;
+        if (!this.current)
+            return;
+        (_a = (_b = this.current).outcome) !== null && _a !== void 0 ? _a : (_b.outcome = { kind: 'aborted' });
+        this.driver.cancel();
+    }
+    /**
+     * Stop, and drop its debug-log bucket. The owner harvests `diagnostics()` first. Cleared again once
+     * the aborted turn has unwound, so nothing it records on the way out is left behind.
+     */
+    dispose() {
+        this.abort();
+        const key = this.ownSessionKey;
+        clearSession(key);
+        void Promise.allSettled([this.driver.dispose(), this.queue]).then(() => clearSession(key));
+    }
+    enqueue(run) {
+        const next = this.queue.then(run);
+        this.queue = next.catch(() => undefined);
+        return next;
+    }
+    /**
+     * One turn on the autopilot's driver: the `<since-last>` block, then the decision. Ends when the
+     * autopilot acts, replies or hands back, when it passes its spend cap, or when it runs out of
+     * calls. Books what it cost to `interactionId`; for a written question, which has none, returns
+     * it on the outcome for the driver to book on its reply.
+     */
+    runTurn(current, decisionText, interactionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e, _f, _g;
+            // Past its budget, the autopilot's own history is rebuilt: dropped, and replaced by a short-form
+            // digest of everything the person saw. Its first decision in a flow — including the first after a
+            // reload — is a catch-up too: the whole visible transcript, since it has seen none of it. So is a
+            // decision after a compaction removed the last message it saw: what came between is gone, and
+            // only the summary says what it was.
+            const budget = positiveOr(this.deps.binding.config.historyBudgetChars, DEFAULT_HISTORY_BUDGET_CHARS);
+            const ownChars = historyChars(this.driver.getRawHistory());
+            const rebuild = ownChars > budget;
+            if (rebuild) {
+                this.archived.push(...this.driver.getRawHistory());
+                this.driver.loadHistory([]);
+                this.seen = undefined;
+            }
+            const history = (_c = (_b = (_a = this.deps.working).getRawHistory) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : [];
+            const from = readFrom(history, this.seen);
+            const catchUp = from === undefined;
+            const why = rebuild ? 'size' : this.seen ? 'compacted' : 'first';
+            if (catchUp && history.length) {
+                recordMetaEvent(this.deps.sessionKey, 'autopilot.catch-up', Object.assign(Object.assign({ why }, (rebuild ? { ownChars } : {})), { messages: history.length }));
+            }
+            // A rebuild and a compaction both catch up in short form: there is a long flow behind them.
+            const short = catchUp && why !== 'first';
+            const transcript = visibleTranscript(history.slice(from !== null && from !== void 0 ? from : 0), {
+                claimant: this.deps.claimant,
+                skipInteractionId: interactionId,
+                short,
+                // On a catch-up its own history does not hold what it sent on the user's behalf.
+                includeOwn: catchUp,
+            });
+            // Short form shortens only older widgets, so on a long flow the digest alone could pass the
+            // budget, and every decision after would rebuild and resend it. Cut to a share of the budget.
+            const sinceLast = short
+                ? newestThatFit(transcript, Math.floor(budget * DIGEST_SHARE_OF_BUDGET))
+                : transcript;
+            this.seen = seenThrough(history);
+            const message = [
+                ...(sinceLast.length ? [`<since-last>\n${sinceLast.join('\n')}\n</since-last>`] : []),
+                decisionText,
+            ].join('\n');
+            this.current = current;
+            recordMetaEvent(this.deps.sessionKey, 'autopilot.decision-sent', Object.assign(Object.assign({}, (interactionId ? { interactionId } : { question: true })), { agent: this.deps.agentName, chars: message.length }));
+            const before = this.driver.getRawHistory().length;
+            // The per-decision spend cap, checked as each model call lands: past it, the decision is handed
+            // back rather than finished at any price.
+            const cap = positiveOr(this.deps.binding.config.maxDecisionCostUsd, undefined);
+            const { copy } = this.deps;
+            // Each landing is progress, for the watchdog; then the spend cap is checked.
+            const onHistory = () => {
+                this.progressAt = Date.now();
+                if (cap === undefined || !this.current || this.current.outcome)
+                    return;
+                const spent = sumUsage(this.driver.getRawHistory().slice(before)).costUsd;
+                if (spent <= cap)
+                    return;
+                this.current.outcome = { kind: 'handed-back', reason: copy.budgetReason, trigger: 'budget' };
+                this.driver.cancel();
+            };
+            this.progressAt = Date.now();
+            this.driver.addEventListener('history-updated', onHistory);
+            try {
+                yield this.driver.sendMessage(message);
+            }
+            catch (e) {
+                logger.error('AutopilotSession: the decision turn threw:', e);
+                (_d = current.outcome) !== null && _d !== void 0 ? _d : (current.outcome = { kind: 'handed-back', reason: copy.errorReason, trigger: 'error' });
+            }
+            this.driver.removeEventListener('history-updated', onHistory);
+            const outcome = (_e = current.outcome) !== null && _e !== void 0 ? _e : {
+                kind: 'handed-back',
+                reason: copy.noDecisionReason,
+                trigger: 'no-decision',
+            };
+            this.current = undefined;
+            this.progressAt = undefined;
+            // What this decision cost, so it reaches the session total: booked to the interaction it
+            // answered, or, for a written question, returned for the driver to book on its reply.
+            const cost = sumUsage(this.driver.getRawHistory().slice(before)).costUsd;
+            if (!interactionId)
+                return cost > 0 ? Object.assign(Object.assign({}, outcome), { costUsd: cost }) : outcome;
+            // A refused booking records its own dropped-cost event; a driver with no way to book records
+            // nothing, so it is recorded here.
+            if (cost > 0 && ((_g = (_f = this.deps.working).recordExternalCost) === null || _g === void 0 ? void 0 : _g.call(_f, interactionId, cost)) === undefined) {
+                recordMetaEvent(this.deps.sessionKey, 'autopilot.cost-dropped', {
+                    costUsd: cost,
+                    interactionId,
+                    why: 'no-recorder',
+                });
+            }
+            return outcome;
+        });
+    }
+    /** The autopilot as an agent: its config's resolvers bound to the working agent's state. */
+    agentConfig() {
+        var _a, _b, _c;
+        const { binding } = this.deps;
+        const { config } = binding;
+        return {
+            name: `${this.deps.agentName} autopilot`,
+            description: `Answers ${this.deps.agentName}'s questions on the user's behalf.`,
+            systemPrompt: (ctx) => __awaiter(this, void 0, void 0, function* () { var _a; return (_a = (yield resolveWith(config.systemPrompt, ctx, binding.state()))) !== null && _a !== void 0 ? _a : ''; }),
+            tailContext: config.tailContext
+                ? (ctx) => __awaiter(this, void 0, void 0, function* () { var _a; return (_a = (yield resolveWith(config.tailContext, ctx, binding.state()))) !== null && _a !== void 0 ? _a : ''; })
+                : undefined,
+            provider: typeof config.provider === 'function'
+                ? (ctx) => __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    return (_a = (yield resolveWith(config.provider, ctx, binding.state()))) !== null && _a !== void 0 ? _a : this.deps.providerRegistry.defaultName();
+                })
+                : config.provider,
+            // The prefix (tools, system, stored history) is stable by design, so cache all of it.
+            cachePolicy: { scope: 'history' },
+            toolDefinitions: [...AUTOPILOT_TOOL_DEFINITIONS, ...((_b = (_a = config.tools) === null || _a === void 0 ? void 0 : _a.definitions) !== null && _b !== void 0 ? _b : [])],
+            toolHandlers: Object.assign(Object.assign({}, (_c = config.tools) === null || _c === void 0 ? void 0 : _c.handlers), this.fixedHandlers()),
+        };
+    }
+    /** `widget_read`, `widget_act` and `hand_back`, acting on the decision in progress. */
+    fixedHandlers() {
+        const relist = () => {
+            var _a;
+            const current = this.current;
+            if ((current === null || current === void 0 ? void 0 : current.question) !== undefined) {
+                return "Actions:\n  reply({text}) — answer the question in the user's place";
+            }
+            const surface = (_a = current === null || current === void 0 ? void 0 : current.opened) === null || _a === void 0 ? void 0 : _a.ctx.surface;
+            if (!current || !surface)
+                return 'There is nothing to decide now.';
+            const actions = renderActions(surface.actions(), { withholdReply: !current.allowReply });
+            current.numbering = actions.numbering;
+            return actions.text;
+        };
+        return {
+            [WIDGET_READ]: (args, ctx) => __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                const current = this.current;
+                if ((current === null || current === void 0 ? void 0 : current.question) !== undefined)
+                    return `Question: ${current.question}\n${relist()}`;
+                const surface = (_a = current === null || current === void 0 ? void 0 : current.opened) === null || _a === void 0 ? void 0 : _a.ctx.surface;
+                if (!surface)
+                    return 'There is nothing to decide now.';
+                const view = args === null || args === void 0 ? void 0 : args.view;
+                // A full-form surface is read by view; a short-form decision has only its facts.
+                const state = surface.read ? surface.read(view) : surface.facts();
+                const result = `${JSON.stringify(state)}\n${relist()}`;
+                // A read serves the decision it was made for. Once that turn ends it is stale — the widget
+                // has moved on — so it leaves the autopilot's history as a one-line note rather than riding
+                // every later decision at full size. Not a re-read pointer: reading again would read the
+                // next decision, not this one.
+                (_b = ctx.condenseWhen) === null || _b === void 0 ? void 0 : _b.call(ctx, {
+                    on: { kind: 'turnEnd' },
+                    response: {
+                        replaceWith: `[An earlier read${view ? ` of the "${view}" view` : ''}, ${result.length} characters, for a decision that has since been made.]`,
+                    },
+                });
+                return result;
+            }),
+            [WIDGET_ACT]: (args, ctx) => __awaiter(this, void 0, void 0, function* () {
+                var _a, _b, _c, _d;
+                const current = this.current;
+                if (!current)
+                    return 'There is nothing to decide now.';
+                const { action, options, text, note, fields } = args;
+                // A written question has one action: the answer, sent on the user's behalf by the driver.
+                if (current.question !== undefined) {
+                    const answer = (text !== null && text !== void 0 ? text : '').trim();
+                    if (String(action !== null && action !== void 0 ? action : '').trim() !== 'reply' || !answer) {
+                        return `Not done: answer with action "reply" and your text.\n${relist()}`;
+                    }
+                    current.outcome = { kind: 'replied', text: answer };
+                    (_a = ctx.completeSubAgent) === null || _a === void 0 ? void 0 : _a.call(ctx, { replied: true });
+                    return 'Sent.';
+                }
+                const opened = current.opened;
+                // A number names an option in the list last sent; a name is a platform-owned action.
+                const byNumber = (value) => /^\d+$/.test(value.trim()) ? current.numbering[Number(value.trim()) - 1] : undefined;
+                const name = (_b = byNumber(String(action !== null && action !== void 0 ? action : ''))) !== null && _b !== void 0 ? _b : String(action !== null && action !== void 0 ? action : '').trim();
+                if (name === 'reply' && !current.allowReply) {
+                    return `Not done: a written answer is not available for this one; choose an option or hand it back.\n${relist()}`;
+                }
+                // A full-form action takes its arguments as `fields`, a JSON object sent as text.
+                let parsedFields;
+                if (fields !== undefined && fields !== '') {
+                    try {
+                        parsedFields = JSON.parse(fields);
+                    }
+                    catch (_e) {
+                        return `Not done: fields is not valid JSON.\n${relist()}`;
+                    }
+                }
+                const result = yield opened.hold.invoke(name, parsedFields !== undefined
+                    ? parsedFields
+                    : Object.assign(Object.assign({}, (options ? { options: options.map((o) => { var _a; return (_a = byNumber(o)) !== null && _a !== void 0 ? _a : o; }) } : {})), (text !== undefined ? { text } : {})), { note });
+                if (!result.ok) {
+                    return `Not done: ${result.message}\n${relist()}`;
+                }
+                if (name === 'reply')
+                    (_c = current.onReply) === null || _c === void 0 ? void 0 : _c.call(current);
+                recordMetaEvent(this.deps.sessionKey, 'autopilot.acted', Object.assign({ interactionId: opened.interactionId, action: name, finished: result.finished }, (note ? { note } : {})));
+                if (result.finished) {
+                    current.outcome = { kind: 'acted', action: name };
+                    (_d = ctx.completeSubAgent) === null || _d === void 0 ? void 0 : _d.call(ctx, { acted: name });
+                    return 'Done.';
+                }
+                const changed = result.output !== undefined ? `\nResult: ${JSON.stringify(result.output)}` : '';
+                return `Done, and it is still open.${changed}\n${relist()}`;
+            }),
+            [HAND_BACK]: (args, ctx) => __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                const current = this.current;
+                if (!current)
+                    return 'There is nothing to decide now.';
+                if (!current.allowHandBack) {
+                    return 'hand_back is not available: the user asked you to decide this one yourself.';
+                }
+                const reason = String((_a = args.reason) !== null && _a !== void 0 ? _a : '').trim();
+                current.outcome = { kind: 'handed-back', reason, trigger: 'model' };
+                (_b = ctx.completeSubAgent) === null || _b === void 0 ? void 0 : _b.call(ctx, { handedBack: reason });
+                return 'Handed to the user.';
+            }),
+        };
+    }
+}

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

@@ -0,0 +1,68 @@
+/** Read the widget as it stands now. */
+export const WIDGET_READ = 'widget_read';
+/** Run one of the widget's actions. */
+export const WIDGET_ACT = 'widget_act';
+/** Hand this one decision to the person. */
+export const HAND_BACK = 'hand_back';
+/**
+ * The autopilot's three fixed tools (GENC-1660 §4.2, §4.6). Fixed for every decision, so the cached
+ * prefix holds: what varies — the widget, its actions, their arguments — travels in the decision
+ * message, not here. Plain string and string-array fields only, which every provider accepts
+ * (critique round 2, N5: Gemini rejects a type-array union).
+ */
+export const AUTOPILOT_TOOL_DEFINITIONS = [
+    {
+        name: WIDGET_READ,
+        description: 'Read the current decision as it stands now: its state (one of its views, if it lists views), and its actions with their numbers and whether each is available. Use it when the decision message may be out of date, or to read a view it lists.',
+        parameters: {
+            type: 'object',
+            properties: {
+                view: { type: 'string', description: 'One of the views the decision lists, if any.' },
+            },
+        },
+    },
+    {
+        name: WIDGET_ACT,
+        description: 'Act on the current decision, as the user would by clicking. `action` is the number of an option from the decision\'s list (e.g. "1"), or a named action from that list: "select" with `options` to choose several, or "reply" with `text` to answer in your own words. ' +
+            'If it settles the decision, your turn ends. ' +
+            '`note` is shown to the user as the assistant speaking, before the outcome: one short sentence in the first person saying what you chose and why, e.g. "Your brief has no external feeds, so I\'ll skip Data Feeds." Never mention an autopilot or a second agent.',
+        parameters: {
+            type: 'object',
+            required: ['action'],
+            properties: {
+                action: {
+                    type: 'string',
+                    description: 'An option number from the list, starting at 1, or a named action ("select", "reply").',
+                },
+                options: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'For "select": the options to choose, by number or label.',
+                },
+                text: { type: 'string', description: 'For "reply": your answer, in the user\'s place.' },
+                fields: {
+                    type: 'string',
+                    description: 'For a named action that takes arguments: a JSON object, as text, matching the args schema the decision lists for it.',
+                },
+                note: {
+                    type: 'string',
+                    description: 'Shown to the user as the assistant speaking. One sentence, first person.',
+                },
+            },
+        },
+    },
+    {
+        name: HAND_BACK,
+        description: 'Give this one decision to the user, when it rests on something only they can know and neither their brief nor their own answers settle it. Your turn ends and the user sees the question. `reason` is shown to them as the assistant speaking, after "I need your input on this one:" — say plainly what you need from them. Never mention an autopilot or a second agent.',
+        parameters: {
+            type: 'object',
+            required: ['reason'],
+            properties: {
+                reason: {
+                    type: 'string',
+                    description: 'What the user needs to decide, and why it is theirs.',
+                },
+            },
+        },
+    },
+];