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

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

@@ -0,0 +1,9 @@
+/**
+ * [WHO]: Provides resolveAgentRunLoopFramework(), buildAgentRunPolicy()
+ * [FROM]: Depends on AgentLoopConfig, AgentRunPolicy, normalizeAgentLoopFramework
+ * [TO]: Consumed by standard and structured-adaptive agent loops
+ * [HERE]: core/lib/agent-core/src/agent-run-result.ts - shared result telemetry helpers
+ */
+import type { AgentLoopConfig, AgentLoopFramework, AgentRunPolicy } from "./types.js";
+export declare function resolveAgentRunLoopFramework(config: AgentLoopConfig): AgentLoopFramework;
+export declare function buildAgentRunPolicy(config: AgentLoopConfig): AgentRunPolicy;

package/dist/node_modules/@pencil-agent/agent-core/dist/agent-run-result.js

@@ -0,0 +1,32 @@
+import { normalizeAgentLoopFramework } from "./types.js";
+export function resolveAgentRunLoopFramework(config) {
+    return normalizeAgentLoopFramework(config.loopFramework) ?? "standard";
+}
+export function buildAgentRunPolicy(config) {
+    const policy = {};
+    if (config.maxModelErrorRecoveryAttempts !== undefined) {
+        policy.maxModelErrorRecoveryAttempts = config.maxModelErrorRecoveryAttempts;
+    }
+    if (config.maxOutputTokenRecoveryAttempts !== undefined) {
+        policy.maxOutputTokenRecoveryAttempts = config.maxOutputTokenRecoveryAttempts;
+    }
+    if (config.outputTokenBudget !== undefined) {
+        policy.outputTokenBudget = { ...config.outputTokenBudget };
+    }
+    if (config.maxStopHookContinuations !== undefined) {
+        policy.maxStopHookContinuations = config.maxStopHookContinuations;
+    }
+    if (config.maxToolConcurrency !== undefined) {
+        policy.maxToolConcurrency = config.maxToolConcurrency;
+    }
+    if (config.maxToolResultBatchSizeChars !== undefined) {
+        policy.maxToolResultBatchSizeChars = config.maxToolResultBatchSizeChars;
+    }
+    if (config.maxTurnsPerPrompt !== undefined) {
+        policy.maxTurnsPerPrompt = config.maxTurnsPerPrompt;
+    }
+    if (config.maxToolCallsPerPrompt !== undefined) {
+        policy.maxToolCallsPerPrompt = config.maxToolCallsPerPrompt;
+    }
+    return policy;
+}

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

@@ -0,0 +1,215 @@
+/**
+ * Agent class that uses the agent-loop directly.
+ * No transport abstraction - calls streamSimple via the loop.
+ */
+/**
+ * [WHO]: AgentOptions, Agent, and loop policy option plumbing
+ * [FROM]: Depends on ./agent-loop.js and ./structured-adaptive-agent-loop.js
+ * [TO]: Consumed by core/lib/agent-core/src/index.ts
+ * [HERE]: core/lib/agent-core/src/agent.ts -
+ */
+import { type ImageContent, type Message, type Model, type ThinkingBudgets, type Transport } from "@pencil-agent/ai/types";
+import type { AgentEvent, AgentLoopFramework, AgentLoopFrameworkInput, AgentLoopConfig, AgentMessage, AgentState, AgentTool, StreamFn, ThinkingLevel } from "./types.js";
+export interface AgentOptions {
+    initialState?: Partial<AgentState>;
+    /**
+     * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
+     * Default filters to user/assistant/toolResult and converts attachments.
+     */
+    convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    /**
+     * Optional transform applied to context before convertToLlm.
+     * Use for context pruning, injecting external context, etc.
+     */
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    /**
+     * Steering mode: "all" = send all steering messages at once, "one-at-a-time" = one per turn
+     */
+    steeringMode?: "all" | "one-at-a-time";
+    /**
+     * Follow-up mode: "all" = send all follow-up messages at once, "one-at-a-time" = one per turn
+     */
+    followUpMode?: "all" | "one-at-a-time";
+    /**
+     * Custom stream function (for proxy backends, etc.). Default uses streamSimple.
+     */
+    streamFn?: StreamFn;
+    /**
+     * Optional session identifier forwarded to LLM providers.
+     * Used by providers that support session-based caching (e.g., OpenAI Codex).
+     */
+    sessionId?: string;
+    /**
+     * Resolves an API key dynamically for each LLM call.
+     * Useful for expiring tokens (e.g., GitHub Copilot OAuth).
+     */
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    /**
+     * Custom token budgets for thinking levels (token-based providers only).
+     */
+    thinkingBudgets?: ThinkingBudgets;
+    /**
+     * Preferred transport for providers that support multiple transports.
+     */
+    transport?: Transport;
+    /**
+     * Maximum delay in milliseconds to wait for a retry when the server requests a long wait.
+     * If the server's requested delay exceeds this value, the request fails immediately,
+     * allowing higher-level retry logic to handle it with user visibility.
+     * Default: 60000 (60 seconds). Set to 0 to disable the cap.
+     */
+    maxRetryDelayMs?: number;
+    /**
+     * Force a loop framework for all models in this Agent.
+     * When omitted, the current model's `agentLoopFramework` setting is used.
+     */
+    agentLoopFramework?: AgentLoopFrameworkInput;
+    /**
+     * Optional tool permission gate used by loop execution.
+     */
+    canUseTool?: AgentLoopConfig["canUseTool"];
+    /**
+     * Optional aggregate tool-result batch budget used by loop execution.
+     */
+    maxToolResultBatchSizeChars?: AgentLoopConfig["maxToolResultBatchSizeChars"];
+    /**
+     * Optional in-loop model error recovery hook used by loop execution.
+     */
+    recoverModelError?: AgentLoopConfig["recoverModelError"];
+    /** Maximum in-loop model error recoveries per prompt. */
+    maxModelErrorRecoveryAttempts?: number;
+    /** Maximum automatic output-token recovery turns per prompt. */
+    maxOutputTokenRecoveryAttempts?: number;
+    /** Optional target for automatic continuation when output is under-complete. */
+    outputTokenBudget?: AgentLoopConfig["outputTokenBudget"];
+    /** Optional stop hook for validation/correction continuation turns. */
+    runStopHooks?: AgentLoopConfig["runStopHooks"];
+    /** Maximum stop-hook continuation turns per prompt. */
+    maxStopHookContinuations?: number;
+    /** Optional non-blocking summary hook for completed tool batches. */
+    createToolUseSummary?: AgentLoopConfig["createToolUseSummary"];
+    /** Maximum concurrency for concurrency-safe tool batches. */
+    maxToolConcurrency?: number;
+    /** Maximum assistant turns allowed for one prompt/continue loop. */
+    maxTurnsPerPrompt?: number;
+    /** Maximum tool calls allowed for one prompt/continue loop. */
+    maxToolCallsPerPrompt?: number;
+}
+export type AgentLoopPolicyOptions = Pick<AgentOptions, "canUseTool" | "maxToolResultBatchSizeChars" | "recoverModelError" | "maxModelErrorRecoveryAttempts" | "maxOutputTokenRecoveryAttempts" | "outputTokenBudget" | "runStopHooks" | "maxStopHookContinuations" | "createToolUseSummary" | "maxToolConcurrency" | "maxTurnsPerPrompt" | "maxToolCallsPerPrompt">;
+export declare class Agent {
+    private _state;
+    private listeners;
+    private abortController?;
+    private convertToLlm;
+    private transformContext?;
+    private steeringQueue;
+    private followUpQueue;
+    private steeringMode;
+    private followUpMode;
+    streamFn: StreamFn;
+    private _sessionId?;
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    private runningPrompt?;
+    private resolveRunningPrompt?;
+    private _thinkingBudgets?;
+    private _transport;
+    private _maxRetryDelayMs?;
+    private _agentLoopFramework?;
+    private canUseTool?;
+    private maxToolResultBatchSizeChars?;
+    private recoverModelError?;
+    private maxModelErrorRecoveryAttempts?;
+    private maxOutputTokenRecoveryAttempts?;
+    private outputTokenBudget?;
+    private runStopHooks?;
+    private maxStopHookContinuations?;
+    private createToolUseSummary?;
+    private maxToolConcurrency?;
+    private maxTurnsPerPrompt?;
+    private maxToolCallsPerPrompt?;
+    constructor(opts?: AgentOptions);
+    /**
+     * Get the current session ID used for provider caching.
+     */
+    get sessionId(): string | undefined;
+    /**
+     * Set the session ID for provider caching.
+     * Call this when switching sessions (new session, branch, resume).
+     */
+    set sessionId(value: string | undefined);
+    /**
+     * Get the current thinking budgets.
+     */
+    get thinkingBudgets(): ThinkingBudgets | undefined;
+    /**
+     * Set custom thinking budgets for token-based providers.
+     */
+    set thinkingBudgets(value: ThinkingBudgets | undefined);
+    /**
+     * Get the current preferred transport.
+     */
+    get transport(): Transport;
+    /**
+     * Set the preferred transport.
+     */
+    setTransport(value: Transport): void;
+    /**
+     * Get the current max retry delay in milliseconds.
+     */
+    get maxRetryDelayMs(): number | undefined;
+    /**
+     * Set the maximum delay to wait for server-requested retries.
+     * Set to 0 to disable the cap.
+     */
+    set maxRetryDelayMs(value: number | undefined);
+    get agentLoopFramework(): AgentLoopFramework;
+    setAgentLoopFramework(value: AgentLoopFrameworkInput | undefined): void;
+    get state(): AgentState;
+    subscribe(fn: (e: AgentEvent) => void): () => void;
+    setSystemPrompt(v: string): void;
+    setModel(m: Model<any>): void;
+    setThinkingLevel(l: ThinkingLevel): void;
+    setSteeringMode(mode: "all" | "one-at-a-time"): void;
+    getSteeringMode(): "all" | "one-at-a-time";
+    setFollowUpMode(mode: "all" | "one-at-a-time"): void;
+    getFollowUpMode(): "all" | "one-at-a-time";
+    setTools(t: AgentTool<any>[]): void;
+    setLoopPolicy(options: Partial<AgentLoopPolicyOptions>): void;
+    setModelErrorRecovery(recoverModelError: AgentLoopConfig["recoverModelError"] | undefined): void;
+    replaceMessages(ms: AgentMessage[]): void;
+    appendMessage(m: AgentMessage): void;
+    /**
+     * Queue a steering message to interrupt the agent mid-run.
+     * Delivered after current tool execution, skips remaining tools.
+     */
+    steer(m: AgentMessage): void;
+    /**
+     * Queue a follow-up message to be processed after the agent finishes.
+     * Delivered only when agent has no more tool calls or steering messages.
+     */
+    followUp(m: AgentMessage): void;
+    clearSteeringQueue(): void;
+    clearFollowUpQueue(): void;
+    clearAllQueues(): void;
+    hasQueuedMessages(): boolean;
+    private dequeueSteeringMessages;
+    private dequeueFollowUpMessages;
+    clearMessages(): void;
+    abort(): void;
+    waitForIdle(): Promise<void>;
+    reset(): void;
+    /** Send a prompt with an AgentMessage */
+    prompt(message: AgentMessage | AgentMessage[]): Promise<void>;
+    prompt(input: string, images?: ImageContent[]): Promise<void>;
+    /**
+     * Continue from current context (used for retries and resuming queued messages).
+     */
+    continue(): Promise<void>;
+    /**
+     * Run the agent loop.
+     * If messages are provided, starts a new conversation turn with those messages.
+     * Otherwise, continues from existing context.
+     */
+    private _runLoop;
+    private emit;
+}