@aeye/core 0.5.4 → 0.7.0

package/dist/prompt.js

@@ -1,13 +1,20 @@
 import Handlebars from "handlebars";
 import { ZodString } from 'zod';
 import { accumulateReasoning, accumulateUsage, extractJSONObject, getChunksFromResponse, getInputTokens, getModel, getOutputTokens, getTotalTokens, resolve, resolveFn, yieldAll } from "./common";
-import { ToolInterrupt, PromptSuspend } from "./tool";
+import { forcesTool, ToolInterrupt, PromptSuspend } from "./tool";
 import { getDescriptorById, strictify, decodeWire } from "./schema";
+import { OutputValidationError, PromptError, ReviewRejectedError, SchemaRejectedError, ToolExecutionError, ToolInputError } from "./errors";
+import { SCHEMA_FALLBACKS, structuredOutput } from "./delivery";
 /** Default cap (chars) for validation error messages surfaced back to the
  *  LLM. Read by `Prompt.truncateValidationError`; subclasses may override
  *  the method to ignore this. Anything past `max` is replaced with a
  *  `… (N more characters)` marker. */
 const DEFAULT_VALIDATION_ERROR_MAX_LENGTH = 4096;
+/**
+ * The user message a prompt adds when it runs without a conversation.
+ * Override it with `userTurn` on the prompt or the context.
+ */
+export const DEFAULT_USER_TURN = 'Begin.';
 /**
  * A Prompt component that generates AI responses based on input, context, and available tools.
  * Prompts orchestrate interactions with AI models, handle tool calls, and manage streaming responses.
@@ -262,7 +269,7 @@ export class Prompt {
             tools,
             responseFormat,
         };
-        const fixedToolChoice = request.toolChoice && (request.toolChoice === 'required' || typeof request.toolChoice === 'object');
+        const fixedToolChoice = forcesTool(request.toolChoice);
         if (fixedToolChoice && (!tools || tools.length === 0)) {
             throw new Error(`Prompt ${this.input.name} is configured to require tools, but no tools are available.`);
         }
@@ -271,13 +278,26 @@ export class Prompt {
             // Pre-emptively trim context messages if we have a context window limit
             request.messages = this.forget(request, ctx);
         }
+        // Without a conversation the request still needs a user turn: APIs such
+        // as Anthropic's and Bedrock's reject a request that has none
+        if (request.messages.length === 1) {
+            request.messages.push({ role: 'user', content: this.input.userTurn ?? ctx.userTurn ?? DEFAULT_USER_TURN });
+        }
         let outputRetries = this.input.outputRetries ?? ctx.outputRetries ?? 2;
         let forgetRetries = this.input.forgetRetries ?? ctx.forgetRetries ?? 1;
         let toolIterations = this.input.toolIterations ?? 3;
         let toolRetries = this.input.toolRetries ?? ctx.toolRetries ?? 2;
+        let reviewRetries = this.input.reviewRetries ?? 1;
+        let reviews = 0;
         const toolsComplete = this.input.toolsComplete ?? true;
+        const schemaFallbacks = this.input.schemaFallbacks ?? ctx.schemaFallbacks ?? SCHEMA_FALLBACKS;
+        // Schema fallbacks taken this run, re-applied when a dynamic prompt
+        // re-resolves its request.
+        const fallbacksTaken = [];
         let result = undefined;
         let lastError = undefined;
+        // The last tool failure, the cause when the iterations run out.
+        let toolFailure = undefined;
         let completeText = '';
         // Runtime schema-delivery fallback guard. A model whose descriptor ALLOWS
         // the schema (so the static `canExpress` check passes and structured output
@@ -290,7 +310,7 @@ export class Prompt {
         // idempotent within a single prompt run — we switch at most once and never
         // loop. Per-run only; nothing is persisted across requests.
         let promotedToPromptDelivery = false;
-        let maxIterations = outputRetries + forgetRetries + toolIterations + toolRetries + 1;
+        let maxIterations = outputRetries + forgetRetries + toolIterations + toolRetries + reviewRetries + 1;
         let requestUsageSent = false;
         let usage = undefined;
         let iterations = 0;
@@ -314,6 +334,30 @@ export class Prompt {
             request.messages.push(message);
             return emit({ type: 'message', message, request });
         };
+        // The events a tool execution is ready to emit, each emitted once.
+        const toolEvents = function* (te) {
+            const { tool, args } = te;
+            const toolCallId = te.toolCall.id;
+            if (te.emitRepairAttempt()) {
+                yield emit({ type: 'toolArgRepairAttempt', tool: tool, fields: te.repairAttempt.fields, success: te.repairAttempt.success, request });
+            }
+            if (te.emitStart()) {
+                yield emitTool({ type: 'toolStart', tool: tool, toolCallId, args, request });
+            }
+            if (te.emitOutput()) {
+                yield emitTool({ type: 'toolOutput', tool: tool, toolCallId, args, result: te.result, toModel: te.toModel, request });
+            }
+            if (te.emitInterrupt()) {
+                yield emitTool({ type: 'toolInterrupt', tool: tool, toolCallId, args, request });
+            }
+            if (te.emitSuspend()) {
+                yield emitTool({ type: 'toolSuspend', tool: tool, toolCallId, args, request });
+            }
+            if (te.emitError()) {
+                const failure = te.error;
+                yield emitTool({ type: 'toolError', tool: tool, toolCallId, args, error: failure.message, failure, rawArgs: failure instanceof ToolInputError ? failure.rawArgs : undefined, request });
+            }
+        };
         // Main execution loop!
         while (iterations < maxIterations) {
             // Honor the caller's abort signal at iteration boundaries — if a
@@ -377,6 +421,18 @@ export class Prompt {
                         reasoning = accumulateReasoning(reasoning, chunk.reasoning);
                         yield emit({ type: 'reasonPartial', reasoning, request });
                     }
+                    if (chunk.citations) {
+                        yield emit({ type: 'citations', citations: chunk.citations, request });
+                    }
+                    if (chunk.images) {
+                        yield emit({ type: 'images', images: chunk.images, request });
+                    }
+                    if (chunk.audio) {
+                        yield emit({ type: 'audioPartial', audio: chunk.audio, request });
+                    }
+                    if (chunk.moderation) {
+                        yield emit({ type: 'moderation', moderation: chunk.moderation, request });
+                    }
                     // Handle tool calls
                     if (chunk.toolCallNamed) {
                         const toolName = chunk.toolCallNamed.name;
@@ -405,7 +461,7 @@ export class Prompt {
                         // value short-circuits, false/undefined proceeds, a throw
                         // propagates through run()'s existing catch (interrupt/suspend/error).
                         onToolIntercept && toolInfo
-                            ? (args) => onToolIntercept(toolInfo.tool, args, ctx)
+                            ? (args, call) => onToolIntercept(toolInfo.tool, args, ctx, call)
                             : undefined);
                         toolExecutors.push(toolExecutor);
                         toolExecutorMap.set(chunk.toolCallNamed.id, toolExecutor);
@@ -446,21 +502,7 @@ export class Prompt {
                     // In immediate mode we might be getting more chunks while executing, emit events as soon as possible.
                     if (toolMode === 'immediate') {
                         for (const toolCall of toolExecutors) {
-                            if (toolCall.emitStart()) {
-                                yield emitTool({ type: 'toolStart', tool: toolCall.tool, args: toolCall.args, request });
-                            }
-                            if (toolCall.emitOutput()) {
-                                yield emitTool({ type: 'toolOutput', tool: toolCall.tool, args: toolCall.args, result: toolCall.result, toModel: toolCall.toModel, request });
-                            }
-                            if (toolCall.emitInterrupt()) {
-                                yield emitTool({ type: 'toolInterrupt', tool: toolCall.tool, args: toolCall.args, request });
-                            }
-                            if (toolCall.emitSuspend()) {
-                                yield emitTool({ type: 'toolSuspend', tool: toolCall.tool, args: toolCall.args, request });
-                            }
-                            if (toolCall.emitError()) {
-                                yield emitTool({ type: 'toolError', tool: toolCall.tool, args: toolCall.args, error: toolCall.error, rawArgs: toolCall.rawArgs, request });
-                            }
+                            yield* toolEvents(toolCall);
                         }
                     }
                 }
@@ -472,13 +514,13 @@ export class Prompt {
                 // If the model refused to answer and stop
                 if (finishReason === 'refusal' || refusal) {
                     yield emit({ type: 'refusal', content: refusal || 'unspecified', request });
-                    lastError = refusal || 'Model refused to answer.';
+                    lastError = new PromptError(refusal || 'Model refused to answer.', 'model');
                     break;
                 }
                 // If the model was stopped due to content filtering
                 if (finishReason === 'content_filter') {
                     yield emit({ type: 'refusal', content: 'Content filtered by AI model', request });
-                    lastError = 'Model response was filtered due to content policy.';
+                    lastError = new PromptError('Model response was filtered due to content policy.', 'model');
                     break;
                 }
                 // If we sent too much, forget the past homie 
@@ -492,7 +534,7 @@ export class Prompt {
                     }
                     else {
                         // Stop iteration - we can't trim without usage info
-                        lastError = 'Model indicated length finish reason but no token usage was provided so context cannot be trimmed.';
+                        lastError = new PromptError('Model indicated length finish reason but no token usage was provided so context cannot be trimmed.', 'model');
                         break;
                     }
                 }
@@ -520,18 +562,19 @@ export class Prompt {
                             // Non-blocking call, we don't want to hold up execution here. But if we can emit start or error early below this we will try.
                             toolExecutor.parse();
                         }
-                        if (toolExecutor.emitRepairAttempt()) {
-                            yield emit({ type: 'toolArgRepairAttempt', tool: toolExecutor.tool, fields: toolExecutor.repairAttempt.fields, success: toolExecutor.repairAttempt.success, request });
-                        }
-                        if (toolExecutor.emitStart()) {
-                            yield emitTool({ type: 'toolStart', tool: toolExecutor.tool, args: toolExecutor.args, request });
-                        }
-                        if (toolExecutor.emitError()) {
-                            yield emitTool({ type: 'toolError', tool: toolExecutor.tool, args: toolExecutor.args, error: toolExecutor.error, rawArgs: toolExecutor.rawArgs, request });
-                        }
+                        yield* toolEvents(toolExecutor);
                     }
-                    // The execution mode for this iteration.
+                    // The execution mode for this iteration. Skipping leaves every valid
+                    // sibling unrun, and its reply says so.
                     const iterationMode = skip ? 'skip' : toolMode;
+                    if (skip) {
+                        for (const toolExecutor of toolExecutors) {
+                            // Only a call that has not started: under 'immediate' a valid call may
+                            // already be running, and its reply is its real outcome.
+                            if (!toolExecutor.error && (toolExecutor.status === 'ready' || toolExecutor.status === 'parsed'))
+                                toolExecutor.skipped = true;
+                        }
+                    }
                     // All tool calls are valid, lets start this!
                     switch (iterationMode) {
                         case 'sequential':
@@ -547,25 +590,9 @@ export class Prompt {
                                 if (ctx.signal?.aborted)
                                     break;
                                 await toolExecutor.parse();
-                                if (toolExecutor.emitRepairAttempt()) {
-                                    yield emit({ type: 'toolArgRepairAttempt', tool: toolExecutor.tool, fields: toolExecutor.repairAttempt.fields, success: toolExecutor.repairAttempt.success, request });
-                                }
-                                if (toolExecutor.emitStart()) {
-                                    yield emitTool({ type: 'toolStart', tool: toolExecutor.tool, args: toolExecutor.args, request });
-                                }
+                                yield* toolEvents(toolExecutor);
                                 await toolExecutor.run();
-                                if (toolExecutor.emitOutput()) {
-                                    yield emitTool({ type: 'toolOutput', tool: toolExecutor.tool, args: toolExecutor.args, result: toolExecutor.result, toModel: toolExecutor.toModel, request });
-                                }
-                                if (toolExecutor.emitInterrupt()) {
-                                    yield emitTool({ type: 'toolInterrupt', tool: toolExecutor.tool, args: toolExecutor.args, request });
-                                }
-                                if (toolExecutor.emitSuspend()) {
-                                    yield emitTool({ type: 'toolSuspend', tool: toolExecutor.tool, args: toolExecutor.args, request });
-                                }
-                                if (toolExecutor.emitError()) {
-                                    yield emitTool({ type: 'toolError', tool: toolExecutor.tool, args: toolExecutor.args, error: toolExecutor.error, rawArgs: toolExecutor.rawArgs, request });
-                                }
+                                yield* toolEvents(toolExecutor);
                             }
                             break;
                         case 'parallel':
@@ -582,25 +609,7 @@ export class Prompt {
                                 // listener was already removed before tool dispatch.)
                                 if (ctx.signal?.aborted)
                                     break;
-                                const toolExecutor = await toolCallPromise;
-                                if (toolExecutor.emitRepairAttempt()) {
-                                    yield emit({ type: 'toolArgRepairAttempt', tool: toolExecutor.tool, fields: toolExecutor.repairAttempt.fields, success: toolExecutor.repairAttempt.success, request });
-                                }
-                                if (toolExecutor.emitStart()) {
-                                    yield emitTool({ type: 'toolStart', tool: toolExecutor.tool, args: toolExecutor.args, request });
-                                }
-                                if (toolExecutor.emitOutput()) {
-                                    yield emitTool({ type: 'toolOutput', tool: toolExecutor.tool, args: toolExecutor.args, result: toolExecutor.result, toModel: toolExecutor.toModel, request });
-                                }
-                                if (toolExecutor.emitInterrupt()) {
-                                    yield emitTool({ type: 'toolInterrupt', tool: toolExecutor.tool, args: toolExecutor.args, request });
-                                }
-                                if (toolExecutor.emitSuspend()) {
-                                    yield emitTool({ type: 'toolSuspend', tool: toolExecutor.tool, args: toolExecutor.args, request });
-                                }
-                                if (toolExecutor.emitError()) {
-                                    yield emitTool({ type: 'toolError', tool: toolExecutor.tool, args: toolExecutor.args, error: toolExecutor.error, rawArgs: toolExecutor.rawArgs, request });
-                                }
+                                yield* toolEvents(await toolCallPromise);
                             }
                             break;
                     }
@@ -644,7 +653,7 @@ export class Prompt {
                         // exactly as before: strings verbatim, everything else JSON.
                         const modelValue = toolExecutor.status === 'success' ? toolExecutor.toModel : toolExecutor.result;
                         const content = hasError
-                            ? toolExecutor.error
+                            ? toolExecutor.error.message
                             : hasResult
                                 ? typeof modelValue === 'string'
                                     ? modelValue
@@ -654,7 +663,9 @@ export class Prompt {
                             role: 'tool',
                             content,
                             toolCallId: toolExecutor.toolCall.id,
+                            failure: toolExecutor.error?.kind,
                         });
+                        toolFailure = toolExecutor.error ?? toolFailure;
                         if (toolExecutor.status === 'invalid') {
                             toolParseErrors++;
                         }
@@ -718,9 +729,9 @@ export class Prompt {
                     toolExecutors.some(toolExecutor => toolExecutor.status === 'interrupted');
                 // If we are finished, parse the output
                 if (stop) {
+                    let failure;
                     if (!schema || (schema instanceof ZodString)) {
                         result = content;
-                        break; // All good!
                     }
                     else {
                         // Grab the JSON part from the content just in case. In the
@@ -728,9 +739,10 @@ export class Prompt {
                         // freeform text (possibly fenced / prose-wrapped), so extract the
                         // outermost balanced `{…}` (see `extractJSONObject`).
                         const potentialJSON = extractJSONObject(content);
-                        let errorMessage = '';
-                        let resetReason = '';
-                        const errMax = this.input.validationErrorMaxLength;
+                        const invalid = (message, reason) => new OutputValidationError(this.truncateValidationError(message, this.input.validationErrorMaxLength), reason, content);
+                        // The descriptor the provider shaped the output with, when the
+                        // schema went on the wire.
+                        const descriptorId = structuredOutput(request.responseFormat)?.descriptor;
                         try {
                             const parsedJSON = JSON.parse(potentialJSON);
                             if (this.input.parse) {
@@ -749,11 +761,8 @@ export class Prompt {
                                 // (no Zod vocabulary — Zod never ran). Absent ⇒ unchanged.
                                 // Decode only when a descriptor was pinned; otherwise the wire
                                 // shape IS the conceptual shape and `parsedJSON` passes through.
-                                const customDescriptorId = typeof request.responseFormat === 'object'
-                                    ? request.responseFormat.descriptor
-                                    : undefined;
-                                const decoded = customDescriptorId
-                                    ? decodeWire(schema, parsedJSON, getDescriptorById(customDescriptorId))
+                                const decoded = descriptorId
+                                    ? decodeWire(schema, parsedJSON, getDescriptorById(descriptorId))
                                     : parsedJSON;
                                 let customResult;
                                 try {
@@ -763,8 +772,7 @@ export class Prompt {
                                     customResult = customError instanceof Error ? customError : new Error(String(customError));
                                 }
                                 if (customResult instanceof Error) {
-                                    errorMessage = this.truncateValidationError(customResult.message, errMax);
-                                    resetReason = 'schema-parsing';
+                                    failure = invalid(customResult.message, 'schema-parsing');
                                 }
                                 else {
                                     result = customResult;
@@ -772,8 +780,7 @@ export class Prompt {
                                         await this.input.validate?.(result, ctx);
                                     }
                                     catch (validationError) {
-                                        errorMessage = this.truncateValidationError(`The output failed validation:\n${validationError.message}`, errMax);
-                                        resetReason = 'validation';
+                                        failure = invalid(`The output failed validation:\n${validationError.message}`, 'validation');
                                     }
                                 }
                             }
@@ -783,19 +790,15 @@ export class Prompt {
                                 // normalize back into the natural Zod shape before validation.
                                 // The descriptor was pinned on the response format when the
                                 // provider built the request. Fast cache lookup on retries.
-                                const responseDescriptorId = typeof request.responseFormat === 'object'
-                                    ? request.responseFormat.descriptor
-                                    : undefined;
-                                const validationSchema = responseDescriptorId
-                                    ? strictify(schema, getDescriptorById(responseDescriptorId))
+                                const validationSchema = descriptorId
+                                    ? strictify(schema, getDescriptorById(descriptorId))
                                     : schema;
                                 const parsedSafe = await validationSchema.safeParseAsync(parsedJSON);
                                 if (!parsedSafe.success) {
                                     const issueSummary = parsedSafe.error.issues
                                         .map(i => `- ${i.path.join('.')}: ${i.message}${['string', 'boolean', 'number'].includes(typeof i.input) ? ` (input: ${i.input})` : ''}`)
                                         .join('\n');
-                                    errorMessage = this.truncateValidationError(`The output was an invalid format:\n${issueSummary}`, errMax);
-                                    resetReason = 'schema-parsing';
+                                    failure = invalid(`The output was an invalid format:\n${issueSummary}`, 'schema-parsing');
                                 }
                                 else {
                                     result = parsedSafe.data;
@@ -803,15 +806,13 @@ export class Prompt {
                                         await this.input.validate?.(result, ctx);
                                     }
                                     catch (validationError) {
-                                        errorMessage = this.truncateValidationError(`The output failed validation:\n${validationError.message}`, errMax);
-                                        resetReason = 'validation';
+                                        failure = invalid(`The output failed validation:\n${validationError.message}`, 'validation');
                                     }
                                 }
                             }
                         }
                         catch (parseError) {
-                            errorMessage = this.truncateValidationError(`The output was not valid JSON:\n${parseError.message}`, errMax);
-                            resetReason = 'json-parsing';
+                            failure = invalid(`The output was not valid JSON:\n${parseError.message}`, 'json-parsing');
                         }
                         // Runtime schema-delivery fallback. The structured response was EMPTY
                         // or its JSON was UNPARSEABLE (`json-parsing` reset — either the
@@ -830,39 +831,73 @@ export class Prompt {
                         // The switch is not remembered beyond this run. This reuses the
                         // existing outputRetries re-prompt mechanism below to re-issue.
                         if (this.input.runtimeSchemaFallback !== false &&
-                            resetReason === 'json-parsing' &&
+                            failure?.reason === 'json-parsing' &&
                             !promotedToPromptDelivery &&
                             typeof request.responseFormat === 'object' &&
                             (request.responseFormat.schemaDelivery ?? 'auto') === 'auto') {
                             request.responseFormat.schemaDelivery = 'prompt';
                             promotedToPromptDelivery = true;
                         }
-                        if (errorMessage) {
-                            if (outputRetries > 0) {
-                                outputRetries--;
-                                yield emit({ type: 'textReset', reason: resetReason, request });
-                                yield emitMessage({
-                                    role: 'user',
-                                    content: errorMessage,
-                                });
-                            }
-                            else {
-                                lastError = errorMessage;
-                                break; // No more retries left
-                            }
+                    }
+                    if (failure) {
+                        result = undefined;
+                        if (outputRetries > 0) {
+                            outputRetries--;
+                            yield emit({ type: 'textReset', reason: failure.reason, error: failure, request });
+                            yield emitMessage({
+                                role: 'user',
+                                content: failure.message,
+                            });
                         }
                         else {
-                            // A result was successfully parsed and validated!
+                            lastError = failure;
+                            break; // No more retries left
+                        }
+                    }
+                    else if (this.input.review) {
+                        // A valid result goes to the review, whose feedback asks the model
+                        // to answer again.
+                        const output = result;
+                        const attempt = ++reviews;
+                        yield emit({ type: 'reviewStart', output, attempt, request });
+                        const verdict = await this.input.review(output, { input, request, ctx, attempt });
+                        if ('pass' in verdict) {
+                            yield emit({ type: 'reviewPass', output, attempt, request });
                             lastError = undefined;
                             break;
                         }
+                        yield emit({ type: 'reviewFeedback', output, feedback: verdict.feedback, attempt, request });
+                        result = undefined;
+                        if (reviewRetries <= 0) {
+                            lastError = new ReviewRejectedError(output, verdict.feedback);
+                            break;
+                        }
+                        reviewRetries--;
+                        yield emitMessage({ role: 'user', content: verdict.feedback });
+                    }
+                    else {
+                        // A result was successfully parsed and validated!
+                        lastError = undefined;
+                        break;
                     }
                 }
             }
             catch (requestError) {
-                if (!ctx.signal?.aborted &&
-                    !streamController.signal.aborted &&
-                    this.input.runtimeSchemaFallback !== false &&
+                const recoverable = !ctx.signal?.aborted && !streamController.signal.aborted && this.input.runtimeSchemaFallback !== false;
+                // A classified schema rejection takes the first schema fallback not
+                // yet taken for its schema that applies, and the request goes again.
+                // The step stays on the request, so later iterations start there.
+                const rejected = requestError instanceof SchemaRejectedError ? requestError : undefined;
+                const fallback = rejected && recoverable
+                    ? schemaFallbacks.find(step => !fallbacksTaken.some(([taken, target]) => taken === step && sameTarget(target, rejected.target)) && step.apply(request, rejected.target))
+                    : undefined;
+                if (rejected && fallback) {
+                    fallbacksTaken.push([fallback, rejected.target]);
+                    yield emit({ type: 'schemaFallback', fallback: fallback.name, error: rejected, request });
+                    continue;
+                }
+                if (!rejected &&
+                    recoverable &&
                     !promotedToPromptDelivery &&
                     typeof request.responseFormat === 'object' &&
                     (request.responseFormat.schemaDelivery ?? 'auto') === 'auto' &&
@@ -943,6 +978,7 @@ export class Prompt {
                 systemMessage.content = dynamicContent;
                 request.tools = dynamicTools;
                 request.responseFormat = dynamicResponseFormat;
+                fallbacksTaken.forEach(([step, target]) => step.apply(request, target));
                 // Update toolMap with new tool objects
                 toolMap.clear();
                 if (dynamicToolObjects) {
@@ -987,13 +1023,11 @@ export class Prompt {
             if (ctx.signal?.aborted) {
                 return undefined;
             }
-            if (!lastError && iterations === maxIterations) {
-                lastError = `Maximum iterations (${maxIterations}) reached without a valid response.`;
-            }
-            if (!lastError) {
-                lastError = `Prompt ${this.input.name} failed without a specified error.`;
-            }
-            throw new Error(`Prompt ${this.input.name} failed: ${lastError}`);
+            const reason = lastError?.message ?? (iterations === maxIterations
+                ? `Maximum iterations (${maxIterations}) reached without a valid response.`
+                : `Prompt ${this.input.name} failed without a specified error.`);
+            const cause = lastError ?? toolFailure;
+            throw new PromptError(`Prompt ${this.input.name} failed: ${reason}`, cause?.kind ?? 'model', cause);
         }
         yield emit({ type: 'complete', output: result, request });
         return result;
@@ -1057,19 +1091,16 @@ export class Prompt {
                 .filter(r => r.applicable)
                 .map(r => r.tool);
         }
-        const toolInstructions = selectedTools && selectedTools.length > 0
-            ? (await Promise.all(selectedTools.map(t => t.compile(ctx)))).filter(t => !!t)
-            : undefined;
-        const instructions = toolInstructions
-            ? toolInstructions.map(t => t[0]).join("\n\n")
+        // Each tool with its compiled instructions and definition; a tool that
+        // doesn't compile (no schema) is left out, and one without instructions
+        // adds nothing to the tools section
+        const compiled = selectedTools && selectedTools.length > 0
+            ? (await Promise.all(selectedTools.map(async (tool) => ({ tool, compiled: await tool.compile(ctx) }))))
+                .flatMap(({ tool, compiled }) => compiled ? [{ tool, instructions: compiled[0], definition: compiled[1] }] : [])
             : undefined;
-        const tools = toolInstructions
-            ? toolInstructions.map(t => t[1])
-            : undefined;
-        // Create toolObjects as array of { tool, definition } pairs
-        const toolObjects = selectedTools && toolInstructions
-            ? selectedTools.map((tool, i) => ({ tool, definition: toolInstructions[i][1] }))
-            : [];
+        const instructions = compiled?.map(c => c.instructions).filter(Boolean).join("\n\n");
+        const tools = compiled?.map(c => c.definition);
+        const toolObjects = compiled?.map(({ tool, definition }) => ({ tool, definition })) ?? [];
         // Compute the input that is fed to the prompt's prompt content
         let contentInput = input;
         const translated = await this.translate(input, ctx);
@@ -1128,7 +1159,8 @@ export class Prompt {
      * `ToolInterrupt` cutting a parallel batch short) or a tool errored
      * before its content could be accumulated.
      *
-     * The marker prefix (`[aborted: …]`, `[interrupted]`, `[error: …]`)
+     * The marker prefix (`[aborted: …]`, `[interrupted]`, `[error: …]`,
+     * `[not run: …]` for a valid call skipped because a sibling was invalid)
      * gives the model a clear cue and lets callers detect synthesized
      * replies by inspecting the message content if they need to
      * differentiate. Suspended tools are intentionally NOT routed
@@ -1140,15 +1172,18 @@ export class Prompt {
      * result, or fall back to a model-specific instruction string.
      */
     synthesizeUnpairedResult(te) {
+        if (te.skipped) {
+            return '[not run: another call in this batch was invalid; call it again]';
+        }
         switch (te.status) {
             case 'interrupted':
                 return te.error
-                    ? `[interrupted: ${te.error}]`
+                    ? `[interrupted: ${te.error.message}]`
                     : '[interrupted]';
             case 'error':
             case 'invalid':
                 return te.error
-                    ? `[error: ${te.error}]`
+                    ? `[error: ${te.error.message}]`
                     : '[error]';
             case 'ready':
             case 'parsed':
@@ -1173,6 +1208,16 @@ export class Prompt {
      * 2. A token estimation function is provided in the context (we can estimate token counts)
      * 3. Messages already have token counts assigned (we can use these directly)
      *
+     * What is removed, oldest first, is whole groups: a message together with
+     * the `role: 'tool'` replies that follow it, so an assistant's
+     * `tool_calls` never lose their replies (providers reject that history).
+     * System messages and the last user message are always kept. Groups after
+     * the last user message (an agent's tool loop) are removed too when the
+     * earlier history is not enough, except the most recent group.
+     *
+     * `protected` so a subclass can replace it, for example to summarize the
+     * removed history instead of dropping it.
+     *
      * @param request - The original request with messages.
      * @param ctx - The context containing message history and token estimation.
      * @param usage - The current token usage.
@@ -1249,30 +1294,45 @@ export class Prompt {
             return request.messages;
         }
         const removeTokens = totalMessageTokensFinal - maxInput;
-        // Calculate where to start trimming and where to stop
-        const messageMinIndex = request.messages.findIndex(m => m.role === 'system') + 1; // inclusive
-        let messageMaxIndex = request.messages.findLastIndex(m => m.role === 'user'); // exclusive
-        if (messageMaxIndex === -1) {
-            messageMaxIndex = request.messages.length;
-        }
-        const trimmedMessages = request.messages.slice(0, messageMinIndex);
-        let removesRemaining = removeTokens;
-        let messageIndex = messageMinIndex;
-        while (removesRemaining > 0 && messageIndex < messageMaxIndex) {
-            const message = request.messages[messageIndex];
-            if (message.role === 'system') {
-                trimmedMessages.push(message);
-                messageIndex++;
+        // Group the history: each message with the tool replies that follow it.
+        const messages = request.messages;
+        const groups = [];
+        for (let i = 0; i < messages.length; i++) {
+            const last = groups[groups.length - 1];
+            if (messages[i].role === 'tool' && last) {
+                last.end = i + 1;
             }
             else {
-                removesRemaining -= messageTokens[messageIndex] || 0;
-                messageIndex++;
+                groups.push({ start: i, end: i + 1 });
             }
         }
-        trimmedMessages.push(...request.messages.slice(messageIndex));
-        return trimmedMessages;
+        const lastUser = messages.findLastIndex(m => m.role === 'user');
+        const finalGroup = groups[groups.length - 1];
+        const removable = (group) => {
+            const first = messages[group.start];
+            return first.role !== 'system' && group.start !== lastUser && group !== finalGroup;
+        };
+        // Oldest first: the history before the last user message, then the tool loop after it.
+        const order = groups.filter(removable);
+        const removed = new Set();
+        let removesRemaining = removeTokens;
+        for (const group of order) {
+            if (removesRemaining <= 0)
+                break;
+            for (let i = group.start; i < group.end; i++) {
+                removed.add(i);
+                removesRemaining -= messageTokens[i] || 0;
+            }
+        }
+        return messages.filter((_, i) => !removed.has(i));
     }
 }
+/**
+ * Whether two schema targets name the same schema.
+ */
+function sameTarget(a, b) {
+    return a.kind === 'tool' && b.kind === 'tool' ? a.name === b.name : a.kind === b.kind;
+}
 function once(fn) {
     let promise;
     return () => {
@@ -1313,7 +1373,7 @@ truncate,
 present, 
 // Optional per-prompt tool interceptor (PromptInput.onToolIntercept),
 // pre-bound by the loop with the matched Tool instance + ctx so this
-// function only needs the parsed args. Runs INSIDE run() BEFORE the tool's
+// function only needs the parsed args and the tool call. Runs INSIDE run() BEFORE the tool's
 // own handler. A returned VALUE short-circuits and becomes `result` (the
 // handler is skipped, then the normal present/success path runs). Returning
 // `false`/`undefined` means "not intercepted" — the real handler runs. A
@@ -1336,7 +1396,7 @@ intercept) {
         tool: toolInfo?.tool,
         definition: toolInfo?.definition,
         status: toolInfo ? 'ready' : 'error',
-        error: toolInfo ? undefined : `Tool not found: ${toolCall.name}`,
+        error: toolInfo ? undefined : new ToolInputError(toolCall.name, `Tool not found: ${toolCall.name}`),
         emitStart: start.emit,
         emitOutput: output.emit,
         emitError: error.emit,
@@ -1367,10 +1427,6 @@ intercept) {
             }
             catch (e) {
                 execution.status = 'invalid';
-                // Preserve the untruncated raw args alongside the truncated
-                // model-facing error so the diagnostic log gets the full
-                // payload (post-mortem reproduction is impossible without it).
-                execution.rawArgs = args;
                 // Distinguish "model sent no arguments at all" from "model sent
                 // bad arguments". The former is usually a streaming-relay issue
                 // (OpenRouter/Anthropic) or a genuine model gaffe — calling it
@@ -1382,9 +1438,9 @@ intercept) {
                     ? `the tool was called with NO arguments. The schema requires arguments — re-call this tool with the required fields populated. Validation: ${e.message}`
                     : `${e.message}, args: ${args}`;
                 const formatted = `Error parsing tool arguments: ${reason}`;
-                execution.error = truncate
-                    ? truncate(formatted, validationErrorMaxLength)
-                    : formatted;
+                // The untruncated raw args go alongside the truncated model-facing
+                // message so the diagnostic log gets the full payload.
+                execution.error = new ToolInputError(toolCall.name, truncate ? truncate(formatted, validationErrorMaxLength) : formatted, args);
                 error.ready = true;
             }
             return execution;
@@ -1403,7 +1459,7 @@ intercept) {
                 // is intentionally NOT caught here — it flows to the catch below and
                 // is routed exactly like a throw from the handler (ToolInterrupt ⇒
                 // interrupted, PromptSuspend ⇒ suspended, else ⇒ tool error).
-                const intercepted = intercept ? await intercept(execution.args) : false;
+                const intercepted = intercept ? await intercept(execution.args, execution.toolCall) : false;
                 execution.result = intercepted === false || intercepted === undefined
                     ? await resolve(toolInfo.tool.run(execution.args, { ...ctx, toolCallId: toolCall.id }))
                     : intercepted;
@@ -1420,7 +1476,7 @@ intercept) {
                 }
                 catch (e) {
                     execution.status = 'error';
-                    execution.error = `Error transforming tool result: ${e.message}`;
+                    execution.error = new ToolExecutionError(toolCall.name, `Error transforming tool result: ${e.message}`, e);
                     error.ready = true;
                     return execution;
                 }
@@ -1438,7 +1494,7 @@ intercept) {
                 }
                 else {
                     execution.status = 'error';
-                    execution.error = `Error executing tool: ${e.message}, args: ${JSON.stringify(execution.args)}`;
+                    execution.error = new ToolExecutionError(toolCall.name, `Error executing tool: ${e.message}, args: ${JSON.stringify(execution.args)}`, e);
                     error.ready = true;
                 }
             }