@caupulican/pi-agent-core 0.86.17 → 0.90.0

package/dist/agent-loop.d.ts

@@ -3,7 +3,8 @@
  * Transforms to Message[] only at the LLM call boundary.
  */
 import { EventStream } from "@caupulican/pi-ai/event-stream";
-import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentToolCall, RequestPreflightContext, RequestPreflightResult, StreamFn, ToolCallRepairInfo } from "./types.ts";
+import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentToolCall, StreamFn, ToolCallRepairInfo } from "./types.ts";
+export { resolveRequestPreflightMaxTokens } from "./provider-request-planner.ts";
 export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
 /**
  * Start an agent loop with a new prompt message.
@@ -21,18 +22,6 @@ export declare function agentLoop(prompts: AgentMessage[], context: AgentContext
 export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
 export declare function runAgentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal, streamFn?: StreamFn): Promise<AgentMessage[]>;
 export declare function runAgentLoopContinue(context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal?: AbortSignal, streamFn?: StreamFn): Promise<AgentMessage[]>;
-/**
- * Apply one request-local preflight without mutating persistent loop configuration.
- * Shared with isolated tool-free provider calls so every transport boundary has identical
- * validation and non-widening semantics.
- */
-export declare function resolveRequestPreflightMaxTokens(options: {
-    requestPreflight?: (context: RequestPreflightContext, signal?: AbortSignal) => RequestPreflightResult | undefined | Promise<RequestPreflightResult | undefined>;
-    model: RequestPreflightContext["model"];
-    context: RequestPreflightContext["context"];
-    maxTokens?: number;
-    signal?: AbortSignal;
-}): Promise<number | undefined>;
 /**
  * Start one provider request through the canonical agent-loop boundary.
  *

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,KAAK,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EAEZ,aAAa,EAEb,uBAAuB,EACvB,sBAAsB,EACtB,QAAQ,EACR,kBAAkB,EAClB,MAAM,YAAY,CAAC;AAIpB,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEzE;;;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,GACjB,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,GACjB,OAAO,CAAC,YAAY,EAAE,CAAC,CAWzB;AAyFD;;;;GAIG;AACH,wBAAsB,gCAAgC,CAAC,OAAO,EAAE;IAC/D,gBAAgB,CAAC,EAAE,CAClB,OAAO,EAAE,uBAAuB,EAChC,MAAM,CAAC,EAAE,WAAW,KAChB,sBAAsB,GAAG,SAAS,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CAAC;IACtF,KAAK,EAAE,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,EAAE,uBAAuB,CAAC,SAAS,CAAC,CAAC;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmB9B;AAqLD;;;;;;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,CA8CxC;AA+hCD,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;AAmC7D,OAAO,KAAK,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EAEZ,aAAa,EAEb,QAAQ,EACR,kBAAkB,EAClB,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AAEjF,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEzE;;;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,GACjB,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,GACjB,OAAO,CAAC,YAAY,EAAE,CAAC,CAWzB;AAmVD;;;;;;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;AA+hCD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,kBAAkB,GAAG,SAAS,CAO7F"}

package/dist/agent-loop.js

@@ -3,13 +3,15 @@
  * Transforms to Message[] only at the LLM call boundary.
  */
 import { EventStream } from "@caupulican/pi-ai/event-stream";
-import { streamSimple } from "@caupulican/pi-ai/stream";
 import { formatToolRepairStandingRule, REPEATED_SUCCESSFUL_TOOL_CALL_FAILURE, } from "@caupulican/pi-ai/tool-repair-registry";
 import { ToolArgumentValidationError, validateToolArguments, } from "@caupulican/pi-ai/validation";
-import { assessToolFailure, clearToolFailure, createRepeatedToolFailureResult, createToolFailureMemoryTracker, createToolFailureRecoveryExhaustedResult, createToolFailureResult, getUnresolvedToolFailure, normalizeToolSignature, rememberToolFailure, sanitizeToolFailureContext, toolFailureCorrection, } from "./tool-failure-memory.js";
+import { startPlannedAgentProviderRequest } from "./provider-request-planner.js";
+import { assessToolFailure, clearToolFailure, createRepeatedToolFailureResult, createToolFailureMemoryTracker, 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 { DEFAULT_MAX_STALL_TURNS } from "./types.js";
 import { createEmptyUsage } from "./usage.js";
+export { resolveRequestPreflightMaxTokens } from "./provider-request-planner.js";
 /**
  * Start an agent loop with a new prompt message.
  * The prompt is added to the context and events are emitted for it.
@@ -89,6 +91,24 @@ function createLoopFailureMessage(error, config, aborted) {
         timestamp: Date.now(),
     };
 }
+function createMandatoryRecoveryDeliveryFallback(halt, config) {
+    const diagnostic = halt.record.diagnostic ?? halt.diagnostic;
+    return {
+        role: "assistant",
+        content: [
+            {
+                type: "text",
+                text: `Tool recovery stopped for ${halt.record.tool}: ${diagnostic} Required recovery: ${halt.record.correction}`,
+            },
+        ],
+        api: config.model.api,
+        provider: config.model.provider,
+        model: config.model.id,
+        usage: createEmptyUsage(),
+        stopReason: "stop",
+        timestamp: Date.now(),
+    };
+}
 function createAgentStream() {
     return new EventStream((event) => event.type === "agent_end", (event) => (event.type === "agent_end" ? event.messages : []));
 }
@@ -144,31 +164,6 @@ function repeatsSuccessfulTextProtocolBatch(incomingSignature, toolCalls, previo
         return phase === "edited" && toolCall.name === "edit" && previousCall.name === "edit";
     });
 }
-/**
- * Apply one request-local preflight without mutating persistent loop configuration.
- * Shared with isolated tool-free provider calls so every transport boundary has identical
- * validation and non-widening semantics.
- */
-export async function resolveRequestPreflightMaxTokens(options) {
-    if (!options.requestPreflight)
-        return options.maxTokens;
-    if (options.maxTokens !== undefined && (!Number.isSafeInteger(options.maxTokens) || options.maxTokens <= 0)) {
-        throw new TypeError("request maxTokens must be a positive safe integer");
-    }
-    const preflight = await options.requestPreflight({ model: options.model, context: options.context, maxTokens: options.maxTokens }, options.signal);
-    if (preflight?.maxTokens === undefined)
-        return options.maxTokens;
-    if (!Number.isSafeInteger(preflight.maxTokens) || preflight.maxTokens <= 0) {
-        throw new TypeError("requestPreflight.maxTokens must be a positive safe integer");
-    }
-    const ceilings = [preflight.maxTokens];
-    if (options.maxTokens !== undefined)
-        ceilings.push(options.maxTokens);
-    if (Number.isSafeInteger(options.model.maxTokens) && options.model.maxTokens > 0) {
-        ceilings.push(options.model.maxTokens);
-    }
-    return Math.min(...ceilings);
-}
 /**
  * Main loop logic shared by agentLoop and agentLoopContinue.
  */
@@ -191,6 +186,7 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
     const repairTeachTracker = new Map();
     let toolFailureMemory = createToolFailureMemoryTracker(currentContext.messages);
     const toolFailureRecoveryGate = new ToolFailureRecoveryGate();
+    let mandatoryRecoveryDeliveryPending = false;
     let lastSuccessfulTextProtocolBatch;
     // Check for steering messages at start (user may have typed while waiting)
     let pendingMessages = (await config.getSteeringMessages?.()) || [];
@@ -216,8 +212,26 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                 }
                 pendingMessages = [];
             }
-            // Stream assistant response
-            const message = await streamAssistantResponse(currentContext, config, signal, emit, streamFn);
+            // 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");
+            }
+            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);
             newMessages.push(message);
             if (message.stopReason === "error" || message.stopReason === "aborted") {
                 await emit({ type: "turn_end", message, toolResults: [] });
@@ -227,6 +241,30 @@ 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) {
+                    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;
+            }
             hasMoreToolCalls = false;
             if (toolCalls.length > 0) {
                 const textProtocolBatch = toolCalls.every((toolCall) => toolCall.source === "text-protocol");
@@ -237,7 +275,13 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                     : undefined;
                 const executedToolBatch = await executeToolCalls(currentContext, message, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, toolFailureRecoveryGate, previousSuccessfulTextProtocolResults, signal, emit);
                 toolResults.push(...executedToolBatch.messages);
-                hasMoreToolCalls = !executedToolBatch.terminate;
+                if (toolFailureRecoveryGate.isHalted()) {
+                    mandatoryRecoveryDeliveryPending = true;
+                    hasMoreToolCalls = true;
+                }
+                else {
+                    hasMoreToolCalls = !executedToolBatch.terminate;
+                }
                 for (const result of toolResults) {
                     currentContext.messages.push(result);
                     newMessages.push(result);
@@ -260,7 +304,7 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
             }
             await emit({ type: "turn_end", message, toolResults });
             // Runaway-loop backstop (cost guard): detect a model stuck repeating one action.
-            if (stallLimit > 0 && toolCalls.length > 0) {
+            if (!mandatoryRecoveryDeliveryPending && 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)
@@ -290,12 +334,13 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                     reasoning: nextTurnSnapshot.thinkingLevel ?? config.reasoning,
                 };
             }
-            if (await config.shouldStopAfterTurn?.({
-                message,
-                toolResults,
-                context: currentContext,
-                newMessages,
-            })) {
+            if (!mandatoryRecoveryDeliveryPending &&
+                (await config.shouldStopAfterTurn?.({
+                    message,
+                    toolResults,
+                    context: currentContext,
+                    newMessages,
+                }))) {
                 await emit({ type: "agent_end", messages: newMessages });
                 return;
             }
@@ -321,46 +366,7 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
  * and request preflight immediately before transport.
  */
 export async function startAgentProviderRequest(context, config, signal, streamFn) {
-    // Failed protocol turns never reach host transforms or provider conversion. Their bounded,
-    // unresolved state is carried separately in the system prompt until the same operation succeeds.
-    const sanitized = sanitizeToolFailureContext(context.messages, context.systemPrompt);
-    let messages = sanitized.messages;
-    if (config.transformContext) {
-        messages = await config.transformContext(messages, signal);
-    }
-    // Convert to LLM-compatible messages (AgentMessage[] → Message[])
-    const llmMessages = await config.convertToLlm(messages);
-    // Build LLM context
-    const llmContext = {
-        systemPrompt: sanitized.systemPrompt,
-        messages: llmMessages,
-        tools: context.tools,
-    };
-    const streamFunction = streamFn || streamSimple;
-    const requestMaxTokens = await resolveRequestPreflightMaxTokens({
-        requestPreflight: config.requestPreflight,
-        model: config.model,
-        context: llmContext,
-        maxTokens: config.maxTokens,
-        signal,
-    });
-    // Resolve credentials only after the request-local authority/budget gate accepts the request.
-    // This prevents an already-exhausted background lane from refreshing OAuth/SSO credentials.
-    const resolvedApiKey = (config.getApiKey ? await config.getApiKey(config.model.provider) : undefined) || config.apiKey;
-    const requestReasoning = config.resolveRequestReasoning
-        ? config.resolveRequestReasoning(config.reasoning, {
-            model: config.model,
-            context: llmContext,
-            maxTokens: requestMaxTokens,
-        })
-        : config.reasoning;
-    return await streamFunction(config.model, llmContext, {
-        ...config,
-        apiKey: resolvedApiKey,
-        maxTokens: requestMaxTokens,
-        reasoning: requestReasoning,
-        signal,
-    });
+    return startPlannedAgentProviderRequest(context, config, signal, streamFn);
 }
 /**
  * Stream an assistant response from the LLM.
@@ -1126,4 +1132,20 @@ 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