@pencil-agent/nano-pencil 2.0.0-beta.2 → 2.0.0-beta.4

package/dist/build-meta.json

@@ -1,6 +1,6 @@
 {
-  "version": "2.0.0-beta.2",
-  "commitHash": "4afe936",
+  "version": "2.0.0-beta.4",
+  "commitHash": "9c42bd0",
   "branch": "refactor/arch-candidate-d",
-  "builtAt": "2026-06-05T15:33:54.463Z"
+  "builtAt": "2026-06-05T16:25:13.633Z"
 }

package/dist/node_modules/@pencil-agent/agent-core/dist/agent-loop-continuations.d.ts

@@ -0,0 +1,17 @@
+/**
+ * [WHO]: Provides output-token recovery and token-budget continuation helpers for agent loops.
+ * [FROM]: Depends on @pencil-agent/ai message types and AgentLoopConfig budget settings.
+ * [TO]: Consumed by standard and structured-adaptive agent loops.
+ * [HERE]: core/lib/agent-core/src/agent-loop-continuations.ts within agent-core; shared loop continuation policy.
+ */
+import type { AssistantMessage, UserMessage } from "@pencil-agent/ai/types";
+import type { AgentLoopConfig } from "./types.js";
+export declare const DEFAULT_OUTPUT_TOKEN_BUDGET_THRESHOLD_PCT = 0.9;
+export declare const DEFAULT_OUTPUT_TOKEN_BUDGET_CONTINUATIONS = 3;
+export declare function computeRecoveryMaxTokens(config: AgentLoopConfig, message: AssistantMessage): number | undefined;
+export declare function createOutputTokenRecoveryMessage(attempt: number): UserMessage;
+export declare function createTokenBudgetContinuation(config: AgentLoopConfig, outputTokens: number, continuationCount: number): {
+    message: UserMessage;
+    outputTokens: number;
+    targetTokens: number;
+} | undefined;

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

@@ -0,0 +1,60 @@
+/**
+ * [WHO]: Provides output-token recovery and token-budget continuation helpers for agent loops.
+ * [FROM]: Depends on @pencil-agent/ai message types and AgentLoopConfig budget settings.
+ * [TO]: Consumed by standard and structured-adaptive agent loops.
+ * [HERE]: core/lib/agent-core/src/agent-loop-continuations.ts within agent-core; shared loop continuation policy.
+ */
+export const DEFAULT_OUTPUT_TOKEN_BUDGET_THRESHOLD_PCT = 0.9;
+export const DEFAULT_OUTPUT_TOKEN_BUDGET_CONTINUATIONS = 3;
+export function computeRecoveryMaxTokens(config, message) {
+    const modelMaxTokens = Math.max(1, Math.floor(config.model.maxTokens || 1));
+    const configured = config.maxTokens !== undefined ? Math.max(1, Math.floor(config.maxTokens)) : undefined;
+    const observedOutput = Math.max(1, Math.floor(message.usage.output || 1));
+    const baseline = configured ?? observedOutput;
+    const expanded = Math.max(baseline + 1, Math.ceil(Math.max(baseline, observedOutput) * 1.5));
+    return Math.min(modelMaxTokens, expanded);
+}
+export function createOutputTokenRecoveryMessage(attempt) {
+    return {
+        role: "user",
+        content: [
+            {
+                type: "text",
+                text: `Continue the previous response from exactly where it stopped. This is automatic output-token recovery attempt ${attempt}.`,
+            },
+        ],
+        timestamp: Date.now(),
+    };
+}
+export function createTokenBudgetContinuation(config, outputTokens, continuationCount) {
+    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 <= continuationCount)
+        return undefined;
+    const normalizedOutputTokens = Math.max(0, Math.floor(outputTokens));
+    const requiredTokens = Math.ceil(targetTokens * thresholdPct);
+    if (normalizedOutputTokens >= requiredTokens)
+        return undefined;
+    const message = {
+        role: "user",
+        content: [
+            {
+                type: "text",
+                text: `Continue because the output token budget is underused ` +
+                    `(${normalizedOutputTokens}/${targetTokens} tokens). Add the missing useful detail directly; ` +
+                    `do not recap or apologize.`,
+            },
+        ],
+        timestamp: Date.now(),
+    };
+    return { message, outputTokens: normalizedOutputTokens, targetTokens };
+}
+function clamp(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(max, Math.max(min, value));
+}

package/dist/node_modules/@pencil-agent/agent-core/dist/agent-loop-stream-events.d.ts

@@ -0,0 +1,19 @@
+/**
+ * [WHO]: Provides waitForAbortableOperation(), waitForAssistantStream(), waitForAssistantStreamEvent()
+ * [FROM]: Depends on @pencil-agent/ai AssistantMessageEvent/AssistantMessageEventStream contracts.
+ * [TO]: Consumed by standard and structured-adaptive agent loops.
+ * [HERE]: core/lib/agent-core/src/agent-loop-stream-events.ts within agent-core; shared abortable operation and assistant-stream iterator utilities.
+ */
+import type { AssistantMessageEvent } from "@pencil-agent/ai/types";
+import type { AssistantMessageEventStream } from "@pencil-agent/ai/events";
+export type AssistantStreamNext = IteratorResult<AssistantMessageEvent> | "aborted";
+export type AssistantStreamStart = AssistantMessageEventStream | "aborted";
+export type AbortableOperationResult<T> = {
+    type: "resolved";
+    value: T;
+} | {
+    type: "aborted";
+};
+export declare function waitForAbortableOperation<T>(valueOrPromise: T | Promise<T>, signal?: AbortSignal): Promise<AbortableOperationResult<T>>;
+export declare function waitForAssistantStream(streamOrPromise: AssistantMessageEventStream | Promise<AssistantMessageEventStream>, signal?: AbortSignal): Promise<AssistantStreamStart>;
+export declare function waitForAssistantStreamEvent(iterator: AsyncIterator<AssistantMessageEvent>, signal?: AbortSignal): Promise<AssistantStreamNext>;

package/dist/node_modules/@pencil-agent/agent-core/dist/agent-loop-stream-events.js

@@ -0,0 +1,55 @@
+/**
+ * [WHO]: Provides waitForAbortableOperation(), waitForAssistantStream(), waitForAssistantStreamEvent()
+ * [FROM]: Depends on @pencil-agent/ai AssistantMessageEvent/AssistantMessageEventStream contracts.
+ * [TO]: Consumed by standard and structured-adaptive agent loops.
+ * [HERE]: core/lib/agent-core/src/agent-loop-stream-events.ts within agent-core; shared abortable operation and assistant-stream iterator utilities.
+ */
+export function waitForAbortableOperation(valueOrPromise, signal) {
+    if (signal?.aborted)
+        return Promise.resolve({ type: "aborted" });
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const onAbort = () => {
+            cleanup();
+            resolve({ type: "aborted" });
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        Promise.resolve(valueOrPromise).then((value) => {
+            cleanup();
+            resolve({ type: "resolved", value });
+        }, (error) => {
+            cleanup();
+            reject(error);
+        });
+    });
+}
+export function waitForAssistantStream(streamOrPromise, signal) {
+    return waitForAbortableOperation(streamOrPromise, signal).then((result) => {
+        if (result.type === "aborted")
+            return "aborted";
+        return result.value;
+    });
+}
+export function waitForAssistantStreamEvent(iterator, signal) {
+    if (signal?.aborted)
+        return Promise.resolve("aborted");
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            signal?.removeEventListener("abort", onAbort);
+        };
+        const onAbort = () => {
+            cleanup();
+            resolve("aborted");
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        iterator.next().then((result) => {
+            cleanup();
+            resolve(result);
+        }, (error) => {
+            cleanup();
+            reject(error);
+        });
+    });
+}

package/dist/node_modules/@pencil-agent/agent-core/dist/agent-loop-tool-results.d.ts

@@ -0,0 +1,10 @@
+/**
+ * [WHO]: Provides enforceToolResultBatchSize(), createInterruptedToolResults(), and createSkippedToolCallLimitResults() for bounded and complete tool-result batches.
+ * [FROM]: Depends on @pencil-agent/ai AssistantMessage/ToolResultMessage/TextContent shapes.
+ * [TO]: Consumed by standard and structured-adaptive agent loops before appending tool results.
+ * [HERE]: core/lib/agent-core/src/agent-loop-tool-results.ts within agent-core; shared tool-result budget policy.
+ */
+import type { AssistantMessage, ToolResultMessage } from "@pencil-agent/ai/types";
+export declare function enforceToolResultBatchSize(toolResults: ToolResultMessage[], maxChars: number | undefined): ToolResultMessage[];
+export declare function createInterruptedToolResults(assistantMessage: AssistantMessage, existingToolResultIds?: ReadonlySet<string>): ToolResultMessage[];
+export declare function createSkippedToolCallLimitResults(assistantMessage: AssistantMessage, reasonText: string): ToolResultMessage[];

package/dist/node_modules/@pencil-agent/agent-core/dist/agent-loop-tool-results.js

@@ -0,0 +1,137 @@
+/**
+ * [WHO]: Provides enforceToolResultBatchSize(), createInterruptedToolResults(), and createSkippedToolCallLimitResults() for bounded and complete tool-result batches.
+ * [FROM]: Depends on @pencil-agent/ai AssistantMessage/ToolResultMessage/TextContent shapes.
+ * [TO]: Consumed by standard and structured-adaptive agent loops before appending tool results.
+ * [HERE]: core/lib/agent-core/src/agent-loop-tool-results.ts within agent-core; shared tool-result budget policy.
+ */
+export 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;
+}
+export function createInterruptedToolResults(assistantMessage, existingToolResultIds = new Set()) {
+    const toolCalls = assistantMessage.content.filter((part) => part.type === "toolCall");
+    if (toolCalls.length === 0) {
+        return [];
+    }
+    const stopReason = assistantMessage.stopReason;
+    const reasonText = stopReason === "aborted"
+        ? "Tool call interrupted because the assistant response was aborted."
+        : "Tool call interrupted because the assistant response ended with an error.";
+    return toolCalls
+        .filter((toolCall) => !existingToolResultIds.has(toolCall.id))
+        .map((toolCall) => ({
+        role: "toolResult",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        content: [{ type: "text", text: reasonText }],
+        details: {
+            errorType: "interrupted_tool_call",
+            stopReason,
+            errorMessage: assistantMessage.errorMessage,
+        },
+        isError: true,
+        timestamp: Date.now(),
+    }));
+}
+export function createSkippedToolCallLimitResults(assistantMessage, reasonText) {
+    const toolCalls = assistantMessage.content.filter((part) => part.type === "toolCall");
+    return toolCalls.map((toolCall) => ({
+        role: "toolResult",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        content: [{ type: "text", text: reasonText }],
+        details: {
+            errorType: "tool_call_limit_reached",
+            toolName: toolCall.name,
+            toolCallId: toolCall.id,
+        },
+        isError: true,
+        timestamp: Date.now(),
+    }));
+}
+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("");
+}

package/dist/node_modules/@pencil-agent/agent-core/dist/agent-loop-tool-summaries.d.ts

@@ -0,0 +1,22 @@
+/**
+ * [WHO]: Provides PendingToolUseSummary, flushReadyToolUseSummaries(), and startToolUseSummary().
+ * [FROM]: Depends on AgentLoopConfig/AgentMessage contracts and tool result message shapes.
+ * [TO]: Consumed by standard and structured-adaptive agent loops for non-blocking tool summaries.
+ * [HERE]: core/lib/agent-core/src/agent-loop-tool-summaries.ts within agent-core; shared tool summary policy.
+ */
+import type { ToolResultMessage } from "@pencil-agent/ai/types";
+import type { EventStream } from "@pencil-agent/ai/events";
+import type { AgentEvent, AgentLoopConfig, AgentMessage } from "./types.js";
+export type PendingToolUseSummary = {
+    read(): {
+        settled: boolean;
+        value?: AgentMessage;
+    };
+};
+export declare function flushReadyToolUseSummaries(pendingSummaries: PendingToolUseSummary[], currentMessages: AgentMessage[], newMessages: AgentMessage[], stream: EventStream<AgentEvent, AgentMessage[]>): PendingToolUseSummary[];
+export declare function startToolUseSummary(config: AgentLoopConfig, event: {
+    assistantMessage: AgentMessage;
+    toolResults: ToolResultMessage[];
+    contextMessages: AgentMessage[];
+    messages: AgentMessage[];
+}): PendingToolUseSummary | undefined;

package/dist/node_modules/@pencil-agent/agent-core/dist/agent-loop-tool-summaries.js

@@ -0,0 +1,64 @@
+/**
+ * [WHO]: Provides PendingToolUseSummary, flushReadyToolUseSummaries(), and startToolUseSummary().
+ * [FROM]: Depends on AgentLoopConfig/AgentMessage contracts and tool result message shapes.
+ * [TO]: Consumed by standard and structured-adaptive agent loops for non-blocking tool summaries.
+ * [HERE]: core/lib/agent-core/src/agent-loop-tool-summaries.ts within agent-core; shared tool summary policy.
+ */
+export function flushReadyToolUseSummaries(pendingSummaries, currentMessages, newMessages, stream) {
+    if (pendingSummaries.length === 0) {
+        return pendingSummaries;
+    }
+    const pending = [];
+    for (const summary of pendingSummaries) {
+        const result = summary.read();
+        if (!result.settled) {
+            pending.push(summary);
+            continue;
+        }
+        if (!result.value) {
+            continue;
+        }
+        currentMessages.push(result.value);
+        newMessages.push(result.value);
+        stream.push({ type: "message_start", message: result.value });
+        stream.push({ type: "message_end", message: result.value });
+    }
+    return pending;
+}
+export 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 }),
+    };
+}

package/dist/node_modules/@pencil-agent/agent-core/dist/agent-loop.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Agent loop that works with AgentMessage throughout.
+ * Transforms to Message[] only at the LLM call boundary.
+ */
+/**
+ * [WHO]: Provides agentLoop(), agentLoopContinue(), standard loop event emission, continuation recovery, recovered-error tombstoning, and serial tool execution.
+ * [FROM]: Depends on @pencil-agent/ai streams/messages, ./types contracts, ./errors, and shared loop helpers.
+ * [TO]: Consumed by agent.ts and package exports as the default agent execution loop.
+ * [HERE]: core/lib/agent-core/src/agent-loop.ts within agent-core; standard counterpart to structured-adaptive-agent-loop.ts.
+ */
+import { EventStream } from "@pencil-agent/ai/events";
+import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types.js";
+/**
+ * Start an agent loop with a new prompt message.
+ * The prompt is added to the context and events are emitted for it.
+ */
+export declare function agentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
+/**
+ * Continue an agent loop from the current context without adding a new message.
+ * Used for retries - context already has user message or tool results.
+ *
+ * **Important:** The last message in context must convert to a `user` or `toolResult` message
+ * via `convertToLlm`. If it doesn't, the LLM provider will reject the request.
+ * This cannot be validated here since `convertToLlm` is only called once per turn.
+ */
+export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;