jeopi-agent-core 16.2.13 → 16.2.14

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

@@ -1,77 +0,0 @@
-import type { ImageContent, Message, MessageAttribution, ProviderPayload, TextContent } from "jeopi-ai";
-import type { AgentMessage } from "../types";
-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[];
-    timestamp: number;
-}
-export type CoreCompactionMessage = CustomMessage | HookMessage | BranchSummaryMessage | CompactionSummaryMessage;
-declare module "../types" {
-    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)[]): 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

@@ -1,77 +0,0 @@
-/**
- * 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 { FetchImpl, Message, Model } from "jeopi-ai/types";
-export * from "./compaction-v2-streaming";
-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 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;
-}
-export interface OpenAiRemoteCompactionResponse extends OpenAiRemoteCompactionPreserveData {
-}
-export interface RemoteCompactionRequest {
-    systemPrompt: string;
-    prompt: string;
-}
-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;
-}): Promise<OpenAiRemoteCompactionResponse>;
-export declare function requestRemoteCompaction(endpoint: string, request: RemoteCompactionRequest, signal?: AbortSignal, opts?: {
-    fetch?: FetchImpl;
-    timeoutMs?: number;
-}): Promise<RemoteCompactionResponse>;

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

@@ -1,105 +0,0 @@
-/**
- * Tool output pruning utilities for compaction.
- */
-import type { SessionEntry } from "./entries";
-import { type ProtectedToolMatcher } from "./tool-protection";
-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

@@ -1,92 +0,0 @@
-/**
- * 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";
-import { type ProtectedToolMatcher } from "./tool-protection";
-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. */
-export declare const AGGRESSIVE_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

@@ -1,17 +0,0 @@
-import type { ToolResultMessage } from "jeopi-ai";
-import type { AgentToolCall } from "../types";
-import type { SessionEntry } from "./entries";
-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;
-export declare function isProtectedToolResult(toolResult: ToolResultMessage, toolCall: AgentToolCall | undefined, matchers: readonly ProtectedToolMatcher[]): boolean;

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

@@ -1,58 +0,0 @@
-/**
- * Shared utilities for compaction and branch summarization.
- */
-import type { Message } from "jeopi-ai";
-import { type Dialect } from "jeopi-ai/dialect";
-import type { AgentMessage } from "../types";
-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 to text for summarization.
- * This prevents the model from treating it as a conversation to continue.
- * 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";

package/dist/types/index.d.ts

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

package/dist/types/proxy.d.ts

@@ -1,85 +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 Model, type SimpleStreamOptions, type StopReason } from "jeopi-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: "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;
-    /** 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 "jeopi-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[];