@linxiraos/pi-agent-core 1.0.0 → 1.0.2

package/dist/types/compaction.d.ts

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

package/dist/types/index.d.ts

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

package/dist/types/pause.d.ts

@@ -1,46 +0,0 @@
-/**
- * Process-global pause gate for agent loops.
- *
- * Every agent in a process — main session, in-process subagents, advisor —
- * funnels through {@link ../agent-loop!agentLoop}, which polls this gate at its
- * two action boundaries: before each model call and before each tool call
- * starts. Engaging the gate therefore freezes all of them at the next safe
- * point without aborting anything: in-flight provider streams and
- * already-started tool executions run to completion, then every loop parks
- * until {@link AgentPauseGate.resume}. Queued steering/follow-up messages stay
- * queued and deliver normally after resume.
- *
- * A run's own `AbortSignal` still unwinds a parked loop immediately: the park
- * releases on abort (without releasing the gate), so cancelling one run never
- * requires resuming the whole process.
- *
- * Hosts drive the singleton {@link agentPauseGate} (e.g. the TUI `/pause`
- * command); library code only ever reads it.
- */
-/** Listener invoked with the new state on every pause/resume transition. */
-export type AgentPauseListener = (paused: boolean) => void;
-/** Freeze switch shared by every agent loop in the process. See module docs. */
-export declare class AgentPauseGate {
-    #private;
-    /** True while the gate is engaged. */
-    get paused(): boolean;
-    /** Epoch ms when the current pause began; undefined when running. */
-    get pausedAt(): number | undefined;
-    /** Engage the gate. Returns false (and does nothing) when already paused. */
-    pause(): boolean;
-    /**
-     * Release the gate, waking every parked loop. Returns the pause duration in
-     * ms, or undefined when the gate was not engaged.
-     */
-    resume(): number | undefined;
-    /** Subscribe to pause/resume transitions. Returns an unsubscribe function. */
-    onChange(listener: AgentPauseListener): () => void;
-    /**
-     * Park until the gate is released. Resolves immediately when not paused.
-     * An abort on `signal` releases only this wait — the gate stays engaged —
-     * so a cancelled run unwinds while the rest of the process stays frozen.
-     */
-    waitUntilResumed(signal?: AbortSignal): Promise<void>;
-}
-/** The process-wide gate polled by the agent loop. */
-export declare const agentPauseGate: AgentPauseGate;

package/dist/types/proxy.d.ts

@@ -1,91 +0,0 @@
-/**
- * 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 ImageContent, type Model, type SimpleStreamOptions, type StopReason } from "@linxiraos/pi-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: "image_end";
-    contentIndex: number;
-    content: ImageContent;
-} | {
-    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"];
-    content?: AssistantMessage["content"];
-} | {
-    type: "error";
-    reason: Extract<StopReason, "aborted" | "error">;
-    errorMessage?: string;
-    usage: AssistantMessage["usage"];
-    content?: AssistantMessage["content"];
-};
-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

@@ -1,5 +0,0 @@
-import type { AssistantMessage, Message } from "@linxiraos/pi-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

@@ -1,196 +0,0 @@
-/**
- * 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 "@linxiraos/pi-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);
-}