comisai 1.0.4

package/node_modules/@comis/agent/dist/executor/model-retry.js

@@ -0,0 +1,301 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Model failover pipeline for PiExecutor.
+ *
+ * The SDK handles transient retry (429/5xx) with exponential backoff via
+ * SettingsManager.retry configuration. This module handles the higher-level
+ * failover concerns that the SDK does not provide:
+ *
+ * - Auth key rotation -- when an API key is exhausted or revoked,
+ *   rotate to the next available key for the same provider.
+ * - Model fallback -- when all keys for the primary model/provider
+ *   are exhausted, fall back to alternate models in priority order.
+ *
+ * Each `session.prompt()` call benefits from SDK internal retry before
+ * Comis failover triggers.
+ *
+ * Steps:
+ * 1. Attempt primary prompt (SDK handles transient retry internally)
+ * 2. On failure, try key rotation if authRotation available
+ * 3. Loop through fallback models
+ * 4. Emit model:fallback_attempt and model:fallback_exhausted events
+ * 5. Return { succeeded, error }
+ *
+ * @module
+ */
+import { withPromptTimeout, withResettablePromptTimeout, PromptTimeoutError } from "./prompt-timeout.js";
+import { normalizeModelId } from "../provider/model-id-normalize.js";
+// ---------------------------------------------------------------------------
+// Cache-aware short retry constants
+// ---------------------------------------------------------------------------
+/**
+ * Maximum retry-after duration (ms) for cache-preserving short retry.
+ * Below this threshold: sleep and retry with same model to preserve cache hit.
+ * Above this threshold: fall through to auth rotation / model fallback.
+ */
+const SHORT_RETRY_THRESHOLD_MS = 20_000;
+// ---------------------------------------------------------------------------
+// Helpers (moved from pi-executor.ts -- only used by fallback loop)
+// ---------------------------------------------------------------------------
+/**
+ * Parse a "provider:modelId" string into provider and modelId components.
+ * Returns undefined if the format is invalid.
+ */
+export function parseModelString(modelStr) {
+    const colonIdx = modelStr.indexOf(":");
+    if (colonIdx <= 0 || colonIdx >= modelStr.length - 1)
+        return undefined;
+    return {
+        provider: modelStr.slice(0, colonIdx),
+        modelId: modelStr.slice(colonIdx + 1),
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers for cache-aware short retry
+// ---------------------------------------------------------------------------
+/** Extract HTTP status code from error, returning 0 if not found. */
+function getErrorStatus(error) {
+    if (!(error instanceof Error))
+        return 0;
+    const errObj = error;
+    if (typeof errObj.status === "number")
+        return errObj.status;
+    if (typeof errObj.statusCode === "number")
+        return errObj.statusCode;
+    return 0;
+}
+/**
+ * Extract retry-after delay from API error.
+ * Checks for `headers["retry-after"]` on the error object (pi-ai SDK errors
+ * expose response headers). Returns milliseconds, or null if not available.
+ */
+function parseRetryAfterMs(error) {
+    if (!(error instanceof Error))
+        return null;
+    const errObj = error;
+    // Check for retry-after header (may be on error.headers or error.responseHeaders)
+    let retryAfter;
+    if (errObj.headers && typeof errObj.headers === "object") {
+        const headers = errObj.headers;
+        retryAfter = headers["retry-after"] ?? headers["Retry-After"];
+    }
+    if (!retryAfter && errObj.responseHeaders && typeof errObj.responseHeaders === "object") {
+        const headers = errObj.responseHeaders;
+        retryAfter = headers["retry-after"] ?? headers["Retry-After"];
+    }
+    if (!retryAfter)
+        return null;
+    // retry-after can be seconds (integer) or HTTP-date
+    const seconds = Number(retryAfter);
+    if (!Number.isNaN(seconds) && seconds > 0) {
+        return seconds * 1000;
+    }
+    // Try HTTP-date format
+    const dateMs = Date.parse(retryAfter);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, dateMs - Date.now());
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Main function
+// ---------------------------------------------------------------------------
+/**
+ * Execute a prompt with auth rotation and model failover.
+ *
+ * Each `session.prompt()` call benefits from SDK internal retry (429/5xx
+ * exponential backoff) before this function's failover logic triggers.
+ * When SDK retry is exhausted, this function:
+ * 1. Rotates API keys within the same provider
+ * 2. Falls back to alternate models in priority order
+ *
+ * Emits structured events for observability.
+ */
+export async function runWithModelRetry(params) {
+    const { session, messageText, promptImages, config, deps, timeoutConfig } = params;
+    const { eventBus, logger, authRotation, modelRegistry } = deps;
+    const fallbackModels = deps.fallbackModels ?? [];
+    // Use session-resolved model for diagnostic logs, falling back to agent config default
+    const displayModel = params.resolvedModel ?? `${config.provider}:${config.model}`;
+    // Track total elapsed time across all retry attempts
+    const retryStartMs = Date.now();
+    const maxRetries = 1 + (authRotation?.hasProfiles(config.provider) ? 1 : 0) + fallbackModels.length;
+    let promptError = undefined;
+    let promptSucceeded = false;
+    try {
+        // Primary prompt uses resettable timeout so tool completions can reset the
+        // deadline. Retry/fallback paths use the original withPromptTimeout (fresh timeout).
+        const resettable = withResettablePromptTimeout(session.prompt(messageText, {
+            expandPromptTemplates: false,
+            images: promptImages,
+        }), timeoutConfig.promptTimeoutMs, () => session.abort());
+        // Expose resetTimer to the caller (pi-executor) for wiring to tool execution events
+        deps.onResetTimer?.(resettable.resetTimer);
+        await resettable.promise;
+        promptSucceeded = true;
+        // Record success for auth rotation cooldown tracking
+        if (authRotation?.hasProfiles(config.provider)) {
+            authRotation.recordSuccess(config.provider);
+        }
+    }
+    catch (primaryError) {
+        promptError = primaryError;
+        logger.warn({
+            err: primaryError,
+            model: displayModel,
+            attempt: 1,
+            maxRetries,
+            totalElapsedMs: Date.now() - retryStartMs,
+            hint: "Primary model failed, attempting fallback",
+            errorKind: "dependency",
+        }, "Primary model prompt error");
+        // Emit prompt timeout event for observability
+        if (primaryError instanceof PromptTimeoutError) {
+            eventBus.emit("execution:prompt_timeout", {
+                agentId: deps.agentId ?? "unknown",
+                sessionKey: deps.sessionKey ?? "unknown",
+                timeoutMs: primaryError.timeoutMs,
+                timestamp: Date.now(),
+            });
+        }
+        // Feed failure into provider health monitor
+        deps.providerHealth?.recordFailure(config.provider, deps.agentId ?? "unknown");
+        // Cache-aware short retry -- preserve model string for cache hit.
+        // If the error is a rate limit (429/529) with a short retry-after,
+        // sleep and retry once with the SAME model before key rotation or fallback.
+        if (!promptSucceeded) {
+            const status = getErrorStatus(primaryError);
+            if (status === 429 || status === 529) {
+                const retryAfterMs = parseRetryAfterMs(primaryError);
+                if (retryAfterMs !== null && retryAfterMs < SHORT_RETRY_THRESHOLD_MS) {
+                    logger.debug({ retryAfterMs, model: displayModel, sessionKey: deps.sessionKey }, "Short retry -- preserving model for cache hit");
+                    await new Promise(r => setTimeout(r, retryAfterMs));
+                    try {
+                        await withPromptTimeout(session.prompt(messageText, { expandPromptTemplates: false, images: promptImages }), timeoutConfig.retryPromptTimeoutMs, () => session.abort());
+                        promptSucceeded = true;
+                        promptError = undefined;
+                        // Record success for auth rotation tracking
+                        if (authRotation?.hasProfiles(config.provider)) {
+                            authRotation.recordSuccess(config.provider);
+                        }
+                        logger.info({ retryAfterMs, model: displayModel }, "Short retry succeeded with same model");
+                    }
+                    catch (shortRetryError) {
+                        logger.debug({ err: shortRetryError, retryAfterMs }, "Short retry failed, falling through to rotation/fallback");
+                        promptError = shortRetryError;
+                        // Fall through to existing auth rotation / model fallback
+                    }
+                }
+            }
+        }
+        // Try rotating API key before falling back to a different model
+        if (!promptSucceeded && authRotation?.hasProfiles(config.provider)) {
+            const rotated = authRotation.rotateKey(config.provider);
+            if (rotated) {
+                logger.info({ provider: config.provider }, "Rotated API key for provider");
+                // Retry with the same model but rotated key
+                try {
+                    await withPromptTimeout(session.prompt(messageText, { expandPromptTemplates: false, images: promptImages }), timeoutConfig.retryPromptTimeoutMs, () => session.abort());
+                    promptSucceeded = true;
+                    promptError = undefined;
+                    authRotation.recordSuccess(config.provider);
+                    logger.info({ provider: config.provider }, "Retry with rotated key succeeded");
+                }
+                catch (rotatedKeyError) {
+                    promptError = rotatedKeyError;
+                    logger.warn({
+                        err: rotatedKeyError,
+                        attempt: 2,
+                        maxRetries,
+                        totalElapsedMs: Date.now() - retryStartMs,
+                        hint: "Rotated key also failed, proceeding to model fallback",
+                        errorKind: "auth",
+                    }, "Rotated key retry failed");
+                    // Emit prompt timeout event on rotation retry timeout
+                    if (rotatedKeyError instanceof PromptTimeoutError) {
+                        eventBus.emit("execution:prompt_timeout", {
+                            agentId: deps.agentId ?? "unknown",
+                            sessionKey: deps.sessionKey ?? "unknown",
+                            timeoutMs: rotatedKeyError.timeoutMs,
+                            timestamp: Date.now(),
+                        });
+                    }
+                    // Feed rotation failure into provider health monitor
+                    deps.providerHealth?.recordFailure(config.provider, deps.agentId ?? "unknown");
+                    // Fall through to model fallback loop below
+                }
+            }
+        }
+        // Fallback retry loop (skipped if key rotation already succeeded)
+        for (let i = 0; i < fallbackModels.length && !promptSucceeded; i++) {
+            const fallbackModelStr = fallbackModels[i];
+            try {
+                // Emit model:fallback_attempt event
+                const parsed = parseModelString(fallbackModelStr);
+                eventBus.emit("model:fallback_attempt", {
+                    fromProvider: config.provider,
+                    fromModel: config.model,
+                    toProvider: parsed?.provider ?? "unknown",
+                    toModel: parsed?.modelId ?? fallbackModelStr,
+                    error: promptError instanceof Error ? promptError.message : "unknown",
+                    attemptNumber: i + 1,
+                    timestamp: Date.now(),
+                });
+                logger.info({ fallbackModel: fallbackModelStr }, "Model fallback attempt");
+                // Resolve and set the fallback model
+                // Normalize fallback model ID before registry lookup
+                if (parsed) {
+                    const normalizedFallback = normalizeModelId(parsed.provider, parsed.modelId);
+                    const fallbackModelObj = modelRegistry.find(parsed.provider, normalizedFallback.modelId);
+                    if (fallbackModelObj) {
+                        await session.setModel(fallbackModelObj);
+                    }
+                }
+                await withPromptTimeout(session.prompt(messageText, {
+                    expandPromptTemplates: false,
+                    images: promptImages,
+                }), timeoutConfig.retryPromptTimeoutMs, () => session.abort());
+                promptSucceeded = true;
+                promptError = undefined;
+                logger.info({ fallbackModel: fallbackModelStr }, "Fallback model succeeded");
+                break;
+            }
+            catch (fallbackError) {
+                promptError = fallbackError;
+                // attempt = primary(1) + rotation(0 or 1) + fallback index(i+1)
+                const attemptNum = (authRotation?.hasProfiles(config.provider) ? 2 : 1) + i + 1;
+                logger.warn({
+                    err: fallbackError,
+                    fallbackModel: fallbackModelStr,
+                    attempt: attemptNum,
+                    maxRetries,
+                    totalElapsedMs: Date.now() - retryStartMs,
+                    hint: "Fallback model also failed",
+                    errorKind: "dependency",
+                }, "Fallback model prompt error");
+                // Emit prompt timeout event on fallback timeout
+                if (fallbackError instanceof PromptTimeoutError) {
+                    eventBus.emit("execution:prompt_timeout", {
+                        agentId: deps.agentId ?? "unknown",
+                        sessionKey: deps.sessionKey ?? "unknown",
+                        timeoutMs: fallbackError.timeoutMs,
+                        timestamp: Date.now(),
+                    });
+                }
+                // Feed fallback failure into provider health monitor
+                deps.providerHealth?.recordFailure(config.provider, deps.agentId ?? "unknown");
+                // Continue to next fallback
+            }
+        }
+        // Emit exhaustion event if all fallbacks failed
+        if (!promptSucceeded && fallbackModels.length > 0) {
+            eventBus.emit("model:fallback_exhausted", {
+                provider: config.provider,
+                model: config.model,
+                totalAttempts: fallbackModels.length + 1,
+                timestamp: Date.now(),
+            });
+        }
+    }
+    return { succeeded: promptSucceeded, error: promptError };
+}

package/node_modules/@comis/agent/dist/executor/overflow-recovery.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Overflow recovery: detects context-exhausted errors and automatically
+ * reduces context via two-phase strategy -- truncation of oversized tool
+ * results, then emergency compaction of old tool results to placeholders.
+ *
+ * Truncate oversized tool results to 30% of window
+ * Emergency compact all old tool results if still over budget
+ * Retry LLM call with reduced context (handled by caller)
+ * Log recovery outcome at INFO (handled by caller)
+ *
+ * @module
+ */
+import type { Message } from "@mariozechner/pi-ai";
+import type { ComisLogger } from "@comis/infra";
+import type { StreamFnWrapper } from "./stream-wrappers/types.js";
+export interface OverflowRecoveryConfig {
+    /** Max total context chars (from agent config). Used to compute 30% truncation target. */
+    maxContextChars: number;
+    /** Fraction of window to truncate oversized results to. Default: 0.3 (30%). */
+    truncationTargetRatio?: number;
+}
+export interface OverflowRecoveryResult {
+    /** Whether recovery succeeded and context was reduced. */
+    recovered: boolean;
+    /** Action taken: 'truncated' | 'compacted' | 'both' | 'none'. */
+    action: "truncated" | "compacted" | "both" | "none";
+    /** Total chars freed by recovery. */
+    charsFreed: number;
+    /** Messages array after recovery (for retry). Only present if recovered=true. */
+    recoveredMessages?: Message[];
+}
+/**
+ * Create an overflow recovery handler with the given config and logger.
+ *
+ * The `recover` method applies a two-phase strategy to reduce context size:
+ *
+ * Phase 1: Truncate oversized tool results to a fraction of the context window.
+ * Phase 2: Emergency-compact old tool results (before last assistant message)
+ *          to placeholder text if total still exceeds the budget.
+ *
+ * Does not mutate the input messages array.
+ *
+ * @param config - Recovery configuration (maxContextChars, truncationTargetRatio)
+ * @param logger - Logger for DEBUG output (caller handles INFO)
+ * @returns Object with `recover(messages)` method
+ */
+export declare function createOverflowRecovery(config: OverflowRecoveryConfig, logger: ComisLogger): {
+    recover(messages: readonly Message[]): OverflowRecoveryResult;
+};
+/**
+ * Create a one-shot StreamFnWrapper that applies overflow recovery on its
+ * first invocation, then passes through unchanged on subsequent calls.
+ *
+ * This wrapper is designed to be temporarily prepended to the wrapper chain
+ * (outermost position) when a context overflow error is detected. On the
+ * retry `session.prompt()` call, it intercepts the context, applies the
+ * two-phase recovery (truncation + emergency compaction), and delegates
+ * to the next wrapper with the reduced context. After firing once, it
+ * becomes a transparent pass-through.
+ *
+ * @param config - Recovery configuration (maxContextChars, truncationTargetRatio)
+ * @param logger - Logger for DEBUG/INFO output
+ * @returns A named StreamFnWrapper ("overflowRecoveryWrapper") and the
+ *          recovery result (populated after first invocation)
+ */
+export declare function createOverflowRecoveryWrapper(config: OverflowRecoveryConfig, logger: ComisLogger): {
+    wrapper: StreamFnWrapper;
+    getResult(): OverflowRecoveryResult | undefined;
+};

package/node_modules/@comis/agent/dist/executor/overflow-recovery.js

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Overflow recovery: detects context-exhausted errors and automatically
+ * reduces context via two-phase strategy -- truncation of oversized tool
+ * results, then emergency compaction of old tool results to placeholders.
+ *
+ * Truncate oversized tool results to 30% of window
+ * Emergency compact all old tool results if still over budget
+ * Retry LLM call with reduced context (handled by caller)
+ * Log recovery outcome at INFO (handled by caller)
+ *
+ * @module
+ */
+import { estimateMessageChars, estimateContextChars } from "../safety/token-estimator.js";
+import { createToolResultSizeGuard } from "../safety/tool-result-size-guard.js";
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create an overflow recovery handler with the given config and logger.
+ *
+ * The `recover` method applies a two-phase strategy to reduce context size:
+ *
+ * Phase 1: Truncate oversized tool results to a fraction of the context window.
+ * Phase 2: Emergency-compact old tool results (before last assistant message)
+ *          to placeholder text if total still exceeds the budget.
+ *
+ * Does not mutate the input messages array.
+ *
+ * @param config - Recovery configuration (maxContextChars, truncationTargetRatio)
+ * @param logger - Logger for DEBUG output (caller handles INFO)
+ * @returns Object with `recover(messages)` method
+ */
+export function createOverflowRecovery(config, logger) {
+    const sizeGuard = createToolResultSizeGuard();
+    return {
+        recover(messages) {
+            // Never mutate the input -- shallow copy individual entries as needed
+            const msgs = [...messages];
+            const truncationTarget = Math.floor(config.maxContextChars * (config.truncationTargetRatio ?? 0.3));
+            // ---------------------------------------------------------------
+            // Phase 1: Truncate oversized tool results
+            // ---------------------------------------------------------------
+            let phase1CharsFreed = 0;
+            for (let i = 0; i < msgs.length; i++) {
+                const msg = msgs[i];
+                if (msg.role !== "toolResult")
+                    continue;
+                const msgChars = estimateMessageChars(msg);
+                if (msgChars <= truncationTarget)
+                    continue;
+                // Truncate content blocks to truncationTarget chars
+                const result = sizeGuard.truncateIfNeeded(msg.content, truncationTarget);
+                if (!result.truncated)
+                    continue;
+                const newMsg = {
+                    ...msg,
+                    content: result.content,
+                };
+                const newChars = estimateMessageChars(newMsg);
+                phase1CharsFreed += msgChars - newChars;
+                msgs[i] = newMsg;
+                logger.debug({ toolName: msg.toolName, originalChars: msgChars, truncatedTo: newChars, index: i }, "Overflow recovery: tool result truncated");
+            }
+            // ---------------------------------------------------------------
+            // Phase 2: Emergency compact
+            // ---------------------------------------------------------------
+            let phase2CharsFreed = 0;
+            let totalChars = estimateContextChars(msgs);
+            if (totalChars > config.maxContextChars) {
+                // Find the last assistant message index (protection boundary)
+                let lastAssistantIndex = -1;
+                for (let i = msgs.length - 1; i >= 0; i--) {
+                    if (msgs[i].role === "assistant") {
+                        lastAssistantIndex = i;
+                        break;
+                    }
+                }
+                // Walk from oldest to newest, compacting tool results until within budget
+                for (let i = 0; i < msgs.length && totalChars > config.maxContextChars; i++) {
+                    const msg = msgs[i];
+                    if (msg.role !== "toolResult")
+                        continue;
+                    // Protect in-flight tool results (after last assistant message)
+                    if (lastAssistantIndex !== -1 && i > lastAssistantIndex)
+                        continue;
+                    const originalChars = estimateMessageChars(msg);
+                    const placeholder = `[Tool result from '${msg.toolName}' emergency-compacted for overflow recovery (was ${originalChars} chars)]`;
+                    const compactedMsg = {
+                        ...msg,
+                        content: [{ type: "text", text: placeholder }],
+                    };
+                    const newChars = estimateMessageChars(compactedMsg);
+                    const saved = originalChars - newChars;
+                    phase2CharsFreed += saved;
+                    totalChars -= saved;
+                    msgs[i] = compactedMsg;
+                    logger.debug({ toolName: msg.toolName, originalChars, index: i }, "Overflow recovery: tool result emergency-compacted");
+                }
+            }
+            // ---------------------------------------------------------------
+            // Build result
+            // ---------------------------------------------------------------
+            const charsFreed = phase1CharsFreed + phase2CharsFreed;
+            let action;
+            if (phase1CharsFreed > 0 && phase2CharsFreed > 0) {
+                action = "both";
+            }
+            else if (phase1CharsFreed > 0) {
+                action = "truncated";
+            }
+            else if (phase2CharsFreed > 0) {
+                action = "compacted";
+            }
+            else {
+                action = "none";
+            }
+            const recovered = charsFreed > 0;
+            return {
+                recovered,
+                action,
+                charsFreed,
+                ...(recovered ? { recoveredMessages: msgs } : {}),
+            };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// One-shot StreamFnWrapper for retry integration
+// ---------------------------------------------------------------------------
+/**
+ * Create a one-shot StreamFnWrapper that applies overflow recovery on its
+ * first invocation, then passes through unchanged on subsequent calls.
+ *
+ * This wrapper is designed to be temporarily prepended to the wrapper chain
+ * (outermost position) when a context overflow error is detected. On the
+ * retry `session.prompt()` call, it intercepts the context, applies the
+ * two-phase recovery (truncation + emergency compaction), and delegates
+ * to the next wrapper with the reduced context. After firing once, it
+ * becomes a transparent pass-through.
+ *
+ * @param config - Recovery configuration (maxContextChars, truncationTargetRatio)
+ * @param logger - Logger for DEBUG/INFO output
+ * @returns A named StreamFnWrapper ("overflowRecoveryWrapper") and the
+ *          recovery result (populated after first invocation)
+ */
+export function createOverflowRecoveryWrapper(config, logger) {
+    let fired = false;
+    let result;
+    const wrapper = function overflowRecoveryWrapper(next) {
+        return (model, context, options) => {
+            if (fired) {
+                // Already applied -- pass through unchanged
+                return next(model, context, options);
+            }
+            fired = true;
+            const recovery = createOverflowRecovery(config, logger);
+            result = recovery.recover(context.messages);
+            if (!result.recovered || !result.recoveredMessages) {
+                // Nothing to recover -- pass through unchanged
+                return next(model, context, options);
+            }
+            logger.info({
+                action: result.action,
+                charsFreed: result.charsFreed,
+                hint: `Overflow recovery ${result.action}: freed ${result.charsFreed} chars, retrying LLM call`,
+                errorKind: "resource",
+            }, "Context overflow recovery applied");
+            const recoveredContext = {
+                ...context,
+                messages: result.recoveredMessages,
+            };
+            return next(model, recoveredContext, options);
+        };
+    };
+    return {
+        wrapper,
+        getResult() {
+            return result;
+        },
+    };
+}

package/node_modules/@comis/agent/dist/executor/phase-filter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Phase-aware text extraction for multi-block LLM responses.
+ *
+ * The OpenAI Responses API returns text content blocks with a textSignature
+ * field encoding a phase ("commentary" or "final_answer"). Commentary
+ * blocks are internal model narration that must not reach users.
+ *
+ * @module
+ */
+/** Parse phase from a textSignature JSON string. */
+export declare function parsePhase(textSignature: unknown): string | undefined;
+/** True if a content block is user-visible text (not commentary). */
+export declare function isVisibleTextBlock(block: any): boolean;
+/**
+ * Extract user-visible text from the last assistant message in a session.
+ *
+ * When the last assistant message contains commentary-phase text blocks,
+ * filters them out and returns only visible text. Otherwise delegates to
+ * the SDK's getLastAssistantText() method.
+ */
+export declare function getVisibleAssistantText(session: any): string;

package/node_modules/@comis/agent/dist/executor/phase-filter.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Phase-aware text extraction for multi-block LLM responses.
+ *
+ * The OpenAI Responses API returns text content blocks with a textSignature
+ * field encoding a phase ("commentary" or "final_answer"). Commentary
+ * blocks are internal model narration that must not reach users.
+ *
+ * @module
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/** Parse phase from a textSignature JSON string. */
+export function parsePhase(textSignature) {
+    if (typeof textSignature !== "string" || textSignature[0] !== "{")
+        return undefined;
+    try {
+        const parsed = JSON.parse(textSignature);
+        if (parsed.v === 1)
+            return parsed.phase;
+    }
+    catch { /* malformed signature — treat as no phase */ }
+    return undefined;
+}
+/** True if a content block is user-visible text (not commentary). */
+export function isVisibleTextBlock(block) {
+    return (block?.type === "text" &&
+        typeof block.text === "string" &&
+        parsePhase(block.textSignature) !== "commentary");
+}
+/**
+ * Extract user-visible text from the last assistant message in a session.
+ *
+ * When the last assistant message contains commentary-phase text blocks,
+ * filters them out and returns only visible text. Otherwise delegates to
+ * the SDK's getLastAssistantText() method.
+ */
+export function getVisibleAssistantText(session) {
+    const messages = session?.messages;
+    // Find last non-aborted assistant message
+    const lastAssistant = Array.isArray(messages)
+        ? messages
+            .slice()
+            .reverse()
+            .find((m) => {
+            if (m.role !== "assistant")
+                return false;
+            if (m.stopReason === "aborted" && m.content?.length === 0)
+                return false;
+            return true;
+        })
+        : undefined;
+    // Only activate phase filtering when commentary blocks are present
+    const hasCommentary = lastAssistant?.content?.some((b) => b?.type === "text" && parsePhase(b.textSignature) === "commentary") ?? false;
+    if (hasCommentary) {
+        return lastAssistant.content
+            .filter(isVisibleTextBlock)
+            .map((b) => b.text)
+            .join("");
+    }
+    // No commentary — delegate to SDK method
+    return session?.getLastAssistantText?.() ?? "";
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */