@zpi-dev/agent-sdk 0.0.0-stage → 0.1.61

package/dist/types/ai/src/utils/json-parse.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Repairs malformed JSON string literals by:
+ * - escaping raw control characters inside strings
+ * - doubling backslashes before invalid escape characters
+ */
+export declare function repairJson(json: string): string;
+export declare function parseJsonWithRepair<T>(json: string): T;

package/dist/types/ai/src/utils/media-policy.d.ts

@@ -0,0 +1,68 @@
+import type { Model, TranscriptContext } from "../types.js";
+export declare const DEFAULT_MODEL_REQUEST_MEDIA_BUDGET_BYTES: number;
+export declare const MEDIA_BUDGET_CURRENT_ATTACHMENT_TOO_LARGE = "MEDIA_BUDGET_CURRENT_ATTACHMENT_TOO_LARGE";
+interface ContentBlock {
+    type: string;
+    text?: string;
+    mimeType?: string;
+    mediaType?: string;
+    name?: string;
+    data?: string;
+    dataUrl?: string;
+}
+interface MediaMessage {
+    role: string;
+    content: string | readonly ContentBlock[];
+    /** Synthetic summaries/reminders must not acquire current-user attachment protection. */
+    synthetic?: boolean;
+}
+export interface MediaBudgetStats {
+    omittedMediaCount: number;
+    projectedMediaBytes: number;
+    retainedMediaCount: number;
+    totalMediaBytes: number;
+    evictionFrontier: {
+        messageIndex: number;
+        blockIndex: number;
+    } | null;
+}
+export declare class MediaBudgetError extends Error {
+    readonly code = "MEDIA_BUDGET_CURRENT_ATTACHMENT_TOO_LARGE";
+    readonly type = "InvalidInput";
+    readonly recoverable = true;
+    readonly context: {
+        maxMediaBytes: number;
+        protectedMediaBytes: number;
+        totalMediaBytes: number;
+    };
+    constructor(context: {
+        maxMediaBytes: number;
+        protectedMediaBytes: number;
+        totalMediaBytes: number;
+    });
+}
+export declare function mediaBlockToText(block: ContentBlock): string;
+export declare function mediaRequestBytes(block: ContentBlock): number;
+export declare function omittedMediaBlock(block: ContentBlock): {
+    type: "text";
+    text: string;
+};
+/** Request-only projection: original transcript, artifacts and tool results remain untouched. */
+export declare function projectMessagesForMediaBudget<T extends MediaMessage>(messages: T[], options?: {
+    maxMediaBytes?: number;
+    latestRealUserMessageIndex?: number;
+    preserveLatestUserMedia?: boolean;
+}): {
+    messages: T[];
+} & MediaBudgetStats;
+/** Always bind capability projection and aggregate budget at the same provider request boundary. */
+export declare function projectContextForModelMediaPolicy(context: TranscriptContext, model: Pick<Model, "input">, options?: {
+    maxMediaBytes?: number;
+    onProjection?: (stats: MediaBudgetStats) => void;
+}): TranscriptContext;
+/** Compact retries use their own short placeholders, never the aggregate-budget omission text. */
+export declare function projectCompactMediaForRetry<T extends MediaMessage>(messages: T[]): {
+    messages: T[];
+    replacedMediaCount: number;
+};
+export {};

package/dist/types/ai/src/utils/model-performance.d.ts

@@ -0,0 +1,23 @@
+import type { AssistantMessageEvent, StreamOptions } from "../types.js";
+import { AssistantMessageEventStream } from "./event-stream.js";
+/** Measures at the producer, before consumers, tool execution or backpressure can delay events. */
+export declare class MeasuredAssistantStream extends AssistantMessageEventStream {
+    private started?;
+    private first?;
+    private last?;
+    private contentVersion;
+    private receivedAt?;
+    private usageVersion;
+    private sample;
+    private options;
+    private now;
+    constructor(options?: StreamOptions, now?: () => number);
+    startRequest(): void;
+    /** All deltas decoded from one wire event share one arrival time. */
+    received(): void;
+    generated(): void;
+    /** Call only when a fresh cumulative output count arrives, after content from the same wire event. */
+    recordUsage(outputTokens: unknown): void;
+    push(event: AssistantMessageEvent): void;
+    private publish;
+}

package/dist/types/ai/src/utils/model-retry.d.ts

@@ -0,0 +1,3 @@
+import type { ModelFailure } from "../types.js";
+/** Preserve retry facts before provider errors are converted into transcript text. */
+export declare function modelFailure(error: unknown, signal?: AbortSignal): ModelFailure;

package/dist/types/ai/src/utils/option-map/compiler.d.ts

@@ -0,0 +1,2 @@
+import { type ModelOptionMapProgram, type ModelOptionName } from "./types.js";
+export declare function compileModelOptionMap(source: string, variableName: ModelOptionName): ModelOptionMapProgram;

package/dist/types/ai/src/utils/option-map/evaluator.d.ts

@@ -0,0 +1,3 @@
+import type { RestrictedCelExpression } from "./parser.js";
+import { type JsonValue, type RestrictedCelValue } from "./types.js";
+export declare function evaluateRestrictedCel(expression: RestrictedCelExpression, input: RestrictedCelValue): JsonValue;

package/dist/types/ai/src/utils/option-map/parser.d.ts

@@ -0,0 +1,40 @@
+import type { RestrictedCelToken } from "./tokenizer.js";
+import { type ModelOptionName } from "./types.js";
+export type RestrictedCelExpression = {
+    readonly type: "literal";
+    readonly value: string | number | boolean | null;
+    readonly offset: number;
+} | {
+    readonly type: "input";
+    readonly offset: number;
+} | {
+    readonly type: "array";
+    readonly elements: readonly RestrictedCelExpression[];
+    readonly offset: number;
+} | {
+    readonly type: "object";
+    readonly entries: readonly {
+        readonly key: string;
+        readonly value: RestrictedCelExpression;
+        readonly offset: number;
+    }[];
+    readonly offset: number;
+} | {
+    readonly type: "unary";
+    readonly operator: "!" | "-" | "+";
+    readonly operand: RestrictedCelExpression;
+    readonly offset: number;
+} | {
+    readonly type: "binary";
+    readonly operator: string;
+    readonly left: RestrictedCelExpression;
+    readonly right: RestrictedCelExpression;
+    readonly offset: number;
+} | {
+    readonly type: "conditional";
+    readonly condition: RestrictedCelExpression;
+    readonly whenTrue: RestrictedCelExpression;
+    readonly whenFalse: RestrictedCelExpression;
+    readonly offset: number;
+};
+export declare function parseRestrictedCel(tokens: readonly RestrictedCelToken[], variableName: ModelOptionName): RestrictedCelExpression;

package/dist/types/ai/src/utils/option-map/tokenizer.d.ts

@@ -0,0 +1,8 @@
+export type RestrictedCelTokenKind = "identifier" | "string" | "number" | "operator" | "punctuation" | "eof";
+export interface RestrictedCelToken {
+    readonly kind: RestrictedCelTokenKind;
+    readonly value: string;
+    readonly offset: number;
+    readonly end: number;
+}
+export declare function tokenizeRestrictedCel(source: string): readonly RestrictedCelToken[];

package/dist/types/ai/src/utils/option-map/types.d.ts

@@ -0,0 +1,15 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+export type RestrictedCelValue = string | number;
+export type ModelOptionName = "reasoningLevel" | "maxOutputTokens";
+export interface ModelOptionMapProgram {
+    readonly source: string;
+    evaluate(input: RestrictedCelValue): JsonObject;
+}
+export declare class RestrictedCelError extends Error {
+    readonly offset: number;
+    constructor(message: string, offset: number);
+}

package/dist/types/ai/src/utils/overflow.d.ts

@@ -0,0 +1,68 @@
+import type { AssistantMessage } from "../types.js";
+/**
+ * Check if an assistant message represents a context overflow error.
+ *
+ * This handles three cases:
+ * 1. Error-based overflow: Most providers return stopReason "error" with a
+ *    specific error message pattern.
+ * 2. Silent overflow: Some providers accept overflow requests and return
+ *    successfully. For these, we check if usage.input exceeds the context window.
+ * 3. Length-stop overflow: Xiaomi MiMo can return "length" with zero output when
+ *    the input fills the context window.
+ *
+ * ## Reliability by Provider
+ *
+ * **Reliable detection (returns error with detectable message):**
+ * - Anthropic: "prompt is too long: X tokens > Y maximum" or "request_too_large"
+ * - OpenAI (Completions & Responses): "exceeds the context window", "exceeds the model's maximum context length of X tokens", or "exceeds model's maximum context length (X)"
+ * - Google Gemini: "input token count exceeds the maximum"
+ * - xAI (Grok): "maximum prompt length is X but request contains Y"
+ * - Groq: "reduce the length of the messages"
+ * - Cerebras: 400/413 status code (no body)
+ * - Mistral: "Prompt contains X tokens ... too large for model with Y maximum context length"
+ * - OpenRouter (most backends): "maximum context length is X tokens"
+ * - OpenRouter/Poolside: "Input length X exceeds the maximum allowed input length of Y tokens."
+ * - Together AI: "The input (X tokens) is longer than the model's context length (Y tokens)."
+ * - llama.cpp: "exceeds the available context size"
+ * - LM Studio: "greater than the context length"
+ * - Kimi For Coding: "exceeded model token limit: X (requested: Y)"
+ * - DS4: "Prompt has X tokens, but the configured context size is Y tokens"
+ * - DashScope/Qwen: "Range of input length should be [1, X]"
+ *
+ * **Unreliable detection:**
+ * - z.ai: Sometimes accepts overflow silently (detectable via usage.input > contextWindow),
+ *   sometimes returns rate limit errors. Pass contextWindow param to detect silent overflow.
+ * - Xiaomi MiMo: Truncates input to fit contextWindow then returns stopReason "length" with
+ *   output=0. Pass contextWindow param to detect via the "filled context + zero output" signal.
+ * - Ollama: May truncate input silently for some setups, but may also return explicit
+ *   overflow errors that match the patterns above. Silent truncation still cannot be
+ *   detected here because we do not know the expected token count.
+ *
+ * ## Custom Providers
+ *
+ * If you've added custom models via settings.json, this function may not detect
+ * overflow errors from those providers. To add support:
+ *
+ * 1. Send a request that exceeds the model's context window
+ * 2. Check the errorMessage in the response
+ * 3. Create a regex pattern that matches the error
+ * 4. The pattern should be added to OVERFLOW_PATTERNS in this file, or
+ *    check the errorMessage yourself before calling this function
+ *
+ * @param message - The assistant message to check
+ * @param contextWindow - Optional context window size for detecting silent overflow (z.ai)
+ * @returns true if the message indicates a context overflow
+ */
+export declare function isContextOverflow(message: AssistantMessage, contextWindow?: number): boolean;
+/**
+ * Check whether a length stop ended below the caller or model's intended output limit.
+ * Such responses may be caused by context pressure or provider-side truncation, so callers
+ * can make one bounded compact-and-retry attempt. `desiredMaxOutput` must be the original
+ * limit before any context-based clamping.
+ */
+export declare function isRecoverableLength(message: AssistantMessage, desiredMaxOutput: number): boolean;
+/** Exact ZCode message predicates. Bare HTTP 413 / length limit exceeded matches neither. */
+export declare function isModelContextExceededMessage(value: string | undefined): boolean;
+export declare function isModelMediaTooLargeMessage(value: string | undefined): boolean;
+export declare function isModelContextExceededError(error: unknown): boolean;
+export declare function isModelMediaTooLargeError(error: unknown): boolean;

package/dist/types/ai/src/utils/provider-cache.d.ts

@@ -0,0 +1,11 @@
+import type { Message } from "../types.js";
+/** System breakpoints are independent; replace only non-system markers on a request copy. */
+export declare function finalizeProviderCacheControl(messages: Message[], options?: {
+    skipCacheWrite?: boolean;
+}): Message[];
+/** Count only protocol cache locations, never user/tool input objects with similarly named fields. */
+export declare function assertProviderCacheControlLimit(request: {
+    system?: unknown;
+    tools?: unknown;
+    messages?: unknown;
+}): void;

package/dist/types/ai/src/utils/provider-env.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderEnv } from "../types.js";
+export declare function getProviderEnvValue(name: string, env?: ProviderEnv): string | undefined;

package/dist/types/ai/src/utils/provider-retry.d.ts

@@ -0,0 +1,17 @@
+import type { ModelRetryStatus } from "../types.js";
+interface ProviderRetryOptions {
+    maxRetries?: number;
+    maxRetryDelayMs?: number;
+    signal?: AbortSignal;
+    onRetry?: (status: ModelRetryStatus | null) => void;
+}
+/**
+ * Reproduce the retry behavior used by the OpenAI and Anthropic SDKs while making
+ * their backoff sleep interruptible. Their built-in retry timers ignore the
+ * request AbortSignal, so callers must invoke the SDK with `maxRetries: 0` and
+ * wrap the request with this helper. Provider-requested delays above
+ * `maxRetryDelayMs` fail immediately (60 seconds by default); set it to zero to
+ * disable the limit.
+ */
+export declare function retryProviderRequest<T>(request: () => Promise<T>, options?: ProviderRetryOptions): Promise<T>;
+export {};

package/dist/types/ai/src/utils/reasoning.d.ts

@@ -0,0 +1,14 @@
+import type { JsonObject, Model, ReasoningConfig, ThinkingLevel } from "../types.js";
+export declare const reasoningParameterKeys: readonly ["reasoning_effort", "thinking", "reasoning", "enable_thinking", "thinking_budget", "reasoning_budget", "output_config"];
+type ReasoningModel = Pick<Model, "reasoning" | "compat" | "thinkingLevelMap" | "defaultThinkingLevel" | "reasoningConfig"> & Partial<Pick<Model, "api">>;
+export declare const thinkingLevels: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export declare function thinkingChoices(model: ReasoningModel): ("off" | ThinkingLevel)[];
+export declare function defaultThinkingLevel(model: ReasoningModel): "off" | ThinkingLevel;
+/** Pi chooses the next supported strength, then searches downwards. */
+export declare function clampThinkingLevel(model: ReasoningModel, level: "off" | ThinkingLevel): "off" | ThinkingLevel;
+export declare function validateThinkingMap(map: unknown): void;
+export declare function canControlThinking(model: ReasoningModel, level: "off" | ThinkingLevel): boolean;
+export declare function reasoningParameters(model: ReasoningModel, level?: "off" | ThinkingLevel | undefined): JsonObject | undefined;
+export declare function validateReasoningConfig(config: unknown): void;
+export declare function editableReasoningConfig(model: ReasoningModel): ReasoningConfig;
+export {};

package/dist/types/ai/src/utils/redact-error.d.ts

@@ -0,0 +1,2 @@
+/** Remove configured credentials before provider errors enter the durable transcript. */
+export declare function redactProviderError(message: string, secrets: readonly (string | null | undefined)[]): string;

package/dist/types/ai/src/utils/retry.d.ts

@@ -0,0 +1,62 @@
+import type { AssistantMessage, ModelRetryStatus } from "../types.js";
+/**
+ * Retry policy: bounded attempts with exponential backoff (`baseDelayMs * 2^(attempt-1)`).
+ * `maxAgentDelayMs` caps each computed delay and defaults to 60 seconds.
+ * Matches `settings.retry` (`enabled`, `maxRetries`, `baseDelayMs`, `maxAgentDelayMs`) in coding-agent; kept
+ * here so the classifier and the policy-driven retry loop live together and stay reusable
+ * by the SDK and other callers.
+ */
+export interface RetryPolicy {
+    enabled: boolean;
+    /** Max retry attempts (0 = no retries). The initial call never counts as a retry. */
+    maxRetries: number;
+    /** Base delay in ms. Per-attempt delay is `baseDelayMs * 2^(attempt-1)`. */
+    baseDelayMs: number;
+    /** Optional cap for agent-level retry delays in ms. Defaults to 60 seconds. */
+    maxAgentDelayMs?: number;
+    /** Recovery time allowed after the first failure; <= 0 disables the cap. */
+    maxElapsedMs?: number;
+}
+export declare const DEFAULT_MAX_AGENT_RETRY_DELAY_MS = 60000;
+/** Keep failure-specific retry limits shared by session and summary recovery. */
+export declare function retryAttemptLimit(message: AssistantMessage, configuredLimit: number): number;
+export declare function retryDelayMs(policy: Pick<RetryPolicy, "baseDelayMs" | "maxAgentDelayMs">, attempt: number, retryAfterMs?: number): number;
+/** Optional callbacks emitted by {@link retryAssistantCall} around each retry. */
+export interface RetryCallbacks {
+    /** Emitted before the backoff sleep of each retry attempt (1-indexed). */
+    onRetryScheduled?: (attempt: number, maxAttempts: number, delayMs: number, errorMessage: string, origin?: ModelRetryStatus["origin"]) => void | Promise<void>;
+    /** Emitted after the backoff sleep, immediately before the retried call starts. */
+    onRetryAttemptStart?: () => void | Promise<void>;
+    /** Optional interruptible backoff. Return true when an explicit user retry resets the recovery budget. */
+    waitBeforeRetry?: (delayMs: number, signal?: AbortSignal) => Promise<boolean>;
+    /** Emitted once when the loop ends: success if a later call completed normally. */
+    onRetryFinished?: (success: boolean, attempt: number, finalError?: string) => void | Promise<void>;
+}
+/**
+ * Run a single assistant-producing call with bounded retry on transient errors.
+ *
+ * Behavior:
+ * - A successful response is returned immediately. Aborts are terminal and never
+ *   retried, but reported as unsuccessful if they happen after a retry was scheduled.
+ *   Aborts during the backoff sleep are normalized to an aborted `AssistantMessage`
+ *   too, so callers do not need to care when cancellation happened.
+ * - A non-retryable error (per {@link isRetryableAssistantError}, including quota/
+ *   billing exhaustion) is returned immediately so deterministic errors fail fast.
+ * - Otherwise retries up to `maxRetries` times with exponential backoff, emitting
+ *   `onRetryScheduled` before each sleep, `onRetryAttemptStart` after each sleep before
+ *   the retried call starts, and `onRetryFinished` once at the end (whether the loop
+ *   ends in success, exhausted retries, or an aborted backoff).
+ *
+ * When `policy` is undefined or disabled, only an explicit manual retry can repeat a request.
+ */
+export declare function retryAssistantCall(produce: (deadlineMs?: number) => Promise<AssistantMessage>, policy: RetryPolicy | undefined, signal: AbortSignal | undefined, callbacks?: RetryCallbacks): Promise<AssistantMessage>;
+/**
+ * Classifies whether a failed assistant message looks like a transient provider
+ * or transport error, so callers can decide if the last assistant turn should be
+ * restarted.
+ *
+ * This does not implement retry policy. Callers should first handle context
+ * overflow separately, then apply their own retry budget, backoff, and reporting
+ * before restarting the assistant turn.
+ */
+export declare function isRetryableAssistantError(message: AssistantMessage): boolean;

package/dist/types/ai/src/utils/sanitize-unicode.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Removes unpaired Unicode surrogate characters from a string.
+ *
+ * Unpaired surrogates (high surrogates 0xD800-0xDBFF without matching low surrogates 0xDC00-0xDFFF,
+ * or vice versa) cause JSON serialization errors in many API providers.
+ *
+ * Valid emoji and other characters outside the Basic Multilingual Plane use properly paired
+ * surrogates and will NOT be affected by this function.
+ *
+ * @param text - The text to sanitize
+ * @returns The sanitized text with unpaired surrogates removed
+ *
+ * @example
+ * // Valid emoji (properly paired surrogates) are preserved
+ * sanitizeSurrogates("Hello 🙈 World") // => "Hello 🙈 World"
+ *
+ * // Unpaired high surrogate is removed
+ * const unpaired = String.fromCharCode(0xD83D); // high surrogate without low
+ * sanitizeSurrogates(`Text ${unpaired} here`) // => "Text  here"
+ */
+export declare function sanitizeSurrogates(text: string): string;

package/dist/types/ai/src/utils/stream-idle-timeout.d.ts

@@ -0,0 +1,36 @@
+export declare const DEFAULT_MODEL_FIRST_RESPONSE_TIMEOUT_MS = 120000;
+export declare const DEFAULT_MODEL_STREAM_IDLE_TIMEOUT_MS = 300000;
+export declare function resolveModelStreamIdleTimeoutMs(options: {
+    baseTimeoutMs?: number;
+    retryNumber?: number;
+}): number;
+export declare class ModelRequestRetryError extends Error {
+    readonly code = "MODEL_REQUEST_RETRY";
+    constructor();
+}
+export declare class ModelRecoveryDeadlineError extends Error {
+    readonly code = "MODEL_RECOVERY_DEADLINE";
+    constructor();
+}
+export declare class ModelStreamIdleTimeoutError extends Error {
+    readonly code = "MODEL_STREAM_IDLE_TIMEOUT";
+    readonly idleMs: number;
+    readonly timeoutMs: number;
+    constructor(options: {
+        idleMs: number;
+        timeoutMs: number;
+    });
+}
+export declare function createLinkedAbortController(parentSignal?: AbortSignal): {
+    controller: AbortController;
+    signal: AbortSignal;
+    cleanup(): void;
+};
+export declare function readNextWithStreamIdleTimeout<T>(iterator: AsyncIterator<T>, options: {
+    abortController: AbortController;
+    onTimeout?: (error: ModelStreamIdleTimeoutError) => void | Promise<void>;
+    timeoutMs: number;
+    startedAt?: number;
+}): Promise<IteratorResult<T>>;
+/** A provider can ignore abort and hang in return(); cleanup must not block recovery. */
+export declare function closeStreamIterator(iterator: AsyncIterator<unknown> | undefined): Promise<void>;

package/dist/types/ai/src/utils/text.d.ts

@@ -0,0 +1,5 @@
+import type { SystemMessage } from "../types.js";
+/**
+ * Shared wire representation of named context changes, regardless of provider role.
+ */
+export declare function renderSystemMessageUpdate(message: SystemMessage): string;

package/dist/types/ai/src/utils/transcript.d.ts

@@ -0,0 +1,28 @@
+import type { AssistantMessage, Context, JsonObject, JsonValue, Model, SystemMessage, Tool, TranscriptContext } from "../types.js";
+export declare function normalizeContext(context: Context): TranscriptContext;
+export declare function contentText(content: string | readonly {
+    type: string;
+    text?: string;
+}[], separator?: string): string;
+export declare function getCurrentSystemPrompt(messages: readonly {
+    role: string;
+}[]): string;
+export declare function getCurrentTools(messages: readonly {
+    role: string;
+}[]): Tool[];
+export declare function toToolDeclaration(tool: Tool): Tool;
+export declare function emptyAssistant(model: Model): AssistantMessage;
+export declare function isJsonValue(value: unknown, seen?: Set<object>): value is JsonValue;
+export declare function isJsonObject(value: unknown): value is JsonObject;
+export declare function assertSupportedOptions(value: object, allowed: readonly string[], label: string): void;
+export type TranscriptMessages = readonly {
+    role: string;
+}[];
+/** Return the leading system message, if the transcript starts with one. */
+export declare function getInitialSystemMessage(messages: TranscriptMessages): SystemMessage | undefined;
+export declare function getDeclaredTools(messages: TranscriptMessages): Tool[];
+/**
+ * Whether a tool name was declared twice with different definitions. Transports that
+ * reference tools by name (Anthropic `tool_addition`/`tool_removal`) cannot express that.
+ */
+export declare function hasToolRedefinitions(messages: TranscriptMessages): boolean;

package/dist/types/coding-agent/src/core/agent-session.d.ts

@@ -0,0 +1,175 @@
+import type { AgentEvent, AgentState, AgentTool, ThinkingLevel } from "../../../agent/src/index.js";
+import type { ImageContent, Model, ModelRetryStatus, ModelWaitStatus, SimpleStreamOptions, UserGuide } from "../../../ai/src/index.js";
+import type { HookExecution, HookRegistration } from "../plugins/hooks.js";
+import type { PluginCommand } from "../plugins/types.js";
+import type { ParsedInput } from "./commands.js";
+import { type ModelPerformance, type ModelPerformanceTotals } from "./model-performance.js";
+import type { ModelRuntime } from "./model-runtime.js";
+import type { LoadedSkill, SkillList } from "./resources.js";
+import type { SessionEntry, SessionManager } from "./session-manager.js";
+import type { ContextUsage } from "./session-state.js";
+import { SettingsManager } from "./settings-manager.js";
+import type { SystemContext } from "./system-prompt.js";
+import type { ResourceDiagnostic, ResourceLoader } from "./types.js";
+export interface InputContext {
+    images?: ImageContent[];
+    fileReferences?: string[];
+}
+export type AgentSessionEvent = {
+    type: "hook_execution";
+    execution: HookExecution;
+} | {
+    type: "model_performance";
+    performance: ModelPerformance;
+    totals: ModelPerformanceTotals;
+} | Exclude<AgentEvent, {
+    type: "agent_end";
+}> | {
+    type: "agent_end";
+    messages: AgentState["messages"];
+    willRetry: boolean;
+} | {
+    type: "agent_settled";
+} | {
+    type: "entry_appended";
+    entry: SessionEntry;
+} | {
+    type: "session_info_changed";
+    name: string;
+} | {
+    type: "thinking_level_changed";
+    thinkingLevel: ThinkingLevel;
+} | {
+    type: "model_retry";
+    status: ModelRetryStatus | null;
+} | {
+    type: "model_wait";
+    status: ModelWaitStatus | null;
+} | {
+    type: "compaction";
+    id: string;
+    status: "running" | "completed" | "aborted" | "error" | "noop";
+    origin: "manual" | "auto";
+    error?: string;
+} | {
+    type: "command_result";
+    message: string;
+};
+export declare class AgentSession {
+    private modelRequestOptions?;
+    private onCompaction?;
+    private agent;
+    private pluginCommands;
+    private hooks;
+    private manager;
+    private steering;
+    private pendingMessages;
+    private allTools;
+    private listeners;
+    private running?;
+    private active?;
+    private disposed;
+    private abortRequested;
+    private fault?;
+    private runtime;
+    private responsesSession?;
+    private responsesWarmupTimer?;
+    private responsesWarmupController?;
+    private resources?;
+    private compactController?;
+    readonly settingsManager: SettingsManager;
+    private overflowRecoveryAttempted;
+    private retryAttempt;
+    private recoveryStartedAt?;
+    private retryCurrentRequest?;
+    private lastAssistantCompletedAtMs?;
+    private microcompactProjection;
+    private recoveredCalls;
+    private performance;
+    get modelPerformance(): ModelPerformance;
+    constructor(model: Model, runtime: ModelRuntime, manager: SessionManager, allTools: AgentTool[], activeTools: AgentTool[], systemPrompt: string, thinkingLevel: ThinkingLevel, resources?: {
+        loader: ResourceLoader;
+        buildContext: () => SystemContext;
+        settingsManager?: SettingsManager;
+    }, performanceTotals?: ModelPerformanceTotals, extensions?: {
+        modelRequestOptions?: () => SimpleStreamOptions;
+        onCompaction?: (phase: "before" | "after", context: {
+            manual: boolean;
+            instructions: string;
+        }, signal?: AbortSignal) => Promise<void>;
+        beforeModelRequest?: (model: Model, context: import("../../../ai/src/index.js").Context) => void;
+        commands?: readonly PluginCommand[];
+        hooks?: readonly (HookRegistration & {
+            pluginId?: string;
+        })[];
+    });
+    private prepareResponsesSession;
+    static create(...args: ConstructorParameters<typeof AgentSession>): Promise<AgentSession>;
+    get state(): AgentState;
+    get messages(): AgentState["messages"];
+    get model(): Model;
+    get thinkingLevel(): ThinkingLevel;
+    get isStreaming(): boolean;
+    get isIdle(): boolean;
+    get systemPrompt(): string;
+    getContextUsage(): ContextUsage;
+    listSkills(): SkillList;
+    getResourceDiagnostics(): ResourceDiagnostic[];
+    loadSkill(name: string): Promise<LoadedSkill>;
+    prepareInput(text: string, context?: InputContext): Promise<ParsedInput>;
+    listCommands(): {
+        name: string;
+        description: string;
+    }[];
+    submit(text: string): Promise<void>;
+    executeInput(input: ParsedInput, context?: InputContext): Promise<void>;
+    private syncContext;
+    private refreshInstructions;
+    private compactionBoundary;
+    private estimateTokens;
+    private precedesCompaction;
+    private tryAutoCompact;
+    private checkCompaction;
+    private dropFailedAssistant;
+    private waitForRetry;
+    private waitForRetryDelay;
+    private canRetry;
+    private recoveryDeadline;
+    /** Only the active model request or retry backoff can be retried; tools keep their lifecycle. */
+    retryModelRequest(): boolean;
+    private requestOptions;
+    private alreadyCompacted;
+    private summarize;
+    private summarizeContext;
+    private streamWithRecovery;
+    private measuredStream;
+    compact(instructions?: string): Promise<void>;
+    get sessionId(): string;
+    get sessionFile(): string | undefined;
+    get sessionName(): string | undefined;
+    subscribe(listener: (event: AgentSessionEvent) => void): () => void;
+    private notify;
+    private notifyLastEntry;
+    private idleCheck;
+    prompt(text: string, options?: {
+        images?: ImageContent[];
+    }): Promise<void>;
+    /** Queue input for the next completed model/tool boundary without interrupting generation. */
+    steer(text: string, options?: {
+        queueOnly?: boolean;
+        inputId?: string;
+        userGuide?: UserGuide;
+        images?: ImageContent[];
+        fileReferences?: string[];
+    }): boolean;
+    abort(): Promise<void>;
+    waitForIdle(): Promise<void>;
+    dispose(): void;
+    getToolDefinitions(): AgentTool[];
+    validateImages(images?: ImageContent[]): void;
+    getActiveToolNames(): string[];
+    setActiveToolsByName(names: string[]): void;
+    setModel(model: Model): Promise<void>;
+    setThinkingLevel(thinkingLevel: ThinkingLevel): void;
+    setSessionName(name: string): void;
+}

package/dist/types/coding-agent/src/core/commands.d.ts

@@ -0,0 +1,19 @@
+export declare const localCommands: readonly [{
+    readonly name: "compact";
+    readonly description: "摘要旧对话，保留完整历史";
+}];
+export declare function listCommands(commands?: readonly {
+    name: string;
+    description: string;
+}[]): {
+    name: string;
+    description: string;
+}[];
+export type ParsedInput = {
+    kind: "prompt";
+    text: string;
+} | {
+    kind: "compact";
+    args: string;
+};
+export declare function parseInput(text: string): ParsedInput;