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

package/dist/node_modules/@pencil-agent/agent-core/dist/errors.js

@@ -0,0 +1,146 @@
+/**
+ * [WHO]: AgentError hierarchy — AgentError, NetworkError, ContextOverflowError, ToolExecutionError, ValidationError, ExtensionError
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by agent-loop, agent, proxy, and downstream consumers
+ * [HERE]: core/lib/agent-core/src/errors.ts - unified error type system
+ */
+// =============================================================================
+// Base Error
+// =============================================================================
+/**
+ * Base error class for all agent-related errors.
+ * Provides structured error info (code, retriable flag) for consistent handling.
+ */
+export class AgentError extends Error {
+    code;
+    retriable;
+    details;
+    constructor(message, code, retriable = false, details) {
+        super(message);
+        this.name = "AgentError";
+        this.code = code;
+        this.retriable = retriable;
+        this.details = details;
+    }
+}
+// =============================================================================
+// Network Errors (retriable)
+// =============================================================================
+export class NetworkError extends AgentError {
+    statusCode;
+    constructor(message, statusCode, details) {
+        super(message, "NETWORK_ERROR", true, details);
+        this.name = "NetworkError";
+        this.statusCode = statusCode;
+    }
+}
+export class RateLimitError extends NetworkError {
+    retryAfterMs;
+    constructor(message, retryAfterMs) {
+        super(message, 429);
+        this.name = "RateLimitError";
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+export class TimeoutError extends NetworkError {
+    constructor(message, details) {
+        super(message, undefined, details);
+        this.name = "TimeoutError";
+    }
+}
+export class ConnectionError extends NetworkError {
+    constructor(message, details) {
+        super(message, undefined, details);
+        this.name = "ConnectionError";
+    }
+}
+// =============================================================================
+// Context Errors
+// =============================================================================
+export class ContextOverflowError extends AgentError {
+    estimatedTokens;
+    contextWindow;
+    constructor(message, estimatedTokens, contextWindow) {
+        super(message, "CONTEXT_OVERFLOW", false, { estimatedTokens, contextWindow });
+        this.name = "ContextOverflowError";
+        this.estimatedTokens = estimatedTokens;
+        this.contextWindow = contextWindow;
+    }
+}
+// =============================================================================
+// Tool Errors
+// =============================================================================
+export class ToolExecutionError extends AgentError {
+    toolName;
+    toolCallId;
+    constructor(message, toolName, toolCallId) {
+        super(message, "TOOL_EXECUTION_ERROR", false, { toolName, toolCallId });
+        this.name = "ToolExecutionError";
+        this.toolName = toolName;
+        this.toolCallId = toolCallId;
+    }
+}
+export class ToolTimeoutError extends ToolExecutionError {
+    constructor(toolName, toolCallId, timeoutMs) {
+        super(`Tool "${toolName}" timed out after ${timeoutMs}ms`, toolName, toolCallId);
+        this.name = "ToolTimeoutError";
+    }
+}
+export class ToolNotFoundError extends ToolExecutionError {
+    constructor(toolName) {
+        super(`Tool "${toolName}" not found`, toolName);
+        this.name = "ToolNotFoundError";
+    }
+}
+// =============================================================================
+// Validation Errors (non-retriable)
+// =============================================================================
+export class ValidationError extends AgentError {
+    constructor(message, details) {
+        super(message, "VALIDATION_ERROR", false, details);
+        this.name = "ValidationError";
+    }
+}
+// =============================================================================
+// Extension Errors (isolated — should not crash the agent)
+// =============================================================================
+export class ExtensionError extends AgentError {
+    extensionName;
+    constructor(message, extensionName) {
+        super(message, "EXTENSION_ERROR", false, { extensionName });
+        this.name = "ExtensionError";
+        this.extensionName = extensionName;
+    }
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/** Type guard: is the error retriable? */
+export function isRetriableError(error) {
+    return error instanceof AgentError && error.retriable;
+}
+/** Type guard: is this a context overflow error? */
+export function isContextOverflowError(error) {
+    return error instanceof ContextOverflowError;
+}
+/**
+ * Classify an HTTP-like error (status code + message) into the appropriate AgentError subclass.
+ * Useful for normalizing raw provider errors into the typed hierarchy.
+ */
+export function classifyApiError(statusCode, message) {
+    if (statusCode === 429) {
+        const match = message.match(/retry[_-]after[:\s]+(\d+)/i);
+        const retryAfterMs = match ? parseInt(match[1], 10) * 1000 : undefined;
+        return new RateLimitError(message, retryAfterMs);
+    }
+    if (statusCode === 413 || (statusCode === 400 && /context|token|prompt.*too long|overflow/i.test(message))) {
+        return new ContextOverflowError(message);
+    }
+    if (statusCode !== undefined && statusCode >= 500) {
+        return new NetworkError(message, statusCode);
+    }
+    if (statusCode !== undefined && statusCode >= 400) {
+        return new ValidationError(message, { statusCode });
+    }
+    return new NetworkError(message, statusCode);
+}

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

@@ -0,0 +1,14 @@
+/**
+ * [WHO]: agent-core barrel exports
+ * [FROM]: Depends on agent.js, agent-loop.js, structured-adaptive-agent-loop.js, structured-adaptive-tool-orchestration.js, structured-adaptive-streaming-tool-executor.js, proxy.js, types.js
+ * [TO]: Consumed by @pencil-agent/agent-core package consumers
+ * [HERE]: core/lib/agent-core/src/index.ts - agent-core entry point
+ */
+export * from "./agent.js";
+export * from "./agent-loop.js";
+export * from "./structured-adaptive-agent-loop.js";
+export * from "./structured-adaptive-tool-orchestration.js";
+export * from "./structured-adaptive-streaming-tool-executor.js";
+export * from "./proxy.js";
+export * from "./types.js";
+export * from "./errors.js";

package/dist/node_modules/@pencil-agent/agent-core/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * [WHO]: agent-core barrel exports
+ * [FROM]: Depends on agent.js, agent-loop.js, structured-adaptive-agent-loop.js, structured-adaptive-tool-orchestration.js, structured-adaptive-streaming-tool-executor.js, proxy.js, types.js
+ * [TO]: Consumed by @pencil-agent/agent-core package consumers
+ * [HERE]: core/lib/agent-core/src/index.ts - agent-core entry point
+ */
+// Core Agent
+export * from "./agent.js";
+// Loop functions
+export * from "./agent-loop.js";
+export * from "./structured-adaptive-agent-loop.js";
+export * from "./structured-adaptive-tool-orchestration.js";
+export * from "./structured-adaptive-streaming-tool-executor.js";
+// Proxy utilities
+export * from "./proxy.js";
+// Types
+export * from "./types.js";
+// Errors
+export * from "./errors.js";

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

@@ -0,0 +1,91 @@
+/**
+ * Proxy stream function for apps that route LLM calls through a server.
+ * The server manages auth and proxies requests to LLM providers.
+ */
+/**
+ * [WHO]: ProxyStreamOptions, streamProxy
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by core/lib/agent-core/src/index.ts
+ * [HERE]: core/lib/agent-core/src/proxy.ts -
+ */
+import { type AssistantMessage, type AssistantMessageEvent, type Context, type Model, type SimpleStreamOptions, type StopReason } from "@pencil-agent/ai/types";
+import { EventStream } from "@pencil-agent/ai/events";
+declare class ProxyMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
+    constructor();
+}
+/**
+ * Proxy event types - server sends these with partial field stripped to reduce bandwidth.
+ */
+export type ProxyAssistantMessageEvent = {
+    type: "start";
+} | {
+    type: "text_start";
+    contentIndex: number;
+} | {
+    type: "text_delta";
+    contentIndex: number;
+    delta: string;
+} | {
+    type: "text_end";
+    contentIndex: number;
+    contentSignature?: string;
+} | {
+    type: "thinking_start";
+    contentIndex: number;
+} | {
+    type: "thinking_delta";
+    contentIndex: number;
+    delta: string;
+} | {
+    type: "thinking_end";
+    contentIndex: number;
+    contentSignature?: string;
+} | {
+    type: "toolcall_start";
+    contentIndex: number;
+    id: string;
+    toolName: string;
+} | {
+    type: "toolcall_delta";
+    contentIndex: number;
+    delta: string;
+} | {
+    type: "toolcall_end";
+    contentIndex: number;
+} | {
+    type: "done";
+    reason: Extract<StopReason, "stop" | "length" | "toolUse">;
+    usage: AssistantMessage["usage"];
+} | {
+    type: "error";
+    reason: Extract<StopReason, "aborted" | "error">;
+    errorMessage?: string;
+    usage: AssistantMessage["usage"];
+};
+export interface ProxyStreamOptions extends SimpleStreamOptions {
+    /** Auth token for the proxy server */
+    authToken: string;
+    /** Proxy server URL (e.g., "https://genai.example.com") */
+    proxyUrl: string;
+}
+/**
+ * Stream function that proxies through a server instead of calling LLM providers directly.
+ * The server strips the partial field from delta events to reduce bandwidth.
+ * We reconstruct the partial message client-side.
+ *
+ * Use this as the `streamFn` option when creating an Agent that needs to go through a proxy.
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   streamFn: (model, context, options) =>
+ *     streamProxy(model, context, {
+ *       ...options,
+ *       authToken: await getAuthToken(),
+ *       proxyUrl: "https://genai.example.com",
+ *     }),
+ * });
+ * ```
+ */
+export declare function streamProxy(model: Model<any>, context: Context, options: ProxyStreamOptions): ProxyMessageEventStream;
+export {};

package/dist/node_modules/@pencil-agent/agent-core/dist/proxy.js

@@ -0,0 +1,279 @@
+/**
+ * Proxy stream function for apps that route LLM calls through a server.
+ * The server manages auth and proxies requests to LLM providers.
+ */
+/**
+ * [WHO]: ProxyStreamOptions, streamProxy
+ * [FROM]: No external dependencies
+ * [TO]: Consumed by core/lib/agent-core/src/index.ts
+ * [HERE]: core/lib/agent-core/src/proxy.ts -
+ */
+import { EventStream } from "@pencil-agent/ai/events";
+import { parseStreamingJson } from "@pencil-agent/ai/json";
+// Create stream class matching ProxyMessageEventStream
+class ProxyMessageEventStream extends EventStream {
+    constructor() {
+        super((event) => event.type === "done" || event.type === "error", (event) => {
+            if (event.type === "done")
+                return event.message;
+            if (event.type === "error")
+                return event.error;
+            throw new Error("Unexpected event type");
+        });
+    }
+}
+function isStreamingToolCall(content) {
+    return (content?.type === "toolCall" &&
+        typeof content.partialJson === "string");
+}
+/**
+ * Stream function that proxies through a server instead of calling LLM providers directly.
+ * The server strips the partial field from delta events to reduce bandwidth.
+ * We reconstruct the partial message client-side.
+ *
+ * Use this as the `streamFn` option when creating an Agent that needs to go through a proxy.
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   streamFn: (model, context, options) =>
+ *     streamProxy(model, context, {
+ *       ...options,
+ *       authToken: await getAuthToken(),
+ *       proxyUrl: "https://genai.example.com",
+ *     }),
+ * });
+ * ```
+ */
+export function streamProxy(model, context, options) {
+    const stream = new ProxyMessageEventStream();
+    (async () => {
+        // Initialize the partial message that we'll build up from events
+        const partial = {
+            role: "assistant",
+            stopReason: "stop",
+            content: [],
+            api: model.api,
+            provider: model.provider,
+            model: model.id,
+            usage: {
+                input: 0,
+                output: 0,
+                cacheRead: 0,
+                cacheWrite: 0,
+                totalTokens: 0,
+                cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+            },
+            timestamp: Date.now(),
+        };
+        let reader;
+        const abortHandler = () => {
+            if (reader) {
+                reader.cancel("Request aborted by user").catch(() => { });
+            }
+        };
+        if (options.signal) {
+            options.signal.addEventListener("abort", abortHandler, { once: true });
+        }
+        try {
+            const response = await fetch(`${options.proxyUrl}/api/stream`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${options.authToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    model,
+                    context,
+                    options: {
+                        temperature: options.temperature,
+                        maxTokens: options.maxTokens,
+                        reasoning: options.reasoning,
+                    },
+                }),
+                signal: options.signal,
+            });
+            if (!response.ok) {
+                let errorMessage = `Proxy error: ${response.status} ${response.statusText}`;
+                try {
+                    const errorData = (await response.json());
+                    if (errorData.error) {
+                        errorMessage = `Proxy error: ${errorData.error}`;
+                    }
+                }
+                catch {
+                    // Couldn't parse error response
+                }
+                throw new Error(errorMessage);
+            }
+            reader = response.body.getReader();
+            const decoder = new TextDecoder();
+            let buffer = "";
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (options.signal?.aborted) {
+                    throw new Error("Request aborted by user");
+                }
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop() || "";
+                for (const line of lines) {
+                    if (line.startsWith("data: ")) {
+                        const data = line.slice(6).trim();
+                        if (data) {
+                            const proxyEvent = JSON.parse(data);
+                            const event = processProxyEvent(proxyEvent, partial);
+                            if (event) {
+                                stream.push(event);
+                            }
+                        }
+                    }
+                }
+            }
+            if (options.signal?.aborted) {
+                throw new Error("Request aborted by user");
+            }
+            stream.end();
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const reason = options.signal?.aborted ? "aborted" : "error";
+            partial.stopReason = reason;
+            partial.errorMessage = errorMessage;
+            stream.push({
+                type: "error",
+                reason,
+                error: partial,
+            });
+            stream.end();
+        }
+        finally {
+            if (options.signal) {
+                options.signal.removeEventListener("abort", abortHandler);
+            }
+        }
+    })();
+    return stream;
+}
+/**
+ * Process a proxy event and update the partial message.
+ */
+function processProxyEvent(proxyEvent, partial) {
+    switch (proxyEvent.type) {
+        case "start":
+            return { type: "start", partial };
+        case "text_start":
+            partial.content[proxyEvent.contentIndex] = { type: "text", text: "" };
+            return { type: "text_start", contentIndex: proxyEvent.contentIndex, partial };
+        case "text_delta": {
+            const content = partial.content[proxyEvent.contentIndex];
+            if (content?.type === "text") {
+                content.text += proxyEvent.delta;
+                return {
+                    type: "text_delta",
+                    contentIndex: proxyEvent.contentIndex,
+                    delta: proxyEvent.delta,
+                    partial,
+                };
+            }
+            throw new Error("Received text_delta for non-text content");
+        }
+        case "text_end": {
+            const content = partial.content[proxyEvent.contentIndex];
+            if (content?.type === "text") {
+                content.textSignature = proxyEvent.contentSignature;
+                return {
+                    type: "text_end",
+                    contentIndex: proxyEvent.contentIndex,
+                    content: content.text,
+                    partial,
+                };
+            }
+            throw new Error("Received text_end for non-text content");
+        }
+        case "thinking_start":
+            partial.content[proxyEvent.contentIndex] = { type: "thinking", thinking: "" };
+            return { type: "thinking_start", contentIndex: proxyEvent.contentIndex, partial };
+        case "thinking_delta": {
+            const content = partial.content[proxyEvent.contentIndex];
+            if (content?.type === "thinking") {
+                content.thinking += proxyEvent.delta;
+                return {
+                    type: "thinking_delta",
+                    contentIndex: proxyEvent.contentIndex,
+                    delta: proxyEvent.delta,
+                    partial,
+                };
+            }
+            throw new Error("Received thinking_delta for non-thinking content");
+        }
+        case "thinking_end": {
+            const content = partial.content[proxyEvent.contentIndex];
+            if (content?.type === "thinking") {
+                content.thinkingSignature = proxyEvent.contentSignature;
+                return {
+                    type: "thinking_end",
+                    contentIndex: proxyEvent.contentIndex,
+                    content: content.thinking,
+                    partial,
+                };
+            }
+            throw new Error("Received thinking_end for non-thinking content");
+        }
+        case "toolcall_start": {
+            const toolCall = {
+                type: "toolCall",
+                id: proxyEvent.id,
+                name: proxyEvent.toolName,
+                arguments: {},
+                partialJson: "",
+            };
+            partial.content[proxyEvent.contentIndex] = toolCall;
+            return { type: "toolcall_start", contentIndex: proxyEvent.contentIndex, partial };
+        }
+        case "toolcall_delta": {
+            const content = partial.content[proxyEvent.contentIndex];
+            if (isStreamingToolCall(content)) {
+                content.partialJson += proxyEvent.delta;
+                content.arguments = parseStreamingJson(content.partialJson) || {};
+                partial.content[proxyEvent.contentIndex] = { ...content }; // Trigger reactivity
+                return {
+                    type: "toolcall_delta",
+                    contentIndex: proxyEvent.contentIndex,
+                    delta: proxyEvent.delta,
+                    partial,
+                };
+            }
+            throw new Error("Received toolcall_delta for non-toolCall content");
+        }
+        case "toolcall_end": {
+            const content = partial.content[proxyEvent.contentIndex];
+            if (isStreamingToolCall(content)) {
+                const { partialJson: _partialJson, ...toolCall } = content;
+                partial.content[proxyEvent.contentIndex] = toolCall;
+                return {
+                    type: "toolcall_end",
+                    contentIndex: proxyEvent.contentIndex,
+                    toolCall,
+                    partial,
+                };
+            }
+            return undefined;
+        }
+        case "done":
+            partial.stopReason = proxyEvent.reason;
+            partial.usage = proxyEvent.usage;
+            return { type: "done", reason: proxyEvent.reason, message: partial };
+        case "error":
+            partial.stopReason = proxyEvent.reason;
+            partial.errorMessage = proxyEvent.errorMessage;
+            partial.usage = proxyEvent.usage;
+            return { type: "error", reason: proxyEvent.reason, error: partial };
+        default: {
+            // Exhaustive check - unhandled event types are silently skipped
+            return undefined;
+        }
+    }
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Structured-adaptive agent loop for nanoPencil.
+ * Keeps the public AgentMessage/EventStream contract while using a query-loop
+ * state machine with ordered tool-result pairing and safe tool batching.
+ */
+/**
+ * [WHO]: structuredAdaptiveAgentLoop, structuredAdaptiveAgentLoopContinue
+ * [FROM]: Depends on @pencil-agent/ai, ./types, ./errors, structured-adaptive tool executors, and shared loop helpers.
+ * [TO]: Consumed by core/lib/agent-core/src/agent.ts and index.ts
+ * [HERE]: core/lib/agent-core/src/structured-adaptive-agent-loop.ts - selectable structured-adaptive query loop framework with recovered-error tombstoning
+ */
+import { EventStream } from "@pencil-agent/ai/events";
+import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types.js";
+export declare function structuredAdaptiveAgentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
+export declare function structuredAdaptiveAgentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;