@kenkaiiii/gg-agent 5.67.1 → 5.68.1

package/dist/index.d.cts

@@ -1,6 +1,82 @@
-import { StreamOptions, Message, Tool, ToolResultContent, ServerToolDefinition, Usage, StopReason, AssistantMessage } from '@kenkaiiii/gg-ai';
+import { Message, StreamOptions, Tool, ToolResultContent, ServerToolDefinition, Usage, StopReason, AssistantMessage } from '@kenkaiiii/gg-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;
@@ -146,7 +222,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 +240,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 +291,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 +343,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. */
@@ -312,6 +412,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;
@@ -415,6 +522,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 +533,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 '@kenkaiiii/gg-ai';
+import { Message, StreamOptions, Tool, ToolResultContent, ServerToolDefinition, Usage, StopReason, AssistantMessage } from '@kenkaiiii/gg-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;
@@ -146,7 +222,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 +240,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 +291,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 +343,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. */
@@ -312,6 +412,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;
@@ -415,6 +522,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 +533,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.js

@@ -90,6 +90,133 @@ function clampOutputTokens(key, requested) {
   return requested === void 0 ? ceiling : Math.min(requested, ceiling);
 }
 
+// src/stream-rules.ts
+var DEFAULT_STREAM_RULE_MAX_RETRIES = 3;
+var DEFAULT_STREAM_RULE_WINDOW_CHARS = 1024;
+var JSON_ESCAPES = {
+  n: "\n",
+  r: "\r",
+  t: "	",
+  b: "\b",
+  f: "\f",
+  '"': '"',
+  "\\": "\\",
+  "/": "/"
+};
+var JsonEscapeDecoder = class {
+  pending = "";
+  push(chunk) {
+    const input = this.pending + chunk;
+    this.pending = "";
+    if (!input.includes("\\")) return input;
+    let out = "";
+    let i = 0;
+    while (i < input.length) {
+      const ch = input.charAt(i);
+      if (ch !== "\\") {
+        out += ch;
+        i++;
+        continue;
+      }
+      if (i + 1 >= input.length) {
+        this.pending = input.slice(i);
+        break;
+      }
+      const next = input.charAt(i + 1);
+      if (next === "u") {
+        if (i + 6 > input.length) {
+          this.pending = input.slice(i);
+          break;
+        }
+        const hex = input.slice(i + 2, i + 6);
+        out += /^[0-9a-fA-F]{4}$/.test(hex) ? String.fromCharCode(Number.parseInt(hex, 16)) : input.slice(i, i + 6);
+        i += 6;
+        continue;
+      }
+      out += JSON_ESCAPES[next] ?? next;
+      i += 2;
+    }
+    return out;
+  }
+};
+var StreamRuleMonitor = class {
+  maxRetries;
+  rules;
+  windowChars;
+  fired = /* @__PURE__ */ new Set();
+  retries = 0;
+  textWindow = "";
+  toolStreams = /* @__PURE__ */ new Map();
+  constructor(config) {
+    this.rules = config.rules;
+    this.maxRetries = Math.max(0, config.maxRetries ?? DEFAULT_STREAM_RULE_MAX_RETRIES);
+    this.windowChars = Math.max(64, config.windowChars ?? DEFAULT_STREAM_RULE_WINDOW_CHARS);
+  }
+  /** False once the retry cap is spent or every rule has fired — skip all matching. */
+  get active() {
+    return this.retries < this.maxRetries && this.fired.size < this.rules.length;
+  }
+  get retriesUsed() {
+    return this.retries;
+  }
+  beginAttempt() {
+    this.textWindow = "";
+    this.toolStreams.clear();
+  }
+  checkText(delta) {
+    if (!this.active || !delta) return null;
+    const scan = this.textWindow + delta;
+    this.textWindow = scan.slice(-this.windowChars);
+    const rules = this.match(scan, "text");
+    return rules.length > 0 ? { rules, source: "text" } : null;
+  }
+  checkToolArgs(id, toolName, argsDelta) {
+    if (!this.active || !argsDelta) return null;
+    let state = this.toolStreams.get(id);
+    if (!state) {
+      state = { window: "", decoder: new JsonEscapeDecoder() };
+      this.toolStreams.set(id, state);
+    }
+    const scan = state.window + state.decoder.push(argsDelta);
+    state.window = scan.slice(-this.windowChars);
+    const rules = this.match(scan, "tool", toolName);
+    return rules.length > 0 ? { rules, source: "tool", toolName } : null;
+  }
+  /** Consume one retry and mark the rules fired. Returns the retry ordinal (1-based). */
+  recordTrigger(rules) {
+    for (const rule of rules) this.fired.add(rule.name);
+    this.retries++;
+    return this.retries;
+  }
+  match(scan, source, toolName) {
+    const hits = [];
+    for (const rule of this.rules) {
+      if (this.fired.has(rule.name)) continue;
+      if (rule.scope !== "both" && rule.scope !== source) continue;
+      if (source === "tool" && rule.tools && toolName !== void 0) {
+        if (!rule.tools.includes(toolName)) continue;
+      }
+      rule.pattern.lastIndex = 0;
+      if (rule.pattern.test(scan)) hits.push(rule);
+    }
+    return hits;
+  }
+};
+function buildStreamRuleReminder(rules) {
+  const blocks = rules.map(
+    (rule) => `<system-reminder reason="stream_rule" rule="${rule.name.replace(/"/g, "'")}">
+Your previous response was interrupted mid-stream because it violated this rule. The interrupted output was discarded: the user never saw it and no tool call from it ran. Regenerate the response from the start and follow the rule:
+
+${rule.reminder.trim()}
+</system-reminder>`
+  );
+  return {
+    role: "user",
+    content: blocks.join("\n\n"),
+    provenance: { source: "runtime", kind: "notification", visibility: "hidden" }
+  };
+}
+
 // src/agent-loop.ts
 var DEFAULT_MAX_TURNS = 300;
 var DEFAULT_TOOL_TIMEOUT_MS = 3e5;
@@ -355,6 +482,7 @@ async function* agentLoop(messages, options) {
   let runawayToolcallRetries = 0;
   let overflowCompactionAttempts = 0;
   let toolResultTruncationAttempted = false;
+  const streamRuleMonitor = options.streamRules && options.streamRules.rules.length > 0 ? new StreamRuleMonitor(options.streamRules) : null;
   const invalidToolArgumentCounts = /* @__PURE__ */ new Map();
   let toolArgumentAutoContinueUsed = false;
   let useNonStreamingFallback = false;
@@ -408,16 +536,7 @@ async function* agentLoop(messages, options) {
       turn++;
       if (logicalTurnStartedAt === 0) logicalTurnStartedAt = Date.now();
       toolMap = new Map((options.tools ?? []).map((t) => [t.name, t]));
-      let msgChars = 0;
-      for (const m of messages) {
-        if (typeof m.content === "string") msgChars += m.content.length;
-        else if (Array.isArray(m.content)) {
-          for (const p of m.content) {
-            if ("text" in p && typeof p.text === "string") msgChars += p.text.length;
-            if ("content" in p && typeof p.content === "string") msgChars += p.content.length;
-          }
-        }
-      }
+      const msgChars = countMessageChars(messages);
       let firstEventTimeoutMs;
       let initialHardTimeoutMs;
       if (baseFirstEventTimeoutMs === STREAM_FIRST_EVENT_TIMEOUT_MS) {
@@ -487,6 +606,9 @@ async function* agentLoop(messages, options) {
       let toolcallDeltaCount = 0;
       let runawayDetected = null;
       let attemptText = "";
+      let streamRuleHit = null;
+      let attemptThinkingChars = 0;
+      streamRuleMonitor?.beginAttempt();
       let lastYieldEndTime = Date.now();
       let maxConsumerLagMs = 0;
       const forwardAbort = () => streamController.abort();
@@ -572,6 +694,7 @@ async function* agentLoop(messages, options) {
           transportSessionId: options.transportSessionId,
           projectId: liveProjectId,
           cacheRetention: options.cacheRetention,
+          onContextPrepared: options.onContextPrepared,
           promptCacheKey: options.promptCacheKey,
           serviceTier: options.serviceTier,
           supportsImages: options.supportsImages,
@@ -645,8 +768,14 @@ async function* agentLoop(messages, options) {
           }
           if (event.type === "text_delta") {
             attemptText += event.text;
+            streamRuleHit = streamRuleMonitor?.checkText(event.text) ?? null;
+            if (streamRuleHit) {
+              streamController.abort();
+              break;
+            }
             yield { type: "text_delta", text: event.text };
           } else if (event.type === "thinking_delta") {
+            attemptThinkingChars += event.text.length;
             yield { type: "thinking_delta", text: event.text };
           } else if (event.type === "server_toolcall") {
             yield {
@@ -666,6 +795,11 @@ async function* agentLoop(messages, options) {
             const chunkChars = event.argsJson?.length ?? 0;
             toolcallDeltaChars += chunkChars;
             toolcallDeltaCount++;
+            streamRuleHit = streamRuleMonitor?.checkToolArgs(event.id, event.name, event.argsJson ?? "") ?? null;
+            if (streamRuleHit) {
+              streamController.abort();
+              break;
+            }
             if (!runawayDetected && (toolcallDeltaChars > MAX_TOOLCALL_DELTA_CHARS || toolcallDeltaCount > MAX_TOOLCALL_DELTA_EVENTS)) {
               runawayDetected = {
                 kind: toolcallDeltaChars > MAX_TOOLCALL_DELTA_CHARS ? "chars" : "events",
@@ -687,6 +821,54 @@ async function* agentLoop(messages, options) {
           lastYieldEndTime = Date.now();
           resetIdleTimer();
         }
+        if (streamRuleHit && streamRuleMonitor) {
+          const attempt = streamRuleMonitor.recordTrigger(streamRuleHit.rules);
+          const ruleNames = streamRuleHit.rules.map((rule) => rule.name);
+          const priorPrompt = latestProviderUsage ? latestProviderUsage.inputTokens + (latestProviderUsage.cacheRead ?? 0) + (latestProviderUsage.cacheWrite ?? 0) : 0;
+          const newChars = priorPrompt > 0 && usageAnchorIndex !== void 0 ? countMessageChars(messages.slice(usageAnchorIndex + 1)) : msgChars;
+          const abortedUsage = {
+            inputTokens: Math.ceil(newChars / 4),
+            outputTokens: Math.ceil(
+              (attemptText.length + attemptThinkingChars + toolcallDeltaChars) / 4
+            ),
+            ...priorPrompt > 0 ? { cacheRead: priorPrompt } : {}
+          };
+          totalUsage.inputTokens += abortedUsage.inputTokens;
+          totalUsage.outputTokens += abortedUsage.outputTokens;
+          if (abortedUsage.cacheRead) {
+            totalUsage.cacheRead = (totalUsage.cacheRead ?? 0) + abortedUsage.cacheRead;
+          }
+          diag("stream_rule_triggered", {
+            rules: ruleNames.join(","),
+            source: streamRuleHit.source,
+            toolName: streamRuleHit.toolName,
+            attempt,
+            maxAttempts: streamRuleMonitor.maxRetries,
+            discardedChars: attemptText.length + toolcallDeltaChars,
+            provider: options.provider,
+            model: options.model
+          });
+          messages.push(buildStreamRuleReminder(streamRuleHit.rules));
+          yield {
+            type: "stream_rule_triggered",
+            rules: ruleNames,
+            source: streamRuleHit.source,
+            ...streamRuleHit.toolName !== void 0 ? { toolName: streamRuleHit.toolName } : {},
+            attempt,
+            maxAttempts: streamRuleMonitor.maxRetries,
+            usage: abortedUsage
+          };
+          yield {
+            type: "retry",
+            reason: "stream_rule",
+            attempt,
+            maxAttempts: streamRuleMonitor.maxRetries,
+            delayMs: 0,
+            silent: true
+          };
+          turn--;
+          continue;
+        }
         diag("stream_done", {
           events: streamEventCount,
           totalMs: Date.now() - streamCallStart,
@@ -1733,6 +1915,19 @@ function sanitizeOrphanedServerTools(messages) {
     break;
   }
 }
+function countMessageChars(messages) {
+  let chars = 0;
+  for (const m of messages) {
+    if (typeof m.content === "string") chars += m.content.length;
+    else if (Array.isArray(m.content)) {
+      for (const p of m.content) {
+        if ("text" in p && typeof p.text === "string") chars += p.text.length;
+        if ("content" in p && typeof p.content === "string") chars += p.content.length;
+      }
+    }
+  }
+  return chars;
+}
 function repairToolPairingAdjacent(messages) {
   for (let i = 0; i < messages.length; i++) {
     const msg = messages[i];
@@ -1911,7 +2106,12 @@ var Agent = class {
 export {
   Agent,
   AgentStream,
+  DEFAULT_STREAM_RULE_MAX_RETRIES,
+  DEFAULT_STREAM_RULE_WINDOW_CHARS,
+  JsonEscapeDecoder,
+  StreamRuleMonitor,
   agentLoop,
+  buildStreamRuleReminder,
   cancelledBeforeStartText,
   indeterminateOutcomeText,
   isAbortError,
@@ -1919,6 +2119,7 @@ export {
   isContextOverflow,
   isLocalBackendUrl,
   isUsageLimitError,
+  repairToolPairingAdjacent,
   setStreamDiagnostic
 };
 //# sourceMappingURL=index.js.map