@pensar/apex 2.5.0 → 2.6.1-canary.025b1ecf

package/build/lib/core/ai/ai.d.ts

@@ -0,0 +1,342 @@
+import type { AnthropicMessagesModelId } from "@ai-sdk/anthropic/internal";
+import type { OpenAIResponsesProviderOptions } from "@ai-sdk/openai";
+import type { OpenAIChatModelId } from "@ai-sdk/openai/internal";
+import { type LanguageModelMiddleware, type ModelMessage, type StopCondition, type StreamTextOnFinishCallback, type StreamTextOnStepFinishCallback, type StreamTextResult, type ToolChoice, type ToolSet } from "ai";
+import type { z } from "zod";
+import { type CustomProviders } from "../config/customProviders";
+import { type HoonifyModel } from "../hoonify";
+import { type AiTelemetryOperation } from "../observability";
+import type { RunContextRecorder } from "../runtime/runContext";
+import { type CompactionLink, type CompactionTrigger } from "./compactionTelemetry";
+import { type InferenceRecorder } from "./inference-attempt";
+import { type ClaudeThinkingEffort } from "./models";
+import { type AIAuthConfig } from "./utils";
+/**
+ * Whether tool-call repair must fail closed (no argument synthesis) for a tool.
+ * Exported for regression tests covering the repaired-invalid-call path.
+ */
+export declare function isRepairFailClosedTool(toolName: string): boolean;
+export type AIModel = AnthropicMessagesModelId | OpenAIChatModelId | string;
+export type OpenAIReasoningEffort = "none" | "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
+export declare const DEFAULT_OPENAI_REASONING_EFFORT: OpenAIReasoningEffort;
+/**
+ * Anthropic adaptive-thinking effort hint. Soft guidance for how much the model
+ * reasons (see AWS "adaptive thinking"): `low` minimizes thinking while
+ * `xhigh` and `max` allow progressively deeper work. Only meaningful for
+ * models that support adaptive thinking; ignored elsewhere.
+ */
+export type ThinkingEffort = ClaudeThinkingEffort;
+/** Per-step billing context attached to a usage report, attributing cost to a specific `(sessionId, stepSeq)`. */
+export interface UsageStepContext {
+    sessionId?: string;
+    stepSeq?: number;
+}
+/**
+ * Context attached to every usage report. The cache counters are always
+ * present — zero when the provider supplies none — and are already included
+ * in `inputTokens`:
+ * `uncachedInputTokens = inputTokens - cacheReadTokens - cacheWriteTokens`.
+ */
+export interface UsageCallbackContext extends UsageStepContext {
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+/** Callback for reporting token usage from AI operations. */
+export type UsageCallback = (modelId: string, inputTokens: number, outputTokens: number, context: UsageCallbackContext) => void | Promise<void>;
+/**
+ * Per-run usage recorder threaded through {@link StreamResponseOpts}. When set
+ * it replaces the ALS run sink and the ambient {@link onUsage} callback for
+ * that call. Async work is awaited before the next model step. Receives the
+ * same cache-aware {@link UsageCallbackContext} as the global callback, so
+ * the cached/uncached split travels on the usage event itself.
+ */
+export type UsageRecorder = (model: string, inputTokens: number, outputTokens: number, context?: UsageCallbackContext) => void | Promise<void>;
+/** Ambient default usage sink when no run-context sink is set. */
+export declare function onUsage(cb: UsageCallback | null): void;
+/** Normalized per-step usage: input/output plus cache buckets, provider-agnostic. */
+export interface NormalizedStepUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+/**
+ * Extract normalized usage from one completed model step. A single function
+ * feeds both `onCacheMetrics` and the usage callback so provider metadata is
+ * never parsed twice. Anthropic's `providerMetadata.anthropic` wins; the
+ * SDK's normalized `usage.inputTokenDetails` is the fallback (Pensar
+ * provider). Input stays inclusive of cached tokens.
+ */
+export declare function normalizeStepUsage(step: {
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        inputTokenDetails?: {
+            cacheReadTokens?: number;
+            cacheWriteTokens?: number;
+        };
+    };
+    providerMetadata?: unknown;
+}): NormalizedStepUsage;
+/** Runs `fn` in a per-run step-counting context; `streamResponse` steps inside it report usage tagged with `sessionId` and an increasing `stepSeq` starting at `seedStepSeq`. */
+export declare function runWithStepContext<T>(opts: {
+    sessionId?: string;
+    seedStepSeq?: number;
+    usageSink?: UsageCallback;
+}, fn: () => T): T;
+/** Takes and advances the next `stepSeq` for the current run; returns `undefined` outside any run context. */
+export declare function takeStepContext(): UsageStepContext | undefined;
+export type AIModelProvider = "custom" | "anthropic" | "openai" | "google" | "openrouter" | "concentrate" | "bedrock" | "bedrock-mantle" | "pensar" | "inception" | "hoonify" | "local";
+/** Conservative default when `getModelInfo` doesn't have a `contextLength`. */
+export declare function getContextWindow(modelId: string, customProviders?: CustomProviders, hoonifyModels?: HoonifyModel[]): number;
+declare const SEQUENTIAL_TOOL_CALL_INSTRUCTION: string;
+declare function applySequentialToolCallPolicy(system: string | undefined, tools: ToolSet | undefined, model: AIModel): string | undefined;
+export declare function withResponseToolActive(tools: ToolSet | undefined, activeTools: string[] | undefined): string[] | undefined;
+/**
+ * Resolve the effective toolset from `activeTools` before any context
+ * fitting. The AI SDK treats `activeTools` as advertise-only — it still
+ * parses, executes, and enumerates every tool in the full map — so the
+ * executable map itself must be filtered here for budgeting, provider
+ * exposure, execution, and repair to agree. Built with DefineOwnProperty
+ * semantics so prototype-shaped names like `__proto__` survive as own keys.
+ * Feed it `withResponseToolActive(tools, activeTools)` so the injected
+ * structured-output tool survives the filter.
+ */
+export declare function resolveEffectiveTools(tools: ToolSet | undefined, activeTools: string[] | undefined): Pick<StreamResponseOpts, "tools" | "activeTools">;
+export declare function restrictToolsToActive(tools: ToolSet | undefined, activeTools: string[] | undefined): ToolSet | undefined;
+export declare function recordContextRestart(depth: number, opts?: Pick<StreamResponseOpts, "inferenceRecorder">): Promise<void>;
+declare function getStreamIdleTimeoutMs(model: AIModel): number;
+declare class StreamIdleTimeoutError extends Error {
+    constructor(idleMs: number);
+}
+/**
+ * Wraps an async iterable with a per-chunk idle timeout. If no chunk arrives
+ * within `idleMs`, throws a {@link StreamIdleTimeoutError} so the caller can
+ * resume the conversation from accumulated messages.
+ *
+ * @param isIdleTimerActive Optional predicate evaluated before awaiting each
+ *   chunk. When it returns `false` the timer is skipped for that chunk and we
+ *   wait indefinitely. This lets callers suppress the timeout during expected
+ *   long pauses (e.g. while a tool call is executing) so a slow tool isn't
+ *   misread as a stalled provider stream.
+ */
+declare function withIdleTimeout<T>(stream: AsyncIterable<T>, idleMs: number, isIdleTimerActive?: () => boolean): AsyncGenerator<T>;
+declare function createToolExecutionGate(): {
+    shouldEnforceIdleTimeout: () => boolean;
+    observe: (chunk: {
+        type: string;
+        toolCallId?: string;
+        toolName?: string;
+    }) => void;
+};
+export interface ModelInfo {
+    id: AIModel;
+    name: string;
+    provider: AIModelProvider;
+    contextLength?: number;
+}
+export declare function modelRequiresThinking(modelId: string): boolean;
+/**
+ * Check whether a model supports extended thinking based on its ID.
+ *
+ * Thinking is available on Claude 3.7 Sonnet and all Claude 4.x+ models
+ * (Sonnet, Opus, Haiku 4.5). Works for Anthropic direct, Bedrock, and
+ * Pensar provider IDs.
+ */
+export declare function modelSupportsThinking(modelId: string): boolean;
+/**
+ * Whether a model accepts the `adaptive` thinking type — Claude Opus 4.6+ and
+ * Sonnet 4.6+. Pre-4.6 models (Opus 4.0–4.5, Sonnet 4.5, Haiku 4.5) support
+ * extended thinking but reject `adaptive`, so we don't request thinking for
+ * them at all.
+ */
+export declare function modelSupportsAdaptiveThinking(modelId: string): boolean;
+export declare function modelSupportsOpenAIReasoning(modelId: string): boolean;
+export declare function modelRequiresReasoning(modelId: string): boolean;
+export declare function getOpenAIReasoningEfforts(modelId: string): OpenAIReasoningEffort[];
+export declare function normalizeOpenAIReasoningEffort(modelId: string, effort?: OpenAIReasoningEffort | null): OpenAIReasoningEffort | undefined;
+/**
+ * Provider-specific options passed to `streamText` to request reasoning /
+ * extended thinking. Each provider reads only its own namespace:
+ *   - `anthropic.thinking` — direct Anthropic provider AND the Pensar gateway
+ *     (the gateway formatter maps it to the Bedrock `thinking` field).
+ *   - `bedrock.reasoningConfig` — the AWS Bedrock provider; it ignores the
+ *     `anthropic` namespace entirely, so Anthropic-on-Bedrock thinking is only
+ *     requested when this key is present. `display: 'summarized'` makes the
+ *     model actually return reasoning text (adaptive can otherwise omit it).
+ *   - `openai.reasoningEffort` — OpenAI/o-series reasoning models.
+ */
+export type ReasoningProviderOptions = {
+    openrouter?: {
+        reasoning: {
+            effort: OpenAIReasoningEffort;
+            enabled?: boolean;
+        };
+    };
+    anthropic?: {
+        thinking: {
+            type: "adaptive";
+            display?: "summarized";
+        } | {
+            type: "disabled";
+        };
+        effort?: ThinkingEffort;
+    };
+    bedrock?: {
+        reasoningConfig: {
+            type: "adaptive";
+            display: "summarized";
+            maxReasoningEffort?: ThinkingEffort;
+        } | {
+            type: "disabled";
+        };
+        /** Explicitly forwarded for Anthropic because the Bedrock SDK currently
+         * drops reasoningConfig.type="disabled" instead of sending it. */
+        additionalModelRequestFields?: {
+            thinking: {
+                type: "disabled";
+            };
+        };
+    };
+    openai?: OpenAIResponsesProviderOptions;
+};
+export type OpenRouterProviderOptions = {
+    openrouter?: {
+        provider: {
+            only: ["z-ai"];
+            allow_fallbacks: false;
+        } | {
+            order: ["z-ai"];
+            allow_fallbacks: true;
+            require_parameters: true;
+        };
+    };
+};
+export declare function buildOpenRouterProviderOptions(model: AIModel): OpenRouterProviderOptions | undefined;
+/**
+ * Z.AI's endpoint is the only `z-ai/*` provider that does not advertise
+ * `structured_outputs`, so under the hard pin above `response_format` is a soft
+ * preference and nothing enforces the schema. Prefer Z.AI, but require an
+ * endpoint that enforces it rather than silently returning unparseable output.
+ */
+export declare function buildOpenRouterStructuredProviderOptions(model: AIModel): OpenRouterProviderOptions | undefined;
+/**
+ * Build the `providerOptions` for a request based on the model and reasoning
+ * settings. Returns `undefined` when no reasoning/thinking is requested.
+ *
+ * When thinking is enabled for an Anthropic-family model we set BOTH the
+ * `anthropic` and `bedrock` keys: the resolved provider (direct Anthropic,
+ * Pensar gateway, or Bedrock) reads only its own namespace and ignores the
+ * other, so this is safe across all three and avoids brittle provider
+ * branching here.
+ */
+export declare function buildReasoningProviderOptions(model: AIModel, opts: {
+    enableThinking?: boolean;
+    /**
+     * Adaptive-thinking effort hint for Anthropic models that support it
+     * Ignored on models without adaptive support. When omitted, models in the
+     * Claude capability registry use their documented provider default.
+     */
+    thinkingEffort?: ThinkingEffort | null;
+    openAIReasoningEffort?: OpenAIReasoningEffort | null;
+}): ReasoningProviderOptions | undefined;
+/** Cache token metrics extracted from Anthropic providerMetadata */
+export interface CacheMetrics {
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+}
+export interface StreamResponseOpts {
+    prompt: string;
+    system?: string;
+    model: AIModel;
+    messages?: Array<ModelMessage>;
+    stopWhen?: StopCondition<NoInfer<ToolSet>> | StopCondition<NoInfer<ToolSet>>[];
+    toolChoice?: ToolChoice<ToolSet>;
+    tools?: ToolSet;
+    onStepFinish?: StreamTextOnStepFinishCallback<ToolSet>;
+    /** Provider middleware applied only to this stream's model calls. */
+    languageModelMiddleware?: LanguageModelMiddleware | LanguageModelMiddleware[];
+    /** Explicit undefined clears an inherited recorder for an unrecorded child. */
+    inferenceRecorder?: InferenceRecorder;
+    /** Per-run usage recorder; when set it replaces the global usage callback for this stream. */
+    usageRecorder?: UsageRecorder;
+    abortSignal?: AbortSignal;
+    activeTools?: string[];
+    silent?: boolean;
+    authConfig?: AIAuthConfig;
+    onFinish?: StreamTextOnFinishCallback<ToolSet>;
+    /**
+     * Called when the context window overflows and the conversation is
+     * summarized. Callers should use this to discard stale message history
+     * so that subsequent persistence writes only include the summary +
+     * new messages (not the full pre-summarization history).
+     */
+    onSummarized?: (summary: string) => void;
+    /**
+     * Deprecated host shim: fires only when a cache counter is `> 0`.
+     * Apex internals read cache from {@link normalizeStepUsage} on the step.
+     */
+    onCacheMetrics?: (metrics: CacheMetrics) => void;
+    /** Enable extended thinking for supported models (Anthropic Claude 3.7+) */
+    enableThinking?: boolean;
+    /**
+     * Adaptive-thinking effort hint for Anthropic models that support it
+     * (Opus/Sonnet 4.6+). Ignored where unsupported; model defaults to `high`.
+     */
+    thinkingEffort?: ThinkingEffort | null;
+    /** OpenAI reasoning effort for GPT/o-series reasoning models. */
+    openAIReasoningEffort?: OpenAIReasoningEffort | null;
+    /** Session root path — used by context management layers to persist truncated tool results */
+    sessionPath?: string;
+    /** Session id (`ses_…`) of the agent making this call; stamped onto AI-span telemetry so traces are filterable by session. */
+    sessionId?: string;
+    /**
+     * Opt-in durable context authority for recorded runs. Turn-0 base and each
+     * step's cumulative context are checkpointed before selection/dispatch;
+     * unset → legacy behavior, no persistence.
+     */
+    contextRecorder?: RunContextRecorder;
+    /**
+     * Internal: recovery-recursion depth. Bumped at each summarize → resume
+     * boundary; throws `ContextLengthExhaustedError` past `MAX_RESTART_DEPTH`.
+     */
+    _restartDepth?: number;
+    /** Shared only by continuations of this stream, never across agents. */
+    _compaction?: {
+        last?: CompactionLink;
+    };
+    _compactionTrigger?: CompactionTrigger;
+}
+export declare function streamResponse(opts: StreamResponseOpts): StreamTextResult<ToolSet, never>;
+export interface GenerateObjectOpts<T extends z.ZodType> {
+    model: AIModel;
+    schema: T;
+    prompt: string;
+    system?: string;
+    maxTokens?: number;
+    temperature?: number;
+    openAIReasoningEffort?: OpenAIReasoningEffort | null;
+    authConfig?: AIAuthConfig;
+    abortSignal?: AbortSignal;
+    onTokenUsage?: (inputTokens: number, outputTokens: number) => void;
+    /** Provider middleware applied only to this call's model. */
+    languageModelMiddleware?: LanguageModelMiddleware | LanguageModelMiddleware[];
+    /** Explicit undefined clears an inherited recorder for an unrecorded child. */
+    inferenceRecorder?: InferenceRecorder;
+    /** Per-run usage recorder; when set it replaces the global usage callback. */
+    usageRecorder?: UsageRecorder;
+    /** Session id (`ses_…`) of the caller — stamped onto AI-span telemetry. */
+    sessionId?: string;
+    /** Stable operation id; defaults to `apex.structured.generate`. */
+    operation?: AiTelemetryOperation;
+}
+export declare function generateObjectResponse<T extends z.ZodType>(opts: GenerateObjectOpts<T>): Promise<z.infer<T>>;
+/**
+ * Terminal: all recovery paths exhausted. The only context-length error
+ * allowed to escape `streamResponse` — others are recoverable by design.
+ */
+export declare class ContextLengthExhaustedError extends Error {
+    readonly restartDepth: number;
+    constructor(message: string, restartDepth: number);
+}
+export { applySequentialToolCallPolicy, createToolExecutionGate, getStreamIdleTimeoutMs, SEQUENTIAL_TOOL_CALL_INSTRUCTION, StreamIdleTimeoutError, withIdleTimeout, };

package/build/lib/core/ai/ai.js

@@ -0,0 +1,68 @@
+import {
+  isRepairFailClosedTool2,
+  DEFAULT_OPENAI_REASONING_EFFORT2,
+  onUsage2,
+  normalizeStepUsage2,
+  runWithStepContext2,
+  takeStepContext2,
+  getContextWindow2,
+  SEQUENTIAL_TOOL_CALL_INSTRUCTION2,
+  applySequentialToolCallPolicy2,
+  withResponseToolActive2,
+  resolveEffectiveTools2,
+  restrictToolsToActive2,
+  recordContextRestart2,
+  getStreamIdleTimeoutMs2,
+  StreamIdleTimeoutError2,
+  withIdleTimeout2,
+  createToolExecutionGate2,
+  modelRequiresThinking2,
+  modelSupportsThinking2,
+  modelSupportsAdaptiveThinking2,
+  modelSupportsOpenAIReasoning2,
+  modelRequiresReasoning2,
+  getOpenAIReasoningEfforts2,
+  normalizeOpenAIReasoningEffort2,
+  buildOpenRouterProviderOptions2,
+  buildOpenRouterStructuredProviderOptions2,
+  buildReasoningProviderOptions2,
+  streamResponse2,
+  generateObjectResponse2,
+  ContextLengthExhaustedError2
+} from "../../chunk-sgd2126b.js";
+import"../../chunk-8vhr65w3.js";
+import"../../chunk-2njv7wz3.js";
+import"../../chunk-jdjagvgr.js";
+import"../../chunk-kfvq4m1s.js";
+export {
+  ContextLengthExhaustedError2 as ContextLengthExhaustedError,
+  DEFAULT_OPENAI_REASONING_EFFORT2 as DEFAULT_OPENAI_REASONING_EFFORT,
+  SEQUENTIAL_TOOL_CALL_INSTRUCTION2 as SEQUENTIAL_TOOL_CALL_INSTRUCTION,
+  StreamIdleTimeoutError2 as StreamIdleTimeoutError,
+  applySequentialToolCallPolicy2 as applySequentialToolCallPolicy,
+  buildOpenRouterProviderOptions2 as buildOpenRouterProviderOptions,
+  buildOpenRouterStructuredProviderOptions2 as buildOpenRouterStructuredProviderOptions,
+  buildReasoningProviderOptions2 as buildReasoningProviderOptions,
+  createToolExecutionGate2 as createToolExecutionGate,
+  generateObjectResponse2 as generateObjectResponse,
+  getContextWindow2 as getContextWindow,
+  getOpenAIReasoningEfforts2 as getOpenAIReasoningEfforts,
+  getStreamIdleTimeoutMs2 as getStreamIdleTimeoutMs,
+  isRepairFailClosedTool2 as isRepairFailClosedTool,
+  modelRequiresReasoning2 as modelRequiresReasoning,
+  modelRequiresThinking2 as modelRequiresThinking,
+  modelSupportsAdaptiveThinking2 as modelSupportsAdaptiveThinking,
+  modelSupportsOpenAIReasoning2 as modelSupportsOpenAIReasoning,
+  modelSupportsThinking2 as modelSupportsThinking,
+  normalizeOpenAIReasoningEffort2 as normalizeOpenAIReasoningEffort,
+  normalizeStepUsage2 as normalizeStepUsage,
+  onUsage2 as onUsage,
+  recordContextRestart2 as recordContextRestart,
+  resolveEffectiveTools2 as resolveEffectiveTools,
+  restrictToolsToActive2 as restrictToolsToActive,
+  runWithStepContext2 as runWithStepContext,
+  streamResponse2 as streamResponse,
+  takeStepContext2 as takeStepContext,
+  withIdleTimeout2 as withIdleTimeout,
+  withResponseToolActive2 as withResponseToolActive
+};

package/build/lib/core/ai/caching.d.ts

@@ -0,0 +1,26 @@
+import type { ModelMessage } from "ai";
+import type { AIModel } from "./ai";
+type CacheBreakpoint = NonNullable<ModelMessage["providerOptions"]>;
+/**
+ * Provider options marking a cache breakpoint for `model`, or `undefined` when
+ * the model has no breakpoint we can express.
+ */
+export declare function cacheBreakpointFor(model: AIModel): CacheBreakpoint | undefined;
+/**
+ * Prepend a system message carrying a cache breakpoint to the messages array.
+ * This ensures tools + system prompt are cached on every request.
+ *
+ * The system prompt is placed as a system-role message at the start of
+ * the messages array with providerOptions containing the breakpoint, so the
+ * provider caches the entire prefix (tools + system) and reads it from cache
+ * on subsequent turns (~90% cost reduction).
+ */
+export declare function withCachedSystemPrompt(system: string, messages: ModelMessage[], breakpoint: CacheBreakpoint | undefined): ModelMessage[];
+/**
+ * Add a cache breakpoint to the last message for incremental conversation
+ * caching. On each turn, everything up to (and including) the last message is
+ * read from cache, so only the new content after the breakpoint is billed at
+ * full price.
+ */
+export declare function withCachedLastMessage(messages: ModelMessage[], breakpoint: CacheBreakpoint | undefined): ModelMessage[];
+export {};

package/build/lib/core/ai/compactionEvidence.d.ts

@@ -0,0 +1,15 @@
+export declare const CONTEXT_EVIDENCE_BYTES: number;
+export declare const RESULT_EVIDENCE_BYTES: number;
+export declare const MAX_RESULT_EVIDENCE = 256;
+export type EvidenceStatus = "available" | "truncated" | "unavailable" | "failed";
+export declare function encodeCompactionEvidence(value: unknown, maxBytes: number): {
+    status: "available";
+    json: string;
+    bytes: number;
+    reason?: undefined;
+} | {
+    status: EvidenceStatus;
+    reason: string;
+    bytes: number;
+    json?: undefined;
+};

package/build/lib/core/ai/compactionTelemetry.d.ts

@@ -0,0 +1,55 @@
+import { type Attributes, type Span, type SpanContext } from "@opentelemetry/api";
+export type CompactionLink = SpanContext;
+export type CompactionTrigger = "proactive" | "context_overflow" | "summary_overflow";
+export type CompactionMethod = "fit" | "summarize" | "reset";
+export interface CompactionContext {
+    trigger: CompactionTrigger;
+    model: string;
+    sessionId?: string;
+    restartDepth?: number;
+    previous?: CompactionLink;
+}
+export interface CompactionLayer {
+    method: "truncate" | "snip";
+    threshold: number;
+    tokensBefore: number;
+    tokensAfter: number;
+}
+interface ResultEvidence {
+    method: "truncate" | "snip";
+    toolCallId: string;
+    toolName: string;
+    inputChars: number;
+    outputChars: number;
+    originalChars: number;
+    preservation: "written" | "write_failed" | "referenced_unverified" | "not_persisted";
+    path?: string;
+}
+export declare class CompactionTelemetry {
+    private readonly span;
+    private readonly method;
+    private ended;
+    private readonly results;
+    private readonly layers;
+    private readonly capturePayloads;
+    private readonly resultEvidence;
+    private resultEvidenceFailed;
+    private written;
+    private writeFailed;
+    private captureMs;
+    readonly link: CompactionLink;
+    constructor(span: Span, method: CompactionMethod);
+    private record;
+    attributes(values: Attributes): void;
+    measure(phase: "before" | "after", tokens: () => number, messageCount: number): void;
+    capture(phase: "before" | "after", value: () => unknown): void;
+    private captureValue;
+    persisted(status: "written" | "write_failed"): void;
+    result(key: string, evidence: () => ResultEvidence): void;
+    layer(layer: CompactionLayer): void;
+    finish(outcome: "completed" | "insufficient_reduction", values?: Attributes): void;
+    fail(error: unknown, aborted?: boolean): void;
+    private end;
+}
+export declare function beginCompaction(method: CompactionMethod, context?: CompactionContext): CompactionTelemetry | undefined;
+export {};

package/build/lib/core/ai/contextManagement.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Tiered context compaction. Layer 1 truncates large tool results;
+ * Layer 2 snips old tool results to 1-line summaries; Layer 3
+ * (`summarizeConversation` in utils.ts) is the fallback.
+ * {@link fitMessagesToContext} composes Layer 1+2 against an explicit
+ * token budget so callers can compact proactively, not only on error.
+ */
+import type { ModelMessage, ToolSet } from "ai";
+import { type CompactionContext, type CompactionLink, type CompactionTelemetry } from "./compactionTelemetry";
+/**
+ * Truncate `text` so the returned string fits in **at most** `max` chars,
+ * and append a marker noting how many were dropped. `label` selects the
+ * marker form: omit for the verbose `"…[truncated N chars]"` (used wherever
+ * the recipient might benefit from the byte count), pass a label for
+ * `"…[<label> truncated]"` when the count would be misleading or noisy.
+ *
+ * `max` is a strict upper bound — the marker length is reserved INSIDE
+ * `max`, not appended outside it. Callers (`MAX_TOOL_INPUT_CHARS`,
+ * `MAX_SCHEMA_CHARS`, `MAX_PER_MESSAGE_CHARS`, `SYSTEM_PROMPT_SNIPPET_CHARS`)
+ * treat the cap as a hard ceiling on auxiliary-LLM input size; soft caps
+ * would silently inflate budgets by ~30 chars per call.
+ *
+ * Degenerate `max < marker.length` returns just the marker (still useful
+ * signal vs. a meaningless ≤30-char head slice).
+ */
+export declare function truncateWithMarker(text: string, max: number, label?: string): string;
+/**
+ * Replace large tool results in message history with truncated previews.
+ * Full results are persisted to disk at `{sessionPath}/tool-results/`.
+ *
+ * Returns a new messages array (does not mutate the input).
+ *
+ * `persistedIds`, when passed, deduplicates writes across cascading calls
+ * (e.g. `fitMessagesToContext` invokes this with progressively tighter
+ * thresholds — the original full output only needs to land on disk once).
+ */
+export declare function applyToolResultBudget(messages: ModelMessage[], opts: {
+    sessionPath: string;
+    maxResultChars?: number;
+    persistedIds?: Set<string>;
+    telemetry?: CompactionTelemetry;
+}): ModelMessage[];
+/**
+ * Pull the latest task summary from a `list_tasks` tool result so it can
+ * survive Layer 3 summarization.
+ */
+export declare function extractTaskSummaryFromMessages(messages: ModelMessage[]): string | null;
+/** Conservative ~4 chars/token; `safetyMarginTokens` absorbs drift. */
+export declare function estimateTokens(text: string): number;
+export declare function estimateToolsOverheadTokens(tools?: ToolSet): number;
+/** Walks parts directly to avoid `JSON.stringify` on a large history. */
+export declare function estimateMessageTokens(messages: ModelMessage[]): number;
+export interface FitContextResult {
+    messages: ModelMessage[];
+    /** Token estimate of `messages` (excludes system + overhead). */
+    estimatedInputTokens: number;
+    /** Reference inequality vs. input. */
+    modified: boolean;
+    /** `false` ⇒ caller must escalate to Layer 3 summarization. */
+    fitsBudget: boolean;
+    compaction?: CompactionLink;
+}
+export interface FitContextOpts {
+    contextWindow: number;
+    /** Tokens reserved for the model's response (`max_tokens`). */
+    maxOutputTokens: number;
+    /** Counted toward input; never compacted here. */
+    system?: string;
+    /** Used to size tool-schema overhead. Pass `tools` OR `overheadTokens`. */
+    tools?: ToolSet;
+    /** Explicit override; otherwise derived from `tools` + 1K fmt allowance. */
+    overheadTokens?: number;
+    /** Absorbs chars/4 drift; default 10_000. */
+    safetyMarginTokens?: number;
+    /** Required to enable Layer 1 (results persisted to disk). */
+    sessionPath?: string;
+    telemetry?: CompactionContext;
+}
+/**
+ * Single entry point for proactive AND reactive compaction. Iteratively
+ * tightens thresholds — Layer 1 ∈ {10K, 5K, 2K, 500} chars, then Layer 2
+ * ∈ {6, 3, 1} steps — and short-circuits the moment the estimate fits.
+ * Returns `fitsBudget: false` when the caller must escalate to Layer 3.
+ */
+export declare function fitMessagesToContext(messages: ModelMessage[], opts: FitContextOpts): FitContextResult;

package/build/lib/core/ai/index.d.ts

@@ -0,0 +1,10 @@
+export type { AIModel, AIModelProvider, CacheMetrics, GenerateObjectOpts, ModelInfo, NormalizedStepUsage, OpenAIReasoningEffort, StreamResponseOpts, ThinkingEffort, UsageCallback, UsageCallbackContext, UsageRecorder, UsageStepContext, } from "./ai";
+export { buildReasoningProviderOptions, DEFAULT_OPENAI_REASONING_EFFORT, generateObjectResponse, getContextWindow, getOpenAIReasoningEfforts, modelRequiresReasoning, modelRequiresThinking, modelSupportsAdaptiveThinking, modelSupportsOpenAIReasoning, modelSupportsThinking, normalizeOpenAIReasoningEffort, normalizeStepUsage, onUsage, runWithStepContext, streamResponse, } from "./ai";
+export type { InferenceAttempt, InferenceRecorder, ModelRetryDecision, ObservedModelToolCall, } from "./inference-attempt";
+export { getInferenceRecorder, InferenceAttemptSchema, parseInferenceAttempt, runWithInferenceRecorder, } from "./inference-attempt";
+export { addRecentModelId, getRecentModels, MAX_RECENT_MODELS, } from "./model-history";
+export { AVAILABLE_MODELS, getClaudeCapabilities, getModelInfo, } from "./models";
+export type { CreateNativeRolloutEvidenceCaptureInput, NativeRolloutCaptureLimits, NativeRolloutCaptureReportV1, NativeRolloutEvidenceCapture, NativeRolloutEvidenceEnvelopeV1, NativeRolloutEvidenceSink, NativeRolloutModelContext, } from "./native-rollout-evidence";
+export { createNativeRolloutEvidenceCapture, DEFAULT_NATIVE_ROLLOUT_CAPTURE_LIMITS, runWithNativeRolloutSession, serializeNativeRolloutEvidence, stringifyCanonicalJson, toJsonValue, } from "./native-rollout-evidence";
+export type { AIAuthConfig } from "./utils";
+export { buildAuthConfig } from "./utils";