jeopi-agent-core 16.2.13

package/dist/types/compaction/pruning.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Tool output pruning utilities for compaction.
+ */
+import type { SessionEntry } from "./entries";
+import { type ProtectedToolMatcher } from "./tool-protection";
+export interface PruneConfig {
+    /** Keep the most recent tool output tokens intact. */
+    protectTokens: number;
+    /** Only prune if total savings meets this threshold. */
+    minimumSavings: number;
+    /** Tool-result protection matchers. String entries protect every result from that tool; predicates may inspect the paired tool call. */
+    protectedTools: ProtectedToolMatcher[];
+    /**
+     * Optional supersede key function (see {@link SupersedePruneConfig.supersedeKey}).
+     * When provided, superseded tool results are pruned first — even inside the
+     * `protectTokens` window — before age-based victims. Absent, behavior is
+     * unchanged.
+     */
+    supersedeKey?: SupersedeKeyFn;
+    /** Useless-flagged results bypass the protect window (see {@link USELESS_NOTICE}). Default true. */
+    pruneUseless?: boolean;
+    /**
+     * Compaction boundary: the `firstKeptEntryId` of the latest compaction on
+     * the branch. Entries at indices BEFORE this id are summarized away and never
+     * sent to the model, so mutating them only churns persisted history without
+     * shrinking the prompt — they are skipped. Undefined = no compaction (the
+     * whole branch is sent).
+     */
+    keepBoundaryId?: string;
+    /**
+     * Prompt-cache guard. When set, a tool result whose all-message suffix
+     * (tokens of every message after it) EXCEEDS this is part of the warm,
+     * already-sent cache prefix: mutating it forces the provider to re-write the
+     * whole suffix (cacheWrite premium). Such results — including superseded and
+     * useless ones, which otherwise bypass {@link protectTokens} — are left for
+     * compaction/shake (which rebuild the cache anyway) to reclaim. Undefined =
+     * no cache guard (legacy: superseded/useless prune at any depth).
+     */
+    cacheWarmSuffixTokens?: number;
+}
+export declare const DEFAULT_PRUNE_CONFIG: PruneConfig;
+export interface PruneResult {
+    prunedCount: number;
+    tokensSaved: number;
+}
+/** Exact placeholder written over a superseded tool result. */
+export declare const SUPERSEDED_NOTICE = "[Superseded by a newer read of this file]";
+/** Exact placeholder written over an elided useless tool result. */
+export declare const USELESS_NOTICE = "[Uneventful result elided]";
+/**
+ * Maps a tool call to a supersede key. Results sharing a key form a group in
+ * which every result except the newest is a supersede candidate. A key `K`
+ * additionally supersedes keys with prefix `K + "\u0000"` (selector-free read
+ * supersedes selector-carrying reads of the same base path). Return
+ * `undefined` to exempt a call from supersede grouping.
+ */
+export type SupersedeKeyFn = (toolName: string, args: Record<string, unknown>) => string | undefined;
+export interface SupersedePruneConfig {
+    /** Supersede key function; results sharing a key supersede older ones. */
+    supersedeKey?: SupersedeKeyFn;
+    /** Also prune results flagged useless by their tool. Default false. */
+    pruneUseless?: boolean;
+    /** Prune a candidate now when all messages after it total at most this many estimated tokens. Default 8 000. */
+    suffixTokenLimit?: number;
+    /**
+     * Prune all candidates when the last message is at least this old: the
+     * provider prompt cache is then cold, so re-writing it is free. MUST exceed
+     * the cache retention (Anthropic "long" = 1h) or a still-warm prefix is busted
+     * by the flush. Default 30 min — callers on long retention override it.
+     */
+    idleFlushMs?: number;
+    /** Clock override for tests. */
+    now?: number;
+    /**
+     * Compaction boundary (`firstKeptEntryId` of the latest compaction). Entries
+     * before it are summarized away and never sent, so they are skipped in every
+     * path — including the idle flush — to avoid pointless history churn.
+     * Undefined = no compaction (the whole branch is sent).
+     */
+    keepBoundaryId?: string;
+    /** Tool-result protection matchers (same contract as {@link PruneConfig.protectedTools}). */
+    protectedTools: ProtectedToolMatcher[];
+}
+/**
+ * Prune superseded tool results (e.g. stale `read` outputs replaced by a newer
+ * read of the same file) and, when `pruneUseless` is set, results their tool
+ * flagged contextually useless. Cheap, incremental, and prompt-cache-aware: a
+ * candidate is pruned now only when the suffix after it is small (tail case —
+ * the read→edit→read loop) or when the context has been idle long enough that
+ * the provider cache is cold anyway (then all still-sent candidates flush).
+ * Never mutates entries before `keepBoundaryId` (summarized away — not sent).
+ */
+export declare function pruneSupersededToolResults(entries: SessionEntry[], config: SupersedePruneConfig): PruneResult;
+export declare function pruneToolOutputs(entries: SessionEntry[], config?: PruneConfig): PruneResult;
+/**
+ * Supersede key for the `read` tool: the file path with the trailing line/raw
+ * selector stripped (the read tool's own splitter grammar via
+ * {@link splitReadSelector}, e.g. `src/foo.ts:50-200`, `:2-4:raw`).
+ * Internal/URL-scheme paths (`skill://…`, `https://…`) are exempt.
+ * Selector-free reads key on the bare path; selector-carrying reads key on
+ * `path + "\u0000" + selector`, so two reads collide only when the newer is
+ * selector-free or the selectors are identical (the pass's prefix rule lets a
+ * bare-path read supersede selector-carrying reads of the same file).
+ */
+export declare function readToolSupersedeKey(toolName: string, args: Record<string, unknown>): string | undefined;

package/dist/types/compaction/shake.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Context-reducing surgical compaction ("shake").
+ *
+ * `shake` drops heavy content out of the live context mechanically: whole
+ * tool-call results and large fenced/XML blocks are replaced with short
+ * placeholders. This module is the pure layer — region detection and in-place
+ * mutation only. Artifact offload, persistence, and provider-session teardown
+ * are orchestrated by the caller (`AgentSession.shake`).
+ *
+ * Layering mirrors `pruning.ts`: no I/O here.
+ */
+import type { CustomMessageEntry, SessionEntry, SessionMessageEntry } from "./entries";
+import { type ProtectedToolMatcher } from "./tool-protection";
+export interface ShakeConfig {
+    /** Keep the most recent context tokens (across all entries) intact. */
+    protectTokens: number;
+    /** Only shake when total estimated savings meets this threshold. */
+    minSavings: number;
+    /** Tool-result protection matchers. String entries protect every result from that tool; predicates may inspect the paired tool call. */
+    protectedTools: ProtectedToolMatcher[];
+    /** Minimum token size for a fenced/XML block to be eligible. */
+    fenceMinTokens: number;
+    /**
+     * Compaction boundary (`firstKeptEntryId` of the latest compaction). Entries
+     * before it are summarized away and never sent, so they are skipped — shaking
+     * them only churns persisted history. Undefined = no compaction (whole branch
+     * is sent). Note: shake still elides the warm cached prefix at/after the
+     * boundary — that is its job as a compaction-class reducer.
+     */
+    keepBoundaryId?: string;
+}
+/** Auto-shake config: protects the live tail, conservative thresholds. */
+export declare const DEFAULT_SHAKE_CONFIG: ShakeConfig;
+/** Manual `/shake`: aggressive — drops every eligible region across history. */
+export declare const AGGRESSIVE_SHAKE_CONFIG: ShakeConfig;
+/** A located eligible region. */
+export interface ToolResultShakeRegion {
+    kind: "toolResult";
+    entry: SessionMessageEntry;
+    tokens: number;
+    originalText: string;
+    /** Human label for the offload doc (tool name). */
+    label: string;
+}
+export interface BlockShakeRegion {
+    kind: "block";
+    entry: SessionMessageEntry | CustomMessageEntry;
+    /** Index into the content array, or -1 for string-form content. */
+    blockIndex: number;
+    /** Character offsets into the target text (start inclusive, end exclusive). */
+    start: number;
+    end: number;
+    tokens: number;
+    originalText: string;
+    /** Human label for the offload doc (role / customType). */
+    label: string;
+}
+export type ShakeRegion = ToolResultShakeRegion | BlockShakeRegion;
+/**
+ * Pure detection: locate every eligible shake region on a branch.
+ *
+ * Walks the protect-recent window (most recent `protectTokens` of context is
+ * kept intact), collects whole tool-result messages (honoring `protectedTools`
+ * and skipping already-pruned results) and large fenced/XML blocks inside
+ * user/developer/assistant/custom messages. Tool results flagged contextually
+ * useless by their tool bypass the protect window — there is nothing recent
+ * worth keeping in them. Returns regions in document order.
+ *
+ * `toolCall` blocks are never touched (tool-call/result pairing is preserved)
+ * and regions never span a message boundary. When the combined estimated
+ * savings is below `minSavings`, returns `[]` (no-op).
+ */
+export declare function collectShakeRegions(entries: SessionEntry[], config: ShakeConfig): ShakeRegion[];
+/**
+ * Pure mutation: replace a single region's content in place.
+ *
+ * Tool-result: replaces the message content with the placeholder text and
+ * stamps `prunedAt`. Block: splices `replacement` over `[start, end)` of the
+ * target text block. When several block regions share one text block they MUST
+ * be applied highest-start-first so earlier offsets stay valid — use
+ * {@link applyShakeRegions}, which orders them correctly.
+ */
+export declare function applyShakeRegion(region: ShakeRegion, replacement: string): void;
+/**
+ * Apply many regions at once. Block regions are applied highest-start-first so
+ * that splicing one region never shifts the offsets of another in the same text
+ * block; tool-result regions are independent.
+ */
+export declare function applyShakeRegions(items: Array<{
+    region: ShakeRegion;
+    replacement: string;
+}>): void;

package/dist/types/compaction/tool-protection.d.ts

@@ -0,0 +1,17 @@
+import type { ToolResultMessage } from "jeopi-ai";
+import type { AgentToolCall } from "../types";
+import type { SessionEntry } from "./entries";
+export interface ProtectedToolContext {
+    readonly toolResult: ToolResultMessage;
+    readonly toolCall: AgentToolCall | undefined;
+}
+export type ProtectedToolMatcher = string | ((context: ProtectedToolContext) => boolean);
+export declare function collectToolCallsById(entries: readonly SessionEntry[]): Map<string, AgentToolCall>;
+/**
+ * Extract the `path` argument from a paired `read` tool call, when the result
+ * is a `read` result carrying a string path. Returns `undefined` otherwise.
+ * Shared primitive for read-targeted protection matchers (skills, plans, …).
+ */
+export declare function getReadToolPath({ toolResult, toolCall }: ProtectedToolContext): string | undefined;
+export declare function isSkillReadToolResult(context: ProtectedToolContext): boolean;
+export declare function isProtectedToolResult(toolResult: ToolResultMessage, toolCall: AgentToolCall | undefined, matchers: readonly ProtectedToolMatcher[]): boolean;

package/dist/types/compaction/utils.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared utilities for compaction and branch summarization.
+ */
+import type { Message } from "jeopi-ai";
+import { type Dialect } from "jeopi-ai/dialect";
+import type { AgentMessage } from "../types";
+export interface FileOperations {
+    read: Set<string>;
+    written: Set<string>;
+    edited: Set<string>;
+}
+export declare function createFileOps(): FileOperations;
+/**
+ * Split a read-tool path into its base path and trailing selector, mirroring the
+ * read tool's own splitter. Single source of the grammar in this package: the
+ * file-operations list strips selectors via {@link stripReadSelector}, and the
+ * supersede-prune pass keys on both parts via `readToolSupersedeKey`.
+ */
+export declare function splitReadSelector(path: string): {
+    path: string;
+    sel?: string;
+};
+/**
+ * Strip a trailing read-tool selector (`:50-200`, `:raw`, `:1-50:raw`, `:conflicts`, …)
+ * so the same file read with different line ranges dedupes to one `<files>` entry
+ * and matches its write/edit path when computing Read/Write/RW markers.
+ */
+export declare function stripReadSelector(path: string): string;
+/**
+ * Whether `path` references a `scheme://` URL (internal URI or web URL) rather
+ * than a filesystem path that belongs in the compaction `<files>` summary.
+ */
+export declare function isUrlSchemePath(path: string): boolean;
+/**
+ * Extract file operations from tool calls in an assistant message.
+ */
+export declare function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOperations): void;
+/**
+ * Compute final file lists from file operations.
+ * Returns readFiles (files only read, not modified) and modifiedFiles.
+ */
+export declare function computeFileLists(fileOps: FileOperations): {
+    readFiles: string[];
+    modifiedFiles: string[];
+};
+export declare function formatFileOperations(readFiles: string[], modifiedFiles: string[], readSet?: ReadonlySet<string>): string;
+export declare function upsertFileOperations(summary: string, readFiles: string[], modifiedFiles: string[], readSet?: ReadonlySet<string>): string;
+/**
+ * Truncate tool results to the same representation used in summarization prompts.
+ */
+export declare function truncateToolResultForSummary(text: string): string;
+/**
+ * Serialize LLM messages to text for summarization.
+ * This prevents the model from treating it as a conversation to continue.
+ * Call convertToLlm() first to handle custom message types.
+ */
+export declare function serializeConversation(messages: Message[], dialect?: Dialect): string;
+export declare const SUMMARIZATION_SYSTEM_PROMPT: string;

package/dist/types/compaction.d.ts

@@ -0,0 +1 @@
+export * from "./compaction/index";

package/dist/types/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./agent";
+export * from "./agent-loop";
+export * from "./append-only-context";
+export * from "./compaction";
+export * from "./proxy";
+export * from "./replay-policy";
+export * from "./run-collector";
+export * from "./telemetry";
+export * from "./thinking";
+export * from "./tokenizer";
+export * from "./types";
+export * from "./utils/yield";

package/dist/types/proxy.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Proxy stream function for apps that route LLM calls through a server.
+ * The server manages auth and proxies requests to LLM providers.
+ */
+import { type AssistantMessage, type AssistantMessageEvent, type Context, EventStream, type FetchImpl, type Model, type SimpleStreamOptions, type StopReason } from "jeopi-ai";
+export 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;
+    /** Optional fetch implementation; defaults to global fetch. */
+    fetch?: FetchImpl;
+}
+/**
+ * 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, context: Context, options: ProxyStreamOptions): ProxyMessageEventStream;

package/dist/types/replay-policy.d.ts

@@ -0,0 +1,5 @@
+import type { AssistantMessage, Message } from "jeopi-ai";
+/** Detects API-level provider refusals that are terminal errors, not dialogue to replay. */
+export declare function isProviderRefusalMessage(message: AssistantMessage): boolean;
+/** Removes API-level provider refusals from live provider replay while preserving other messages. */
+export declare function filterProviderReplayMessages(messages: readonly Message[]): Message[];

package/dist/types/run-collector.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Per-invocation run aggregator. Buffers per-chat and per-tool records as the
+ * loop executes and folds them into a single {@link AgentRunSummary} +
+ * {@link AgentRunCoverage} value at the end.
+ *
+ * One collector lives on each {@link AgentTelemetry} handle, which is
+ * constructed once per `agentLoop` invocation in {@link resolveTelemetry}.
+ * Collector lookups use the live `Span` as a `WeakMap` key — bounded memory,
+ * no cross-invoke leakage.
+ *
+ * The collector is fed exclusively by helpers in `./telemetry.ts`. Loop
+ * authors do not interact with it directly except via the public
+ * `recordSkippedTool` helper used for the two skip paths that bypass spans
+ * entirely (pre-run interrupt and the tail-sweep for tool calls that never
+ * produced a result message).
+ */
+import type { Span } from "@opentelemetry/api";
+import type { AssistantMessage, Model, StopReason } from "jeopi-ai";
+/** Terminal status reported by an `execute_tool` span. */
+export type ToolStatus = "ok" | "error" | "skipped" | "blocked" | "timeout" | "aborted";
+/** Raw record for a single `chat` step, finalized by `finishChatSpan`. */
+export interface ChatRecord {
+    readonly stepNumber: number;
+    readonly model: string;
+    readonly provider: string;
+    readonly stopReason: StopReason | undefined;
+    readonly latencyMs: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cachedInputTokens: number;
+    readonly cacheWriteTokens: number;
+    readonly reasoningOutputTokens: number;
+    readonly totalTokens: number;
+    readonly costUsd: number | undefined;
+    readonly costUnavailableReason: string | undefined;
+    readonly errorType: string | undefined;
+}
+/** Raw record for a single `execute_tool` invocation. */
+export interface ToolRecord {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly status: ToolStatus;
+    readonly latencyMs: number;
+    readonly errorType: string | undefined;
+}
+/** Per-tool counters surfaced under {@link AgentRunSummary.tools.byName}. */
+export interface ToolCounters {
+    readonly total: number;
+    readonly ok: number;
+    readonly error: number;
+    readonly skipped: number;
+    readonly blocked: number;
+    readonly timeout: number;
+    readonly aborted: number;
+    readonly totalLatencyMs: number;
+}
+/**
+ * Run-level rollup returned in the `agent_end` event and passed to
+ * {@link AgentTelemetryConfig.onRunEnd}. Pure aggregation — no references to
+ * spans, no callbacks, no live state. Safe to persist / diff / assert.
+ */
+export interface AgentRunSummary {
+    readonly chats: {
+        readonly total: number;
+        /** Bucketed by raw {@link StopReason}; absent reasons omitted. */
+        readonly byStopReason: Readonly<Record<string, number>>;
+        readonly totalLatencyMs: number;
+    };
+    readonly tools: {
+        readonly total: number;
+        readonly ok: number;
+        readonly error: number;
+        readonly skipped: number;
+        readonly blocked: number;
+        readonly timeout: number;
+        readonly aborted: number;
+        readonly totalLatencyMs: number;
+        /** Per-tool-name counters; keys sorted by name on snapshot. */
+        readonly byName: Readonly<Record<string, ToolCounters>>;
+    };
+    readonly usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly cachedInputTokens: number;
+        readonly cacheWriteTokens: number;
+        readonly reasoningOutputTokens: number;
+        readonly totalTokens: number;
+    };
+    readonly cost: {
+        readonly estimatedUsd: number;
+        /** Sorted, deduped. */
+        readonly unavailableReasons: readonly string[];
+    };
+    readonly errors: {
+        readonly total: number;
+        readonly byType: Readonly<Record<string, number>>;
+    };
+    readonly stepCount: number;
+}
+/**
+ * Coverage rollup: registered-vs-invoked across the run. All arrays are
+ * sorted ascending and deduped so the value is stable for diffing.
+ */
+export interface AgentRunCoverage {
+    readonly toolsAvailable: readonly string[];
+    readonly toolsInvoked: readonly string[];
+    readonly toolsUnused: readonly string[];
+    readonly modelsUsed: readonly string[];
+    readonly providersUsed: readonly string[];
+}
+export declare class AgentRunCollector {
+    #private;
+    /** True once `markRunEnded()` has been called for this invocation. */
+    get runEnded(): boolean;
+    /**
+     * Mark this run as logically ended. Callers use this to coordinate the
+     * `onRunEnd` hook between the success path (fires inside
+     * `buildAgentEndEvent`, before `stream.end()`) and the error path (fires
+     * inside `finishInvokeAgentSpan`'s finally). Idempotent — returns `true`
+     * the first time, `false` on subsequent calls.
+     */
+    markRunEnded(): boolean;
+    /** Record the tool names exposed on a single chat step. */
+    noteAvailableTools(tools: readonly {
+        readonly name: string;
+    }[] | undefined): void;
+    beginChat(span: Span, init: {
+        readonly stepNumber: number;
+        readonly model: Model;
+        readonly provider?: string;
+    }): void;
+    endChat(span: Span, message: AssistantMessage, fields: {
+        readonly costUsd: number | undefined;
+        readonly costUnavailableReason: string | undefined;
+    }): void;
+    /**
+     * Stamp the chat span as failed without a finalized AssistantMessage. Used
+     * by the `catch` arm of `streamAssistantResponse` so error chats still
+     * appear in the run summary.
+     */
+    failChat(span: Span, fields: {
+        readonly errorType: string;
+    }): void;
+    beginTool(span: Span, init: {
+        readonly toolCallId: string;
+        readonly toolName: string;
+    }): void;
+    endTool(span: Span, fields: {
+        readonly status: ToolStatus;
+        readonly errorType: string | undefined;
+    }): void;
+    /**
+     * Record a tool that never produced a span — pre-run interrupt or tail
+     * sweep. The LLM still asked for it, so it counts toward
+     * {@link AgentRunCoverage.toolsInvoked}.
+     */
+    recordOrphanTool(record: {
+        readonly toolCallId: string;
+        readonly toolName: string;
+        readonly status: ToolStatus;
+    }): void;
+    /** Build the immutable summary value from buffered records. */
+    snapshot(opts: {
+        readonly stepCount: number;
+    }): {
+        readonly summary: AgentRunSummary;
+        readonly coverage: AgentRunCoverage;
+    };
+}
+/**
+ * Fold multiple per-run summaries into one. Pure aggregation — useful when a
+ * caller (verify pass, benchmark harness) drives the agent loop N times and
+ * needs a single rollup across all invocations.
+ *
+ * Counters sum element-wise. Sets (cost reasons, error types, per-tool
+ * counters) merge by key. Numeric totals sum. The output is in the same
+ * shape as a single `AgentRunSummary`, so all dashboards and persistence
+ * layers handle it uniformly.
+ */
+export declare function aggregateAgentRunSummaries(summaries: readonly AgentRunSummary[]): AgentRunSummary;
+/** Union-merge multiple coverage values, preserving the sorted+deduped invariant. */
+export declare function aggregateAgentRunCoverage(coverages: readonly AgentRunCoverage[]): AgentRunCoverage;
+/** Empty `AgentRunSummary` constant. Exported for tests and default-initializers. */
+export declare function emptyAgentRunSummary(): AgentRunSummary;
+/** Empty `AgentRunCoverage` constant. Exported for tests and default-initializers. */
+export declare function emptyAgentRunCoverage(): AgentRunCoverage;
+/**
+ * Distinguishable error class thrown when `beforeToolCall` returns
+ * `{ block: true }`. Lets the catch arm of `runTool` set the terminal status
+ * on the execute_tool span to `"blocked"` instead of conflating with a real
+ * tool exception.
+ */
+export declare class ToolCallBlockedError extends Error {
+    readonly name = "ToolCallBlockedError";
+    constructor(reason?: string);
+}