@prometheus-ai/agent-core 0.5.3 → 0.5.8

package/dist/types/agent-loop.d.ts

@@ -53,3 +53,10 @@ export declare function agentLoopContinueDetailed(context: AgentContext, config:
 };
 export declare const INTENT_FIELD = "_i";
 export declare function normalizeTools(tools: AgentContext["tools"], injectIntent: boolean): Context["tools"];
+/** Resolve the human-readable reason an abort carried. A caller that aborts via
+ *  `AbortController.abort(reason)` with a string or a non-`AbortError` `Error`
+ *  (e.g. the coding agent's user-interrupt label) gets that text surfaced on the
+ *  synthesized assistant message's `errorMessage`; a bare `abort()` (whose
+ *  `signal.reason` is the default `AbortError` `DOMException`) falls back to the
+ *  generic sentinel that downstream renderers treat as "no specific reason". */
+export declare function abortReasonText(signal: AbortSignal | undefined): string;

package/dist/types/agent.d.ts

@@ -1,7 +1,7 @@
-import { type AssistantMessage, type AssistantMessageEvent, type CursorExecHandlers, type CursorToolResultHandler, type Effort, type ImageContent, type Message, type Model, type ProviderSessionState, type ServiceTier, type SimpleStreamOptions, type ThinkingBudgets, type ToolChoice } from "@prometheus-ai/ai";
+import { type ApiKeyResolveContext, type AssistantMessage, type AssistantMessageEvent, type Context, type CursorExecHandlers, type CursorToolResultHandler, type Effort, type ImageContent, type Message, type Model, type ProviderSessionState, type ServiceTier, type SimpleStreamOptions, type ThinkingBudgets, type ToolChoice } from "@prometheus-ai/ai";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { HarmonyAuditEvent } from "./harmony-leak";
-import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, StreamFn, ToolCallContext } from "./types";
+import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AsideMessage, StreamFn, ToolCallContext } from "./types";
 export declare class AgentBusyError extends Error {
     constructor(message?: string);
 }
@@ -17,6 +17,11 @@ export interface AgentOptions {
      * Use for context pruning, injecting external context, etc.
      */
     transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    /**
+     * Optional transform applied after provider context assembly and before
+     * telemetry capture/provider send.
+     */
+    transformProviderContext?: (context: Context, model: Model) => Context;
     /**
      * Steering mode: "all" = send all steering messages at once, "one-at-a-time" = one per turn
      */
@@ -31,11 +36,6 @@ export interface AgentOptions {
      * - "wait": defer steering until the current turn completes
      */
     interruptMode?: "immediate" | "wait";
-    /**
-     * Maximum completed tool calls to accept from one streamed assistant turn before
-     * executing the batch. Undefined disables batching.
-     */
-    maxToolCallsPerTurn?: number;
     /**
      * API format for Kimi Code provider: "openai" or "anthropic" (default: "anthropic")
      */
@@ -51,6 +51,11 @@ export interface AgentOptions {
      * Used by providers that support session-based caching (e.g., OpenAI Codex).
      */
     sessionId?: string;
+    /**
+     * Optional prompt cache key forwarded to LLM providers.
+     * When omitted, providers may fall back to sessionId.
+     */
+    promptCacheKey?: string;
     /**
      * Shared provider state map for session-scoped transport/session caches.
      */
@@ -59,7 +64,7 @@ export interface AgentOptions {
      * 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;
+    getApiKey?: (provider: string, ctx?: ApiKeyResolveContext) => Promise<string | undefined> | string | undefined;
     /**
      * Inspect or replace provider payloads before they are sent.
      */
@@ -159,7 +164,7 @@ export interface AgentPromptOptions {
 export declare class Agent {
     #private;
     streamFn: StreamFn;
-    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    getApiKey?: (provider: string, ctx?: ApiKeyResolveContext) => Promise<string | undefined> | string | undefined;
     /**
      * Hook invoked after tool arguments are validated and before execution.
      * Reassign at any time to swap the implementation (e.g. on extension reload).
@@ -180,6 +185,14 @@ export declare class Agent {
      * Call this when switching sessions (new session, branch, resume).
      */
     set sessionId(value: string | undefined);
+    /**
+     * Get the prompt cache key forwarded to providers.
+     */
+    get promptCacheKey(): string | undefined;
+    /**
+     * Set the prompt cache key forwarded to providers.
+     */
+    set promptCacheKey(value: string | undefined);
     /**
      * Static metadata forwarded to every API request when no resolver is installed
      * (e.g. `metadata.user_id` for Anthropic session attribution). Setting this
@@ -268,8 +281,6 @@ export declare class Agent {
      * Set to 0 to disable the cap.
      */
     set maxRetryDelayMs(value: number | undefined);
-    get maxToolCallsPerTurn(): number | undefined;
-    set maxToolCallsPerTurn(value: number | undefined);
     get state(): AgentState;
     get appendOnlyContext(): AppendOnlyContextManager | undefined;
     setAppendOnlyContext(manager?: AppendOnlyContextManager): void;
@@ -278,10 +289,17 @@ export declare class Agent {
     setRawSseEventInterceptor(fn: SimpleStreamOptions["onSseEvent"] | undefined): void;
     setAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
     setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void;
+    /**
+     * Provide a source of non-interrupting "aside" messages (e.g. background-job
+     * completions, late LSP diagnostics) drained at each step boundary. Never
+     * aborts in-flight tools. See `AgentLoopConfig.getAsideMessages`.
+     */
+    setAsideMessageProvider(fn: (() => AsideMessage[] | Promise<AsideMessage[]>) | undefined): void;
     emitExternalEvent(event: AgentEvent): void;
-    setSystemPrompt(v: string[]): void;
+    setSystemPrompt(v: string[] | string): void;
     setModel(m: Model): void;
     setThinkingLevel(l: Effort | undefined): void;
+    setDisableReasoning(disabled: boolean): void;
     setSteeringMode(mode: "all" | "one-at-a-time"): void;
     getSteeringMode(): "all" | "one-at-a-time";
     setFollowUpMode(mode: "all" | "one-at-a-time"): void;
@@ -290,6 +308,7 @@ export declare class Agent {
     getInterruptMode(): "immediate" | "wait";
     setTools(t: AgentTool<any>[]): void;
     replaceMessages(ms: AgentMessage[]): void;
+    replaceQueues(steering: AgentMessage[], followUp: AgentMessage[]): void;
     appendMessage(m: AgentMessage): void;
     popMessage(): AgentMessage | undefined;
     /**
@@ -306,6 +325,15 @@ export declare class Agent {
     clearFollowUpQueue(): void;
     clearAllQueues(): void;
     hasQueuedMessages(): boolean;
+    /** Non-consuming view of the pending steering queue (insertion order, newest
+     *  last). The session layer derives its queued-message display/count from
+     *  this live view instead of a mirror, so the agent-core queue stays the
+     *  single source of truth. */
+    peekSteeringQueue(): readonly AgentMessage[];
+    /** Non-consuming view of the pending follow-up queue. See
+     *  {@link peekSteeringQueue}. */
+    peekFollowUpQueue(): readonly AgentMessage[];
+    get isAborting(): boolean;
     /**
      * Remove and return the last steering message from the queue (LIFO).
      * Used by dequeue keybinding.
@@ -317,7 +345,7 @@ export declare class Agent {
      */
     popLastFollowUp(): AgentMessage | undefined;
     clearMessages(): void;
-    abort(): void;
+    abort(reason?: unknown): void;
     waitForIdle(): Promise<void>;
     reset(): void;
     /** Send a prompt with an AgentMessage */

package/dist/types/compaction/branch-summarization.d.ts

@@ -4,7 +4,7 @@
  * When navigating to a different point in the session tree, this generates
  * a summary of the branch being left so context isn't lost.
  */
-import type { Model } from "@prometheus-ai/ai";
+import type { ApiKey, Model } from "@prometheus-ai/ai";
 import { type AgentTelemetry } from "../telemetry";
 import type { AgentMessage } from "../types";
 import type { ReadonlySessionManager, SessionEntry } from "./entries";
@@ -41,7 +41,7 @@ export interface GenerateBranchSummaryOptions {
     /** Model to use for summarization */
     model: Model;
     /** API key for the model */
-    apiKey: string;
+    apiKey: ApiKey;
     /** Abort signal for cancellation */
     signal: AbortSignal;
     /** Optional custom instructions for summarization */
@@ -54,7 +54,7 @@ export interface GenerateBranchSummaryOptions {
     convertToLlm?: ConvertToLlm;
     /**
      * Optional telemetry handle. When provided, the branch summary LLM call is
-     * wrapped in an OTEL chat span tagged with `prometheus.gen_ai.oneshot.kind = "branch_summary"`.
+     * wrapped in an OTEL chat span tagged with `pi.gen_ai.oneshot.kind = "branch_summary"`.
      */
     telemetry?: AgentTelemetry;
 }

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

@@ -4,10 +4,10 @@
  * Pure functions for compaction logic. The session manager handles I/O,
  * and after compaction the session is reloaded.
  */
-import { type MessageAttribution, type Model, type Usage } from "@prometheus-ai/ai";
+import { type ApiKey, type FetchImpl, type MessageAttribution, type Model, type Tool, type Usage } from "@prometheus-ai/ai";
 import { type AgentTelemetry } from "../telemetry";
 import { ThinkingLevel } from "../thinking";
-import type { AgentMessage, AgentTool } from "../types";
+import type { AgentMessage } from "../types";
 import type { SessionEntry } from "./entries";
 import { type ConvertToLlm } from "./messages";
 import { type FileOperations } from "./utils";
@@ -30,7 +30,7 @@ export interface CompactionResult<T = unknown> {
 }
 export interface CompactionSettings {
     enabled: boolean;
-    strategy?: "context-full" | "handoff" | "shake" | "off";
+    strategy?: "context-full" | "handoff" | "shake" | "snapcompact" | "off";
     thresholdPercent?: number;
     thresholdTokens?: number;
     reserveTokens: number;
@@ -112,7 +112,7 @@ export interface SummaryOptions {
     /**
      * Optional telemetry handle. When provided, every LLM call emitted during
      * compaction is wrapped in an OTEL chat span tagged with
-     * `prometheus.gen_ai.oneshot.kind` (`compaction_summary`, `compaction_short_summary`,
+     * `pi.gen_ai.oneshot.kind` (`compaction_summary`, `compaction_short_summary`,
      * or `compaction_turn_prefix`). `undefined` keeps the call paths zero-cost.
      */
     telemetry?: AgentTelemetry;
@@ -125,20 +125,22 @@ export interface SummaryOptions {
      * `resolveCompactionEffort` for the conversion contract.
      */
     thinkingLevel?: ThinkingLevel;
+    /** Optional fetch implementation threaded into remote compaction calls. */
+    fetch?: FetchImpl;
 }
-export declare function generateSummary(currentMessages: AgentMessage[], model: Model, reserveTokens: number, apiKey: string, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, options?: SummaryOptions): Promise<string>;
+export declare function generateSummary(currentMessages: AgentMessage[], model: Model, reserveTokens: number, apiKey: ApiKey, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, options?: SummaryOptions): Promise<string>;
 export interface HandoffOptions {
     /** Live agent system prompt — passed verbatim so providers hit the cached prefix. */
     systemPrompt: string[];
     /** Live agent tool list — same purpose. Forced to `toolChoice: "none"`. */
-    tools?: AgentTool<any>[];
+    tools?: Tool[];
     customInstructions?: string;
     convertToLlm?: ConvertToLlm;
     initiatorOverride?: MessageAttribution;
     metadata?: Record<string, unknown>;
     /**
      * Optional telemetry handle. When provided, the handoff LLM call is
-     * wrapped in an OTEL chat span tagged with `prometheus.gen_ai.oneshot.kind = "handoff"`.
+     * wrapped in an OTEL chat span tagged with `pi.gen_ai.oneshot.kind = "handoff"`.
      */
     telemetry?: AgentTelemetry;
     /**
@@ -150,7 +152,7 @@ export interface HandoffOptions {
     thinkingLevel?: ThinkingLevel;
 }
 export declare function renderHandoffPrompt(customInstructions?: string): string;
-export declare function generateHandoff(messages: AgentMessage[], model: Model, apiKey: string, options: HandoffOptions, signal?: AbortSignal): Promise<string>;
+export declare function generateHandoff(messages: AgentMessage[], model: Model, apiKey: ApiKey, options: HandoffOptions, signal?: AbortSignal): Promise<string>;
 export interface CompactionPreparation {
     /** UUID of first entry to keep */
     firstKeptEntryId: string;
@@ -180,4 +182,4 @@ export declare function prepareCompaction(pathEntries: SessionEntry[], settings:
  * @param preparation - Pre-calculated preparation from prepareCompaction()
  * @param customInstructions - Optional custom focus for the summary
  */
-export declare function compact(preparation: CompactionPreparation, model: Model, apiKey: string, customInstructions?: string, signal?: AbortSignal, options?: SummaryOptions): Promise<CompactionResult>;
+export declare function compact(preparation: CompactionPreparation, model: Model, apiKey: ApiKey, customInstructions?: string, signal?: AbortSignal, options?: SummaryOptions): Promise<CompactionResult>;

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

@@ -33,6 +33,8 @@ export interface CompactionSummaryMessage {
     shortSummary?: string;
     tokensBefore: number;
     providerPayload?: ProviderPayload;
+    /** Snapcompact frames archived by this compaction; appended as image blocks after the summary text. */
+    images?: ImageContent[];
     timestamp: number;
 }
 export type CoreCompactionMessage = CustomMessage | HookMessage | BranchSummaryMessage | CompactionSummaryMessage;
@@ -48,8 +50,19 @@ export type ConvertToLlm = (messages: AgentMessage[]) => Message[];
 export declare function renderBranchSummaryContext(summary: string): string;
 export declare function renderCompactionSummaryContext(summary: string): string;
 export declare function createBranchSummaryMessage(summary: string, fromId: string, timestamp: string): BranchSummaryMessage;
-export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: string, shortSummary?: string, providerPayload?: ProviderPayload): CompactionSummaryMessage;
+export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: string, shortSummary?: string, providerPayload?: ProviderPayload, images?: ImageContent[]): CompactionSummaryMessage;
 export declare function createCustomMessage(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details: unknown | undefined, timestamp: string, attribution?: MessageAttribution): CustomMessage;
+/**
+ * Transform a single core-domain agent message to its LLM form; `undefined`
+ * drops it from the provider request.
+ *
+ * Single source of truth for the core roles (user/developer/assistant/
+ * toolResult) and the compaction messages owned by this package. Embedders
+ * with their own app messages (e.g. the coding agent) handle their custom
+ * roles and delegate every core role here — duplicating these cases is how
+ * snapcompact frames once silently fell off the provider request.
+ */
+export declare function convertMessageToLlm(message: AgentMessage): Message | undefined;
 /**
  * Default compaction-domain transformer.
  *
@@ -58,4 +71,3 @@ export declare function createCustomMessage(customType: string, content: string
  * core LLM roles and the compaction messages owned by this package.
  */
 export declare function defaultConvertToLlm(messages: AgentMessage[]): Message[];
-export declare const convertToLlm: typeof defaultConvertToLlm;

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

@@ -11,8 +11,17 @@
  *   summarization endpoints that accept `{ systemPrompt, prompt }` and reply
  *   with `{ summary, shortSummary? }`.
  */
-import type { Message, Model } from "@prometheus-ai/ai/types";
+import type { FetchImpl, Message, Model } from "@prometheus-ai/ai/types";
 export declare const OPENAI_REMOTE_COMPACTION_PRESERVE_KEY = "openaiRemoteCompaction";
+/**
+ * Hard ceiling on remote compaction HTTP requests. Unlike every provider
+ * stream (guarded by first-event/idle watchdogs in pi-ai), these are raw
+ * fetches awaiting one non-streamed JSON body — a connection silently dropped
+ * by a middlebox would otherwise hang the whole compaction pipeline forever
+ * (frozen "Auto context-full maintenance…" spinner, manual /compact queueing
+ * behind it). On timeout the caller falls back to local summarization.
+ */
+export declare const REMOTE_COMPACTION_TIMEOUT_MS = 180000;
 export type OpenAiRemoteCompactionItem = {
     type: "compaction" | "compaction_summary";
     encrypted_content?: string;
@@ -54,5 +63,11 @@ export declare function withOpenAiRemoteCompactionPreserveData(preserveData: Rec
  *   encrypted reasoning we want to preserve.
  */
 export declare function buildOpenAiNativeHistory(messages: Message[], model: Model, previousReplacementHistory?: Array<Record<string, unknown>>): Array<Record<string, unknown>>;
-export declare function requestOpenAiRemoteCompaction(model: Model, apiKey: string, compactInput: Array<Record<string, unknown>>, instructions: string, signal?: AbortSignal): Promise<OpenAiRemoteCompactionResponse>;
-export declare function requestRemoteCompaction(endpoint: string, request: RemoteCompactionRequest, signal?: AbortSignal): Promise<RemoteCompactionResponse>;
+export declare function requestOpenAiRemoteCompaction(model: Model, apiKey: string, compactInput: Array<Record<string, unknown>>, instructions: string, signal?: AbortSignal, opts?: {
+    fetch?: FetchImpl;
+    timeoutMs?: number;
+}): Promise<OpenAiRemoteCompactionResponse>;
+export declare function requestRemoteCompaction(endpoint: string, request: RemoteCompactionRequest, signal?: AbortSignal, opts?: {
+    fetch?: FetchImpl;
+    timeoutMs?: number;
+}): Promise<RemoteCompactionResponse>;

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

@@ -10,10 +10,65 @@ export interface PruneConfig {
     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;
 }
 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 (prompt cache is cold anyway). Default 30 min. */
+    idleFlushMs?: number;
+    /** Clock override for tests. */
+    now?: number;
+    /** 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 candidates flush).
+ */
+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

@@ -54,7 +54,9 @@ export type ShakeRegion = ToolResultShakeRegion | BlockShakeRegion;
  * 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. Returns regions in document order.
+ * 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

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

@@ -9,6 +9,22 @@ export interface FileOperations {
     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;
 /**
  * Extract file operations from tool calls in an assistant message.
  */
@@ -21,8 +37,8 @@ export declare function computeFileLists(fileOps: FileOperations): {
     readFiles: string[];
     modifiedFiles: string[];
 };
-export declare function formatFileOperations(readFiles: string[], modifiedFiles: string[]): string;
-export declare function upsertFileOperations(summary: string, readFiles: string[], modifiedFiles: string[]): 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;
 /**
  * Serialize LLM messages to text for summarization.
  * This prevents the model from treating it as a conversation to continue.

package/dist/types/proxy.d.ts

@@ -2,8 +2,8 @@
  * 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 Model, type SimpleStreamOptions, type StopReason } from "@prometheus-ai/ai";
-declare class ProxyMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
+import { type AssistantMessage, type AssistantMessageEvent, type Context, EventStream, type FetchImpl, type Model, type SimpleStreamOptions, type StopReason } from "@prometheus-ai/ai";
+export declare class ProxyMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
     constructor();
 }
 /**
@@ -60,6 +60,8 @@ export interface ProxyStreamOptions extends SimpleStreamOptions {
     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.
@@ -81,4 +83,3 @@ export interface ProxyStreamOptions extends SimpleStreamOptions {
  * ```
  */
 export declare function streamProxy(model: Model, context: Context, options: ProxyStreamOptions): ProxyMessageEventStream;
-export {};

package/dist/types/telemetry.d.ts

@@ -2,7 +2,7 @@
  * OpenTelemetry instrumentation for the agent loop.
  *
  * Implements the OpenTelemetry GenAI semantic conventions
- * (https://opentelemetry.io/docs/specs/semconv/gen-ai/) plus `prometheus.gen_ai.*`
+ * (https://opentelemetry.io/docs/specs/semconv/gen-ai/) plus `pi.gen_ai.*`
  * extension attributes for run summaries, dashboard summaries, and cost hints
  * that are useful to downstream observability UIs.
  *
@@ -78,32 +78,33 @@ export declare const enum OpenAIAttr {
     ResponseServiceTier = "openai.response.service_tier"
 }
 /** Project extension attributes. Kept out of the reserved `gen_ai.*` namespace. */
-export declare const enum PrometheusGenAIAttr {
-    AgentStepNumber = "prometheus.gen_ai.agent.step.number",
-    AgentStepCount = "prometheus.gen_ai.agent.step.count",
-    RequestReasoningEffort = "prometheus.gen_ai.request.reasoning.effort",
-    RequestToolChoice = "prometheus.gen_ai.request.tool.choice",
-    RequestAvailableTools = "prometheus.gen_ai.request.available_tools",
-    RequestMessages = "prometheus.gen_ai.request.messages",
-    ResponseText = "prometheus.gen_ai.response.text",
-    ResponseToolCalls = "prometheus.gen_ai.response.tool_calls",
-    UsageTotalTokens = "prometheus.gen_ai.usage.total_tokens",
-    UsageServerSideTools = "prometheus.gen_ai.usage.server_tool_requests",
-    CostEstimatedUsd = "prometheus.gen_ai.cost.estimated_usd",
-    CostInputUsd = "prometheus.gen_ai.cost.input_usd",
-    CostOutputUsd = "prometheus.gen_ai.cost.output_usd",
-    CostUnavailableReason = "prometheus.gen_ai.cost.unavailable_reason",
-    ToolStatus = "prometheus.gen_ai.tool.status",
-    ToolCallIntent = "prometheus.gen_ai.tool.call.intent",
-    HandoffFromAgentName = "prometheus.gen_ai.handoff.from_agent.name",
-    HandoffFromAgentId = "prometheus.gen_ai.handoff.from_agent.id",
-    HandoffToAgentName = "prometheus.gen_ai.handoff.to_agent.name",
-    HandoffToAgentId = "prometheus.gen_ai.handoff.to_agent.id",
-    OneshotKind = "prometheus.gen_ai.oneshot.kind",
-    GatewayName = "prometheus.gen_ai.gateway.name",
-    GatewayEndpoint = "prometheus.gen_ai.gateway.endpoint",
-    GatewayCallId = "prometheus.gen_ai.gateway.call_id",
-    GatewayRoutedTo = "prometheus.gen_ai.gateway.routed_to"
+export declare const enum PiGenAIAttr {
+    AgentStepNumber = "pi.gen_ai.agent.step.number",
+    AgentStepCount = "pi.gen_ai.agent.step.count",
+    RequestReasoningEffort = "pi.gen_ai.request.reasoning.effort",
+    RequestToolChoice = "pi.gen_ai.request.tool.choice",
+    RequestAvailableTools = "pi.gen_ai.request.available_tools",
+    RequestMessages = "pi.gen_ai.request.messages",
+    ResponseText = "pi.gen_ai.response.text",
+    ResponseToolCalls = "pi.gen_ai.response.tool_calls",
+    ResponseUpstreamProvider = "pi.gen_ai.response.upstream_provider",
+    UsageTotalTokens = "pi.gen_ai.usage.total_tokens",
+    UsageServerSideTools = "pi.gen_ai.usage.server_tool_requests",
+    CostEstimatedUsd = "pi.gen_ai.cost.estimated_usd",
+    CostInputUsd = "pi.gen_ai.cost.input_usd",
+    CostOutputUsd = "pi.gen_ai.cost.output_usd",
+    CostUnavailableReason = "pi.gen_ai.cost.unavailable_reason",
+    ToolStatus = "pi.gen_ai.tool.status",
+    ToolCallIntent = "pi.gen_ai.tool.call.intent",
+    HandoffFromAgentName = "pi.gen_ai.handoff.from_agent.name",
+    HandoffFromAgentId = "pi.gen_ai.handoff.from_agent.id",
+    HandoffToAgentName = "pi.gen_ai.handoff.to_agent.name",
+    HandoffToAgentId = "pi.gen_ai.handoff.to_agent.id",
+    OneshotKind = "pi.gen_ai.oneshot.kind",
+    GatewayName = "pi.gen_ai.gateway.name",
+    GatewayEndpoint = "pi.gen_ai.gateway.endpoint",
+    GatewayCallId = "pi.gen_ai.gateway.call_id",
+    GatewayRoutedTo = "pi.gen_ai.gateway.routed_to"
 }
 /** GenAI operation names — values for {@link GenAIAttr.OperationName}. */
 export declare const GenAIOperation: {
@@ -141,9 +142,9 @@ export interface CostEstimatorContext {
 }
 /**
  * Cost estimator result.
- *   { usd: number }                — cost is known; emitted as prometheus.gen_ai.cost.estimated_usd
+ *   { usd: number }                — cost is known; emitted as pi.gen_ai.cost.estimated_usd
  *   { unavailable: string }        — cost is intentionally unknown; emitted as
- *                                    prometheus.gen_ai.cost.unavailable_reason
+ *                                    pi.gen_ai.cost.unavailable_reason
  *   undefined                      — no opinion; nothing emitted
  */
 export type CostEstimate = {
@@ -192,7 +193,7 @@ export interface ChatUsageEvent {
      *
      * Use this to reconcile gateway-issued ids (e.g. `x-litellm-call-id`) with
      * downstream billing / spend dashboards. Known gateway patterns are also
-     * auto-stamped on the chat span as `prometheus.gen_ai.gateway.*` attributes.
+     * auto-stamped on the chat span as `pi.gen_ai.gateway.*` attributes.
      */
     readonly headers: Readonly<Record<string, string>> | undefined;
 }
@@ -446,7 +447,7 @@ export interface InstrumentedChatSpanOptions {
     /** Step index recorded on the span; defaults to `-1` for non-loop calls. */
     readonly stepNumber?: number;
     /**
-     * Tag stamped onto `prometheus.gen_ai.oneshot.kind`. Values used by the agent:
+     * Tag stamped onto `pi.gen_ai.oneshot.kind`. Values used by the agent:
      * `compaction_summary`, `compaction_short_summary`, `compaction_turn_prefix`,
      * `handoff`, `branch_summary`, `inspect_image`. Free-form to allow callers
      * outside this package to add new kinds without bumping the helper.
@@ -499,7 +500,7 @@ export declare function finishExecuteToolSpan(telemetry: AgentTelemetry | undefi
     readonly toolName: string;
 }): void;
 /** Span attribute carrying the terminal {@link ToolStatus}. */
-export declare const EXECUTE_TOOL_STATUS_ATTR = PrometheusGenAIAttr.ToolStatus;
+export declare const EXECUTE_TOOL_STATUS_ATTR = PiGenAIAttr.ToolStatus;
 /**
  * Record a tool that bypassed the span lifecycle entirely (pre-run
  * interrupt, post-execution tail sweep for calls that never produced a
@@ -527,36 +528,37 @@ export declare function finishInvokeAgentSpan(telemetry: AgentTelemetry | undefi
 } | undefined;
 /**
  * Invoke {@link AgentTelemetryConfig.onRunEnd} on `telemetry` if set. Throws
- are caught and logged via `console.warn` — telemetry callbacks NEVER turn a
+ * are caught and surfaced via the `onTelemetryWarning` hook (falling back to `console.warn`
+ * when no hook is set) — telemetry callbacks NEVER turn a
  * successful agent run into a failed one. Idempotent at the call site via
  * {@link AgentRunCollector.markRunEnded}; callers must check that before
  * calling this helper.
  */
 export declare function fireOnRunEnd(telemetry: AgentTelemetry, summary: AgentRunSummary, coverage: AgentRunCoverage): void;
-/** Aggregate `prometheus.gen_ai.agent.*` attributes stamped on the `invoke_agent` span. */
-export declare const enum PrometheusGenAIAggregateAttr {
-    ChatsCount = "prometheus.gen_ai.agent.chats.count",
-    ChatsTotalLatencyMs = "prometheus.gen_ai.agent.chats.total_latency_ms",
-    ChatsStopReasonPrefix = "prometheus.gen_ai.agent.chats.stop_reason.",
-    ToolsCount = "prometheus.gen_ai.agent.tools.count",
-    ToolsOkCount = "prometheus.gen_ai.agent.tools.ok.count",
-    ToolsErrorCount = "prometheus.gen_ai.agent.tools.error.count",
-    ToolsSkippedCount = "prometheus.gen_ai.agent.tools.skipped.count",
-    ToolsBlockedCount = "prometheus.gen_ai.agent.tools.blocked.count",
-    ToolsTimeoutCount = "prometheus.gen_ai.agent.tools.timeout.count",
-    ToolsAbortedCount = "prometheus.gen_ai.agent.tools.aborted.count",
-    ToolsTotalLatencyMs = "prometheus.gen_ai.agent.tools.total_latency_ms",
-    ToolsInvoked = "prometheus.gen_ai.agent.tools.invoked",
-    ToolsAvailable = "prometheus.gen_ai.agent.tools.available",
-    ToolsUnused = "prometheus.gen_ai.agent.tools.unused",
-    UsageInputTokensTotal = "prometheus.gen_ai.agent.usage.input_tokens.total",
-    UsageOutputTokensTotal = "prometheus.gen_ai.agent.usage.output_tokens.total",
-    UsageCacheReadInputTokensTotal = "prometheus.gen_ai.agent.usage.cache_read.input_tokens.total",
-    UsageCacheCreationInputTokensTotal = "prometheus.gen_ai.agent.usage.cache_creation.input_tokens.total",
-    UsageReasoningOutputTokensTotal = "prometheus.gen_ai.agent.usage.reasoning.output_tokens.total",
-    UsageTotalTokensTotal = "prometheus.gen_ai.agent.usage.total_tokens.total",
-    CostEstimatedUsdTotal = "prometheus.gen_ai.agent.cost.estimated_usd.total",
-    ErrorsCount = "prometheus.gen_ai.agent.errors.count"
+/** Aggregate `pi.gen_ai.agent.*` attributes stamped on the `invoke_agent` span. */
+export declare const enum PiGenAIAggregateAttr {
+    ChatsCount = "pi.gen_ai.agent.chats.count",
+    ChatsTotalLatencyMs = "pi.gen_ai.agent.chats.total_latency_ms",
+    ChatsStopReasonPrefix = "pi.gen_ai.agent.chats.stop_reason.",
+    ToolsCount = "pi.gen_ai.agent.tools.count",
+    ToolsOkCount = "pi.gen_ai.agent.tools.ok.count",
+    ToolsErrorCount = "pi.gen_ai.agent.tools.error.count",
+    ToolsSkippedCount = "pi.gen_ai.agent.tools.skipped.count",
+    ToolsBlockedCount = "pi.gen_ai.agent.tools.blocked.count",
+    ToolsTimeoutCount = "pi.gen_ai.agent.tools.timeout.count",
+    ToolsAbortedCount = "pi.gen_ai.agent.tools.aborted.count",
+    ToolsTotalLatencyMs = "pi.gen_ai.agent.tools.total_latency_ms",
+    ToolsInvoked = "pi.gen_ai.agent.tools.invoked",
+    ToolsAvailable = "pi.gen_ai.agent.tools.available",
+    ToolsUnused = "pi.gen_ai.agent.tools.unused",
+    UsageInputTokensTotal = "pi.gen_ai.agent.usage.input_tokens.total",
+    UsageOutputTokensTotal = "pi.gen_ai.agent.usage.output_tokens.total",
+    UsageCacheReadInputTokensTotal = "pi.gen_ai.agent.usage.cache_read.input_tokens.total",
+    UsageCacheCreationInputTokensTotal = "pi.gen_ai.agent.usage.cache_creation.input_tokens.total",
+    UsageReasoningOutputTokensTotal = "pi.gen_ai.agent.usage.reasoning.output_tokens.total",
+    UsageTotalTokensTotal = "pi.gen_ai.agent.usage.total_tokens.total",
+    CostEstimatedUsdTotal = "pi.gen_ai.agent.cost.estimated_usd.total",
+    ErrorsCount = "pi.gen_ai.agent.errors.count"
 }
 /**
  * Run `fn` with `span` activated on the OTEL context. Spans created