@open-multi-agent/core 1.4.0

package/dist/agent/runner.d.ts

@@ -0,0 +1,242 @@
+/**
+ * @fileoverview Core conversation loop engine for open-multi-agent.
+ *
+ * {@link AgentRunner} is the heart of the framework. It handles:
+ *  - Sending messages to the LLM adapter
+ *  - Extracting tool-use blocks from the response
+ *  - Executing tool calls in parallel via {@link ToolExecutor}
+ *  - Appending tool results and looping back until `end_turn`
+ *  - Accumulating token usage and timing data across all turns
+ *
+ * The loop follows a standard agentic conversation pattern:
+ * one outer `while (true)` that breaks on `end_turn` or maxTurns exhaustion.
+ */
+import type { LLMMessage, ToolCallRecord, TokenUsage, StreamEvent, ToolResult, TeamInfo, LLMAdapter, TraceEvent, LoopDetectionConfig, ContextStrategy, ThinkingConfig } from '../types.js';
+import type { ToolRegistry } from '../tool/framework.js';
+import type { ToolExecutor } from '../tool/executor.js';
+/** Predefined tool sets for common agent use cases. */
+export declare const TOOL_PRESETS: {
+    readonly readonly: readonly ["file_read", "grep", "glob"];
+    readonly readwrite: readonly ["file_read", "file_write", "file_edit", "grep", "glob"];
+    readonly full: readonly ["file_read", "file_write", "file_edit", "grep", "glob", "bash"];
+};
+/** Framework-level disallowed tools for safety rails. */
+export declare const AGENT_FRAMEWORK_DISALLOWED: readonly string[];
+/**
+ * Static configuration for an {@link AgentRunner} instance.
+ * These values are constant across every `run` / `stream` call.
+ */
+export interface RunnerOptions {
+    /** LLM model identifier, e.g. `'claude-opus-4-6'`. */
+    readonly model: string;
+    /** Optional system prompt prepended to every conversation. */
+    readonly systemPrompt?: string;
+    /**
+     * Maximum number of tool-call round-trips before the runner stops.
+     * Prevents unbounded loops. Defaults to `10`.
+     */
+    readonly maxTurns?: number;
+    /** Maximum output tokens per LLM response. */
+    readonly maxTokens?: number;
+    /** Sampling temperature passed to the adapter. */
+    readonly temperature?: number;
+    /** Nucleus sampling top_p. Forwarded to all adapters. */
+    readonly topP?: number;
+    /**
+     * Top-k sampling. Forwarded to Anthropic and OpenAI-compatible local
+     * servers. Cloud OpenAI rejects this parameter.
+     */
+    readonly topK?: number;
+    /**
+     * Min-p sampling. Only supported by OpenAI-compatible local servers.
+     * Cloud OpenAI rejects this parameter; the Anthropic adapter ignores it.
+     */
+    readonly minP?: number;
+    /**
+     * Whether the model may emit multiple tool calls in a single assistant
+     * turn. Forwarded to OpenAI cloud and OpenAI-compatible local servers as
+     * `parallel_tool_calls`. The Anthropic adapter ignores this field.
+     */
+    readonly parallelToolCalls?: boolean;
+    /**
+     * Frequency penalty. Forwarded to OpenAI cloud and OpenAI-compatible local
+     * servers. The Anthropic adapter ignores this field.
+     */
+    readonly frequencyPenalty?: number;
+    /**
+     * Presence penalty. Forwarded to OpenAI cloud and OpenAI-compatible local
+     * servers. The Anthropic adapter ignores this field.
+     */
+    readonly presencePenalty?: number;
+    /**
+     * Adapter-specific escape hatch merged into the outgoing request payload.
+     * See {@link AgentConfig.extraBody} for the override precedence contract.
+     */
+    readonly extraBody?: Record<string, unknown>;
+    /** See {@link AgentConfig.thinking}. */
+    readonly thinking?: ThinkingConfig;
+    /** AbortSignal that cancels any in-flight adapter call and stops the loop. */
+    readonly abortSignal?: AbortSignal;
+    /**
+     * Tool access control configuration.
+     * - `toolPreset`: Predefined tool sets for common use cases
+     * - `allowedTools`: Whitelist of tool names (allowlist)
+     * - `disallowedTools`: Blacklist of tool names (denylist)
+     * Tools are resolved in order: preset → allowlist → denylist
+     */
+    readonly toolPreset?: 'readonly' | 'readwrite' | 'full';
+    readonly allowedTools?: readonly string[];
+    readonly disallowedTools?: readonly string[];
+    /** Display name of the agent driving this runner (used in tool context). */
+    readonly agentName?: string;
+    /** Short role description of the agent (used in tool context). */
+    readonly agentRole?: string;
+    /** Loop detection configuration. When set, detects stuck agent loops. */
+    readonly loopDetection?: LoopDetectionConfig;
+    /** Maximum cumulative tokens (input + output) allowed for this run. */
+    readonly maxTokenBudget?: number;
+    /** Optional context compression strategy for long multi-turn runs. */
+    readonly contextStrategy?: ContextStrategy;
+    /**
+     * Compress tool results that the agent has already processed.
+     * See {@link AgentConfig.compressToolResults} for details.
+     */
+    readonly compressToolResults?: boolean | {
+        readonly minChars?: number;
+    };
+}
+/**
+ * Per-call callbacks for observing tool execution in real time.
+ * All callbacks are optional; unused ones are simply skipped.
+ */
+export interface RunOptions {
+    /** Fired just before each tool is dispatched. */
+    readonly onToolCall?: (name: string, input: Record<string, unknown>) => void;
+    /** Fired after each tool result is received. */
+    readonly onToolResult?: (name: string, result: ToolResult) => void;
+    /** Fired after each complete {@link LLMMessage} is appended. */
+    readonly onMessage?: (message: LLMMessage) => void;
+    /**
+     * Fired when the runner detects a potential configuration issue.
+     * For example, when a model appears to ignore tool definitions.
+     */
+    readonly onWarning?: (message: string) => void;
+    /** Trace callback for observability spans. Async callbacks are safe. */
+    readonly onTrace?: (event: TraceEvent) => void | Promise<void>;
+    /** Run ID for trace correlation. */
+    readonly runId?: string;
+    /** Task ID for trace correlation. */
+    readonly taskId?: string;
+    /** Agent name for trace correlation (overrides RunnerOptions.agentName). */
+    readonly traceAgent?: string;
+    /**
+     * Per-call abort signal. When set, takes precedence over the static
+     * {@link RunnerOptions.abortSignal}. Useful for per-run timeouts.
+     */
+    readonly abortSignal?: AbortSignal;
+    /**
+     * Team context for built-in tools such as `delegate_to_agent`.
+     * Injected by the orchestrator during `runTeam` / `runTasks` pool runs.
+     */
+    readonly team?: TeamInfo;
+}
+/** The aggregated result returned when a full run completes. */
+export interface RunResult {
+    /** All messages accumulated during this run (assistant + tool results). */
+    readonly messages: LLMMessage[];
+    /** The final text output from the last assistant turn. */
+    readonly output: string;
+    /** All tool calls made during this run, in execution order. */
+    readonly toolCalls: ToolCallRecord[];
+    /** Aggregated token counts across every LLM call in this run. */
+    readonly tokenUsage: TokenUsage;
+    /** Total number of LLM turns (including tool-call follow-ups). */
+    readonly turns: number;
+    /** True when the run was terminated or warned due to loop detection. */
+    readonly loopDetected?: boolean;
+    /** True when the run was terminated due to token budget limits. */
+    readonly budgetExceeded?: boolean;
+}
+/**
+ * Drives a full agentic conversation: LLM calls, tool execution, and looping.
+ *
+ * @example
+ * ```ts
+ * const runner = new AgentRunner(adapter, registry, executor, {
+ *   model: 'claude-opus-4-6',
+ *   maxTurns: 10,
+ * })
+ * const result = await runner.run(messages)
+ * console.log(result.output)
+ * ```
+ */
+export declare class AgentRunner {
+    private readonly adapter;
+    private readonly toolRegistry;
+    private readonly toolExecutor;
+    private readonly options;
+    private readonly maxTurns;
+    private summarizeCache;
+    constructor(adapter: LLMAdapter, toolRegistry: ToolRegistry, toolExecutor: ToolExecutor, options: RunnerOptions);
+    private serializeMessage;
+    private truncateToSlidingWindow;
+    private summarizeMessages;
+    private applyContextStrategy;
+    /**
+     * Resolve the final set of tools available to this agent based on the
+     * three-layer configuration: preset → allowlist → denylist → framework safety.
+     *
+     * Returns LLMToolDef[] for direct use with LLM adapters.
+     */
+    private resolveTools;
+    /**
+     * Run a complete conversation starting from `messages`.
+     *
+     * The call may internally make multiple LLM requests (one per tool-call
+     * round-trip). It returns only when:
+     *  - The LLM emits `end_turn` with no tool-use blocks, or
+     *  - `maxTurns` is exceeded, or
+     *  - The abort signal is triggered.
+     */
+    run(messages: LLMMessage[], options?: RunOptions): Promise<RunResult>;
+    /**
+     * Run the conversation and yield {@link StreamEvent}s incrementally.
+     *
+     * Callers receive:
+     *  - `{ type: 'text', data: string }` for each text delta
+     *  - `{ type: 'tool_use', data: ToolUseBlock }` when the model requests a tool
+     *  - `{ type: 'tool_result', data: ToolResultBlock }` after each execution
+   *  - `{ type: 'budget_exceeded', data: TokenBudgetExceededError }` on budget trip
+     *  - `{ type: 'done', data: RunResult }` at the very end
+     *  - `{ type: 'error', data: Error }` on unrecoverable failure
+     */
+    stream(initialMessages: LLMMessage[], options?: RunOptions): AsyncGenerator<StreamEvent>;
+    /**
+     * Rule-based selective context compaction (no LLM calls).
+     *
+     * Compresses old turns while preserving the conversation skeleton:
+     * - tool_use blocks (decisions) are always kept
+     * - Long tool_result content is replaced with a compact marker
+     * - Long assistant text blocks are truncated with an excerpt
+     * - Error tool_results are never compressed
+     * - Recent turns (within `preserveRecentTurns`) are kept intact
+     */
+    private compactMessages;
+    /**
+     * Replace consumed tool results with compact markers.
+     *
+     * A tool_result is "consumed" when the assistant has produced a response
+     * after seeing it (i.e. there is an assistant message following the user
+     * message that contains the tool_result).  The most recent user message
+     * with tool results is always kept intact — the LLM is about to see it.
+     *
+     * Error results and results shorter than `minChars` are never compressed.
+     */
+    private compressConsumedToolResults;
+    /**
+     * Build the {@link ToolUseContext} passed to every tool execution.
+     * Identifies this runner as the invoking agent.
+     */
+    private buildToolContext;
+}
+//# sourceMappingURL=runner.d.ts.map

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

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