@genesislcap/ai-assistant 14.496.0 → 14.496.1-GENC-1461.4

package/dist/ai-assistant.api.json

@@ -2780,6 +2780,48 @@
               "parameters": [],
               "name": "getActiveProviderName"
             },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@genesislcap/ai-assistant!AiDriver#getExternalDiagnostics:member(1)",
+              "docComment": "/**\n * Diagnostic-log entries harvested from resolved interactions (e.g. a server-side ChatDriver's collated debug log, returned on `InteractionResult.diagnostics`). The host folds these into its debug log. Optional for the same leaf/orchestrator reason as `getTurnSnapshots`. (GENC-1461 unified diagnostics.)\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getExternalDiagnostics?(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ReadonlyArray",
+                  "canonicalReference": "!ReadonlyArray:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<"
+                },
+                {
+                  "kind": "Reference",
+                  "text": "DiagnosticEntry",
+                  "canonicalReference": "@genesislcap/ai-assistant!DiagnosticEntry:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ">"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": true,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 5
+              },
+              "releaseTag": "Beta",
+              "overloadIndex": 1,
+              "parameters": [],
+              "name": "getExternalDiagnostics"
+            },
             {
               "kind": "MethodSignature",
               "canonicalReference": "@genesislcap/ai-assistant!AiDriver#getInteractionContext:member(1)",
@@ -4565,6 +4607,51 @@
               "isAbstract": false,
               "name": "getAgentReleaseRequested"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#getExternalDiagnostics:member(1)",
+              "docComment": "/**\n * The `turn` + `message` diagnostic-log entries harvested from resolved interactions' `InteractionResult.diagnostics` (e.g. a server-side ChatDriver's collated debug log). The host concatenates these into its own debug log so `downloadDebugLog`/the persisted diagnostics stream include external-engine logs; `event` entries are excluded here because they're merged into the session's meta-event registry instead (see `resolveInteraction`) and reach the log via `getMetaEvents`. Opaque, chronologically sorted by the host at assemble time. (GENC-1461.)\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getExternalDiagnostics(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ReadonlyArray",
+                  "canonicalReference": "!ReadonlyArray:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<"
+                },
+                {
+                  "kind": "Reference",
+                  "text": "DiagnosticEntry",
+                  "canonicalReference": "@genesislcap/ai-assistant!DiagnosticEntry:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ">"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 5
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "getExternalDiagnostics"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!ChatDriver#getHistory:member(1)",
@@ -13282,6 +13369,51 @@
               "isAbstract": false,
               "name": "getActiveProviderName"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!OrchestratingDriver#getExternalDiagnostics:member(1)",
+              "docComment": "/**\n * Delegates to the inner {@link ChatDriver} — interactions resolve there, so it holds the buffer.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "getExternalDiagnostics(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ReadonlyArray",
+                  "canonicalReference": "!ReadonlyArray:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<"
+                },
+                {
+                  "kind": "Reference",
+                  "text": "DiagnosticEntry",
+                  "canonicalReference": "@genesislcap/ai-assistant!DiagnosticEntry:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ">"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 5
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "getExternalDiagnostics"
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!OrchestratingDriver#getInteractionContext:member(1)",

package/dist/ai-assistant.d.ts

@@ -604,6 +604,13 @@ export declare interface AiDriver extends EventTarget {
      * orchestrator just delegates to its inner `ChatDriver`.
      */
     getTurnSnapshots?(): ReadonlyArray<TurnSnapshot>;
+    /**
+     * Diagnostic-log entries harvested from resolved interactions (e.g. a server-side ChatDriver's
+     * collated debug log, returned on `InteractionResult.diagnostics`). The host folds these into its
+     * debug log. Optional for the same leaf/orchestrator reason as `getTurnSnapshots`.
+     * (GENC-1461 unified diagnostics.)
+     */
+    getExternalDiagnostics?(): ReadonlyArray<DiagnosticEntry>;
     /**
      * Name of the AI provider used on the most recent turn. Falls back to the
      * registry's default name when no turn has run yet.
@@ -1190,6 +1197,23 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * arrive. See {@link TurnSnapshot} for the captured shape.
      */
     private turnSnapshots;
+    /**
+     * `turn` + `message` diagnostic-log entries harvested from an out-of-band source (a resolved
+     * interaction whose widget returned `InteractionResult.diagnostics` — e.g. a server-side
+     * ChatDriver's debug log). `event` entries are NOT kept here — they're folded into the session's
+     * meta-event registry via `mergeMetaEvents` (see `resolveInteraction`) so they inherit fresh host
+     * indices, and reach the log through `getMetaEvents`. Append-only; the host folds these into its
+     * debug log alongside this driver's own timeline. Not cleared here — it lives with the driver
+     * instance, like `turnSnapshots`, so a new chat (fresh driver) starts empty while a compaction
+     * (same instance) keeps it. (GENC-1461.)
+     */
+    private readonly externalDiagnostics;
+    /**
+     * Monotonic count of external-diagnostics batches harvested this driver-lifetime. Namespaces each
+     * batch's re-keyed `turn` entries so distinct server generations in one chat session can't collide
+     * on `turnIndex` in the forward-capture persister (which dedups turns by that key). (GENC-1461.)
+     */
+    private externalDiagnosticsBatches;
     /** Monotonic counter that survives agent swaps — useful for cross-referencing with history. */
     private globalTurnIndex;
     /** Captured from `applyAgent` so we don't store the whole `AgentConfig`. */
@@ -1444,6 +1468,15 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * Ring-buffered at `MAX_TURN_SNAPSHOTS`; older entries are dropped.
      */
     getTurnSnapshots(): ReadonlyArray<TurnSnapshot>;
+    /**
+     * The `turn` + `message` diagnostic-log entries harvested from resolved interactions'
+     * `InteractionResult.diagnostics` (e.g. a server-side ChatDriver's collated debug log). The host
+     * concatenates these into its own debug log so `downloadDebugLog`/the persisted diagnostics stream
+     * include external-engine logs; `event` entries are excluded here because they're merged into the
+     * session's meta-event registry instead (see `resolveInteraction`) and reach the log via
+     * `getMetaEvents`. Opaque, chronologically sorted by the host at assemble time. (GENC-1461.)
+     */
+    getExternalDiagnostics(): ReadonlyArray<DiagnosticEntry>;
     /**
      * 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
@@ -3079,6 +3112,8 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
     canCompact(): boolean;
     /** Delegates to the inner {@link ChatDriver} — turns are captured there. */
     getTurnSnapshots(): ReadonlyArray<TurnSnapshot>;
+    /** Delegates to the inner {@link ChatDriver} — interactions resolve there, so it holds the buffer. */
+    getExternalDiagnostics(): ReadonlyArray<DiagnosticEntry>;
     getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
     sendMessage(input: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult>;
     continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult>;

package/dist/chat-driver.cjs

@@ -29,10 +29,16 @@ __export(chat_driver_node_exports, {
   NOOP_ACTIVITY_BUS: () => NOOP_ACTIVITY_BUS,
   OrchestratingDriver: () => OrchestratingDriver,
   REQUEST_CONTINUATION_TOOL: () => REQUEST_CONTINUATION_TOOL,
+  SUPPORTED_ANTHROPIC_MODEL_IDS: () => SUPPORTED_ANTHROPIC_MODEL_IDS,
+  SUPPORTED_GEMINI_MODEL_IDS: () => SUPPORTED_GEMINI_MODEL_IDS,
   agenticActivityBus: () => agenticActivityBus,
+  assembleDebugLog: () => assembleDebugLog,
+  buildTimelineEntries: () => buildTimelineEntries,
+  clearSession: () => clearSession,
   defineAgent: () => defineAgent,
   defineStatefulAgent: () => defineStatefulAgent,
   friendlyFallbackAgent: () => friendlyFallbackAgent,
+  getMetaEvents: () => getMetaEvents,
   isObservableAIProviderRegistry: () => isObservableAIProviderRegistry,
   restoreMachine: () => restoreMachine,
   strictFallbackAgent: () => strictFallbackAgent
@@ -2630,6 +2636,7 @@ var META_EVENT_IMPORTANCE = {
   "provider.selected": "normal",
   "interaction.requested": "normal",
   "interaction.resolved": "normal",
+  "external-diagnostics.folded": "normal",
   "session.cleared": "normal",
   "session.switched": "low",
   "session.switch-deferred": "low",
@@ -3126,6 +3133,23 @@ var ChatDriver = class _ChatDriver extends EventTarget {
      * arrive. See {@link TurnSnapshot} for the captured shape.
      */
     this.turnSnapshots = [];
+    /**
+     * `turn` + `message` diagnostic-log entries harvested from an out-of-band source (a resolved
+     * interaction whose widget returned `InteractionResult.diagnostics` — e.g. a server-side
+     * ChatDriver's debug log). `event` entries are NOT kept here — they're folded into the session's
+     * meta-event registry via `mergeMetaEvents` (see `resolveInteraction`) so they inherit fresh host
+     * indices, and reach the log through `getMetaEvents`. Append-only; the host folds these into its
+     * debug log alongside this driver's own timeline. Not cleared here — it lives with the driver
+     * instance, like `turnSnapshots`, so a new chat (fresh driver) starts empty while a compaction
+     * (same instance) keeps it. (GENC-1461.)
+     */
+    this.externalDiagnostics = [];
+    /**
+     * Monotonic count of external-diagnostics batches harvested this driver-lifetime. Namespaces each
+     * batch's re-keyed `turn` entries so distinct server generations in one chat session can't collide
+     * on `turnIndex` in the forward-capture persister (which dedups turns by that key). (GENC-1461.)
+     */
+    this.externalDiagnosticsBatches = 0;
     /** Monotonic counter that survives agent swaps — useful for cross-referencing with history. */
     this.globalTurnIndex = 0;
     /**
@@ -3500,6 +3524,17 @@ var ChatDriver = class _ChatDriver extends EventTarget {
   getTurnSnapshots() {
     return this.turnSnapshots;
   }
+  /**
+   * The `turn` + `message` diagnostic-log entries harvested from resolved interactions'
+   * `InteractionResult.diagnostics` (e.g. a server-side ChatDriver's collated debug log). The host
+   * concatenates these into its own debug log so `downloadDebugLog`/the persisted diagnostics stream
+   * include external-engine logs; `event` entries are excluded here because they're merged into the
+   * session's meta-event registry instead (see `resolveInteraction`) and reach the log via
+   * `getMetaEvents`. Opaque, chronologically sorted by the host at assemble time. (GENC-1461.)
+   */
+  getExternalDiagnostics() {
+    return this.externalDiagnostics;
+  }
   /**
    * 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
@@ -3809,6 +3844,34 @@ Output format (strict):
     const interaction = this.pendingInteractions.get(interactionId);
     if (interaction) {
       if (interaction.timeoutHandle) clearTimeout(interaction.timeoutHandle);
+      const harvestedDiagnostics = result?.diagnostics;
+      if (Array.isArray(harvestedDiagnostics) && harvestedDiagnostics.length) {
+        const batch = this.externalDiagnosticsBatches += 1;
+        const externalEvents = [];
+        let turnCount = 0;
+        let messageCount = 0;
+        for (const entry of harvestedDiagnostics) {
+          if (entry.kind === "event") {
+            const { kind: _kind, ...event } = entry;
+            externalEvents.push(event);
+          } else if (entry.kind === "turn") {
+            turnCount += 1;
+            this.externalDiagnostics.push({
+              ...entry,
+              turnIndex: `server-generation.${batch}:${String(entry.turnIndex ?? "")}`
+            });
+          } else {
+            messageCount += 1;
+            this.externalDiagnostics.push(entry);
+          }
+        }
+        if (externalEvents.length) mergeMetaEvents(this.sessionKey, externalEvents);
+        recordMetaEvent(this.sessionKey, "external-diagnostics.folded", {
+          interactionId,
+          batch,
+          counts: { turn: turnCount, event: externalEvents.length, message: messageCount }
+        });
+      }
       const idx = this.history.findIndex((m) => m.interaction?.interactionId === interactionId);
       if (idx !== -1) {
         const costUsd = typeof result?.costUsd === "number" && Number.isFinite(result.costUsd) && result.costUsd > 0 ? result.costUsd : void 0;
@@ -4518,9 +4581,10 @@ ${tailBody}
       }
       const isThinkingStep = response.content && response.toolCalls?.length;
       const isEmptyResponse = !response.content?.trim() && !response.toolCalls?.length;
+      const isRefusal = response.responseMeta?.finishReason === "refusal";
       if (isEmptyResponse) {
         emptyResponseAttempts += 1;
-        if (emptyResponseAttempts < MAX_EMPTY_RESPONSE_RETRIES) {
+        if (!isRefusal && emptyResponseAttempts < MAX_EMPTY_RESPONSE_RETRIES) {
           logger2.warn(
             `ChatDriver: empty model response, retrying (${emptyResponseAttempts}/${MAX_EMPTY_RESPONSE_RETRIES})`
           );
@@ -4538,8 +4602,11 @@ ${tailBody}
           iterations -= 1;
           continue;
         }
-        logger2.error("ChatDriver: empty model response after all retries");
-        recordTurnError(this.sessionKey, "empty-response", {
+        const failureReason2 = isRefusal ? "refusal" : "empty-response";
+        logger2.error(
+          isRefusal ? "ChatDriver: model refused the request (safety decline) \u2014 not retrying" : "ChatDriver: empty model response after all retries"
+        );
+        recordTurnError(this.sessionKey, failureReason2, {
           agent: this.activeAgentName,
           provider: this.lastResolvedProviderName,
           attempts: emptyResponseAttempts,
@@ -4547,14 +4614,14 @@ ${tailBody}
           ...response.responseMeta
         });
         if (this.isSubAgent) {
-          this.failSubAgent("empty_response");
+          this.failSubAgent(isRefusal ? "refusal" : "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 \u2014 would you like me to try again? If it happens again, try breaking your request into smaller steps."
+            content: isRefusal ? "This request was declined. Try rephrasing it, or breaking it into smaller steps." : "While working on your request, I repeatedly generated a blank response. This often works on a second try \u2014 would you like me to try again? If it happens again, try breaking your request into smaller steps."
           });
         }
-        return this.turnDone("empty-response");
+        return this.turnDone(failureReason2);
       } else {
         const { reasoning, ...rest } = response;
         const displayOnly = { cost: void 0, inputTokens: void 0, outputTokens: void 0 };
@@ -5072,6 +5139,10 @@ var OrchestratingDriver = class extends EventTarget {
   getTurnSnapshots() {
     return this.chatDriver.getTurnSnapshots();
   }
+  /** Delegates to the inner {@link ChatDriver} — interactions resolve there, so it holds the buffer. */
+  getExternalDiagnostics() {
+    return this.chatDriver.getExternalDiagnostics();
+  }
   async getSuggestions(history, prompt2, count, allAgentInfo) {
     const pinned = this.resolvePinnedAgent();
     const candidates = pinned && isSpecialist(pinned) ? [pinned] : this.specialists;
@@ -5585,6 +5656,86 @@ var strictFallbackAgent = {
   fallback: true,
   systemPrompt: `You are a concise assistant. The user's request is outside your scope. Respond with a single short sentence stating what you can assist with. Do not elaborate. The available specialists are: {{agents}}.`
 };
+
+// src/utils/flatten-sub-agent-messages.ts
+function flattenSubAgentMessages(messages, prefix = "", depth = 0, subAgentOf) {
+  return messages.flatMap((m) => {
+    const breadcrumb = prefix ? `${prefix} \u203A ${m.agentName ?? "?"}` : m.agentName;
+    const traceCalls = m.toolCalls?.filter((tc) => tc.subAgentTrace?.length) ?? [];
+    const entry = {
+      kind: "message",
+      ...m,
+      // Move the (about-to-be-hoisted) child conversations out of the emitted tool
+      // calls. Setting it to `undefined` drops the key from the serialized export.
+      ...traceCalls.length > 0 && {
+        toolCalls: m.toolCalls.map(
+          (tc) => tc.subAgentTrace ? { ...tc, subAgentTrace: void 0 } : tc
+        )
+      },
+      // Mark + breadcrumb hoisted sub-agent messages; top-level (depth 0) stays as-is.
+      ...depth > 0 && {
+        agentName: breadcrumb,
+        subAgentName: m.agentName,
+        subAgentDepth: depth,
+        subAgentOf
+      }
+    };
+    if (traceCalls.length === 0) return [entry];
+    const hoisted = traceCalls.flatMap(
+      (tc) => flattenSubAgentMessages(tc.subAgentTrace, breadcrumb ?? "", depth + 1, tc.id)
+    );
+    return [entry, ...hoisted];
+  });
+}
+
+// src/state/persistence/build-timeline-entries.ts
+function buildTimelineEntries(input) {
+  const { turnSnapshots, messages, metaEvents } = input;
+  let lastFullPrompt;
+  let lastFullIndex = "";
+  const turns = turnSnapshots.map((t) => {
+    let { systemPrompt } = t;
+    if (systemPrompt != null && systemPrompt === lastFullPrompt) {
+      systemPrompt = `<repeated \u2014 identical to turn ${lastFullIndex}>`;
+    } else if (systemPrompt != null) {
+      lastFullPrompt = systemPrompt;
+      lastFullIndex = t.turnIndex;
+    }
+    return { kind: "turn", ...t, systemPrompt };
+  });
+  const messageEntries = flattenSubAgentMessages(messages);
+  const eventEntries = metaEvents.map((e) => ({ kind: "event", ...e }));
+  return [...messageEntries, ...turns, ...eventEntries];
+}
+
+// src/state/persistence/diagnostics.ts
+var KIND_RANK = { event: 0, turn: 1, message: 2 };
+var UNKNOWN_KIND_RANK = 99;
+function assembleDebugLog(entries, readme) {
+  const seen = /* @__PURE__ */ new Set();
+  let latestMeta;
+  const timeline = [];
+  for (const entry of entries) {
+    const id = JSON.stringify(entry);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    if (entry.kind === "meta-snapshot") {
+      if (!latestMeta || (entry.timestamp ?? "") >= (latestMeta.timestamp ?? "")) {
+        latestMeta = entry;
+      }
+    } else {
+      timeline.push(entry);
+    }
+  }
+  timeline.sort((a, b) => {
+    const ta = a.timestamp ?? "";
+    const tb = b.timestamp ?? "";
+    if (ta < tb) return -1;
+    if (ta > tb) return 1;
+    return (KIND_RANK[a.kind] ?? UNKNOWN_KIND_RANK) - (KIND_RANK[b.kind] ?? UNKNOWN_KIND_RANK);
+  });
+  return { readme, timeline, meta: latestMeta?.meta };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AgenticActivityBus,
@@ -5597,10 +5748,16 @@ var strictFallbackAgent = {
   NOOP_ACTIVITY_BUS,
   OrchestratingDriver,
   REQUEST_CONTINUATION_TOOL,
+  SUPPORTED_ANTHROPIC_MODEL_IDS,
+  SUPPORTED_GEMINI_MODEL_IDS,
   agenticActivityBus,
+  assembleDebugLog,
+  buildTimelineEntries,
+  clearSession,
   defineAgent,
   defineStatefulAgent,
   friendlyFallbackAgent,
+  getMetaEvents,
   isObservableAIProviderRegistry,
   restoreMachine,
   strictFallbackAgent