@vib-rato/agent-core 0.16.0

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

@@ -0,0 +1,26 @@
+/**
+ * Compaction error types.
+ *
+ * `CompactionCancelledError` is the canonical signal raised when a compaction
+ * is explicitly aborted — operator Esc, extension hook returning `cancel`,
+ * programmatic `session.abortCompaction()` call, or any other deliberate
+ * abort source. Downstream callers (e.g. `executeCompaction`) discriminate
+ * cancellation from other failures via `instanceof CompactionCancelledError`
+ * rather than introspecting error messages or `name` fields — the typed
+ * sentinel makes classification source-agnostic and refactor-stable.
+ */
+export declare class CompactionCancelledError extends Error {
+    readonly name: "CompactionCancelledError";
+    constructor(message?: string);
+}
+/**
+ * Outcome of a compaction attempt, surfaced by `CommandController.executeCompaction`
+ * so callers (e.g. the plan-mode approval flow) can distinguish a deliberate abort
+ * from an unrelated failure.
+ *
+ *   "ok"        — compaction completed; transcript was summarized.
+ *   "cancelled" — `CompactionCancelledError` was raised. Operator Esc, extension
+ *                 hook, programmatic abort — all source-agnostic.
+ *   "failed"    — any other rejection from `session.compact()`.
+ */
+export type CompactionOutcome = "ok" | "cancelled" | "failed";

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

@@ -0,0 +1,12 @@
+/**
+ * Compaction and summarization utilities.
+ */
+export * from "./adaptive";
+export * from "./branch-summarization";
+export * from "./compaction";
+export * from "./entries";
+export * from "./errors";
+export * from "./messages";
+export * from "./openai";
+export * from "./pruning";
+export * from "./utils";

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

@@ -0,0 +1,61 @@
+import type { ImageContent, Message, MessageAttribution, ProviderPayload, TextContent } from "@vib-rato/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;
+    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): CompactionSummaryMessage;
+export declare function createCustomMessage(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details: unknown | undefined, timestamp: string, attribution?: MessageAttribution): CustomMessage;
+/**
+ * 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[];
+export declare const convertToLlm: typeof defaultConvertToLlm;

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

@@ -0,0 +1,65 @@
+/**
+ * Remote compaction utilities.
+ *
+ * Provider-side conversation summarization endpoints. Two flavors:
+ *
+ * - **OpenAI remote compaction** (`/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 { Message, Model } from "@vib-rato/ai/types";
+export declare const OPENAI_REMOTE_COMPACTION_PRESERVE_KEY = "openaiRemoteCompaction";
+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;
+/** Test seam: the compaction endpoint as resolved from trusted env. */
+export declare function resolveOpenAiCompactEndpointForTest(model: Model, authCredentialType?: "api_key" | "oauth"): string;
+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;
+export declare function estimateOpenAiCompactInputTokens(input: Array<Record<string, unknown>>, instructions: string): number;
+export declare function trimOpenAiCompactInput(input: Array<Record<string, unknown>>, contextWindow: number, instructions: string): Array<Record<string, unknown>>;
+export declare function resolveOpenAiCompactInputBudget(contextWindow: number, maxOutputTokens?: number): number;
+/**
+ * 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, options?: {
+    authCredentialType?: "api_key" | "oauth";
+}): Promise<OpenAiRemoteCompactionResponse>;
+export declare function requestRemoteCompaction(endpoint: string, request: RemoteCompactionRequest, signal?: AbortSignal): Promise<RemoteCompactionResponse>;

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

@@ -0,0 +1,130 @@
+/**
+ * Tool output pruning utilities for compaction.
+ *
+ * Candidate selection is staleness-aware: tool results that have been
+ * superseded by a later result for the same target (same file read again,
+ * same search re-run) or invalidated by a later successful edit/write to a
+ * covered file are pruned in preference to merely-old results. Protect-window
+ * and minimum-savings hysteresis semantics are unchanged.
+ */
+import type { ToolCall, ToolResultMessage } from "@vib-rato/ai";
+import type { SessionEntry, SessionMessageEntry } from "./entries";
+export interface PruneConfig {
+    /** Keep the most recent tool output tokens intact. */
+    protectTokens: number;
+    /** Only prune if total savings meets this threshold. */
+    minimumSavings: number;
+    /** Tool names that should never be pruned. */
+    protectedTools: string[];
+    /** Number of newest user turns whose tool outputs must remain intact. Defaults to 2. */
+    protectRecentTurns?: number;
+    /**
+     * Tools in `protectedTools` whose protection is waived once the result is
+     * superseded (a later result for the same target, or a later successful
+     * edit/write to the covered file). The most recent result per target is
+     * never considered superseded. Optional; defaults to none.
+     */
+    staleOverridableTools?: string[];
+}
+export declare const DEFAULT_PRUNE_CONFIG: PruneConfig;
+export interface ToolOutputPruneDigest {
+    entryId: string;
+    sha256: string;
+    bytes: number;
+}
+export interface ToolOutputPruneReplacement {
+    entryId: string;
+    replacementText: string;
+    /** Text-only results are the only entries safe to evict to an artifact. */
+    complete: boolean;
+    tokens: number;
+}
+export interface ToolOutputPrunePlan {
+    prunedCount: number;
+    tokensSaved: number;
+    /** Digest-only identity records; no original output text is retained. */
+    digests: readonly ToolOutputPruneDigest[];
+    /** Immutable replacement proposals keyed by entry id. */
+    replacements: readonly ToolOutputPruneReplacement[];
+}
+export interface ToolOutputPruneEvictionHandle {
+    v: 1;
+    artifactId: string;
+    uri: string;
+    encoding: "utf-8";
+    bytes: number;
+    sha256: string;
+    complete: true;
+}
+export interface ToolOutputPruneCommitReplacement {
+    replacementText?: string;
+    eviction?: ToolOutputPruneEvictionHandle;
+}
+export interface ToolOutputPruneCommitOptions {
+    replacements?: ReadonlyMap<string, ToolOutputPruneCommitReplacement>;
+}
+export type ToolOutputCommitOutcome = {
+    entryId: string;
+    outcome: "committed";
+} | {
+    entryId: string;
+    outcome: "mismatch";
+    diagnostic: string;
+} | {
+    entryId: string;
+    outcome: "unavailable";
+    diagnostic: string;
+};
+export declare function extractToolOutputText(message: ToolResultMessage): {
+    text: string;
+    complete: boolean;
+};
+export declare function createPrunedNotice(tokens: number, message?: ToolResultMessage, call?: ToolCall, artifact?: string): string;
+export interface AssistantArgumentPruneResult {
+    argumentPrunedCount: number;
+    argumentTokensSaved: number;
+    /**
+     * The mutated assistant message entries. Callers whose entry source returns
+     * materialized copies must write these back into their canonical store by id.
+     */
+    prunedEntries: SessionMessageEntry[];
+}
+export declare function pruneAssistantToolArguments(entries: SessionEntry[], config?: PruneConfig): AssistantArgumentPruneResult;
+/**
+ * Estimate conservative savings for a digest-only prune plan without mutating
+ * entries or invoking artifact publication.
+ */
+export declare function estimateToolOutputPruneSavings(entries: SessionEntry[], config?: PruneConfig, options?: PruneToolOutputsOptions): {
+    prunableCount: number;
+    tokensSaved: number;
+};
+/**
+ * Evidence gate for below-threshold maintenance pruning (Finding 13). Pruning
+ * forces a prompt-cache-epoch reset, so it only runs when opted in AND the
+ * estimated stale savings clear a high minimum AND exceed the one-time reset
+ * cost (so the reclaim pays the reset back). Default-off/blocked until live
+ * evidence justifies enabling.
+ */
+export declare function shouldRunMaintenancePrune(args: {
+    enabled: boolean;
+    estimatedSavings: number;
+    minSavings: number;
+    cacheEpochResetCost: number;
+}): boolean;
+export interface PruneToolOutputsOptions {
+    /** Lower the usual minimum only when the caller is already over its compaction threshold. */
+    relaxedMinimum?: number;
+    /** Conservative maximum ASCII length of every planned artifact reference. */
+    artifactRefMaxChars?: number;
+}
+/**
+ * Build a digest-only pruning plan. This function is deliberately read-only:
+ * candidates are inspected in private locals and the returned plan never keeps
+ * references to the source entries or their original output text.
+ */
+export declare function planToolOutputPrune(entries: SessionEntry[], config?: PruneConfig, options?: PruneToolOutputsOptions): ToolOutputPrunePlan;
+/**
+ * Re-check and commit a digest-only plan against the supplied live entries.
+ * Each entry is mutated only after its canonical full-text digest matches.
+ */
+export declare function commitToolOutputPrune(entries: SessionEntry[], plan: ToolOutputPrunePlan, options?: ToolOutputPruneCommitOptions): ToolOutputCommitOutcome[];

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

@@ -0,0 +1,32 @@
+/**
+ * Shared utilities for compaction and branch summarization.
+ */
+import type { Message } from "@vib-rato/ai";
+import type { AgentMessage } from "../types";
+export interface FileOperations {
+    read: Set<string>;
+    written: Set<string>;
+    edited: Set<string>;
+}
+export declare function createFileOps(): FileOperations;
+/**
+ * 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[]): string;
+export declare function upsertFileOperations(summary: string, readFiles: string[], modifiedFiles: 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[]): string;
+export declare const SUMMARIZATION_SYSTEM_PROMPT: string;

package/dist/types/compaction.d.ts

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

package/dist/types/harmony-leak.d.ts

@@ -0,0 +1,100 @@
+/**
+ * GPT-5 Harmony-header leakage detection and recovery.
+ *
+ * Background and policy: see `docs/ERRATA-GPT5-HARMONY.md`. This module
+ * implements §3 of that document: detection by signal fusion, plus a
+ * truncate-and-resume primitive for the `edit` tool when its input is in
+ * hashline DSL form. Other tools and surfaces fall through to
+ * abort-and-retry handled by the agent loop.
+ */
+import type { AssistantMessage, Model } from "@vib-rato/ai";
+declare const SIGNAL_ORDER: readonly ["M", "C", "G", "S", "B", "R", "T"];
+export type HarmonySignalClass = "H" | "I" | (typeof SIGNAL_ORDER)[number];
+export type HarmonySurface = "assistant_text" | "assistant_thinking" | "tool_arg";
+export interface HarmonySignal {
+    classes: HarmonySignalClass[];
+    start: number;
+    end: number;
+    text: string;
+}
+export interface HarmonyDetection {
+    surface: HarmonySurface;
+    contentIndex?: number;
+    toolName?: string;
+    toolCallId?: string;
+    signals: HarmonySignal[];
+}
+export interface HarmonyAuditEvent {
+    action: "truncate_resume" | "abort_retry" | "escalated";
+    surface: HarmonySurface;
+    signal: string;
+    retryN: number;
+    model: string;
+    provider: string;
+    toolName?: string;
+    removedLen: number;
+    removedSha8: string;
+    removedPreview: string;
+    removedBlob?: string;
+}
+export interface HarmonyRecoveredToolCall {
+    message: AssistantMessage;
+    removed: string;
+}
+/**
+ * Whether to run leak detection on responses from this model. We default-on
+ * for every OpenAI code provider model rather than enumerating ids, so a future
+ * gpt-5.6 (or whatever) doesn't silently bypass the mitigation. Detection
+ * itself is cheap; the cost of missing a leak on a new model is not.
+ */
+export declare function isHarmonyLeakMitigationTarget(model: Model): boolean;
+export declare function shouldMitigateHarmonyLeak(model: Model, detection: HarmonyDetection): boolean;
+export declare function signalListLabel(signals: readonly HarmonySignal[]): string;
+/**
+ * Detect harmony-protocol leakage in `text`. Returns undefined if clean.
+ *
+ * Trip rule: `H` alone, or `M` paired with at least one co-signal
+ * (`C`/`G`/`S`/`B`/`R`/`T`). Bare `M` does not trip — this document, its
+ * tests, and bug reports legitimately carry the marker.
+ *
+ * `parsedEnd`, when supplied, marks the byte at which a structurally valid
+ * tool-argument parse ends; markers strictly after it set the `T` co-signal.
+ * `contentIndex`/`toolName`/`toolCallId` flow through to the returned
+ * detection for downstream auditing.
+ */
+export declare function detectHarmonyLeak(text: string, surface: HarmonySurface, options?: {
+    parsedEnd?: number;
+    contentIndex?: number;
+    toolName?: string;
+    toolCallId?: string;
+}): HarmonyDetection | undefined;
+/** Scan an assistant message's content blocks; return the first detection. */
+export declare function detectHarmonyLeakInAssistantMessage(message: AssistantMessage): HarmonyDetection | undefined;
+/**
+ * Truncate a contaminated tool call at the start of the contaminated line and
+ * append the tool's recovery sentinel. Returns a recovered AssistantMessage
+ * (containing only the cleaned tool call), a synthetic continuation user
+ * message asking the model to re-issue the rest, and the removed substring
+ * for auditing. Returns undefined when the tool is not recovery-eligible or
+ * the truncation would leave nothing meaningful to dispatch.
+ *
+ * `providerPayload` is dropped from the recovered message: for OpenAI code backend the
+ * encrypted reasoning blob is opaque/signed and we cannot validate that it is
+ * uncontaminated. The model re-reasons on the next turn.
+ */
+export declare function recoverHarmonyToolCall(message: AssistantMessage, detection: HarmonyDetection): HarmonyRecoveredToolCall | undefined;
+/**
+ * Return the contaminated substring from `message` for audit purposes when
+ * recovery is not applicable (abort path). Walks from the first detected
+ * signal to end-of-content within the relevant block. Returns "" if the
+ * detection cannot be resolved against the message.
+ */
+export declare function extractHarmonyRemoved(message: AssistantMessage, detection: HarmonyDetection): string;
+export declare function createHarmonyAuditEvent(params: {
+    action: HarmonyAuditEvent["action"];
+    detection: HarmonyDetection;
+    model: Model;
+    retryN: number;
+    removed: string;
+}): HarmonyAuditEvent;
+export {};

package/dist/types/heap-eviction-retainers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/image-placeholder-guard.d.ts

@@ -0,0 +1,4 @@
+import type { ImageContent, TextContent } from "@vib-rato/ai";
+export declare const IMAGE_PLACEHOLDER_ATTACHMENT_GUIDANCE = "Image placeholder text was submitted without an image payload. Paste the image with #paste-image, attach it with @path/to/image.png, or save the image and provide the saved file path.";
+export declare function isImagePlaceholderOnlyText(text: string): boolean;
+export declare function assertImagePlaceholdersHavePayload(text: string, content: readonly (TextContent | ImageContent)[] | undefined): void;

package/dist/types/index.d.ts

@@ -0,0 +1,13 @@
+export * from "./agent";
+export * from "./agent-loop";
+export * from "./append-only-context";
+export * from "./compaction";
+export * from "./harmony-leak";
+export * from "./image-placeholder-guard";
+export * from "./proxy";
+export * from "./run-collector";
+export * from "./run-resource-ledger";
+export * from "./telemetry";
+export * from "./thinking";
+export * from "./tool-dispatch-identity";
+export * from "./types";

package/dist/types/proxy.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Proxy stream function for apps that route LLM calls through a server.
+ * The server manages auth and proxies requests to LLM providers.
+ */
+import { type AssistantMessage, type AssistantMessageEvent, type Context, EventStream, type Model, type SimpleStreamOptions, type StopReason } from "@vib-rato/ai";
+declare class ProxyMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
+    constructor();
+}
+/**
+ * Proxy event types - server sends these with partial field stripped to reduce bandwidth.
+ */
+export type ProxyAssistantMessageEvent = {
+    type: "start";
+} | {
+    type: "text_start";
+    contentIndex: number;
+} | {
+    type: "text_delta";
+    contentIndex: number;
+    delta: string;
+} | {
+    type: "text_end";
+    contentIndex: number;
+    contentSignature?: string;
+} | {
+    type: "thinking_start";
+    contentIndex: number;
+} | {
+    type: "thinking_delta";
+    contentIndex: number;
+    delta: string;
+} | {
+    type: "thinking_end";
+    contentIndex: number;
+    contentSignature?: string;
+} | {
+    type: "reasoning_summary_start";
+    contentIndex: number;
+} | {
+    type: "reasoning_summary_delta";
+    contentIndex: number;
+    delta: string;
+} | {
+    type: "reasoning_summary_end";
+    contentIndex: number;
+    content?: string;
+} | {
+    type: "toolcall_start";
+    contentIndex: number;
+    id: string;
+    toolName: string;
+} | {
+    type: "toolcall_delta";
+    contentIndex: number;
+    delta: string;
+} | {
+    type: "toolcall_end";
+    contentIndex: number;
+} | {
+    type: "done";
+    reason: Extract<StopReason, "stop" | "length" | "toolUse">;
+    usage: AssistantMessage["usage"];
+} | {
+    type: "error";
+    reason: Extract<StopReason, "aborted" | "error">;
+    errorMessage?: string;
+    usage: AssistantMessage["usage"];
+};
+export interface ProxyStreamOptions extends SimpleStreamOptions {
+    /** Auth token for the proxy server */
+    authToken: string;
+    /** Proxy server URL (e.g., "https://genai.example.com") */
+    proxyUrl: string;
+}
+/**
+ * Stream function that proxies through a server instead of calling LLM providers directly.
+ * The server strips the partial field from delta events to reduce bandwidth.
+ * We reconstruct the partial message client-side.
+ *
+ * Use this as the `streamFn` option when creating an Agent that needs to go through a proxy.
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   streamFn: (model, context, options) =>
+ *     streamProxy(model, context, {
+ *       ...options,
+ *       authToken: await getAuthToken(),
+ *       proxyUrl: "https://genai.example.com",
+ *     }),
+ * });
+ * ```
+ */
+export declare function streamProxy(model: Model, context: Context, options: ProxyStreamOptions): ProxyMessageEventStream;
+export {};