@genesislcap/ai-assistant 14.494.0 → 14.496.0

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

@@ -2,16 +2,22 @@ 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 ActivityBus, AgenticActivityBus } from '../../channel/ai-activity-bus';
 import type { AgentConfig } from '../../config/config';
 import { clearMetaEventRegistry, getMetaEvents } from '../../state/debug-event-log';
 import { sumCosts } from '../../utils/sum-costs';
@@ -114,18 +120,18 @@ const callsTool = (name: string, id: string): ChatMessage => ({
 const agent = (overrides: Partial<AgentConfig> & { name: string }): AgentConfig =>
   ({ description: 'test agent', ...overrides }) as AgentConfig;
 
-const makeDriver = (config: AgentConfig, provider: AIProvider, sessionKey = ''): ChatDriver => {
-  const driver = new ChatDriver(
-    makeRegistry(provider),
-    {},
-    [],
-    undefined,
-    undefined,
-    50,
-    5,
-    undefined,
+const makeDriver = (
+  config: AgentConfig,
+  provider: AIProvider,
+  sessionKey = '',
+  activityBus?: ActivityBus,
+): ChatDriver => {
+  const driver = new ChatDriver(makeRegistry(provider), {
+    maxToolIterations: 50,
+    maxFoldOperations: 5,
     sessionKey,
-  );
+    activityBus,
+  });
   driver.applyAgent(config);
   return driver;
 };
@@ -153,13 +159,6 @@ const unresolvedEvents = (sessionKey: string): Array<Record<string, unknown>> =>
 
 const stale = createLogicSuite('ChatDriver stale-tool detection');
 
-// The driver imports the `agenticActivityBus` singleton, which opens a
-// BroadcastChannel at module load. An open channel keeps the test page alive
-// and hangs the runner, so close it once the suite finishes.
-stale.after(() => {
-  agenticActivityBus.close();
-});
-
 stale('guides the model when it calls a tool that an earlier state exposed', async () => {
   // State A exposes tool_a; calling it advances to state B, which exposes only
   // tool_b. A factory-form agent narrows the tool set per turn, mirroring how
@@ -357,10 +356,6 @@ stale.run();
 
 const hook = createLogicSuite('ChatDriver onUnresolvedTool hook');
 
-hook.after(() => {
-  agenticActivityBus.close();
-});
-
 hook('replaces the default for a hallucinated tool when the hook returns a string', async () => {
   const config = agent({
     name: 'Hooked',
@@ -716,12 +711,6 @@ cancel.run();
 
 const subagent = createLogicSuite('ChatDriver sub-agents');
 
-subagent.after(() => {
-  // Safe to call again even if `stale` already closed it — close() is
-  // idempotent and cross-tab publishes are guarded by `&& this.channel`.
-  agenticActivityBus.close();
-});
-
 /** A sub-agent named `worker` that finishes by calling `completeSubAgent`. */
 const completingWorker = (result: unknown): AgentConfig =>
   agent({
@@ -1530,17 +1519,18 @@ interactionContextLifecycle.run();
 
 const interactionBus = createLogicSuite('ChatDriver interaction activity-bus signals');
 
-interactionBus.after(() => {
-  agenticActivityBus.close();
-});
+// These two tests need to observe what the driver publishes, so they inject a local
+// in-memory bus (no `crossTabEvents` → no BroadcastChannel is ever opened, nothing to close)
+// rather than the shared singleton. Every other suite lets the driver default to the no-op bus.
 
 interactionBus('brackets a park with interaction-requested then -resolved', async () => {
   const events: string[] = [];
+  const bus = new AgenticActivityBus();
   const unsubs = [
-    agenticActivityBus.subscribe('interaction-requested', () => events.push('requested')),
-    agenticActivityBus.subscribe('interaction-resolved', () => events.push('resolved')),
+    bus.subscribe('interaction-requested', () => events.push('requested')),
+    bus.subscribe('interaction-resolved', () => events.push('resolved')),
   ];
-  const driver = makeDriver(agent({ name: 'a' }), scriptedProvider([]));
+  const driver = makeDriver(agent({ name: 'a' }), scriptedProvider([]), '', bus);
 
   const pending = driver.requestInteraction('w', {});
   assert.equal(events, ['requested'], 'parking fires interaction-requested');
@@ -1556,8 +1546,9 @@ interactionBus('brackets a park with interaction-requested then -resolved', asyn
 
 interactionBus('a timed-out interaction still fires interaction-resolved', async () => {
   const events: string[] = [];
-  const unsub = agenticActivityBus.subscribe('interaction-resolved', () => events.push('resolved'));
-  const driver = makeDriver(agent({ name: 'a' }), scriptedProvider([]));
+  const bus = new AgenticActivityBus();
+  const unsub = bus.subscribe('interaction-resolved', () => events.push('resolved'));
+  const driver = makeDriver(agent({ name: 'a' }), scriptedProvider([]), '', bus);
 
   // Never resolved by a user — the timeout path runs the same teardown, so it
   // must signal the bus too (else the button would stay enabled after a timeout).
@@ -1713,17 +1704,13 @@ const makeObservableRegistry = (initial: AIProvider): ObservableTestRegistry =>
 };
 
 const makeDriverWithRegistry = (config: AgentConfig, registry: AIProviderRegistry): ChatDriver => {
-  const driver = new ChatDriver(registry, {}, [], undefined, undefined, 50, 5, undefined, '');
+  const driver = new ChatDriver(registry, { maxToolIterations: 50, maxFoldOperations: 5 });
   driver.applyAgent(config);
   return driver;
 };
 
 const observable = createLogicSuite('ChatDriver observable provider registry');
 
-observable.after(() => {
-  agenticActivityBus.close();
-});
-
 observable(
   'a registry change clears the resolved-provider cache so the next turn uses the new provider',
   async () => {
@@ -1822,10 +1809,6 @@ const modelProvider = (model: string | undefined, responses: ChatMessage[]): AIP
 
 const modelAttr = createLogicSuite('ChatDriver per-message model attribution');
 
-modelAttr.after(() => {
-  agenticActivityBus.close();
-});
-
 modelAttr('stamps the resolved model and registry name onto an assistant reply', async () => {
   const provider = modelProvider('gemini-2.5-flash-lite', [
     { role: 'assistant', content: 'hi there' },
@@ -1912,9 +1895,6 @@ modelAttr.run();
 // ---------------------------------------------------------------------------
 
 const condense = createLogicSuite('ChatDriver condenseWhen');
-condense.after(() => {
-  agenticActivityBus.close();
-});
 
 const bigBody = 'A'.repeat(2000);
 
@@ -2175,3 +2155,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');
+
+// This branch routes activity events to an INJECTED bus (default NOOP), not the module
+// singleton, so these tests inject a local bus and observe the same seam the driver publishes to.
+const outcomeBus = new AgenticActivityBus();
+
+outcome.after(() => {
+  outcomeBus.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 = outcomeBus.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), {
+    maxToolIterations: maxIterations,
+    maxFoldOperations: 5,
+    sessionKey,
+    activityBus: outcomeBus,
+  });
+  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, outcomeBus),
+): 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',
+    outcomeBus,
+  );
+  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();