longer-agent 0.1.0

package/configExample.yaml

@@ -0,0 +1,83 @@
+# LongerAgent Configuration
+#
+# This file is auto-generated by `longeragent init`, but you can also
+# create or edit it manually. Place it at: ~/.longeragent/config.yaml
+#
+# API keys can use ${ENV_VAR} syntax to read from environment variables,
+# or be specified as literal strings (not recommended for security).
+
+# Which model to use by default. Must match a name in the `models` section.
+default_model: my-claude
+
+models:
+  # ── Anthropic ──────────────────────────────────────────────────────
+  my-claude:
+    provider: anthropic
+    model: claude-sonnet-4-6          # or: claude-opus-4-6, claude-haiku-4-5
+    api_key: ${ANTHROPIC_API_KEY}
+    # temperature: 0.7                # default: 0.7
+    # max_tokens: 32000               # default: 32000
+    # thinking_budget: 10000          # thinking token budget (if model supports thinking)
+
+  # ── OpenAI ─────────────────────────────────────────────────────────
+  # my-openai:
+  #   provider: openai                # uses Responses API (web search, reasoning)
+  #   model: gpt-5.2                  # or: gpt-5.2-codex, gpt-5.3-codex, gpt-5.4
+  #   api_key: ${OPENAI_API_KEY}
+
+  # my-openai-chat:
+  #   provider: openai-chat           # uses Chat Completions API
+  #   model: gpt-5.2                  # or: gpt-5.2-codex, gpt-5.3-codex, gpt-5.4
+  #   api_key: ${OPENAI_API_KEY}
+
+  # ── Kimi (Moonshot) ────────────────────────────────────────────────
+  # my-kimi:
+  #   provider: kimi-cn               # or: kimi / kimi-ai (international)
+  #   model: kimi-k2.5
+  #   api_key: ${KIMI_CN_API_KEY}     # international: ${KIMI_API_KEY}
+
+  # ── MiniMax ────────────────────────────────────────────────────────
+  # my-minimax:
+  #   provider: minimax
+  #   model: MiniMax-M2.5             # or: MiniMax-M2.1, MiniMax-M1-80k
+  #   api_key: ${MINIMAX_API_KEY}
+
+  # ── GLM (Zhipu) ───────────────────────────────────────────────────
+  # my-glm:
+  #   provider: glm
+  #   model: glm-5                    # or: glm-4.7
+  #   api_key: ${GLM_API_KEY}
+
+  # ── OpenRouter ─────────────────────────────────────────────────────
+  # my-openrouter:
+  #   provider: openrouter
+  #   model: anthropic/claude-sonnet-4.6  # or: anthropic/claude-haiku-4.5, openai/gpt-5.2-codex, openai/gpt-5.3-codex, minimax/minimax-m2.1
+  #   api_key: ${OPENROUTER_API_KEY}
+  #   http_referer: https://myapp.example.com  # optional
+  #   x_title: MyApp                            # optional
+
+# ── Sub-agent model override (optional) ──────────────────────────────
+# When set, all sub-agents use this model instead of the primary agent's.
+# Must reference a model name defined above.
+# sub_agent_model: my-openai
+
+# ── MCP Servers (optional) ───────────────────────────────────────────
+# LongerAgent acts as an MCP client: connects to these servers and
+# makes their tools available to agents.
+#
+# mcp_servers:
+#   filesystem:
+#     transport: stdio
+#     command: npx
+#     args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
+#
+#   brave-search:
+#     transport: stdio
+#     command: python
+#     args: ["-m", "mcp_server_brave_search"]
+#     env:
+#       BRAVE_API_KEY: ${BRAVE_API_KEY}
+#
+#   remote-tools:
+#     transport: sse
+#     url: http://localhost:8080/mcp

package/dist/agents/agent.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Agent — the core execution unit.
+ *
+ * An Agent wraps a model + system prompt + tools into a callable unit.
+ * Supports both stateless single-shot and stateful multi-turn execution.
+ */
+import type { Config, ModelConfig } from "../config.js";
+import type { MessageBlock } from "../primitives/context.js";
+import type { ToolDef } from "../providers/base.js";
+import type { LogEntry } from "../log-entry.js";
+import { type BeforeToolExecuteCallback, type OnToolCallCallback, type ToolExecutor, type ToolLoopResult } from "./tool-loop.js";
+export declare const NO_REPLY_MARKER = "<NO_REPLY>";
+/** Check if model output text is the `<NO_REPLY>` marker. */
+export declare function isNoReply(text: string): boolean;
+export interface AgentResult {
+    text: string;
+    toolHistory: Array<Record<string, unknown>>;
+    totalUsage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    noReply: boolean;
+}
+/**
+ * A callable intelligent unit: model + system prompt + tools.
+ *
+ * Supports two construction styles:
+ *
+ * **Explicit:**
+ *   new Agent({ name: "Coder", modelConfig, systemPrompt: "...", tools })
+ *
+ * **Simplified:**
+ *   new Agent({ name: "Coder", role: "...", model: "claude-sonnet", config })
+ */
+export declare class Agent {
+    name: string;
+    description: string;
+    systemPrompt: string;
+    tools: ToolDef[];
+    maxToolRounds: number;
+    modelConfig: ModelConfig;
+    private _provider;
+    constructor(opts: {
+        name: string;
+        modelConfig?: ModelConfig;
+        systemPrompt?: string;
+        tools?: ToolDef[];
+        maxToolRounds?: number;
+        role?: string;
+        model?: string;
+        config?: Config;
+        description?: string;
+    });
+    /**
+     * Replace this agent's model config and recreate the provider.
+     * Used for runtime model switching (e.g., /model command).
+     * Only safe to call between turns (not while a turn is in progress).
+     */
+    replaceModelConfig(newConfig: ModelConfig): void;
+    /**
+     * Single-shot async execution (stateless).
+     *
+     * Builds a fresh message list with system prompt + user input,
+     * runs the tool loop, and returns the result.
+     */
+    asyncRun(userInput: string | MessageBlock, extraMessages?: Array<Record<string, unknown>>, toolExecutors?: Record<string, ToolExecutor>, onToolCall?: OnToolCallCallback, signal?: AbortSignal): Promise<AgentResult>;
+    /**
+     * Run the tool loop with callback-based message management.
+     *
+     * The caller provides getMessages/appendEntry/allocId callbacks.
+     * Main agent: backed by structured log.
+     * Sub-agents: backed by an ephemeral structured log.
+     */
+    asyncRunWithMessages(getMessages: () => Array<Record<string, unknown>>, appendEntry: (entry: LogEntry) => void, allocId: (type: LogEntry["type"]) => string, turnIndex: number, baseRoundIndex?: number, toolExecutors?: Record<string, ToolExecutor>, onToolCall?: OnToolCallCallback, onTextChunk?: (roundIndex: number, chunk: string) => boolean | void, onReasoningChunk?: (roundIndex: number, chunk: string) => boolean | void, signal?: AbortSignal, contextIdAllocator?: (roundIndex: number) => string, compactCheck?: (inputTokens: number, outputTokens: number, hasToolCalls: boolean) => {
+        compactNeeded: boolean;
+        scenario?: "output" | "toolcall";
+    } | null, onTokenUpdate?: (inputTokens: number, usage?: import("../providers/base.js").Usage) => void, thinkingLevel?: string, cacheEnabled?: boolean, onSaveCheckpoint?: () => void, beforeToolExecute?: BeforeToolExecuteCallback, getNotification?: () => string | null, streamCallbacksOwnEntries?: boolean, onRetryAttempt?: (attempt: number, maxRetries: number, delaySec: number, errMsg: string) => void, onRetrySuccess?: (attempt: number) => void, onRetryExhausted?: (maxRetries: number, errMsg: string) => void): Promise<ToolLoopResult>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/agents/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agents/agent.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAgB,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAIlE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEhD,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,cAAc,EACpB,MAAM,gBAAgB,CAAC;AAMxB,eAAO,MAAM,eAAe,eAAe,CAAC;AAE5C,6DAA6D;AAC7D,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE/C;AAMD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC5C,UAAU,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,KAAK;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,WAAW,CAAC;IAEzB,OAAO,CAAC,SAAS,CAAe;gBAEpB,IAAI,EAAE;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB;IA2BD;;;;OAIG;IACH,kBAAkB,CAAC,SAAS,EAAE,WAAW,GAAG,IAAI;IAShD;;;;;OAKG;IACG,QAAQ,CACZ,SAAS,EAAE,MAAM,GAAG,YAAY,EAChC,aAAa,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC9C,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAC5C,UAAU,CAAC,EAAE,kBAAkB,EAC/B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,CAAC;IAwCvB;;;;;;OAMG;IACG,oBAAoB,CACxB,WAAW,EAAE,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACjD,WAAW,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,EACtC,OAAO,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,MAAM,EAC3C,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,EACvB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAC5C,UAAU,CAAC,EAAE,kBAAkB,EAC/B,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,EACnE,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,EACxE,MAAM,CAAC,EAAE,WAAW,EACpB,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,EACnD,YAAY,CAAC,EAAE,CACb,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,OAAO,KAClB;QAAE,aAAa,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAA;KAAE,GAAG,IAAI,EACxE,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,sBAAsB,EAAE,KAAK,KAAK,IAAI,EAC3F,aAAa,CAAC,EAAE,MAAM,EACtB,YAAY,CAAC,EAAE,OAAO,EACtB,gBAAgB,CAAC,EAAE,MAAM,IAAI,EAC7B,iBAAiB,CAAC,EAAE,yBAAyB,EAC7C,eAAe,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,EACrC,yBAAyB,CAAC,EAAE,OAAO,EACnC,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,EAChG,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC1C,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GAC9D,OAAO,CAAC,cAAc,CAAC;CA+B3B"}

package/dist/agents/agent.js

@@ -0,0 +1,156 @@
+/**
+ * Agent — the core execution unit.
+ *
+ * An Agent wraps a model + system prompt + tools into a callable unit.
+ * Supports both stateless single-shot and stateful multi-turn execution.
+ */
+import { createProvider } from "../providers/registry.js";
+import { executeTool } from "../tools/basic.js";
+import { createEphemeralLogState } from "../ephemeral-log.js";
+import { asyncRunToolLoop, } from "./tool-loop.js";
+// ------------------------------------------------------------------
+// Output prefix detection
+// ------------------------------------------------------------------
+export const NO_REPLY_MARKER = "<NO_REPLY>";
+/** Check if model output text is the `<NO_REPLY>` marker. */
+export function isNoReply(text) {
+    return text.trim() === NO_REPLY_MARKER;
+}
+// ------------------------------------------------------------------
+// Agent class
+// ------------------------------------------------------------------
+/**
+ * A callable intelligent unit: model + system prompt + tools.
+ *
+ * Supports two construction styles:
+ *
+ * **Explicit:**
+ *   new Agent({ name: "Coder", modelConfig, systemPrompt: "...", tools })
+ *
+ * **Simplified:**
+ *   new Agent({ name: "Coder", role: "...", model: "claude-sonnet", config })
+ */
+export class Agent {
+    name;
+    description;
+    systemPrompt;
+    tools;
+    maxToolRounds;
+    modelConfig;
+    _provider;
+    constructor(opts) {
+        this.name = opts.name;
+        this.description = opts.description ?? "";
+        this.systemPrompt = opts.role && !opts.systemPrompt
+            ? opts.role
+            : opts.systemPrompt ?? "";
+        this.tools = opts.tools ?? [];
+        this.maxToolRounds = opts.maxToolRounds ?? 25;
+        // Resolve modelConfig
+        if (opts.modelConfig) {
+            this.modelConfig = opts.modelConfig;
+        }
+        else if (opts.model && opts.config) {
+            this.modelConfig = opts.config.getModel(opts.model);
+        }
+        else if (opts.model) {
+            throw new Error("Agent: 'config' is required when using the 'model' shorthand.");
+        }
+        else {
+            throw new Error("Agent: either 'modelConfig' or 'model'+'config' must be provided.");
+        }
+        this._provider = createProvider(this.modelConfig);
+    }
+    /**
+     * Replace this agent's model config and recreate the provider.
+     * Used for runtime model switching (e.g., /model command).
+     * Only safe to call between turns (not while a turn is in progress).
+     */
+    replaceModelConfig(newConfig) {
+        this.modelConfig = newConfig;
+        this._provider = createProvider(newConfig);
+    }
+    // ------------------------------------------------------------------
+    // Async methods
+    // ------------------------------------------------------------------
+    /**
+     * Single-shot async execution (stateless).
+     *
+     * Builds a fresh message list with system prompt + user input,
+     * runs the tool loop, and returns the result.
+     */
+    async asyncRun(userInput, extraMessages, toolExecutors, onToolCall, signal) {
+        const rendered = typeof userInput === "string"
+            ? userInput
+            : userInput.render();
+        const initialMessages = [
+            { role: "system", content: this.systemPrompt },
+        ];
+        if (extraMessages) {
+            initialMessages.push(...extraMessages);
+        }
+        initialMessages.push({ role: "user", content: rendered });
+        const runtime = createEphemeralLogState(initialMessages, {
+            requiresAlternatingRoles: this._provider.requiresAlternatingRoles,
+        });
+        const result = await asyncRunToolLoop({
+            provider: this._provider,
+            getMessages: runtime.getMessages,
+            appendEntry: runtime.appendEntry,
+            allocId: runtime.allocId,
+            turnIndex: 0,
+            tools: this.tools.length > 0 ? this.tools : undefined,
+            toolExecutors: toolExecutors ?? {},
+            maxRounds: this.maxToolRounds,
+            agentName: this.name,
+            onToolCall,
+            builtinExecutor: executeTool,
+            signal,
+        });
+        return {
+            text: result.text,
+            toolHistory: result.toolHistory,
+            totalUsage: result.totalUsage,
+            noReply: isNoReply(result.text),
+        };
+    }
+    /**
+     * Run the tool loop with callback-based message management.
+     *
+     * The caller provides getMessages/appendEntry/allocId callbacks.
+     * Main agent: backed by structured log.
+     * Sub-agents: backed by an ephemeral structured log.
+     */
+    async asyncRunWithMessages(getMessages, appendEntry, allocId, turnIndex, baseRoundIndex, toolExecutors, onToolCall, onTextChunk, onReasoningChunk, signal, contextIdAllocator, compactCheck, onTokenUpdate, thinkingLevel, cacheEnabled, onSaveCheckpoint, beforeToolExecute, getNotification, streamCallbacksOwnEntries, onRetryAttempt, onRetrySuccess, onRetryExhausted) {
+        return asyncRunToolLoop({
+            provider: this._provider,
+            getMessages,
+            appendEntry,
+            allocId,
+            turnIndex,
+            baseRoundIndex,
+            tools: this.tools.length > 0 ? this.tools : undefined,
+            toolExecutors: toolExecutors ?? {},
+            maxRounds: this.maxToolRounds,
+            agentName: this.name,
+            onToolCall,
+            onTextChunk,
+            onReasoningChunk,
+            builtinExecutor: executeTool,
+            signal,
+            contextIdAllocator,
+            onTokenUpdate,
+            compactCheck,
+            thinkingLevel,
+            cacheEnabled,
+            onSaveCheckpoint,
+            beforeToolExecute,
+            getNotification,
+            streamCallbacksOwnEntries,
+            onRetryAttempt,
+            onRetrySuccess,
+            onRetryExhausted,
+        });
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/agents/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/agents/agent.ts"],"names":[],"mappings":"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"}

package/dist/agents/tool-loop.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Shared tool loop logic for Agent.
+ *
+ * Provides the async LLM <-> tool round-trip cycle. Calls the provider,
+ * executes tool calls, appends results via callbacks, and repeats until
+ * the model responds without tool calls or max rounds are reached.
+ *
+ * v2: operates through callbacks (getMessages / appendEntry) instead of
+ * directly mutating provider messages. The backing store can be the
+ * structured session log (main agent) or an ephemeral structured log
+ * (sub-agents / stateless runs).
+ */
+import type { BaseProvider, ToolDef, ToolResult } from "../providers/base.js";
+import type { LogEntry } from "../log-entry.js";
+import type { AskRequest } from "../ask.js";
+/**
+ * A tool executor receives the arguments dict and returns either
+ * a plain string or a ToolResult. May be sync or async.
+ */
+export type ToolExecutor = (args: Record<string, unknown>) => ToolResult | string | Promise<ToolResult | string>;
+/** Generate a one-line summary from a ToolDef.summaryTemplate. */
+export declare function generateToolSummary(agentName: string, toolName: string, toolArgs: Record<string, unknown>, summaryTemplate: string): string;
+export declare function generateToolCallDisplay(toolName: string, toolArgs: Record<string, unknown>): string;
+export interface ToolLoopResult {
+    text: string;
+    toolHistory: Array<Record<string, unknown>>;
+    totalUsage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    intermediateText: string[];
+    lastInputTokens: number;
+    reasoningContent: string;
+    reasoningState: unknown;
+    /** Flat context_id of the last tool-call round (undefined if no tool calls). */
+    lastRoundId?: string;
+    /** Whether the tool loop detected that compact is needed. */
+    compactNeeded?: boolean;
+    /** Which scenario triggered compact: "output" (no tool calls) or "toolcall" (after tool execution). */
+    compactScenario?: "output" | "toolcall";
+    /** Total tokens (input + output) from the last provider call. */
+    lastTotalTokens?: number;
+    /** Whether the final assistant text was already materialized by stream callbacks. */
+    textHandledInLog?: boolean;
+    /** Whether the final reasoning content was already materialized by stream callbacks. */
+    reasoningHandledInLog?: boolean;
+    /** Suspended on an ask tool call that requires user input. */
+    suspendedAsk?: {
+        ask: AskRequest;
+        toolCallId: string;
+        roundIndex: number;
+    };
+}
+export type OnToolCallCallback = (agentName: string, toolName: string, toolArgs: Record<string, unknown>, summary: string) => void;
+export interface ToolPreflightContext {
+    agentName: string;
+    toolName: string;
+    toolArgs: Record<string, unknown>;
+    toolCallId: string;
+    summary: string;
+}
+export type ToolPreflightDecision = {
+    kind: "allow";
+} | {
+    kind: "deny";
+    message: string;
+};
+export type BeforeToolExecuteCallback = (ctx: ToolPreflightContext) => ToolPreflightDecision | void | Promise<ToolPreflightDecision | void>;
+export interface ToolLoopOptions {
+    provider: BaseProvider;
+    /**
+     * Returns the current API message sequence for the provider.
+     * Called before each provider call.
+     * Main agent: projects from _log; sub-agents: returns local array.
+     */
+    getMessages: () => Array<Record<string, unknown>>;
+    /**
+     * Append a LogEntry to the backing store.
+     * Main agent: appends to _log; sub-agents: converts to raw msg and pushes.
+     */
+    appendEntry: (entry: LogEntry) => void;
+    /** Allocate the next entry ID. */
+    allocId: (type: LogEntry["type"]) => string;
+    /** Current turn index (for entry creation). */
+    turnIndex: number;
+    /** Base round index for this activation within the current turn. */
+    baseRoundIndex?: number;
+    tools?: ToolDef[];
+    toolExecutors: Record<string, ToolExecutor>;
+    maxRounds: number;
+    agentName?: string;
+    onToolCall?: OnToolCallCallback;
+    toolsMap?: Record<string, ToolDef>;
+    onTextChunk?: (roundIndex: number, chunk: string) => boolean | void;
+    onReasoningChunk?: (roundIndex: number, chunk: string) => boolean | void;
+    /** Fallback executor for tools not found in toolExecutors. */
+    builtinExecutor?: (name: string, args: Record<string, unknown>) => Promise<ToolResult | string>;
+    /** Abort signal for cancellation. */
+    signal?: AbortSignal;
+    /** Allocator that returns the round's context_id. Provided by Session for context ID tracking. */
+    contextIdAllocator?: (roundIndex: number) => string;
+    /** Called after each provider response with the latest input token count and full Usage. */
+    onTokenUpdate?: (inputTokens: number, usage?: import("../providers/base.js").Usage) => void;
+    /**
+     * Callback to check whether compact is needed after each provider call.
+     * Returns { compactNeeded, scenario } or null to skip.
+     * When undefined, no compact checking is performed (e.g. sub-agents).
+     */
+    compactCheck?: (inputTokens: number, outputTokens: number, hasToolCalls: boolean) => {
+        compactNeeded: boolean;
+        scenario?: "output" | "toolcall";
+    } | null;
+    /** Unified thinking level override (passed to provider). */
+    thinkingLevel?: string;
+    /** Whether to enable provider-specific prompt caching. */
+    cacheEnabled?: boolean;
+    /** Called after each tool_result is appended, for incremental persistence. */
+    onSaveCheckpoint?: () => void;
+    /** Optional preflight gate before executing a tool call (may ask/pause/deny). */
+    beforeToolExecute?: BeforeToolExecuteCallback;
+    /** Returns a notification string to append to tool_result content, or null if none. */
+    getNotification?: () => string | null;
+    /** When true, streamed text/reasoning callbacks own the corresponding log entries. */
+    streamCallbacksOwnEntries?: boolean;
+    /** Called when a network error is detected and a retry is being attempted. */
+    onRetryAttempt?: (attempt: number, maxRetries: number, delaySec: number, errMsg: string) => void;
+    /** Called when a retried network call succeeds. */
+    onRetrySuccess?: (attempt: number) => void;
+    /** Called when all network retries have been exhausted. */
+    onRetryExhausted?: (maxRetries: number, errMsg: string) => void;
+}
+/**
+ * Async tool loop: call LLM, execute tools, repeat until done.
+ *
+ * Tool executors are called with their arguments dict and may be
+ * sync or async. Exceptions are caught and returned as error
+ * ToolResult content.
+ */
+export declare function asyncRunToolLoop(opts: ToolLoopOptions): Promise<ToolLoopResult>;
+//# sourceMappingURL=tool-loop.d.ts.map

package/dist/agents/tool-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-loop.d.ts","sourceRoot":"","sources":["../../src/agents/tool-loop.ts"],"names":[],"mappings":"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"}