loopengine 0.0.20 → 0.1.2

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

@@ -13,7 +13,7 @@
 //
 // stop_reason is normalized to the vocabulary anthropic-model-call.ts
 // already established ('end_turn' / 'tool_use' / 'max_tokens') rather than
-// passed through as OpenAI's own finish_reason strings — reflowkit's
+// passed through as OpenAI's own finish_reason strings — recovery.ts's
 // defaultIsTruncated checks a translated ModelResponse for stop_reason ===
 // 'max_tokens', so a provider-agnostic caller wiring up onTruncated later
 // gets the same behavior regardless of which ModelCall is plugged in.
@@ -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 };
+    }
+}

package/dist/core/run-agent.d.ts

@@ -1,5 +1,5 @@
 import { RuleSet, type Approver } from 'actauth';
-import type { AgentConfig, ToolDefinition, ToolSchema } from '#core/agent-config.js';
+import type { AgentConfig, ApproverChannel, QuestionHandler, ToolDefinition, ToolSchema } from '#core/agent-config.js';
 import { type PendingQuestion } from './system-tools/index.js';
 import type { LoopEvent } from './loop-events.js';
 export { systemTools } from './system-tools/index.js';
@@ -8,7 +8,18 @@ export declare const systemSkillsDir: string;
 export declare function dedupeToolsByName(list: ToolDefinition[]): ToolDefinition[];
 export interface ModelContentBlock {
     type: string;
-    /** text blocks. */
+    /** text blocks, and thinking blocks (a model's own chain-of-thought,
+     * e.g. DeepSeek's `reasoning_content` sibling field, or — if a
+     * model-calls/* adapter ever opts into it — Anthropic's own `thinking`
+     * content block). Reuses this same field rather than adding a
+     * thinking-only one, since both are just "a string of the model's own
+     * words." Carried opaquely: loopengine never reads or reasons about
+     * this text itself, only round-trips it back verbatim on the next
+     * request that includes this message — some reasoning-mode providers
+     * (DeepSeek's thinking mode, confirmed live; Anthropic's extended
+     * thinking, documented the same way) reject the request outright if a
+     * prior turn's reasoning gets silently dropped on the way back in,
+     * once the conversation has tool_calls in it. */
     text?: string;
     /** tool_use blocks: this call's own id (referenced by a later tool_result). */
     id?: string;
@@ -35,7 +46,7 @@ export interface ModelResponse {
     content: ModelContentBlock[];
 }
 /** loopengine's own conversation-message type — a superset of
- * ContextClip's `{role, content: string}`: `content` can also be a
+ * budget.ts's own `{role, content: string}`: `content` can also be a
  * `ModelContentBlock[]`, the same block shape `ModelResponse.content`
  * already used, so a model's tool_use requests and this loop's
  * tool_result replies round-trip with real per-call identity
@@ -73,15 +84,32 @@ export interface RunAgentOptions {
      * pending question can't be session-scoped — still fine, it's still
      * agent-scoped either way. */
     sessionId?: string;
-    /** Default Approver for this call's 'ask' decisions, when
-     * AgentConfig.approver isn't set — the seam an adapter uses to pick
-     * whichever approver actually fits its own channel (ConsoleApprover for
-     * a real terminal, a web-based one for an HTTP-served conversation,
-     * ...) without every agent needing to hardcode one itself. An explicit
-     * AgentConfig.approver still wins outright over this when the agent
-     * author set one on purpose — same as it always has (see Gate
-     * construction below) — this only fills in when that's absent. Default,
-     * if neither is given: actauth's own ConsoleApprover, same as always. */
+    /** Which channel this call is on — checked below against `'http'`,
+     * the only value `AgentConfig.httpNotifier` ever matches (see that
+     * field's own doc comment). Omitted (a standalone script, a bespoke
+     * dispatcher with no fixed channel identity) means `httpNotifier` is
+     * never consulted at all — `approver` below is the only thing that
+     * applies. */
+    channel?: ApproverChannel;
+    /** This call's own default Approver for 'ask' decisions, when
+     * `AgentConfig.httpNotifier` doesn't supply one (only possible on the
+     * `http` channel, and only when it lists `'approval'`) — the seam an
+     * adapter uses to pick whichever approver actually fits its own channel
+     * (ConsoleApprover for a real terminal, a fresh WebchatApprover per
+     * streamed turn, a WebhookApprover for a background dispatcher,
+     * ...) without every agent needing to hardcode one itself. `http`'s own
+     * `httpNotifier`, if it covers `'approval'`, still wins outright over
+     * this — the agent author's own explicit choice *for that channel*
+     * beats whatever the adapter would otherwise default to (see Gate
+     * construction below) — `cli`/`http_stream` have no such override at
+     * all, so this is the only thing that ever applies there. Default, if
+     * neither is given: actauth's own ConsoleApprover, same as always.
+     *
+     * Can be a DurableApprover (WebhookApprover, ...) instead of a live
+     * one — see HUMAN_IN_THE_LOOP.md. A background/cron dispatcher calling
+     * runAgent() directly is exactly this same kind of caller, and should
+     * pass its own durable default here the same way adapters/http.ts's
+     * stream route passes a fresh WebchatApprover. */
     approver?: Approver;
     /** Fired the instant the system ask_user tool registers a new pending
      * question — this is the seam that decides between a real, answerable
@@ -100,6 +128,30 @@ export interface RunAgentOptions {
      * that genuinely has an answering mechanism (adapters/http.ts, for both
      * its routes) should pass this. */
     onQuestionPending?: (question: PendingQuestion) => void;
+    /** This call's own default QuestionHandler — question-side sibling of
+     * `approver` above, same precedence (`AgentConfig.httpNotifier`, when it
+     * covers `'question'` on the `http` channel, still wins outright over
+     * this) and the same `LiveQuestionHandler | DurableQuestionHandler`
+     * union `approver` itself is, duck-typed the same way (see
+     * `isDurableQuestionHandler`). Default, if neither this nor
+     * `httpNotifier` supplies one: `new CliQuestionHandler()` — same role
+     * `new ConsoleApprover()` plays for `approver`.
+     *
+     * One real, current asymmetry versus `approver`: only the *durable*
+     * half of this union is actually wired into the loop below — a
+     * `system_ask_user` call only ever consults this field to decide
+     * live-vs-durable; the live case still always falls through to
+     * `onQuestionPending`/the tool's own independent live resolution
+     * (unchanged from before this field existed), never actually calling
+     * a live `QuestionHandler` resolved here. See HUMAN_IN_THE_LOOP.md's
+     * "Durable questions" section for why: fully wiring the live half too
+     * would mean moving system_ask_user's answer-collection inline into
+     * this loop (changing today's batching semantics — right now a
+     * pending question is deferred past the whole tool_use batch scan,
+     * unlike a live approval) and a breaking change to createAskUserTool's
+     * own signature — deliberately deferred rather than done half-carefully
+     * here. */
+    questionHandler?: QuestionHandler;
 }
 export interface RunAgentResult {
     /** Final assistant text for this turn. */
@@ -109,7 +161,7 @@ export interface RunAgentResult {
      * the caller: store/transmit it, don't inspect or mutate it. */
     history: Message[];
     /** Exactly what this turn added — safe to durably append regardless of
-     * whether ContextClip recovery reshaped `history` mid-turn. A caller
+     * whether compaction.ts's own recovery reshaped `history` mid-turn. A caller
      * that persists conversations (see session-store.ts) should use this
      * instead of diffing `history` by length against what it loaded: that
      * only works if `history` only ever grows, which stops being true the
@@ -132,8 +184,62 @@ export interface RunAgentResult {
      * model requested in the same turn, even one already approved, never
      * runs either (see the loop's own body); it gets a "skipped", not a
      * "denied", tool_result, since it was never evaluated against its own
-     * rule. */
-    stopReason?: 'max_turns' | 'denied';
+     * rule.
+     *
+     * 'pending_approval' / 'pending_question': at least one requested tool
+     * call is durably pending a DurableApprover decision, or at least one
+     * `system_ask_user` call is durably pending a DurableQuestionHandler
+     * answer (see HUMAN_IN_THE_LOOP.md) — same "the whole batch stops here"
+     * shape as 'denied', except this isn't a rejection: any already-run
+     * sibling call in the same batch still ran (see the loop's own
+     * bucket-then-execute), captured in `pending.resultsSoFar`, and the
+     * turn resumes later via resumeAgent() once every pendingId in
+     * `pending.outstanding` is resolved — not by sending another message
+     * the way 'denied' recovers. A batch can mix both kinds (a gated tool
+     * call and an `system_ask_user` call in the same model response) — both
+     * land in the same `pending.outstanding`, since the one dangling
+     * assistant tool_use message can only ever get one completing
+     * tool_result message; `stopReason` reports 'pending_approval' for that
+     * mixed case too (only a batch with *no* approval items at all reports
+     * 'pending_question'). `newMessages` ends at the dangling assistant
+     * tool_use message, same crash-recovery shape session-store.ts's own
+     * hasUnresolvedToolCall already detects — entered on purpose here,
+     * not by accident. runAgent() does no I/O (see this module's own
+     * header comment): turning `pending` into a durable TurnCheckpoint
+     * (core/durable-approvals.ts) is the caller's job. */
+    stopReason?: 'max_turns' | 'denied' | 'pending_approval' | 'pending_question';
+    /** Set only when stopReason is 'pending_approval' or 'pending_question'. */
+    pending?: {
+        /** tool_result blocks already computed this batch — safely
+         * auto-allowed calls that ran immediately despite a gated/asked
+         * sibling still being outstanding. Not yet pushed into `newMessages`/
+         * `history`: incomplete until every outstanding item below is
+         * resolved too, and a real model API expects one complete
+         * tool_result message per assistant tool_use message, not a partial
+         * one now and a follow-up later. */
+        resultsSoFar: ModelContentBlock[];
+        /** One entry per tool call still awaiting a durable decision, keyed
+         * by the pendingId its DurableApprover/DurableQuestionHandler handed
+         * out — what an incoming resolution actually names. `kind`
+         * distinguishes which of the two this is — for 'question', `args` is
+         * `{ question, options }` and `reason` is the question text itself
+         * (there's no separate ActAuth "reason" for a question the way there
+         * is for a gated tool call's decision). */
+        outstanding: PendingItem[];
+    };
+}
+/** One requested call still awaiting a durable decision — either a gated
+ * tool call (`kind: 'approval'`) or a `system_ask_user` call (`kind:
+ * 'question'`), unified into one array so a batch mixing both shares
+ * exactly one checkpoint (see RunAgentResult.stopReason's own doc
+ * comment for why that has to be true). */
+export interface PendingItem {
+    kind: 'approval' | 'question';
+    toolUseId: string;
+    tool: string;
+    args: Record<string, unknown>;
+    pendingId: string;
+    reason: string;
 }
 /** Resolves AgentConfig.rules the same way skillsDirs resolves its own
  * default: an inline array is used as-is (full 3-segment scopePattern,
@@ -180,3 +286,25 @@ export declare function loadDefaultTools(config: AgentConfig): Promise<ToolDefin
  * elsewhere could. */
 export declare function loadSubagentAsTools(config: AgentConfig): Promise<ToolDefinition[]>;
 export declare function runAgent(config: AgentConfig, modelCall: ModelCall, userMessage: string, history?: Message[], options?: RunAgentOptions): Promise<RunAgentResult>;
+/** Continues a turn durably paused on RunAgentResult.stopReason ===
+ * 'pending_approval' — see HUMAN_IN_THE_LOOP.md for the full design.
+ * `history` is durable session history including the dangling assistant
+ * tool_use message the pause left behind (exactly what a caller's
+ * SessionStore.getHistory/withSession already returns — this needs no
+ * special resumed-session handling, since that message is real, already
+ * on disk). `resolution` is the *complete* set of tool_result blocks
+ * answering that message — every entry from a resolved TurnCheckpoint's
+ * own resultsSoFar, once its outstanding is empty; assembling that is the
+ * caller's job (core/durable-approvals.ts's own CheckpointStore only
+ * stores it, it doesn't execute tools or know when a batch is complete —
+ * see that module's own doc comment), not something this function
+ * derives on its own.
+ *
+ * Pushes `resolution` as the completing message and picks the loop back
+ * up from there — a fresh model call, now with the full picture, exactly
+ * like a synchronous 'ask' would have continued if it hadn't needed to
+ * pause at all. Can itself return with stopReason 'pending_approval'
+ * again (the model's next round of tool calls hits another durably-gated
+ * one), 'denied', 'max_turns', or a genuine finish — runLoop handles all
+ * of those uniformly regardless of how this turn started. */
+export declare function resumeAgent(config: AgentConfig, modelCall: ModelCall, history: Message[], resolution: ModelContentBlock[], options?: RunAgentOptions): Promise<RunAgentResult>;