@genesislcap/ai-assistant 14.494.0 → 14.495.0

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`