@genesislcap/ai-assistant 15.86.1 → 15.87.0

package/dist/esm/headless-server/types.js

@@ -0,0 +1,3 @@
+export const DECISION_TEXTS = ['full', 'lean'];
+/** What the server uses when neither it nor the command says. Its readers are models that can `read` a view. */
+export const DEFAULT_DECISION_TEXT = 'lean';

package/dist/esm/index.js

@@ -4,6 +4,9 @@ export * from './main/main.template';
 export * from './components/agent-picker';
 export * from './components/agent-session';
 export * from './autopilot';
+export * from './headless';
+// Persistence for a headless session reaches the session store, so it is here and not in the Node entry.
+export { headlessPersistence, } from './headless/headless-persistence';
 export * from './components/ai-driver';
 export * from './components/chat-driver';
 export * from './components/orchestrating-driver';

package/dist/esm/main/main.js

@@ -49,11 +49,11 @@ import { agentNotificationPermission, asAgentNotificationLevel, belongsToSession
 import { AgentNotifier } from '../notifications/agent-notifier';
 import { addNotificationSettingsHost, announceNotificationSettings, } from '../notifications/notification-settings';
 import { AssistantAppSettingsProvider, } from '../provider/assistant-app-settings';
-import { recordMetaEvent, getMetaEvents, clearSession as clearMetaSession, DEBUG_LOG_README, } from '../state/debug-event-log';
+import { recordMetaEvent, clearSession as clearMetaSession, DEBUG_LOG_README, } from '../state/debug-event-log';
 import { getOrCreateDriver, getDriver, getDriverAgentsKey, deleteDriver, } from '../state/driver-registry';
 import { getInteractionRegistration } from '../state/interaction-registry';
-import { buildTimelineEntries } from '../state/persistence/build-timeline-entries';
-import { assembleDebugLog, withFreshMetaSnapshot } from '../state/persistence/diagnostics';
+import { buildDiagnosticEntries, lifetimeDebugLog } from '../state/persistence/debug-log-assembly';
+import { assembleDebugLog } from '../state/persistence/diagnostics';
 import { deleteDiagnosticsCursorsFor, resetDiagnosticsCursorsFor, } from '../state/persistence/diagnostics-cursors';
 import { getOrCreatePersister, getPersister, deletePersister, } from '../state/persistence/persister-registry';
 import { resumeVerdict } from '../state/persistence/resume-verdict';
@@ -4059,25 +4059,12 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
      * been appended to the persisted stream.
      */
     buildDiagnosticEntries() {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
-        const stateKey = this.getStateKey();
-        // The message/turn/event timeline entries — built by the shared, pure `buildTimelineEntries`
-        // (the same helper a headless consumer uses to harvest its own log), from the driver's pull
-        // surfaces. Prefer the driver's raw history (carries sub-agent traces) over the redux projection.
-        const timelineEntries = buildTimelineEntries({
-            turnSnapshots: (_c = (_b = (_a = this.driver) === null || _a === void 0 ? void 0 : _a.getTurnSnapshots) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : [],
-            messages: (_f = (_e = (_d = this.driver) === null || _d === void 0 ? void 0 : _d.getRawHistory) === null || _e === void 0 ? void 0 : _e.call(_d)) !== null && _f !== void 0 ? _f : this.messages,
-            metaEvents: stateKey ? getMetaEvents(stateKey) : [],
+        return buildDiagnosticEntries({
+            driver: this.driver,
+            stateKey: this.getStateKey(),
+            metaSnapshot: () => this.buildMetaSnapshot(),
+            messages: this.messages,
         });
-        // Fold in any external diagnostics harvested from an out-of-band driver (e.g. a server-side
-        // ChatDriver whose collated log an interaction widget returned on its result). They ride the
-        // same download + persisted-diagnostics path; `assembleDebugLog` sorts the whole timeline by
-        // timestamp so they interleave chronologically. (GENC-1461 unified diagnostics.)
-        return [
-            ...timelineEntries,
-            ...((_j = (_h = (_g = this.driver) === null || _g === void 0 ? void 0 : _g.getExternalDiagnostics) === null || _h === void 0 ? void 0 : _h.call(_g)) !== null && _j !== void 0 ? _j : []),
-            this.buildMetaSnapshot(),
-        ];
     }
     /**
      * The `meta-snapshot` entry for right now. The assembly is a pure transformation
@@ -4383,23 +4370,17 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
      */
     getLifetimeDebugLog() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a;
-            const provider = this.persistence.provider;
-            const key = this.getStateKey();
-            if ((provider === null || provider === void 0 ? void 0 : provider.loadDiagnostics) && key) {
-                try {
-                    // Land the current page's unflushed delta first so the download includes it.
+            return lifetimeDebugLog({
+                provider: this.persistence.provider,
+                stateKey: this.getStateKey(),
+                // Land the current page's unflushed delta first so the download includes it.
+                flush: () => __awaiter(this, void 0, void 0, function* () {
+                    var _a;
                     yield ((_a = this.persister()) === null || _a === void 0 ? void 0 : _a.flushDiagnostics());
-                    const stored = yield provider.loadDiagnostics(key);
-                    if (stored.length) {
-                        return assembleDebugLog(withFreshMetaSnapshot(stored, this.buildMetaSnapshot()), DEBUG_LOG_README);
-                    }
-                }
-                catch (e) {
-                    logger.error('Diagnostics load failed — using current-page log:', e);
-                }
-            }
-            return this.getDebugLog();
+                }),
+                metaSnapshot: () => this.buildMetaSnapshot(),
+                fallback: () => this.getDebugLog(),
+            });
         });
     }
     /**

package/dist/esm/state/debug-event-log.js

@@ -108,6 +108,11 @@ export const META_EVENT_IMPORTANCE = {
     'autopilot.catch-up': 'normal',
     // Autopilot spend that reached no message, so it is missing from the session total.
     'autopilot.cost-dropped': 'high',
+    // A headless session attached to the driver: from here a host with no screen is the person.
+    'headless.attached': 'normal',
+    // The host settled an interaction raw, without the widget's own actions: its result went to the
+    // tool as given, unchecked by anything the widget would have enforced.
+    'headless.raw-resolved': 'normal',
     'external-diagnostics.folded': 'normal',
     'session.cleared': 'normal',
     'session.switched': 'low',
@@ -264,7 +269,7 @@ export const DEBUG_LOG_README = [
     "kind:'turn'.`agentSnapshot` — the active agent's own view of its internal state, captured at that turn. An agent opts into this by exposing a `getDebugSnapshot()` that returns JSON-serializable per-state info; stateful/flow agents wire it automatically, so you can watch a flow advance turn-by-turn (e.g. current step, cursor, collected fields, pending changes). Absent for agents that don't expose one.",
     "kind:'event' — a meta/lifecycle event. `type` names it (see below); `detail` carries structured data. `detail.placement` is the emitting UI instance: 'bubble' (collapsed), 'panel' (popped-out), or 'standalone'.",
     "Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, subagent.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions, sub-agent start/complete), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated, context.condensed). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. A 'high' turn.error is often preceded by one or more 'normal' turn.retry events for the same reason — read them together to see how many attempts were made before bailing. 'message' and 'turn' entries carry no importance — they are the substance, always read them.",
-    'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated/refusal/budget-exhausted/provider-refused/context-exhausted/ai-service-error, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, for budget-exhausted the budgetUsd + spentUsd figures reported by the proxy plus the resolved vendor, for provider-refused the kind (spend|auth) plus the upstream status and error type — the vendor refusing the ACCOUNT rather than us refusing to spend, so the remedy is a top-up or a key rotation rather than a raised cap, and the kind is the only place that distinction survives because the user-facing copy is deliberately cause-free, for context-exhausted the estimated contextTokens against the guard that stopped the turn plus the iterations reached — the driver ending a runaway tool loop at the edge of the context window rather than issuing a request the provider would reject, so the transcript survives intact and can still be compacted, for ai-service-error the code (one of AI_SERVICE_ERROR_CODES, e.g. NO_API_KEY) and the status the AI service answered with — its own text goes to the browser console only, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated/refusal/budget_exhausted/provider_refused/context_exhausted/ai_service_error; budget_exhausted and provider_refused are terminal for the PARENT turn too, and so is ai_service_error when the refusal is about the service rather than the request and came from the vendor the parent calls — the parent stops rather than calling the model again into the same wall; after context_exhausted the parent goes on, but its own next call is likely to stop on the same guard), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), routing.decided (ONE PER ROUTING DECISION — see its own paragraph below), provider.selected (the resolved provider for the upcoming turns — detail.provider is the registry SLOT/tier name, detail.model the concrete model behind it and detail.vendor its vendor; emitted only when the slot CHANGES, so read the per-turn `model` for the model of any given call rather than assuming the nearest event still applies), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver; detail.ownerPath names the agents that actually asked, outermost first, the last being the one whose tool requested it, and detail.heldBy says who held it when it opened: user, or the id of the interceptor that claimed it, such as autopilot; on interaction.resolved, detail.answeredBy is who answered — the claimant id when it settled through its own hold, user for any other answer (a click counts as the person even on a widget a claimant held) — absent when it closed unanswered (a timeout or a stop), and absent too when it settled by itself other than through the hold of a claimant — a widget registered resolvesItself (one that does its work and settles on its own, asking the person nothing, such as a generation run), or one outcome its controller said settled itself (ctx.resolve with resolvedItself, such as a generation phase that failed outright before its review gate ever asked anything) — which then carries detail.resolvedItself: true instead, as the interaction message does — nobody answered it, and the platform cannot tell it finishing from the person interrupting it (a Skip), so only the result of the widget itself can say which; the same value is stamped on the interaction message as answeredBy and on the result the asking tool handler receives (absent there in the same cases), and when it is not user the tool result that interaction returned carries a decidedOnUsersBehalf record, so the model was told the choice was not made by the person; detail.edits, present only when non-zero, counts the editing actions a claimant ran on the widget before it was settled, whoever settled it, and those edits are stamped on the interaction message as edits, each with by, action, choice and args when it had some, in the order they ran, while a decidedOnUsersBehalf record carries their choice texts as edits, and when the person settled it after such edits the tool result carries an editedOnUsersBehalf record instead — the framing and those choice texts — so the model knows the widget was changed on the user behalf before the user answered, and that the user then confirmed it by finishing it), interaction.held (a claimant moved a pending interaction to the person or back to itself — detail.heldBy is the new holder, detail.claimant the interceptor; detail.late: true is an interceptor that declined it when it opened claiming it afterwards, such as the autopilot resumed while it was open; a widget held by anything but user was not answered by the person), interaction.claim-refused (a claim on a userOnly interaction, which stays with the person — detail.claimant + reason), autopilot.* (the autopilot, a decorator that answers interactions on behalf of the user — autopilot.claimed / autopilot.declined say whether it took each interaction and, for a decline, detail.reason: paused, other-flow, no-autopilot, unavailable, userOnly, policy or no-controller; one declined as paused that is still open when the person resumes the autopilot is looked at again, and the autopilot.claimed or autopilot.declined recorded for it then carries detail.onResume: true (a decline then can also be claimed-elsewhere, another interceptor having claimed it first); a restored mode looks at nothing; autopilot.decision-sent is what it was sent (detail.chars; detail.nothingEnabled: true when every action on the widget was unavailable — a gate whose controller said it was asking, such as a failed build the autopilot may not cancel — so it could only hand it back, which it may then do even after the person asked it to decide it itself; a widget whose controller says it is working (ctx.setWorking) is never sent a decision until it says it is asking, even when an action is enabled or the person resumes the autopilot); autopilot.acted is what it did (detail.action, detail.note, detail.finished); autopilot.handed-back is a decision it gave to the person (detail.reason and detail.trigger: model, no-decision or error); autopilot.paused / autopilot.resumed are mode changes (detail.scope, detail.trigger, detail.decideYourself when the person resumed during a hand-back; detail.trigger is restored when the mode came back with the session after a reload, applied once its flow re-activated, which starts nothing by itself); autopilot.carried is the mode, running or paused, going with the task to the agent that took it over, rather than ending with the flow as on any other change of flow owner: to the target of a hand-off, or back to its caller on the hand-back (detail.from, detail.to, detail.mode); a pause the person chose goes with it, and Stop and Clear still end it; a mode restored for the target of a hand-off applies to its caller when the reload hands back; autopilot.error is the wrapper itself failing; autopilot.refinement counts a refining action against its step — a written answer (reply) or a widget action declared refines, such as a regenerate with instructions, counted together (detail.action, detail.stepKey, detail.count, detail.limitReached, after which every refining action is withdrawn for that step: not listed, and refused; the decision and every relisting of its actions say how many are left at the step, as a line Refinements left at this step: N, wherever the widget has a refining action); autopilot.handback-presented is the turn-level hand-back, shown when a working turn ended needing the person with no widget to hand over (detail.why: max-iterations, context-exhausted, failure or question; detail.options; detail.choice once answered); autopilot.catch-up is the autopilot being given the whole visible transcript at once (detail.why: first, for its first decision in a flow or after a reload; size, when its own history passed its budget and was rebuilt short — detail.ownChars; or compacted, when a compaction removed the last message it had seen, so it reads the summary and everything since, short; in each, what it had sent on the user behalf is included and labelled as its own, since its own history does not hold it); autopilot.cost-dropped is autopilot spend that no message carries, so it is NOT in the session total (detail.costUsd and detail.why: handed-back, aborted or stale for a written question it answered that no reply was sent for — stale when a pause, a resume, a new turn or the end of its flow came before the answer landed, which then went nowhere — or no-recorder when the driver had no way to book a decision to its interaction); a hand-back trigger can also be budget (the decision passed its spend cap), watchdog (its work went quiet: no ready surface and no heartbeat, or its own decision stalled with no model call landing, which stops that decision) or detached (the autopilot was removed while it held the interaction, which went to the person with no reason shown). To debug one autopilot decision, follow its interactionId: interaction.requested (heldBy), autopilot.claimed, autopilot.decision-sent, autopilot.acted or autopilot.handed-back, interaction.invoked, interaction.resolved (answeredBy), then the next turn of the working agent), interaction.invoked (a claimant ran one of the actions the widget itself exposes, through its hold, the same code the button runs — detail.claimant, detail.action (an option id, select or reply) and detail.finished, whether that settled the interaction, and when it did not, the run is recorded as an edit; the choice and narration it recorded reach the result of the tool that asked as decidedOnUsersBehalf), interaction.step (a long action run as named steps through runSteps, which survive a reload — detail.step and detail.outcome: started, done, skipped when the step was already done before a reload, or resumed when it started before a reload and runs again with what it saved part-way, such as a job id it re-attaches to), interaction.checkpoint (the checkpoints a conversation keeps for its long actions: the one in flight, and each one a reload cut, held apart until a request of its own widget type takes it over, so a resumed flow that opens other long widgets first, which save their own, loses nothing — detail.action: resumed when a reload cut the work and a request of the same widget type that the registration sameWork agrees is the same work took it over, refused when sameWork said a new request is different work (detail.saved is the identity it kept; detail.kept: true, since it stays for a later request of that type, and is offered to every one until one agrees) or when runSteps found the handed-over checkpoint malformed and started fresh (detail.reason, detail.saved), or cleared when its flow ended, once per checkpoint, with detail.cut: true for one a reload cut that nothing took over), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
+    "Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated/refusal/budget-exhausted/provider-refused/context-exhausted/ai-service-error, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, for budget-exhausted the budgetUsd + spentUsd figures reported by the proxy plus the resolved vendor, for provider-refused the kind (spend|auth) plus the upstream status and error type — the vendor refusing the ACCOUNT rather than us refusing to spend, so the remedy is a top-up or a key rotation rather than a raised cap, and the kind is the only place that distinction survives because the user-facing copy is deliberately cause-free, for context-exhausted the estimated contextTokens against the guard that stopped the turn plus the iterations reached — the driver ending a runaway tool loop at the edge of the context window rather than issuing a request the provider would reject, so the transcript survives intact and can still be compacted, for ai-service-error the code (one of AI_SERVICE_ERROR_CODES, e.g. NO_API_KEY) and the status the AI service answered with — its own text goes to the browser console only, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated/refusal/budget_exhausted/provider_refused/context_exhausted/ai_service_error; budget_exhausted and provider_refused are terminal for the PARENT turn too, and so is ai_service_error when the refusal is about the service rather than the request and came from the vendor the parent calls — the parent stops rather than calling the model again into the same wall; after context_exhausted the parent goes on, but its own next call is likely to stop on the same guard), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), routing.decided (ONE PER ROUTING DECISION — see its own paragraph below), provider.selected (the resolved provider for the upcoming turns — detail.provider is the registry SLOT/tier name, detail.model the concrete model behind it and detail.vendor its vendor; emitted only when the slot CHANGES, so read the per-turn `model` for the model of any given call rather than assuming the nearest event still applies), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver; detail.ownerPath names the agents that actually asked, outermost first, the last being the one whose tool requested it, and detail.heldBy says who held it when it opened: user, or the id of the interceptor that claimed it, such as autopilot; on interaction.resolved, detail.answeredBy is who answered — the claimant id when it settled through its own hold, user for any other answer (a click counts as the person even on a widget a claimant held) — absent when it closed unanswered (a timeout or a stop), and absent too when it settled by itself other than through the hold of a claimant — a widget registered resolvesItself (one that does its work and settles on its own, asking the person nothing, such as a generation run), or one outcome its controller said settled itself (ctx.resolve with resolvedItself, such as a generation phase that failed outright before its review gate ever asked anything) — which then carries detail.resolvedItself: true instead, as the interaction message does — nobody answered it, and the platform cannot tell it finishing from the person interrupting it (a Skip), so only the result of the widget itself can say which; the same value is stamped on the interaction message as answeredBy and on the result the asking tool handler receives (absent there in the same cases), and when it is not user the tool result that interaction returned carries a decidedOnUsersBehalf record, so the model was told the choice was not made by the person; detail.edits, present only when non-zero, counts the editing actions a claimant ran on the widget before it was settled, whoever settled it, and those edits are stamped on the interaction message as edits, each with by, action, choice and args when it had some, in the order they ran, while a decidedOnUsersBehalf record carries their choice texts as edits, and when the person settled it after such edits the tool result carries an editedOnUsersBehalf record instead — the framing and those choice texts — so the model knows the widget was changed on the user behalf before the user answered, and that the user then confirmed it by finishing it), interaction.held (a claimant moved a pending interaction to the person or back to itself — detail.heldBy is the new holder, detail.claimant the interceptor; detail.late: true is an interceptor that declined it when it opened claiming it afterwards, such as the autopilot resumed while it was open; a widget held by anything but user was not answered by the person), interaction.claim-refused (a claim on a userOnly interaction, which stays with the person — detail.claimant + reason), autopilot.* (the autopilot, a decorator that answers interactions on behalf of the user — autopilot.claimed / autopilot.declined say whether it took each interaction and, for a decline, detail.reason: paused, other-flow, no-autopilot, unavailable, userOnly, policy or no-controller; one declined as paused that is still open when the person resumes the autopilot is looked at again, and the autopilot.claimed or autopilot.declined recorded for it then carries detail.onResume: true (a decline then can also be claimed-elsewhere, another interceptor having claimed it first); a restored mode looks at nothing; autopilot.decision-sent is what it was sent (detail.chars; detail.nothingEnabled: true when every action on the widget was unavailable — a gate whose controller said it was asking, such as a failed build the autopilot may not cancel — so it could only hand it back, which it may then do even after the person asked it to decide it itself; a widget whose controller says it is working (ctx.setWorking) is never sent a decision until it says it is asking, even when an action is enabled or the person resumes the autopilot); autopilot.acted is what it did (detail.action, detail.note, detail.finished); autopilot.handed-back is a decision it gave to the person (detail.reason and detail.trigger: model, no-decision or error); autopilot.paused / autopilot.resumed are mode changes (detail.scope, detail.trigger, detail.decideYourself when the person resumed during a hand-back; detail.trigger is restored when the mode came back with the session after a reload, applied once its flow re-activated, which starts nothing by itself); autopilot.carried is the mode, running or paused, going with the task to the agent that took it over, rather than ending with the flow as on any other change of flow owner: to the target of a hand-off, or back to its caller on the hand-back (detail.from, detail.to, detail.mode); a pause the person chose goes with it, and Stop and Clear still end it; a mode restored for the target of a hand-off applies to its caller when the reload hands back; autopilot.error is the wrapper itself failing; autopilot.refinement counts a refining action against its step — a written answer (reply) or a widget action declared refines, such as a regenerate with instructions, counted together (detail.action, detail.stepKey, detail.count, detail.limitReached, after which every refining action is withdrawn for that step: not listed, and refused; the decision and every relisting of its actions say how many are left at the step, as a line Refinements left at this step: N, wherever the widget has a refining action); autopilot.handback-presented is the turn-level hand-back, shown when a working turn ended needing the person with no widget to hand over (detail.why: max-iterations, context-exhausted, failure or question; detail.options; detail.choice once answered); autopilot.catch-up is the autopilot being given the whole visible transcript at once (detail.why: first, for its first decision in a flow or after a reload; size, when its own history passed its budget and was rebuilt short — detail.ownChars; or compacted, when a compaction removed the last message it had seen, so it reads the summary and everything since, short; in each, what it had sent on the user behalf is included and labelled as its own, since its own history does not hold it); autopilot.cost-dropped is autopilot spend that no message carries, so it is NOT in the session total (detail.costUsd and detail.why: handed-back, aborted or stale for a written question it answered that no reply was sent for — stale when a pause, a resume, a new turn or the end of its flow came before the answer landed, which then went nowhere — or no-recorder when the driver had no way to book a decision to its interaction); a hand-back trigger can also be budget (the decision passed its spend cap), watchdog (its work went quiet: no ready surface and no heartbeat, or its own decision stalled with no model call landing, which stops that decision) or detached (the autopilot was removed while it held the interaction, which went to the person with no reason shown). To debug one autopilot decision, follow its interactionId: interaction.requested (heldBy), autopilot.claimed, autopilot.decision-sent, autopilot.acted or autopilot.handed-back, interaction.invoked, interaction.resolved (answeredBy), then the next turn of the working agent), interaction.invoked (a claimant ran one of the actions the widget itself exposes, through its hold, the same code the button runs — detail.claimant, detail.action (an option id, select or reply) and detail.finished, whether that settled the interaction, and when it did not, the run is recorded as an edit; the choice and narration it recorded reach the result of the tool that asked as decidedOnUsersBehalf; the person's own programmatic action, from a host with no DOM to click, carries detail.by: user in place of detail.claimant, and is not recorded as an edit nor as a decision on their behalf, so what it settles is answered by user), interaction.step (a long action run as named steps through runSteps, which survive a reload — detail.step and detail.outcome: started, done, skipped when the step was already done before a reload, or resumed when it started before a reload and runs again with what it saved part-way, such as a job id it re-attaches to), interaction.checkpoint (the checkpoints a conversation keeps for its long actions: the one in flight, and each one a reload cut, held apart until a request of its own widget type takes it over, so a resumed flow that opens other long widgets first, which save their own, loses nothing — detail.action: resumed when a reload cut the work and a request of the same widget type that the registration sameWork agrees is the same work took it over, refused when sameWork said a new request is different work (detail.saved is the identity it kept; detail.kept: true, since it stays for a later request of that type, and is offered to every one until one agrees) or when runSteps found the handed-over checkpoint malformed and started fresh (detail.reason, detail.saved), or cleared when its flow ended, once per checkpoint, with detail.cut: true for one a reload cut that nothing took over), context.updated/threshold-crossed (token + cost), headless.attached (a HeadlessSession attached, for a host that drives the assistant with no screen — detail.label, what the host called itself, when it gave one) and headless.raw-resolved (that host settled an interaction raw, bypassing the widget's own actions: detail.interactionId and detail.component; the result went to the tool as given, so check what the widget would have enforced), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.",
     'Sub-agent meta events: a sub-agent\'s own turn.retry/turn.error/tool.failed/tool.unresolved events are merged into this same timeline, tagged with `detail.subAgent` — a `"<parent> › <sub-agent>"` breadcrumb that composes when nested (e.g. `"UI Builder › Planner › Grounding"`) — and interleaved by their original timestamps within the subagent.started→completed/failed bracket. These are the per-attempt/per-failure signals that do NOT appear among the sub-agent\'s (hoisted) messages: a malformed/empty attempt that gets retried produces no message, and the stale-vs-hallucinated split and streak counts live only on the event. A sub-agent\'s high-volume, message-derivable events (turn.start/turn.end, provider.selected, context.updated) are intentionally NOT merged — read its hoisted messages for model/tokens/cost and turn-by-turn activity, and the bracketing subagent.* events for the run\'s span.',
     "`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, contextTokens/contextLimit/contextUsagePercent for the last call, and the session totals — sessionCostUsd, sessionTokensConsumed, and the four-bucket sessionUsage lifted to the top of this log), activeDebugSnapshot (the active agent's `getDebugSnapshot()` taken fresh at export — reflects state NOW, which may have advanced beyond the last turn's agentSnapshot), debug (optional host-supplied debug state), host, and the export timestamp.",
     'Note the two different scopes in `meta.context`: `contextTokens` is the prompt size of the LAST call (against `contextLimit`, the model context window), while `sessionUsage`/`sessionTokensConsumed` are cumulative BILLED throughput. Every turn resends the conversation, so the cumulative figure counts each turn’s prompt again in the next turn’s and is expected to dwarf the context size — that is not double-counting.',

package/dist/esm/state/decision-surface.js

@@ -42,14 +42,16 @@ const describeViews = (views) => Object.fromEntries(Object.entries(views).map(([
 const readView = (views, view) => Object.prototype.hasOwnProperty.call(views, view) ? views[view].read() : undefined;
 /**
  * Build the surface for a short-form decision (GENC-1660). Its actions are its options (by id),
- * plus `select` for a multi-select and `reply` for a written answer; all of them finish. Its views,
- * if it has any, are read by name. Every read — facts, views, actions, enabled-ness — is taken
+ * plus `select` for a multi-select and `reply` for a written answer; all of them finish. A spec's
+ * own `actions` follow them, run as a full-form surface's are (and editing unless they say
+ * otherwise); they do not count towards readiness. Its views, if it has any, are read by name. Every read — facts, views, actions, enabled-ness — is taken
  * fresh, so the surface always describes the widget as it is now.
  *
- * Throws if an option's id collides with another or with a platform-owned name, which is a bug in
- * the widget rather than something to recover from.
+ * Throws if an option's id collides with another or with a platform-owned name, or an extra action
+ * does, which is a bug in the widget rather than something to recover from.
  */
 export function buildDecisionSurface(spec) {
+    var _a;
     const options = spec.options.map(normalise);
     const ids = new Set();
     for (const { id } of options) {
@@ -60,8 +62,18 @@ export function buildDecisionSurface(spec) {
         }
         ids.add(id);
     }
+    const extra = (_a = spec.actions) !== null && _a !== void 0 ? _a : {};
+    assertActionShapes('exposeDecision', extra);
+    for (const name of Object.keys(extra)) {
+        if (ids.has(name) ||
+            (spec.multi && name === SELECT_ACTION) ||
+            (spec.freeText && name === REPLY_ACTION)) {
+            throw new Error(`exposeDecision: the action "${name}" is also an option or a reserved name.`);
+        }
+    }
     const byIdOrLabel = (key) => typeof key === 'string' ? options.find((o) => o.id === key || o.label === key) : undefined;
-    const actions = () => {
+    // What the options, `select` and `reply` make of the decision: its readiness is theirs alone.
+    const builtIn = () => {
         const enabled = options.filter(isEnabled);
         return [
             ...options.map((o) => {
@@ -81,6 +93,10 @@ export function buildDecisionSurface(spec) {
             ...(spec.freeText ? [replyAction()] : []),
         ];
     };
+    const actions = () => [
+        ...builtIn(),
+        ...Object.entries(extra).map(([name, a]) => describeSpecAction(name, a)),
+    ];
     const replyReason = () => unavailableReason(spec.freeTextUnavailable);
     const replyAction = () => {
         const unavailable = replyReason();
@@ -98,7 +114,7 @@ export function buildDecisionSurface(spec) {
             read: (view) => (view === undefined ? facts() : readView(views, view)),
         }
         : {};
-    return Object.assign(Object.assign({ prompt: spec.prompt, facts }, readable), { actions, isReady: () => actions().some((a) => a.finishes && a.enabled), prepare(name, args) {
+    return Object.assign(Object.assign({ prompt: spec.prompt, facts }, readable), { actions, isReady: () => builtIn().some((a) => a.finishes && a.enabled), prepare(name, args) {
             if (spec.multi && name === SELECT_ACTION) {
                 const picked = args === null || args === void 0 ? void 0 : args.options;
                 if (!Array.isArray(picked) || picked.length === 0) {
@@ -139,6 +155,9 @@ export function buildDecisionSurface(spec) {
             }
             const option = options.find((o) => o.id === name);
             if (!option) {
+                const own = ownAction(extra, name);
+                if (own)
+                    return prepareSpecAction(name, own, args);
                 return { error: 'unknown-action', message: `No action "${name}" here.` };
             }
             const why = reasonFor(option);
@@ -225,6 +244,52 @@ export function exampleArgs(schema) {
     const names = Object.keys(properties).sort((a, b) => Number(required.has(b)) - Number(required.has(a)));
     return Object.fromEntries(names.map((name) => { var _a; return [name, placeholder((_a = properties[name]) === null || _a === void 0 ? void 0 : _a.type)]; }));
 }
+/** An action as anyone may read it, from a full-form action's spec: one rule for both forms. */
+const describeSpecAction = (name, a) => {
+    const unavailable = unavailableReason(a.unavailable);
+    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ name, finishes: !!a.finishes, enabled: unavailable === undefined }, (unavailable !== undefined ? { unavailable } : {})), { description: a.description }), (a.text ? { args: 'text' } : {})), (a.argsSchema ? { args: 'fields', argsSchema: a.argsSchema } : {})), (a.refines ? { refines: true } : {}));
+};
+/** Check a full-form action's guard and arguments, and ready it to run: one rule for both forms. */
+const prepareSpecAction = (name, action, args) => {
+    const why = unavailableReason(action.unavailable);
+    if (why !== undefined) {
+        return { error: 'disabled', message: `"${name}" is not available right now: ${why}.` };
+    }
+    if (action.text) {
+        const text = args === null || args === void 0 ? void 0 : args.text;
+        if (typeof text !== 'string' || !text.trim()) {
+            return {
+                error: 'invalid-args',
+                message: `"${name}" takes its argument as \`text\`, not empty.`,
+            };
+        }
+        const trimmed = text.trim();
+        return {
+            choice: `${name}: ${trimmed}`.slice(0, CHOICE_CHARS),
+            finishes: !!action.finishes,
+            run: () => action.run(trimmed),
+        };
+    }
+    const problem = checkArgs(args !== null && args !== void 0 ? args : {}, action.argsSchema);
+    if (problem)
+        return { error: 'invalid-args', message: `"${name}": ${problem}` };
+    const shown = args && Object.keys(args).length ? ` ${JSON.stringify(args)}` : '';
+    return {
+        choice: `${name}${shown}`.slice(0, CHOICE_CHARS),
+        finishes: !!action.finishes,
+        run: () => action.run(args !== null && args !== void 0 ? args : {}),
+    };
+};
+/** The action of `actions` called `name`. Own actions only: `constructor` must not reach the prototype. */
+const ownAction = (actions, name) => Object.prototype.hasOwnProperty.call(actions, name) ? actions[name] : undefined;
+/** Refuse an action that takes `text` and `argsSchema` both: a bug in the widget. */
+const assertActionShapes = (who, actions) => {
+    for (const [name, action] of Object.entries(actions)) {
+        if (action.text && action.argsSchema) {
+            throw new Error(`${who}: action "${name}" takes \`text\` or \`argsSchema\`, not both.`);
+        }
+    }
+};
 /**
  * Build the surface for a full-form spec (GENC-1660 §4.2): named actions, some editing and some
  * finishing, each guarded and checked (a text action's text, a form's fields against its schema); a
@@ -234,59 +299,21 @@ export function exampleArgs(schema) {
  * views: a bug in the widget rather than something to recover from.
  */
 export function buildFullSurface(spec) {
-    for (const [name, action] of Object.entries(spec.actions)) {
-        if (action.text && action.argsSchema) {
-            throw new Error(`exposeSurface: action "${name}" takes \`text\` or \`argsSchema\`, not both.`);
-        }
-    }
+    assertActionShapes('exposeSurface', spec.actions);
     const views = spec.views && Object.keys(spec.views).length ? spec.views : undefined;
     if (spec.preview !== undefined &&
         !(views && Object.prototype.hasOwnProperty.call(views, spec.preview))) {
         throw new Error(`exposeSurface: the preview "${spec.preview}" is not one of its views.`);
     }
-    const actions = () => Object.entries(spec.actions).map(([name, a]) => {
-        const unavailable = unavailableReason(a.unavailable);
-        return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ name, finishes: !!a.finishes, enabled: unavailable === undefined }, (unavailable !== undefined ? { unavailable } : {})), { description: a.description }), (a.text ? { args: 'text' } : {})), (a.argsSchema ? { args: 'fields', argsSchema: a.argsSchema } : {})), (a.refines ? { refines: true } : {}));
-    });
+    const actions = () => Object.entries(spec.actions).map(([name, a]) => describeSpecAction(name, a));
     return Object.assign(Object.assign({ prompt: spec.prompt, facts: () => ({}), describe: () => spec.describe() }, (views
         ? Object.assign(Object.assign({ views: describeViews(views) }, (spec.preview !== undefined ? { preview: spec.preview } : {})), { read: (view) => {
                 const name = view !== null && view !== void 0 ? view : spec.preview;
                 return name === undefined ? undefined : readView(views, name);
             } }) : {})), { actions, isReady: () => actions().some((a) => a.enabled), prepare(name, args) {
-            // Own actions only: a name from the model such as `constructor` or `toString` must not reach
-            // the object's prototype.
-            const action = Object.prototype.hasOwnProperty.call(spec.actions, name)
-                ? spec.actions[name]
-                : undefined;
+            const action = ownAction(spec.actions, name);
             if (!action)
                 return { error: 'unknown-action', message: `No action "${name}" here.` };
-            const why = unavailableReason(action.unavailable);
-            if (why !== undefined) {
-                return { error: 'disabled', message: `"${name}" is not available right now: ${why}.` };
-            }
-            if (action.text) {
-                const text = args === null || args === void 0 ? void 0 : args.text;
-                if (typeof text !== 'string' || !text.trim()) {
-                    return {
-                        error: 'invalid-args',
-                        message: `"${name}" takes its argument as \`text\`, not empty.`,
-                    };
-                }
-                const trimmed = text.trim();
-                return {
-                    choice: `${name}: ${trimmed}`.slice(0, CHOICE_CHARS),
-                    finishes: !!action.finishes,
-                    run: () => action.run(trimmed),
-                };
-            }
-            const problem = checkArgs(args !== null && args !== void 0 ? args : {}, action.argsSchema);
-            if (problem)
-                return { error: 'invalid-args', message: `"${name}": ${problem}` };
-            const shown = args && Object.keys(args).length ? ` ${JSON.stringify(args)}` : '';
-            return {
-                choice: `${name}${shown}`.slice(0, CHOICE_CHARS),
-                finishes: !!action.finishes,
-                run: () => action.run(args !== null && args !== void 0 ? args : {}),
-            };
+            return prepareSpecAction(name, action, args);
         } });
 }

package/dist/esm/state/persistence/debug-log-assembly.js

@@ -0,0 +1,69 @@
+import { __awaiter } from "tslib";
+import { logger } from '../../utils/logger';
+import { DEBUG_LOG_README, getMetaEvents } from '../debug-event-log';
+import { buildTimelineEntries } from './build-timeline-entries';
+import { assembleDebugLog, withFreshMetaSnapshot, } from './diagnostics';
+/**
+ * The current page's diagnostic entries (GENC-1351 §5.8): the debug-log timeline entries
+ * (`message`/`turn`/`event`), the driver's external diagnostics, and one `meta-snapshot` carrying
+ * the export-time `meta` block. The assistant element reassembles these into the live log, and the
+ * persister's forward-capture path diffs them against what has already been appended to the stored
+ * stream. Extracted from the element so a host with no element (the headless session) derives its
+ * log from the same code, not a second copy that could drift.
+ *
+ * DOM-free and framework-free.
+ *
+ * @beta
+ */
+export function buildDiagnosticEntries(input) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    const { driver, stateKey } = input;
+    // The message/turn/event timeline entries — built by the shared, pure `buildTimelineEntries`
+    // (the same helper a headless consumer uses to harvest its own log), from the driver's pull
+    // surfaces. Prefer the driver's raw history (carries sub-agent traces) over the host's copy.
+    const timelineEntries = buildTimelineEntries({
+        turnSnapshots: (_b = (_a = driver === null || driver === void 0 ? void 0 : driver.getTurnSnapshots) === null || _a === void 0 ? void 0 : _a.call(driver)) !== null && _b !== void 0 ? _b : [],
+        messages: (_e = (_d = (_c = driver === null || driver === void 0 ? void 0 : driver.getRawHistory) === null || _c === void 0 ? void 0 : _c.call(driver)) !== null && _d !== void 0 ? _d : input.messages) !== null && _e !== void 0 ? _e : [],
+        metaEvents: stateKey ? getMetaEvents(stateKey) : [],
+    });
+    // Fold in any external diagnostics harvested from an out-of-band driver (e.g. a server-side
+    // ChatDriver whose collated log an interaction widget returned on its result). They ride the
+    // same download + persisted-diagnostics path; `assembleDebugLog` sorts the whole timeline by
+    // timestamp so they interleave chronologically. (GENC-1461 unified diagnostics.)
+    return [
+        ...timelineEntries,
+        ...((_g = (_f = driver === null || driver === void 0 ? void 0 : driver.getExternalDiagnostics) === null || _f === void 0 ? void 0 : _f.call(driver)) !== null && _g !== void 0 ? _g : []),
+        input.metaSnapshot(),
+    ];
+}
+/**
+ * The debug log for the WHOLE session (GENC-1351 §5.8 / §5.10), not just this page's activity:
+ * the persisted diagnostics stream with its stored `meta-snapshot`s replaced by a fresh one
+ * (`withFreshMetaSnapshot`), so its context and cost figures are current. When the provider
+ * stores no diagnostics, there is no key, the stream is empty or loading it fails, it is
+ * `fallback()` — the current-page log. Never throws.
+ *
+ * The one derivation of the lifetime log: the assistant element's `getLifetimeDebugLog` and the
+ * headless session both call it, because a second one drifts, and for this log that means silently
+ * understating spend.
+ *
+ * @beta
+ */
+export function lifetimeDebugLog(input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { provider, stateKey } = input;
+        if ((provider === null || provider === void 0 ? void 0 : provider.loadDiagnostics) && stateKey) {
+            try {
+                yield input.flush();
+                const stored = yield provider.loadDiagnostics(stateKey);
+                if (stored.length) {
+                    return assembleDebugLog(withFreshMetaSnapshot(stored, input.metaSnapshot()), DEBUG_LOG_README);
+                }
+            }
+            catch (e) {
+                logger.error('Diagnostics load failed — using current-page log:', e);
+            }
+        }
+        return input.fallback();
+    });
+}

package/dist/esm/state/persistence/index.js

@@ -1,3 +1,4 @@
 export { PERSISTED_SESSION_VERSION } from './session-snapshot';
 export { WebStorageSessionProvider } from './session-persistence-provider';
 export { assembleDebugLog, withFreshMetaSnapshot } from './diagnostics';
+export { buildDiagnosticEntries, lifetimeDebugLog } from './debug-log-assembly';

package/dist/esm/state/persistence/session-persister.js

@@ -213,6 +213,22 @@ export class SessionPersister {
             void this.persistSession();
         }, delay);
     }
+    /**
+     * Save the session now, and wait for the write: the pending debounced autosave, if there is one,
+     * is taken over by this call. For a host with no `pagehide` to save on, which wants the snapshot
+     * written before it reads it back or exits (the headless session's `flush`). Like the autosave it
+     * replaces, it never throws: a failed write is recorded and, repeated, reported.
+     */
+    saveNow() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { provider, enabled } = this.deps.getPersistence();
+            if (!enabled || !provider)
+                return;
+            this.cancelPendingSave();
+            this._lastSaveAt = Date.now();
+            yield this.persistSession();
+        });
+    }
     /**
      * Cancel a pending debounced autosave **without flushing it** (GENC-1351 §5.12).
      * Called before a session switch/re-key so the outgoing transcript can never be