loopengine 0.0.21 → 0.1.3

package/dist/core/http-notify-triggers/slack.d.ts

@@ -0,0 +1,21 @@
+import type { DurableApprover, Scope } from 'actauth';
+import type { DurableQuestionHandler } from '../agent-config.js';
+export declare class SlackNotifier implements DurableApprover, DurableQuestionHandler {
+    private readonly botToken;
+    private readonly channelId;
+    constructor(options: {
+        botToken: string;
+        channelId: string;
+    });
+    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
+        pendingId: string;
+    };
+    notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined): {
+        pendingId: string;
+    };
+    /** Public, not private: core/http-notifier.ts's own onRunStart/onRunFinish
+     * lifecycle sender for `channel: 'slack'` calls this directly with no
+     * `blocks` — a plain announcement, since there's nothing to resolve and
+     * so nothing to attach buttons to. */
+    postMessage(text: string, blocks?: unknown[]): void;
+}

package/dist/core/http-notify-triggers/slack.js

@@ -0,0 +1,91 @@
+// The *sending* half of a Slack-backed DurableApprover/DurableQuestionHandler,
+// real, maintained core/ code so AgentConfig.httpNotifier
+// (core/http-notifier.ts) can construct one directly for `channel:
+// 'slack'`, the same way it already constructs actauth's own
+// WebhookApprover for `channel: 'webhook'`. Not "DurableSlackNotifier":
+// unlike the Web/Webhook pair, there's no live "SlackNotifier" this name
+// could collide with (Slack's own *live* approver, actauth's
+// `SlackChatApprover`, has an entirely different name already) — durable is
+// just what a Slack-backed notifier defaults to being, so the name
+// doesn't need to say so.
+//
+// The *receiving* side — verifying a Slack Interactivity payload really
+// came from Slack, then dispatching approve/deny/answer back into
+// loopengine's own resolve/answer routes — deliberately stays out of
+// core and out of this class: that's an HTTP endpoint only the host can
+// deploy (it needs a route, a public URL, Slack app configuration), the
+// same "sending built for you, receiving you deploy" split every other
+// durable channel in this repo has. See
+// examples/notifier-handler/slack.ts's own `SlackNotifierHandler` for
+// that half.
+//
+// One class for both concerns, not two: nothing about what a Slack
+// integration needs to send is approval-specific or question-specific,
+// it's Slack-specific (the bot token, the channel, the chat.postMessage
+// call shape).
+import { randomUUID } from 'node:crypto';
+export class SlackNotifier {
+    botToken;
+    channelId;
+    constructor(options) {
+        this.botToken = options.botToken;
+        this.channelId = options.channelId;
+    }
+    requestDurableApproval(tool, args, scope, reason) {
+        const pendingId = randomUUID();
+        this.postMessage(`Approval requested: ${tool} on ${scope.tenant}/${scope.environment}/${scope.agent}`, [
+            {
+                type: 'section',
+                text: {
+                    type: 'mrkdwn',
+                    text: `*Approval requested*\n*tool:* ${tool}\n*args:* \`${JSON.stringify(args)}\`\n*scope:* ${scope.tenant}/${scope.environment}/${scope.agent}\n*reason:* ${reason}`,
+                },
+            },
+            {
+                type: 'actions',
+                elements: [
+                    { type: 'button', text: { type: 'plain_text', text: 'Approve' }, style: 'primary', action_id: 'approve', value: pendingId },
+                    { type: 'button', text: { type: 'plain_text', text: 'Deny' }, style: 'danger', action_id: 'deny', value: pendingId },
+                ],
+            },
+        ]);
+        return { pendingId };
+    }
+    notifyPendingQuestion(question, options, agent, sessionId) {
+        const pendingId = randomUUID();
+        const optionButtons = (options ?? []).map((option) => ({
+            type: 'button',
+            text: { type: 'plain_text', text: option },
+            value: JSON.stringify({ pendingId, answer: option }),
+            action_id: 'answer_option',
+        }));
+        this.postMessage(`Question from ${agent}: ${question}`, [
+            { type: 'section', text: { type: 'mrkdwn', text: `*Question from ${agent}${sessionId ? ` (session ${sessionId})` : ''}:*\n${question}` } },
+            { type: 'actions', elements: [...optionButtons, { type: 'button', text: { type: 'plain_text', text: 'Other…' }, action_id: 'open_answer_modal', value: pendingId }] },
+        ]);
+        return { pendingId };
+    }
+    /** Public, not private: core/http-notifier.ts's own onRunStart/onRunFinish
+     * lifecycle sender for `channel: 'slack'` calls this directly with no
+     * `blocks` — a plain announcement, since there's nothing to resolve and
+     * so nothing to attach buttons to. */
+    postMessage(text, blocks) {
+        // Not awaited — both requestDurableApproval/notifyPendingQuestion
+        // above return immediately, by contract (see DurableApprover's own
+        // doc comment); a delivery failure here has no synchronous way to
+        // surface to either caller, so it's logged instead of thrown.
+        fetch('https://slack.com/api/chat.postMessage', {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${this.botToken}`, 'content-type': 'application/json; charset=utf-8' },
+            body: JSON.stringify({ channel: this.channelId, text, ...(blocks ? { blocks } : {}) }),
+        })
+            .then((res) => res.json())
+            .then((body) => {
+            if (!body.ok)
+                console.error('[loopengine] SlackNotifier: chat.postMessage failed:', body.error);
+        })
+            .catch((err) => {
+            console.error('[loopengine] SlackNotifier: chat.postMessage failed:', err);
+        });
+    }
+}

package/dist/core/http-notify-triggers/webhook.d.ts

@@ -0,0 +1,27 @@
+import type { DurableApprover, Scope } from 'actauth';
+import type { DurableQuestionHandler } from '../agent-config.js';
+export declare class WebhookNotifier implements DurableApprover, DurableQuestionHandler {
+    private readonly webhookUrl;
+    private readonly signingSecret;
+    constructor(options: {
+        webhookUrl: string;
+        signingSecret: string;
+    });
+    requestDurableApproval(tool: string, args: Record<string, unknown>, scope: Scope, reason: string): {
+        pendingId: string;
+    };
+    notifyPendingQuestion(question: string, options: string[] | undefined, agent: string, sessionId: string | undefined): {
+        pendingId: string;
+    };
+    /** Shared by both methods above — the one place either used to
+     * independently build the same signed fetch() call. Not awaited by its
+     * own callers, same fire-and-forget contract each had on its own: both
+     * requestDurableApproval/notifyPendingQuestion return immediately, by
+     * contract (see DurableApprover/DurableQuestionHandler's own doc
+     * comments), so a delivery failure here has no synchronous way to
+     * surface to the caller — logged instead of thrown, since throwing
+     * would blow up a decision that has already, correctly, been recorded
+     * as pending. */
+    private post;
+}
+export declare function postLifecycleWebhook(webhookUrl: string, webhookSecret: string, event: 'run_start' | 'run_finish', context: Record<string, unknown>): void;

package/dist/core/http-notify-triggers/webhook.js

@@ -0,0 +1,94 @@
+// The generic-webhook channel's sending side, one class for both
+// concerns — same "it's channel-specific, not concern-specific" shape
+// slack.ts/lark.ts/email.ts already have, not the "two already-shipped
+// classes from two separate packages" split this file used to be (see
+// git history): approval-sending used to be actauth's own
+// `WebhookApprover`, question-sending loopengine's own
+// `WebhookQuestionHandler` (`core/system-tools/ask_user.ts`) — genuinely
+// separate classes, since `actauth`'s `Gate` has no concept of
+// `system_ask_user` questions at all (see HUMAN_IN_THE_LOOP.md's
+// "Durable questions" section). Nothing about *sending* a signed webhook
+// POST is actauth-specific, though, once you stop assuming the approval
+// half has to live in actauth's own package — both halves are the exact
+// same HMAC-SHA256-over-the-raw-body scheme, just under different
+// headers, so merging them removes real duplication (one class, one
+// constructor, one place either concern's own webhook target/secret is
+// held) rather than just looking simpler on paper.
+//
+// `actauth`'s own `WebhookApprover` still exists and is unaffected —
+// this is loopengine's own implementation of the same `DurableApprover`
+// interface, not a fork of actauth's class; a standalone actauth
+// consumer (no loopengine involved) still has and should use actauth's
+// own. loopengine no longer imports it anywhere, since everywhere it
+// used to (this file, and adapters/http.ts's own deployment-wide
+// default) now constructs one `WebhookNotifier` instead.
+//
+// The signed payloads below are wire-compatible with what actauth's
+// `WebhookApprover`/loopengine's former `WebhookQuestionHandler` already
+// sent — same fields, same `X-Actauth-Signature`/`X-Askuser-Signature`
+// headers — so an existing receiving-side deployment (this repo's own
+// `examples/notifier-handler/webhook.ts`, or a host's own) needs no
+// changes; only where the bytes come from moved.
+//
+// `postLifecycleWebhook` below is the third, genuinely new piece:
+// `onRunStart`/`onRunFinish` have no shipped class on either side, for
+// any channel (see this repo's own history — agents/customer-service/index.ts
+// used to hand-write this exact function before `AgentConfig.httpNotifier`
+// existed). Same signing scheme, under its own `X-Lifecycle-Signature`
+// header so a receiver can tell a lifecycle event apart from a
+// pending-approval/pending-question one hitting the same URL (see
+// examples/notifier-handler/webhook.ts's own `verifyWebhookNotifier` for
+// the receiving side of all three).
+import { createHmac, randomUUID } from 'node:crypto';
+export class WebhookNotifier {
+    webhookUrl;
+    signingSecret;
+    constructor(options) {
+        this.webhookUrl = options.webhookUrl;
+        this.signingSecret = options.signingSecret;
+    }
+    requestDurableApproval(tool, args, scope, reason) {
+        const pendingId = randomUUID();
+        const requestedAt = new Date().toISOString();
+        const body = JSON.stringify({ pendingId, tool, args, scope, reason, requestedAt });
+        this.post(body, 'X-Actauth-Signature', pendingId);
+        return { pendingId };
+    }
+    notifyPendingQuestion(question, options, agent, sessionId) {
+        const pendingId = randomUUID();
+        const requestedAt = new Date().toISOString();
+        const body = JSON.stringify({ pendingId, question, options, agent, sessionId, requestedAt });
+        this.post(body, 'X-Askuser-Signature', pendingId);
+        return { pendingId };
+    }
+    /** Shared by both methods above — the one place either used to
+     * independently build the same signed fetch() call. Not awaited by its
+     * own callers, same fire-and-forget contract each had on its own: both
+     * requestDurableApproval/notifyPendingQuestion return immediately, by
+     * contract (see DurableApprover/DurableQuestionHandler's own doc
+     * comments), so a delivery failure here has no synchronous way to
+     * surface to the caller — logged instead of thrown, since throwing
+     * would blow up a decision that has already, correctly, been recorded
+     * as pending. */
+    post(body, signatureHeader, pendingId) {
+        const signature = `sha256=${createHmac('sha256', this.signingSecret).update(body).digest('hex')}`;
+        fetch(this.webhookUrl, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', [signatureHeader]: signature },
+            body,
+        }).catch((err) => {
+            console.error(`[loopengine] WebhookNotifier: webhook delivery failed for pendingId '${pendingId}':`, err);
+        });
+    }
+}
+export function postLifecycleWebhook(webhookUrl, webhookSecret, event, context) {
+    const payload = JSON.stringify({ event, ...context, occurredAt: new Date().toISOString() });
+    const signature = `sha256=${createHmac('sha256', webhookSecret).update(payload).digest('hex')}`;
+    fetch(webhookUrl, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'X-Lifecycle-Signature': signature },
+        body: payload,
+    }).catch((err) => {
+        console.error(`[loopengine] httpNotifier ${event} webhook delivery failed:`, err);
+    });
+}

package/dist/core/loop-events.d.ts

@@ -109,6 +109,26 @@ export interface LoopDeniedEvent {
     type: 'loop:denied';
     deniedTools: string[];
 }
+/** At least one requested tool call is durably pending a DurableApprover
+ * decision — the turn stops right there too, but unlike loop:denied this
+ * isn't a rejection: any already-approved sibling call in the same batch
+ * still ran (see run-agent.ts's own bucket-then-execute), and the turn
+ * resumes (via resumeAgent) once every pendingId here is resolved. See
+ * HUMAN_IN_THE_LOOP.md for the full design. */
+export interface PendingApprovalEvent {
+    type: 'loop:pending_approval';
+    pendingIds: string[];
+}
+/** The question-side sibling of PendingApprovalEvent above — at least one
+ * `system_ask_user` call is durably pending a DurableQuestionHandler
+ * (see HUMAN_IN_THE_LOOP.md's "Durable questions" section), fired only
+ * when nothing else in the same batch is a pending *approval* (a mixed
+ * batch reports PendingApprovalEvent instead — see
+ * RunAgentResult.stopReason's own doc comment for why). */
+export interface PendingQuestionEvent {
+    type: 'loop:pending_question';
+    pendingIds: string[];
+}
 /** The loop's own final answer — the model produced text with no more
  * tool_use blocks. Distinct from the adapter-level 'done' below: this
  * only ever means a genuine finish, never a synthetic max_turns/denied
@@ -120,7 +140,7 @@ export interface LoopDoneEvent {
 /** Every event runAgent() itself can emit via RunAgentOptions.onEvent —
  * not the adapter-synthesized ones below, which no caller of runAgent()
  * itself ever produces. */
-export type RunAgentLoopEvent = BudgetCheckEvent | PromptCompactionEvent | AssistantTextEvent | ActauthDecisionEvent | ToolStartedEvent | ToolResultEvent | ToolLaneResultEvent | SkillLoadEvent | LoopSkippedEvent | LoopMaxTurnsEvent | LoopDeniedEvent | LoopDoneEvent;
+export type RunAgentLoopEvent = BudgetCheckEvent | PromptCompactionEvent | AssistantTextEvent | ActauthDecisionEvent | ToolStartedEvent | ToolResultEvent | ToolLaneResultEvent | SkillLoadEvent | LoopSkippedEvent | LoopMaxTurnsEvent | LoopDeniedEvent | PendingApprovalEvent | PendingQuestionEvent | LoopDoneEvent;
 /** adapters/http.ts echoing back which session id this turn used — first
  * event of every streamed turn, so a caller that omitted sessionId can
  * capture what got generated. Not something runAgent() itself knows
@@ -143,14 +163,18 @@ export type ApprovalPendingEvent = {
 export type QuestionPendingEvent = {
     type: 'question:pending';
 } & PendingQuestion;
-/** The turn is over — covers a genuine finish and both synthetic
- * stopReasons (max_turns/denied) alike, the one event every caller can
- * treat as "nothing more is coming" regardless of which of the three it
- * was (see RunAgentResult.stopReason's own doc comment). */
+/** This turn/request is over — covers a genuine finish and all four
+ * synthetic stopReasons (max_turns/denied/pending_approval/pending_question)
+ * alike, the one event every caller can treat as "nothing more is coming
+ * on this response" regardless of which it was (see
+ * RunAgentResult.stopReason's own doc comment). pending_approval/
+ * pending_question, like denied, don't mean the conversation itself is
+ * over — only this turn; it resumes later via a separate resolve call,
+ * not by continuing to read this same response. */
 export interface DoneEvent {
     type: 'done';
     text: string;
-    stopReason?: 'max_turns' | 'denied';
+    stopReason?: 'max_turns' | 'denied' | 'pending_approval' | 'pending_question';
 }
 /** Something failed after the response was already committed (SSE
  * headers sent, or a background turn already running) — surfaced in-band

package/dist/core/model-calls/openai-model-call.js

@@ -35,22 +35,31 @@ export function toMessageParams(message) {
             .map((block) => block.text ?? '')
             .join('');
         const toolUseBlocks = message.content.filter((block) => block.type === 'tool_use');
-        return [
-            {
-                role: 'assistant',
-                // Required unless tool_calls is set — an empty string here (no
-                // text, only tool calls) is rejected by the API, so this must be
-                // null, not ''.
-                content: text || null,
-                tool_calls: toolUseBlocks.length
-                    ? toolUseBlocks.map((block) => ({
-                        id: block.id,
-                        type: 'function',
-                        function: { name: block.name, arguments: JSON.stringify(block.input ?? {}) },
-                    }))
-                    : undefined,
-            },
-        ];
+        // DeepSeek's thinking mode requires the exact reasoning that produced
+        // this message — tool_calls included — echoed back verbatim on every
+        // later request that still includes this message, for as long as the
+        // conversation keeps passing `tools` at all (confirmed live: dropping
+        // it gets the whole request rejected with a 400, not just ignored).
+        // Round-tripped opaquely here, never inspected — see
+        // ModelContentBlock's own 'thinking' block doc comment (run-agent.ts).
+        const thinkingBlock = message.content.find((block) => block.type === 'thinking');
+        const result = {
+            role: 'assistant',
+            // Required unless tool_calls is set — an empty string here (no
+            // text, only tool calls) is rejected by the API, so this must be
+            // null, not ''.
+            content: text || null,
+            tool_calls: toolUseBlocks.length
+                ? toolUseBlocks.map((block) => ({
+                    id: block.id,
+                    type: 'function',
+                    function: { name: block.name, arguments: JSON.stringify(block.input ?? {}) },
+                }))
+                : undefined,
+        };
+        if (thinkingBlock?.text)
+            result.reasoning_content = thinkingBlock.text;
+        return [result];
     }
     // Every non-assistant, block-structured Message this loop ever builds is
     // one turn's tool_result blocks bundled together (see run-agent.ts's
@@ -72,6 +81,13 @@ export function toStopReason(finishReason) {
 }
 export function toModelResponse(choice) {
     const content = [];
+    // Ordered first — reasoning precedes the response it produced. Only
+    // DeepSeek's thinking-mode responses carry this; a plain response
+    // simply has no reasoning_content, so nothing gets pushed and
+    // toMessageParams above has nothing to echo back for this message.
+    const reasoningContent = choice.message.reasoning_content;
+    if (reasoningContent)
+        content.push({ type: 'thinking', text: reasoningContent });
     if (choice.message.content)
         content.push({ type: 'text', text: choice.message.content });
     for (const call of choice.message.tool_calls ?? []) {

package/dist/core/recovery.d.ts

@@ -0,0 +1,49 @@
+export type RecoveryAction = 'prompt_too_long' | 'media_too_large' | 'truncated_retry';
+export interface RecoveryResult<T> {
+    value: T;
+    /** Ordered log of what happened, empty if the first attempt just worked. */
+    recoveries: RecoveryAction[];
+    /** True if the final result is still truncated after exhausting retries
+     * (or if no onTruncated hook was provided at all). */
+    truncated: boolean;
+}
+export interface RecoveryOptions<TMessages> {
+    /** Called when a request is rejected as too large. Return a smaller
+     * message list to retry with. No default — an unhandled too-long
+     * error propagates rather than being guessed at. */
+    onPromptTooLong?: (messages: TMessages) => TMessages | Promise<TMessages>;
+    /** Called when a request is rejected for oversized media. Same
+     * fail-loud default as onPromptTooLong. */
+    onMediaTooLarge?: (messages: TMessages) => TMessages | Promise<TMessages>;
+    /** Called when a response comes back truncated. Return adjusted
+     * messages to retry with, or undefined to stop and accept the
+     * truncated result. */
+    onTruncated?: (messages: TMessages, attempt: number) => TMessages | undefined | Promise<TMessages | undefined>;
+    /** Cap on truncation-recovery attempts. Default 2. */
+    maxTruncationRetries?: number;
+    /** Cap on prompt-too-long/media-too-large recovery attempts combined —
+     * a safety limit so a broken recovery hook can't loop forever burning
+     * API calls. Default 3. */
+    maxRecoveryAttempts?: number;
+    /** Override the default Anthropic/OpenAI-shaped error classifier. */
+    isPromptTooLong?: (error: unknown) => boolean;
+    isMediaTooLarge?: (error: unknown) => boolean;
+    isTruncated?: (response: unknown) => boolean;
+}
+export declare function defaultIsPromptTooLong(error: unknown): boolean;
+export declare function defaultIsMediaTooLarge(error: unknown): boolean;
+export declare function defaultIsTruncated(response: unknown): boolean;
+/** Wraps a model API call with reactive recovery — see this file's own
+ * header comment for the three cases it covers. */
+export declare class Recovery<TMessages> {
+    private readonly onPromptTooLong?;
+    private readonly onMediaTooLarge?;
+    private readonly onTruncated?;
+    private readonly maxTruncationRetries;
+    private readonly maxRecoveryAttempts;
+    private readonly isPromptTooLong;
+    private readonly isMediaTooLarge;
+    private readonly isTruncated;
+    constructor(options?: RecoveryOptions<TMessages>);
+    call<T>(fn: (messages: TMessages) => Promise<T>, messages: TMessages): Promise<RecoveryResult<T>>;
+}

package/dist/core/recovery.js

@@ -0,0 +1,124 @@
+/** Heuristic defaults covering Anthropic- and OpenAI-shaped errors and
+ * responses. Deliberately not exhaustive — override via RecoveryOptions
+ * for other providers or stricter matching. Duck-typed on purpose, so
+ * this stays independent of either SDK's own error/response classes. */
+function messageOf(error) {
+    if (error && typeof error === 'object' && 'message' in error) {
+        return String(error.message).toLowerCase();
+    }
+    return '';
+}
+function codeOf(error) {
+    if (error && typeof error === 'object' && 'code' in error) {
+        return String(error.code).toLowerCase();
+    }
+    return '';
+}
+function statusOf(error) {
+    if (error && typeof error === 'object' && 'status' in error) {
+        const status = Number(error.status);
+        return Number.isNaN(status) ? undefined : status;
+    }
+    return undefined;
+}
+const TOO_LONG_PATTERNS = ['prompt is too long', 'too many tokens', 'maximum context length', 'context_length_exceeded', 'input length', 'exceeds the maximum'];
+export function defaultIsPromptTooLong(error) {
+    const status = statusOf(error);
+    if (status !== 400 && status !== 413)
+        return false;
+    if (codeOf(error) === 'context_length_exceeded')
+        return true;
+    const message = messageOf(error);
+    return TOO_LONG_PATTERNS.some((pattern) => message.includes(pattern));
+}
+const MEDIA_PATTERNS = ['image', 'media', 'file size', 'attachment'];
+const SIZE_PATTERNS = ['too large', 'exceeds', 'size limit', 'too big'];
+export function defaultIsMediaTooLarge(error) {
+    const status = statusOf(error);
+    if (status !== 400 && status !== 413)
+        return false;
+    const message = messageOf(error);
+    const mentionsMedia = MEDIA_PATTERNS.some((pattern) => message.includes(pattern));
+    const mentionsSize = SIZE_PATTERNS.some((pattern) => message.includes(pattern));
+    return mentionsMedia && mentionsSize;
+}
+export function defaultIsTruncated(response) {
+    if (!response || typeof response !== 'object')
+        return false;
+    const r = response;
+    if (r.stop_reason === 'max_tokens')
+        return true; // Anthropic
+    const choices = r.choices;
+    if (Array.isArray(choices) && choices[0] && typeof choices[0] === 'object') {
+        const choice = choices[0];
+        if (choice.finish_reason === 'length')
+            return true; // OpenAI
+    }
+    return false;
+}
+/** Wraps a model API call with reactive recovery — see this file's own
+ * header comment for the three cases it covers. */
+export class Recovery {
+    onPromptTooLong;
+    onMediaTooLarge;
+    onTruncated;
+    maxTruncationRetries;
+    maxRecoveryAttempts;
+    isPromptTooLong;
+    isMediaTooLarge;
+    isTruncated;
+    constructor(options = {}) {
+        this.onPromptTooLong = options.onPromptTooLong;
+        this.onMediaTooLarge = options.onMediaTooLarge;
+        this.onTruncated = options.onTruncated;
+        this.maxTruncationRetries = options.maxTruncationRetries ?? 2;
+        this.maxRecoveryAttempts = options.maxRecoveryAttempts ?? 3;
+        this.isPromptTooLong = options.isPromptTooLong ?? defaultIsPromptTooLong;
+        this.isMediaTooLarge = options.isMediaTooLarge ?? defaultIsMediaTooLarge;
+        this.isTruncated = options.isTruncated ?? defaultIsTruncated;
+    }
+    async call(fn, messages) {
+        let currentMessages = messages;
+        const recoveries = [];
+        let value;
+        // Stage 1: recover from prompt-too-long / media-too-large, capped so
+        // a broken recovery hook can't loop forever burning API calls.
+        let attempts = 0;
+        for (;;) {
+            try {
+                value = await fn(currentMessages);
+                break;
+            }
+            catch (error) {
+                attempts++;
+                if (attempts > this.maxRecoveryAttempts)
+                    throw error;
+                if (this.isPromptTooLong(error) && this.onPromptTooLong) {
+                    currentMessages = await this.onPromptTooLong(currentMessages);
+                    recoveries.push('prompt_too_long');
+                    continue;
+                }
+                if (this.isMediaTooLarge(error) && this.onMediaTooLarge) {
+                    currentMessages = await this.onMediaTooLarge(currentMessages);
+                    recoveries.push('media_too_large');
+                    continue;
+                }
+                throw error;
+            }
+        }
+        // Stage 2: recover from output truncation, bounded.
+        let truncated = this.isTruncated(value);
+        let truncationAttempt = 0;
+        while (truncated && this.onTruncated && truncationAttempt < this.maxTruncationRetries) {
+            const nextMessages = await this.onTruncated(currentMessages, truncationAttempt);
+            if (nextMessages === undefined)
+                break;
+            currentMessages = nextMessages;
+            value = await fn(currentMessages);
+            recoveries.push('truncated_retry');
+            truncated = this.isTruncated(value);
+            truncationAttempt++;
+        }
+        return { value, recoveries, truncated };
+    }
+}