@genesislcap/ai-assistant 14.452.0 → 14.452.1

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

@@ -9,6 +9,7 @@ import type {
   ChatToolDefinition,
   ChatToolHandlers,
   InteractionRequestOptions,
+  SubAgentFailureReason,
   SubAgentRequestOptions,
 } from '@genesislcap/foundation-ai';
 import { MalformedFunctionCallError } from '@genesislcap/foundation-ai';
@@ -40,8 +41,19 @@ const DEFAULT_MAX_FOLD_OPERATIONS = 5;
 // cap reach thousands for full-session capture without the memory blowup.
 const DEFAULT_MAX_TURN_SNAPSHOTS = 400;
 const DEFAULT_MAX_UNKNOWN_TOOL_CALLS = 5;
-const MAX_MALFORMED_RETRIES = 2;
+// Stale tools (advertised in an earlier state, retired now) and fold-hidden tools are
+// self-correcting — the model drops them once guided — so they get a higher loop-protection
+// ceiling than hallucinated names: a few legitimate stale calls across state transitions must
+// not prematurely end the turn. Still bounded so a genuinely stuck loop terminates.
+const MAX_STALE_TOOL_CALLS = DEFAULT_MAX_UNKNOWN_TOOL_CALLS * 2;
+// Gemini in particular emits short bursts of MALFORMED_FUNCTION_CALL; allow more CONSECUTIVE
+// retries. These counters reset on any productive response, so this is a consecutive-failure
+// ceiling, not a per-turn total.
+const MAX_MALFORMED_RETRIES = 5;
 const MAX_EMPTY_RESPONSE_RETRIES = 3;
+// Transient throws while building the per-turn tool surface or calling the provider retry the
+// SAME iteration up to this many times before propagating, rather than tearing down the turn.
+const MAX_SETUP_TRANSPORT_RETRIES = 3;
 const SUGGESTIONS_HISTORY_WINDOW = 8;
 
 /** Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver. */
@@ -69,8 +81,15 @@ export type ChatHistoryUpdatedEvent = CustomEvent<ReadonlyArray<ChatMessage>>;
  * @beta
  */
 export interface TurnSnapshot {
-  /** Monotonic counter across the driver's lifetime (does not reset on agent swap). */
-  turnIndex: number;
+  /**
+   * Turn identifier, always a string. A driver's own turns are the bare counter
+   * (`"0"`, `"1"`, … — monotonic, does not reset on agent swap). Turns forwarded
+   * up from a sub-agent are re-labelled under the parent turn that activated them
+   * — a sub-agent invoked on parent turn 5 contributes `"5-1"`, `"5-2"`, …, and a
+   * nested sub-agent on `"5-2"` contributes `"5-2-1"`, …. See
+   * `forwardSubAgentSnapshots`.
+   */
+  turnIndex: string;
   /** ISO timestamp captured just before the LLM call. */
   timestamp: string;
   /** Name of the agent active when this LLM call ran. */
@@ -218,6 +237,20 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * `undefined` means the loop has not been stopped early.
    */
   private subAgentCompletion: { result: unknown } | undefined;
+  /**
+   * True when this driver runs as a child sub-agent (created by a parent
+   * driver's `invokeSubAgent`). Sub-agents force tool use every turn so a turn
+   * can only end via their completion tool, and on any non-completion exit they
+   * record a typed `SubAgentFailureReason` instead of appending a
+   * user-facing message — the parent decides how to surface the failure.
+   */
+  private isSubAgent = false;
+  /**
+   * Set when a sub-agent's tool loop ends without `completeSubAgent` being
+   * called. Read by the parent's `invokeSubAgent` to build the `{ ok: false }`
+   * branch of `requestSubAgent`. Only ever set when `isSubAgent` is true.
+   */
+  private subAgentFailure: { reason: SubAgentFailureReason } | undefined;
   /**
    * Set by `releaseAgent` inside a top-level tool handler — typically a stateful
    * agent's terminal-state handler signalling that its flow is complete and the
@@ -405,6 +438,37 @@ export class ChatDriver extends EventTarget implements AiDriver {
     return this.subAgentCompletion;
   }
 
+  /**
+   * Mark this driver as running as a sub-agent. Called by a parent driver's
+   * `invokeSubAgent` immediately after construction, before the first turn.
+   * Enables forced tool use and typed failure reporting (see `isSubAgent`).
+   */
+  markAsSubAgent(): void {
+    this.isSubAgent = true;
+  }
+
+  /**
+   * Returns the typed failure recorded when a sub-agent run ended without
+   * `completeSubAgent`, if any. Called by a parent `ChatDriver` after running
+   * this instance as a sub-agent.
+   */
+  getSubAgentFailure(): { reason: SubAgentFailureReason } | undefined {
+    return this.subAgentFailure;
+  }
+
+  /**
+   * Record a sub-agent failure reason (first one wins). No-op for top-level
+   * agents, so loop-exit sites can call it unconditionally. The parent reads
+   * this via `getSubAgentFailure()` and emits the `subagent.failed` meta event
+   * under its *own* session — see `invokeSubAgent`. (A child sub-agent runs
+   * under a separate session key, so recording here would orphan the event off
+   * the user-visible debug-log timeline.)
+   */
+  private failSubAgent(reason: SubAgentFailureReason): void {
+    if (!this.isSubAgent || this.subAgentFailure) return;
+    this.subAgentFailure = { reason };
+  }
+
   /**
    * Returns true if `releaseAgent` was called during the most recent turn.
    * Consumed by the orchestrator to trigger the auto-pin release path.
@@ -424,6 +488,45 @@ export class ChatDriver extends EventTarget implements AiDriver {
     return this.turnSnapshots;
   }
 
+  /**
+   * Merge a sub-agent's turn snapshots into this driver's buffer so they surface
+   * as `kind:'turn'` entries in the exported debug log. The child runs as a
+   * separate, discarded driver, so its snapshots would otherwise be lost. Each is
+   * re-labelled under the parent turn that activated the sub-agent: the child's
+   * own (numeric) turns become `"<parentTurn>-1"`, `"-2"`, … (1-based, in order);
+   * any already-forwarded grand-child labels (strings) have their leading segment
+   * remapped the same way, so nesting composes (`"5-2"` → `"5-2-1"`).
+   *
+   * Note: two sub-agents invoked in the *same* parent turn share the prefix, so
+   * their labels can repeat — `agentName` on each snapshot disambiguates them.
+   */
+  private forwardSubAgentSnapshots(childSnapshots: ReadonlyArray<TurnSnapshot>): void {
+    if (childSnapshots.length === 0) return;
+    // The activating parent turn = the most recent snapshot this driver recorded
+    // before entering the tool handler that invoked the sub-agent.
+    const parentTurn = Math.max(0, this.globalTurnIndex - 1);
+    const ownTurnLabel = new Map<string, string>();
+    let ownPos = 0;
+    for (const snap of childSnapshots) {
+      let turnIndex: string;
+      if (!snap.turnIndex.includes('-')) {
+        // The child's own turn (a bare counter) → number it under the parent turn.
+        ownPos += 1;
+        turnIndex = `${parentTurn}-${ownPos}`;
+        ownTurnLabel.set(snap.turnIndex, turnIndex);
+      } else {
+        // An already-forwarded grand-child label — remap its leading segment.
+        const [lead, ...rest] = snap.turnIndex.split('-');
+        const leadLabel = ownTurnLabel.get(lead) ?? `${parentTurn}-${lead}`;
+        turnIndex = [leadLabel, ...rest].join('-');
+      }
+      this.turnSnapshots.push({ ...snap, turnIndex });
+    }
+    while (this.turnSnapshots.length > this.maxTurnSnapshots) {
+      this.turnSnapshots.shift();
+    }
+  }
+
   /**
    * Push one snapshot to the ring buffer. Called inside `runToolLoop` just
    * before each LLM call — that's the latest point where the prompt, tool
@@ -441,7 +544,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
         agentSnapshot = `<getDebugSnapshot threw: ${e instanceof Error ? e.message : String(e)}>`;
       }
     }
-    const turnIndex = this.globalTurnIndex;
+    const turnIndex = String(this.globalTurnIndex);
     this.globalTurnIndex += 1;
     this.turnSnapshots.push({
       turnIndex,
@@ -720,6 +823,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
 
     this.busy = true;
     this.subAgentCompletion = undefined;
+    this.subAgentFailure = undefined;
     this.agentReleaseRequested = false;
     this.appendToHistory({ role: 'user', content: userInput, attachments });
     this.turnStartedAt = Date.now();
@@ -776,10 +880,13 @@ export class ChatDriver extends EventTarget implements AiDriver {
         requestSubAgent: <T = never>(
           name: string,
           options?: SubAgentRequestOptions,
-        ): Promise<T | string> =>
-          this.invokeSubAgent<T>(name, options).then(({ result, trace }) => {
+        ): Promise<
+          | { ok: true; result: T; reason?: never }
+          | { ok: false; result?: never; reason: SubAgentFailureReason }
+        > =>
+          this.invokeSubAgent<T>(name, options).then(({ outcome, trace }) => {
             if (traceCapture) traceCapture.trace = trace;
-            return result;
+            return outcome;
           }),
       }),
       completeSubAgent: (result: unknown): void => {
@@ -812,7 +919,14 @@ export class ChatDriver extends EventTarget implements AiDriver {
   private async invokeSubAgent<T = never>(
     name: string,
     options?: SubAgentRequestOptions,
-  ): Promise<{ result: T | string; trace: ChatMessage[] }> {
+  ): Promise<{
+    // Closed union (see ChatToolHandlers.requestSubAgent) — keeps `result`/`reason`
+    // accessible for consumers compiled without strictNullChecks.
+    outcome:
+      | { ok: true; result: T; reason?: never }
+      | { ok: false; result?: never; reason: SubAgentFailureReason };
+    trace: ChatMessage[];
+  }> {
     const subConfig = this.subAgentsMap.get(name);
     if (!subConfig) {
       const available = [...this.subAgentsMap.keys()].join(', ') || '(none)';
@@ -846,6 +960,9 @@ export class ChatDriver extends EventTarget implements AiDriver {
     ];
 
     const child = new ChatDriver(this.providerRegistry);
+    // Mark before the first turn so the child forces tool use and reports a
+    // typed failure (rather than user-facing text) if it never completes.
+    child.markAsSubAgent();
     child.applyAgent({ ...subConfig, primerHistory: effectivePrimer });
     // Route interactions back through this driver so widgets render in the
     // parent's (ultimately the root's) history and resolve via the same
@@ -891,16 +1008,30 @@ export class ChatDriver extends EventTarget implements AiDriver {
     }
 
     const trace = child.getHistory() as ChatMessage[];
+    // Forward the child's per-LLM-call snapshots onto this (parent) driver's
+    // buffer so they show as `kind:'turn'` entries in the exported debug log,
+    // re-numbered under the activating parent turn. Runs for both success and
+    // failure so the sub-agent's turns are always visible.
+    this.forwardSubAgentSnapshots(child.getTurnSnapshots());
     const completion = child.getSubAgentCompletion();
 
     if (completion) {
-      return { result: completion.result as T, trace };
+      return { outcome: { ok: true, result: completion.result as T }, trace };
     }
 
-    const finalMsg = [...trace]
-      .reverse()
-      .find((m) => m.role === 'assistant' && !m.toolCalls?.length && m.content?.trim());
-    return { result: (finalMsg?.content ?? '') as string, trace };
+    // No completion → the sub-agent's loop ended without calling its completion
+    // tool. Surface the typed reason it recorded; default to 'max_iterations'
+    // for the defensive case where the loop ended with no reason set (e.g. a
+    // provider ignored forced tool use and returned text). The previous
+    // final-text fallback is intentionally gone — sub-agents return a
+    // structured outcome only, and the parent handler decides how to recover.
+    const reason = child.getSubAgentFailure()?.reason ?? 'max_iterations';
+    // Record under THIS (parent) driver's session so the failure lands on the
+    // user-visible debug-log timeline — the child ran under its own session key.
+    // This is also the only telemetry for the defensive default above, where the
+    // child's loop ended without recording an explicit failure reason.
+    recordMetaEvent(this.sessionKey, 'subagent.failed', { agent: name, reason });
+    return { outcome: { ok: false, reason }, trace };
   }
 
   /**
@@ -912,6 +1043,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
 
     this.busy = true;
     this.subAgentCompletion = undefined;
+    this.subAgentFailure = undefined;
     this.turnStartedAt = Date.now();
     recordMetaEvent(this.sessionKey, 'turn.start', {
       phase: 'continueFromHistory',
@@ -1133,6 +1265,10 @@ export class ChatDriver extends EventTarget implements AiDriver {
     let iterations = 0;
     let malformedAttempts = 0;
     let emptyResponseAttempts = 0;
+    // Bounded retries for transient throws while resolving the per-turn tool surface or
+    // calling the provider. Without this, a single transient throw tears down the whole turn
+    // and strands the agent's unflushed work behind an opaque error.
+    let setupTransportAttempts = 0;
     // True only for the very first LLM call. Used to exclude the pending user message
     // from history (it is passed separately as currentInput). Must not be derived from
     // `iterations` because fold operations decrement iterations, which would incorrectly
@@ -1155,17 +1291,31 @@ export class ChatDriver extends EventTarget implements AiDriver {
       // forbidden when a factory is set, so the array form is always valid.
       // Sequential await is required — each iteration must see fresh values
       // before constructing the LLM request.
-      if (this.toolDefinitionsFactory) {
-        // oxlint-disable-next-line no-await-in-loop
-        this.toolDefinitions = await this.toolDefinitionsFactory(promptCtx);
-      }
-      // Same story for the handler-map factory: re-resolve so dispatch sees
-      // only the handlers valid for the current state, in lockstep with the
-      // tool definitions exposed above. Folds are forbidden when this is set,
-      // so the fold-mutation paths on `this.toolHandlers` are unreachable.
-      if (this.toolHandlersFactory) {
-        // oxlint-disable-next-line no-await-in-loop
-        this.toolHandlers = await this.toolHandlersFactory(promptCtx);
+      // A transient throw while building the tool surface should retry the iteration, not
+      // tear down the whole turn and strand the agent's unflushed buffer behind an opaque
+      // error. The handler-map factory re-resolves in lockstep so dispatch sees only the
+      // handlers valid for the current state, in step with the tool definitions exposed
+      // above. Folds are forbidden when either factory is set, so the fold-mutation paths
+      // on `this.toolDefinitions` / `this.toolHandlers` are unreachable.
+      try {
+        if (this.toolDefinitionsFactory) {
+          // oxlint-disable-next-line no-await-in-loop
+          this.toolDefinitions = await this.toolDefinitionsFactory(promptCtx);
+        }
+        if (this.toolHandlersFactory) {
+          // oxlint-disable-next-line no-await-in-loop
+          this.toolHandlers = await this.toolHandlersFactory(promptCtx);
+        }
+      } catch (e) {
+        setupTransportAttempts += 1;
+        if (setupTransportAttempts < MAX_SETUP_TRANSPORT_RETRIES) {
+          logger.warn(
+            `ChatDriver: tool-surface resolution failed, retrying (${setupTransportAttempts}/${MAX_SETUP_TRANSPORT_RETRIES})`,
+          );
+          iterations -= 1;
+          continue;
+        }
+        throw e;
       }
 
       // Record everything advertised this turn so the unknown-tool path can tell
@@ -1227,6 +1377,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
         // Strip fold-only properties (foldEvent, foldPath) before sending to provider
         tools: this.toolDefinitions.length ? this.toolDefinitions : undefined,
         attachments: attachmentsForCall,
+        // Sub-agents must finish by calling a tool (their completion tool), never
+        // by emitting a free-text turn — force tool use so the provider can't
+        // return a bare text answer. Top-level agents stay on the default 'auto'.
+        // (Transports no-op the force when no tools are advertised.)
+        toolChoice: this.isSubAgent ? 'required' : undefined,
       };
 
       // Resolve the active provider for this turn. Static names were validated
@@ -1262,14 +1417,31 @@ export class ChatDriver extends EventTarget implements AiDriver {
             provider: this.lastResolvedProviderName,
             attempts: malformedAttempts,
             finishMessage: e.finishMessage,
+            isSubAgent: this.isSubAgent,
           });
-          this.appendToHistory({
-            role: 'assistant',
-            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.',
-          });
+          if (this.isSubAgent) {
+            // Bubble a typed failure to the parent instead of speaking to the user.
+            this.failSubAgent('malformed_tool_call');
+          } else {
+            this.appendToHistory({
+              role: 'assistant',
+              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' };
         }
+        // A transient provider/transport error should retry the SAME iteration a bounded
+        // number of times rather than tearing down the whole turn (which strands the
+        // agent's unflushed buffer behind an opaque error message).
+        setupTransportAttempts += 1;
+        if (setupTransportAttempts < MAX_SETUP_TRANSPORT_RETRIES) {
+          logger.warn(
+            `ChatDriver: provider/transport error, retrying (${setupTransportAttempts}/${MAX_SETUP_TRANSPORT_RETRIES})`,
+          );
+          iterations -= 1;
+          continue;
+        }
         throw e;
       }
 
@@ -1296,12 +1468,17 @@ export class ChatDriver extends EventTarget implements AiDriver {
           agent: this.activeAgentName,
           provider: this.lastResolvedProviderName,
           attempts: emptyResponseAttempts,
+          isSubAgent: this.isSubAgent,
         });
-        this.appendToHistory({
-          role: 'assistant',
-          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.',
-        });
+        if (this.isSubAgent) {
+          this.failSubAgent('empty_response');
+        } else {
+          this.appendToHistory({
+            role: 'assistant',
+            content:
+              'While working on your request, I repeatedly generated a blank response. This often works on a second try — would you like me to try again? If it happens again, try breaking your request into smaller steps.',
+          });
+        }
         return { reason: 'done' };
       } else if (isThinkingStep) {
         this.appendToHistory({ ...response, toolCalls: undefined, thinking: true });
@@ -1310,6 +1487,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
         this.appendToHistory(response);
       }
 
+      // Reset retry budgets on any productive (non-empty) response, so the caps mean
+      // "N CONSECUTIVE failures" not "N total per turn".
+      emptyResponseAttempts = 0;
+      malformedAttempts = 0;
+      setupTransportAttempts = 0;
+
       if (!response.toolCalls?.length) {
         break;
       }
@@ -1406,8 +1589,9 @@ export class ChatDriver extends EventTarget implements AiDriver {
               // or an exclusive fold is hiding it) rather than hallucinated — a
               // distinction worth making, because the model should stop retrying
               // a retired tool rather than treat the failure as a typo. Stale
-              // calls still count toward the same unknown-tool limit (loop
-              // protection); only the guidance and telemetry differ.
+              // calls still trip loop protection, but at a higher ceiling than
+              // hallucinated tools (see below) — they are self-correcting, so the
+              // guidance, telemetry, and limit differ.
               if (this.everSeenToolNames.has(tc.name)) {
                 this.consecutiveUnknownToolCalls += 1;
                 const hidingFold = this.foldHidingTool(tc.name);
@@ -1415,12 +1599,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
                 if (hidingFold) {
                   content = `"${tc.name}" is not available while the "${hidingFold}" fold is open. Call close_${hidingFold} to return to the previous set of tools, then call ${tc.name}.`;
                   logger.warn(
-                    `ChatDriver: tool "${tc.name}" is hidden behind open fold "${hidingFold}" (${this.consecutiveUnknownToolCalls}/${DEFAULT_MAX_UNKNOWN_TOOL_CALLS})`,
+                    `ChatDriver: tool "${tc.name}" is hidden behind open fold "${hidingFold}" (${this.consecutiveUnknownToolCalls}/${MAX_STALE_TOOL_CALLS})`,
                   );
                 } else {
                   content = `"${tc.name}" was available earlier but is not part of the current step — that step is complete, so do not call it again. Continue with the tools available now: ${Object.keys(this.toolHandlers).join(', ') || '(none)'}.`;
                   logger.warn(
-                    `ChatDriver: stale tool "${tc.name}" — advertised earlier this activation but retired in the current state (${this.consecutiveUnknownToolCalls}/${DEFAULT_MAX_UNKNOWN_TOOL_CALLS})`,
+                    `ChatDriver: stale tool "${tc.name}" — advertised earlier this activation but retired in the current state (${this.consecutiveUnknownToolCalls}/${MAX_STALE_TOOL_CALLS})`,
                   );
                 }
                 recordMetaEvent(this.sessionKey, 'tool.unresolved', {
@@ -1429,14 +1613,14 @@ export class ChatDriver extends EventTarget implements AiDriver {
                   kind: hidingFold ? 'fold-hidden' : 'stale',
                   fold: hidingFold ?? undefined,
                   consecutive: this.consecutiveUnknownToolCalls,
-                  max: DEFAULT_MAX_UNKNOWN_TOOL_CALLS,
+                  max: MAX_STALE_TOOL_CALLS,
                 });
                 executedById.set(tc.id, { toolCallId: tc.id, content });
                 unknownToolIds.add(tc.id);
                 staleToolIds.add(tc.id);
                 this.recentUnknownToolNames.add(tc.name);
                 this.recentStaleToolNames.add(tc.name);
-                if (this.consecutiveUnknownToolCalls >= DEFAULT_MAX_UNKNOWN_TOOL_CALLS) {
+                if (this.consecutiveUnknownToolCalls >= MAX_STALE_TOOL_CALLS) {
                   hitUnknownToolLimit = true;
                 }
                 return;
@@ -1484,7 +1668,9 @@ export class ChatDriver extends EventTarget implements AiDriver {
               });
               executedById.set(tc.id, {
                 toolCallId: tc.id,
-                content: `Tool error: ${(e as Error).message}`,
+                // Structured recovery hint so the model retries or routes around a tool
+                // failure instead of apologising and giving up.
+                content: `Tool error: ${(e as Error).message}\nRECOVERY: this tool failed once — you may retry it, or take a different valid action to make progress. Do NOT abandon the task, ask the user to rephrase, or claim you cannot make changes. If a planning tool failed, retry it or proceed with the information you already have.`,
               });
               anyRealToolExecuted = true; // treat errors as real work for fold op counting
             }
@@ -1595,12 +1781,17 @@ export class ChatDriver extends EventTarget implements AiDriver {
           staleTools,
           hallucinatedTools,
           availableTools: Object.keys(this.toolHandlers),
+          isSubAgent: this.isSubAgent,
         });
-        this.appendToHistory({
-          role: 'assistant',
-          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.",
-        });
+        if (this.isSubAgent) {
+          this.failSubAgent('unknown_tool_limit');
+        } else {
+          this.appendToHistory({
+            role: 'assistant',
+            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' };
       }
 
@@ -1627,12 +1818,17 @@ export class ChatDriver extends EventTarget implements AiDriver {
         provider: this.lastResolvedProviderName,
         iterations,
         limit: this.maxToolIterations,
+        isSubAgent: this.isSubAgent,
       });
-      this.appendToHistory({
-        role: 'assistant',
-        content:
-          "I've reached my limit for this response. You can ask me to continue and I'll pick up where I left off.",
-      });
+      if (this.isSubAgent) {
+        this.failSubAgent('max_iterations');
+      } else {
+        this.appendToHistory({
+          role: 'assistant',
+          content:
+            "I've reached my limit for this response. You can ask me to continue and I'll pick up where I left off.",
+        });
+      }
     }
 
     return { reason: 'done' };

package/src/main/main.ts

@@ -1434,7 +1434,7 @@ export class FoundationAiAssistant extends GenesisElement {
     // prompt is still shown in full whenever it changes, so prompt evolution
     // stays visible.
     let lastFullPrompt: string | undefined;
-    let lastFullIndex = -1;
+    let lastFullIndex = '';
     const turns = (this.driver?.getTurnSnapshots?.() ?? []).map((t) => {
       let { systemPrompt } = t;
       if (systemPrompt != null && systemPrompt === lastFullPrompt) {

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

@@ -46,6 +46,7 @@ export type MetaEventType =
   | 'turn.error'
   | 'tool.failed'
   | 'tool.unresolved'
+  | 'subagent.failed'
   // Routing / providers
   | 'agent.handoff'
   | 'agent.pinned'
@@ -83,6 +84,7 @@ export type MetaEventImportance = 'high' | 'normal' | 'low';
 export const META_EVENT_IMPORTANCE: Record<MetaEventType, MetaEventImportance> = {
   'turn.error': 'high',
   'tool.failed': 'high',
+  'subagent.failed': 'high',
   'file.read-failed': 'high',
   'suggestions.failed': 'high',
   'context.threshold-crossed': 'high',
@@ -241,7 +243,7 @@ export const DEBUG_LOG_README: readonly string[] = [
   'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',
   '`timeline` is the entire session as one array, already sorted chronologically by `timestamp` (ISO 8601). Every entry has a `kind`.',
   "kind:'message' — the conversation. `role` is user/assistant/tool/system-event; `agentName` says which agent produced it; `toolCalls`/`toolResult`/`interaction` carry tool and widget activity; `inputTokens`/`outputTokens`/`cost` are per-message usage.",
-  "kind:'turn' — one LLM call. `systemPrompt` and `toolNames` are what the model saw. A systemPrompt of '<repeated — identical to turn N>' was byte-identical to turn N and de-duplicated; the full prompt is shown whenever it changes (often because a stateful agent advanced), so prompt evolution is visible.",
+  "kind:'turn' — one LLM call. `turnIndex` is a string: a top-level turn is the bare counter ('0', '1', …); a sub-agent's turns are numbered under the parent turn that activated them ('3-1', '3-2', …, and a nested sub-agent contributes '3-2-1', …), and `agentName` names the agent that ran the turn. `systemPrompt` and `toolNames` are what the model saw. A systemPrompt of '<repeated — identical to turn N>' was byte-identical to turn N and de-duplicated; the full prompt is shown whenever it changes (often because a stateful agent advanced), so prompt evolution is visible.",
   "kind:'turn'.`agentSnapshot` — the active agent's own view of its internal state, captured at that turn. An agent opts into this by exposing a `getDebugSnapshot()` that returns JSON-serializable per-state info; stateful/flow agents wire it automatically, so you can watch a flow advance turn-by-turn (e.g. current step, cursor, collected fields, pending changes). Absent for agents that don't expose one.",
   "kind:'event' — a meta/lifecycle event. `type` names it (see below); `detail` carries structured data. `detail.placement` is the emitting UI instance: 'bubble' (collapsed), 'panel' (popped-out), or 'standalone'.",
   "Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. A 'high' turn.error is often preceded by one or more 'normal' turn.retry events for the same reason — read them together to see how many attempts were made before bailing. 'message' and 'turn' entries carry no importance — they are the substance, always read them.",