@pencil-agent/nano-pencil 1.14.2 → 1.14.4

package/dist/node_modules/@pencil-agent/agent-core/structured-adaptive-agent-loop.js

@@ -5,17 +5,21 @@
  */
 /**
  * [WHO]: structuredAdaptiveAgentLoop, structuredAdaptiveAgentLoopContinue
- * [FROM]: Depends on @pencil-agent/ai, ./types, ./errors, ./structured-adaptive-tool-orchestration
+ * [FROM]: Depends on @pencil-agent/ai, ./types, ./errors, ./structured-adaptive-tool-orchestration, ./structured-adaptive-streaming-tool-executor
  * [TO]: Consumed by packages/agent-core/src/agent.ts and index.ts
  * [HERE]: packages/agent-core/src/structured-adaptive-agent-loop.ts - selectable structured-adaptive query loop framework
  */
 import { EventStream, isContextOverflow, streamSimple, } from "@pencil-agent/ai";
-import { runStructuredAdaptiveTools } from "./structured-adaptive-tool-orchestration.js";
+import { resolveMaxToolConcurrency, runStructuredAdaptiveTools, } from "./structured-adaptive-tool-orchestration.js";
+import { StructuredAdaptiveStreamingToolExecutor } from "./structured-adaptive-streaming-tool-executor.js";
 import { ValidationError } from "./errors.js";
 const DEFAULT_MAX_TURNS_PER_PROMPT = 64;
 const DEFAULT_MAX_TOOL_CALLS_PER_PROMPT = 128;
 const DEFAULT_MAX_OUTPUT_TOKEN_RECOVERY_ATTEMPTS = 1;
 const DEFAULT_MAX_STOP_HOOK_CONTINUATIONS = 3;
+const DEFAULT_MAX_MODEL_ERROR_RECOVERY_ATTEMPTS = 1;
+const DEFAULT_OUTPUT_TOKEN_BUDGET_THRESHOLD_PCT = 0.9;
+const DEFAULT_OUTPUT_TOKEN_BUDGET_CONTINUATIONS = 3;
 export function structuredAdaptiveAgentLoop(prompts, context, config, signal, streamFn) {
     const stream = createAgentStream();
     (async () => {
@@ -69,14 +73,18 @@ async function runStructuredAdaptiveQueryLoop(currentContext, newMessages, confi
     const maxToolCalls = config.maxToolCallsPerPrompt ?? DEFAULT_MAX_TOOL_CALLS_PER_PROMPT;
     const maxOutputTokenRecoveryAttempts = config.maxOutputTokenRecoveryAttempts ?? DEFAULT_MAX_OUTPUT_TOKEN_RECOVERY_ATTEMPTS;
     const maxStopHookContinuations = config.maxStopHookContinuations ?? DEFAULT_MAX_STOP_HOOK_CONTINUATIONS;
+    const maxModelErrorRecoveryAttempts = config.maxModelErrorRecoveryAttempts ?? DEFAULT_MAX_MODEL_ERROR_RECOVERY_ATTEMPTS;
     const state = {
         turnCount: 0,
         toolCallCount: 0,
-        transition: "start",
+        transition: { reason: "start" },
         pendingMessages: (await config.getSteeringMessages?.()) || [],
+        pendingToolUseSummaries: [],
         stopHookActive: false,
         stopHookContinuationCount: 0,
         maxOutputTokensRecoveryCount: 0,
+        modelErrorRecoveryCount: 0,
+        tokenBudgetContinuationCount: 0,
         hasAttemptedReactiveCompact: false,
         startedAt: Date.now(),
         usage: emptyUsage(),
@@ -90,6 +98,7 @@ async function runStructuredAdaptiveQueryLoop(currentContext, newMessages, confi
         else {
             firstTurn = false;
         }
+        flushReadyToolUseSummaries(state, currentContext, newMessages, stream);
         if (state.pendingMessages.length > 0) {
             for (const message of state.pendingMessages) {
                 stream.push({ type: "message_start", message });
@@ -113,20 +122,61 @@ async function runStructuredAdaptiveQueryLoop(currentContext, newMessages, confi
             finish(stream, newMessages, state);
             return;
         }
-        const message = await streamAssistantResponse(currentContext, config, signal, stream, streamFn, state.maxOutputTokensOverride);
+        const streamingToolExecutor = new StructuredAdaptiveStreamingToolExecutor(currentContext.tools, signal, stream, resolveMaxToolConcurrency(config.maxToolConcurrency), config.canUseTool);
+        const message = await streamAssistantResponse(currentContext, config, signal, stream, streamFn, state.maxOutputTokensOverride, streamingToolExecutor);
         newMessages.push(message);
         addUsage(state.usage, message.usage);
         state.maxOutputTokensOverride = undefined;
         if (message.stopReason === "error" || message.stopReason === "aborted") {
-            stream.push({ type: "turn_end", message, toolResults: [] });
+            const errorSubtype = message.stopReason === "aborted"
+                ? "aborted"
+                : isContextOverflow(message, config.model.contextWindow)
+                    ? "context_overflow"
+                    : "model_error";
+            const failedToolExecution = streamingToolExecutor.size > 0
+                ? await streamingToolExecutor.discardAndDrain(message.stopReason === "aborted" ? "assistant stream aborted" : "assistant stream error", message.stopReason === "aborted" ? "cancel" : "all")
+                : { toolResults: [], contextMessages: [], permissionDenials: [] };
+            const toolResults = enforceToolResultBatchSize(failedToolExecution.toolResults, config.maxToolResultBatchSizeChars);
+            state.permissionDenials.push(...failedToolExecution.permissionDenials);
+            for (const result of toolResults) {
+                currentContext.messages.push(result);
+                newMessages.push(result);
+                stream.push({ type: "message_start", message: result });
+                stream.push({ type: "message_end", message: result });
+            }
+            for (const contextMessage of failedToolExecution.contextMessages) {
+                currentContext.messages.push(contextMessage);
+                newMessages.push(contextMessage);
+                stream.push({ type: "message_start", message: contextMessage });
+                stream.push({ type: "message_end", message: contextMessage });
+            }
+            if (message.stopReason === "error" &&
+                config.recoverModelError &&
+                state.modelErrorRecoveryCount < maxModelErrorRecoveryAttempts) {
+                const attempt = state.modelErrorRecoveryCount + 1;
+                const recovery = await config.recoverModelError({
+                    message,
+                    messages: currentContext.messages,
+                    errorSubtype,
+                    attempt,
+                });
+                if (recovery.action === "retry") {
+                    stream.push({ type: "turn_end", message, toolResults });
+                    state.modelErrorRecoveryCount = attempt;
+                    currentContext.messages = recovery.messages;
+                    state.transition =
+                        recovery.transition ?? {
+                            reason: "model_error_recovery",
+                            subtype: errorSubtype,
+                            attempt,
+                        };
+                    continue;
+                }
+            }
+            stream.push({ type: "turn_end", message, toolResults });
             state.finalStopReason = message.stopReason;
             state.finalErrorMessage = message.errorMessage;
-            state.finalErrorSubtype =
-                message.stopReason === "aborted"
-                    ? "aborted"
-                    : isContextOverflow(message, config.model.contextWindow)
-                        ? "context_overflow"
-                        : "model_error";
+            state.finalErrorSubtype = errorSubtype;
             finish(stream, newMessages, state);
             return;
         }
@@ -138,7 +188,10 @@ async function runStructuredAdaptiveQueryLoop(currentContext, newMessages, confi
                 state.maxOutputTokensRecoveryCount += 1;
                 state.maxOutputTokensOverride = computeRecoveryMaxTokens(config, message);
                 state.pendingMessages = [createOutputTokenRecoveryMessage(state.maxOutputTokensRecoveryCount)];
-                state.transition = "follow_up";
+                state.transition = {
+                    reason: "max_output_tokens_recovery",
+                    attempt: state.maxOutputTokensRecoveryCount,
+                };
                 continue;
             }
             if (config.runStopHooks && !state.stopHookActive) {
@@ -164,16 +217,31 @@ async function runStructuredAdaptiveQueryLoop(currentContext, newMessages, confi
                     }
                     state.stopHookContinuationCount += 1;
                     state.pendingMessages = stopHookResult.messages;
-                    state.transition = "follow_up";
+                    state.transition = {
+                        reason: "stop_hook_blocking",
+                        continuationCount: state.stopHookContinuationCount,
+                    };
                     continue;
                 }
             }
+            const tokenBudgetContinuation = maybeCreateTokenBudgetContinuation(config, state);
+            if (tokenBudgetContinuation) {
+                state.tokenBudgetContinuationCount += 1;
+                state.pendingMessages = [tokenBudgetContinuation.message];
+                state.transition = {
+                    reason: "token_budget_continuation",
+                    continuationCount: state.tokenBudgetContinuationCount,
+                    outputTokens: tokenBudgetContinuation.outputTokens,
+                    targetTokens: tokenBudgetContinuation.targetTokens,
+                };
+                continue;
+            }
             const followUpMessages = (await config.getFollowUpMessages?.()) || [];
             if (followUpMessages.length === 0) {
                 break;
             }
             state.pendingMessages = followUpMessages;
-            state.transition = "follow_up";
+            state.transition = { reason: "follow_up" };
             continue;
         }
         if (state.toolCallCount + toolCalls.length > maxToolCalls) {
@@ -190,9 +258,10 @@ async function runStructuredAdaptiveQueryLoop(currentContext, newMessages, confi
             return;
         }
         state.toolCallCount += toolCalls.length;
-        state.pendingToolUseSummary = toolCalls.map((call) => call.name).join(", ");
-        const toolExecution = await runStructuredAdaptiveTools(toolCalls, currentContext.tools, signal, stream, config.getSteeringMessages, config.maxToolConcurrency, config.canUseTool);
-        const toolResults = toolExecution.toolResults;
+        const toolExecution = streamingToolExecutor.size > 0
+            ? await streamingToolExecutor.drain()
+            : await runStructuredAdaptiveTools(toolCalls, currentContext.tools, signal, stream, config.getSteeringMessages, config.maxToolConcurrency, config.canUseTool);
+        const toolResults = enforceToolResultBatchSize(toolExecution.toolResults, config.maxToolResultBatchSizeChars);
         state.permissionDenials.push(...toolExecution.permissionDenials);
         for (const result of toolResults) {
             currentContext.messages.push(result);
@@ -206,6 +275,15 @@ async function runStructuredAdaptiveQueryLoop(currentContext, newMessages, confi
             stream.push({ type: "message_start", message: contextMessage });
             stream.push({ type: "message_end", message: contextMessage });
         }
+        const pendingSummary = startToolUseSummary(config, {
+            assistantMessage: message,
+            toolResults,
+            contextMessages: toolExecution.contextMessages,
+            messages: currentContext.messages,
+        });
+        if (pendingSummary) {
+            state.pendingToolUseSummaries.push(pendingSummary);
+        }
         stream.push({ type: "turn_end", message, toolResults });
         if (toolExecution.steeringMessages && toolExecution.steeringMessages.length > 0) {
             state.pendingMessages = toolExecution.steeringMessages;
@@ -213,12 +291,160 @@ async function runStructuredAdaptiveQueryLoop(currentContext, newMessages, confi
         else {
             state.pendingMessages = (await config.getSteeringMessages?.()) || [];
         }
-        state.transition = "tool_result";
+        state.transition = { reason: "tool_result", toolCallCount: toolCalls.length };
     }
     state.finalStopReason = state.finalStopReason ?? inferStopReason(newMessages);
     finish(stream, newMessages, state);
 }
-async function streamAssistantResponse(context, config, signal, stream, streamFn, maxTokensOverride) {
+function flushReadyToolUseSummaries(state, currentContext, newMessages, stream) {
+    if (state.pendingToolUseSummaries.length === 0) {
+        return;
+    }
+    const pending = [];
+    for (const summary of state.pendingToolUseSummaries) {
+        const result = summary.read();
+        if (!result.settled) {
+            pending.push(summary);
+            continue;
+        }
+        if (!result.value) {
+            continue;
+        }
+        currentContext.messages.push(result.value);
+        newMessages.push(result.value);
+        stream.push({ type: "message_start", message: result.value });
+        stream.push({ type: "message_end", message: result.value });
+    }
+    state.pendingToolUseSummaries = pending;
+}
+function startToolUseSummary(config, event) {
+    if (!config.createToolUseSummary) {
+        return undefined;
+    }
+    try {
+        const value = config.createToolUseSummary({
+            ...event,
+            messages: [...event.messages],
+        });
+        return trackToolUseSummary(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function trackToolUseSummary(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (typeof value.then !== "function") {
+        return {
+            read: () => ({ settled: true, value: value }),
+        };
+    }
+    let settled = false;
+    let settledValue;
+    value.then((summary) => {
+        settled = true;
+        settledValue = summary;
+    }, () => {
+        settled = true;
+        settledValue = undefined;
+    });
+    return {
+        read: () => ({ settled, value: settledValue }),
+    };
+}
+function enforceToolResultBatchSize(toolResults, maxChars) {
+    if (!maxChars || maxChars <= 0 || toolResults.length === 0) {
+        return toolResults;
+    }
+    const limit = Math.floor(maxChars);
+    let currentTotal = sumToolResultTextChars(toolResults);
+    if (currentTotal <= limit) {
+        return toolResults;
+    }
+    const next = [...toolResults];
+    const ranked = toolResults
+        .map((result, index) => ({
+        index,
+        size: sumTextContentChars(result.content),
+        isError: result.isError,
+    }))
+        .filter((candidate) => candidate.size > 0)
+        .sort((a, b) => {
+        if (a.isError !== b.isError)
+            return a.isError ? 1 : -1;
+        return b.size - a.size || a.index - b.index;
+    });
+    for (const candidate of ranked) {
+        if (currentTotal <= limit)
+            break;
+        const reductionNeeded = currentTotal - limit;
+        const targetSize = Math.max(0, candidate.size - reductionNeeded);
+        const truncated = truncateToolResultToTextChars(next[candidate.index], targetSize, limit);
+        next[candidate.index] = truncated.result;
+        currentTotal = currentTotal - candidate.size + truncated.textChars;
+    }
+    return next;
+}
+function truncateToolResultToTextChars(result, targetChars, maxToolResultBatchSizeChars) {
+    const originalTextChars = sumTextContentChars(result.content);
+    if (originalTextChars <= targetChars) {
+        return { result, textChars: originalTextChars };
+    }
+    const note = `[Tool result truncated by batch budget: original ${originalTextChars} chars.]`;
+    let nextText = "";
+    if (targetChars > 0) {
+        if (targetChars <= note.length) {
+            nextText = note.slice(0, targetChars);
+        }
+        else {
+            const suffix = `\n\n${note}`;
+            const bodyBudget = Math.max(0, targetChars - suffix.length);
+            nextText = `${flattenTextContent(result.content).slice(0, bodyBudget)}${suffix}`;
+        }
+    }
+    let hasWrittenText = false;
+    const content = result.content.map((part) => {
+        if (part.type !== "text")
+            return part;
+        if (hasWrittenText) {
+            return { ...part, text: "" };
+        }
+        hasWrittenText = true;
+        return { ...part, text: nextText };
+    });
+    if (!hasWrittenText) {
+        content.push({ type: "text", text: nextText });
+    }
+    return {
+        result: {
+            ...result,
+            content,
+            details: {
+                ...(typeof result.details === "object" && result.details !== null ? result.details : {}),
+                truncationReason: "tool_result_batch_budget",
+                originalTextChars,
+                retainedTextChars: nextText.length,
+                maxToolResultBatchSizeChars,
+            },
+        },
+        textChars: nextText.length,
+    };
+}
+function sumToolResultTextChars(toolResults) {
+    return toolResults.reduce((total, result) => total + sumTextContentChars(result.content), 0);
+}
+function sumTextContentChars(content) {
+    return content.reduce((total, part) => total + (part.type === "text" ? part.text.length : 0), 0);
+}
+function flattenTextContent(content) {
+    return content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("");
+}
+async function streamAssistantResponse(context, config, signal, stream, streamFn, maxTokensOverride, streamingToolExecutor) {
     let messages = context.messages;
     if (config.transformContext) {
         messages = await config.transformContext(messages, signal);
@@ -263,6 +489,16 @@ async function streamAssistantResponse(context, config, signal, stream, streamFn
             case "thinking_end":
             case "toolcall_start":
             case "toolcall_delta":
+                if (partialMessage) {
+                    partialMessage = event.partial;
+                    context.messages[context.messages.length - 1] = partialMessage;
+                    stream.push({
+                        type: "message_update",
+                        assistantMessageEvent: event,
+                        message: { ...partialMessage },
+                    });
+                }
+                break;
             case "toolcall_end":
                 if (partialMessage) {
                     partialMessage = event.partial;
@@ -272,6 +508,7 @@ async function streamAssistantResponse(context, config, signal, stream, streamFn
                         assistantMessageEvent: event,
                         message: { ...partialMessage },
                     });
+                    streamingToolExecutor?.addTool(event.toolCall);
                 }
                 break;
             case "done":
@@ -313,6 +550,38 @@ function createOutputTokenRecoveryMessage(attempt) {
         timestamp: Date.now(),
     };
 }
+function maybeCreateTokenBudgetContinuation(config, state) {
+    const budget = config.outputTokenBudget;
+    if (!budget)
+        return undefined;
+    const targetTokens = Math.max(1, Math.floor(budget.targetTokens));
+    const thresholdPct = clamp(budget.thresholdPct ?? DEFAULT_OUTPUT_TOKEN_BUDGET_THRESHOLD_PCT, 0, 1);
+    const maxContinuations = Math.max(0, Math.floor(budget.maxContinuations ?? DEFAULT_OUTPUT_TOKEN_BUDGET_CONTINUATIONS));
+    if (maxContinuations <= state.tokenBudgetContinuationCount)
+        return undefined;
+    const outputTokens = Math.max(0, Math.floor(state.usage.output));
+    const requiredTokens = Math.ceil(targetTokens * thresholdPct);
+    if (outputTokens >= requiredTokens)
+        return undefined;
+    const message = {
+        role: "user",
+        content: [
+            {
+                type: "text",
+                text: `Continue because the output token budget is underused ` +
+                    `(${outputTokens}/${targetTokens} tokens). Add the missing useful detail directly; ` +
+                    `do not recap or apologize.`,
+            },
+        ],
+        timestamp: Date.now(),
+    };
+    return { message, outputTokens, targetTokens };
+}
+function clamp(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(max, Math.max(min, value));
+}
 function createLoopLimitMessage(config, errorMessage) {
     return {
         role: "assistant",
@@ -345,11 +614,14 @@ function endWithLoopError(stream, newMessages, config, error, signal) {
     const state = {
         turnCount: 0,
         toolCallCount: 0,
-        transition: "start",
+        transition: { reason: "start" },
         pendingMessages: [],
+        pendingToolUseSummaries: [],
         stopHookActive: false,
         stopHookContinuationCount: 0,
         maxOutputTokensRecoveryCount: 0,
+        modelErrorRecoveryCount: 0,
+        tokenBudgetContinuationCount: 0,
         hasAttemptedReactiveCompact: false,
         startedAt: Date.now(),
         usage: emptyUsage(),
@@ -370,6 +642,7 @@ function finish(stream, newMessages, state) {
         usage: state.usage,
         permissionDenialCount: state.permissionDenials.length,
         permissionDenials: state.permissionDenials,
+        lastTransition: state.transition,
         errorMessage: state.finalErrorMessage,
         errorSubtype: state.finalErrorSubtype,
     });

package/dist/node_modules/@pencil-agent/agent-core/structured-adaptive-streaming-tool-executor.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Structured-adaptive streaming tool executor.
+ * Starts complete streamed tool calls before the assistant response finishes,
+ * while preserving ordered tool_result emission for the next model turn.
+ */
+/**
+ * [WHO]: StructuredAdaptiveStreamingToolExecutor
+ * [FROM]: Depends on @pencil-agent/ai, ./types, ./structured-adaptive-tool-orchestration
+ * [TO]: Consumed by ./structured-adaptive-agent-loop.ts
+ * [HERE]: packages/agent-core/src/structured-adaptive-streaming-tool-executor.ts - streaming tool scheduling for weak-model-compatible loop
+ */
+import { EventStream } from "@pencil-agent/ai";
+import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentTool } from "./types.js";
+import { type StructuredAdaptiveToolCall, type StructuredAdaptiveToolRunResult } from "./structured-adaptive-tool-orchestration.js";
+export declare class StructuredAdaptiveStreamingToolExecutor {
+    private readonly stream;
+    private readonly canUseTool?;
+    private readonly toolByName;
+    private readonly records;
+    private readonly maxConcurrency;
+    private discardedReason;
+    private parentAborted;
+    private parentAbortReason;
+    constructor(tools: AgentTool<any>[] | undefined, signal: AbortSignal | undefined, stream: EventStream<AgentEvent, AgentMessage[]>, maxConcurrency: number, canUseTool?: AgentLoopConfig["canUseTool"]);
+    get size(): number;
+    addTool(toolCall: StructuredAdaptiveToolCall): void;
+    drain(): Promise<StructuredAdaptiveToolRunResult>;
+    discardAndDrain(reason: string, abortMode?: "all" | "cancel"): Promise<StructuredAdaptiveToolRunResult>;
+    private processQueue;
+    private canStart;
+    private start;
+    private completeWithSyntheticError;
+}

package/dist/node_modules/@pencil-agent/agent-core/structured-adaptive-streaming-tool-executor.js

@@ -0,0 +1,189 @@
+/**
+ * Structured-adaptive streaming tool executor.
+ * Starts complete streamed tool calls before the assistant response finishes,
+ * while preserving ordered tool_result emission for the next model turn.
+ */
+/**
+ * [WHO]: StructuredAdaptiveStreamingToolExecutor
+ * [FROM]: Depends on @pencil-agent/ai, ./types, ./structured-adaptive-tool-orchestration
+ * [TO]: Consumed by ./structured-adaptive-agent-loop.ts
+ * [HERE]: packages/agent-core/src/structured-adaptive-streaming-tool-executor.ts - streaming tool scheduling for weak-model-compatible loop
+ */
+import { buildToolMap, isStructuredAdaptiveToolCallConcurrencySafe, resolveStructuredAdaptiveToolInterruptBehavior, runStructuredAdaptiveToolUse, } from "./structured-adaptive-tool-orchestration.js";
+export class StructuredAdaptiveStreamingToolExecutor {
+    stream;
+    canUseTool;
+    toolByName;
+    records = [];
+    maxConcurrency;
+    discardedReason;
+    parentAborted = false;
+    parentAbortReason;
+    constructor(tools, signal, stream, maxConcurrency, canUseTool) {
+        this.stream = stream;
+        this.canUseTool = canUseTool;
+        this.toolByName = buildToolMap(tools);
+        this.maxConcurrency = Math.max(1, Math.floor(maxConcurrency));
+        if (signal?.aborted) {
+            this.parentAborted = true;
+            this.parentAbortReason = signal.reason;
+        }
+        else {
+            signal?.addEventListener("abort", () => {
+                this.parentAborted = true;
+                this.parentAbortReason = signal.reason;
+                for (const record of this.records) {
+                    if (record.interruptBehavior === "cancel" && !record.abortController.signal.aborted) {
+                        record.abortController.abort(signal.reason);
+                    }
+                }
+            }, { once: true });
+        }
+    }
+    get size() {
+        return this.records.length;
+    }
+    addTool(toolCall) {
+        if (this.records.some((record) => record.toolCall.id === toolCall.id))
+            return;
+        const tool = this.toolByName.get(toolCall.name);
+        const abortController = new AbortController();
+        const interruptBehavior = resolveStructuredAdaptiveToolInterruptBehavior(toolCall, tool);
+        if (this.parentAborted && interruptBehavior === "cancel") {
+            abortController.abort(this.parentAbortReason);
+        }
+        this.records.push({
+            toolCall,
+            tool,
+            isConcurrencySafe: isStructuredAdaptiveToolCallConcurrencySafe(toolCall, tool),
+            interruptBehavior,
+            status: "queued",
+            abortController,
+            contextMessages: [],
+        });
+        this.processQueue();
+    }
+    async drain() {
+        this.processQueue();
+        while (this.records.some((record) => record.status !== "completed")) {
+            const running = this.records
+                .filter((record) => record.status === "executing" && record.promise)
+                .map((record) => record.promise);
+            if (running.length === 0) {
+                this.processQueue();
+                continue;
+            }
+            await Promise.race(running);
+            this.processQueue();
+        }
+        const toolResults = this.records.map((record) => record.toolResult);
+        return {
+            toolResults,
+            contextMessages: this.records.flatMap((record) => record.contextMessages),
+            permissionDenials: extractPermissionDenials(toolResults),
+        };
+    }
+    async discardAndDrain(reason, abortMode = "all") {
+        this.discardedReason = reason;
+        for (const record of this.records) {
+            if (record.status === "executing" &&
+                (abortMode === "all" || record.interruptBehavior === "cancel") &&
+                !record.abortController.signal.aborted) {
+                record.abortController.abort(reason);
+            }
+            if (record.status === "queued") {
+                this.completeWithSyntheticError(record, reason);
+            }
+        }
+        return this.drain();
+    }
+    processQueue() {
+        for (const record of this.records) {
+            if (record.status !== "queued")
+                continue;
+            if (this.discardedReason) {
+                this.completeWithSyntheticError(record, this.discardedReason);
+                continue;
+            }
+            if (!this.canStart(record)) {
+                if (!record.isConcurrencySafe)
+                    return;
+                continue;
+            }
+            this.start(record);
+        }
+    }
+    canStart(record) {
+        const executing = this.records.filter((candidate) => candidate.status === "executing");
+        if (record.isConcurrencySafe) {
+            return (executing.length < this.maxConcurrency &&
+                executing.every((candidate) => candidate.isConcurrencySafe));
+        }
+        return executing.length === 0;
+    }
+    start(record) {
+        record.status = "executing";
+        record.promise = runStructuredAdaptiveToolUse(record.toolCall, record.tool, record.abortController.signal, this.stream, this.canUseTool)
+            .then((result) => {
+            record.toolResult = result.toolResult;
+            record.contextMessages = result.contextMessages;
+        })
+            .finally(() => {
+            record.status = "completed";
+        });
+    }
+    completeWithSyntheticError(record, reason) {
+        const startedAt = Date.now();
+        const result = {
+            content: [{ type: "text", text: `Tool discarded because ${reason}.` }],
+            details: {
+                errorType: "streaming_tool_discarded",
+                reason,
+                toolName: record.tool?.name ?? record.toolCall.name,
+                toolCallId: record.toolCall.id,
+            },
+        };
+        this.stream.push({
+            type: "tool_execution_start",
+            toolCallId: record.toolCall.id,
+            toolName: record.toolCall.name,
+            args: record.toolCall.arguments,
+        });
+        this.stream.push({
+            type: "tool_execution_end",
+            toolCallId: record.toolCall.id,
+            toolName: record.toolCall.name,
+            result,
+            isError: true,
+            durationMs: Date.now() - startedAt,
+        });
+        record.toolResult = {
+            role: "toolResult",
+            toolCallId: record.toolCall.id,
+            toolName: record.toolCall.name,
+            content: result.content,
+            details: result.details,
+            isError: true,
+            timestamp: Date.now(),
+        };
+        record.contextMessages = [];
+        record.status = "completed";
+    }
+}
+function extractPermissionDenials(toolResults) {
+    const denials = [];
+    for (const result of toolResults) {
+        const details = result.details;
+        if (!details || typeof details !== "object")
+            continue;
+        if (details.errorType !== "permission_denied")
+            continue;
+        const reason = details.reason;
+        denials.push({
+            toolCallId: result.toolCallId,
+            toolName: result.toolName,
+            reason: typeof reason === "string" && reason.length > 0 ? reason : undefined,
+        });
+    }
+    return denials;
+}

package/dist/node_modules/@pencil-agent/agent-core/structured-adaptive-tool-orchestration.d.ts

@@ -20,6 +20,15 @@ export interface StructuredAdaptiveToolRunResult {
     steeringMessages?: AgentMessage[];
     permissionDenials: AgentToolPermissionDenial[];
 }
+interface StructuredAdaptiveToolUseResult {
+    toolResult: ToolResultMessage;
+    contextMessages: AgentMessage[];
+}
 export declare function runStructuredAdaptiveTools(toolCalls: StructuredAdaptiveToolCall[], tools: AgentTool<any>[] | undefined, signal: AbortSignal | undefined, stream: EventStream<AgentEvent, AgentMessage[]>, getSteeringMessages?: AgentLoopConfig["getSteeringMessages"], maxConcurrency?: number, canUseTool?: AgentLoopConfig["canUseTool"]): Promise<StructuredAdaptiveToolRunResult>;
+export declare function resolveMaxToolConcurrency(maxConcurrency: number | undefined): number;
 export declare function buildToolMap(tools: AgentTool<any>[] | undefined): Map<string, AgentTool<any>>;
 export declare function partitionStructuredAdaptiveToolCalls(toolCalls: StructuredAdaptiveToolCall[], toolByName: Map<string, AgentTool<any>>): StructuredAdaptiveToolCall[][];
+export declare function isStructuredAdaptiveToolCallConcurrencySafe(toolCall: StructuredAdaptiveToolCall, tool: AgentTool<any> | undefined): boolean;
+export declare function resolveStructuredAdaptiveToolInterruptBehavior(toolCall: StructuredAdaptiveToolCall, tool: AgentTool<any> | undefined): "cancel" | "block";
+export declare function runStructuredAdaptiveToolUse(toolCall: StructuredAdaptiveToolCall, tool: AgentTool<any> | undefined, signal: AbortSignal | undefined, stream: EventStream<AgentEvent, AgentMessage[]>, canUseTool?: AgentLoopConfig["canUseTool"]): Promise<StructuredAdaptiveToolUseResult>;
+export {};