@linxiraos/pi-agent-core 1.0.0

package/dist/types/compaction/message-cache.d.ts

@@ -0,0 +1,23 @@
+import type { AgentMessage } from "../types.js";
+/**
+ * Register a cache tied to message identity so owner mutations in this package
+ * (prune/shake) can invalidate it across the package boundary. Returns an
+ * unregister function. The coding-agent `convertToLlm` memo registers here.
+ */
+export declare function registerMessageCacheInvalidator(invalidate: (message: AgentMessage) => void): () => void;
+/**
+ * True when this message's estimate is safe to cache by identity. Non-assistants
+ * are immutable once appended; assistants are cached only once settled (see the
+ * settle-gate invariant above).
+ */
+export declare function isEstimateCacheable(message: AgentMessage): boolean;
+/** Read a cached estimate for the given option split, or `undefined` on miss. */
+export declare function readEstimateCache(message: AgentMessage, excludeEncryptedReasoning: boolean): number | undefined;
+/** Store an estimate for the given option split. */
+export declare function writeEstimateCache(message: AgentMessage, excludeEncryptedReasoning: boolean, value: number): void;
+/**
+ * Drop every cached derivation of `message` after an in-place rewrite. Owners of
+ * mutation (prune, shake, strip-images) call this at the mutation seam so the
+ * next convert/estimate pass recomputes from the new content.
+ */
+export declare function invalidateMessageCache(message: AgentMessage): void;

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

@@ -0,0 +1,79 @@
+import type { ImageContent, Message, MessageAttribution, ProviderPayload, TextContent } from "@linxiraos/pi-ai";
+import type { AgentMessage } from "../types.js";
+export interface CustomMessage<T = unknown> {
+    role: "custom";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    display: boolean;
+    details?: T;
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    timestamp: number;
+}
+/** Legacy hook message type (pre-extensions). Kept for session migration. */
+export interface HookMessage<T = unknown> {
+    role: "hookMessage";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    display: boolean;
+    details?: T;
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    timestamp: number;
+}
+export interface BranchSummaryMessage {
+    role: "branchSummary";
+    summary: string;
+    fromId: string;
+    timestamp: number;
+}
+export interface CompactionSummaryMessage {
+    role: "compactionSummary";
+    summary: string;
+    shortSummary?: string;
+    tokensBefore: number;
+    providerPayload?: ProviderPayload;
+    /** Runtime-only ordered archive blocks for snapcompact: old text region,
+     *  imaged middle, then new text region. When present, `summary` is already
+     *  the final lead-in text (no legacy wrapper applied). */
+    blocks?: (TextContent | ImageContent)[];
+    /** Snapcompact image blocks, kept for display counts / legacy consumers. */
+    images?: ImageContent[];
+    /** Post-pass dead-end warning attached to this compaction (progress guard). */
+    warning?: string;
+    timestamp: number;
+}
+export type CoreCompactionMessage = CustomMessage | HookMessage | BranchSummaryMessage | CompactionSummaryMessage;
+declare module "../types.js" {
+    interface CustomAgentMessages {
+        custom: CustomMessage;
+        hookMessage: HookMessage;
+        branchSummary: BranchSummaryMessage;
+        compactionSummary: CompactionSummaryMessage;
+    }
+}
+export type ConvertToLlm = (messages: AgentMessage[]) => Message[];
+export declare function renderBranchSummaryContext(summary: string): string;
+export declare function renderCompactionSummaryContext(summary: string): string;
+export declare function createBranchSummaryMessage(summary: string, fromId: string, timestamp: string): BranchSummaryMessage;
+export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: string, shortSummary?: string, providerPayload?: ProviderPayload, images?: ImageContent[], blocks?: (TextContent | ImageContent)[], warning?: string): CompactionSummaryMessage;
+export declare function createCustomMessage(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details: unknown | undefined, timestamp: string, attribution?: MessageAttribution): CustomMessage;
+/**
+ * Transform a single core-domain agent message to its LLM form; `undefined`
+ * drops it from the provider request.
+ *
+ * Single source of truth for the core roles (user/developer/assistant/
+ * toolResult) and the compaction messages owned by this package. Embedders
+ * with their own app messages (e.g. the coding agent) handle their custom
+ * roles and delegate every core role here — duplicating these cases is how
+ * snapcompact frames once silently fell off the provider request.
+ */
+export declare function convertMessageToLlm(message: AgentMessage): Message | undefined;
+/**
+ * Default compaction-domain transformer.
+ *
+ * Embedders with their own app messages should pass a richer transformer through
+ * `SummaryOptions.convertToLlm`; this default intentionally preserves only the
+ * core LLM roles and the compaction messages owned by this package.
+ */
+export declare function defaultConvertToLlm(messages: AgentMessage[]): Message[];

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

@@ -0,0 +1,117 @@
+/**
+ * Remote compaction utilities.
+ *
+ * Provider-side conversation summarization endpoints. Three flavors:
+ *
+ * - **OpenAI remote compaction V2** (Responses streaming): appends a
+ *   `compaction_trigger` input item to the normal stream and stores the returned
+ *   `compaction` item with retained real user messages in `preserveData`.
+ * - **OpenAI remote compaction V1** (`/responses/compact`): preserves encrypted
+ *   reasoning across compactions by submitting the full responses-API native
+ *   history and storing the returned `compaction` / `compaction_summary`
+ *   item in `preserveData` so future turns can replay the encrypted state.
+ * - **Generic remote compaction**: a thin POST helper for self-hosted
+ *   summarization endpoints that accept `{ systemPrompt, prompt }` and reply
+ *   with `{ summary, shortSummary? }`.
+ */
+import type { CodexCompactionContext, FetchImpl, Message, Model, ProviderSessionState } from "@linxiraos/pi-ai/types";
+export * from "./compaction-v2-streaming.js";
+export declare const OPENAI_REMOTE_COMPACTION_PRESERVE_KEY = "openaiRemoteCompaction";
+/**
+ * Hard ceiling on remote compaction HTTP requests. Unlike every provider
+ * stream (guarded by first-event/idle watchdogs in pi-ai), these are raw
+ * fetches awaiting one non-streamed JSON body — a connection silently dropped
+ * by a middlebox would otherwise hang the whole compaction pipeline forever
+ * (frozen "Auto context-full maintenance…" spinner, manual /compact queueing
+ * behind it). On timeout the caller falls back to local summarization.
+ */
+export declare const REMOTE_COMPACTION_TIMEOUT_MS = 180000;
+export declare const CONTEXT_WINDOW_TRUNCATED_OUTPUT_MESSAGE: string;
+export interface TrimRemoteCompactionInputResult {
+    input: Array<Record<string, unknown>>;
+    rewrittenOutputs: number;
+    estimatedTokensBefore: number;
+    estimatedTokensAfter: number;
+}
+/**
+ * Preserve the full native transcript unless trailing tool outputs alone push a
+ * remote compaction request beyond the model window. Replacing only those
+ * outputs keeps call/result pairing and all earlier assistant/reasoning history,
+ * matching Codex's recovery path for oversized tool turns.
+ */
+export declare function trimRemoteCompactionInputToContextWindow(input: Array<Record<string, unknown>>, contextWindow: number | null | undefined, instructions: string, tools?: unknown[]): TrimRemoteCompactionInputResult;
+export type OpenAiRemoteCompactionItem = {
+    type: "compaction" | "compaction_summary";
+    encrypted_content?: string;
+    summary?: string;
+};
+export interface OpenAiRemoteCompactionPreserveData {
+    provider?: string;
+    replacementHistory: Array<Record<string, unknown>>;
+    compactionItem: OpenAiRemoteCompactionItem;
+}
+export interface OpenAiRemoteCompactionRequest {
+    model: string;
+    input: Array<Record<string, unknown>>;
+    instructions: string;
+    reasoning?: {
+        context?: string;
+        [key: string]: unknown;
+    };
+    include?: string[];
+}
+export interface OpenAiRemoteCompactionResponse extends OpenAiRemoteCompactionPreserveData {
+}
+export interface RemoteCompactionRequest {
+    systemPrompt: string;
+    prompt: string;
+    maxTokens?: number;
+}
+export interface RemoteCompactionResponse {
+    summary: string;
+    shortSummary?: string;
+}
+export declare function shouldUseOpenAiRemoteCompaction(model: Model): boolean;
+export declare function getPreservedOpenAiRemoteCompactionData(preserveData: Record<string, unknown> | undefined): OpenAiRemoteCompactionPreserveData | undefined;
+export declare function withOpenAiRemoteCompactionPreserveData(preserveData: Record<string, unknown> | undefined, remoteCompaction: OpenAiRemoteCompactionPreserveData | undefined): Record<string, unknown> | undefined;
+/**
+ * Build the OpenAI Responses-API native history array from LLM messages.
+ *
+ * Caller is responsible for converting any custom message types to
+ * `Message[]` first (e.g. via the agent's `convertToLlm`); this function
+ * operates purely on the LLM-domain shape.
+ *
+ * @param messages - LLM messages to encode.
+ * @param model - Target model (used for provider gating + tool-call id rules).
+ * @param previousReplacementHistory - History from a prior compaction whose
+ *   encrypted reasoning we want to preserve.
+ */
+export declare function buildOpenAiNativeHistory(messages: Message[], model: Model, previousReplacementHistory?: Array<Record<string, unknown>>): Array<Record<string, unknown>>;
+export declare function requestOpenAiRemoteCompaction(model: Model, apiKey: string, compactInput: Array<Record<string, unknown>>, instructions: string, signal?: AbortSignal, opts?: {
+    fetch?: FetchImpl;
+    timeoutMs?: number;
+    sessionId?: string;
+    providerSessionState?: Map<string, ProviderSessionState>;
+    codexCompaction?: CodexCompactionContext;
+}): Promise<OpenAiRemoteCompactionResponse>;
+/**
+ * Generic remote-compaction POST. Two wire shapes are auto-selected by
+ * endpoint suffix so a single `compaction.remoteEndpoint` setting can point at
+ * either a purpose-built omp summarizer (`{systemPrompt, prompt}` → `{summary}`)
+ * or any OpenAI-compatible chat-completions server (`/chat/completions`,
+ * `/v1/chat/completions`, …) as reported for llama.cpp / vLLM / etc. in
+ * issue #4630: without this, the omp payload was rejected with
+ * HTTP 400 `"'messages' is required"`, compaction silently fell back to
+ * local summarization, and context grew unbounded.
+ *
+ * When `context.model` is provided the chat-completions body is tagged with
+ * that model's wire id (llama.cpp requires the field) and `context.apiKey` is
+ * forwarded as `Authorization: Bearer`. Callers wrap this in `withAuth` so
+ * 401s force-refresh through the standard credential rotation policy.
+ */
+export declare function requestRemoteCompaction(endpoint: string, request: RemoteCompactionRequest, signal?: AbortSignal, opts?: {
+    fetch?: FetchImpl;
+    timeoutMs?: number;
+    model?: Model;
+    apiKey?: string;
+}): Promise<RemoteCompactionResponse>;

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

@@ -0,0 +1,105 @@
+/**
+ * Tool output pruning utilities for compaction.
+ */
+import type { SessionEntry } from "./entries.js";
+import { type ProtectedToolMatcher } from "./tool-protection.js";
+export interface PruneConfig {
+    /** Keep the most recent tool output tokens intact. */
+    protectTokens: number;
+    /** Only prune if total savings meets this threshold. */
+    minimumSavings: number;
+    /** Tool-result protection matchers. String entries protect every result from that tool; predicates may inspect the paired tool call. */
+    protectedTools: ProtectedToolMatcher[];
+    /**
+     * Optional supersede key function (see {@link SupersedePruneConfig.supersedeKey}).
+     * When provided, superseded tool results are pruned first — even inside the
+     * `protectTokens` window — before age-based victims. Absent, behavior is
+     * unchanged.
+     */
+    supersedeKey?: SupersedeKeyFn;
+    /** Useless-flagged results bypass the protect window (see {@link USELESS_NOTICE}). Default true. */
+    pruneUseless?: boolean;
+    /**
+     * Compaction boundary: the `firstKeptEntryId` of the latest compaction on
+     * the branch. Entries at indices BEFORE this id are summarized away and never
+     * sent to the model, so mutating them only churns persisted history without
+     * shrinking the prompt — they are skipped. Undefined = no compaction (the
+     * whole branch is sent).
+     */
+    keepBoundaryId?: string;
+    /**
+     * Prompt-cache guard. When set, a tool result whose all-message suffix
+     * (tokens of every message after it) EXCEEDS this is part of the warm,
+     * already-sent cache prefix: mutating it forces the provider to re-write the
+     * whole suffix (cacheWrite premium). Such results — including superseded and
+     * useless ones, which otherwise bypass {@link protectTokens} — are left for
+     * compaction/shake (which rebuild the cache anyway) to reclaim. Undefined =
+     * no cache guard (legacy: superseded/useless prune at any depth).
+     */
+    cacheWarmSuffixTokens?: number;
+}
+export declare const DEFAULT_PRUNE_CONFIG: PruneConfig;
+export interface PruneResult {
+    prunedCount: number;
+    tokensSaved: number;
+}
+/** Exact placeholder written over a superseded tool result. */
+export declare const SUPERSEDED_NOTICE = "[Superseded by a newer read of this file]";
+/** Exact placeholder written over an elided useless tool result. */
+export declare const USELESS_NOTICE = "[Uneventful result elided]";
+/**
+ * Maps a tool call to a supersede key. Results sharing a key form a group in
+ * which every result except the newest is a supersede candidate. A key `K`
+ * additionally supersedes keys with prefix `K + "\u0000"` (selector-free read
+ * supersedes selector-carrying reads of the same base path). Return
+ * `undefined` to exempt a call from supersede grouping.
+ */
+export type SupersedeKeyFn = (toolName: string, args: Record<string, unknown>) => string | undefined;
+export interface SupersedePruneConfig {
+    /** Supersede key function; results sharing a key supersede older ones. */
+    supersedeKey?: SupersedeKeyFn;
+    /** Also prune results flagged useless by their tool. Default false. */
+    pruneUseless?: boolean;
+    /** Prune a candidate now when all messages after it total at most this many estimated tokens. Default 8 000. */
+    suffixTokenLimit?: number;
+    /**
+     * Prune all candidates when the last message is at least this old: the
+     * provider prompt cache is then cold, so re-writing it is free. MUST exceed
+     * the cache retention (Anthropic "long" = 1h) or a still-warm prefix is busted
+     * by the flush. Default 30 min — callers on long retention override it.
+     */
+    idleFlushMs?: number;
+    /** Clock override for tests. */
+    now?: number;
+    /**
+     * Compaction boundary (`firstKeptEntryId` of the latest compaction). Entries
+     * before it are summarized away and never sent, so they are skipped in every
+     * path — including the idle flush — to avoid pointless history churn.
+     * Undefined = no compaction (the whole branch is sent).
+     */
+    keepBoundaryId?: string;
+    /** Tool-result protection matchers (same contract as {@link PruneConfig.protectedTools}). */
+    protectedTools: ProtectedToolMatcher[];
+}
+/**
+ * Prune superseded tool results (e.g. stale `read` outputs replaced by a newer
+ * read of the same file) and, when `pruneUseless` is set, results their tool
+ * flagged contextually useless. Cheap, incremental, and prompt-cache-aware: a
+ * candidate is pruned now only when the suffix after it is small (tail case —
+ * the read→edit→read loop) or when the context has been idle long enough that
+ * the provider cache is cold anyway (then all still-sent candidates flush).
+ * Never mutates entries before `keepBoundaryId` (summarized away — not sent).
+ */
+export declare function pruneSupersededToolResults(entries: SessionEntry[], config: SupersedePruneConfig): PruneResult;
+export declare function pruneToolOutputs(entries: SessionEntry[], config?: PruneConfig): PruneResult;
+/**
+ * Supersede key for the `read` tool: the file path with the trailing line/raw
+ * selector stripped (the read tool's own splitter grammar via
+ * {@link splitReadSelector}, e.g. `src/foo.ts:50-200`, `:2-4:raw`).
+ * Internal/URL-scheme paths (`skill://…`, `https://…`) are exempt.
+ * Selector-free reads key on the bare path; selector-carrying reads key on
+ * `path + "\u0000" + selector`, so two reads collide only when the newer is
+ * selector-free or the selectors are identical (the pass's prefix rule lets a
+ * bare-path read supersede selector-carrying reads of the same file).
+ */
+export declare function readToolSupersedeKey(toolName: string, args: Record<string, unknown>): string | undefined;

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

@@ -0,0 +1,97 @@
+/**
+ * Context-reducing surgical compaction ("shake").
+ *
+ * `shake` drops heavy content out of the live context mechanically: whole
+ * tool-call results and large fenced/XML blocks are replaced with short
+ * placeholders. This module is the pure layer — region detection and in-place
+ * mutation only. Artifact offload, persistence, and provider-session teardown
+ * are orchestrated by the caller (`AgentSession.shake`).
+ *
+ * Layering mirrors `pruning.ts`: no I/O here.
+ */
+import type { CustomMessageEntry, SessionEntry, SessionMessageEntry } from "./entries.js";
+import { type ProtectedToolMatcher } from "./tool-protection.js";
+export interface ShakeConfig {
+    /** Keep the most recent context tokens (across all entries) intact. */
+    protectTokens: number;
+    /** Only shake when total estimated savings meets this threshold. */
+    minSavings: number;
+    /** Tool-result protection matchers. String entries protect every result from that tool; predicates may inspect the paired tool call. */
+    protectedTools: ProtectedToolMatcher[];
+    /** Minimum token size for a fenced/XML block to be eligible. */
+    fenceMinTokens: number;
+    /**
+     * Compaction boundary (`firstKeptEntryId` of the latest compaction). Entries
+     * before it are summarized away and never sent, so they are skipped — shaking
+     * them only churns persisted history. Undefined = no compaction (whole branch
+     * is sent). Note: shake still elides the warm cached prefix at/after the
+     * boundary — that is its job as a compaction-class reducer.
+     */
+    keepBoundaryId?: string;
+}
+/** Auto-shake config: protects the live tail, conservative thresholds. */
+export declare const DEFAULT_SHAKE_CONFIG: ShakeConfig;
+/**
+ * Manual `/shake`: aggressive — drops every eligible region across history,
+ * artifact recovery reads included (the user's full escape hatch).
+ */
+export declare const AGGRESSIVE_SHAKE_CONFIG: ShakeConfig;
+/** Compaction dead-end rescue: aggressive reach, but artifact recovery reads stay protected. */
+export declare const RESCUE_SHAKE_CONFIG: ShakeConfig;
+/** A located eligible region. */
+export interface ToolResultShakeRegion {
+    kind: "toolResult";
+    entry: SessionMessageEntry;
+    tokens: number;
+    originalText: string;
+    /** Human label for the offload doc (tool name). */
+    label: string;
+}
+export interface BlockShakeRegion {
+    kind: "block";
+    entry: SessionMessageEntry | CustomMessageEntry;
+    /** Index into the content array, or -1 for string-form content. */
+    blockIndex: number;
+    /** Character offsets into the target text (start inclusive, end exclusive). */
+    start: number;
+    end: number;
+    tokens: number;
+    originalText: string;
+    /** Human label for the offload doc (role / customType). */
+    label: string;
+}
+export type ShakeRegion = ToolResultShakeRegion | BlockShakeRegion;
+/**
+ * Pure detection: locate every eligible shake region on a branch.
+ *
+ * Walks the protect-recent window (most recent `protectTokens` of context is
+ * kept intact), collects whole tool-result messages (honoring `protectedTools`
+ * and skipping already-pruned results) and large fenced/XML blocks inside
+ * user/developer/assistant/custom messages. Tool results flagged contextually
+ * useless by their tool bypass the protect window — there is nothing recent
+ * worth keeping in them. Returns regions in document order.
+ *
+ * `toolCall` blocks are never touched (tool-call/result pairing is preserved)
+ * and regions never span a message boundary. When the combined estimated
+ * savings is below `minSavings`, returns `[]` (no-op).
+ */
+export declare function collectShakeRegions(entries: SessionEntry[], config: ShakeConfig): ShakeRegion[];
+/**
+ * Pure mutation: replace a single region's content in place.
+ *
+ * Tool-result: replaces the message content with the placeholder text and
+ * stamps `prunedAt`. Block: splices `replacement` over `[start, end)` of the
+ * target text block. When several block regions share one text block they MUST
+ * be applied highest-start-first so earlier offsets stay valid — use
+ * {@link applyShakeRegions}, which orders them correctly.
+ */
+export declare function applyShakeRegion(region: ShakeRegion, replacement: string): void;
+/**
+ * Apply many regions at once. Block regions are applied highest-start-first so
+ * that splicing one region never shifts the offsets of another in the same text
+ * block; tool-result regions are independent.
+ */
+export declare function applyShakeRegions(items: Array<{
+    region: ShakeRegion;
+    replacement: string;
+}>): void;

package/dist/types/compaction/tool-protection.d.ts

@@ -0,0 +1,19 @@
+import type { ToolResultMessage } from "@linxiraos/pi-ai";
+import type { AgentToolCall } from "../types.js";
+import type { SessionEntry } from "./entries.js";
+export interface ProtectedToolContext {
+    readonly toolResult: ToolResultMessage;
+    readonly toolCall: AgentToolCall | undefined;
+}
+export type ProtectedToolMatcher = string | ((context: ProtectedToolContext) => boolean);
+export declare function collectToolCallsById(entries: readonly SessionEntry[]): Map<string, AgentToolCall>;
+/**
+ * Extract the `path` argument from a paired `read` tool call, when the result
+ * is a `read` result carrying a string path. Returns `undefined` otherwise.
+ * Shared primitive for read-targeted protection matchers (skills, plans, …).
+ */
+export declare function getReadToolPath({ toolResult, toolCall }: ProtectedToolContext): string | undefined;
+export declare function isSkillReadToolResult(context: ProtectedToolContext): boolean;
+/** Recovery reads of session artifacts — eliding one only mints another artifact and can repeat indefinitely. */
+export declare function isArtifactRecoveryToolResult(context: ProtectedToolContext): boolean;
+export declare function isProtectedToolResult(toolResult: ToolResultMessage, toolCall: AgentToolCall | undefined, matchers: readonly ProtectedToolMatcher[]): boolean;

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

@@ -0,0 +1,61 @@
+/**
+ * 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;
+/**
+ * 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

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

package/dist/types/index.d.ts

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,46 @@
+/**
+ * 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

@@ -0,0 +1,91 @@
+/**
+ * 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

@@ -0,0 +1,5 @@
+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[];