@caupulican/pi-agent-core 0.92.0 → 0.93.0

package/dist/agent-loop.d.ts

@@ -5,10 +5,11 @@
 import { EventStream } from "@caupulican/pi-ai/event-stream";
 import { ToolFailureRecoveryGate } from "./tool-failure-recovery-gate.ts";
 import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentToolCall, StreamFn, ToolCallRepairInfo } from "./types.ts";
-export { narrowRequestMaxTokens, resolveRequestPreflightMaxTokens } from "./provider-request-planner.ts";
+export { composeRequestSystemPrompt, narrowRequestMaxTokens, resolveRequestPreflightMaxTokens, } from "./provider-request-planner.ts";
 export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
 /** Bounded no-progress state retained across host-owned continuations of one logical prompt. */
 export interface AgentLoopContinuationState {
+    providerTurns: number;
     stallWindow: string[];
     toolFailureRecoveryGate: ToolFailureRecoveryGate;
 }

package/dist/agent-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../src/agent-loop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAmC7D,OAAO,EAGN,uBAAuB,EAGvB,MAAM,iCAAiC,CAAC;AAGzC,OAAO,KAAK,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EAEZ,aAAa,EAEb,QAAQ,EACR,kBAAkB,EAClB,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,sBAAsB,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AAEzG,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEzE,gGAAgG;AAChG,MAAM,WAAW,0BAA0B;IAC1C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uBAAuB,EAAE,uBAAuB,CAAC;CACjD;AAED,wBAAgB,gCAAgC,IAAI,0BAA0B,CAE7E;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACxB,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAEzC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAIzC;AAuBD,wBAAsB,YAAY,CACjC,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,EACnB,iBAAiB,GAAE,0BAA+D,GAChF,OAAO,CAAC,YAAY,EAAE,CAAC,CAgBzB;AAED,wBAAsB,oBAAoB,CACzC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,EACnB,iBAAiB,GAAE,0BAA+D,GAChF,OAAO,CAAC,YAAY,EAAE,CAAC,CAWzB;AAgWD;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC9C,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAExC;AAqjCD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,kBAAkB,GAAG,SAAS,CAO7F"}
+{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../src/agent-loop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAiC7D,OAAO,EAGN,uBAAuB,EAGvB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EAEZ,aAAa,EAEb,QAAQ,EACR,kBAAkB,EAClB,MAAM,YAAY,CAAC;AAIpB,OAAO,EACN,0BAA0B,EAC1B,sBAAsB,EACtB,gCAAgC,GAChC,MAAM,+BAA+B,CAAC;AAEvC,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEzE,gGAAgG;AAChG,MAAM,WAAW,0BAA0B;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,uBAAuB,EAAE,uBAAuB,CAAC;CACjD;AAED,wBAAgB,gCAAgC,IAAI,0BAA0B,CAE7E;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACxB,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAEzC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAIzC;AAuBD,wBAAsB,YAAY,CACjC,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,EACnB,iBAAiB,GAAE,0BAA+D,GAChF,OAAO,CAAC,YAAY,EAAE,CAAC,CAgBzB;AAED,wBAAsB,oBAAoB,CACzC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,EACnB,iBAAiB,GAAE,0BAA+D,GAChF,OAAO,CAAC,YAAY,EAAE,CAAC,CAWzB;AAoVD;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC9C,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAExC;AAqjCD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,kBAAkB,GAAG,SAAS,CAO7F"}

package/dist/agent-loop.js

@@ -5,17 +5,16 @@
 import { EventStream } from "@caupulican/pi-ai/event-stream";
 import { formatToolRepairStandingRule, REPEATED_SUCCESSFUL_TOOL_CALL_FAILURE, } from "@caupulican/pi-ai/tool-repair-registry";
 import { ToolArgumentValidationError, validateToolArguments, } from "@caupulican/pi-ai/validation";
-import { assistantMessageText, collapseDegenerateAssistantMessage, isCollapsedDegenerateAssistantMessage, isDegenerateRepeatedText, shouldAbortDegenerateStream, } from "./degenerate-assistant-text.js";
+import { assistantMessageText, collapseDegenerateAssistantMessage, shouldAbortDegenerateStream, } from "./degenerate-assistant-text.js";
 import { startPlannedAgentProviderRequest } from "./provider-request-planner.js";
 import { assessToolFailure, clearToolFailure, createRepeatedToolFailureResult, createToolFailureMemoryTracker, createToolFailureOperationExhaustedResult, createToolFailureRecoveryExhaustedResult, createToolFailureResult, getUnresolvedToolFailure, normalizeToolSignature, rememberToolFailure, toolFailureCorrection, } from "./tool-failure-memory.js";
 import { TOOL_FAILURE_RECOVERY_ACCOUNTING_WAVE_SIZE, ToolFailureRecoveryGate, } from "./tool-failure-recovery-gate.js";
-import { appendMandatoryToolFailureDeliveryPrompt } from "./tool-failure-recovery-protocol.js";
 import { rejectNativeToolProtocolResidue } from "./tool-protocol-residue.js";
-import { DEFAULT_MAX_STALL_TURNS } from "./types.js";
+import { DEFAULT_MAX_PROVIDER_TURNS, DEFAULT_MAX_STALL_TURNS } from "./types.js";
 import { createEmptyUsage } from "./usage.js";
-export { narrowRequestMaxTokens, resolveRequestPreflightMaxTokens } from "./provider-request-planner.js";
+export { composeRequestSystemPrompt, narrowRequestMaxTokens, resolveRequestPreflightMaxTokens, } from "./provider-request-planner.js";
 export function createAgentLoopContinuationState() {
-    return { stallWindow: [], toolFailureRecoveryGate: new ToolFailureRecoveryGate() };
+    return { providerTurns: 0, stallWindow: [], toolFailureRecoveryGate: new ToolFailureRecoveryGate() };
 }
 /**
  * Start an agent loop with a new prompt message.
@@ -96,30 +95,17 @@ function createLoopFailureMessage(error, config, aborted) {
         timestamp: Date.now(),
     };
 }
-function mandatoryDeliveryReportsHalt(message, halt) {
-    const raw = assistantMessageText(message);
-    if (!raw.trim())
-        return false;
-    if (isCollapsedDegenerateAssistantMessage(message) || isDegenerateRepeatedText(raw))
-        return false;
-    const text = raw.toLowerCase();
-    if (text.includes("recovery"))
-        return true;
-    if (text.includes(halt.record.failureCode.toLowerCase()))
-        return true;
-    const diagnostic = halt.record.diagnostic ?? halt.diagnostic;
-    return diagnostic !== undefined && text.includes(diagnostic.toLowerCase().slice(0, 40));
-}
 function createMandatoryRecoveryDeliveryFallback(halt, config) {
     const diagnostic = halt.record.diagnostic ?? halt.diagnostic;
+    return createLocalDiagnosticMessage(config, `Tool recovery stopped for ${halt.record.tool}: ${diagnostic} Required recovery: ${halt.record.correction}`);
+}
+function createProviderTurnLimitMessage(config, providerTurns) {
+    return createLocalDiagnosticMessage(config, `Provider turn limit (${providerTurns}) reached. The harness stopped before another paid model request; continue explicitly if more work is needed.`);
+}
+function createLocalDiagnosticMessage(config, text) {
     return {
         role: "assistant",
-        content: [
-            {
-                type: "text",
-                text: `Tool recovery stopped for ${halt.record.tool}: ${diagnostic} Required recovery: ${halt.record.correction}`,
-            },
-        ],
+        content: [{ type: "text", text }],
         api: config.model.api,
         provider: config.model.provider,
         model: config.model.id,
@@ -128,6 +114,14 @@ function createMandatoryRecoveryDeliveryFallback(halt, config) {
         timestamp: Date.now(),
     };
 }
+async function emitTerminalLocalMessage(message, newMessages, emit, startTurn) {
+    if (startTurn)
+        await emit({ type: "turn_start" });
+    await emit({ type: "message_start", message });
+    await emit({ type: "message_end", message });
+    await emit({ type: "turn_end", message, toolResults: [] });
+    await emit({ type: "agent_end", messages: newMessages });
+}
 function createAgentStream() {
     return new EventStream((event) => event.type === "agent_end", (event) => (event.type === "agent_end" ? event.messages : []));
 }
@@ -200,13 +194,13 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
     // window slides past it. Counts only turns that issued tool calls, so varied/long work never trips
     // it. `0` disables.
     const stallLimit = config.maxStallTurns ?? DEFAULT_MAX_STALL_TURNS;
+    const providerTurnLimit = config.maxProviderTurns ?? DEFAULT_MAX_PROVIDER_TURNS;
     const stallWindow = continuationState.stallWindow;
     const validationFailureTracker = { repeats: 0 };
     const repairTeachTracker = new Map();
     let toolFailureMemory = createToolFailureMemoryTracker(currentContext.messages);
     const toolFailureRecoveryGate = continuationState.toolFailureRecoveryGate;
     toolFailureRecoveryGate.restoreFromMessages(currentContext.messages);
-    let mandatoryRecoveryDeliveryPending = false;
     let lastSuccessfulTextProtocolBatch;
     // Check for steering messages at start (user may have typed while waiting)
     let pendingMessages = (await config.getSteeringMessages?.()) || [];
@@ -232,26 +226,20 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                 }
                 pendingMessages = [];
             }
-            // Recovery exhaustion receives exactly one provider turn without tools so the mandatory
-            // diagnostic can reach the user instead of terminating on an undelivered tool result.
-            const recoveryDeliveryTurn = mandatoryRecoveryDeliveryPending;
-            const recoveryDeliveryHalt = recoveryDeliveryTurn ? toolFailureRecoveryGate.getHalt() : undefined;
-            if (recoveryDeliveryTurn && !recoveryDeliveryHalt) {
-                throw new Error("Mandatory recovery delivery started without a recovery halt");
+            if (providerTurnLimit > 0 && continuationState.providerTurns >= providerTurnLimit) {
+                const fallback = createProviderTurnLimitMessage(config, continuationState.providerTurns);
+                currentContext.messages.push(fallback);
+                newMessages.push(fallback);
+                config.onRunawayStop?.({
+                    reason: "provider_turn_limit",
+                    signature: "provider_turn_limit",
+                    repeats: continuationState.providerTurns,
+                });
+                await emitTerminalLocalMessage(fallback, newMessages, emit, false);
+                return;
             }
-            const responseContext = recoveryDeliveryHalt
-                ? {
-                    ...currentContext,
-                    systemPrompt: appendMandatoryToolFailureDeliveryPrompt(currentContext.systemPrompt, {
-                        tool: recoveryDeliveryHalt.record.tool,
-                        failureCode: recoveryDeliveryHalt.record.failureCode,
-                        diagnostic: recoveryDeliveryHalt.record.diagnostic ?? recoveryDeliveryHalt.diagnostic,
-                        requiredAction: recoveryDeliveryHalt.record.correction,
-                    }),
-                    tools: [],
-                }
-                : currentContext;
-            const message = await streamAssistantResponse(responseContext, config, signal, emit, streamFn);
+            continuationState.providerTurns++;
+            const message = await streamAssistantResponse(currentContext, config, signal, emit, streamFn);
             newMessages.push(message);
             if (message.stopReason === "error" || message.stopReason === "aborted") {
                 await emit({ type: "turn_end", message, toolResults: [] });
@@ -261,30 +249,7 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
             // Check for tool calls
             const toolCalls = message.content.filter((c) => c.type === "toolCall");
             const toolResults = [];
-            if (recoveryDeliveryTurn) {
-                if (!recoveryDeliveryHalt) {
-                    throw new Error("Mandatory recovery delivery continued without a recovery halt");
-                }
-                if (toolCalls.length > 0) {
-                    toolResults.push(...(await rejectRecoveryDeliveryToolCalls(toolCalls, recoveryDeliveryHalt, emit)));
-                    for (const result of toolResults) {
-                        currentContext.messages.push(result);
-                        newMessages.push(result);
-                    }
-                }
-                await emit({ type: "turn_end", message, toolResults });
-                if (toolCalls.length > 0 || !mandatoryDeliveryReportsHalt(message, recoveryDeliveryHalt)) {
-                    const fallback = createMandatoryRecoveryDeliveryFallback(recoveryDeliveryHalt, config);
-                    currentContext.messages.push(fallback);
-                    newMessages.push(fallback);
-                    await emit({ type: "turn_start" });
-                    await emit({ type: "message_start", message: fallback });
-                    await emit({ type: "message_end", message: fallback });
-                    await emit({ type: "turn_end", message: fallback, toolResults: [] });
-                }
-                await emit({ type: "agent_end", messages: newMessages });
-                return;
-            }
+            let recoveryHalt;
             hasMoreToolCalls = false;
             if (toolCalls.length > 0) {
                 const textProtocolBatch = toolCalls.every((toolCall) => toolCall.source === "text-protocol");
@@ -296,8 +261,9 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                 const executedToolBatch = await executeToolCalls(currentContext, message, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, toolFailureRecoveryGate, previousSuccessfulTextProtocolResults, signal, emit);
                 toolResults.push(...executedToolBatch.messages);
                 if (toolFailureRecoveryGate.isHalted()) {
-                    mandatoryRecoveryDeliveryPending = true;
-                    hasMoreToolCalls = true;
+                    recoveryHalt = toolFailureRecoveryGate.getHalt();
+                    if (!recoveryHalt)
+                        throw new Error("Tool recovery halted without a failure record");
                 }
                 else {
                     hasMoreToolCalls = !executedToolBatch.terminate;
@@ -323,15 +289,22 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                 lastSuccessfulTextProtocolBatch = undefined;
             }
             await emit({ type: "turn_end", message, toolResults });
+            if (recoveryHalt) {
+                const fallback = createMandatoryRecoveryDeliveryFallback(recoveryHalt, config);
+                currentContext.messages.push(fallback);
+                newMessages.push(fallback);
+                await emitTerminalLocalMessage(fallback, newMessages, emit, true);
+                return;
+            }
             // Runaway-loop backstop (cost guard): detect a model stuck repeating one action.
-            if (!mandatoryRecoveryDeliveryPending && stallLimit > 0 && toolCalls.length > 0) {
+            if (stallLimit > 0 && toolCalls.length > 0) {
                 const signature = normalizeToolSignature(toolCalls.map((c) => [c.name, c.arguments ?? null]));
                 stallWindow.push(signature);
                 if (stallWindow.length > stallLimit * STALL_WINDOW_PERIODS)
                     stallWindow.shift();
                 const repeats = stallWindow.reduce((n, s) => (s === signature ? n + 1 : n), 0);
                 if (repeats >= stallLimit) {
-                    config.onRunawayStop?.({ signature, repeats });
+                    config.onRunawayStop?.({ reason: "repeated_tool_call", signature, repeats });
                     await emit({ type: "agent_end", messages: newMessages });
                     return;
                 }
@@ -354,13 +327,12 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                     reasoning: nextTurnSnapshot.thinkingLevel ?? config.reasoning,
                 };
             }
-            if (!mandatoryRecoveryDeliveryPending &&
-                (await config.shouldStopAfterTurn?.({
-                    message,
-                    toolResults,
-                    context: currentContext,
-                    newMessages,
-                }))) {
+            if (await config.shouldStopAfterTurn?.({
+                message,
+                toolResults,
+                context: currentContext,
+                newMessages,
+            })) {
                 await emit({ type: "agent_end", messages: newMessages });
                 return;
             }
@@ -1166,20 +1138,4 @@ async function emitToolResultMessage(toolResultMessage, emit) {
     await emit({ type: "message_start", message: toolResultMessage });
     await emit({ type: "message_end", message: toolResultMessage });
 }
-async function rejectRecoveryDeliveryToolCalls(toolCalls, halt, emit) {
-    const messages = [];
-    for (const toolCall of toolCalls) {
-        await emitToolExecutionStart(toolCall, emit);
-        const finalized = {
-            toolCall,
-            result: createToolFailureRecoveryExhaustedResult(halt.record, "Tool execution is disabled during the mandatory recovery delivery turn."),
-            isError: true,
-        };
-        await emitToolExecutionEnd(finalized, emit);
-        const message = createToolResultMessage(finalized);
-        await emitToolResultMessage(message, emit);
-        messages.push(message);
-    }
-    return messages;
-}
 //# sourceMappingURL=agent-loop.js.map