@vib-rato/agent-core 0.16.0

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

@@ -0,0 +1,223 @@
+/**
+ * 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 "@vib-rato/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;
+    /** Begin a chat record without allocating or mutating an OTEL span. */
+    beginChatWithoutSpan(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;
+    /** Finish a chat record without allocating or mutating an OTEL span. */
+    endChatWithoutSpan(stepNumber: number | undefined, 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;
+    /** Record a failed chat without allocating or mutating an OTEL span. */
+    failChatWithoutSpan(stepNumber: number | undefined, fields: {
+        readonly errorType: string;
+    }): void;
+    beginTool(span: Span, init: {
+        readonly toolCallId: string;
+        readonly toolName: string;
+    }): void;
+    /** Begin a tool record without allocating or mutating an OTEL span. */
+    beginToolWithoutSpan(init: {
+        readonly toolCallId: string;
+        readonly toolName: string;
+    }): void;
+    endTool(span: Span, fields: {
+        readonly status: ToolStatus;
+        readonly errorType: string | undefined;
+    }): void;
+    /** Finish a tool record without allocating or mutating an OTEL span. */
+    endToolWithoutSpan(record: {
+        readonly toolCallId: string;
+        readonly toolName: string;
+        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);
+}

package/dist/types/run-resource-ledger.d.ts

@@ -0,0 +1,2 @@
+import type { RunResourceLedger } from "./types";
+export declare function createRunResourceLedger(): RunResourceLedger;