@prestyj/agent 5.28.1 → 5.29.1

package/dist/index.d.cts

@@ -1,6 +1,82 @@
-import { StreamOptions, Message, Tool, ToolResultContent, ServerToolDefinition, Usage, StopReason, AssistantMessage } from '@prestyj/ai';
+import { Message, StreamOptions, Tool, ToolResultContent, ServerToolDefinition, Usage, StopReason, AssistantMessage } from '@prestyj/ai';
 import { z } from 'zod';
 
+/**
+ * Stream rules: regex guards matched against a response WHILE it streams.
+ *
+ * A rule costs zero prompt tokens until the model actually breaks it. On a
+ * match the agent loop aborts the in-flight response, discards the partial
+ * assistant message (nothing is persisted, no partial tool call runs), appends
+ * the rule's reminder as a hidden runtime note, and retries the same step.
+ *
+ * Matching is incremental: each stream (assistant text, or one tool call's
+ * argument JSON) keeps a bounded rolling window, so a delta is scanned together
+ * with only the last `windowChars` characters before it — never the whole
+ * output. A pattern whose match spans more than the window is not detected.
+ *
+ * Tool-call arguments arrive as JSON text; they are unescaped incrementally so
+ * rules see `\n`, `"`, etc. as the model meant them, not as JSON escapes.
+ */
+
+/** Which streamed output a rule watches. Thinking is never matched. */
+type StreamRuleScope = "text" | "tool" | "both";
+interface StreamRule {
+    /** Stable identifier; also the once-per-run dedupe key. */
+    name: string;
+    /** Pattern tested against the rolling window. `g`/`y` flags are tolerated. */
+    pattern: RegExp;
+    scope: StreamRuleScope;
+    /** Reminder appended to the context when the rule fires. */
+    reminder: string;
+    /** Restrict tool-scope matching to these tool names. Unset = every tool. */
+    tools?: readonly string[];
+}
+interface StreamRulesConfig {
+    rules: readonly StreamRule[];
+    /** Rule-triggered retries allowed per agent run (one user turn). Default 3. */
+    maxRetries?: number;
+    /** Characters of prior output kept per stream for cross-delta matches. Default 1024. */
+    windowChars?: number;
+}
+type StreamRuleSource = "text" | "tool";
+interface StreamRuleMatch {
+    rules: StreamRule[];
+    source: StreamRuleSource;
+    toolName?: string;
+}
+declare const DEFAULT_STREAM_RULE_MAX_RETRIES = 3;
+declare const DEFAULT_STREAM_RULE_WINDOW_CHARS = 1024;
+/** Incremental JSON string-escape decoder that tolerates escapes split across chunks. */
+declare class JsonEscapeDecoder {
+    private pending;
+    push(chunk: string): string;
+}
+/**
+ * Per-run rule state. Create one per `agentLoop` run; call `beginAttempt()`
+ * before every provider attempt so windows never leak across attempts.
+ */
+declare class StreamRuleMonitor {
+    readonly maxRetries: number;
+    private readonly rules;
+    private readonly windowChars;
+    private readonly fired;
+    private retries;
+    private textWindow;
+    private readonly toolStreams;
+    constructor(config: StreamRulesConfig);
+    /** False once the retry cap is spent or every rule has fired — skip all matching. */
+    get active(): boolean;
+    get retriesUsed(): number;
+    beginAttempt(): void;
+    checkText(delta: string): StreamRuleMatch | null;
+    checkToolArgs(id: string, toolName: string, argsDelta: string): StreamRuleMatch | null;
+    /** Consume one retry and mark the rules fired. Returns the retry ordinal (1-based). */
+    recordTrigger(rules: readonly StreamRule[]): number;
+    private match;
+}
+/** The hidden runtime note appended before the retry. */
+declare function buildStreamRuleReminder(rules: readonly StreamRule[]): Message;
+
 interface StructuredToolResult {
     content: ToolResultContent;
     details?: unknown;
@@ -27,6 +103,12 @@ interface AgentTool<T extends z.ZodType = z.ZodType> extends Tool {
      * message — becomes unreachable.
      */
     timeoutMs?: number;
+    /**
+     * Whether a mid-run steering message may preempt this tool. Defaults to
+     * true, except for atomic file mutators (`edit`, `write`, …) which always
+     * run to completion so they are never left half-applied.
+     */
+    interruptible?: boolean;
     execute: (args: z.infer<T>, context: ToolContext) => ToolExecuteResult | Promise<ToolExecuteResult>;
 }
 interface AgentTextDeltaEvent {
@@ -146,7 +228,7 @@ interface AgentTruncatedEvent {
 }
 interface AgentRetryEvent {
     type: "retry";
-    reason: "overloaded" | "rate_limit" | "provider_error" | "empty_response" | "stream_stall" | "overflow_compact" | "tool_argument_glitch" | "runaway_toolcall";
+    reason: "overloaded" | "rate_limit" | "provider_error" | "empty_response" | "stream_stall" | "overflow_compact" | "tool_argument_glitch" | "runaway_toolcall" | "stream_rule";
     attempt: number;
     maxAttempts: number;
     delayMs: number;
@@ -164,6 +246,29 @@ interface AgentRetryEvent {
      */
     preservedChars?: number;
 }
+/**
+ * A stream rule matched mid-response. The attempt was aborted and discarded
+ * (no partial message persisted, no partial tool call executed), the rule's
+ * reminder was appended to the context, and the step is retried. Always
+ * followed by a silent `retry` (reason `stream_rule`) so UIs roll back the
+ * streamed partial exactly as for any other replayed attempt.
+ */
+interface AgentStreamRuleTriggeredEvent {
+    type: "stream_rule_triggered";
+    /** Names of the rules that matched (usually one). */
+    rules: string[];
+    source: "text" | "tool";
+    /** Tool whose streamed arguments matched, for `source: "tool"`. */
+    toolName?: string;
+    attempt: number;
+    maxAttempts: number;
+    /**
+     * ESTIMATED usage of the aborted attempt (providers report none for an
+     * aborted stream): prompt chars/4 in, streamed chars/4 out. Already added to
+     * the run's `totalUsage`.
+     */
+    usage: Usage;
+}
 interface AgentToolCallDeltaEvent {
     type: "toolcall_delta";
     chars: number;
@@ -192,7 +297,7 @@ interface AgentFollowUpMessageEvent {
     type: "follow_up_message";
     content: Message["content"];
 }
-type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentCheckpointEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTurnBudgetExtendedEvent | AgentTruncatedEvent | AgentErrorEvent;
+type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentStreamRuleTriggeredEvent | AgentTurnEndEvent | AgentCheckpointEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTurnBudgetExtendedEvent | AgentTruncatedEvent | AgentErrorEvent;
 interface TransformContextOptions {
     /** Force a transform after the provider reports context overflow. */
     force?: boolean;
@@ -244,6 +349,7 @@ interface AgentOptions {
     transportSessionId?: StreamOptions["transportSessionId"];
     projectId?: StreamOptions["projectId"];
     cacheRetention?: StreamOptions["cacheRetention"];
+    onContextPrepared?: StreamOptions["onContextPrepared"];
     /** Stable per-session cache routing key for providers that support it. */
     promptCacheKey?: StreamOptions["promptCacheKey"];
     /** Override the User-Agent sent with OAuth-authenticated Anthropic requests. */
@@ -253,6 +359,10 @@ interface AgentOptions {
     defaultHeaders?: StreamOptions["defaultHeaders"];
     /** OpenAI service tier for latency-sensitive first-party API requests. */
     serviceTier?: StreamOptions["serviceTier"];
+    /** Codex Responses-Lite request shape override (see StreamOptions). */
+    responsesLite?: StreamOptions["responsesLite"];
+    /** Codex strict tool schema override (see StreamOptions). */
+    strictTools?: StreamOptions["strictTools"];
     /** Whether the target model supports image input. When false, image blocks
      *  in messages/tool_results are downgraded to text placeholders. Default: true. */
     supportsImages?: boolean;
@@ -271,6 +381,14 @@ interface AgentOptions {
      *  against parallel fan-outs injecting huge uncached context in one turn;
      *  the largest results are trimmed (water-filling) with a re-run notice. */
     maxTurnToolResultChars?: number;
+    /** Optional post-processing of a SUCCESSFUL tool result (after redaction,
+     *  before the tool_call_end event and the provider context). Return the
+     *  content unchanged to leave it alone. A throw is ignored (original kept).
+     *  Used e.g. to append a warning to untrusted-content results. */
+    transformToolResult?: (call: {
+        name: string;
+        args: Record<string, unknown>;
+    }, content: ToolResultContent) => ToolResultContent;
     /** Max consecutive pause_turn continuations before stopping (default: 5).
      *  Prevents infinite loops when server-side tools keep pausing. */
     maxContinuations?: number;
@@ -292,6 +410,15 @@ interface AgentOptions {
      * on read.
      */
     getSteeringMessages?: () => Promise<Message[] | null> | Message[] | null;
+    /**
+     * Instant interrupt (codex `instant_interrupt`): subscribe to "a steering
+     * message just arrived". While tools are running, the listener preempts
+     * interruptible tools (their AbortSignal fires; unfinished calls get an
+     * "Interrupted" error result) and the loop drains steering and continues.
+     * Distinct from `signal` (the Stop button), which ends the run. Returns an
+     * unsubscribe function.
+     */
+    onSteeringAvailable?: (listener: () => void) => () => void;
     /**
      * Polled when the agent would otherwise stop (no tool calls, no steering).
      * Returns messages to inject and continue the loop. Lower priority than
@@ -312,6 +439,13 @@ interface AgentOptions {
         maxTurns: number;
         extension: number;
     }) => Promise<boolean> | boolean;
+    /**
+     * Regex rules matched against streamed assistant text and tool-call
+     * arguments. A match aborts the attempt, discards it, appends the rule's
+     * reminder and retries the step. Each rule fires at most once per run;
+     * `maxRetries` (default 3) caps rule retries per run. Unset = no matching.
+     */
+    streamRules?: StreamRulesConfig;
 }
 interface AgentResult {
     message: AssistantMessage;
@@ -349,6 +483,7 @@ declare class Agent {
     private options;
     private steeringQueue;
     private followUpQueue;
+    private steeringListeners;
     constructor(options: AgentOptions);
     /** Snapshot of the current message history. Used for session persistence. */
     getMessages(): Message[];
@@ -359,7 +494,11 @@ declare class Agent {
      */
     setSignal(signal: AbortSignal | undefined): void;
     get running(): boolean;
-    /** Queue a steering message for injection after current tool execution completes. */
+    /**
+     * Queue a steering message. Instant interrupt: if tools are running, the
+     * interruptible ones are preempted right away and the message is injected
+     * before the next model call (the turn continues — unlike abort/Stop).
+     */
     steer(msg: Message): void;
     /** Queue a follow-up message for injection when the agent would otherwise stop. */
     followUp(msg: Message): void;
@@ -415,6 +554,7 @@ declare function cancelledBeforeStartText(name: string): string;
  * something never ran when it did.
  */
 declare function indeterminateOutcomeText(name: string): string;
+declare function repairToolPairingAdjacent(messages: Message[]): void;
 
 /**
  * A local inference server (llama.cpp, vLLM, Ollama, LM Studio) can spend
@@ -425,4 +565,4 @@ declare function indeterminateOutcomeText(name: string): string;
  */
 declare function isLocalBackendUrl(baseUrl?: string): boolean;
 
-export { Agent, type AgentDoneEvent, type AgentErrorEvent, type AgentEvent, type AgentFollowUpMessageEvent, type AgentOptions, type AgentResult, type AgentRetryEvent, type AgentServerToolCallEvent, type AgentServerToolResultEvent, type AgentSteeringMessageEvent, AgentStream, type AgentTextDeltaEvent, type AgentThinkingDeltaEvent, type AgentTool, type AgentToolCallDeltaEvent, type AgentToolCallEndEvent, type AgentToolCallStartEvent, type AgentToolCallUpdateEvent, type AgentTurnEndEvent, type AgentTurnTiming, type StreamDiagnosticFn, type StructuredToolResult, type ToolContext, type ToolExecuteResult, type ToolExecutionMode, type TransformContextOptions, agentLoop, cancelledBeforeStartText, indeterminateOutcomeText, isAbortError, isBillingError, isContextOverflow, isLocalBackendUrl, isUsageLimitError, setStreamDiagnostic };
+export { Agent, type AgentDoneEvent, type AgentErrorEvent, type AgentEvent, type AgentFollowUpMessageEvent, type AgentOptions, type AgentResult, type AgentRetryEvent, type AgentServerToolCallEvent, type AgentServerToolResultEvent, type AgentSteeringMessageEvent, AgentStream, type AgentStreamRuleTriggeredEvent, type AgentTextDeltaEvent, type AgentThinkingDeltaEvent, type AgentTool, type AgentToolCallDeltaEvent, type AgentToolCallEndEvent, type AgentToolCallStartEvent, type AgentToolCallUpdateEvent, type AgentTurnEndEvent, type AgentTurnTiming, DEFAULT_STREAM_RULE_MAX_RETRIES, DEFAULT_STREAM_RULE_WINDOW_CHARS, JsonEscapeDecoder, type StreamDiagnosticFn, type StreamRule, type StreamRuleMatch, StreamRuleMonitor, type StreamRuleScope, type StreamRuleSource, type StreamRulesConfig, type StructuredToolResult, type ToolContext, type ToolExecuteResult, type ToolExecutionMode, type TransformContextOptions, agentLoop, buildStreamRuleReminder, cancelledBeforeStartText, indeterminateOutcomeText, isAbortError, isBillingError, isContextOverflow, isLocalBackendUrl, isUsageLimitError, repairToolPairingAdjacent, setStreamDiagnostic };

package/dist/index.d.ts

@@ -1,6 +1,82 @@
-import { StreamOptions, Message, Tool, ToolResultContent, ServerToolDefinition, Usage, StopReason, AssistantMessage } from '@prestyj/ai';
+import { Message, StreamOptions, Tool, ToolResultContent, ServerToolDefinition, Usage, StopReason, AssistantMessage } from '@prestyj/ai';
 import { z } from 'zod';
 
+/**
+ * Stream rules: regex guards matched against a response WHILE it streams.
+ *
+ * A rule costs zero prompt tokens until the model actually breaks it. On a
+ * match the agent loop aborts the in-flight response, discards the partial
+ * assistant message (nothing is persisted, no partial tool call runs), appends
+ * the rule's reminder as a hidden runtime note, and retries the same step.
+ *
+ * Matching is incremental: each stream (assistant text, or one tool call's
+ * argument JSON) keeps a bounded rolling window, so a delta is scanned together
+ * with only the last `windowChars` characters before it — never the whole
+ * output. A pattern whose match spans more than the window is not detected.
+ *
+ * Tool-call arguments arrive as JSON text; they are unescaped incrementally so
+ * rules see `\n`, `"`, etc. as the model meant them, not as JSON escapes.
+ */
+
+/** Which streamed output a rule watches. Thinking is never matched. */
+type StreamRuleScope = "text" | "tool" | "both";
+interface StreamRule {
+    /** Stable identifier; also the once-per-run dedupe key. */
+    name: string;
+    /** Pattern tested against the rolling window. `g`/`y` flags are tolerated. */
+    pattern: RegExp;
+    scope: StreamRuleScope;
+    /** Reminder appended to the context when the rule fires. */
+    reminder: string;
+    /** Restrict tool-scope matching to these tool names. Unset = every tool. */
+    tools?: readonly string[];
+}
+interface StreamRulesConfig {
+    rules: readonly StreamRule[];
+    /** Rule-triggered retries allowed per agent run (one user turn). Default 3. */
+    maxRetries?: number;
+    /** Characters of prior output kept per stream for cross-delta matches. Default 1024. */
+    windowChars?: number;
+}
+type StreamRuleSource = "text" | "tool";
+interface StreamRuleMatch {
+    rules: StreamRule[];
+    source: StreamRuleSource;
+    toolName?: string;
+}
+declare const DEFAULT_STREAM_RULE_MAX_RETRIES = 3;
+declare const DEFAULT_STREAM_RULE_WINDOW_CHARS = 1024;
+/** Incremental JSON string-escape decoder that tolerates escapes split across chunks. */
+declare class JsonEscapeDecoder {
+    private pending;
+    push(chunk: string): string;
+}
+/**
+ * Per-run rule state. Create one per `agentLoop` run; call `beginAttempt()`
+ * before every provider attempt so windows never leak across attempts.
+ */
+declare class StreamRuleMonitor {
+    readonly maxRetries: number;
+    private readonly rules;
+    private readonly windowChars;
+    private readonly fired;
+    private retries;
+    private textWindow;
+    private readonly toolStreams;
+    constructor(config: StreamRulesConfig);
+    /** False once the retry cap is spent or every rule has fired — skip all matching. */
+    get active(): boolean;
+    get retriesUsed(): number;
+    beginAttempt(): void;
+    checkText(delta: string): StreamRuleMatch | null;
+    checkToolArgs(id: string, toolName: string, argsDelta: string): StreamRuleMatch | null;
+    /** Consume one retry and mark the rules fired. Returns the retry ordinal (1-based). */
+    recordTrigger(rules: readonly StreamRule[]): number;
+    private match;
+}
+/** The hidden runtime note appended before the retry. */
+declare function buildStreamRuleReminder(rules: readonly StreamRule[]): Message;
+
 interface StructuredToolResult {
     content: ToolResultContent;
     details?: unknown;
@@ -27,6 +103,12 @@ interface AgentTool<T extends z.ZodType = z.ZodType> extends Tool {
      * message — becomes unreachable.
      */
     timeoutMs?: number;
+    /**
+     * Whether a mid-run steering message may preempt this tool. Defaults to
+     * true, except for atomic file mutators (`edit`, `write`, …) which always
+     * run to completion so they are never left half-applied.
+     */
+    interruptible?: boolean;
     execute: (args: z.infer<T>, context: ToolContext) => ToolExecuteResult | Promise<ToolExecuteResult>;
 }
 interface AgentTextDeltaEvent {
@@ -146,7 +228,7 @@ interface AgentTruncatedEvent {
 }
 interface AgentRetryEvent {
     type: "retry";
-    reason: "overloaded" | "rate_limit" | "provider_error" | "empty_response" | "stream_stall" | "overflow_compact" | "tool_argument_glitch" | "runaway_toolcall";
+    reason: "overloaded" | "rate_limit" | "provider_error" | "empty_response" | "stream_stall" | "overflow_compact" | "tool_argument_glitch" | "runaway_toolcall" | "stream_rule";
     attempt: number;
     maxAttempts: number;
     delayMs: number;
@@ -164,6 +246,29 @@ interface AgentRetryEvent {
      */
     preservedChars?: number;
 }
+/**
+ * A stream rule matched mid-response. The attempt was aborted and discarded
+ * (no partial message persisted, no partial tool call executed), the rule's
+ * reminder was appended to the context, and the step is retried. Always
+ * followed by a silent `retry` (reason `stream_rule`) so UIs roll back the
+ * streamed partial exactly as for any other replayed attempt.
+ */
+interface AgentStreamRuleTriggeredEvent {
+    type: "stream_rule_triggered";
+    /** Names of the rules that matched (usually one). */
+    rules: string[];
+    source: "text" | "tool";
+    /** Tool whose streamed arguments matched, for `source: "tool"`. */
+    toolName?: string;
+    attempt: number;
+    maxAttempts: number;
+    /**
+     * ESTIMATED usage of the aborted attempt (providers report none for an
+     * aborted stream): prompt chars/4 in, streamed chars/4 out. Already added to
+     * the run's `totalUsage`.
+     */
+    usage: Usage;
+}
 interface AgentToolCallDeltaEvent {
     type: "toolcall_delta";
     chars: number;
@@ -192,7 +297,7 @@ interface AgentFollowUpMessageEvent {
     type: "follow_up_message";
     content: Message["content"];
 }
-type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentTurnEndEvent | AgentCheckpointEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTurnBudgetExtendedEvent | AgentTruncatedEvent | AgentErrorEvent;
+type AgentEvent = AgentTextDeltaEvent | AgentThinkingDeltaEvent | AgentToolCallStartEvent | AgentToolCallUpdateEvent | AgentToolCallEndEvent | AgentToolCallDeltaEvent | AgentServerToolCallEvent | AgentServerToolResultEvent | AgentSteeringMessageEvent | AgentFollowUpMessageEvent | AgentRetryEvent | AgentStreamRuleTriggeredEvent | AgentTurnEndEvent | AgentCheckpointEvent | AgentDoneEvent | AgentMaxTurnsEvent | AgentTurnBudgetExtendedEvent | AgentTruncatedEvent | AgentErrorEvent;
 interface TransformContextOptions {
     /** Force a transform after the provider reports context overflow. */
     force?: boolean;
@@ -244,6 +349,7 @@ interface AgentOptions {
     transportSessionId?: StreamOptions["transportSessionId"];
     projectId?: StreamOptions["projectId"];
     cacheRetention?: StreamOptions["cacheRetention"];
+    onContextPrepared?: StreamOptions["onContextPrepared"];
     /** Stable per-session cache routing key for providers that support it. */
     promptCacheKey?: StreamOptions["promptCacheKey"];
     /** Override the User-Agent sent with OAuth-authenticated Anthropic requests. */
@@ -253,6 +359,10 @@ interface AgentOptions {
     defaultHeaders?: StreamOptions["defaultHeaders"];
     /** OpenAI service tier for latency-sensitive first-party API requests. */
     serviceTier?: StreamOptions["serviceTier"];
+    /** Codex Responses-Lite request shape override (see StreamOptions). */
+    responsesLite?: StreamOptions["responsesLite"];
+    /** Codex strict tool schema override (see StreamOptions). */
+    strictTools?: StreamOptions["strictTools"];
     /** Whether the target model supports image input. When false, image blocks
      *  in messages/tool_results are downgraded to text placeholders. Default: true. */
     supportsImages?: boolean;
@@ -271,6 +381,14 @@ interface AgentOptions {
      *  against parallel fan-outs injecting huge uncached context in one turn;
      *  the largest results are trimmed (water-filling) with a re-run notice. */
     maxTurnToolResultChars?: number;
+    /** Optional post-processing of a SUCCESSFUL tool result (after redaction,
+     *  before the tool_call_end event and the provider context). Return the
+     *  content unchanged to leave it alone. A throw is ignored (original kept).
+     *  Used e.g. to append a warning to untrusted-content results. */
+    transformToolResult?: (call: {
+        name: string;
+        args: Record<string, unknown>;
+    }, content: ToolResultContent) => ToolResultContent;
     /** Max consecutive pause_turn continuations before stopping (default: 5).
      *  Prevents infinite loops when server-side tools keep pausing. */
     maxContinuations?: number;
@@ -292,6 +410,15 @@ interface AgentOptions {
      * on read.
      */
     getSteeringMessages?: () => Promise<Message[] | null> | Message[] | null;
+    /**
+     * Instant interrupt (codex `instant_interrupt`): subscribe to "a steering
+     * message just arrived". While tools are running, the listener preempts
+     * interruptible tools (their AbortSignal fires; unfinished calls get an
+     * "Interrupted" error result) and the loop drains steering and continues.
+     * Distinct from `signal` (the Stop button), which ends the run. Returns an
+     * unsubscribe function.
+     */
+    onSteeringAvailable?: (listener: () => void) => () => void;
     /**
      * Polled when the agent would otherwise stop (no tool calls, no steering).
      * Returns messages to inject and continue the loop. Lower priority than
@@ -312,6 +439,13 @@ interface AgentOptions {
         maxTurns: number;
         extension: number;
     }) => Promise<boolean> | boolean;
+    /**
+     * Regex rules matched against streamed assistant text and tool-call
+     * arguments. A match aborts the attempt, discards it, appends the rule's
+     * reminder and retries the step. Each rule fires at most once per run;
+     * `maxRetries` (default 3) caps rule retries per run. Unset = no matching.
+     */
+    streamRules?: StreamRulesConfig;
 }
 interface AgentResult {
     message: AssistantMessage;
@@ -349,6 +483,7 @@ declare class Agent {
     private options;
     private steeringQueue;
     private followUpQueue;
+    private steeringListeners;
     constructor(options: AgentOptions);
     /** Snapshot of the current message history. Used for session persistence. */
     getMessages(): Message[];
@@ -359,7 +494,11 @@ declare class Agent {
      */
     setSignal(signal: AbortSignal | undefined): void;
     get running(): boolean;
-    /** Queue a steering message for injection after current tool execution completes. */
+    /**
+     * Queue a steering message. Instant interrupt: if tools are running, the
+     * interruptible ones are preempted right away and the message is injected
+     * before the next model call (the turn continues — unlike abort/Stop).
+     */
     steer(msg: Message): void;
     /** Queue a follow-up message for injection when the agent would otherwise stop. */
     followUp(msg: Message): void;
@@ -415,6 +554,7 @@ declare function cancelledBeforeStartText(name: string): string;
  * something never ran when it did.
  */
 declare function indeterminateOutcomeText(name: string): string;
+declare function repairToolPairingAdjacent(messages: Message[]): void;
 
 /**
  * A local inference server (llama.cpp, vLLM, Ollama, LM Studio) can spend
@@ -425,4 +565,4 @@ declare function indeterminateOutcomeText(name: string): string;
  */
 declare function isLocalBackendUrl(baseUrl?: string): boolean;
 
-export { Agent, type AgentDoneEvent, type AgentErrorEvent, type AgentEvent, type AgentFollowUpMessageEvent, type AgentOptions, type AgentResult, type AgentRetryEvent, type AgentServerToolCallEvent, type AgentServerToolResultEvent, type AgentSteeringMessageEvent, AgentStream, type AgentTextDeltaEvent, type AgentThinkingDeltaEvent, type AgentTool, type AgentToolCallDeltaEvent, type AgentToolCallEndEvent, type AgentToolCallStartEvent, type AgentToolCallUpdateEvent, type AgentTurnEndEvent, type AgentTurnTiming, type StreamDiagnosticFn, type StructuredToolResult, type ToolContext, type ToolExecuteResult, type ToolExecutionMode, type TransformContextOptions, agentLoop, cancelledBeforeStartText, indeterminateOutcomeText, isAbortError, isBillingError, isContextOverflow, isLocalBackendUrl, isUsageLimitError, setStreamDiagnostic };
+export { Agent, type AgentDoneEvent, type AgentErrorEvent, type AgentEvent, type AgentFollowUpMessageEvent, type AgentOptions, type AgentResult, type AgentRetryEvent, type AgentServerToolCallEvent, type AgentServerToolResultEvent, type AgentSteeringMessageEvent, AgentStream, type AgentStreamRuleTriggeredEvent, type AgentTextDeltaEvent, type AgentThinkingDeltaEvent, type AgentTool, type AgentToolCallDeltaEvent, type AgentToolCallEndEvent, type AgentToolCallStartEvent, type AgentToolCallUpdateEvent, type AgentTurnEndEvent, type AgentTurnTiming, DEFAULT_STREAM_RULE_MAX_RETRIES, DEFAULT_STREAM_RULE_WINDOW_CHARS, JsonEscapeDecoder, type StreamDiagnosticFn, type StreamRule, type StreamRuleMatch, StreamRuleMonitor, type StreamRuleScope, type StreamRuleSource, type StreamRulesConfig, type StructuredToolResult, type ToolContext, type ToolExecuteResult, type ToolExecutionMode, type TransformContextOptions, agentLoop, buildStreamRuleReminder, cancelledBeforeStartText, indeterminateOutcomeText, isAbortError, isBillingError, isContextOverflow, isLocalBackendUrl, isUsageLimitError, repairToolPairingAdjacent, setStreamDiagnostic };