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

package/dist/node_modules/@pencil-agent/agent-core/dist/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]: core/lib/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/dist/structured-adaptive-tool-orchestration.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Structured-adaptive tool orchestration for the selectable structured loop.
+ * Batches concurrency-safe tools, keeps stateful tools serial, and returns
+ * ordered tool_result messages matching assistant tool_use order.
+ */
+/**
+ * [WHO]: runStructuredAdaptiveTools, partitionStructuredAdaptiveToolCalls, StructuredAdaptiveToolCall
+ * [FROM]: Depends on @pencil-agent/ai, ./types, ./errors
+ * [TO]: Consumed by ./structured-adaptive-agent-loop.ts and agent-core tests
+ * [HERE]: core/lib/agent-core/src/structured-adaptive-tool-orchestration.ts - tool batching/execution layer for structured-adaptive loop
+ */
+import { type AssistantMessage, type ToolResultMessage } from "@pencil-agent/ai/types";
+import { EventStream } from "@pencil-agent/ai/events";
+import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentTool, AgentToolPermissionDenial } from "./types.js";
+export type StructuredAdaptiveToolCall = Extract<AssistantMessage["content"][number], {
+    type: "toolCall";
+}>;
+export interface StructuredAdaptiveToolRunResult {
+    toolResults: ToolResultMessage[];
+    contextMessages: AgentMessage[];
+    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 {};

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

@@ -0,0 +1,319 @@
+/**
+ * Structured-adaptive tool orchestration for the selectable structured loop.
+ * Batches concurrency-safe tools, keeps stateful tools serial, and returns
+ * ordered tool_result messages matching assistant tool_use order.
+ */
+/**
+ * [WHO]: runStructuredAdaptiveTools, partitionStructuredAdaptiveToolCalls, StructuredAdaptiveToolCall
+ * [FROM]: Depends on @pencil-agent/ai, ./types, ./errors
+ * [TO]: Consumed by ./structured-adaptive-agent-loop.ts and agent-core tests
+ * [HERE]: core/lib/agent-core/src/structured-adaptive-tool-orchestration.ts - tool batching/execution layer for structured-adaptive loop
+ */
+import { validateToolArguments } from "@pencil-agent/ai/schema";
+import { ToolNotFoundError } from "./errors.js";
+const DEFAULT_SAFE_TOOL_NAMES = new Set([
+    "read",
+    "find",
+    "grep",
+    "ls",
+    "source",
+    "time",
+    "web_search",
+    "web_fetch",
+    "CronList",
+]);
+const DEFAULT_MAX_TOOL_CONCURRENCY = 10;
+const MAX_TOOL_CONCURRENCY_ENV = "NANOPENCIL_MAX_TOOL_USE_CONCURRENCY";
+export async function runStructuredAdaptiveTools(toolCalls, tools, signal, stream, getSteeringMessages, maxConcurrency, canUseTool) {
+    const results = [];
+    const contextMessages = [];
+    const permissionDenials = [];
+    const toolByName = buildToolMap(tools);
+    const batches = partitionStructuredAdaptiveToolCalls(toolCalls, toolByName);
+    let consumed = 0;
+    for (const batch of batches) {
+        const batchUses = await runToolBatch(batch, (toolCall) => runStructuredAdaptiveToolUse(toolCall, toolByName.get(toolCall.name), signal, stream, canUseTool), maxConcurrency);
+        const batchResults = batchUses.map((use) => use.toolResult);
+        results.push(...batchResults);
+        contextMessages.push(...batchUses.flatMap((use) => use.contextMessages));
+        permissionDenials.push(...extractPermissionDenials(batchResults));
+        consumed += batch.length;
+        if (getSteeringMessages) {
+            const steering = await getSteeringMessages();
+            if (steering.length > 0) {
+                for (const skipped of toolCalls.slice(consumed)) {
+                    results.push(skipStructuredAdaptiveToolCall(skipped, stream));
+                }
+                return { toolResults: results, contextMessages, steeringMessages: steering, permissionDenials };
+            }
+        }
+    }
+    return { toolResults: results, contextMessages, permissionDenials };
+}
+async function runToolBatch(items, run, maxConcurrency) {
+    const limit = resolveMaxToolConcurrency(maxConcurrency);
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function worker() {
+        while (nextIndex < items.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            results[index] = await run(items[index]);
+        }
+    }
+    const workerCount = Math.min(limit, items.length);
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    return results;
+}
+export function resolveMaxToolConcurrency(maxConcurrency) {
+    if (maxConcurrency !== undefined) {
+        return Math.max(1, Math.floor(maxConcurrency || DEFAULT_MAX_TOOL_CONCURRENCY));
+    }
+    const raw = typeof process !== "undefined" ? process.env[MAX_TOOL_CONCURRENCY_ENV] : undefined;
+    const parsed = raw ? Number.parseInt(raw, 10) : Number.NaN;
+    if (Number.isFinite(parsed) && parsed > 0) {
+        return Math.floor(parsed);
+    }
+    return DEFAULT_MAX_TOOL_CONCURRENCY;
+}
+export function buildToolMap(tools) {
+    const toolByName = new Map();
+    for (const tool of tools ?? []) {
+        toolByName.set(tool.name, tool);
+        for (const alias of tool.aliases ?? []) {
+            if (!toolByName.has(alias)) {
+                toolByName.set(alias, tool);
+            }
+        }
+    }
+    return toolByName;
+}
+export function partitionStructuredAdaptiveToolCalls(toolCalls, toolByName) {
+    const batches = [];
+    let safeBatch = [];
+    for (const toolCall of toolCalls) {
+        const tool = toolByName.get(toolCall.name);
+        if (isStructuredAdaptiveToolCallConcurrencySafe(toolCall, tool)) {
+            safeBatch.push(toolCall);
+            continue;
+        }
+        if (safeBatch.length > 0) {
+            batches.push(safeBatch);
+            safeBatch = [];
+        }
+        batches.push([toolCall]);
+    }
+    if (safeBatch.length > 0) {
+        batches.push(safeBatch);
+    }
+    return batches;
+}
+export function isStructuredAdaptiveToolCallConcurrencySafe(toolCall, tool) {
+    if (!tool)
+        return DEFAULT_SAFE_TOOL_NAMES.has(toolCall.name);
+    const safety = tool.isConcurrencySafe;
+    if (typeof safety === "function") {
+        try {
+            return safety(validateToolArguments(tool, toolCall));
+        }
+        catch {
+            return false;
+        }
+    }
+    return safety ?? DEFAULT_SAFE_TOOL_NAMES.has(toolCall.name);
+}
+export function resolveStructuredAdaptiveToolInterruptBehavior(toolCall, tool) {
+    if (!tool)
+        return "block";
+    const behavior = tool?.interruptBehavior;
+    if (typeof behavior === "function") {
+        try {
+            return behavior(validateToolArguments(tool, toolCall));
+        }
+        catch {
+            return "block";
+        }
+    }
+    return behavior ?? "block";
+}
+export async function runStructuredAdaptiveToolUse(toolCall, tool, signal, stream, canUseTool) {
+    const startedAt = Date.now();
+    stream.push({
+        type: "tool_execution_start",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        args: toolCall.arguments,
+    });
+    let result;
+    let isError = false;
+    try {
+        if (!tool)
+            throw new ToolNotFoundError(toolCall.name);
+        const validatedArgs = validateToolArguments(tool, toolCall);
+        const validationMessage = await tool.validateInput?.(validatedArgs);
+        if (typeof validationMessage === "string" && validationMessage.trim()) {
+            throw new Error(validationMessage);
+        }
+        const permission = await canUseTool?.({
+            toolCallId: toolCall.id,
+            toolName: tool.name,
+            requestedToolName: toolCall.name,
+            input: validatedArgs,
+            rawInput: toolCall.arguments,
+            tool,
+        });
+        if (permission?.decision === "deny") {
+            const reason = permission.reason?.trim();
+            result = {
+                content: [
+                    { type: "text", text: reason ? `Permission denied: ${reason}` : `Permission denied for ${tool.name}` },
+                ],
+                details: {
+                    errorType: "permission_denied",
+                    reason,
+                    toolName: tool.name,
+                    toolCallId: toolCall.id,
+                },
+            };
+            isError = true;
+        }
+        else {
+            result = await tool.execute(toolCall.id, validatedArgs, signal, (partialResult) => {
+                stream.push({
+                    type: "tool_execution_update",
+                    toolCallId: toolCall.id,
+                    toolName: toolCall.name,
+                    args: toolCall.arguments,
+                    partialResult,
+                });
+            });
+            result = enforceMaxResultSize(result, tool.maxResultSizeChars);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        result = {
+            content: [{ type: "text", text: message }],
+            details: isPermissionDeniedMessage(message)
+                ? {
+                    errorType: "permission_denied",
+                    reason: message,
+                    toolName: tool?.name ?? toolCall.name,
+                    toolCallId: toolCall.id,
+                }
+                : {},
+        };
+        isError = true;
+    }
+    stream.push({
+        type: "tool_execution_end",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        result,
+        isError,
+        durationMs: Date.now() - startedAt,
+    });
+    const toolResult = {
+        role: "toolResult",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        content: result.content,
+        details: result.details,
+        isError,
+        timestamp: Date.now(),
+    };
+    return {
+        toolResult,
+        contextMessages: result.contextMessages ?? [],
+    };
+}
+function isPermissionDeniedMessage(message) {
+    return /^Permission (denied|request was cancelled)/i.test(message.trim());
+}
+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;
+}
+function enforceMaxResultSize(result, maxResultSizeChars) {
+    if (!maxResultSizeChars || maxResultSizeChars <= 0)
+        return result;
+    let remaining = Math.floor(maxResultSizeChars);
+    let truncated = false;
+    const content = result.content.map((part) => {
+        if (part.type !== "text")
+            return part;
+        if (remaining <= 0) {
+            truncated = true;
+            return { ...part, text: "" };
+        }
+        if (part.text.length <= remaining) {
+            remaining -= part.text.length;
+            return part;
+        }
+        truncated = true;
+        const text = part.text.slice(0, remaining);
+        remaining = 0;
+        return { ...part, text };
+    });
+    if (!truncated)
+        return result;
+    const note = `\n\n[Tool result truncated to ${Math.floor(maxResultSizeChars)} characters.]`;
+    let lastTextIndex = -1;
+    for (let i = content.length - 1; i >= 0; i -= 1) {
+        if (content[i]?.type === "text") {
+            lastTextIndex = i;
+            break;
+        }
+    }
+    if (lastTextIndex >= 0) {
+        const part = content[lastTextIndex];
+        content[lastTextIndex] = { ...part, text: `${part.text}${note}` };
+    }
+    else {
+        content.push({ type: "text", text: note.trimStart() });
+    }
+    return { ...result, content };
+}
+function skipStructuredAdaptiveToolCall(toolCall, stream) {
+    const startedAt = Date.now();
+    const result = {
+        content: [{ type: "text", text: "Skipped due to queued user message." }],
+        details: {},
+    };
+    stream.push({
+        type: "tool_execution_start",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        args: toolCall.arguments,
+    });
+    stream.push({
+        type: "tool_execution_end",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        result,
+        isError: true,
+        durationMs: Date.now() - startedAt,
+    });
+    return {
+        role: "toolResult",
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        content: result.content,
+        details: result.details,
+        isError: true,
+        timestamp: Date.now(),
+    };
+}