@genesislcap/ai-assistant 14.451.1 → 14.451.2-FUI-2550.1

package/dist/ai-assistant.api.json

@@ -9623,7 +9623,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/ai-assistant!TurnSnapshot:interface",
-          "docComment": "/**\n * One captured frame of what the LLM saw on a single tool-loop iteration. The driver records these as a ring buffer (cap: configurable via `chatConfig.agent.maxTurnSnapshots`, default 40) so the export log can show, per turn: which agent was active, the resolved system prompt, the tool names visible to the LLM, and any agent-supplied debug snapshot (e.g. machine state for stateful agents).\n *\n * @beta\n */\n",
+          "docComment": "/**\n * One captured frame of what the LLM saw on a single tool-loop iteration. The driver records these as a ring buffer (cap: configurable via `chatConfig.agent.maxTurnSnapshots`, default 400) so the export log can show, per turn: which agent was active, the resolved system prompt, the tool names visible to the LLM, and any agent-supplied debug snapshot (e.g. machine state for stateful agents).\n *\n * @beta\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",

package/dist/ai-assistant.d.ts

@@ -625,6 +625,12 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     private consecutiveFoldOps;
     /** Consecutive unknown-tool calls without a real tool call. Reset on real tool execution. */
     private consecutiveUnknownToolCalls;
+    /**
+     * Distinct unknown-tool names seen in the current consecutive streak — stamped
+     * onto the `unknown-tool-limit` turn.error so a triager knows which tools were
+     * hallucinated. Reset alongside `consecutiveUnknownToolCalls`.
+     */
+    private readonly recentUnknownToolNames;
     private readonly maxFoldOperations;
     /** Sub-agents declared on the active agent config, keyed by name. */
     private subAgentsMap;
@@ -1562,8 +1568,10 @@ declare type MetaEventImportance = 'high' | 'normal' | 'low';
  *   there's no reason to pay immutable-reducer cost or flood the Redux DevTools
  *   action log with debug noise.
  *
- * Surfaced under `getDebugLog().meta.events`. Ring-buffered so a long-lived
- * session can't grow the timeline unbounded.
+ * Surfaced in `getDebugLog().timeline`, merged chronologically with messages and
+ * turn snapshots. Ring-buffered — the oldest non-`high` events are evicted first
+ * while `high`-importance failure events are retained — so a long-lived session
+ * stays bounded in normal use without ever dropping a failure signal.
  *
  * @internal
  */
@@ -1571,7 +1579,7 @@ declare type MetaEventImportance = 'high' | 'normal' | 'low';
  * Catalogue of meta event names. This is the documented surface — extend it as
  * new events are wired in (Tier 2/3 lifecycle, interaction, provider events).
  */
-declare type MetaEventType = 'assistant.connected' | 'assistant.disconnected' | 'assistant.popout' | 'assistant.popin' | 'driver.created' | 'driver.wired' | 'driver.unwired' | 'state.changed' | 'turn.start' | 'turn.end' | 'turn.error' | 'tool.failed' | 'agent.handoff' | 'agent.pinned' | 'agent.unpinned' | 'provider.selected' | 'interaction.requested' | 'interaction.resolved' | 'context.updated' | 'context.threshold-crossed' | 'panel.toggled' | 'attachment.added' | 'file.read-failed' | 'suggestions.failed';
+declare type MetaEventType = 'assistant.connected' | 'assistant.disconnected' | 'assistant.popout' | 'assistant.popin' | 'driver.created' | 'driver.wired' | 'driver.unwired' | 'state.changed' | 'turn.start' | 'turn.end' | 'turn.retry' | 'turn.error' | 'tool.failed' | 'agent.handoff' | 'agent.pinned' | 'agent.unpinned' | 'provider.selected' | 'interaction.requested' | 'interaction.resolved' | 'context.updated' | 'context.threshold-crossed' | 'panel.toggled' | 'attachment.added' | 'file.read-failed' | 'suggestions.failed';
 
 /**
  * Orchestrates multiple specialist agents. Sits between `FoundationAiAssistant`
@@ -2009,7 +2017,7 @@ export declare interface ToolTreeNode extends ChatToolDefinition {
 /**
  * One captured frame of what the LLM saw on a single tool-loop iteration.
  * The driver records these as a ring buffer (cap: configurable via
- * `chatConfig.agent.maxTurnSnapshots`, default 40) so the export log can show,
+ * `chatConfig.agent.maxTurnSnapshots`, default 400) so the export log can show,
  * per turn: which agent was active, the resolved system prompt, the tool names
  * visible to the LLM, and any agent-supplied debug snapshot (e.g. machine
  * state for stateful agents).

package/dist/dts/components/chat-driver/chat-driver.d.ts

@@ -12,7 +12,7 @@ export type ChatHistoryUpdatedEvent = CustomEvent<ReadonlyArray<ChatMessage>>;
 /**
  * One captured frame of what the LLM saw on a single tool-loop iteration.
  * The driver records these as a ring buffer (cap: configurable via
- * `chatConfig.agent.maxTurnSnapshots`, default 40) so the export log can show,
+ * `chatConfig.agent.maxTurnSnapshots`, default 400) so the export log can show,
  * per turn: which agent was active, the resolved system prompt, the tool names
  * visible to the LLM, and any agent-supplied debug snapshot (e.g. machine
  * state for stateful agents).
@@ -116,6 +116,12 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     private consecutiveFoldOps;
     /** Consecutive unknown-tool calls without a real tool call. Reset on real tool execution. */
     private consecutiveUnknownToolCalls;
+    /**
+     * Distinct unknown-tool names seen in the current consecutive streak — stamped
+     * onto the `unknown-tool-limit` turn.error so a triager knows which tools were
+     * hallucinated. Reset alongside `consecutiveUnknownToolCalls`.
+     */
+    private readonly recentUnknownToolNames;
     private readonly maxFoldOperations;
     /** Sub-agents declared on the active agent config, keyed by name. */
     private subAgentsMap;

package/dist/dts/components/chat-driver/chat-driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat-driver.d.ts","sourceRoot":"","sources":["../../../../src/components/chat-driver/chat-driver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,WAAW,EAKX,yBAAyB,EAE1B,MAAM,4BAA4B,CAAC;AAGpC,OAAO,KAAK,EACV,WAAW,EAGX,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,qBAAqB,CAAC;AAM7B,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAUxE,wFAAwF;AACxF,eAAO,MAAM,yBAAyB,yBAAyB,CAAC;AAMhE;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,WAAW,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC,CAAC;AAE9E;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qGAAqG;IACrG,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gGAAgG;IAChG,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAQD;;;;;;;;;GASG;AACH,qBAAa,UAAW,SAAQ,WAAY,YAAW,QAAQ;IAmI3D,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAKjC,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAGlC,oFAAoF;IACpF,OAAO,CAAC,QAAQ,CAAC,UAAU;IA3I7B,OAAO,CAAC,OAAO,CAAqB;IACpC,OAAO,CAAC,IAAI,CAAS;IACrB,kFAAkF;IAClF,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,mBAAmB,CAQvB;IAEJ,OAAO,CAAC,YAAY,CAAC,CAAoB;IACzC;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAuB;IAC9C;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB,CAAC,CAE2B;IAC1D;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY,CAAmB;IACvC;;;;OAIG;IACH,OAAO,CAAC,mBAAmB,CAAC,CAEsB;IAClD,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,eAAe,CAAC,CAAS;IACjC;;;;OAIG;IACH,OAAO,CAAC,gBAAgB,CAAC,CAAS;IAClC,OAAO,CAAC,WAAW,CAAC,CAAoB;IACxC;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB,CAAC,CAIjB;IAChB;;;OAGG;IACH,OAAO,CAAC,wBAAwB,CAAC,CAA4C;IAE7E,8EAA8E;IAC9E,OAAO,CAAC,SAAS,CAAwB;IACzC,8FAA8F;IAC9F,OAAO,CAAC,kBAAkB,CAAK;IAC/B,6FAA6F;IAC7F,OAAO,CAAC,2BAA2B,CAAK;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAE3C,qEAAqE;IACrE,OAAO,CAAC,YAAY,CAAuC;IAC3D;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB,CAAkC;IAC5D;;;;;;;;OAQG;IACH,OAAO,CAAC,qBAAqB,CAAS;IACtC;;;;OAIG;IACH,OAAO,CAAC,aAAa,CAAsB;IAC3C,+FAA+F;IAC/F,OAAO,CAAC,eAAe,CAAK;IAC5B,4EAA4E;IAC5E,OAAO,CAAC,gBAAgB,CAAC,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C;;;OAGG;IACH,OAAO,CAAC,mBAAmB,CAAC,CAAgB;IAC5C;;;;OAIG;IACH,OAAO,CAAC,qBAAqB,CAAiC;IAC9D,iFAAiF;IACjF,OAAO,CAAC,wBAAwB,CAAC,CAAS;IAC1C,wFAAwF;IACxF,OAAO,CAAC,0BAA0B,CAAC,CAAS;gBAGzB,gBAAgB,EAAE,kBAAkB,EACrD,YAAY,GAAE,iBAAsB,EACpC,eAAe,GAAE,oBAAyB,EAC1C,YAAY,CAAC,EAAE,iBAAiB,EAChC,aAAa,CAAC,EAAE,WAAW,EAAE,EACZ,iBAAiB,GAAE,MAAoC,EACxE,iBAAiB,GAAE,MAAoC,EACvD,gBAAgB,GAAE,MAAmC;IACrD,oFAAoF;IACnE,UAAU,GAAE,MAAW;IAuB1C;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IA4CrC;;;OAGG;IACH,qBAAqB,IAAI,MAAM;IAI/B;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IAQ7B;;;;;OAKG;YACW,sBAAsB;IA4BpC;;;OAGG;IACH,qBAAqB,IAAI;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS;IAIxD;;;OAGG;IACH,wBAAwB,IAAI,OAAO;IAInC;;;;;;OAMG;IACH,gBAAgB,IAAI,aAAa,CAAC,YAAY,CAAC;IAI/C;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IA4B1B;;;OAGG;IACH,2BAA2B,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,GAAG,IAAI;IAIxF,UAAU,IAAI,aAAa,CAAC,WAAW,CAAC;IAIxC,aAAa,IAAI,SAAS,WAAW,EAAE;IAIvC,0DAA0D;IAC1D,kBAAkB,IAAI,MAAM,EAAE;IAIxB,cAAc,CAClB,OAAO,EAAE,WAAW,EAAE,EACtB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,eAAe,EAAE,GAC/B,OAAO,CAAC,MAAM,EAAE,CAAC;IAiHpB,MAAM,IAAI,OAAO;IAIjB;;;;;OAKG;IACI,2BAA2B,CAChC,EAAE,EAAE,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,yBAAyB,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3F,IAAI;IAIP;;;;;;;;;;;;;;;;OAgBG;IACU,kBAAkB,CAAC,CAAC,EAC/B,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,GAAG,EACT,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAAC,CAAC,CAAC;IAuCb;;;OAGG;IACI,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI;IA0BnE;;;OAGG;IACI,WAAW,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI;IAS3C,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqC/F;;;;;;;;OAQG;IACH,OAAO,CAAC,mBAAmB;IAsC3B;;;;;OAKG;YACW,cAAc;IA8F5B;;;OAGG;IACG,mBAAmB,CAAC,eAAe,CAAC,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAsCrF,wFAAwF;IACxF,OAAO,CAAC,OAAO;IAKf;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAc1B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA+BxB,uFAAuF;IACvF,OAAO,CAAC,QAAQ;IAqChB,OAAO,CAAC,aAAa;IAQrB,8EAA8E;IAC9E,OAAO,CAAC,SAAS;IAWjB,mFAAmF;IACnF,OAAO,CAAC,2BAA2B;YAkCrB,WAAW;IAyZzB,OAAO,CAAC,eAAe;CAoBxB"}
+{"version":3,"file":"chat-driver.d.ts","sourceRoot":"","sources":["../../../../src/components/chat-driver/chat-driver.ts"],"names":[],"mappings":"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"}

package/dist/dts/state/debug-event-log.d.ts

@@ -16,8 +16,10 @@
  *   there's no reason to pay immutable-reducer cost or flood the Redux DevTools
  *   action log with debug noise.
  *
- * Surfaced under `getDebugLog().meta.events`. Ring-buffered so a long-lived
- * session can't grow the timeline unbounded.
+ * Surfaced in `getDebugLog().timeline`, merged chronologically with messages and
+ * turn snapshots. Ring-buffered — the oldest non-`high` events are evicted first
+ * while `high`-importance failure events are retained — so a long-lived session
+ * stays bounded in normal use without ever dropping a failure signal.
  *
  * @internal
  */
@@ -25,7 +27,7 @@
  * Catalogue of meta event names. This is the documented surface — extend it as
  * new events are wired in (Tier 2/3 lifecycle, interaction, provider events).
  */
-export type MetaEventType = 'assistant.connected' | 'assistant.disconnected' | 'assistant.popout' | 'assistant.popin' | 'driver.created' | 'driver.wired' | 'driver.unwired' | 'state.changed' | 'turn.start' | 'turn.end' | 'turn.error' | 'tool.failed' | 'agent.handoff' | 'agent.pinned' | 'agent.unpinned' | 'provider.selected' | 'interaction.requested' | 'interaction.resolved' | 'context.updated' | 'context.threshold-crossed' | 'panel.toggled' | 'attachment.added' | 'file.read-failed' | 'suggestions.failed';
+export type MetaEventType = 'assistant.connected' | 'assistant.disconnected' | 'assistant.popout' | 'assistant.popin' | 'driver.created' | 'driver.wired' | 'driver.unwired' | 'state.changed' | 'turn.start' | 'turn.end' | 'turn.retry' | 'turn.error' | 'tool.failed' | 'agent.handoff' | 'agent.pinned' | 'agent.unpinned' | 'provider.selected' | 'interaction.requested' | 'interaction.resolved' | 'context.updated' | 'context.threshold-crossed' | 'panel.toggled' | 'attachment.added' | 'file.read-failed' | 'suggestions.failed';
 /**
  * How much a reader should care about an event — lets a consumer (or an AI
  * agent) filter the timeline: skip `low` UI/bookkeeping noise, skim `normal`
@@ -57,12 +59,38 @@ export interface MetaEvent {
     detail?: Record<string, unknown>;
 }
 /**
- * Append a meta event to the timeline for `key`. Evicts the oldest entry once
- * the buffer exceeds {@link DEFAULT_MAX_META_EVENTS}. An empty `key` is bucketed
- * under `''`, matching how drivers/stores handle an absent session identity, so
+ * Append a meta event to the timeline for `key`. Once the buffer exceeds
+ * {@link DEFAULT_MAX_META_EVENTS}, evicts the oldest *non-`high`* event;
+ * `high`-importance events are never evicted. An empty `key` is bucketed under
+ * `''`, matching how drivers/stores handle an absent session identity, so
  * callers never need to guard.
  */
 export declare function recordMetaEvent(key: string, type: MetaEventType, detail?: Record<string, unknown>): void;
+/**
+ * Why a turn failed or was retried — stamped as `detail.reason` on `turn.error`
+ * and `turn.retry` events. Enumerated so the set stays in sync with the README
+ * and call sites can't drift to ad-hoc strings.
+ *
+ * - `exception`              — an uncaught error escaped the tool loop (catch-all).
+ * - `malformed-function-call`— the provider returned an unparseable tool call.
+ * - `empty-response`         — the model returned no content and no tool calls.
+ * - `unknown-tool-limit`     — the model repeatedly called tools that don't exist.
+ * - `max-iterations`         — the tool loop hit its iteration cap.
+ */
+export type TurnFailureReason = 'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations';
+/**
+ * Record a turn-ending failure (`turn.error`, importance `high`). The `reason`
+ * is typed so the high-importance triage surface stays consistent; pass any
+ * diagnostic specifics (attempt counts, offending tool names, etc.) in `detail`.
+ */
+export declare function recordTurnError(key: string, reason: TurnFailureReason, detail?: Record<string, unknown>): void;
+/**
+ * Record a recoverable retry *within* a turn (`turn.retry`, importance `normal`)
+ * — e.g. one malformed/empty attempt that will be retried, as distinct from the
+ * final attempt that bails out as a `turn.error`. Include `attempt`/`maxAttempts`
+ * in `detail` so the timeline shows which try this was.
+ */
+export declare function recordTurnRetry(key: string, reason: TurnFailureReason, detail?: Record<string, unknown>): void;
 /** Returns the meta-event timeline for `key`, or an empty array if none recorded. */
 export declare function getMetaEvents(key: string): ReadonlyArray<MetaEvent>;
 /**

package/dist/dts/state/debug-event-log.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"debug-event-log.d.ts","sourceRoot":"","sources":["../../../src/state/debug-event-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAErB,qBAAqB,GACrB,wBAAwB,GACxB,kBAAkB,GAClB,iBAAiB,GAEjB,gBAAgB,GAChB,cAAc,GACd,gBAAgB,GAEhB,eAAe,GACf,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,aAAa,GAEb,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,mBAAmB,GAEnB,uBAAuB,GACvB,sBAAsB,GAEtB,iBAAiB,GACjB,2BAA2B,GAE3B,eAAe,GACf,kBAAkB,GAClB,kBAAkB,GAClB,oBAAoB,CAAC;AAEzB;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE5D;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,aAAa,EAAE,mBAAmB,CA2B5E,CAAC;AAEF,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACxB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,IAAI,EAAE,aAAa,CAAC;IACpB,6EAA6E;IAC7E,UAAU,EAAE,mBAAmB,CAAC;IAChC,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAaD;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,aAAa,EACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAiBN;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,CAEnE;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAW7C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}
+{"version":3,"file":"debug-event-log.d.ts","sourceRoot":"","sources":["../../../src/state/debug-event-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAErB,qBAAqB,GACrB,wBAAwB,GACxB,kBAAkB,GAClB,iBAAiB,GAEjB,gBAAgB,GAChB,cAAc,GACd,gBAAgB,GAEhB,eAAe,GACf,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,aAAa,GAEb,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,mBAAmB,GAEnB,uBAAuB,GACvB,sBAAsB,GAEtB,iBAAiB,GACjB,2BAA2B,GAE3B,eAAe,GACf,kBAAkB,GAClB,kBAAkB,GAClB,oBAAoB,CAAC;AAEzB;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE5D;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,aAAa,EAAE,mBAAmB,CA4B5E,CAAC;AAEF,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACxB,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,IAAI,EAAE,aAAa,CAAC;IACpB,6EAA6E;IAC7E,UAAU,EAAE,mBAAmB,CAAC;IAChC,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAmBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,aAAa,EACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAyBN;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,yBAAyB,GACzB,gBAAgB,GAChB,oBAAoB,GACpB,gBAAgB,CAAC;AAErB;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,EACzB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAEN;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,EACzB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAEN;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAC,SAAS,CAAC,CAEnE;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAW7C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

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

@@ -2,13 +2,21 @@ import { __awaiter } from "tslib";
 import { MalformedFunctionCallError } from '@genesislcap/foundation-ai';
 import { agenticActivityBus } from '../../channel/ai-activity-bus';
 import { resolveChatProvider } from '../../config/validate-providers';
-import { recordMetaEvent } from '../../state/debug-event-log';
+import { recordMetaEvent, recordTurnError, recordTurnRetry } from '../../state/debug-event-log';
 import { applyHistoryCap } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
 import { TOOL_FOLD_SYMBOL } from '../../utils/tool-fold';
 const DEFAULT_MAX_TOOL_ITERATIONS = 50;
 const DEFAULT_MAX_FOLD_OPERATIONS = 5;
-const DEFAULT_MAX_TURN_SNAPSHOTS = 40;
+// TODO: dedup system prompts in-memory to allow raising this cap much higher.
+// Each TurnSnapshot stores the full resolved `systemPrompt`, so the buffer's
+// memory cost scales with cap × prompt size — a stable agent repeats a multi-KB
+// prompt every turn. `getDebugLog` already dedups identical consecutive prompts
+// at export time (`<repeated — identical to turn N>`); applying the same dedup
+// at capture time (store the prompt only when it changes, back-reference
+// otherwise) would make snapshots nearly as cheap as meta events and let this
+// cap reach thousands for full-session capture without the memory blowup.
+const DEFAULT_MAX_TURN_SNAPSHOTS = 400;
 const DEFAULT_MAX_UNKNOWN_TOOL_CALLS = 5;
 const MAX_MALFORMED_RETRIES = 2;
 const MAX_EMPTY_RESPONSE_RETRIES = 3;
@@ -46,6 +54,12 @@ export class ChatDriver extends EventTarget {
         this.consecutiveFoldOps = 0;
         /** Consecutive unknown-tool calls without a real tool call. Reset on real tool execution. */
         this.consecutiveUnknownToolCalls = 0;
+        /**
+         * Distinct unknown-tool names seen in the current consecutive streak — stamped
+         * onto the `unknown-tool-limit` turn.error so a triager knows which tools were
+         * hallucinated. Reset alongside `consecutiveUnknownToolCalls`.
+         */
+        this.recentUnknownToolNames = new Set();
         /** Sub-agents declared on the active agent config, keyed by name. */
         this.subAgentsMap = new Map();
         /**
@@ -494,13 +508,17 @@ export class ChatDriver extends EventTarget {
             }
             catch (e) {
                 logger.error('ChatDriver error:', e);
-                recordMetaEvent(this.sessionKey, 'turn.error', {
+                recordTurnError(this.sessionKey, 'exception', {
                     phase: 'sendMessage',
                     agent: this.activeAgentName,
                     provider: this.lastResolvedProviderName,
+                    name: e instanceof Error ? e.name : undefined,
                     message: e instanceof Error ? e.message : String(e),
                 });
-                this.appendToHistory({ role: 'assistant', content: 'Sorry, something went wrong.' });
+                this.appendToHistory({
+                    role: 'assistant',
+                    content: 'Sorry, something went wrong on my end. Please try again in a moment.',
+                });
                 return { reason: 'done' };
             }
             finally {
@@ -644,13 +662,17 @@ export class ChatDriver extends EventTarget {
             }
             catch (e) {
                 logger.error('ChatDriver error:', e);
-                recordMetaEvent(this.sessionKey, 'turn.error', {
+                recordTurnError(this.sessionKey, 'exception', {
                     phase: 'continueFromHistory',
                     agent: this.activeAgentName,
                     provider: this.lastResolvedProviderName,
+                    name: e instanceof Error ? e.name : undefined,
                     message: e instanceof Error ? e.message : String(e),
                 });
-                this.appendToHistory({ role: 'assistant', content: 'Sorry, something went wrong.' });
+                this.appendToHistory({
+                    role: 'assistant',
+                    content: 'Sorry, something went wrong on my end. Please try again in a moment.',
+                });
                 return { reason: 'done' };
             }
             finally {
@@ -798,7 +820,7 @@ export class ChatDriver extends EventTarget {
     // oxlint-disable-next-line complexity
     runToolLoop(userInput, attachments, transientPrimer) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g;
+            var _a, _b, _c, _d, _e, _f, _g, _h;
             if (!this.systemPrompt) {
                 logger.warn('ChatDriver: no systemPrompt set. The assistant will have no instructions — provide a systemPrompt via agents config or the foundation-ai-assistant property.');
             }
@@ -898,18 +920,26 @@ export class ChatDriver extends EventTarget {
                         malformedAttempts += 1;
                         if (malformedAttempts < MAX_MALFORMED_RETRIES) {
                             logger.warn(`ChatDriver: MALFORMED_FUNCTION_CALL, retrying (${malformedAttempts}/${MAX_MALFORMED_RETRIES})`);
+                            recordTurnRetry(this.sessionKey, 'malformed-function-call', {
+                                agent: this.activeAgentName,
+                                provider: this.lastResolvedProviderName,
+                                attempt: malformedAttempts,
+                                maxAttempts: MAX_MALFORMED_RETRIES,
+                                finishMessage: e.finishMessage,
+                            });
                             iterations -= 1;
                             continue;
                         }
                         logger.error('ChatDriver: MALFORMED_FUNCTION_CALL, max retries reached');
-                        recordMetaEvent(this.sessionKey, 'turn.error', {
-                            reason: 'malformed-function-call',
+                        recordTurnError(this.sessionKey, 'malformed-function-call', {
                             agent: this.activeAgentName,
                             provider: this.lastResolvedProviderName,
+                            attempts: malformedAttempts,
+                            finishMessage: e.finishMessage,
                         });
                         this.appendToHistory({
                             role: 'assistant',
-                            content: "I'm sorry, I wasn't able to complete that request. Please try rephrasing or breaking it into smaller steps.",
+                            content: 'While working on your request, I repeatedly called my tools incorrectly. This often works on a second try — would you like me to try again? If it happens again, try breaking your request into smaller steps.',
                         });
                         return { reason: 'done' };
                     }
@@ -921,18 +951,24 @@ export class ChatDriver extends EventTarget {
                     emptyResponseAttempts += 1;
                     if (emptyResponseAttempts < MAX_EMPTY_RESPONSE_RETRIES) {
                         logger.warn(`ChatDriver: empty model response, retrying (${emptyResponseAttempts}/${MAX_EMPTY_RESPONSE_RETRIES})`);
+                        recordTurnRetry(this.sessionKey, 'empty-response', {
+                            agent: this.activeAgentName,
+                            provider: this.lastResolvedProviderName,
+                            attempt: emptyResponseAttempts,
+                            maxAttempts: MAX_EMPTY_RESPONSE_RETRIES,
+                        });
                         iterations -= 1;
                         continue;
                     }
                     logger.error('ChatDriver: empty model response after all retries');
-                    recordMetaEvent(this.sessionKey, 'turn.error', {
-                        reason: 'empty-response',
+                    recordTurnError(this.sessionKey, 'empty-response', {
                         agent: this.activeAgentName,
                         provider: this.lastResolvedProviderName,
+                        attempts: emptyResponseAttempts,
                     });
                     this.appendToHistory({
                         role: 'assistant',
-                        content: 'Remote agent returned no response.',
+                        content: 'While working on your request, I repeatedly generated a blank response. This often works on a second try — would you like me to try again? If it happens again, try breaking your request into smaller steps.',
                     });
                     return { reason: 'done' };
                 }
@@ -1014,6 +1050,7 @@ export class ChatDriver extends EventTarget {
                                 logger.warn(`ChatDriver: no handler registered for tool "${tc.name}" (${this.consecutiveUnknownToolCalls}/${DEFAULT_MAX_UNKNOWN_TOOL_CALLS}). Available tools: ${Object.keys(this.toolHandlers).join(', ') || '(none)'}`);
                                 executedById.set(tc.id, { toolCallId: tc.id, content: `Unknown tool: ${tc.name}` });
                                 unknownToolIds.add(tc.id);
+                                this.recentUnknownToolNames.add(tc.name);
                                 if (this.consecutiveUnknownToolCalls >= DEFAULT_MAX_UNKNOWN_TOOL_CALLS) {
                                     hitUnknownToolLimit = true;
                                 }
@@ -1051,6 +1088,7 @@ export class ChatDriver extends EventTarget {
                 if (anyRealToolExecuted) {
                     this.consecutiveFoldOps = 0;
                     this.consecutiveUnknownToolCalls = 0;
+                    this.recentUnknownToolNames.clear();
                 }
                 // Tag tool calls with fold UI metadata before appending results
                 const foldPath = this.foldStack.map((f) => f.foldName);
@@ -1105,14 +1143,23 @@ export class ChatDriver extends EventTarget {
                 }
                 if (hitUnknownToolLimit) {
                     logger.error(`ChatDriver: unknown-tool limit (${DEFAULT_MAX_UNKNOWN_TOOL_CALLS}) reached — stopping`);
-                    recordMetaEvent(this.sessionKey, 'turn.error', {
-                        reason: 'unknown-tool-limit',
+                    const unknownTools = [
+                        ...new Set([
+                            ...this.recentUnknownToolNames,
+                            ...((_h = response.toolCalls) !== null && _h !== void 0 ? _h : [])
+                                .filter((tc) => unknownToolIds.has(tc.id))
+                                .map((tc) => tc.name),
+                        ]),
+                    ];
+                    recordTurnError(this.sessionKey, 'unknown-tool-limit', {
                         agent: this.activeAgentName,
                         provider: this.lastResolvedProviderName,
+                        unknownTools,
+                        availableTools: Object.keys(this.toolHandlers),
                     });
                     this.appendToHistory({
                         role: 'assistant',
-                        content: "I'm sorry, I repeatedly tried to use tools that don't exist. Please check your agent configuration or try rephrasing your request.",
+                        content: "I'm sorry, I repeatedly tried to use tools that aren't available to me, so I couldn't complete that. If a 'Download agent log' option appears in the Settings (cog) menu, you can download the log and share it with whoever set up this assistant to help fix the issue.",
                     });
                     return { reason: 'done' };
                 }
@@ -1129,10 +1176,11 @@ export class ChatDriver extends EventTarget {
             }
             if (iterations >= this.maxToolIterations) {
                 logger.warn('ChatDriver: reached max tool iterations, stopping');
-                recordMetaEvent(this.sessionKey, 'turn.error', {
-                    reason: 'max-iterations',
+                recordTurnError(this.sessionKey, 'max-iterations', {
                     agent: this.activeAgentName,
                     provider: this.lastResolvedProviderName,
+                    iterations,
+                    limit: this.maxToolIterations,
                 });
                 this.appendToHistory({
                     role: 'assistant',

package/dist/esm/components/chat-interaction-wrapper/chat-interaction-wrapper.js

@@ -87,9 +87,9 @@ let AiChatInteractionWrapper = class AiChatInteractionWrapper extends GenesisEle
         this._resizeObserver = undefined;
         this.container.replaceChildren();
         if (!customElements.get(this.componentName)) {
-            logger.warn(`Interactive component "\${this.componentName}" is not registered in the customElements registry.`);
+            logger.warn(`Interactive component "${this.componentName}" is not registered in the customElements registry.`);
             const errorDiv = document.createElement('div');
-            errorDiv.textContent = `Error: Component "\${this.componentName}" is not available in this application.`;
+            errorDiv.textContent = `Error: Component "${this.componentName}" is not available in this application.`;
             this.container.appendChild(errorDiv);
             return;
         }
@@ -121,7 +121,7 @@ let AiChatInteractionWrapper = class AiChatInteractionWrapper extends GenesisEle
         catch (e) {
             logger.error(`Failed to create interactive component: \${this.componentName}`, e);
             const errorDiv = document.createElement('div');
-            errorDiv.textContent = `Error: Could not load component \${this.componentName}`;
+            errorDiv.textContent = `Error: Could not load component ${this.componentName}`;
             this.container.appendChild(errorDiv);
         }
     }

package/dist/esm/components/orchestrating-driver/orchestrating-driver.js

@@ -222,7 +222,7 @@ export class OrchestratingDriver extends EventTarget {
                 }
                 handoffs += 1;
                 if (handoffs > this.maxHandoffs) {
-                    this.appendInlineMessage(`I wasn't able to fully complete your request — the task required more hand-offs between specialists than allowed (max: ${this.maxHandoffs}). Please try breaking your request into smaller steps.`);
+                    this.appendInlineMessage(`I wasn't able to fully complete your request — the task required more hand-offs between specialists than allowed. Please try breaking your request into smaller steps.`);
                     break;
                 }
                 handoffSummary = result.summary;

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

@@ -16,8 +16,10 @@
  *   there's no reason to pay immutable-reducer cost or flood the Redux DevTools
  *   action log with debug noise.
  *
- * Surfaced under `getDebugLog().meta.events`. Ring-buffered so a long-lived
- * session can't grow the timeline unbounded.
+ * Surfaced in `getDebugLog().timeline`, merged chronologically with messages and
+ * turn snapshots. Ring-buffered — the oldest non-`high` events are evicted first
+ * while `high`-importance failure events are retained — so a long-lived session
+ * stays bounded in normal use without ever dropping a failure signal.
  *
  * @internal
  */
@@ -45,6 +47,7 @@ export const META_EVENT_IMPORTANCE = {
     'state.changed': 'normal',
     'turn.start': 'normal',
     'turn.end': 'normal',
+    'turn.retry': 'normal',
     'agent.handoff': 'normal',
     'agent.pinned': 'normal',
     'agent.unpinned': 'normal',
@@ -57,13 +60,20 @@ export const META_EVENT_IMPORTANCE = {
     'panel.toggled': 'low',
     'attachment.added': 'low',
 };
-/** Default ring-buffer cap. ~5× the turn-snapshot cap — entries are cheap. */
-const DEFAULT_MAX_META_EVENTS = 200;
+/**
+ * Soft ring-buffer cap. Once exceeded, the oldest *non-`high`* event is evicted;
+ * `high`-importance events (failures and hard limits) are never dropped — they're
+ * the whole reason the log exists. So a buffer dominated by `high` events is
+ * allowed to float above this cap rather than lose a failure signal; in normal
+ * use the frequent `low`/`normal` events keep it near the cap. Entries are cheap.
+ */
+const DEFAULT_MAX_META_EVENTS = 400;
 const registry = new Map();
 /**
- * Append a meta event to the timeline for `key`. Evicts the oldest entry once
- * the buffer exceeds {@link DEFAULT_MAX_META_EVENTS}. An empty `key` is bucketed
- * under `''`, matching how drivers/stores handle an absent session identity, so
+ * Append a meta event to the timeline for `key`. Once the buffer exceeds
+ * {@link DEFAULT_MAX_META_EVENTS}, evicts the oldest *non-`high`* event;
+ * `high`-importance events are never evicted. An empty `key` is bucketed under
+ * `''`, matching how drivers/stores handle an absent session identity, so
  * callers never need to guard.
  */
 export function recordMetaEvent(key, type, detail) {
@@ -81,9 +91,34 @@ export function recordMetaEvent(key, type, detail) {
     });
     buffer.next += 1;
     if (buffer.events.length > DEFAULT_MAX_META_EVENTS) {
-        buffer.events.shift();
+        // Drop the oldest event that isn't `high` importance. `high` events
+        // (failures/limits) are retained even past the cap — losing a failure
+        // signal is worse than briefly exceeding the buffer size. If every retained
+        // event is `high` (all-failures session), nothing is evicted and the buffer
+        // grows; in practice frequent `low`/`normal` events keep it bounded.
+        const evictAt = buffer.events.findIndex((e) => e.importance !== 'high');
+        if (evictAt !== -1) {
+            buffer.events.splice(evictAt, 1);
+        }
     }
 }
+/**
+ * Record a turn-ending failure (`turn.error`, importance `high`). The `reason`
+ * is typed so the high-importance triage surface stays consistent; pass any
+ * diagnostic specifics (attempt counts, offending tool names, etc.) in `detail`.
+ */
+export function recordTurnError(key, reason, detail) {
+    recordMetaEvent(key, 'turn.error', Object.assign({ reason }, detail));
+}
+/**
+ * Record a recoverable retry *within* a turn (`turn.retry`, importance `normal`)
+ * — e.g. one malformed/empty attempt that will be retried, as distinct from the
+ * final attempt that bails out as a `turn.error`. Include `attempt`/`maxAttempts`
+ * in `detail` so the timeline shows which try this was.
+ */
+export function recordTurnRetry(key, reason, detail) {
+    recordMetaEvent(key, 'turn.retry', Object.assign({ reason }, detail));
+}
 /** Returns the meta-event timeline for `key`, or an empty array if none recorded. */
 export function getMetaEvents(key) {
     var _a, _b;
@@ -102,8 +137,8 @@ export const DEBUG_LOG_README = [
     "kind:'turn' — one LLM call. `systemPrompt` and `toolNames` are what the model saw. A systemPrompt of '<repeated — identical to turn N>' was byte-identical to turn N and de-duplicated; the full prompt is shown whenever it changes (often because a stateful agent advanced), so prompt evolution is visible.",
     "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, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, handoffs, agent/provider changes, interactions), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. '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.error (a turn failed or hit a guardrail — see detail.reason), tool.failed (a tool threw), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (model/provider for the upcoming turns), interaction.requested/resolved (blocking user widgets — explain quiet gaps), context.updated/threshold-crossed (token + cost), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
+    "Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated). 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), 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, plus reason-specific diagnostics: attempts, finishMessage, unknownTools + availableTools, iterations + limit, or name + message for exceptions), tool.failed (a tool threw), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (model/provider for the upcoming turns), interaction.requested/resolved (blocking user widgets — explain quiet gaps), context.updated/threshold-crossed (token + cost), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
     "`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, token usage, session cost), 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.",
     'To debug a failure: find the last turn.error or tool.failed, then read upward for the user message, the turn(s), and the agent/provider/state events that led into it.',
 ];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "14.451.1",
+  "version": "14.451.2-FUI-2550.1",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -64,24 +64,24 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.451.1",
-    "@genesislcap/genx": "14.451.1",
-    "@genesislcap/rollup-builder": "14.451.1",
-    "@genesislcap/ts-builder": "14.451.1",
-    "@genesislcap/uvu-playwright-builder": "14.451.1",
-    "@genesislcap/vite-builder": "14.451.1",
-    "@genesislcap/webpack-builder": "14.451.1",
+    "@genesislcap/foundation-testing": "14.451.2-FUI-2550.1",
+    "@genesislcap/genx": "14.451.2-FUI-2550.1",
+    "@genesislcap/rollup-builder": "14.451.2-FUI-2550.1",
+    "@genesislcap/ts-builder": "14.451.2-FUI-2550.1",
+    "@genesislcap/uvu-playwright-builder": "14.451.2-FUI-2550.1",
+    "@genesislcap/vite-builder": "14.451.2-FUI-2550.1",
+    "@genesislcap/webpack-builder": "14.451.2-FUI-2550.1",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "14.451.1",
-    "@genesislcap/foundation-logger": "14.451.1",
-    "@genesislcap/foundation-redux": "14.451.1",
-    "@genesislcap/foundation-ui": "14.451.1",
-    "@genesislcap/foundation-utils": "14.451.1",
-    "@genesislcap/rapid-design-system": "14.451.1",
-    "@genesislcap/web-core": "14.451.1",
+    "@genesislcap/foundation-ai": "14.451.2-FUI-2550.1",
+    "@genesislcap/foundation-logger": "14.451.2-FUI-2550.1",
+    "@genesislcap/foundation-redux": "14.451.2-FUI-2550.1",
+    "@genesislcap/foundation-ui": "14.451.2-FUI-2550.1",
+    "@genesislcap/foundation-utils": "14.451.2-FUI-2550.1",
+    "@genesislcap/rapid-design-system": "14.451.2-FUI-2550.1",
+    "@genesislcap/web-core": "14.451.2-FUI-2550.1",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -93,5 +93,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "63decfd7190d1701b06dadb80d4a45ef5b29c4fe"
+  "gitHead": "66dcfaa6711a02dc94ffc5934a69d312054dfe0b"
 }

package/src/components/chat-driver/chat-driver.ts

@@ -22,7 +22,7 @@ import type {
   ToolHandlersInput,
 } from '../../config/config';
 import { resolveChatProvider } from '../../config/validate-providers';
-import { recordMetaEvent } from '../../state/debug-event-log';
+import { recordMetaEvent, recordTurnError, recordTurnRetry } from '../../state/debug-event-log';
 import { applyHistoryCap } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
 import { TOOL_FOLD_SYMBOL, type ToolFold } from '../../utils/tool-fold';
@@ -30,7 +30,15 @@ import type { AiDriver, AllAgentSummary } from '../ai-driver/ai-driver';
 
 const DEFAULT_MAX_TOOL_ITERATIONS = 50;
 const DEFAULT_MAX_FOLD_OPERATIONS = 5;
-const DEFAULT_MAX_TURN_SNAPSHOTS = 40;
+// TODO: dedup system prompts in-memory to allow raising this cap much higher.
+// Each TurnSnapshot stores the full resolved `systemPrompt`, so the buffer's
+// memory cost scales with cap × prompt size — a stable agent repeats a multi-KB
+// prompt every turn. `getDebugLog` already dedups identical consecutive prompts
+// at export time (`<repeated — identical to turn N>`); applying the same dedup
+// at capture time (store the prompt only when it changes, back-reference
+// otherwise) would make snapshots nearly as cheap as meta events and let this
+// cap reach thousands for full-session capture without the memory blowup.
+const DEFAULT_MAX_TURN_SNAPSHOTS = 400;
 const DEFAULT_MAX_UNKNOWN_TOOL_CALLS = 5;
 const MAX_MALFORMED_RETRIES = 2;
 const MAX_EMPTY_RESPONSE_RETRIES = 3;
@@ -53,7 +61,7 @@ export type ChatHistoryUpdatedEvent = CustomEvent<ReadonlyArray<ChatMessage>>;
 /**
  * One captured frame of what the LLM saw on a single tool-loop iteration.
  * The driver records these as a ring buffer (cap: configurable via
- * `chatConfig.agent.maxTurnSnapshots`, default 40) so the export log can show,
+ * `chatConfig.agent.maxTurnSnapshots`, default 400) so the export log can show,
  * per turn: which agent was active, the resolved system prompt, the tool names
  * visible to the LLM, and any agent-supplied debug snapshot (e.g. machine
  * state for stateful agents).
@@ -178,6 +186,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
   private consecutiveFoldOps = 0;
   /** Consecutive unknown-tool calls without a real tool call. Reset on real tool execution. */
   private consecutiveUnknownToolCalls = 0;
+  /**
+   * Distinct unknown-tool names seen in the current consecutive streak — stamped
+   * onto the `unknown-tool-limit` turn.error so a triager knows which tools were
+   * hallucinated. Reset alongside `consecutiveUnknownToolCalls`.
+   */
+  private readonly recentUnknownToolNames = new Set<string>();
   private readonly maxFoldOperations: number;
 
   /** Sub-agents declared on the active agent config, keyed by name. */
@@ -700,13 +714,17 @@ export class ChatDriver extends EventTarget implements AiDriver {
       return await this.runToolLoop(userInput, attachments);
     } catch (e) {
       logger.error('ChatDriver error:', e);
-      recordMetaEvent(this.sessionKey, 'turn.error', {
+      recordTurnError(this.sessionKey, 'exception', {
         phase: 'sendMessage',
         agent: this.activeAgentName,
         provider: this.lastResolvedProviderName,
+        name: e instanceof Error ? e.name : undefined,
         message: e instanceof Error ? e.message : String(e),
       });
-      this.appendToHistory({ role: 'assistant', content: 'Sorry, something went wrong.' });
+      this.appendToHistory({
+        role: 'assistant',
+        content: 'Sorry, something went wrong on my end. Please try again in a moment.',
+      });
       return { reason: 'done' };
     } finally {
       recordMetaEvent(this.sessionKey, 'turn.end', {
@@ -885,13 +903,17 @@ export class ChatDriver extends EventTarget implements AiDriver {
       return await this.runToolLoop('', undefined, transientPrimer);
     } catch (e) {
       logger.error('ChatDriver error:', e);
-      recordMetaEvent(this.sessionKey, 'turn.error', {
+      recordTurnError(this.sessionKey, 'exception', {
         phase: 'continueFromHistory',
         agent: this.activeAgentName,
         provider: this.lastResolvedProviderName,
+        name: e instanceof Error ? e.name : undefined,
         message: e instanceof Error ? e.message : String(e),
       });
-      this.appendToHistory({ role: 'assistant', content: 'Sorry, something went wrong.' });
+      this.appendToHistory({
+        role: 'assistant',
+        content: 'Sorry, something went wrong on my end. Please try again in a moment.',
+      });
       return { reason: 'done' };
     } finally {
       recordMetaEvent(this.sessionKey, 'turn.end', {
@@ -1183,19 +1205,27 @@ export class ChatDriver extends EventTarget implements AiDriver {
             logger.warn(
               `ChatDriver: MALFORMED_FUNCTION_CALL, retrying (${malformedAttempts}/${MAX_MALFORMED_RETRIES})`,
             );
+            recordTurnRetry(this.sessionKey, 'malformed-function-call', {
+              agent: this.activeAgentName,
+              provider: this.lastResolvedProviderName,
+              attempt: malformedAttempts,
+              maxAttempts: MAX_MALFORMED_RETRIES,
+              finishMessage: e.finishMessage,
+            });
             iterations -= 1;
             continue;
           }
           logger.error('ChatDriver: MALFORMED_FUNCTION_CALL, max retries reached');
-          recordMetaEvent(this.sessionKey, 'turn.error', {
-            reason: 'malformed-function-call',
+          recordTurnError(this.sessionKey, 'malformed-function-call', {
             agent: this.activeAgentName,
             provider: this.lastResolvedProviderName,
+            attempts: malformedAttempts,
+            finishMessage: e.finishMessage,
           });
           this.appendToHistory({
             role: 'assistant',
             content:
-              "I'm sorry, I wasn't able to complete that request. Please try rephrasing or breaking it into smaller steps.",
+              'While working on your request, I repeatedly called my tools incorrectly. This often works on a second try — would you like me to try again? If it happens again, try breaking your request into smaller steps.',
           });
           return { reason: 'done' };
         }
@@ -1211,18 +1241,25 @@ export class ChatDriver extends EventTarget implements AiDriver {
           logger.warn(
             `ChatDriver: empty model response, retrying (${emptyResponseAttempts}/${MAX_EMPTY_RESPONSE_RETRIES})`,
           );
+          recordTurnRetry(this.sessionKey, 'empty-response', {
+            agent: this.activeAgentName,
+            provider: this.lastResolvedProviderName,
+            attempt: emptyResponseAttempts,
+            maxAttempts: MAX_EMPTY_RESPONSE_RETRIES,
+          });
           iterations -= 1;
           continue;
         }
         logger.error('ChatDriver: empty model response after all retries');
-        recordMetaEvent(this.sessionKey, 'turn.error', {
-          reason: 'empty-response',
+        recordTurnError(this.sessionKey, 'empty-response', {
           agent: this.activeAgentName,
           provider: this.lastResolvedProviderName,
+          attempts: emptyResponseAttempts,
         });
         this.appendToHistory({
           role: 'assistant',
-          content: 'Remote agent returned no response.',
+          content:
+            'While working on your request, I repeatedly generated a blank response. This often works on a second try — would you like me to try again? If it happens again, try breaking your request into smaller steps.',
         });
         return { reason: 'done' };
       } else if (isThinkingStep) {
@@ -1318,6 +1355,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
                 );
                 executedById.set(tc.id, { toolCallId: tc.id, content: `Unknown tool: ${tc.name}` });
                 unknownToolIds.add(tc.id);
+                this.recentUnknownToolNames.add(tc.name);
                 if (this.consecutiveUnknownToolCalls >= DEFAULT_MAX_UNKNOWN_TOOL_CALLS) {
                   hitUnknownToolLimit = true;
                 }
@@ -1357,6 +1395,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       if (anyRealToolExecuted) {
         this.consecutiveFoldOps = 0;
         this.consecutiveUnknownToolCalls = 0;
+        this.recentUnknownToolNames.clear();
       }
 
       // Tag tool calls with fold UI metadata before appending results
@@ -1423,15 +1462,24 @@ export class ChatDriver extends EventTarget implements AiDriver {
         logger.error(
           `ChatDriver: unknown-tool limit (${DEFAULT_MAX_UNKNOWN_TOOL_CALLS}) reached — stopping`,
         );
-        recordMetaEvent(this.sessionKey, 'turn.error', {
-          reason: 'unknown-tool-limit',
+        const unknownTools = [
+          ...new Set([
+            ...this.recentUnknownToolNames,
+            ...(response.toolCalls ?? [])
+              .filter((tc) => unknownToolIds.has(tc.id))
+              .map((tc) => tc.name),
+          ]),
+        ];
+        recordTurnError(this.sessionKey, 'unknown-tool-limit', {
           agent: this.activeAgentName,
           provider: this.lastResolvedProviderName,
+          unknownTools,
+          availableTools: Object.keys(this.toolHandlers),
         });
         this.appendToHistory({
           role: 'assistant',
           content:
-            "I'm sorry, I repeatedly tried to use tools that don't exist. Please check your agent configuration or try rephrasing your request.",
+            "I'm sorry, I repeatedly tried to use tools that aren't available to me, so I couldn't complete that. If a 'Download agent log' option appears in the Settings (cog) menu, you can download the log and share it with whoever set up this assistant to help fix the issue.",
         });
         return { reason: 'done' };
       }
@@ -1454,10 +1502,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
 
     if (iterations >= this.maxToolIterations) {
       logger.warn('ChatDriver: reached max tool iterations, stopping');
-      recordMetaEvent(this.sessionKey, 'turn.error', {
-        reason: 'max-iterations',
+      recordTurnError(this.sessionKey, 'max-iterations', {
         agent: this.activeAgentName,
         provider: this.lastResolvedProviderName,
+        iterations,
+        limit: this.maxToolIterations,
       });
       this.appendToHistory({
         role: 'assistant',

package/src/components/chat-interaction-wrapper/chat-interaction-wrapper.ts

@@ -109,10 +109,10 @@ export class AiChatInteractionWrapper extends GenesisElement {
 
     if (!customElements.get(this.componentName)) {
       logger.warn(
-        `Interactive component "\${this.componentName}" is not registered in the customElements registry.`,
+        `Interactive component "${this.componentName}" is not registered in the customElements registry.`,
       );
       const errorDiv = document.createElement('div');
-      errorDiv.textContent = `Error: Component "\${this.componentName}" is not available in this application.`;
+      errorDiv.textContent = `Error: Component "${this.componentName}" is not available in this application.`;
       this.container.appendChild(errorDiv);
       return;
     }
@@ -150,7 +150,7 @@ export class AiChatInteractionWrapper extends GenesisElement {
     } catch (e) {
       logger.error(`Failed to create interactive component: \${this.componentName}`, e);
       const errorDiv = document.createElement('div');
-      errorDiv.textContent = `Error: Could not load component \${this.componentName}`;
+      errorDiv.textContent = `Error: Could not load component ${this.componentName}`;
       this.container.appendChild(errorDiv);
     }
   }

package/src/components/orchestrating-driver/orchestrating-driver.ts

@@ -316,7 +316,7 @@ export class OrchestratingDriver extends EventTarget implements AiDriver {
       handoffs += 1;
       if (handoffs > this.maxHandoffs) {
         this.appendInlineMessage(
-          `I wasn't able to fully complete your request — the task required more hand-offs between specialists than allowed (max: ${this.maxHandoffs}). Please try breaking your request into smaller steps.`,
+          `I wasn't able to fully complete your request — the task required more hand-offs between specialists than allowed. Please try breaking your request into smaller steps.`,
         );
         break;
       }

package/src/state/debug-event-log.ts

@@ -16,8 +16,10 @@
  *   there's no reason to pay immutable-reducer cost or flood the Redux DevTools
  *   action log with debug noise.
  *
- * Surfaced under `getDebugLog().meta.events`. Ring-buffered so a long-lived
- * session can't grow the timeline unbounded.
+ * Surfaced in `getDebugLog().timeline`, merged chronologically with messages and
+ * turn snapshots. Ring-buffered — the oldest non-`high` events are evicted first
+ * while `high`-importance failure events are retained — so a long-lived session
+ * stays bounded in normal use without ever dropping a failure signal.
  *
  * @internal
  */
@@ -40,6 +42,7 @@ export type MetaEventType =
   | 'state.changed'
   | 'turn.start'
   | 'turn.end'
+  | 'turn.retry'
   | 'turn.error'
   | 'tool.failed'
   // Routing / providers
@@ -91,6 +94,7 @@ export const META_EVENT_IMPORTANCE: Record<MetaEventType, MetaEventImportance> =
   'state.changed': 'normal',
   'turn.start': 'normal',
   'turn.end': 'normal',
+  'turn.retry': 'normal',
   'agent.handoff': 'normal',
   'agent.pinned': 'normal',
   'agent.unpinned': 'normal',
@@ -119,8 +123,14 @@ export interface MetaEvent {
   detail?: Record<string, unknown>;
 }
 
-/** Default ring-buffer cap. ~5× the turn-snapshot cap — entries are cheap. */
-const DEFAULT_MAX_META_EVENTS = 200;
+/**
+ * Soft ring-buffer cap. Once exceeded, the oldest *non-`high`* event is evicted;
+ * `high`-importance events (failures and hard limits) are never dropped — they're
+ * the whole reason the log exists. So a buffer dominated by `high` events is
+ * allowed to float above this cap rather than lose a failure signal; in normal
+ * use the frequent `low`/`normal` events keep it near the cap. Entries are cheap.
+ */
+const DEFAULT_MAX_META_EVENTS = 400;
 
 interface MetaEventBuffer {
   events: MetaEvent[];
@@ -131,9 +141,10 @@ interface MetaEventBuffer {
 const registry = new Map<string, MetaEventBuffer>();
 
 /**
- * Append a meta event to the timeline for `key`. Evicts the oldest entry once
- * the buffer exceeds {@link DEFAULT_MAX_META_EVENTS}. An empty `key` is bucketed
- * under `''`, matching how drivers/stores handle an absent session identity, so
+ * Append a meta event to the timeline for `key`. Once the buffer exceeds
+ * {@link DEFAULT_MAX_META_EVENTS}, evicts the oldest *non-`high`* event;
+ * `high`-importance events are never evicted. An empty `key` is bucketed under
+ * `''`, matching how drivers/stores handle an absent session identity, so
  * callers never need to guard.
  */
 export function recordMetaEvent(
@@ -155,10 +166,63 @@ export function recordMetaEvent(
   });
   buffer.next += 1;
   if (buffer.events.length > DEFAULT_MAX_META_EVENTS) {
-    buffer.events.shift();
+    // Drop the oldest event that isn't `high` importance. `high` events
+    // (failures/limits) are retained even past the cap — losing a failure
+    // signal is worse than briefly exceeding the buffer size. If every retained
+    // event is `high` (all-failures session), nothing is evicted and the buffer
+    // grows; in practice frequent `low`/`normal` events keep it bounded.
+    const evictAt = buffer.events.findIndex((e) => e.importance !== 'high');
+    if (evictAt !== -1) {
+      buffer.events.splice(evictAt, 1);
+    }
   }
 }
 
+/**
+ * Why a turn failed or was retried — stamped as `detail.reason` on `turn.error`
+ * and `turn.retry` events. Enumerated so the set stays in sync with the README
+ * and call sites can't drift to ad-hoc strings.
+ *
+ * - `exception`              — an uncaught error escaped the tool loop (catch-all).
+ * - `malformed-function-call`— the provider returned an unparseable tool call.
+ * - `empty-response`         — the model returned no content and no tool calls.
+ * - `unknown-tool-limit`     — the model repeatedly called tools that don't exist.
+ * - `max-iterations`         — the tool loop hit its iteration cap.
+ */
+export type TurnFailureReason =
+  | 'exception'
+  | 'malformed-function-call'
+  | 'empty-response'
+  | 'unknown-tool-limit'
+  | 'max-iterations';
+
+/**
+ * Record a turn-ending failure (`turn.error`, importance `high`). The `reason`
+ * is typed so the high-importance triage surface stays consistent; pass any
+ * diagnostic specifics (attempt counts, offending tool names, etc.) in `detail`.
+ */
+export function recordTurnError(
+  key: string,
+  reason: TurnFailureReason,
+  detail?: Record<string, unknown>,
+): void {
+  recordMetaEvent(key, 'turn.error', { reason, ...detail });
+}
+
+/**
+ * Record a recoverable retry *within* a turn (`turn.retry`, importance `normal`)
+ * — e.g. one malformed/empty attempt that will be retried, as distinct from the
+ * final attempt that bails out as a `turn.error`. Include `attempt`/`maxAttempts`
+ * in `detail` so the timeline shows which try this was.
+ */
+export function recordTurnRetry(
+  key: string,
+  reason: TurnFailureReason,
+  detail?: Record<string, unknown>,
+): void {
+  recordMetaEvent(key, 'turn.retry', { reason, ...detail });
+}
+
 /** Returns the meta-event timeline for `key`, or an empty array if none recorded. */
 export function getMetaEvents(key: string): ReadonlyArray<MetaEvent> {
   return registry.get(key)?.events ?? [];
@@ -177,8 +241,8 @@ export const DEBUG_LOG_README: readonly string[] = [
   "kind:'turn' — one LLM call. `systemPrompt` and `toolNames` are what the model saw. A systemPrompt of '<repeated — identical to turn N>' was byte-identical to turn N and de-duplicated; the full prompt is shown whenever it changes (often because a stateful agent advanced), so prompt evolution is visible.",
   "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, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, handoffs, agent/provider changes, interactions), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. '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.error (a turn failed or hit a guardrail — see detail.reason), tool.failed (a tool threw), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (model/provider for the upcoming turns), interaction.requested/resolved (blocking user widgets — explain quiet gaps), context.updated/threshold-crossed (token + cost), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
+  "Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated). 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), 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, plus reason-specific diagnostics: attempts, finishMessage, unknownTools + availableTools, iterations + limit, or name + message for exceptions), tool.failed (a tool threw), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (model/provider for the upcoming turns), interaction.requested/resolved (blocking user widgets — explain quiet gaps), context.updated/threshold-crossed (token + cost), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
   "`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, token usage, session cost), 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.",
   'To debug a failure: find the last turn.error or tool.failed, then read upward for the user message, the turn(s), and the agent/provider/state events that led into it.',
 ];