@caupulican/pi-agent-core 0.81.40 → 0.81.42

package/dist/agent-loop.js

@@ -2,7 +2,8 @@
  * Agent loop that works with AgentMessage throughout.
  * Transforms to Message[] only at the LLM call boundary.
  */
-import { EventStream, getToolExecutionErrorGuidance, streamSimple, ToolArgumentValidationError, validateToolArguments, } from "@caupulican/pi-ai";
+import { EventStream, formatToolRepairStandingRule, streamSimple, ToolArgumentValidationError, validateToolArguments, } from "@caupulican/pi-ai";
+import { assessToolFailure, clearToolFailure, createToolFailureMemoryTracker, createToolFailureResult, normalizeToolSignature, rememberToolFailure, sanitizeToolFailureContext, toolFailureCorrection, } from "./tool-failure-memory.js";
 import { DEFAULT_MAX_STALL_TURNS } from "./types.js";
 import { createEmptyUsage } from "./usage.js";
 /**
@@ -106,18 +107,29 @@ function createAgentStream() {
  */
 const STALL_WINDOW_PERIODS = 4;
 /**
- * Normalize a tool-call batch into a stable signature for runaway-loop detection. Volatile argument
- * tokens — epoch/timestamps, UUIDs, long hashes/nonces — are masked so a model retrying the SAME call
- * with a fresh timestamp/id each turn still collapses to one signature and is detected (bug #28). Only
- * clearly-volatile patterns are masked: short numbers (`file2.ts`, `line 42`, `count: 3`) are kept so
- * genuinely-distinct calls (reading numbered files, different line ranges) are NOT falsely merged.
+ * 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.
  */
-function normalizeToolSignature(pairs) {
-    return JSON.stringify(pairs)
-        .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "<uuid>")
-        .replace(/\d{4}-\d{2}-\d{2}[tT][0-9:.]+(?:z|[+-]\d{2}:?\d{2})?/gi, "<ts>")
-        .replace(/\b[0-9a-f]{16,}\b/gi, "<hex>")
-        .replace(/\d{10,}/g, "<num>");
+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.
@@ -139,7 +151,7 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
     const stallWindow = [];
     const validationFailureTracker = { repeats: 0 };
     const repairTeachTracker = new Map();
-    const executionFailureTracker = { repeats: 0 };
+    let toolFailureMemory = createToolFailureMemoryTracker(currentContext.messages);
     // Check for steering messages at start (user may have typed while waiting)
     let pendingMessages = (await config.getSteeringMessages?.()) || [];
     // Outer loop: continues when queued follow-up messages arrive after agent would stop
@@ -176,7 +188,7 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
             const toolResults = [];
             hasMoreToolCalls = false;
             if (toolCalls.length > 0) {
-                const executedToolBatch = await executeToolCalls(currentContext, message, config, validationFailureTracker, repairTeachTracker, executionFailureTracker, signal, emit);
+                const executedToolBatch = await executeToolCalls(currentContext, message, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, signal, emit);
                 toolResults.push(...executedToolBatch.messages);
                 hasMoreToolCalls = !executedToolBatch.terminate;
                 for (const result of toolResults) {
@@ -207,6 +219,9 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
             const nextTurnSnapshot = await config.prepareNextTurn?.(nextTurnContext);
             if (nextTurnSnapshot) {
                 currentContext = nextTurnSnapshot.context ?? currentContext;
+                if (nextTurnSnapshot.context) {
+                    toolFailureMemory = createToolFailureMemoryTracker(currentContext.messages);
+                }
                 config = {
                     ...config,
                     model: nextTurnSnapshot.model ?? config.model,
@@ -237,12 +252,17 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
     await emit({ type: "agent_end", messages: newMessages });
 }
 /**
- * Stream an assistant response from the LLM.
- * This is where AgentMessage[] gets transformed to Message[] for the LLM.
+ * Start one provider request through the canonical agent-loop boundary.
+ *
+ * All callers, including host-owned tool-free finalization, receive the same failure-context
+ * sanitization, context transformation/conversion, dynamic authentication, request-local reasoning,
+ * and request preflight immediately before transport.
  */
-async function streamAssistantResponse(context, config, signal, emit, streamFn) {
-    // Apply context transform if configured (AgentMessage[] → AgentMessage[])
-    let messages = context.messages;
+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);
     }
@@ -250,26 +270,42 @@ async function streamAssistantResponse(context, config, signal, emit, streamFn)
     const llmMessages = await config.convertToLlm(messages);
     // Build LLM context
     const llmContext = {
-        systemPrompt: context.systemPrompt,
+        systemPrompt: sanitized.systemPrompt,
         messages: llmMessages,
         tools: context.tools,
     };
     const streamFunction = streamFn || streamSimple;
-    // Resolve API key (important for expiring tokens)
+    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: config.maxTokens,
+            maxTokens: requestMaxTokens,
         })
         : config.reasoning;
-    const response = await streamFunction(config.model, llmContext, {
+    return await streamFunction(config.model, llmContext, {
         ...config,
         apiKey: resolvedApiKey,
+        maxTokens: requestMaxTokens,
         reasoning: requestReasoning,
         signal,
     });
+}
+/**
+ * Stream an assistant response from the LLM.
+ * This is where AgentMessage[] gets transformed to Message[] for the LLM.
+ */
+async function streamAssistantResponse(context, config, signal, emit, streamFn) {
+    const response = await startAgentProviderRequest(context, config, signal, streamFn);
     let partialMessage = null;
     let addedPartial = false;
     for await (const event of response) {
@@ -330,15 +366,15 @@ async function streamAssistantResponse(context, config, signal, emit, streamFn)
 /**
  * Execute tool calls from an assistant message.
  */
-async function executeToolCalls(currentContext, assistantMessage, config, validationFailureTracker, repairTeachTracker, executionFailureTracker, signal, emit) {
+async function executeToolCalls(currentContext, assistantMessage, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, signal, emit) {
     const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");
     const hasSequentialToolCall = toolCalls.some((tc) => currentContext.tools?.find((t) => t.name === tc.name)?.executionMode === "sequential");
     if (config.toolExecution === "sequential" || hasSequentialToolCall) {
-        return executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, validationFailureTracker, repairTeachTracker, executionFailureTracker, signal, emit);
+        return executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, signal, emit);
     }
-    return executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, validationFailureTracker, repairTeachTracker, executionFailureTracker, signal, emit);
+    return executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, signal, emit);
 }
-async function executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, validationFailureTracker, repairTeachTracker, executionFailureTracker, signal, emit) {
+async function executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, signal, emit) {
     const finalizedCalls = [];
     const messages = [];
     for (const toolCall of toolCalls) {
@@ -346,17 +382,12 @@ async function executeToolCallsSequential(currentContext, assistantMessage, tool
         await emitToolExecutionStart(toolCall, emit);
         let finalized;
         if (preparation.kind === "immediate") {
-            resetExecutionFailureTracker(executionFailureTracker);
             emitToolArgumentValidationTelemetry(config, preparation.validationEvent, "not_run", "none");
-            finalized = {
-                toolCall,
-                result: preparation.result,
-                isError: preparation.isError,
-            };
+            finalized = finalizeRejectedToolCall(toolCall, preparation, toolFailureMemory);
         }
         else {
             const executed = await executePreparedToolCall(preparation, signal, emit);
-            finalized = await finalizeExecutedToolCall(currentContext, assistantMessage, preparation, executed, config, repairTeachTracker, executionFailureTracker, signal);
+            finalized = await finalizeExecutedToolCall(currentContext, assistantMessage, preparation, executed, config, repairTeachTracker, toolFailureMemory, signal);
         }
         await emitToolExecutionEnd(finalized, emit);
         const toolResultMessage = createToolResultMessage(finalized);
@@ -372,19 +403,14 @@ async function executeToolCallsSequential(currentContext, assistantMessage, tool
         terminate: shouldTerminateToolBatch(finalizedCalls),
     };
 }
-async function executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, validationFailureTracker, repairTeachTracker, executionFailureTracker, signal, emit) {
+async function executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, signal, emit) {
     const finalizedCalls = [];
     for (const toolCall of toolCalls) {
         const preparation = await prepareToolCall(currentContext, assistantMessage, toolCall, config, validationFailureTracker, signal);
         await emitToolExecutionStart(toolCall, emit);
         if (preparation.kind === "immediate") {
-            resetExecutionFailureTracker(executionFailureTracker);
             emitToolArgumentValidationTelemetry(config, preparation.validationEvent, "not_run", "none");
-            const finalized = {
-                toolCall,
-                result: preparation.result,
-                isError: preparation.isError,
-            };
+            const finalized = finalizeRejectedToolCall(toolCall, preparation, toolFailureMemory);
             await emitToolExecutionEnd(finalized, emit);
             finalizedCalls.push(finalized);
             if (signal?.aborted) {
@@ -394,7 +420,7 @@ async function executeToolCallsParallel(currentContext, assistantMessage, toolCa
         }
         finalizedCalls.push(async () => {
             const executed = await executePreparedToolCall(preparation, signal, emit);
-            const finalized = await finalizeExecutedToolCall(currentContext, assistantMessage, preparation, executed, config, repairTeachTracker, executionFailureTracker, signal);
+            const finalized = await finalizeExecutedToolCall(currentContext, assistantMessage, preparation, executed, config, repairTeachTracker, toolFailureMemory, signal);
             await emitToolExecutionEnd(finalized, emit);
             return finalized;
         });
@@ -416,7 +442,6 @@ async function executeToolCallsParallel(currentContext, assistantMessage, toolCa
 }
 const DEFAULT_TOOL_VALIDATION_ESCALATION_THRESHOLD = 3;
 const TOOL_REPAIR_TEACH_EVERY = 5;
-const TOOL_EXECUTION_FAILURE_TEACH_AT = 2;
 function shouldTerminateToolBatch(finalizedCalls) {
     return finalizedCalls.length > 0 && finalizedCalls.every((finalized) => finalized.result.terminate === true);
 }
@@ -447,6 +472,20 @@ function createValidationBounceTelemetry(config, toolCall, errorKeyword) {
         executionOutcome: "not_run",
     };
 }
+function validationFailureCorrection(event, toolName) {
+    const shape = event?.failureShape
+        ?.slice(0, 3)
+        .map((entry) => `${entry.path}: expected ${entry.expectedType}, received ${entry.receivedType}`)
+        .join("; ");
+    const rules = [
+        ...new Set((event?.failureModes ?? [])
+            .filter((mode) => mode !== "other")
+            .map((mode) => formatToolRepairStandingRule(mode))),
+    ];
+    return [`Match ${toolName} arguments to its current schema.`, shape ? `Fix ${shape}.` : undefined, ...rules]
+        .filter((part) => part !== undefined)
+        .join(" ");
+}
 function resetValidationFailureTracker(tracker) {
     tracker.signature = undefined;
     tracker.repeats = 0;
@@ -503,6 +542,8 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
             kind: "immediate",
             result: createErrorToolResult(toolCall.errorMessage),
             isError: true,
+            failureCode: "malformed_call",
+            correction: "Resend one complete JSON argument object matching the current tool schema.",
             validationEvent: createValidationBounceTelemetry(config, toolCall, "unknown_tool"),
         };
     }
@@ -512,6 +553,8 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
             kind: "immediate",
             result: createErrorToolResult(`Tool ${toolCall.name} not found`),
             isError: true,
+            failureCode: "unknown_tool",
+            correction: "Choose a tool from the currently available tool list.",
             validationEvent: createValidationBounceTelemetry(config, toolCall, "unknown_tool"),
         };
     }
@@ -546,14 +589,20 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
                     kind: "immediate",
                     result: createErrorToolResult("Operation aborted"),
                     isError: true,
+                    failureCode: "aborted",
+                    correction: "Retry only if the operation is still required.",
                     validationEvent,
                 };
             }
             if (beforeResult?.block) {
+                const reason = beforeResult.reason || "Tool execution was blocked";
                 return {
                     kind: "immediate",
-                    result: createErrorToolResult(beforeResult.reason || "Tool execution was blocked"),
+                    result: createErrorToolResult(reason),
                     isError: true,
+                    failureCode: "blocked",
+                    correction: "Choose an allowed approach or request the required authority before retrying.",
+                    diagnostic: reason,
                     validationEvent,
                 };
             }
@@ -563,6 +612,8 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
                 kind: "immediate",
                 result: createErrorToolResult("Operation aborted"),
                 isError: true,
+                failureCode: "aborted",
+                correction: "Retry only if the operation is still required.",
                 validationEvent,
             };
         }
@@ -584,10 +635,22 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
             kind: "immediate",
             result: createErrorToolResult(message),
             isError: true,
+            failureCode: isToolArgumentValidationError(error) ? "invalid_arguments" : "preflight_error",
+            correction: isToolArgumentValidationError(error)
+                ? validationFailureCorrection(validationEvent, toolCall.name)
+                : toolFailureCorrection(message, "rejected"),
             validationEvent,
         };
     }
 }
+function finalizeRejectedToolCall(toolCall, outcome, tracker) {
+    const record = rememberToolFailure(tracker, toolCall.name, toolCall.arguments, "rejected", outcome.failureCode, outcome.correction, outcome.diagnostic);
+    return {
+        toolCall,
+        result: createToolFailureResult(record, outcome.result.terminate),
+        isError: true,
+    };
+}
 async function executePreparedToolCall(prepared, signal, emit) {
     const updateEvents = [];
     try {
@@ -601,15 +664,23 @@ async function executePreparedToolCall(prepared, signal, emit) {
             })));
         });
         await Promise.all(updateEvents);
-        return { result, isError: false };
+        return {
+            result,
+            // Tool definitions can report an expected operation failure without
+            // throwing. Keep the returned result intact through afterToolCall so
+            // policy hooks can inspect its bounded diagnostics and metadata.
+            isError: result.isError === true,
+            ...(result.isError === true ? { errorClass: "tool_result_error" } : {}),
+        };
     }
     catch (error) {
         await Promise.all(updateEvents);
         const message = error instanceof Error ? error.message : String(error);
         return {
-            result: createErrorToolResultWithGuidance(message),
+            result: createErrorToolResult(message),
             isError: true,
             errorClass: error instanceof Error ? error.name : typeof error,
+            failureMessage: message,
         };
     }
 }
@@ -637,39 +708,11 @@ function appendRepairTeachNotes(result, toolCall, tracker, config) {
         taught: true,
     };
 }
-function resetExecutionFailureTracker(tracker) {
-    tracker.signature = undefined;
-    tracker.repeats = 0;
-}
-function executionFailureSignature(prepared, errorClass) {
-    return `${normalizeToolSignature([[prepared.toolCall.name, prepared.args]])}\0${errorClass}`;
-}
-function appendExecutionFailureTeachNote(result, prepared, errorClass, tracker) {
-    const signature = executionFailureSignature(prepared, errorClass ?? "tool-error");
-    if (tracker.signature === signature) {
-        tracker.repeats++;
-    }
-    else {
-        tracker.signature = signature;
-        tracker.repeats = 1;
-    }
-    if (tracker.repeats !== TOOL_EXECUTION_FAILURE_TEACH_AT || tracker.taughtSignature === signature)
-        return result;
-    tracker.taughtSignature = signature;
-    return {
-        ...result,
-        content: [
-            {
-                type: "text",
-                text: `[harness] This exact ${prepared.toolCall.name} call failed twice with the same ${errorClass ?? "tool"} error. Change the arguments or approach; do not resend the identical call.`,
-            },
-            ...result.content,
-        ],
-    };
-}
-async function finalizeExecutedToolCall(currentContext, assistantMessage, prepared, executed, config, repairTeachTracker, executionFailureTracker, signal) {
+async function finalizeExecutedToolCall(currentContext, assistantMessage, prepared, executed, config, repairTeachTracker, toolFailureMemory, signal) {
     let result = executed.result;
     let isError = executed.isError;
+    let failureMessage = executed.failureMessage ?? "";
+    let errorClass = executed.errorClass;
     if (config.afterToolCall) {
         try {
             const afterResult = await config.afterToolCall({
@@ -684,23 +727,32 @@ async function finalizeExecutedToolCall(currentContext, assistantMessage, prepar
                 result = {
                     content: afterResult.content ?? result.content,
                     details: afterResult.details ?? result.details,
+                    usage: afterResult.usage ?? result.usage,
                     terminate: afterResult.terminate ?? result.terminate,
                 };
                 isError = afterResult.isError ?? isError;
             }
         }
         catch (error) {
-            result = createErrorToolResult(error instanceof Error ? error.message : String(error));
+            failureMessage = error instanceof Error ? error.message : String(error);
+            errorClass = error instanceof Error ? error.name : typeof error;
+            result = { ...createErrorToolResult(failureMessage), usage: result.usage };
             isError = true;
         }
     }
     if (isError) {
-        result = appendExecutionFailureTeachNote(result, prepared, executed.errorClass, executionFailureTracker);
+        const usage = result.usage;
+        const effectiveFailureMessage = failureMessage || result.content.find((block) => block.type === "text")?.text || "Tool execution failed";
+        const assessment = assessToolFailure(effectiveFailureMessage, "failed", errorClass);
+        const record = rememberToolFailure(toolFailureMemory, prepared.toolCall.name, prepared.args, "failed", assessment.failureCode, assessment.guidance, assessment.diagnostic);
+        result = { ...createToolFailureResult(record, result.terminate), usage };
     }
     else {
-        resetExecutionFailureTracker(executionFailureTracker);
+        clearToolFailure(toolFailureMemory, prepared.toolCall.name, prepared.args);
     }
-    const repaired = appendRepairTeachNotes(result, prepared.toolCall, repairTeachTracker, config);
+    const repaired = isError
+        ? { result, taught: false }
+        : appendRepairTeachNotes(result, prepared.toolCall, repairTeachTracker, config);
     emitToolArgumentValidationTelemetry(config, prepared.validationEvent, isError ? "failed" : "succeeded", repaired.taught ? "note" : "none");
     return {
         toolCall: prepared.toolCall,
@@ -714,18 +766,6 @@ function createErrorToolResult(message) {
         details: {},
     };
 }
-function createErrorToolResultWithGuidance(message) {
-    const guidance = getToolExecutionErrorGuidance(message);
-    if (!guidance)
-        return createErrorToolResult(message);
-    return {
-        content: [
-            { type: "text", text: message },
-            { type: "text", text: `[harness] ${guidance}` },
-        ],
-        details: {},
-    };
-}
 async function emitToolExecutionStart(toolCall, emit) {
     await emit({
         type: "tool_execution_start",
@@ -761,6 +801,7 @@ function createToolResultMessage(finalized) {
         toolName: finalized.toolCall.name,
         content: finalized.result.content,
         details: finalized.result.details,
+        usage: finalized.result.usage,
         isError: finalized.isError,
         timestamp: Date.now(),
     };