@genesislcap/ai-assistant 14.493.1-alpha-8ff3328.0 → 14.495.0

package/dist/ai-assistant.api.json

@@ -856,7 +856,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/ai-assistant!AgenticActivityEvents#\"tool-loop-end\":member",
-              "docComment": "/**\n * Fired when the tool loop completes for the current turn and control returns to the user on the **main chat prompt** (i.e. the next free-form user message can now be accepted).\n *\n * Boundary: this is the moment the user regains control of the main chat input. It is **not** fired when a tool handler hands a widget to the user mid-loop (e.g. while a planning widget is awaiting a click) — widget pauses are still inside the loop, the assistant still owns the turn, and the main chat input may be hidden during them. Wait for this event when you need to know that the assistant is fully idle and the user can type freely again.\n *\n * Emitted from the finally block of each `ChatDriver`'s `sendMessage` and `continueFromHistory`, so a multi-agent handoff fires this event once per agent.\n *\n * Distinct from {@link AgenticActivityEvents.'halo-stop'} — the halo event tracks the spinner animation lifecycle (which can flap mid-turn as tool calls resolve), whereas this event is a one-shot per turn boundary. Use this for hooks tied to a turn ending (telemetry flushes, post-turn workspace transitions, deferred state recomputation).\n */\n",
+              "docComment": "/**\n * Fired when the tool loop completes for the current turn and control returns to the user on the **main chat prompt** (i.e. the next free-form user message can now be accepted).\n *\n * Boundary: this is the moment the user regains control of the main chat input. It is **not** fired when a tool handler hands a widget to the user mid-loop (e.g. while a planning widget is awaiting a click) — widget pauses are still inside the loop, the assistant still owns the turn, and the main chat input may be hidden during them. Wait for this event when you need to know that the assistant is fully idle and the user can type freely again.\n *\n * Emitted from the finally block of each `ChatDriver`'s `sendMessage` and `continueFromHistory`, so a multi-agent handoff fires this event once per agent.\n *\n * Distinct from {@link AgenticActivityEvents.'halo-stop'} — the halo event tracks the spinner animation lifecycle (which can flap mid-turn as tool calls resolve), whereas this event is a one-shot per turn boundary. Use this for hooks tied to a turn ending (telemetry flushes, post-turn workspace transitions, deferred state recomputation).\n *\n * The detail carries the turn's outcome (PTC-0): on a failure it is `{ failureReason }` with the typed `TurnFailureReason`; on a clean completion, a user cancel, a driver dispose, and an agent handoff the detail is `undefined` — the historical shape, kept byte-identical so subscribers that only care about the boundary can keep ignoring it. Structured-cloneable so it survives the cross-tab BroadcastChannel hop.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -864,7 +864,16 @@
                 },
                 {
                   "kind": "Content",
-                  "text": "undefined"
+                  "text": "{\n        failureReason?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "TurnFailureReason",
+                  "canonicalReference": "@genesislcap/foundation-ai!TurnFailureReason:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";\n    } | undefined"
                 },
                 {
                   "kind": "Content",
@@ -877,7 +886,7 @@
               "name": "\"tool-loop-end\"",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 2
+                "endIndex": 4
               }
             },
             {

package/dist/ai-assistant.d.ts

@@ -18,6 +18,7 @@ import { InterfaceSymbol } from '@microsoft/fast-foundation';
 import type { Modal } from '@genesislcap/rapid-design-system';
 import { ModelTagAppearance } from '@genesislcap/foundation-ai';
 import type { SubAgentFailureReason } from '@genesislcap/foundation-ai';
+import type { TurnFailureReason } from '@genesislcap/foundation-ai';
 import { ViewTemplate } from '@genesislcap/web-core';
 
 /** Sentinel value used by the segmented control / select to represent "Auto". */
@@ -179,8 +180,16 @@ export declare interface AgenticActivityEvents {
      * spinner animation lifecycle (which can flap mid-turn as tool calls resolve), whereas
      * this event is a one-shot per turn boundary. Use this for hooks tied to a turn ending
      * (telemetry flushes, post-turn workspace transitions, deferred state recomputation).
+     *
+     * The detail carries the turn's outcome (PTC-0): on a failure it is `{ failureReason }`
+     * with the typed `TurnFailureReason`; on a clean completion, a user cancel, a
+     * driver dispose, and an agent handoff the detail is `undefined` — the historical shape,
+     * kept byte-identical so subscribers that only care about the boundary can keep ignoring
+     * it. Structured-cloneable so it survives the cross-tab BroadcastChannel hop.
      */
-    'tool-loop-end': undefined;
+    'tool-loop-end': {
+        failureReason?: TurnFailureReason;
+    } | undefined;
     /**
      * Fired when a tool handler hands a widget to the user mid-loop and parks awaiting it
      * (`requestInteraction`) — the turn is suspended between provider calls, with no request
@@ -1268,6 +1277,23 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * cached history would otherwise gain a stray marker on remount).
      */
     private completeAbortedTurn;
+    /**
+     * Build the `done` loop result, carrying the typed failure reason when the turn
+     * bailed (PTC-0). The discriminant stays `'done'` either way — the same value a
+     * clean turn returns — so consumers matching on `reason === 'done'` are unchanged;
+     * `failureReason` is simply present on a failure and absent on success. Omitted
+     * (rather than set to `undefined`) so a happy-path result stays byte-identical to
+     * the historical `{ reason: 'done' }`.
+     */
+    private turnDone;
+    /** The typed failure reason on a loop result, or `undefined` for a clean turn / handoff. */
+    private static failureReasonOf;
+    /**
+     * Build the `tool-loop-end` event detail for a turn's result. A failure carries a
+     * `{ failureReason }` detail; a clean turn emits `undefined` — the historical shape,
+     * kept byte-identical so subscribers see exactly what they always have.
+     */
+    private static loopEndDetail;
     /**
      * Swap in a new agent's configuration. Called by OrchestratingDriver before
      * each specialist turn so the shared driver runs with the right tools and prompt.
@@ -3698,6 +3724,8 @@ export declare interface ToolTreeNode extends ChatToolDefinition {
     tools?: ToolTreeNode[];
 }
 
+export { TurnFailureReason }
+
 /**
  * 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

package/dist/custom-elements.json

@@ -151,6 +151,14 @@
             "package": "./utils/tool-fold"
           }
         },
+        {
+          "kind": "js",
+          "name": "TurnFailureReason",
+          "declaration": {
+            "name": "TurnFailureReason",
+            "module": "./state/debug-event-log"
+          }
+        },
         {
           "kind": "js",
           "name": "TimelineMessage",
@@ -3971,6 +3979,14 @@
             "module": "src/state/debug-event-log.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "TurnFailureReason",
+          "declaration": {
+            "name": "TurnFailureReason",
+            "module": "src/state/debug-event-log.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "recordTurnError",
@@ -6892,6 +6908,66 @@
               },
               "description": "Finish a turn whose signal aborted. A user cancel adds a subtle \"Stopped.\"\nmarker; a dispose-driven abort stops quietly (the widget is gone and the\ncached history would otherwise gain a stray marker on remount)."
             },
+            {
+              "kind": "method",
+              "name": "turnDone",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "ChatDriverResult"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "failureReason",
+                  "optional": true,
+                  "type": {
+                    "text": "TurnFailureReason"
+                  }
+                }
+              ],
+              "description": "Build the `done` loop result, carrying the typed failure reason when the turn\nbailed (PTC-0). The discriminant stays `'done'` either way — the same value a\nclean turn returns — so consumers matching on `reason === 'done'` are unchanged;\n`failureReason` is simply present on a failure and absent on success. Omitted\n(rather than set to `undefined`) so a happy-path result stays byte-identical to\nthe historical `{ reason: 'done' }`."
+            },
+            {
+              "kind": "method",
+              "name": "failureReasonOf",
+              "privacy": "private",
+              "static": true,
+              "return": {
+                "type": {
+                  "text": "TurnFailureReason | undefined"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "result",
+                  "type": {
+                    "text": "ChatDriverResult"
+                  }
+                }
+              ],
+              "description": "The typed failure reason on a loop result, or `undefined` for a clean turn / handoff."
+            },
+            {
+              "kind": "method",
+              "name": "loopEndDetail",
+              "privacy": "private",
+              "static": true,
+              "return": {
+                "type": {
+                  "text": "{ failureReason: TurnFailureReason } | undefined"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "result",
+                  "type": {
+                    "text": "ChatDriverResult"
+                  }
+                }
+              ],
+              "description": "Build the `tool-loop-end` event detail for a turn's result. A failure carries a\n`{ failureReason }` detail; a clean turn emits `undefined` — the historical shape,\nkept byte-identical so subscribers see exactly what they always have."
+            },
             {
               "kind": "method",
               "name": "applyAgent",

package/dist/dts/channel/ai-activity-channel.d.ts

@@ -1,3 +1,4 @@
+import type { TurnFailureReason } from '@genesislcap/foundation-ai';
 /**
  * Event map for the AI activity bus.
  *
@@ -61,8 +62,16 @@ export interface AgenticActivityEvents {
      * spinner animation lifecycle (which can flap mid-turn as tool calls resolve), whereas
      * this event is a one-shot per turn boundary. Use this for hooks tied to a turn ending
      * (telemetry flushes, post-turn workspace transitions, deferred state recomputation).
+     *
+     * The detail carries the turn's outcome (PTC-0): on a failure it is `{ failureReason }`
+     * with the typed `TurnFailureReason`; on a clean completion, a user cancel, a
+     * driver dispose, and an agent handoff the detail is `undefined` — the historical shape,
+     * kept byte-identical so subscribers that only care about the boundary can keep ignoring
+     * it. Structured-cloneable so it survives the cross-tab BroadcastChannel hop.
      */
-    'tool-loop-end': undefined;
+    'tool-loop-end': {
+        failureReason?: TurnFailureReason;
+    } | undefined;
     /**
      * Fired when a tool handler hands a widget to the user mid-loop and parks awaiting it
      * (`requestInteraction`) — the turn is suspended between provider calls, with no request

package/dist/dts/channel/ai-activity-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-activity-channel.d.ts","sourceRoot":"","sources":["../../../src/channel/ai-activity-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,qBAAqB;IACpC,2FAA2F;IAC3F,YAAY,EAAE;QAAE,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACtC,iFAAiF;IACjF,WAAW,EAAE,SAAS,CAAC;IACvB,mJAAmJ;IACnJ,aAAa,EAAE,SAAS,CAAC;IACzB,wJAAwJ;IACxJ,YAAY,EAAE,SAAS,CAAC;IACxB;;;;;;;;;;;;;;;;;;OAkBG;IACH,iBAAiB,EAAE,SAAS,CAAC;IAC7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,eAAe,EAAE,SAAS,CAAC;IAC3B;;;;;;;;;;;OAWG;IACH,uBAAuB,EAAE,SAAS,CAAC;IACnC;;;;;OAKG;IACH,sBAAsB,EAAE,SAAS,CAAC;CACnC"}
+{"version":3,"file":"ai-activity-channel.d.ts","sourceRoot":"","sources":["../../../src/channel/ai-activity-channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,qBAAqB;IACpC,2FAA2F;IAC3F,YAAY,EAAE;QAAE,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACtC,iFAAiF;IACjF,WAAW,EAAE,SAAS,CAAC;IACvB,mJAAmJ;IACnJ,aAAa,EAAE,SAAS,CAAC;IACzB,wJAAwJ;IACxJ,YAAY,EAAE,SAAS,CAAC;IACxB;;;;;;;;;;;;;;;;;;OAkBG;IACH,iBAAiB,EAAE,SAAS,CAAC;IAC7B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,eAAe,EAAE;QAAE,aAAa,CAAC,EAAE,iBAAiB,CAAA;KAAE,GAAG,SAAS,CAAC;IACnE;;;;;;;;;;;OAWG;IACH,uBAAuB,EAAE,SAAS,CAAC;IACnC;;;;;OAKG;IACH,sBAAsB,EAAE,SAAS,CAAC;CACnC"}

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

@@ -398,6 +398,23 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * cached history would otherwise gain a stray marker on remount).
      */
     private completeAbortedTurn;
+    /**
+     * Build the `done` loop result, carrying the typed failure reason when the turn
+     * bailed (PTC-0). The discriminant stays `'done'` either way — the same value a
+     * clean turn returns — so consumers matching on `reason === 'done'` are unchanged;
+     * `failureReason` is simply present on a failure and absent on success. Omitted
+     * (rather than set to `undefined`) so a happy-path result stays byte-identical to
+     * the historical `{ reason: 'done' }`.
+     */
+    private turnDone;
+    /** The typed failure reason on a loop result, or `undefined` for a clean turn / handoff. */
+    private static failureReasonOf;
+    /**
+     * Build the `tool-loop-end` event detail for a turn's result. A failure carries a
+     * `{ failureReason }` detail; a clean turn emits `undefined` — the historical shape,
+     * kept byte-identical so subscribers see exactly what they always have.
+     */
+    private static loopEndDetail;
     /**
      * Swap in a new agent's configuration. Called by OrchestratingDriver before
      * each specialist turn so the shared driver runs with the right tools and prompt.

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":"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"}
+{"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/components/chat-driver/chat-driver.test.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat-driver.test.d.ts","sourceRoot":"","sources":["../../../../src/components/chat-driver/chat-driver.test.ts"],"names":[],"mappings":"AAsBA,OAAO,uBAAuB,CAAC"}
+{"version":3,"file":"chat-driver.test.d.ts","sourceRoot":"","sources":["../../../../src/components/chat-driver/chat-driver.test.ts"],"names":[],"mappings":"AA4BA,OAAO,uBAAuB,CAAC"}

package/dist/dts/index.d.ts

@@ -16,6 +16,7 @@ export * from './state/persistence';
 export * from './provider/ai-provider-switcher';
 export * from './provider/assistant-app-settings';
 export * from './utils/tool-fold';
+export type { TurnFailureReason } from './state/debug-event-log';
 export type { TimelineMessage } from './utils/flatten-sub-agent-messages';
 export type { CostSessionModelEntry, CostSessionRecord } from './utils/cost-session-history';
 export type { ModelTagAppearance } from '@genesislcap/foundation-ai';

package/dist/dts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,YAAY,EAAE,+BAA+B,EAAE,MAAM,gEAAgE,CAAC;AACtH,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,mBAAmB,CAAC;AAClC,YAAY,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,YAAY,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAC7F,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC9E,YAAY,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,YAAY,EAAE,+BAA+B,EAAE,MAAM,gEAAgE,CAAC;AACtH,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,mBAAmB,CAAC;AAClC,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,YAAY,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,YAAY,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAC7F,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC9E,YAAY,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC"}

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

@@ -23,6 +23,7 @@
  *
  * @internal
  */
+import type { TurnFailureReason } from '@genesislcap/foundation-ai';
 /**
  * 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).
@@ -68,19 +69,14 @@ export interface MetaEvent {
 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 it couldn't dispatch,
- *                              whether hallucinated or stale (real earlier, retired now).
- * - `max-iterations`         — the tool loop hit its iteration cap.
- * - `response-truncated`     — a turn stopped at the provider's output-token cap with an
- *                              incomplete tool call; deterministic, so it bails without retry.
+ * and `turn.retry` events, and (since PTC-0) surfaced at the driver's loop
+ * boundary via {@link ChatDriverResult.failureReason}. Re-exported from
+ * `@genesislcap/foundation-ai` — where it lives alongside `ChatDriverResult` so
+ * the boundary field and this log surface can never drift apart — under its
+ * historical name so existing importers are unaffected. Enumerated so the set
+ * stays in sync with the README and call sites can't drift to ad-hoc strings.
  */
-export type TurnFailureReason = 'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated';
+export type { TurnFailureReason };
 /**
  * Record a turn-ending failure (`turn.error`, importance `high`). The `reason`
  * is typed so the high-importance triage surface stays consistent; pass any

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;;;;;;;;;;;;;;;;;;;;;;;;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,GACb,iBAAiB,GACjB,kBAAkB,GAClB,oBAAoB,GACpB,iBAAiB,GAEjB,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,mBAAmB,GAEnB,uBAAuB,GACvB,sBAAsB,GAEtB,iBAAiB,GACjB,2BAA2B,GAC3B,mBAAmB,GACnB,mBAAmB,GAEnB,eAAe,GACf,kBAAkB,GAClB,kBAAkB,GAClB,oBAAoB,GAEpB,iBAAiB,GACjB,kBAAkB,GAClB,yBAAyB,GACzB,qBAAqB,GACrB,mBAAmB,GACnB,wBAAwB,GACxB,2BAA2B,GAC3B,sBAAsB,GACtB,4BAA4B,CAAC;AAEjC;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE5D;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,aAAa,EAAE,mBAAmB,CA2C5E,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;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,yBAAyB,GACzB,gBAAgB,GAChB,oBAAoB,GACpB,gBAAgB,GAChB,oBAAoB,CAAC;AAEzB;;;;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;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI,CA0BrF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAc7C,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,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;;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,GACb,iBAAiB,GACjB,kBAAkB,GAClB,oBAAoB,GACpB,iBAAiB,GAEjB,eAAe,GACf,cAAc,GACd,gBAAgB,GAChB,mBAAmB,GAEnB,uBAAuB,GACvB,sBAAsB,GAEtB,iBAAiB,GACjB,2BAA2B,GAC3B,mBAAmB,GACnB,mBAAmB,GAEnB,eAAe,GACf,kBAAkB,GAClB,kBAAkB,GAClB,oBAAoB,GAEpB,iBAAiB,GACjB,kBAAkB,GAClB,yBAAyB,GACzB,qBAAqB,GACrB,mBAAmB,GACnB,wBAAwB,GACxB,2BAA2B,GAC3B,sBAAsB,GACtB,4BAA4B,CAAC;AAEjC;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAE5D;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,aAAa,EAAE,mBAAmB,CA2C5E,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;;;;;;;;GAQG;AACH,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC;;;;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;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI,CA0BrF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE9C;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAc7C,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

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

@@ -337,6 +337,30 @@ export class ChatDriver extends EventTarget {
         }
         return { reason: 'done' };
     }
+    /**
+     * Build the `done` loop result, carrying the typed failure reason when the turn
+     * bailed (PTC-0). The discriminant stays `'done'` either way — the same value a
+     * clean turn returns — so consumers matching on `reason === 'done'` are unchanged;
+     * `failureReason` is simply present on a failure and absent on success. Omitted
+     * (rather than set to `undefined`) so a happy-path result stays byte-identical to
+     * the historical `{ reason: 'done' }`.
+     */
+    turnDone(failureReason) {
+        return failureReason ? { reason: 'done', failureReason } : { reason: 'done' };
+    }
+    /** The typed failure reason on a loop result, or `undefined` for a clean turn / handoff. */
+    static failureReasonOf(result) {
+        return result.reason === 'done' ? result.failureReason : undefined;
+    }
+    /**
+     * Build the `tool-loop-end` event detail for a turn's result. A failure carries a
+     * `{ failureReason }` detail; a clean turn emits `undefined` — the historical shape,
+     * kept byte-identical so subscribers see exactly what they always have.
+     */
+    static loopEndDetail(result) {
+        const failureReason = ChatDriver.failureReasonOf(result);
+        return failureReason ? { failureReason } : undefined;
+    }
     /**
      * Swap in a new agent's configuration. Called by OrchestratingDriver before
      * each specialist turn so the shared driver runs with the right tools and prompt.
@@ -1062,8 +1086,11 @@ export class ChatDriver extends EventTarget {
                 agent: this.activeAgentName,
             });
             agenticActivityBus.publish('tool-loop-start', undefined);
+            // Captured so the `finally` can carry the turn's outcome onto `tool-loop-end`.
+            let result = { reason: 'done' };
             try {
-                return yield this.runToolLoop(userInput, attachments);
+                result = yield this.runToolLoop(userInput, attachments);
+                return result;
             }
             catch (e) {
                 logger.error('ChatDriver error:', e);
@@ -1078,7 +1105,8 @@ export class ChatDriver extends EventTarget {
                     role: 'assistant',
                     content: 'Sorry, something went wrong on my end. Please try again in a moment.',
                 });
-                return { reason: 'done' };
+                result = this.turnDone('exception');
+                return result;
             }
             finally {
                 recordMetaEvent(this.sessionKey, 'turn.end', {
@@ -1088,7 +1116,7 @@ export class ChatDriver extends EventTarget {
                 });
                 this.busy = false;
                 this.endTurn();
-                agenticActivityBus.publish('tool-loop-end', undefined);
+                agenticActivityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
             }
         });
     }
@@ -1373,8 +1401,11 @@ export class ChatDriver extends EventTarget {
                 agent: this.activeAgentName,
             });
             agenticActivityBus.publish('tool-loop-start', undefined);
+            // Captured so the `finally` can carry the turn's outcome onto `tool-loop-end`.
+            let result = { reason: 'done' };
             try {
-                return yield this.runToolLoop('', undefined, transientPrimer);
+                result = yield this.runToolLoop('', undefined, transientPrimer);
+                return result;
             }
             catch (e) {
                 logger.error('ChatDriver error:', e);
@@ -1389,7 +1420,8 @@ export class ChatDriver extends EventTarget {
                     role: 'assistant',
                     content: 'Sorry, something went wrong on my end. Please try again in a moment.',
                 });
-                return { reason: 'done' };
+                result = this.turnDone('exception');
+                return result;
             }
             finally {
                 recordMetaEvent(this.sessionKey, 'turn.end', {
@@ -1399,7 +1431,7 @@ export class ChatDriver extends EventTarget {
                 });
                 this.busy = false;
                 this.endTurn();
-                agenticActivityBus.publish('tool-loop-end', undefined);
+                agenticActivityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
             }
         });
     }
@@ -1784,7 +1816,7 @@ export class ChatDriver extends EventTarget {
                                 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' };
+                        return this.turnDone('malformed-function-call');
                     }
                     // The response was truncated at the provider's output-token cap while it
                     // still carried a tool call — its arguments are incomplete and unusable.
@@ -1813,7 +1845,7 @@ export class ChatDriver extends EventTarget {
                                 content: 'My response was cut off because a single step reached the model output limit. This usually means one step tried to produce too much at once — try breaking your request into smaller steps.',
                             });
                         }
-                        return { reason: 'done' };
+                        return this.turnDone('response-truncated');
                     }
                     // A request timeout from the transport (tagged `TimeoutError`) is not a
                     // bug on our end — surface it distinctly instead of letting it fall
@@ -1839,7 +1871,9 @@ export class ChatDriver extends EventTarget {
                                 content: 'The request timed out. You can ask me to try again, or break this into a smaller step.',
                             });
                         }
-                        return { reason: 'done' };
+                        // Recorded as `exception` above (there is no separate `timeout` member of
+                        // TurnFailureReason for the main turn); surface the same reason here.
+                        return this.turnDone('exception');
                     }
                     // The request was aborted: either a user cancel (turnController) or a
                     // driver dispose (lifecycleController, chained into the turn). A user
@@ -1899,7 +1933,7 @@ export class ChatDriver extends EventTarget {
                             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' };
+                    return this.turnDone('empty-response');
                 }
                 else {
                     // Split one model response into separate, individually-toggleable messages so each has its
@@ -2213,7 +2247,7 @@ export class ChatDriver extends EventTarget {
                             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' };
+                    return this.turnDone('unknown-tool-limit');
                 }
                 const firstContinuation = systemCalls[0];
                 if (firstContinuation) {
@@ -2223,9 +2257,12 @@ export class ChatDriver extends EventTarget {
                 // Sub-agent early exit — checked here so the exit point mirrors the
                 // system-call pattern above. Set by completeSubAgent() in a tool handler.
                 if (this.subAgentCompletion) {
-                    return { reason: 'done' };
+                    return this.turnDone();
                 }
             }
+            // The loop fell through: either it hit the iteration cap (a failure) or it
+            // broke on a clean final answer (success). Only the former carries a reason.
+            let failureReason;
             if (iterations >= this.maxToolIterations) {
                 logger.warn('ChatDriver: reached max tool iterations, stopping');
                 recordTurnError(this.sessionKey, 'max-iterations', {
@@ -2244,8 +2281,9 @@ export class ChatDriver extends EventTarget {
                         content: "I've reached my limit for this response. You can ask me to continue and I'll pick up where I left off.",
                     });
                 }
+                failureReason = 'max-iterations';
             }
-            return { reason: 'done' };
+            return this.turnDone(failureReason);
         });
     }
     appendToHistory(message) {

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

@@ -1,5 +1,5 @@
 import { __awaiter } from "tslib";
-import { isChatToolCallUnknown } from '@genesislcap/foundation-ai';
+import { isChatToolCallUnknown, MalformedFunctionCallError, ResponseTruncatedError, } from '@genesislcap/foundation-ai';
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
 import { agenticActivityBus } from '../../channel/ai-activity-bus';
 import { clearMetaEventRegistry, getMetaEvents } from '../../state/debug-event-log';
@@ -1621,3 +1621,135 @@ condense('phaseEnd: collapses at endPhase() while the agent keeps running', () =
     assert.is((_a = events[0].detail) === null || _a === void 0 ? void 0 : _a.trigger, 'phaseEnd');
 }));
 condense.run();
+// ---------------------------------------------------------------------------
+// turn-outcome surfacing (PTC-0) — the typed failure reason must reach BOTH
+// the loop-boundary result (`ChatDriverResult.failureReason`) and the
+// `tool-loop-end` activity-bus event detail. Historically every exit flattened
+// to `{ reason: 'done' }` and the bus detail was `undefined`; these lock the
+// two seams together, one per `TurnFailureReason`, plus a happy-path compat
+// check that the legacy shape is byte-unchanged.
+// ---------------------------------------------------------------------------
+const outcome = createLogicSuite('ChatDriver turn-outcome surfacing');
+outcome.after(() => {
+    agenticActivityBus.close();
+});
+/**
+ * Subscribe to `tool-loop-end` and expose the most recent detail seen. `fired()` reports
+ * whether the event was seen at all — distinct from `detail()`, which is `undefined` both
+ * when no event fired and when a clean turn fired with the historical `undefined` detail.
+ */
+const captureLoopEnd = () => {
+    let last;
+    let seen = false;
+    const stop = agenticActivityBus.subscribe('tool-loop-end', (d) => {
+        last = d;
+        seen = true;
+    });
+    return { detail: () => (seen ? last : undefined), fired: () => seen, stop };
+};
+/** A ChatDriver with an explicit (small) tool-iteration cap. */
+const makeCappedDriver = (config, provider, maxIterations, sessionKey = '') => {
+    const driver = new ChatDriver(makeRegistry(provider), {}, [], undefined, undefined, maxIterations, 5, undefined, sessionKey);
+    driver.applyAgent(config);
+    return driver;
+};
+/**
+ * Assert that a turn driven by `provider` surfaces `expected` at BOTH seams.
+ * `driverFor` lets the max-iterations case swap in a low cap.
+ */
+const assertSurfacesReason = (label_1, provider_1, expected_1, ...args_1) => __awaiter(void 0, [label_1, provider_1, expected_1, ...args_1], void 0, function* (label, provider, expected, driverFor = (c, p, k) => makeDriver(c, p, k)) {
+    var _a;
+    clearMetaEventRegistry();
+    const sessionKey = `outcome-${label}`;
+    const config = agent({
+        name: 'Static',
+        toolDefinitions: [def('noop')],
+        toolHandlers: { noop: () => __awaiter(void 0, void 0, void 0, function* () { return 'ok'; }) },
+    });
+    const driver = driverFor(config, provider, sessionKey);
+    const cap = captureLoopEnd();
+    const result = yield driver.sendMessage('go');
+    // Seam 1 — the loop-boundary result. Discriminant stays 'done' (compat).
+    assert.is(result.reason, 'done', `[${label}] discriminant stays 'done'`);
+    assert.is(result.reason === 'done' ? result.failureReason : undefined, expected, `[${label}] result.failureReason surfaces the typed reason`);
+    // Seam 2 — the activity-bus tool-loop-end detail.
+    assert.ok(cap.detail(), `[${label}] a tool-loop-end event fired`);
+    assert.is(cap.detail().failureReason, expected, `[${label}] the bus detail carries the same reason`);
+    // Consistency: the debug-log turn.error records the same taxonomy.
+    const err = getMetaEvents(sessionKey).find((e) => e.type === 'turn.error');
+    assert.ok(err, `[${label}] a turn.error is recorded`);
+    assert.is((_a = err.detail) === null || _a === void 0 ? void 0 : _a.reason, expected, `[${label}] the debug-log reason matches`);
+    cap.stop();
+});
+/** A provider that returns a MALFORMED_FUNCTION_CALL on every call. */
+const malformedProvider = () => ({
+    chat: () => __awaiter(void 0, void 0, void 0, function* () {
+        throw new MalformedFunctionCallError('bad call');
+    }),
+});
+/** A provider that returns an empty response on every call. */
+const emptyProvider = () => ({
+    chat: () => __awaiter(void 0, void 0, void 0, function* () { return ({ role: 'assistant', content: '' }); }),
+});
+/** A provider that throws a ResponseTruncatedError (deterministic, no retry). */
+const truncatedProvider = () => ({
+    chat: () => __awaiter(void 0, void 0, void 0, function* () {
+        throw new ResponseTruncatedError('test-model', 1024, 1024, ['noop']);
+    }),
+});
+/** A provider that throws a generic error (the sendMessage catch-all → 'exception'). */
+const throwingProvider = () => ({
+    chat: () => __awaiter(void 0, void 0, void 0, function* () {
+        throw new Error('boom');
+    }),
+});
+/** A provider that never stops calling a valid tool (drives the iteration cap). */
+const neverStopsProvider = () => {
+    let n = 0;
+    return {
+        chat: () => __awaiter(void 0, void 0, void 0, function* () {
+            const id = `noop-${n}`;
+            n += 1;
+            return { role: 'assistant', content: '', toolCalls: [{ id, name: 'noop', args: {} }] };
+        }),
+    };
+};
+/** A provider that keeps calling a tool with no handler (hallucinated → limit). */
+const hallucinatedProvider = () => scriptedProvider(Array.from({ length: 6 }, (_u, i) => callsTool('ghost', `ghost-${i}`)));
+outcome('malformed-function-call surfaces at both seams', () => __awaiter(void 0, void 0, void 0, function* () {
+    yield assertSurfacesReason('malformed', malformedProvider(), 'malformed-function-call');
+}));
+outcome('empty-response surfaces at both seams', () => __awaiter(void 0, void 0, void 0, function* () {
+    yield assertSurfacesReason('empty', emptyProvider(), 'empty-response');
+}));
+outcome('response-truncated surfaces at both seams', () => __awaiter(void 0, void 0, void 0, function* () {
+    yield assertSurfacesReason('truncated', truncatedProvider(), 'response-truncated');
+}));
+outcome('exception surfaces at both seams', () => __awaiter(void 0, void 0, void 0, function* () {
+    yield assertSurfacesReason('exception', throwingProvider(), 'exception');
+}));
+outcome('unknown-tool-limit surfaces at both seams', () => __awaiter(void 0, void 0, void 0, function* () {
+    yield assertSurfacesReason('unknown-tool', hallucinatedProvider(), 'unknown-tool-limit');
+}));
+outcome('max-iterations surfaces at both seams', () => __awaiter(void 0, void 0, void 0, function* () {
+    yield assertSurfacesReason('max-iter', neverStopsProvider(), 'max-iterations', (c, p, k) => makeCappedDriver(c, p, 2, k));
+}));
+outcome('a clean turn leaves the legacy shape byte-unchanged (no failureReason)', () => __awaiter(void 0, void 0, void 0, function* () {
+    clearMetaEventRegistry();
+    const config = agent({ name: 'Static' });
+    // Plain-text reply ends the turn cleanly on the first call.
+    const driver = makeDriver(config, scriptedProvider([{ role: 'assistant', content: 'hi' }]), 'outcome-ok');
+    const cap = captureLoopEnd();
+    const result = yield driver.sendMessage('go');
+    // The result is exactly `{ reason: 'done' }` — no `failureReason` key added.
+    assert.equal(result, { reason: 'done' }, 'happy-path result is the historical shape');
+    assert.not.ok('failureReason' in result, 'no failureReason key is present on a clean turn');
+    // The bus event still fires, and its detail is the historical `undefined` — a clean
+    // turn emits no detail object at all (byte-shape compat), not `{ failureReason: undefined }`.
+    assert.ok(cap.fired(), 'a tool-loop-end event fired');
+    assert.is(cap.detail(), undefined, 'a clean turn emits the historical undefined detail');
+    // And no turn.error was recorded.
+    assert.not.ok(getMetaEvents('outcome-ok').some((e) => e.type === 'turn.error'), 'a clean turn records no turn.error');
+    cap.stop();
+}));
+outcome.run();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/ai-assistant",
   "description": "Genesis AI Assistant micro-frontend",
-  "version": "14.493.1-alpha-8ff3328.0",
+  "version": "14.495.0",
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
   "types": "dist/ai-assistant.d.ts",
@@ -64,25 +64,25 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.493.1-alpha-8ff3328.0",
-    "@genesislcap/genx": "14.493.1-alpha-8ff3328.0",
-    "@genesislcap/rollup-builder": "14.493.1-alpha-8ff3328.0",
-    "@genesislcap/ts-builder": "14.493.1-alpha-8ff3328.0",
-    "@genesislcap/uvu-playwright-builder": "14.493.1-alpha-8ff3328.0",
-    "@genesislcap/vite-builder": "14.493.1-alpha-8ff3328.0",
-    "@genesislcap/webpack-builder": "14.493.1-alpha-8ff3328.0",
+    "@genesislcap/foundation-testing": "14.495.0",
+    "@genesislcap/genx": "14.495.0",
+    "@genesislcap/rollup-builder": "14.495.0",
+    "@genesislcap/ts-builder": "14.495.0",
+    "@genesislcap/uvu-playwright-builder": "14.495.0",
+    "@genesislcap/vite-builder": "14.495.0",
+    "@genesislcap/webpack-builder": "14.495.0",
     "@types/dompurify": "^3.0.5",
     "@types/marked": "^5.0.2"
   },
   "dependencies": {
-    "@genesislcap/foundation-ai": "14.493.1-alpha-8ff3328.0",
-    "@genesislcap/foundation-logger": "14.493.1-alpha-8ff3328.0",
-    "@genesislcap/foundation-notifications": "14.493.1-alpha-8ff3328.0",
-    "@genesislcap/foundation-redux": "14.493.1-alpha-8ff3328.0",
-    "@genesislcap/foundation-ui": "14.493.1-alpha-8ff3328.0",
-    "@genesislcap/foundation-utils": "14.493.1-alpha-8ff3328.0",
-    "@genesislcap/rapid-design-system": "14.493.1-alpha-8ff3328.0",
-    "@genesislcap/web-core": "14.493.1-alpha-8ff3328.0",
+    "@genesislcap/foundation-ai": "14.495.0",
+    "@genesislcap/foundation-logger": "14.495.0",
+    "@genesislcap/foundation-notifications": "14.495.0",
+    "@genesislcap/foundation-redux": "14.495.0",
+    "@genesislcap/foundation-ui": "14.495.0",
+    "@genesislcap/foundation-utils": "14.495.0",
+    "@genesislcap/rapid-design-system": "14.495.0",
+    "@genesislcap/web-core": "14.495.0",
     "dompurify": "^3.3.1",
     "marked": "^17.0.3"
   },
@@ -95,5 +95,5 @@
     "access": "public"
   },
   "customElements": "dist/custom-elements.json",
-  "gitHead": "8c565dfbaf36c06f5a28278da59043c5453c564a"
+  "gitHead": "24d26a75271717d40c0b6168b983bd8536a3db7f"
 }

package/src/channel/ai-activity-channel.ts

@@ -1,3 +1,5 @@
+import type { TurnFailureReason } from '@genesislcap/foundation-ai';
+
 /**
  * Event map for the AI activity bus.
  *
@@ -59,8 +61,14 @@ export interface AgenticActivityEvents {
    * spinner animation lifecycle (which can flap mid-turn as tool calls resolve), whereas
    * this event is a one-shot per turn boundary. Use this for hooks tied to a turn ending
    * (telemetry flushes, post-turn workspace transitions, deferred state recomputation).
+   *
+   * The detail carries the turn's outcome (PTC-0): on a failure it is `{ failureReason }`
+   * with the typed `TurnFailureReason`; on a clean completion, a user cancel, a
+   * driver dispose, and an agent handoff the detail is `undefined` — the historical shape,
+   * kept byte-identical so subscribers that only care about the boundary can keep ignoring
+   * it. Structured-cloneable so it survives the cross-tab BroadcastChannel hop.
    */
-  'tool-loop-end': undefined;
+  'tool-loop-end': { failureReason?: TurnFailureReason } | undefined;
   /**
    * Fired when a tool handler hands a widget to the user mid-loop and parks awaiting it
    * (`requestInteraction`) — the turn is suspended between provider calls, with no request

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

@@ -2,14 +2,20 @@ import type {
   AIProvider,
   AIProviderRegistry,
   CachePolicy,
+  ChatDriverResult,
   ChatMessage,
   ChatRequestOptions,
   ChatToolCall,
   ChatToolChoice,
   ChatToolDefinition,
   InteractionResult,
+  TurnFailureReason,
+} from '@genesislcap/foundation-ai';
+import {
+  isChatToolCallUnknown,
+  MalformedFunctionCallError,
+  ResponseTruncatedError,
 } from '@genesislcap/foundation-ai';
-import { isChatToolCallUnknown } from '@genesislcap/foundation-ai';
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
 import { agenticActivityBus } from '../../channel/ai-activity-bus';
 import type { AgentConfig } from '../../config/config';
@@ -2175,3 +2181,210 @@ condense('phaseEnd: collapses at endPhase() while the agent keeps running', asyn
 });
 
 condense.run();
+
+// ---------------------------------------------------------------------------
+// turn-outcome surfacing (PTC-0) — the typed failure reason must reach BOTH
+// the loop-boundary result (`ChatDriverResult.failureReason`) and the
+// `tool-loop-end` activity-bus event detail. Historically every exit flattened
+// to `{ reason: 'done' }` and the bus detail was `undefined`; these lock the
+// two seams together, one per `TurnFailureReason`, plus a happy-path compat
+// check that the legacy shape is byte-unchanged.
+// ---------------------------------------------------------------------------
+
+const outcome = createLogicSuite('ChatDriver turn-outcome surfacing');
+
+outcome.after(() => {
+  agenticActivityBus.close();
+});
+
+/**
+ * Subscribe to `tool-loop-end` and expose the most recent detail seen. `fired()` reports
+ * whether the event was seen at all — distinct from `detail()`, which is `undefined` both
+ * when no event fired and when a clean turn fired with the historical `undefined` detail.
+ */
+const captureLoopEnd = (): {
+  detail: () => { failureReason?: TurnFailureReason } | undefined;
+  fired: () => boolean;
+  stop: () => void;
+} => {
+  let last: { failureReason?: TurnFailureReason } | undefined;
+  let seen = false;
+  const stop = agenticActivityBus.subscribe('tool-loop-end', (d) => {
+    last = d;
+    seen = true;
+  });
+  return { detail: () => (seen ? last : undefined), fired: () => seen, stop };
+};
+
+/** A ChatDriver with an explicit (small) tool-iteration cap. */
+const makeCappedDriver = (
+  config: AgentConfig,
+  provider: AIProvider,
+  maxIterations: number,
+  sessionKey = '',
+): ChatDriver => {
+  const driver = new ChatDriver(
+    makeRegistry(provider),
+    {},
+    [],
+    undefined,
+    undefined,
+    maxIterations,
+    5,
+    undefined,
+    sessionKey,
+  );
+  driver.applyAgent(config);
+  return driver;
+};
+
+/**
+ * Assert that a turn driven by `provider` surfaces `expected` at BOTH seams.
+ * `driverFor` lets the max-iterations case swap in a low cap.
+ */
+const assertSurfacesReason = async (
+  label: string,
+  provider: AIProvider,
+  expected: TurnFailureReason,
+  driverFor: (config: AgentConfig, provider: AIProvider, sessionKey: string) => ChatDriver = (
+    c,
+    p,
+    k,
+  ) => makeDriver(c, p, k),
+): Promise<void> => {
+  clearMetaEventRegistry();
+  const sessionKey = `outcome-${label}`;
+  const config = agent({
+    name: 'Static',
+    toolDefinitions: [def('noop')],
+    toolHandlers: { noop: async () => 'ok' },
+  });
+  const driver = driverFor(config, provider, sessionKey);
+  const cap = captureLoopEnd();
+
+  const result: ChatDriverResult = await driver.sendMessage('go');
+
+  // Seam 1 — the loop-boundary result. Discriminant stays 'done' (compat).
+  assert.is(result.reason, 'done', `[${label}] discriminant stays 'done'`);
+  assert.is(
+    result.reason === 'done' ? result.failureReason : undefined,
+    expected,
+    `[${label}] result.failureReason surfaces the typed reason`,
+  );
+
+  // Seam 2 — the activity-bus tool-loop-end detail.
+  assert.ok(cap.detail(), `[${label}] a tool-loop-end event fired`);
+  assert.is(
+    cap.detail()!.failureReason,
+    expected,
+    `[${label}] the bus detail carries the same reason`,
+  );
+
+  // Consistency: the debug-log turn.error records the same taxonomy.
+  const err = getMetaEvents(sessionKey).find((e) => e.type === 'turn.error');
+  assert.ok(err, `[${label}] a turn.error is recorded`);
+  assert.is(err!.detail?.reason, expected, `[${label}] the debug-log reason matches`);
+
+  cap.stop();
+};
+
+/** A provider that returns a MALFORMED_FUNCTION_CALL on every call. */
+const malformedProvider = (): AIProvider => ({
+  chat: async (): Promise<ChatMessage> => {
+    throw new MalformedFunctionCallError('bad call');
+  },
+});
+
+/** A provider that returns an empty response on every call. */
+const emptyProvider = (): AIProvider => ({
+  chat: async (): Promise<ChatMessage> => ({ role: 'assistant', content: '' }),
+});
+
+/** A provider that throws a ResponseTruncatedError (deterministic, no retry). */
+const truncatedProvider = (): AIProvider => ({
+  chat: async (): Promise<ChatMessage> => {
+    throw new ResponseTruncatedError('test-model', 1024, 1024, ['noop']);
+  },
+});
+
+/** A provider that throws a generic error (the sendMessage catch-all → 'exception'). */
+const throwingProvider = (): AIProvider => ({
+  chat: async (): Promise<ChatMessage> => {
+    throw new Error('boom');
+  },
+});
+
+/** A provider that never stops calling a valid tool (drives the iteration cap). */
+const neverStopsProvider = (): AIProvider => {
+  let n = 0;
+  return {
+    chat: async (): Promise<ChatMessage> => {
+      const id = `noop-${n}`;
+      n += 1;
+      return { role: 'assistant', content: '', toolCalls: [{ id, name: 'noop', args: {} }] };
+    },
+  };
+};
+
+/** A provider that keeps calling a tool with no handler (hallucinated → limit). */
+const hallucinatedProvider = (): AIProvider =>
+  scriptedProvider(Array.from({ length: 6 }, (_u, i) => callsTool('ghost', `ghost-${i}`)));
+
+outcome('malformed-function-call surfaces at both seams', async () => {
+  await assertSurfacesReason('malformed', malformedProvider(), 'malformed-function-call');
+});
+
+outcome('empty-response surfaces at both seams', async () => {
+  await assertSurfacesReason('empty', emptyProvider(), 'empty-response');
+});
+
+outcome('response-truncated surfaces at both seams', async () => {
+  await assertSurfacesReason('truncated', truncatedProvider(), 'response-truncated');
+});
+
+outcome('exception surfaces at both seams', async () => {
+  await assertSurfacesReason('exception', throwingProvider(), 'exception');
+});
+
+outcome('unknown-tool-limit surfaces at both seams', async () => {
+  await assertSurfacesReason('unknown-tool', hallucinatedProvider(), 'unknown-tool-limit');
+});
+
+outcome('max-iterations surfaces at both seams', async () => {
+  await assertSurfacesReason('max-iter', neverStopsProvider(), 'max-iterations', (c, p, k) =>
+    makeCappedDriver(c, p, 2, k),
+  );
+});
+
+outcome('a clean turn leaves the legacy shape byte-unchanged (no failureReason)', async () => {
+  clearMetaEventRegistry();
+  const config = agent({ name: 'Static' });
+  // Plain-text reply ends the turn cleanly on the first call.
+  const driver = makeDriver(
+    config,
+    scriptedProvider([{ role: 'assistant', content: 'hi' }]),
+    'outcome-ok',
+  );
+  const cap = captureLoopEnd();
+
+  const result: ChatDriverResult = await driver.sendMessage('go');
+
+  // The result is exactly `{ reason: 'done' }` — no `failureReason` key added.
+  assert.equal(result, { reason: 'done' }, 'happy-path result is the historical shape');
+  assert.not.ok('failureReason' in result, 'no failureReason key is present on a clean turn');
+
+  // The bus event still fires, and its detail is the historical `undefined` — a clean
+  // turn emits no detail object at all (byte-shape compat), not `{ failureReason: undefined }`.
+  assert.ok(cap.fired(), 'a tool-loop-end event fired');
+  assert.is(cap.detail(), undefined, 'a clean turn emits the historical undefined detail');
+
+  // And no turn.error was recorded.
+  assert.not.ok(
+    getMetaEvents('outcome-ok').some((e) => e.type === 'turn.error'),
+    'a clean turn records no turn.error',
+  );
+
+  cap.stop();
+});
+
+outcome.run();

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

@@ -17,6 +17,7 @@ import type {
   InteractionResult,
   SubAgentFailureReason,
   SubAgentRequestOptions,
+  TurnFailureReason,
 } from '@genesislcap/foundation-ai';
 import {
   isObservableAIProviderRegistry,
@@ -631,6 +632,35 @@ export class ChatDriver extends EventTarget implements AiDriver {
     return { reason: 'done' };
   }
 
+  /**
+   * Build the `done` loop result, carrying the typed failure reason when the turn
+   * bailed (PTC-0). The discriminant stays `'done'` either way — the same value a
+   * clean turn returns — so consumers matching on `reason === 'done'` are unchanged;
+   * `failureReason` is simply present on a failure and absent on success. Omitted
+   * (rather than set to `undefined`) so a happy-path result stays byte-identical to
+   * the historical `{ reason: 'done' }`.
+   */
+  private turnDone(failureReason?: TurnFailureReason): ChatDriverResult {
+    return failureReason ? { reason: 'done', failureReason } : { reason: 'done' };
+  }
+
+  /** The typed failure reason on a loop result, or `undefined` for a clean turn / handoff. */
+  private static failureReasonOf(result: ChatDriverResult): TurnFailureReason | undefined {
+    return result.reason === 'done' ? result.failureReason : undefined;
+  }
+
+  /**
+   * Build the `tool-loop-end` event detail for a turn's result. A failure carries a
+   * `{ failureReason }` detail; a clean turn emits `undefined` — the historical shape,
+   * kept byte-identical so subscribers see exactly what they always have.
+   */
+  private static loopEndDetail(
+    result: ChatDriverResult,
+  ): { failureReason: TurnFailureReason } | undefined {
+    const failureReason = ChatDriver.failureReasonOf(result);
+    return failureReason ? { failureReason } : undefined;
+  }
+
   /**
    * Swap in a new agent's configuration. Called by OrchestratingDriver before
    * each specialist turn so the shared driver runs with the right tools and prompt.
@@ -1412,8 +1442,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
     });
     agenticActivityBus.publish('tool-loop-start', undefined);
 
+    // Captured so the `finally` can carry the turn's outcome onto `tool-loop-end`.
+    let result: ChatDriverResult = { reason: 'done' };
     try {
-      return await this.runToolLoop(userInput, attachments);
+      result = await this.runToolLoop(userInput, attachments);
+      return result;
     } catch (e) {
       logger.error('ChatDriver error:', e);
       recordTurnError(this.sessionKey, 'exception', {
@@ -1427,7 +1460,8 @@ export class ChatDriver extends EventTarget implements AiDriver {
         role: 'assistant',
         content: 'Sorry, something went wrong on my end. Please try again in a moment.',
       });
-      return { reason: 'done' };
+      result = this.turnDone('exception');
+      return result;
     } finally {
       recordMetaEvent(this.sessionKey, 'turn.end', {
         phase: 'sendMessage',
@@ -1436,7 +1470,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       });
       this.busy = false;
       this.endTurn();
-      agenticActivityBus.publish('tool-loop-end', undefined);
+      agenticActivityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
     }
   }
 
@@ -1782,8 +1816,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
       agent: this.activeAgentName,
     });
     agenticActivityBus.publish('tool-loop-start', undefined);
+    // Captured so the `finally` can carry the turn's outcome onto `tool-loop-end`.
+    let result: ChatDriverResult = { reason: 'done' };
     try {
-      return await this.runToolLoop('', undefined, transientPrimer);
+      result = await this.runToolLoop('', undefined, transientPrimer);
+      return result;
     } catch (e) {
       logger.error('ChatDriver error:', e);
       recordTurnError(this.sessionKey, 'exception', {
@@ -1797,7 +1834,8 @@ export class ChatDriver extends EventTarget implements AiDriver {
         role: 'assistant',
         content: 'Sorry, something went wrong on my end. Please try again in a moment.',
       });
-      return { reason: 'done' };
+      result = this.turnDone('exception');
+      return result;
     } finally {
       recordMetaEvent(this.sessionKey, 'turn.end', {
         phase: 'continueFromHistory',
@@ -1806,7 +1844,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       });
       this.busy = false;
       this.endTurn();
-      agenticActivityBus.publish('tool-loop-end', undefined);
+      agenticActivityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
     }
   }
 
@@ -2244,7 +2282,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
                 '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' };
+          return this.turnDone('malformed-function-call');
         }
         // The response was truncated at the provider's output-token cap while it
         // still carried a tool call — its arguments are incomplete and unusable.
@@ -2273,7 +2311,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
                 'My response was cut off because a single step reached the model output limit. This usually means one step tried to produce too much at once — try breaking your request into smaller steps.',
             });
           }
-          return { reason: 'done' };
+          return this.turnDone('response-truncated');
         }
         // A request timeout from the transport (tagged `TimeoutError`) is not a
         // bug on our end — surface it distinctly instead of letting it fall
@@ -2299,7 +2337,9 @@ export class ChatDriver extends EventTarget implements AiDriver {
                 'The request timed out. You can ask me to try again, or break this into a smaller step.',
             });
           }
-          return { reason: 'done' };
+          // Recorded as `exception` above (there is no separate `timeout` member of
+          // TurnFailureReason for the main turn); surface the same reason here.
+          return this.turnDone('exception');
         }
         // The request was aborted: either a user cancel (turnController) or a
         // driver dispose (lifecycleController, chained into the turn). A user
@@ -2380,7 +2420,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
               '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' };
+        return this.turnDone('empty-response');
       } else {
         // Split one model response into separate, individually-toggleable messages so each has its
         // own visibility toggle and debug-log category:
@@ -2744,7 +2784,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
               "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' };
+        return this.turnDone('unknown-tool-limit');
       }
 
       const firstContinuation = systemCalls[0];
@@ -2759,10 +2799,13 @@ export class ChatDriver extends EventTarget implements AiDriver {
       // Sub-agent early exit — checked here so the exit point mirrors the
       // system-call pattern above. Set by completeSubAgent() in a tool handler.
       if (this.subAgentCompletion) {
-        return { reason: 'done' };
+        return this.turnDone();
       }
     }
 
+    // The loop fell through: either it hit the iteration cap (a failure) or it
+    // broke on a clean final answer (success). Only the former carries a reason.
+    let failureReason: TurnFailureReason | undefined;
     if (iterations >= this.maxToolIterations) {
       logger.warn('ChatDriver: reached max tool iterations, stopping');
       recordTurnError(this.sessionKey, 'max-iterations', {
@@ -2781,9 +2824,10 @@ export class ChatDriver extends EventTarget implements AiDriver {
             "I've reached my limit for this response. You can ask me to continue and I'll pick up where I left off.",
         });
       }
+      failureReason = 'max-iterations';
     }
 
-    return { reason: 'done' };
+    return this.turnDone(failureReason);
   }
 
   private appendToHistory(message: ChatMessage): void {

package/src/index.ts

@@ -16,6 +16,7 @@ export * from './state/persistence';
 export * from './provider/ai-provider-switcher';
 export * from './provider/assistant-app-settings';
 export * from './utils/tool-fold';
+export type { TurnFailureReason } from './state/debug-event-log';
 export type { TimelineMessage } from './utils/flatten-sub-agent-messages';
 export type { CostSessionModelEntry, CostSessionRecord } from './utils/cost-session-history';
 export type { ModelTagAppearance } from '@genesislcap/foundation-ai';

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

@@ -24,6 +24,8 @@
  * @internal
  */
 
+import type { TurnFailureReason } from '@genesislcap/foundation-ai';
+
 /**
  * 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).
@@ -211,25 +213,14 @@ export function recordMetaEvent(
 
 /**
  * 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 it couldn't dispatch,
- *                              whether hallucinated or stale (real earlier, retired now).
- * - `max-iterations`         — the tool loop hit its iteration cap.
- * - `response-truncated`     — a turn stopped at the provider's output-token cap with an
- *                              incomplete tool call; deterministic, so it bails without retry.
+ * and `turn.retry` events, and (since PTC-0) surfaced at the driver's loop
+ * boundary via {@link ChatDriverResult.failureReason}. Re-exported from
+ * `@genesislcap/foundation-ai` — where it lives alongside `ChatDriverResult` so
+ * the boundary field and this log surface can never drift apart — under its
+ * historical name so existing importers are unaffected. Enumerated so the set
+ * stays in sync with the README and call sites can't drift to ad-hoc strings.
  */
-export type TurnFailureReason =
-  | 'exception'
-  | 'malformed-function-call'
-  | 'empty-response'
-  | 'unknown-tool-limit'
-  | 'max-iterations'
-  | 'response-truncated';
+export type { TurnFailureReason };
 
 /**
  * Record a turn-ending failure (`turn.error`, importance `high`). The `reason`