@prometheus-ai/agent-core 0.5.0

package/dist/types/harmony-leak.d.ts

@@ -0,0 +1,118 @@
+/**
+ * GPT-5 Harmony-header leakage detection and recovery.
+ *
+ * Background and policy: see `docs/ERRATA-GPT5-HARMONY.md`. This module
+ * implements §3 of that document: detection by signal fusion, plus a
+ * truncate-and-resume primitive for the `edit` tool when its input is in
+ * hashline DSL form. Other tools and surfaces fall through to
+ * abort-and-retry handled by the agent loop.
+ */
+import type { AssistantMessage, Model, ToolCall } from "@prometheus-ai/ai";
+declare const SIGNAL_ORDER: readonly ["M", "C", "G", "S", "B", "R", "T"];
+export type HarmonySignalClass = "H" | (typeof SIGNAL_ORDER)[number];
+export type HarmonySurface = "assistant_text" | "assistant_thinking" | "tool_arg";
+export interface HarmonySignal {
+    classes: HarmonySignalClass[];
+    start: number;
+    end: number;
+    text: string;
+}
+export interface HarmonyDetection {
+    surface: HarmonySurface;
+    contentIndex?: number;
+    toolName?: string;
+    toolCallId?: string;
+    signals: HarmonySignal[];
+}
+export interface HarmonyAuditEvent {
+    action: "truncate_resume" | "abort_retry" | "escalated";
+    surface: HarmonySurface;
+    signal: string;
+    retryN: number;
+    model: string;
+    provider: string;
+    toolName?: string;
+    removedLen: number;
+    removedSha8: string;
+    removedPreview: string;
+    removedBlob?: string;
+}
+export interface HarmonyRecoveredToolCall {
+    message: AssistantMessage;
+    removed: string;
+}
+/**
+ * Whether to run leak detection on responses from this model. We default-on
+ * for every openai-codex model rather than enumerating ids, so a future
+ * gpt-5.6 (or whatever) doesn't silently bypass the mitigation. Detection
+ * itself is cheap; the cost of missing a leak on a new model is not.
+ */
+export declare function isHarmonyLeakMitigationTarget(model: Model): boolean;
+export declare function signalListLabel(signals: readonly HarmonySignal[]): string;
+/**
+ * Detect harmony-protocol leakage in `text`. Returns undefined if clean.
+ *
+ * Trip rule: `H` alone, or `M` paired with at least one co-signal
+ * (`C`/`G`/`S`/`B`/`R`/`T`). Bare `M` does not trip — this document, its
+ * tests, and bug reports legitimately carry the marker.
+ *
+ * The `tool_arg` surface is held to a stricter rule. A tool argument is
+ * arbitrary file/data content that can legitimately carry the marker, a
+ * channel word, harmony control tokens, or a non-Latin script run (editing
+ * these very fixtures does exactly that). The only robust leak signal there
+ * is content trailing the structurally-valid parse, so a `tool_arg` detection
+ * additionally requires the `T` co-signal. Absent a `parsedEnd` boundary `T`
+ * is never set, so `tool_arg` scanning stays inert and a legitimate codex tool
+ * call is never hard-aborted. `assistant_text`/`assistant_thinking` keep the
+ * base rule.
+ *
+ * `parsedEnd`, when supplied, marks the byte at which a structurally valid
+ * tool-argument parse ends; markers at or past it set the `T` co-signal.
+ * `contentIndex`/`toolName`/`toolCallId` flow through to the returned
+ * detection for downstream auditing.
+ */
+export declare function detectHarmonyLeak(text: string, surface: HarmonySurface, options?: {
+    parsedEnd?: number;
+    contentIndex?: number;
+    toolName?: string;
+    toolCallId?: string;
+}): HarmonyDetection | undefined;
+/**
+ * Scan an assistant message's content blocks; return the first detection.
+ *
+ * `toolArgParseEnd`, when supplied, resolves the byte offset at which a tool
+ * call's structurally-valid argument parse ends (the `T` co-signal in
+ * {@link detectHarmonyLeak}). Callers that can parse a tool's argument DSL pass
+ * it to enable `tool_arg` leak detection; omitting it keeps that surface inert
+ * — the safe default the agent loop relies on, since it cannot bound a streamed
+ * tool DSL and must never hard-abort a legitimate tool call.
+ */
+export declare function detectHarmonyLeakInAssistantMessage(message: AssistantMessage, toolArgParseEnd?: (toolCall: ToolCall) => number | undefined): HarmonyDetection | undefined;
+/**
+ * Truncate a contaminated tool call at the start of the contaminated line and
+ * append the tool's recovery sentinel. Returns a recovered AssistantMessage
+ * (containing only the cleaned tool call), a synthetic continuation user
+ * message asking the model to re-issue the rest, and the removed substring
+ * for auditing. Returns undefined when the tool is not recovery-eligible or
+ * the truncation would leave nothing meaningful to dispatch.
+ *
+ * `providerPayload` is dropped from the recovered message: for Codex the
+ * encrypted reasoning blob is opaque/signed and we cannot validate that it is
+ * uncontaminated. The model re-reasons on the next turn.
+ */
+export declare function recoverHarmonyToolCall(message: AssistantMessage, detection: HarmonyDetection): HarmonyRecoveredToolCall | undefined;
+/**
+ * Return the contaminated substring from `message` for audit purposes when
+ * recovery is not applicable (abort path). Walks from the first detected
+ * signal to end-of-content within the relevant block. Returns "" if the
+ * detection cannot be resolved against the message.
+ */
+export declare function extractHarmonyRemoved(message: AssistantMessage, detection: HarmonyDetection): string;
+export declare function createHarmonyAuditEvent(params: {
+    action: HarmonyAuditEvent["action"];
+    detection: HarmonyDetection;
+    model: Model;
+    retryN: number;
+    removed: string;
+}): HarmonyAuditEvent;
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./agent";
+export * from "./agent-loop";
+export * from "./append-only-context";
+export * from "./compaction";
+export * from "./harmony-leak";
+export * from "./proxy";
+export * from "./run-collector";
+export * from "./telemetry";
+export * from "./thinking";
+export * from "./types";
+export * from "./utils/yield";

package/dist/types/proxy.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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> {
+    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;
+}
+/**
+ * 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;
+export {};

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 "@prometheus-ai/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);
+}