@gajae-code/agent-core 0.1.1

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 "@gajae-code/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 { AssistantMessage, Model, StopReason } from "@gajae-code/ai";
+import type { Span } from "@opentelemetry/api";
+/** 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);
+}