noumen 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { S as Sandbox, A as Agent, D as DockerContainer, E as E2BSandboxInstance, a as SkillDefinition, T as ThreadConfig, b as SessionStorage, C as ContextFile, P as ProjectContextConfig, c as ContextScope, R as RetryConfig, d as RetryContext, e as RetryEngineOptions, f as Span, g as SpanAttributeValue, h as SpanStatusCode, i as Tracer, j as SpanOptions, k as StoredCostState } from './agent-BrkbZyOT.js';
-export { l as AgentOptions, m as AutoCompactConfig, n as AutoCompactTrackingState, B as BudgetState, o as CLEARED_PLACEHOLDER, p as COMPACTABLE_TOOLS, q as ContentReplacementState, r as CostTracker, s as DEFAULT_MODELS, t as DEFAULT_RETRY_CONFIG, u as DiagnoseCheckResult, v as DiagnoseResult, w as DockerComputer, x as DockerComputerOptions, y as DockerSandbox, z as DockerSandboxOptions, F as E2BComputer, G as E2BComputerOptions, H as E2BSandbox, I as E2BSandboxOptions, L as LocalSandbox, J as LocalSandboxOptions, M as MicrocompactConfig, K as MicrocompactResult, N as ProviderName, O as ReactiveCompactConfig, Q as ReactiveCompactResult, U as ResolveProviderOptions, V as RetryEvent, W as RunCallbacks, X as RunResult, Y as SUPPORTED_PROVIDERS, Z as SandboxConfig, _ as SandboxedLocalComputer, $ as SandboxedLocalComputerOptions, a0 as SnipConfig, a1 as SnipResult, a2 as SpritesSandbox, a3 as SpritesSandboxOptions, a4 as Thread, a5 as ThreadOptions, a6 as ToolResultBudgetConfig, a7 as ToolResultBudgetResult, a8 as ToolResultReplacementRecord, a9 as ToolResultSpillResult, aa as ToolResultStorageConfig, ab as TracingConfig, ac as UnsandboxedLocal, ad as UnsandboxedLocalOptions, ae as WebSearchConfig, af as WebSearchResult, ag as applyPersistedReplacements, ah as applySnipRemovals, ai as canAutoCompact, aj as createAutoCompactConfig, ak as createAutoCompactTracking, al as createBudgetState, am as createContentReplacementState, an as createWebSearchTool, ao as detectProvider, ap as enforceToolResultBudget, aq as enforceToolResultStorageBudget, ar as microcompactMessages, as as persistToolResult, at as projectSnippedView, au as reconstructContentReplacementState, av as recordAutoCompactFailure, aw as recordAutoCompactSuccess, ax as resolveProvider, ay as shouldAutoCompact, az as snipMessagesByUuids, aA as tryReactiveCompact, aB as webSearchToolPlaceholder } from './agent-BrkbZyOT.js';
-import { A as AIProvider, T as ToolDefinition, o as ToolCallContent, S as StreamEvent, e as ContentPart, b as ChatMessage, k as ChatCompletionUsage, M as ModelPricing, h as UsageRecord, a as ChatStreamChunk, p as MemoryProvider, q as MemoryEntry, l as ThinkingConfig, r as AssistantMessage, s as ToolResultMessage, d as FileCheckpointSnapshot, t as ToolResultOverflowEntry, f as ContentReplacementRecord, J as JsonSchemaOutputFormat } from './types-3c88cRKH.js';
-export { C as ChatParams, u as ChatStreamChoice, v as ChatStreamDelta, w as ChatStreamError, c as CheckpointConfig, x as CompactBoundaryEntry, y as ContentReplacementEntry, i as CostSummary, z as CustomTitleEntry, D as DiffStats, E as Entry, B as FileCheckpointBackup, G as FileCheckpointEntry, F as FileCheckpointState, I as ImageContent, H as ImageUrlContent, K as JsonObjectOutputFormat, m as MemoryConfig, L as MemoryType, N as MessageEntry, P as MetadataEntry, j as ModelUsageSummary, O as OutputFormat, R as RunOptions, Q as SerializedMessage, g as SessionInfo, V as SnipBoundaryEntry, W as SummaryEntry, X as SystemMessage, Y as TextContent, Z as ToolDefParameterProperty, n as ToolResult, _ as UserMessage, $ as createCheckpointState } from './types-3c88cRKH.js';
-import { H as HookDefinition, V as VirtualFs, R as ReadOptions, F as FileEntry, i as FileStat, j as VirtualComputer, E as ExecOptions, C as CommandResult, T as Tool, h as ToolContext, g as ToolResult, o as HookEvent, p as HookInput, P as PostToolUseFailureHookInput, q as PostToolUseFailureHookOutput, r as PostToolUseHookInput, s as PostToolUseHookOutput, t as PreToolUseHookInput, u as PreToolUseHookOutput } from './types-CwKKucOF.js';
-export { m as FileCheckpointManager, v as FileState, w as FileStateCache, n as FileStateCacheConfig, x as FileWriteHookInput, y as HookOutput, J as JsonSchemaType, b as LspDiagnostic, c as LspLocation, d as LspOperation, L as LspServerConfig, a as LspServerState, f as LspSymbol, M as MemoryUpdateHookInput, z as ModelSwitchHookInput, N as NotificationHookInput, A as PermissionDeniedHookInput, B as PermissionRequestHookInput, G as RetryAttemptHookInput, I as SafeParseResult, K as SessionEndHookInput, O as SessionStartHookInput, S as SubagentConfig, k as SubagentRun, Q as SubagentStartHookInput, U as SubagentStopHookInput, W as Task, X as TaskCreateInput, Y as TaskStatus, l as TaskStore, Z as TaskUpdateInput, _ as ToolParameters, $ as ZodLikeSchema, a0 as formatZodValidationError, a1 as registerZodToJsonSchema, a2 as zodToJsonSchema } from './types-CwKKucOF.js';
+import { S as Sandbox, A as Agent, D as DockerContainer, E as E2BSandboxInstance, F as FreestyleVmInstance, a as SkillDefinition, T as ThreadConfig, b as SessionStorage, C as ContextFile, P as ProjectContextConfig, c as ContextScope, R as RetryConfig, d as RetryContext, e as RetryEngineOptions, f as Span, g as SpanAttributeValue, h as SpanStatusCode, i as Tracer, j as SpanOptions, k as StoredCostState } from './agent-1nFVUP9E.js';
+export { l as AgentOptions, m as AutoCompactConfig, n as AutoCompactTrackingState, B as BudgetState, o as CLEARED_PLACEHOLDER, p as COMPACTABLE_TOOLS, q as ContentReplacementState, r as CostTracker, s as DEFAULT_MODELS, t as DEFAULT_RETRY_CONFIG, u as DiagnoseCheckResult, v as DiagnoseResult, w as DockerComputer, x as DockerComputerOptions, y as DockerSandbox, z as DockerSandboxOptions, G as E2BComputer, H as E2BComputerOptions, I as E2BSandbox, J as E2BSandboxOptions, K as FreestyleComputer, L as FreestyleComputerOptions, M as FreestyleSandbox, N as FreestyleSandboxOptions, O as LocalSandbox, Q as LocalSandboxOptions, U as MicrocompactConfig, V as MicrocompactResult, W as ProviderName, X as ReactiveCompactConfig, Y as ReactiveCompactResult, Z as ResolveProviderOptions, _ as RetryEvent, $ as RunCallbacks, a0 as RunResult, a1 as SUPPORTED_PROVIDERS, a2 as SandboxConfig, a3 as SandboxedLocalComputer, a4 as SandboxedLocalComputerOptions, a5 as SnipConfig, a6 as SnipResult, a7 as SpritesSandbox, a8 as SpritesSandboxOptions, a9 as Thread, aa as ThreadOptions, ab as ToolResultBudgetConfig, ac as ToolResultBudgetResult, ad as ToolResultReplacementRecord, ae as ToolResultSpillResult, af as ToolResultStorageConfig, ag as TracingConfig, ah as UnsandboxedLocal, ai as UnsandboxedLocalOptions, aj as WebSearchConfig, ak as WebSearchResult, al as applyPersistedReplacements, am as applySnipRemovals, an as canAutoCompact, ao as createAutoCompactConfig, ap as createAutoCompactTracking, aq as createBudgetState, ar as createContentReplacementState, as as createWebSearchTool, at as detectProvider, au as enforceToolResultBudget, av as enforceToolResultStorageBudget, aw as microcompactMessages, ax as persistToolResult, ay as projectSnippedView, az as reconstructContentReplacementState, aA as recordAutoCompactFailure, aB as recordAutoCompactSuccess, aC as resolveProvider, aD as shouldAutoCompact, aE as snipMessagesByUuids, aF as tryReactiveCompact, aG as webSearchToolPlaceholder } from './agent-1nFVUP9E.js';
+import { A as AIProvider, T as ToolDefinition, o as ToolCallContent, S as StreamEvent, e as ContentPart, b as ChatMessage, k as ChatCompletionUsage, M as ModelPricing, h as UsageRecord, a as ChatStreamChunk, p as MemoryProvider, q as MemoryEntry, l as ThinkingConfig, r as AssistantMessage, s as ToolResultMessage, d as FileCheckpointSnapshot, t as ToolResultOverflowEntry, f as ContentReplacementRecord, J as JsonSchemaOutputFormat } from './types-LrU4LRmX.js';
+export { C as ChatParams, u as ChatStreamChoice, v as ChatStreamDelta, w as ChatStreamError, c as CheckpointConfig, x as CompactBoundaryEntry, y as ContentReplacementEntry, i as CostSummary, z as CustomTitleEntry, D as DiffStats, E as Entry, B as FileCheckpointBackup, G as FileCheckpointEntry, F as FileCheckpointState, I as ImageContent, H as ImageUrlContent, K as JsonObjectOutputFormat, m as MemoryConfig, L as MemoryType, N as MessageEntry, P as MetadataEntry, j as ModelUsageSummary, O as OutputFormat, R as RunOptions, Q as SerializedMessage, g as SessionInfo, V as SnipBoundaryEntry, W as SummaryEntry, X as SystemMessage, Y as TextContent, Z as ToolDefParameterProperty, n as ToolResult, _ as UserMessage, $ as createCheckpointState } from './types-LrU4LRmX.js';
+import { H as HookDefinition, V as VirtualFs, R as ReadOptions, F as FileEntry, i as FileStat, j as VirtualComputer, E as ExecOptions, C as CommandResult, T as Tool, h as ToolContext, g as ToolResult, o as HookEvent, p as HookInput, P as PostToolUseFailureHookInput, q as PostToolUseFailureHookOutput, r as PostToolUseHookInput, s as PostToolUseHookOutput, t as PreToolUseHookInput, u as PreToolUseHookOutput } from './types-RPKUTu1k.js';
+export { m as FileCheckpointManager, v as FileState, w as FileStateCache, n as FileStateCacheConfig, x as FileWriteHookInput, y as HookOutput, J as JsonSchemaType, b as LspDiagnostic, c as LspLocation, d as LspOperation, L as LspServerConfig, a as LspServerState, f as LspSymbol, M as MemoryUpdateHookInput, z as ModelSwitchHookInput, N as NotificationHookInput, A as PermissionDeniedHookInput, B as PermissionRequestHookInput, G as RetryAttemptHookInput, I as SafeParseResult, K as SessionEndHookInput, O as SessionStartHookInput, S as SubagentConfig, k as SubagentRun, Q as SubagentStartHookInput, U as SubagentStopHookInput, W as Task, X as TaskCreateInput, Y as TaskStatus, l as TaskStore, Z as TaskUpdateInput, _ as ToolParameters, $ as ZodLikeSchema, a0 as formatZodValidationError, a1 as registerZodToJsonSchema, a2 as zodToJsonSchema } from './types-RPKUTu1k.js';
 import { M as McpServerConfig } from './types-2kTLUCnD.js';
 export { b as McpConfig, c as McpConnection, d as McpHttpServerConfig, e as McpOAuthConfig, f as McpSseServerConfig, g as McpStdioServerConfig, h as McpToolInfo, i as McpWebSocketServerConfig, a as OAuthProviderOptions, O as OAuthTokenData, T as TokenStorage } from './types-2kTLUCnD.js';
 export { OpenAIProviderOptions } from './providers/openai.js';
@@ -12,10 +12,11 @@ export { GeminiProviderOptions } from './providers/gemini.js';
 export { OpenRouterProviderOptions } from './providers/openrouter.js';
 export { BedrockAnthropicProviderOptions } from './providers/bedrock.js';
 export { VertexAnthropicProviderOptions } from './providers/vertex.js';
-import { c as PermissionHandler, e as PermissionContext, f as PermissionBehavior, g as PermissionRule, A as AutoModeConfig, h as PermissionDecision, i as PermissionUpdate } from './types-DwdzmXfs.js';
-export { D as DenialTrackingConfig, j as PermissionAllowResult, k as PermissionAskResult, d as PermissionConfig, l as PermissionDenyResult, a as PermissionMode, m as PermissionPassthroughResult, n as PermissionRequest, P as PermissionResponse, b as PermissionResult, o as PermissionRuleSource, R as RULE_SOURCE_PRECEDENCE } from './types-DwdzmXfs.js';
-export { a as McpClientManagerOptions, b as McpServerOptions, c as buildMcpToolName, g as getMcpPrefix, n as normalizeNameForMCP, p as parseMcpToolName } from './server-Cg1yWGaV.js';
-export { C as CacheControlConfig, a as CacheScope, g as getMessageCacheBreakpointIndex, s as sortToolDefinitionsForCache } from './cache-DVqaCX8v.js';
+export { OllamaProviderOptions } from './providers/ollama.js';
+import { c as PermissionHandler, e as PermissionContext, f as PermissionBehavior, g as PermissionRule, A as AutoModeConfig, h as PermissionDecision, i as PermissionUpdate } from './types-CD0rUKKT.js';
+export { D as DenialTrackingConfig, j as PermissionAllowResult, k as PermissionAskResult, d as PermissionConfig, l as PermissionDenyResult, a as PermissionMode, m as PermissionPassthroughResult, n as PermissionRequest, P as PermissionResponse, b as PermissionResult, o as PermissionRuleSource, R as RULE_SOURCE_PRECEDENCE } from './types-CD0rUKKT.js';
+export { a as McpClientManagerOptions, b as McpServerOptions, c as buildMcpToolName, g as getMcpPrefix, n as normalizeNameForMCP, p as parseMcpToolName } from './server-CHMxuWKq.js';
+export { C as CacheControlConfig, a as CacheScope, g as getMessageCacheBreakpointIndex, s as sortToolDefinitionsForCache } from './cache-DsRqxx6v.js';
 export { JsonRpcErrorObject, JsonRpcMessage, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse } from './jsonrpc/index.js';
 export { b as AcpCapabilities, c as AcpInitializeParams, d as AcpInitializeResult, A as AcpTransport } from './types-QwfylltH.js';
 export { e as A2AArtifact, M as A2AMessage, P as A2APart, b as A2ATask, g as A2ATaskStatus, a as AgentCard, A as AgentSkill } from './types-NIyVwQ4h.js';
@@ -55,12 +56,6 @@ declare function planningAgent(opts: PresetOptions): Agent;
  */
 declare function reviewAgent(opts: PresetOptions): Agent;
 
-interface OllamaProviderOptions {
-    /** Ollama server URL. Defaults to http://localhost:11434/v1. */
-    baseURL?: string;
-    model?: string;
-}
-
 interface LocalFsOptions {
     basePath?: string;
 }
@@ -73,7 +68,10 @@ interface LocalFsOptions {
  */
 declare class LocalFs implements VirtualFs {
     private basePath;
+    private resolvedBasePath;
+    private realBasePathPromise;
     constructor(opts?: LocalFsOptions);
+    private getRealBasePath;
     private resolve;
     readFile(filePath: string, opts?: ReadOptions): Promise<string>;
     readFileBytes(filePath: string, maxBytes?: number): Promise<Buffer>;
@@ -139,6 +137,10 @@ declare class SpritesFs implements VirtualFs {
     readFile(filePath: string, _opts?: ReadOptions): Promise<string>;
     readFileBytes(filePath: string, maxBytes?: number): Promise<Buffer>;
     writeFile(filePath: string, content: string): Promise<void>;
+    /**
+     * @warning Not atomic. Concurrent appends may lose data due to
+     * read-then-write TOCTOU. The Sprites API does not expose an append primitive.
+     */
     appendFile(filePath: string, content: string): Promise<void>;
     deleteFile(filePath: string, opts?: {
         recursive?: boolean;
@@ -245,6 +247,10 @@ declare class E2BFs implements VirtualFs {
     readFile(path: string, _opts?: ReadOptions): Promise<string>;
     readFileBytes(path: string, maxBytes?: number): Promise<Buffer>;
     writeFile(path: string, content: string): Promise<void>;
+    /**
+     * @warning Not atomic. Concurrent appends may lose data due to
+     * read-then-write TOCTOU. The E2B SDK does not expose an append primitive.
+     */
     appendFile(path: string, content: string): Promise<void>;
     deleteFile(path: string, _opts?: {
         recursive?: boolean;
@@ -259,6 +265,44 @@ declare class E2BFs implements VirtualFs {
     stat(path: string): Promise<FileStat>;
 }
 
+interface FreestyleFsOptions {
+    /** A Freestyle VM instance. */
+    vm: FreestyleVmInstance;
+    /** Working directory for relative path resolution. */
+    workingDir?: string;
+}
+/**
+ * VirtualFs backed by a Freestyle VM.
+ *
+ * Uses `vm.fs.*` for operations with native SDK support (readTextFile,
+ * writeTextFile, readDir) and falls back to `vm.exec()` for the rest
+ * (stat, exists, mkdir, deleteFile, appendFile, readFileBytes).
+ *
+ * Requires `freestyle-sandboxes` as an optional peer dependency.
+ * The user is responsible for VM lifecycle when using explicit mode.
+ */
+declare class FreestyleFs implements VirtualFs {
+    private vm;
+    private workingDir;
+    constructor(opts: FreestyleFsOptions);
+    private resolvePath;
+    readFile(filePath: string, _opts?: ReadOptions): Promise<string>;
+    readFileBytes(filePath: string, maxBytes?: number): Promise<Buffer>;
+    writeFile(filePath: string, content: string): Promise<void>;
+    appendFile(filePath: string, content: string): Promise<void>;
+    deleteFile(filePath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    mkdir(filePath: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(dirPath: string, _opts?: {
+        recursive?: boolean;
+    }): Promise<FileEntry[]>;
+    exists(filePath: string): Promise<boolean>;
+    stat(filePath: string): Promise<FileStat>;
+}
+
 /**
  * Resolve a tool flag that can be a static boolean or a function of the input.
  * Returns `defaultValue` when the flag is `undefined`.
@@ -394,6 +438,16 @@ interface ToolCallExecResult {
     result: ToolResult;
     /** When true, the result came from a permission denial — not actual tool execution */
     permissionDenied?: boolean;
+    /** When true, the turn loop should stop after processing this batch */
+    preventContinuation?: boolean;
+    /** Permission and lifecycle events emitted during execution */
+    events?: StreamEvent[];
+    /**
+     * Optional context modifier to apply after a concurrent batch completes.
+     * Applied in original tool_call order (not completion order) so state
+     * transitions are deterministic.
+     */
+    contextModifier?: () => void | Promise<void>;
 }
 type ToolCallExecutor = (toolCall: ToolCallContent, parsedArgs: Record<string, unknown>) => Promise<ToolCallExecResult>;
 interface Batch {
@@ -422,7 +476,7 @@ interface StreamingExecResult {
     preventContinuation?: boolean;
     events: StreamEvent[];
 }
-type StreamingToolExecutorFn = (toolCall: ToolCallContent, parsedArgs: Record<string, unknown>) => Promise<{
+type StreamingToolExecutorFn = (toolCall: ToolCallContent, parsedArgs: Record<string, unknown>, signal?: AbortSignal) => Promise<{
     result: ToolResult;
     permissionDenied?: boolean;
     preventContinuation?: boolean;
@@ -432,25 +486,29 @@ type StreamingToolExecutorFn = (toolCall: ToolCallContent, parsedArgs: Record<st
  * Executes tools as they arrive during model streaming.
  * Concurrency-safe tools run in parallel; unsafe tools wait for all prior
  * executions to finish before starting.
+ *
+ * Supports abort propagation: a parent signal aborts all tools, and a
+ * Bash tool error aborts sibling tools via siblingAbortController.
  */
 declare class StreamingToolExecutor {
     private readonly getTool;
     private readonly executeFn;
+    private readonly parentSignal?;
     private tools;
     private progressResolve?;
-    constructor(getTool: (name: string) => Tool | undefined, executeFn: StreamingToolExecutorFn);
+    private discarded;
+    private siblingAbortController;
+    private hasErrored;
+    private processingQueue;
+    constructor(getTool: (name: string) => Tool | undefined, executeFn: StreamingToolExecutorFn, parentSignal?: AbortSignal | undefined);
+    discard(): void;
+    isDiscarded(): boolean;
     addTool(toolCall: ToolCallContent, parsedArgs: Record<string, unknown>): void;
     private canExecute;
     private processQueue;
+    private createToolAbortController;
     private executeTool;
-    /**
-     * Synchronously yield any completed results (called during streaming).
-     * Preserves declaration order: stops before a non-safe executing tool.
-     */
     getCompletedResults(): Generator<StreamingExecResult, void>;
-    /**
-     * Async drain: waits for all in-flight tools then yields remaining results.
-     */
     getRemainingResults(): AsyncGenerator<StreamingExecResult, void>;
     private hasUnfinished;
     private hasExecuting;
@@ -513,7 +571,7 @@ declare function looksLikeBareRepo(dirEntries: string[]): boolean;
 /**
  * Check if a shell command targets git-internal paths for writes.
  * Scans for redirect operators (`>`, `>>`, `tee`) whose target is
- * inside `.git/`.
+ * inside `.git/` or matches a bare repo internal path.
  */
 declare function commandWritesGitInternals(command: string): boolean;
 
@@ -826,6 +884,13 @@ interface CompactOptions {
     stripBinaryContent?: boolean;
     /** Abort signal — if fired, the partial summary is discarded instead of persisted. */
     signal?: AbortSignal;
+    /**
+     * Recently-read file contents to reinject after compaction so the model
+     * doesn't lose awareness of files that were only in the compacted portion.
+     * Map of file path -> file content. At most 5 files are reinjected, capped
+     * at 50 KB total.
+     */
+    recentlyReadFiles?: Map<string, string>;
 }
 declare function compactConversation(provider: AIProvider, model: string, messages: ChatMessage[], storage: SessionStorage, sessionId: string, opts?: CompactOptions): Promise<ChatMessage[]>;
 /**
@@ -878,18 +943,26 @@ declare function estimateMessagesTokens(messages: Array<{
  */
 declare function tokenCountWithEstimation(messages: ChatMessage[], lastUsage?: ChatCompletionUsage, anchorMessageIndex?: number): number;
 /**
- * Group messages into API-round groups. A new group starts when an
- * assistant message follows a tool result (i.e. each model response
- * round). This gives finer-grained groups than splitting on user
- * messages, enabling PTL recovery in agentic sessions with many
- * tool-use rounds under a single user prompt.
+ * Group messages into API-round groups. A new group starts at each
+ * assistant boundary (after tool results) or user message. This gives
+ * finer-grained groups than splitting on user messages alone, enabling
+ * PTL recovery in agentic sessions with many tool-use rounds.
  */
 declare function groupMessagesByTurn(messages: ChatMessage[]): ChatMessage[][];
+interface PTLRetryOptions {
+    /** Tokens the server reported we need to shed, or undefined if unknown. */
+    tokenGap?: number;
+    /** Effective context window for this model (fallback when gap unknown). */
+    targetTokens: number;
+}
 /**
- * Drop the oldest turn groups until estimated tokens drop below `targetTokens`.
- * Returns the trimmed message list. Used for prompt-too-long recovery.
+ * Drop the oldest turn groups to fit within the context window.
+ *
+ * If `tokenGap` is provided (parsed from the server error), use it to
+ * determine exactly how many tokens to shed. Otherwise fall back to
+ * dropping 20% of groups (more conservative than the heuristic target).
  */
-declare function truncateHeadForPTLRetry(messages: ChatMessage[], targetTokens: number): ChatMessage[];
+declare function truncateHeadForPTLRetry(messages: ChatMessage[], targetOrOpts: number | PTLRetryOptions): ChatMessage[];
 
 declare function buildSystemPrompt(opts: {
     customPrompt?: string;
@@ -948,6 +1021,9 @@ declare function toolMatchesRule(toolName: string, rule: PermissionRule, mcpInfo
  *  - **exact**: `ruleContent === content`
  *  - **prefix**: `ruleContent` ends with `:*` → prefix match
  *  - **glob**: `ruleContent` contains `*` or `**` → simple glob match
+ *
+ * For deny/ask rules, also tries matching after stripping env vars and
+ * safe wrapper commands from the content.
  */
 declare function contentMatchesRule(content: string, ruleContent: string): boolean;
 /**
@@ -970,6 +1046,46 @@ declare function getMatchingRules(context: PermissionContext, toolName: string,
  */
 declare function isPathInWorkingDirectories(filePath: string, workingDirectories: string[]): boolean;
 
+interface DenialLimits {
+    maxConsecutive: number;
+    maxTotal: number;
+}
+interface DenialState {
+    consecutiveDenials: number;
+    totalDenials: number;
+}
+type FallbackCheck = {
+    triggered: false;
+} | {
+    triggered: true;
+    reason: "consecutive" | "total" | "repeated_consecutive";
+};
+/**
+ * Tracks permission denials and determines when limits are exceeded.
+ * When limits are hit, the system should fall back to prompting or abort.
+ */
+declare class DenialTracker {
+    private state;
+    private limits;
+    private consecutiveFallbacksWithoutSuccess;
+    constructor(limits?: Partial<DenialLimits>);
+    recordDenial(): void;
+    recordSuccess(): void;
+    shouldFallback(): FallbackCheck;
+    /**
+     * Reset counters after a fallback. Only resets totalDenials when the
+     * total limit was the trigger — consecutive-only fallbacks preserve
+     * the total counter so the session-wide safety net stays effective.
+     *
+     * Tracks repeated consecutive fallbacks: if `resetAfterFallback("consecutive")`
+     * is called again without an intervening `recordSuccess()`, the next
+     * `shouldFallback()` returns `"repeated_consecutive"` to signal escalation.
+     */
+    resetAfterFallback(trigger: "consecutive" | "total"): void;
+    getState(): Readonly<DenialState>;
+    reset(): void;
+}
+
 /**
  * Resolve the permission decision for a tool invocation.
  *
@@ -987,6 +1103,7 @@ interface ResolvePermissionOptions {
     recentMessages?: ChatMessage[];
     autoModeConfig?: AutoModeConfig;
     signal?: AbortSignal;
+    denialTracker?: DenialTracker;
 }
 declare function resolvePermission(tool: Tool, input: Record<string, unknown>, ctx: ToolContext, permCtx: PermissionContext, opts?: ResolvePermissionOptions): Promise<PermissionDecision>;
 
@@ -1000,29 +1117,6 @@ declare function applyPermissionUpdate(ctx: PermissionContext, update: Permissio
  */
 declare function applyPermissionUpdates(ctx: PermissionContext, updates: PermissionUpdate[]): PermissionContext;
 
-interface DenialLimits {
-    maxConsecutive: number;
-    maxTotal: number;
-}
-interface DenialState {
-    consecutiveDenials: number;
-    totalDenials: number;
-}
-/**
- * Tracks permission denials and determines when limits are exceeded.
- * When limits are hit, the system should fall back to prompting or abort.
- */
-declare class DenialTracker {
-    private state;
-    private limits;
-    constructor(limits?: Partial<DenialLimits>);
-    recordDenial(): void;
-    recordSuccess(): void;
-    shouldFallback(): boolean;
-    getState(): Readonly<DenialState>;
-    reset(): void;
-}
-
 interface ClassifierResult {
     shouldBlock: boolean;
     reason: string;
@@ -1087,18 +1181,13 @@ declare function isRetryable(classified: ClassifiedError, config: RetryConfig):
  * If a Retry-After header value is provided (seconds), it takes precedence.
  * Ported from claude-code's getRetryDelay with the same formula.
  */
-declare function getRetryDelay(attempt: number, retryAfterHeader?: string | null, maxDelayMs?: number): number;
+declare function getRetryDelay(attempt: number, retryAfterHeader?: string | null, maxDelayMs?: number, baseDelayMs?: number): number;
 
 declare class CannotRetryError extends Error {
     readonly originalError: unknown;
     readonly retryContext: RetryContext;
     constructor(originalError: unknown, retryContext: RetryContext);
 }
-declare class FallbackTriggeredError extends Error {
-    readonly originalModel: string;
-    readonly fallbackModel: string;
-    constructor(originalModel: string, fallbackModel: string);
-}
 /**
  * Retry engine that wraps a stream-creating operation.
  * Yields retry_attempt events while waiting, then returns the stream on success.
@@ -1251,12 +1340,46 @@ declare function createCacheSafeParams(opts: {
     thinking?: ThinkingConfig;
 }): CacheSafeParams;
 
+/**
+ * Centralized message normalization for API calls.
+ *
+ * Ensures a ChatMessage[] is structurally valid before being sent to any
+ * provider. Handles duplicate tool IDs, orphaned results, missing pairing,
+ * empty assistants, consecutive same-role messages, and other corruption
+ * from error/abort/compaction paths.
+ *
+ * Pure function: returns a new array, never mutates the input.
+ */
+
+/**
+ * Normalize a message array so it is structurally valid for any LLM API.
+ *
+ * Transformations applied (order matters):
+ *  1. Drop system messages (system prompt is a separate param)
+ *  2. Deduplicate tool_use IDs across assistants
+ *  3. Strip orphaned tool_results with no matching tool_use
+ *  4. Deduplicate tool_results with the same tool_call_id
+ *  5. Insert synthetic error results for unpaired tool_uses
+ *  6. Filter orphaned thinking-only assistants (null/undefined content)
+ *  7. Filter whitespace-only assistant messages
+ *  8. Merge consecutive same-role messages
+ *  9. Ensure every assistant has non-null content
+ * 10. Strip thinking-only trailing assistant (after merge — merge can
+ *     create new trailing messages with only thinking content)
+ * 11. Ensure array starts with a user message
+ */
+declare function normalizeMessagesForAPI(messages: ChatMessage[]): ChatMessage[];
+
 /**
  * Conversation recovery and message sanitization.
  *
  * Cleans up persisted messages before resuming a session so the API
  * receives a structurally valid conversation. Handles crashes, streaming
  * interruptions, orphaned tool calls, and whitespace-only messages.
+ *
+ * Shared normalization primitives (merge, filter, pairing) live in
+ * `src/messages/normalize.ts` and are re-exported here for backward
+ * compatibility.
  */
 
 type TurnInterruption = {
@@ -1299,10 +1422,6 @@ declare function filterWhitespaceOnlyAssistantMessages(messages: ChatMessage[]):
  * real text and no tool_calls). These are artifacts of streaming
  * interruptions where a thinking block was streamed but the model
  * never produced a real response.
- *
- * In noumen's format, thinking content appears as `content: null`
- * with no tool_calls (the thinking deltas were streamed separately).
- * We detect these as assistants with null/empty content and no calls.
  */
 declare function filterOrphanedThinkingMessages(messages: ChatMessage[]): {
     messages: ChatMessage[];
@@ -1372,6 +1491,37 @@ interface ResumePayload {
  */
 declare function restoreSession(storage: SessionStorage, sessionId: string): Promise<ResumePayload>;
 
+/**
+ * Runtime invariant assertions for normalized message sequences.
+ *
+ * `assertValidMessageSequence` throws an `InvariantViolation` error
+ * when a ChatMessage[] violates the structural rules that every LLM
+ * provider expects. Wire it behind a `debug` flag in thread.ts to
+ * catch normalization regressions during development and testing.
+ */
+
+declare class InvariantViolation extends Error {
+    constructor(message: string);
+}
+/**
+ * Assert that `messages` is a structurally valid sequence for the LLM API.
+ *
+ * Checks:
+ *  1. Non-empty (at least one message)
+ *  2. First message has role "user"
+ *  3. No system messages
+ *  4. No consecutive same-role (non-tool) messages
+ *  5. Every tool_use has exactly one matching tool result
+ *  6. No orphaned tool results (no matching tool_use)
+ *  7. No duplicate tool_use IDs
+ *  8. No duplicate tool_result IDs
+ *  9. No assistant with null/undefined content
+ * 10. No whitespace-only assistant without tool_calls or thinking_content
+ * 11. Trailing assistant must not be thinking-only (no text, no tool_calls)
+ * 12. Tool results appear in a contiguous block after their owning assistant
+ */
+declare function assertValidMessageSequence(messages: ChatMessage[]): void;
+
 declare const STRUCTURED_OUTPUT_TOOL_NAME = "StructuredOutput";
 /**
  * Creates a synthetic tool whose input schema matches the user's desired
@@ -1435,4 +1585,4 @@ declare const IMAGE_EXTENSIONS: Set<string>;
  */
 declare function createImageMetadataText(dims: ImageDimensions): string;
 
-export { AIProvider, API_IMAGE_MAX_BASE64_SIZE, Agent, AssistantMessage, AutoModeConfig, type CacheSafeParams, CannotRetryError, ChatCompletionUsage, ChatMessage, ChatStreamChunk, type ClassifiedError, type ClassifierResult, type CommandClassification, CommandResult, type CompactOptions, type CompressedImageResult, ContentPart, ContentReplacementRecord, ContextFile, ContextScope, DEFAULT_PRICING, type DenialLimits, type DenialState, DenialTracker, DockerContainer, DockerFs, type DockerFsOptions, E2BFs, type E2BFsOptions, E2BSandboxInstance, ExecOptions, type ExtractMemoriesResult, FallbackTriggeredError, FileCheckpointSnapshot, FileEntry, FileMemoryProvider, FileStat, type FrontmatterData, type GitOperationEvent, type GitOperationType, HookDefinition, HookEvent, HookInput, IMAGE_EXTENSIONS, IMAGE_MAX_HEIGHT, IMAGE_MAX_WIDTH, type ImageDimensions, InProcessBackend, type IndexTruncation, JsonSchemaOutputFormat, LocalComputer, type LocalComputerOptions, LocalFs, type LocalFsOptions, Mailbox, McpServerConfig, MemoryEntry, MemoryProvider, ModelPricing, NoopSpan, NoopTracer, OTelTracer, type OllamaProviderOptions, type ParsedFrontmatter, PermissionBehavior, PermissionContext, PermissionDecision, PermissionHandler, PermissionRule, PermissionUpdate, PostToolUseFailureHookInput, PostToolUseFailureHookOutput, PostToolUseHookInput, PostToolUseHookOutput, PreToolUseHookInput, PreToolUseHookOutput, type PresetOptions, ProjectContextConfig, ReadOptions, type ResizedImage, type ResolvePermissionOptions, type ResumePayload, RetryConfig, RetryContext, RetryEngineOptions, STRUCTURED_OUTPUT_TOOL_NAME, Sandbox, type SanitizeResult, type ShellSafetyConfig, SkillDefinition, Span, SpanAttributeValue, SpanOptions, SpanStatusCode, SpritesComputer, type SpritesComputerOptions, SpritesFs, type SpritesFsOptions, StoredCostState, StreamEvent, type StreamingExecResult, StreamingToolExecutor, type StreamingToolExecutorFn, type SwarmBackend, type SwarmConfig, type SwarmEvents, SwarmManager, type SwarmMember, type SwarmMemberConfig, type SwarmMemberStatus, type SwarmMessage, type SwarmStatus, TOOL_SEARCH_NAME, ThinkingConfig, ThreadConfig, Tool, ToolCallContent, type ToolCallExecResult, type ToolCallExecutor, ToolResult as ToolCallResult, ToolContext, ToolDefinition, ToolRegistry, ToolResultMessage, ToolResultOverflowEntry, type ToolWithDeferral, Tracer, type TurnInterruption, UsageRecord, type UserInputHandler, VirtualComputer, VirtualFs, type WorktreeInfo, activateContextForPaths, activateSkillsForPaths, agentTool, all, applyPermissionUpdate, applyPermissionUpdates, askUserTool, bashTool, buildExtractionPrompt, buildMemorySystemPromptSection, buildProjectContextSection, buildSystemPrompt, calculateCost, classifyCommand, classifyError, classifyPermission, codingAgent, commandWritesGitInternals, compactConversation, compressImageBufferWithTokenLimit, contentMatchesRule, contentToString, countOccurrences, createCacheSafeParams, createImageMetadataText, createSkillTool, createStructuredOutputTool, createToolSearchTool, createWorktree, detectGitOperations, detectTurnInterruption, editFileTool, enterPlanModeTool, enterWorktreeTool, estimateCompactionSavings, estimateMessagesTokens, estimateTokens, exitPlanModeTool, exitWorktreeTool, extractCommandName, extractMemories, filterActiveContextFiles, filterOrphanedThinkingMessages, filterUnresolvedToolUses, filterWhitespaceOnlyAssistantMessages, findActualString, findGitRoot, findModelPricing, formatDeferredToolLine, generateMissingToolResults, getActiveSkills, getAutoCompactThreshold, getContextWindowForModel, getEffectiveContextWindow, getLastCacheSafeParams, getMatchingRules, getRetryDelay, getWorktreeChanges, globTool, grepTool, groupMessagesByTurn, hasGitIndexLockError, hasImageContent, isDeferredTool, isGitInternalPath, isPathInWorkingDirectories, isRetryable, listWorktrees, loadProjectContext, loadSkills, looksLikeBareRepo, matchSimpleGlob, maybeResizeAndDownsampleImageBlock, maybeResizeAndDownsampleImageBuffer, normalizeContent, normalizeQuotes, notebookEditTool, parseAllowedTools, parseFrontmatter, parsePaths, partitionToolCalls, planningAgent, preserveQuoteStyle, readFileTool, registerContextWindows, removeWorktree, resolvePermission, resolveToolFlag, restoreSession, reviewAgent, runNotificationHooks, runPostToolUseFailureHooks, runPostToolUseHooks, runPreToolUseHooks, runToolsBatched, sanitizeForResume, sanitizeWorktreeSlug, saveCacheSafeParams, searchToolsWithKeywords, stripImageContent, stripTrailingWhitespace, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, tokenCountWithEstimation, toolMatchesRule, truncateHeadForPTLRetry, truncateIndex, webFetchTool, withRetry, writeFileTool };
+export { AIProvider, API_IMAGE_MAX_BASE64_SIZE, Agent, AssistantMessage, AutoModeConfig, type CacheSafeParams, CannotRetryError, ChatCompletionUsage, ChatMessage, ChatStreamChunk, type ClassifiedError, type ClassifierResult, type CommandClassification, CommandResult, type CompactOptions, type CompressedImageResult, ContentPart, ContentReplacementRecord, ContextFile, ContextScope, DEFAULT_PRICING, type DenialLimits, type DenialState, DenialTracker, DockerContainer, DockerFs, type DockerFsOptions, E2BFs, type E2BFsOptions, E2BSandboxInstance, ExecOptions, type ExtractMemoriesResult, FileCheckpointSnapshot, FileEntry, FileMemoryProvider, FileStat, FreestyleFs, type FreestyleFsOptions, FreestyleVmInstance, type FrontmatterData, type GitOperationEvent, type GitOperationType, HookDefinition, HookEvent, HookInput, IMAGE_EXTENSIONS, IMAGE_MAX_HEIGHT, IMAGE_MAX_WIDTH, type ImageDimensions, InProcessBackend, type IndexTruncation, InvariantViolation, JsonSchemaOutputFormat, LocalComputer, type LocalComputerOptions, LocalFs, type LocalFsOptions, Mailbox, McpServerConfig, MemoryEntry, MemoryProvider, ModelPricing, NoopSpan, NoopTracer, OTelTracer, type ParsedFrontmatter, PermissionBehavior, PermissionContext, PermissionDecision, PermissionHandler, PermissionRule, PermissionUpdate, PostToolUseFailureHookInput, PostToolUseFailureHookOutput, PostToolUseHookInput, PostToolUseHookOutput, PreToolUseHookInput, PreToolUseHookOutput, type PresetOptions, ProjectContextConfig, ReadOptions, type ResizedImage, type ResolvePermissionOptions, type ResumePayload, RetryConfig, RetryContext, RetryEngineOptions, STRUCTURED_OUTPUT_TOOL_NAME, Sandbox, type SanitizeResult, type ShellSafetyConfig, SkillDefinition, Span, SpanAttributeValue, SpanOptions, SpanStatusCode, SpritesComputer, type SpritesComputerOptions, SpritesFs, type SpritesFsOptions, StoredCostState, StreamEvent, type StreamingExecResult, StreamingToolExecutor, type StreamingToolExecutorFn, type SwarmBackend, type SwarmConfig, type SwarmEvents, SwarmManager, type SwarmMember, type SwarmMemberConfig, type SwarmMemberStatus, type SwarmMessage, type SwarmStatus, TOOL_SEARCH_NAME, ThinkingConfig, ThreadConfig, Tool, ToolCallContent, type ToolCallExecResult, type ToolCallExecutor, ToolResult as ToolCallResult, ToolContext, ToolDefinition, ToolRegistry, ToolResultMessage, ToolResultOverflowEntry, type ToolWithDeferral, Tracer, type TurnInterruption, UsageRecord, type UserInputHandler, VirtualComputer, VirtualFs, type WorktreeInfo, activateContextForPaths, activateSkillsForPaths, agentTool, all, applyPermissionUpdate, applyPermissionUpdates, askUserTool, assertValidMessageSequence, bashTool, buildExtractionPrompt, buildMemorySystemPromptSection, buildProjectContextSection, buildSystemPrompt, calculateCost, classifyCommand, classifyError, classifyPermission, codingAgent, commandWritesGitInternals, compactConversation, compressImageBufferWithTokenLimit, contentMatchesRule, contentToString, countOccurrences, createCacheSafeParams, createImageMetadataText, createSkillTool, createStructuredOutputTool, createToolSearchTool, createWorktree, detectGitOperations, detectTurnInterruption, editFileTool, enterPlanModeTool, enterWorktreeTool, estimateCompactionSavings, estimateMessagesTokens, estimateTokens, exitPlanModeTool, exitWorktreeTool, extractCommandName, extractMemories, filterActiveContextFiles, filterOrphanedThinkingMessages, filterUnresolvedToolUses, filterWhitespaceOnlyAssistantMessages, findActualString, findGitRoot, findModelPricing, formatDeferredToolLine, generateMissingToolResults, getActiveSkills, getAutoCompactThreshold, getContextWindowForModel, getEffectiveContextWindow, getLastCacheSafeParams, getMatchingRules, getRetryDelay, getWorktreeChanges, globTool, grepTool, groupMessagesByTurn, hasGitIndexLockError, hasImageContent, isDeferredTool, isGitInternalPath, isPathInWorkingDirectories, isRetryable, listWorktrees, loadProjectContext, loadSkills, looksLikeBareRepo, matchSimpleGlob, maybeResizeAndDownsampleImageBlock, maybeResizeAndDownsampleImageBuffer, normalizeContent, normalizeMessagesForAPI, normalizeQuotes, notebookEditTool, parseAllowedTools, parseFrontmatter, parsePaths, partitionToolCalls, planningAgent, preserveQuoteStyle, readFileTool, registerContextWindows, removeWorktree, resolvePermission, resolveToolFlag, restoreSession, reviewAgent, runNotificationHooks, runPostToolUseFailureHooks, runPostToolUseHooks, runPreToolUseHooks, runToolsBatched, sanitizeForResume, sanitizeWorktreeSlug, saveCacheSafeParams, searchToolsWithKeywords, stripImageContent, stripTrailingWhitespace, taskCreateTool, taskGetTool, taskListTool, taskUpdateTool, tokenCountWithEstimation, toolMatchesRule, truncateHeadForPTLRetry, truncateIndex, webFetchTool, withRetry, writeFileTool };