@genesislcap/ai-assistant 15.26.0 → 15.27.0

package/dist/esm/components/chat-driver/interaction-controller.js

@@ -0,0 +1,235 @@
+import { recordMetaEvent } from '../../state/debug-event-log';
+import { createInteractionContext, } from '../../state/interaction-context';
+import { logger } from '../../utils/logger';
+/**
+ * Custom UI interactions: parking a tool handler on a widget, and settling it when the user (or a
+ * timeout) answers.
+ *
+ * Owns the pending call and its live context, which are created and destroyed together. Everything
+ * else it needs is the driver's history and event target, reached through `InteractionDeps`.
+ */
+export class InteractionController {
+    constructor(deps) {
+        this.deps = deps;
+        this.pending = new Map();
+        /**
+         * Live per-interaction contexts (GENC-1390), keyed by interactionId. Created in `request`
+         * alongside the pending entry, disposed + removed in `resolve`. Non-serialisable (sockets,
+         * timers, subscriber sets), so they live here — not on the DOM, not in the persisted store — and
+         * therefore survive the element remounts (layout reflow/drag, transcript re-render) that this
+         * feature exists to make harmless. At most one is live at a time (see the
+         * one-interaction-at-a-time guard in `request`).
+         */
+        this.contexts = new Map();
+    }
+    /** See `ChatDriver.setHostInteractionRequester`. */
+    setHostRequester(fn) {
+        this.hostRequester = fn;
+    }
+    /** See `ChatDriver.requestInteraction`. */
+    request(componentName, data, options) {
+        if (this.hostRequester) {
+            return this.hostRequester(componentName, data, options);
+        }
+        if (this.pending.size > 0) {
+            throw new Error('requestInteraction: another user interaction is already in flight. ' +
+                'Only one interaction may be active at a time — sequence them in a single tool handler ' +
+                'rather than spawning widgets from parallel sub-agents or parallel tool calls.');
+        }
+        const interactionId = crypto.randomUUID();
+        const chatInputDuringExecution = options === null || options === void 0 ? void 0 : options.chatInputDuringExecution;
+        const timeoutMs = options === null || options === void 0 ? void 0 : options.timeoutMs;
+        const presentation = options === null || options === void 0 ? void 0 : options.presentation;
+        return new Promise((resolve, reject) => {
+            this.pending.set(interactionId, {
+                resolve,
+                reject,
+                overrideId: chatInputDuringExecution ? interactionId : undefined,
+                // Resolve the interaction with a timeout result if the user does not
+                // respond in time. `resolve` runs the same teardown a normal resolution
+                // does (marks the widget read-only, reverts any input override) and
+                // clears any still-pending handle.
+                timeoutHandle: timeoutMs != null
+                    ? setTimeout(() => {
+                        this.resolve(interactionId, {
+                            status: 'timeout',
+                            message: `Interaction timed out after ${timeoutMs}ms.`,
+                        });
+                    }, timeoutMs)
+                    : undefined,
+            });
+            recordMetaEvent(this.deps.sessionKey, 'interaction.requested', {
+                interactionId,
+                component: componentName,
+                agent: this.deps.activeAgentName(),
+            });
+            // Signal the park boundary on the activity bus so turn-aware UI can tell
+            // "actively computing" from "parked awaiting the user" — the latter is a
+            // safe window for actions disallowed mid-request (e.g. switching provider
+            // during a long journey step). Paired with `interaction-resolved`.
+            this.deps.activityBus.publish('interaction-requested', undefined);
+            if (chatInputDuringExecution) {
+                this.deps.emit(new CustomEvent('interaction-start', {
+                    detail: { interactionId, chatInputDuringExecution },
+                }));
+            }
+            // Create the live context (GENC-1390) BEFORE the widget can mount, so the
+            // wrapper finds it when it builds the pending `interaction` descriptor.
+            this.contexts.set(interactionId, createInteractionContext(interactionId));
+            this.deps.appendToHistory({
+                role: 'assistant',
+                content: '',
+                interaction: Object.assign({ interactionId,
+                    componentName,
+                    data }, (presentation ? { presentation } : {})),
+            });
+        });
+    }
+    /**
+     * See `ChatDriver.resolveInteraction`. Warns and returns when the id is unknown — a widget can
+     * report twice, and the second report has nothing left to settle.
+     */
+    resolve(interactionId, result) {
+        var _a;
+        const interaction = this.pending.get(interactionId);
+        if (!interaction) {
+            logger.warn(`Interaction with ID ${interactionId} not found.`);
+            return;
+        }
+        // Clear the timeout so a user resolution doesn't later fire a stale
+        // timeout (and a timeout firing here clears its own already-fired handle).
+        if (interaction.timeoutHandle)
+            clearTimeout(interaction.timeoutHandle);
+        // Harvest any out-of-band diagnostic entries the widget collated (e.g. from a server-side
+        // ChatDriver) so the host's debug log + persisted diagnostics include them. Independent of the
+        // message patched below — they describe the widget's own work, not this message.
+        this.deps.foldDiagnostics(interactionId, result === null || result === void 0 ? void 0 : result.diagnostics);
+        // Fold any widget-reported external (non-LLM) cost onto the message, so
+        // the host's `sumCosts` recompute includes it in the session total.
+        // Accumulates defensively in case a widget reports more than once.
+        const costUsd = typeof (result === null || result === void 0 ? void 0 : result.costUsd) === 'number' && Number.isFinite(result.costUsd) && result.costUsd > 0
+            ? result.costUsd
+            : undefined;
+        const patched = this.deps.patchInteractionMessage(interactionId, (message) => {
+            var _a;
+            return (Object.assign(Object.assign(Object.assign({}, message), { interaction: Object.assign(Object.assign({}, message.interaction), { resolved: result }) }), (costUsd != null ? { externalCostUsd: ((_a = message.externalCostUsd) !== null && _a !== void 0 ? _a : 0) + costUsd } : {})));
+        });
+        if (patched)
+            this.deps.notifyHistoryUpdated();
+        // A widget may opt into echoing its outcome on the user's side of the
+        // chat by returning `userMessage`. Appended as a display-only
+        // `'synthetic-user'` message: it is tracked in history (and the debug log)
+        // and rendered like a user message, but transports never serialize it —
+        // the model already learns the outcome from this handler's return value.
+        // Appended before `interaction.resolve` so it precedes the tool result and
+        // any follow-up turn the resumed handler produces.
+        if (typeof (result === null || result === void 0 ? void 0 : result.userMessage) === 'string' && result.userMessage.trim()) {
+            this.deps.appendToHistory({ role: 'synthetic-user', content: result.userMessage });
+        }
+        if (interaction.overrideId) {
+            this.deps.emit(new CustomEvent('interaction-stop', { detail: { interactionId } }));
+        }
+        recordMetaEvent(this.deps.sessionKey, 'interaction.resolved', { interactionId });
+        // The park is ending and the loop is about to resume computing — paired
+        // with `interaction-requested`. Fires for every resolution path (user
+        // completion, timeout, cancellation), since all route through here.
+        this.deps.activityBus.publish('interaction-resolved', undefined);
+        interaction.resolve(result);
+        this.pending.delete(interactionId);
+        // Tear down the live context on RESOLVE (not on element unmount) — this closes
+        // any sockets/timers the widget parked on it via `onDispose`. (GENC-1390)
+        (_a = this.contexts.get(interactionId)) === null || _a === void 0 ? void 0 : _a.dispose();
+        this.contexts.delete(interactionId);
+    }
+    /**
+     * See `ChatDriver.recordExternalCost`.
+     *
+     * **Why this exists separately from `resolve`.** A widget's spend reaches the session total only
+     * through `InteractionResult.costUsd`, which is read exactly once — `resolve` does its whole job
+     * against a live pending entry and then deletes it. That is correct for the resolution itself,
+     * but it assumes a widget stops costing money when it resolves, and several deliberately do not:
+     * a widget that resolves EARLY so the assistant stops waiting (options shown, a preview
+     * rendered) may stay interactive for minutes afterwards and do more paid work on the user's
+     * behalf. Re-emitting `interaction-completed` does not help — with the interaction gone from the
+     * map the call is a silent no-op — so that spend had nowhere to go and was simply missing from
+     * the figure shown to the user.
+     *
+     * Touches only `externalCostUsd`: the recorded `interaction.resolved` payload is left exactly as
+     * the resolution wrote it, because this is not a second resolution and must not read like one.
+     */
+    recordExternalCost(interactionId, costUsd) {
+        const drop = (reason) => {
+            recordMetaEvent(this.deps.sessionKey, 'interaction.external-cost-dropped', {
+                interactionId,
+                costUsd,
+                reason,
+            });
+            return false;
+        };
+        if (!interactionId)
+            return drop('no interactionId');
+        if (typeof costUsd !== 'number' || !Number.isFinite(costUsd) || costUsd <= 0) {
+            return drop('not a positive finite amount');
+        }
+        const patched = this.deps.patchInteractionMessage(interactionId, (message) => {
+            var _a;
+            return (Object.assign(Object.assign({}, message), { externalCostUsd: ((_a = message.externalCostUsd) !== null && _a !== void 0 ? _a : 0) + costUsd }));
+        });
+        // The message is gone (trimmed or condensed): the spend is real and already billed, so it is
+        // recorded as dropped rather than silently discarded — an invisible gap in the session total
+        // is exactly what this whole channel exists to close.
+        if (!patched)
+            return drop('interaction message no longer in history');
+        recordMetaEvent(this.deps.sessionKey, 'interaction.external-cost', { interactionId, costUsd });
+        // A NARROW event, deliberately not `history-updated`.
+        //
+        // The host answers `history-updated` by reassigning `messages`, which re-evaluates
+        // `activeInteractionRow` — and the trailing interaction slot renders through a
+        // `repeat(..., { recycle: false })`, so every view in it is disposed and rebuilt regardless of
+        // item identity. That is correct for a PENDING interaction (GENC-1429: a recycled wrapper
+        // carries the previous interaction's truthy `resolved` and swallows the next completion), and
+        // survivable because `buildInteraction` hands a remounted pending widget the same driver-owned
+        // `interactionContext`.
+        //
+        // A RESOLVED one has no such context — `resolve` disposed and deleted it — so announcing this
+        // on `history-updated` would tear down and blank the very widget that just reported, in
+        // exactly the flow this channel exists for (a user tweaking an option after the interaction
+        // resolved). Bookkeeping about a finished turn must stay invisible, so the host recomputes its
+        // totals from this driver's history and saves, without touching what is rendered. Reviewer
+        // catch on #2474 — confirmed against the layout widget, whose tweak result went off screen
+        // because the rebuild raced the session write that would have restored it.
+        this.deps.emit(new CustomEvent('external-cost-recorded', {
+            detail: { interactionId, costUsd },
+        }));
+        return true;
+    }
+    /** See `ChatDriver.getInteractionContext`. */
+    context(interactionId) {
+        var _a;
+        return (_a = this.contexts.get(interactionId)) === null || _a === void 0 ? void 0 : _a.context;
+    }
+    /**
+     * Resolve every in-flight interaction with a `'timeout'` result, closing its
+     * widget read-only. Used when a sub-agent that owns the open widget times out:
+     * the widget is parked in *this* driver's map (interactions resolve on the
+     * host, not the child), so cancelling it here unblocks the sub-agent handler
+     * awaiting it. The "one interaction at a time" invariant means there is at
+     * most one.
+     */
+    cancelAll(message) {
+        // Snapshot the keys: `resolve` deletes from the map it would otherwise be iterating live.
+        for (const interactionId of [...this.pending.keys()]) {
+            this.resolve(interactionId, { status: 'timeout', message });
+        }
+    }
+    /**
+     * Drop any live interaction contexts on driver teardown. Normally empty (a context is created
+     * and destroyed with its pending interaction, and dispose is not reached mid-interaction);
+     * disposed defensively so a stray context can never leak an open socket/timer.
+     */
+    disposeContexts() {
+        for (const handle of this.contexts.values())
+            handle.dispose();
+        this.contexts.clear();
+    }
+}

package/dist/esm/components/chat-driver/turn-recorder.js

@@ -0,0 +1,206 @@
+import { __rest } from "tslib";
+import { mergeMetaEvents, recordMetaEvent } from '../../state/debug-event-log';
+/**
+ * Everything the exported debug log draws from one driver: its own per-LLM-call snapshots, the
+ * ones forwarded up from sub-agents, and the diagnostics harvested from resolved interactions.
+ *
+ * All three feed the same timeline and all three are keyed in this driver's turn space, which is
+ * why they share an owner — a forwarded child turn and a harvested server turn are both re-labelled
+ * against the counter kept here.
+ */
+export class TurnRecorder {
+    constructor(sessionKey, maxSnapshots) {
+        this.sessionKey = sessionKey;
+        this.maxSnapshots = maxSnapshots;
+        /**
+         * Ring buffer of per-LLM-call snapshots, capped at `maxSnapshots`; older entries drop off as
+         * new ones arrive.
+         */
+        this.buffer = [];
+        /** Monotonic counter that survives agent swaps — useful for cross-referencing with history. */
+        this.turnIndex = 0;
+        /**
+         * `turn` + `message` diagnostic entries harvested from an out-of-band source. `event` entries
+         * are NOT kept here — they are folded into the session's meta-event registry so they inherit
+         * fresh host indices, and reach the log through `getMetaEvents`. Append-only, and never cleared:
+         * it lives with the recorder, so a new chat (fresh driver) starts empty while a compaction (same
+         * instance) keeps it. (GENC-1461.)
+         */
+        this.externalEntries = [];
+        /**
+         * Monotonic count of external-diagnostics batches folded this driver-lifetime. Namespaces each
+         * batch's re-keyed `turn` entries so distinct server generations in one chat session can't
+         * collide on `turnIndex` in the forward-capture persister (which dedups turns by that key).
+         */
+        this.externalBatches = 0;
+    }
+    /** Point at the incoming agent's `getDebugSnapshot`, or clear it when the agent supplies none. */
+    setSnapshotter(snapshotter) {
+        this.snapshotter = snapshotter;
+    }
+    /**
+     * The per-turn snapshots captured so far — what the LLM saw on each turn: system prompt, tool
+     * surface, and agent-supplied state (e.g. a machine snapshot).
+     */
+    snapshots() {
+        return this.buffer;
+    }
+    /**
+     * The harvested `turn` + `message` diagnostic entries. Opaque, and chronologically sorted by the
+     * host at assemble time.
+     */
+    externalDiagnostics() {
+        return this.externalEntries;
+    }
+    /**
+     * Push one snapshot to the ring buffer. Called inside `runToolLoop` just
+     * before each LLM call — that's the latest point where the prompt, tool
+     * surface, and agent state line up with what the model is about to see.
+     *
+     * Returns the pushed object so the caller can back-fill what only the response
+     * knows (`usage`). Mutating it after the fact is safe whether or not the ring
+     * buffer has since evicted it — an evicted snapshot is simply no longer exported.
+     */
+    record(turn) {
+        let agentSnapshot;
+        if (this.snapshotter) {
+            try {
+                agentSnapshot = this.snapshotter();
+            }
+            catch (e) {
+                // A snapshotter throwing must not derail the LLM call — capture the
+                // error string in place of the snapshot so the export still shows
+                // *something* happened.
+                agentSnapshot = `<getDebugSnapshot threw: ${e instanceof Error ? e.message : String(e)}>`;
+            }
+        }
+        const turnIndex = String(this.turnIndex);
+        this.turnIndex += 1;
+        const snapshot = Object.assign(Object.assign({}, turn), { turnIndex, timestamp: new Date().toISOString(), agentSnapshot });
+        this.buffer.push(snapshot);
+        this.trim();
+        return snapshot;
+    }
+    /**
+     * Merge a sub-agent's turn snapshots into this driver's buffer so they surface
+     * as `kind:'turn'` entries in the exported debug log. The child runs as a
+     * separate, discarded driver, so its snapshots would otherwise be lost. Each is
+     * re-labelled under the parent turn that activated the sub-agent: the child's
+     * own (numeric) turns become `"<parentTurn>-1"`, `"-2"`, … (1-based, in order);
+     * any already-forwarded grand-child labels (strings) have their leading segment
+     * remapped the same way, so nesting composes (`"5-2"` → `"5-2-1"`).
+     *
+     * Note: two sub-agents invoked in the *same* parent turn share the prefix, so
+     * their labels can repeat — `agentName` on each snapshot disambiguates them.
+     */
+    forwardSubAgent(childSnapshots) {
+        var _a;
+        if (childSnapshots.length === 0)
+            return;
+        // The activating parent turn = the most recent snapshot this driver recorded
+        // before entering the tool handler that invoked the sub-agent.
+        const parentTurn = Math.max(0, this.turnIndex - 1);
+        const ownTurnLabel = new Map();
+        let ownPos = 0;
+        for (const snap of childSnapshots) {
+            let turnIndex;
+            if (!snap.turnIndex.includes('-')) {
+                // The child's own turn (a bare counter) → number it under the parent turn.
+                ownPos += 1;
+                turnIndex = `${parentTurn}-${ownPos}`;
+                ownTurnLabel.set(snap.turnIndex, turnIndex);
+            }
+            else {
+                // An already-forwarded grand-child label — remap its leading segment.
+                const [lead, ...rest] = snap.turnIndex.split('-');
+                const leadLabel = (_a = ownTurnLabel.get(lead)) !== null && _a !== void 0 ? _a : `${parentTurn}-${lead}`;
+                turnIndex = [leadLabel, ...rest].join('-');
+            }
+            this.buffer.push(Object.assign(Object.assign({}, snap), { turnIndex }));
+        }
+        this.trim();
+    }
+    /**
+     * Fold a widget's out-of-band diagnostics into this session — typically a server-side
+     * ChatDriver's collated log, arriving on `InteractionResult.diagnostics` — so the host's debug
+     * log and persisted diagnostics stream include them. Independent of the interaction's own
+     * message: these describe the widget's work, not that message. A non-array or empty harvest is
+     * a no-op.
+     */
+    foldDiagnostics(interactionId, harvested) {
+        // The harvested entries carry the SOURCE engine's own index space (0-based turns/events), which
+        // would collide with this host's cursors in the forward-capture persister — turns dedup by
+        // `turnIndex`, events by an `index` high-water mark — so foreign entries get silently dropped
+        // from the persisted stream. Route each kind through the host's own collision-safe machinery,
+        // mirroring how a sub-agent's log is folded in (see `invokeSubAgent`):
+        //   • `event`   → `mergeMetaEvents`, which re-indexes them onto this session's monotonic event
+        //                 counter (clearing the high-water) while preserving their timestamps; they then
+        //                 reach the log via `getMetaEvents` in `buildTimelineEntries`, not this buffer.
+        //   • `turn`    → re-key `turnIndex` to the turn's local position within a per-batch namespace,
+        //                 so turns stay unique even when one interaction folds in several independent
+        //                 server runs that each number their own turns from 0 (a consolidator carries a
+        //                 consolidator-code run AND a table-code run), and never collide with the host's
+        //                 own bare-integer turn keys.
+        //   • `message` → kept as-is; the persister already keys messages by content, so they survive.
+        // TODO(GENC-1461, option 2 / streaming): expose an imperative `appendDiagnostics(entries)` on
+        // the handler context (see buildHandlerContext) that runs this same decomposition as SSE ticks
+        // arrive, so a streaming widget can surface its external engine's log live rather than only at
+        // resolve time. Batch-at-resolve (here) is the current, non-streaming path.
+        if (!Array.isArray(harvested) || !harvested.length)
+            return;
+        const batch = (this.externalBatches += 1);
+        const externalEvents = [];
+        let turnCount = 0;
+        let messageCount = 0;
+        for (const raw of harvested) {
+            // The harvest is external and typed `unknown[]`, so an element could be a primitive, null,
+            // or an object without a string `kind`. Guard before reading `.kind` so a malformed entry
+            // can't throw here (and gets skipped rather than derailing the whole fold).
+            if (!raw || typeof raw !== 'object' || typeof raw.kind !== 'string') {
+                continue;
+            }
+            const entry = raw;
+            if (entry.kind === 'event') {
+                const { kind: _kind } = entry, event = __rest(entry, ["kind"]);
+                externalEvents.push(event);
+            }
+            else if (entry.kind === 'turn') {
+                // Local position within THIS harvest, not the source engine's own `turnIndex`: one
+                // interaction can carry several independent server runs (a consolidator folds in its
+                // consolidator-code run and its table-code run), each numbering its turns from 0, so
+                // keying by the source index would collide them. The local position keeps every turn key
+                // distinct within the batch, so the persister's per-`turnIndex` dedup keeps them all.
+                this.externalEntries.push(Object.assign(Object.assign({}, entry), { turnIndex: `server-generation.${batch}:${turnCount}` }));
+                turnCount += 1;
+            }
+            else if (entry.kind === 'message') {
+                messageCount += 1;
+                this.externalEntries.push(entry);
+            }
+            // Any other kind is intentionally dropped, not folded. A sibling's `buildTimelineEntries`
+            // only ever emits message/turn/event; `meta-snapshot` is host/DOM-owned (latest-wins on
+            // reassembly, plus its own persister dedup), so folding a foreign one would pollute this
+            // host's timeline and meta cursor. Restricting to the three real kinds also keeps the
+            // manifest counts accurate (nothing miscounted as a `message`).
+        }
+        if (externalEvents.length)
+            mergeMetaEvents(this.sessionKey, externalEvents);
+        // Manifest: one provenance marker for the fold itself — records that an out-of-band engine's
+        // log crossed into this session and how much of each kind, so a regression that silently
+        // drops a generation's diagnostics (e.g. a new path that forgets to thread them across the
+        // boundary) surfaces as a zero/absent manifest rather than only by diffing a download. Also
+        // the natural seed for the streaming PR's open/close bracket. Stamped at resolve, so it
+        // closes the block on the sorted timeline. (GENC-1461.)
+        recordMetaEvent(this.sessionKey, 'external-diagnostics.folded', {
+            interactionId,
+            batch,
+            counts: { turn: turnCount, event: externalEvents.length, message: messageCount },
+        });
+    }
+    /** Hold the ring buffer at its cap, dropping oldest-first. */
+    trim() {
+        while (this.buffer.length > this.maxSnapshots) {
+            this.buffer.shift();
+        }
+    }
+}

package/dist/esm/components/settings-modal/settings-modal.template.js

@@ -31,6 +31,54 @@ const toggleAnimationEnabled = (host, value, enabled) => {
     host.setEnabledAnimations(next);
 };
 const readSwitchChecked = (event) => event.target.checked;
+/**
+ * The timestamp modes, in the order they read as an increasing amount of chrome.
+ *
+ * Keyed by {@link TimestampDisplay} rather than listed as an array of `{ value, label }`,
+ * so adding a mode to the union is a compile error here instead of a picker that silently
+ * cannot reach it.
+ */
+const TIMESTAMP_MODE_LABELS = {
+    off: 'Off',
+    hover: 'On hover',
+    always: 'Always',
+};
+const TIMESTAMP_MODE_OPTIONS = Object.keys(TIMESTAMP_MODE_LABELS).map((value) => ({ value, label: TIMESTAMP_MODE_LABELS[value] }));
+/**
+ * Three-way picker for {@link TimestampDisplay} (GENC-1257).
+ *
+ * The design system's segmented control rather than the `switch` every other row uses,
+ * because the setting genuinely has three states — and rather than hand-rolled buttons
+ * carrying `role="radio"`, because ARIA roles supply semantics but never behaviour:
+ * promising a radio group means owning roving `tabindex` and arrow-key navigation.
+ *
+ * `SegmentedControl extends FASTRadioGroup` (and `SegmentedItem extends FASTRadio`), so
+ * this IS the DS radio group — it inherits the whole keyboard pattern — just skinned as
+ * segments rather than dots, which is the right affordance for three short mode labels.
+ *
+ * The usual reason to avoid a DS control here does not apply. `RadioGroup.valueChanged`
+ * emits `change` whenever `value` is written — including the write this template's own
+ * binding performs on render, exactly the phantom-change footgun the DS switch has
+ * (GENC-1351 #1). It is harmless because the `timestampDisplay` setter guards on
+ * `preferenceUnchanged`, as every preference setter does, so a render-time echo returns early
+ * and never reaches the store or marks preferences user-changed.
+ */
+export const timestampModePickerTemplate = (segmentedControlTag, segmentedItemTag) => html `
+  <${segmentedControlTag}
+    part="toggle-timestamps"
+    aria-label="Show timestamps"
+    :value=${(x) => x.timestampDisplay}
+    @change=${(x, c) => {
+    x.timestampDisplay = c.event.target.value;
+}}
+  >
+    ${repeat(() => TIMESTAMP_MODE_OPTIONS, html `
+        <${segmentedItemTag} part="timestamp-mode-option" value="${(option) => option.value}"
+          >${(option) => option.label}</${segmentedItemTag}
+        >
+      `)}
+  </${segmentedControlTag}>
+`;
 /** Inline animation picker — categories and options always visible (no multiselect popup). */
 const animationsPickerTemplate = (switchTag) => html `
   <div class="settings-animation-list" part="toggle-animations">
@@ -198,7 +246,7 @@ export const settingsUsageMetersTemplate = (progressTag, buttonTag, iconTag) =>
       </div>
     `)}
 `;
-const chatBotSettingsTemplate = (switchTag, buttonTag) => html `
+const chatBotSettingsTemplate = (switchTag, buttonTag, segmentedControlTag, segmentedItemTag) => html `
   ${when((x) => { var _a; return ((_a = x.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.showToolCalls) != null; }, chatBotToggleRow('Show tool calls', "Display each tool the chatbot invokes — file reads, searches, edits and commands — inline as it works, so you can follow exactly what it's doing behind the scenes.", switchTag, 'toggle-tool-calls', (x) => x.showToolCalls, (x, c) => {
     x.showToolCalls = readSwitchChecked(c.event);
 }))}
@@ -211,6 +259,7 @@ const chatBotSettingsTemplate = (switchTag, buttonTag) => html `
   ${when((x) => { var _a; return ((_a = x.chatConfig.ui) === null || _a === void 0 ? void 0 : _a.showAgentSwitchIndicator) != null; }, chatBotToggleRow('Show delegation', 'Show in the chat window when tasks are delegated to different agents.', switchTag, 'toggle-agent-switch', (x) => x.showAgentSwitchIndicator, (x, c) => {
     x.showAgentSwitchIndicator = readSwitchChecked(c.event);
 }))}
+  ${settingsToggleRow('Show timestamps', 'Show when each message was sent, next to the sender name. Screen readers announce the full date in either visible mode.', 'toggle-timestamps', timestampModePickerTemplate(segmentedControlTag, segmentedItemTag))}
   ${when((x) => x.persistenceToggleable, chatBotToggleRow('Remember chat', 'Save this conversation so it can be restored after a page refresh. Turning this off deletes the saved copy.', switchTag, 'toggle-remember-chat', (x) => x.persistenceActive, (x, c) => {
     x.setPersistenceEnabled(readSwitchChecked(c.event));
 }))}
@@ -526,6 +575,8 @@ export const SettingsModalTemplate = (designSystemPrefix) => {
     const tabsTag = `${designSystemPrefix}-tabs`;
     const tabTag = `${designSystemPrefix}-tab`;
     const tabPanelTag = `${designSystemPrefix}-tab-panel`;
+    const segmentedControlTag = `${designSystemPrefix}-segmented-control`;
+    const segmentedItemTag = `${designSystemPrefix}-segmented-item`;
     const settingsTabPanel = html `
     <${tabPanelTag}
       slot="tabpanel"
@@ -595,7 +646,7 @@ export const SettingsModalTemplate = (designSystemPrefix) => {
         </h3>
         <p class="settings-modal-section-note">These options only control what you see in the chat window and do not control model behaviour.</p>
         <div class="settings-modal-section-body">
-          ${chatBotSettingsTemplate(switchTag, buttonTag)}
+          ${chatBotSettingsTemplate(switchTag, buttonTag, segmentedControlTag, segmentedItemTag)}
         </div>
       </section>
       </div>