@linxiraos/pi-agent-core 1.1.7 → 1.1.9

package/dist/types/compaction/transcript-tokens.d.ts

@@ -1,76 +0,0 @@
-/**
- * Provider-anchored transcript token accounting.
- *
- * Local tokenization is the expensive way to answer "how big is this
- * conversation?" — and usually the wrong one, because the provider already
- * answered it. Every settled assistant turn carries `usage` covering the exact
- * prompt it was sent: the system prompt, the tool schemas, and every message up
- * to and including itself. The only genuinely unaccounted-for text is the tail
- * appended *after* that turn.
- *
- * These helpers locate the newest trustworthy usage report and tokenize only
- * that tail, so a long session pays counting proportional to one turn instead
- * of to the whole transcript, every turn.
- *
- * Trust rules for an anchor (mirroring the provider contract):
- * - Assistant role only — nothing else carries `usage`.
- * - Not `aborted` / `error`: those turns report partial or zero usage.
- * - `hasContextTokenUsage(usage)`: the report must carry usable context numbers.
- */
-import type { AssistantMessage } from "@linxiraos/pi-ai";
-import type { Tokenizer } from "../tokenizer.js";
-import type { AgentMessage } from "../types.js";
-/** A provider usage report that accounts for a prefix of the transcript. */
-export interface TranscriptUsageAnchor {
-    /** Index in the scanned array; messages at or before it are provider-accounted. */
-    index: number;
-    /** The anchoring assistant turn. */
-    message: AssistantMessage;
-    /** Conversation tokens the provider reported for that prompt. */
-    tokens: number;
-}
-/**
- * Whether this message's provider usage may anchor transcript accounting.
- *
- * The single home for the trust rules — every anchor scan MUST route through
- * it so a stale-usage rule can never drift between the transcript walkers and
- * the session-entry walkers.
- */
-export declare function isTranscriptUsageAnchor(message: AgentMessage): message is AssistantMessage;
-/**
- * Newest assistant turn in `messages[fromIndex..]` whose usage can anchor the
- * transcript, or `undefined` when none qualifies (fresh context, or every
- * recent turn aborted/errored).
- *
- * `fromIndex` excludes turns whose usage is stale — anything a compaction
- * summarized away describes a prompt that is no longer sent.
- */
-export declare function findTranscriptUsageAnchor(messages: readonly AgentMessage[], fromIndex?: number): TranscriptUsageAnchor | undefined;
-/** Options for {@link estimateTranscriptTokens}. */
-export interface TranscriptTokenOptions {
-    /**
-     * Gates the anchor search only: usage at or before this index is stale (a
-     * compaction rewrote the prompt it describes) and must not anchor. Content
-     * accounting is governed separately by {@link countFromIndex}.
-     */
-    anchorFromIndex?: number;
-    /**
-     * First message whose content is counted locally when no anchor is found.
-     * Defaults to 0 (count the whole transcript), which is what a floor
-     * estimate wants; pass the compaction boundary to skip summarized-away
-     * messages entirely.
-     */
-    countFromIndex?: number;
-    /** Forwarded to {@link Tokenizer.countMessage} for every locally counted message. */
-    excludeEncryptedReasoning?: boolean;
-}
-/**
- * Conversation tokens for `messages`: the provider's own report for everything
- * it already covers, plus a local count of only the unaccounted-for tail.
- *
- * An anchored result already includes the non-message prefix (system prompt +
- * tool schemas) because the provider charged it; an unanchored result is a
- * message-only sum. Callers that add non-message tokens on top MUST branch on
- * {@link findTranscriptUsageAnchor} rather than assuming one shape.
- */
-export declare function estimateTranscriptTokens(messages: readonly AgentMessage[], tokenizer: Tokenizer, options?: TranscriptTokenOptions): number;

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

@@ -1,63 +0,0 @@
-/**
- * Shared utilities for compaction and branch summarization.
- */
-import type { Message } from "@linxiraos/pi-ai";
-import { type Dialect } from "@linxiraos/pi-ai/dialect";
-import type { AgentMessage } from "../types.js";
-export interface FileOperations {
-    read: Set<string>;
-    written: Set<string>;
-    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;
-/**
- * Whether `path` references a `scheme://` URL (internal URI or web URL) rather
- * than a filesystem path that belongs in the compaction `<files>` summary.
- */
-export declare function isUrlSchemePath(path: string): boolean;
-/**
- * Extract file operations from tool calls in an assistant message.
- */
-export declare function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOperations): void;
-/**
- * Compute final file lists from file operations.
- * Returns readFiles (files only read, not modified) and modifiedFiles.
- */
-export declare function computeFileLists(fileOps: FileOperations): {
-    readFiles: string[];
-    modifiedFiles: 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;
-/**
- * Truncate tool results to the same representation used in summarization prompts.
- */
-export declare function truncateToolResultForSummary(text: string): string;
-/** Keep untrusted summary input from closing or impersonating harness-owned boundaries. */
-export declare function escapeSummaryBoundaryTags(text: string): string;
-/**
- * Serialize LLM messages as plain summary input without provider control tokens.
- */
-export declare function serializeConversationForSummary(messages: Message[], dialect?: Dialect): string;
-/**
- * Serialize LLM messages to transcript text.
- * Call convertToLlm() first to handle custom message types.
- */
-export declare function serializeConversation(messages: Message[], dialect?: Dialect): string;
-export declare const SUMMARIZATION_SYSTEM_PROMPT: string;

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);
-}