zidane 5.12.9 → 5.13.0

package/README.md

@@ -80,6 +80,8 @@ createAgent({
     compactStrategy: 'off',          // 'off' | 'tail' (non-Anthropic compaction)
     compactThreshold: 131_072,       // 128 KiB
     compactKeepTurns: 4,
+    mediaKeepTurns: undefined,       // age old image/document base64 off the wire; chat profiles use 8
+    autoCompact: false,              // loop-native LLM summary at N% of the window; chat profiles enable it
     toolDisclosure: 'eager',         // 'eager' | 'lazy' (hide MCP schemas behind tool_search)
     toolSearch: { tool: true, limit: 20 },
   },
@@ -355,6 +357,10 @@ agent.hooks.hook('context:transform', (ctx) => {
 
 `behavior.compactStrategy: 'tail'` elides older `tool_result` blocks once their combined size exceeds `compactThreshold` (default 128 KiB); the newest `compactKeepTurns` (default 4) stay intact. Anthropic users should prefer the server-side `context-management-2025-06-27` beta via `anthropic({ extraBetas, contextManagement })` — token-accurate.
 
+`behavior.mediaKeepTurns` is separate: it ages old inline image/document base64 off the provider wire while keeping bytes in `session.turns`. Aged media becomes an `attachment://<hash>` marker that `read_file path="attachment://..."` can re-inline. SDK default is off; built-in chat profiles set it to `8`. Proactive age-out only runs when `read_file` is registered.
+
+`behavior.autoCompact` is the heavy lever: loop-native auto-compaction. Once a turn's effective input crosses `threshold` (default `0.85`) of the context window, the loop runs a real LLM summary over the older turns, appends a `compact-summary` marker + file/skill restoration to the session, and continues — mid-run and at end-of-run. Window source is `autoCompact.contextWindow` → `provider.meta.contextWindow` (inert without one). Observe via the `compact:start` / `compact:end` hooks. SDK default off; chat profiles enable it. Distinct from `compactStrategy` (per-turn wire-only `tool_result` trim) and the always-on reactive `context_exceeded` recovery.
+
 ### Read dedup + read-before-edit guard
 
 - `behavior.dedupReads` (default **on**) — `read_file` returns `"unchanged since the previous read"` on identical re-reads. Per-session content-hash.

package/dist/{agent-DFxjgQx5.d.ts → agent-Db4ojCSV.d.ts}

@@ -1,6 +1,6 @@
 import { c as ExecutionContext, f as TaskExitInfo, l as ExecutionHandle } from "./types-B39tBba1.js";
 import { Hookable } from "hookable";
-import { OAuthCredentials, getOAuthApiKey } from "@earendil-works/pi-ai/oauth";
+import { OAuthCredentials } from "@earendil-works/pi-ai/oauth";
 import { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import Anthropic from "@anthropic-ai/sdk";
@@ -766,6 +766,68 @@ type CompactFunction = (messages: SessionMessage[], ctx: {
    */
   totalBytes: number;
 }) => SessionMessage[] | Promise<SessionMessage[]>;
+/**
+ * Loop-native auto-compaction config (`AgentBehavior.autoCompact`).
+ *
+ * Distinct from `compactStrategy` (wire-only tail elision of `tool_result`
+ * text). Auto-compaction is the heavy lever: when the last turn's input
+ * usage crosses {@link AutoCompactConfig.threshold} of the effective context
+ * window, the loop runs a real LLM summary (`compactConversation`) over the
+ * older turns, appends a `compact-summary` marker + restoration turns to the
+ * session mid-run, and the next turn's wire view is the summary plus the
+ * preserved tail. It mutates the session (durable summary turn), whereas
+ * `compactStrategy` never touches `session.turns`.
+ *
+ * The two compose: `compactStrategy: 'tail'` trims tool-output bytes every
+ * turn; `autoCompact` summarizes the narrative when the window fills.
+ */
+interface AutoCompactConfig {
+  /**
+   * Fraction of the EFFECTIVE context window (raw window minus the output
+   * reserve) the last turn's input usage must reach to fire. Must be in the
+   * open interval `(0, 1)`; out-of-range disables the trigger. Default: `0.85`.
+   */
+  threshold?: number;
+  /**
+   * Raw model context window in tokens. The SDK core has no model catalog,
+   * so when omitted it falls back to `provider.meta.contextWindow` (a
+   * number, if the provider advertises one). When neither resolves, the
+   * trigger is inert — it can't compute a usage ratio. Chat hosts inject
+   * the picked model's window here from their catalog.
+   */
+  contextWindow?: number;
+  /**
+   * Trailing turns kept verbatim (passed to `compactConversation` as
+   * `scope: 'tail'` `keepTurns`). Defaults to `compactKeepTurns` when set,
+   * else `4`.
+   */
+  keepTurns?: number;
+  /**
+   * Hysteresis floor — minimum fraction of the window that must be consumed
+   * by NEW content after a compaction before another can fire, so the
+   * post-compact bounce doesn't immediately re-trigger. Default: `0.1`.
+   */
+  minGrowthFraction?: number;
+  /**
+   * Re-inject recently-read files + active skills as synthetic tool-call
+   * pairs after the summary marker (via `buildPostCompactAttachments`) so
+   * the model keeps its working set. Default: `true`.
+   */
+  restore?: boolean;
+  /**
+   * Consecutive-failure circuit breaker. After this many failed compaction
+   * attempts in a single run, the loop stops trying for the rest of the run
+   * (the reactive `context_exceeded` net still protects overflow). A
+   * successful compaction resets the counter. Default: `2`.
+   */
+  maxFailures?: number;
+}
+/**
+ * `AgentBehavior.autoCompact` value: `true` enables loop-native
+ * auto-compaction with defaults, `false` / omitted disables it, and an
+ * {@link AutoCompactConfig} enables it with overrides.
+ */
+type AutoCompact = boolean | AutoCompactConfig;
 type DedupToolConfig = DedupHasher | {
   hasher: DedupHasher;
   mode?: 'replay' | 'block-after';
@@ -823,7 +885,8 @@ type RepeatGuardToolMatcher = string | ((name: string) => boolean);
 interface RepeatGuardConfig {
   /**
    * Consecutive identical calls at which the guard refuses the call via
-   * `tool:gate` `block`. Clamped to `>= 2`. Default: `4`.
+   * `tool:gate` `block`. Clamped to `>= 2`. Default: `4` (`read_file` uses
+   * `6` unless this is explicitly configured).
    */
   blockThreshold?: number;
   /**
@@ -831,7 +894,8 @@ interface RepeatGuardConfig {
    * the agent's `AbortController` (the loop then fires `agent:abort`). Must
    * be `>` the block threshold to be reachable; clamped up if not. Set to a
    * non-positive value or `Infinity` to disable the abort escalation
-   * (block-only). Default: `8`.
+   * (block-only). Default: `8` (`read_file` uses `12` unless this is
+   * explicitly configured).
    */
   abortThreshold?: number;
   /**
@@ -849,27 +913,54 @@ interface RepeatGuardConfig {
    */
   normalize?: (name: string, input: Record<string, unknown>) => string | undefined;
   /**
-   * Model-visible refusal text at the block threshold, rendered as
-   * `Blocked: <reason>`. String used verbatim; callback receives the tool
-   * name and consecutive count. Default: a generic pivot suggestion.
+   * Model-visible steering text at the block threshold. Used as the
+   * `Blocked: <message>` reason for `thresholdAction: 'block'`, or appended
+   * to the successful tool result for `thresholdAction: 'steer'`. String used
+   * verbatim; callback receives the tool name and observed repeat count.
+   * Default: a generic pivot suggestion.
+   */
+  steeringMessage?: string | ((name: string, count: number) => string);
+  /**
+   * Legacy alias for {@link steeringMessage}. Preserved for callers already
+   * customizing the old block-only message.
    */
   blockReason?: string | ((name: string, count: number) => string);
   /**
-   * Sliding-window counting instead of strictly-consecutive streaks.
+   * What to do at `blockThreshold`.
+   *
+   * - `'block'` (default) refuses the call via `tool:gate`, returning
+   *   `Blocked: <steering message>`.
+   * - `'steer'` lets the tool execute, then appends the steering message to
+   *   the tool result. `abortThreshold` still blocks and aborts the run.
+   */
+  thresholdAction?: 'block' | 'steer';
+  /**
+   * Repeat detector strategy.
+   *
+   * - `'chain'` — strict back-to-back chain counting. Any intervening tool
+   *   call breaks the chain.
+   * - `'window'` — sliding-window counting. Interleaved calls can accumulate.
+   * - `'both'` — run both counters and trip when either reaches the threshold.
+   *
+   * Default: `'chain'`. For compatibility, setting {@link windowSize} without
+   * `mode` keeps the old `'window'` behavior.
+   */
+  mode?: 'chain' | 'window' | 'both';
+  /**
+   * Sliding-window size for `mode: 'window'` / `mode: 'both'`.
    *
    * When set (`>= 2`), a call's count is the number of occurrences of its
    * normalized key among that tool's last `windowSize` tracked calls
    * (including this one). A *different* payload of the same tool no longer
-   * resets the count — which is exactly how production loops evade the
-   * consecutive streak: `read_file A / read_file B / read_file A / …` or a
-   * read→edit→read ping-pong re-reads the same file every other call and
-   * never accumulates a streak, burning turns until the cap.
+   * resets the count. This is opt-in non-chain behavior for consumers that
+   * explicitly want to catch interleaved repeats.
    *
    * The effective window is clamped up to the abort threshold (or the
    * block threshold when abort is disabled) so the thresholds stay
    * reachable.
    *
-   * Default: `undefined` (consecutive streaks — historic behavior).
+   * Default: `undefined` for `mode: 'chain'`; a conservative built-in default
+   * is used when `mode` requests window counting without an explicit size.
    */
   windowSize?: number;
   /**
@@ -891,13 +982,12 @@ interface RepeatGuardConfig {
    */
   countBlockedCalls?: boolean;
   /**
-   * Universal repeat ceiling — the last-resort loop breaker. Independent of
-   * {@link tools}, it counts exact `(tool, args)` repeats across EVERY tool
-   * and aborts the run when one recurs this many times within
-   * {@link globalCeilingWindow} calls of that tool. Catches loops the
-   * per-tool streak/window misses: a `grep`/`glob`/`edit` cycle, or a model
-   * hammering a tool stuck behind a sticky block (it counts blocked attempts,
-   * unlike {@link countBlockedCalls}; never a `result` substitute).
+   * Universal repeat ceiling — the last-resort chain breaker. Independent of
+   * {@link tools}, it counts exact back-to-back `(tool, args)` repeats across
+   * EVERY tool and aborts the run when one recurs this many times in a row.
+   * Catches untracked tool chains and tools stuck behind a sticky block (it
+   * counts blocked attempts, unlike {@link countBlockedCalls}; never a
+   * `result` substitute).
    *
    * Set high enough that honest retries don't trip it. The main false-positive
    * risk is a tool that's legitimately polled with identical args many times
@@ -907,8 +997,8 @@ interface RepeatGuardConfig {
    */
   globalCeiling?: number;
   /**
-   * Sliding window (per run + tool) the {@link globalCeiling} counts repeats
-   * within. Clamped up to the ceiling so it stays reachable. Default: `40`.
+   * Deprecated no-op kept for config compatibility. The {@link globalCeiling}
+   * now uses strict chain counting, not a sliding window.
    */
   globalCeilingWindow?: number;
   /**
@@ -1024,6 +1114,86 @@ interface AgentBehavior {
    * are ignored).
    */
   maxWallMs?: number;
+  /**
+   * Provider first-response watchdog in milliseconds.
+   *
+   * Starts at `stream:start` and is cleared by the first text/thinking/server
+   * tool callback or by the provider returning a tool-only/final result. If it
+   * expires, the loop aborts the provider request signal and surfaces a typed
+   * provider error instead of leaving `agent.run()` pending forever.
+   *
+   * `maxWallMs`, when lower, bounds this value too. Set `0` to disable.
+   * Default: 300000 (5 minutes).
+   */
+  providerStreamStartTimeoutMs?: number;
+  /**
+   * Provider total stream watchdog in milliseconds.
+   *
+   * Bounds the whole `provider.stream()` call, including streams that already
+   * produced partial output but never settle. If it expires, the loop aborts
+   * the provider request signal and surfaces the timeout as a provider error.
+   *
+   * `maxWallMs`, when lower, bounds this value too. Set `0` to disable.
+   * Default: 1800000 (30 minutes).
+   */
+  providerStreamTimeoutMs?: number;
+  /**
+   * Custom MCP connector watchdog in milliseconds.
+   *
+   * The built-in `connectMcpServers()` has per-server bootstrap timeouts. This
+   * extra guard protects embedders that provide `mcpConnector` and accidentally
+   * return a promise that never settles before the first model call.
+   *
+   * `maxWallMs`, when lower, bounds this value during `run()`. Set `0` to
+   * disable. Default: 120000 (2 minutes).
+   */
+  mcpConnectTimeoutMs?: number;
+  /**
+   * Watchdog for awaited hook dispatch (in milliseconds).
+   *
+   * Bounds every awaited `hooks.callHook(...)` the agent loop and run
+   * lifecycle await — `context:transform` / `system:transform` /
+   * `turn:before` / `stream:start` / `turn:after` / `stream:end` /
+   * `tool-results:after`, plus the run-setup (`session:start`,
+   * `agent:start`) and run-teardown (`agent:done`, `session:end`,
+   * `session:turns`, `skills:deactivate`) hooks. A host handler that never
+   * resolves would otherwise hang the first turn (before the provider
+   * watchdog can run) or strand the `running` gate during cleanup.
+   *
+   * State-mutating pre-stream hooks surface a timeout as a typed
+   * `OperationTimeoutError` (fail-closed — a half-applied transform must
+   * not reach the wire); observability/lifecycle hooks log under
+   * `ZIDANE_DEBUG` and continue. Generous by design — the goal is catching
+   * infinite hangs, not policing slow handlers.
+   *
+   * Set `0` to disable. Default: 300000 (5 minutes).
+   */
+  hookTimeoutMs?: number;
+  /**
+   * Watchdog for the first `executionContext.spawn()` (in milliseconds).
+   *
+   * The process context spawns synchronously, but docker / sandbox / e2b /
+   * daytona contexts do daemon + network round-trips (image pull, container
+   * create/start) with no inherent timeout. This bounds that first spawn so
+   * a hung daemon surfaces a typed `OperationTimeoutError` instead of a run
+   * that never starts responding.
+   *
+   * `maxWallMs`, when lower, bounds this value too. Set `0` to disable.
+   * Default: 300000 (5 minutes). Raise for hosts doing large first-time
+   * image pulls on slow links.
+   */
+  spawnTimeoutMs?: number;
+  /**
+   * Watchdog for `agent.destroy()` teardown awaits (in milliseconds).
+   *
+   * Bounds each awaited teardown step (pending MCP warmup, MCP connection
+   * `close()`, execution-context `destroy()`) so a custom connector / sandbox
+   * whose `close()` never settles can't strand `destroy()` — which hosts
+   * await before releasing their own run gate (TUI session switch). Steps
+   * that time out are abandoned and teardown continues. Set `0` to disable.
+   * Default: 30000 (30 seconds).
+   */
+  destroyTimeoutMs?: number;
   /**
    * Bounded retry-with-backoff policy applied around `provider.stream()`.
    *
@@ -1046,6 +1216,17 @@ interface AgentBehavior {
    * headers honored when present. Set `maxAttempts: 1` to disable.
    */
   retry?: RetryConfig;
+  /**
+   * Custom `toolBatchExecutor` watchdog in milliseconds.
+   *
+   * Native tool execution keeps its existing per-tool/cancellation semantics.
+   * This only bounds a host-provided batch executor; on timeout the executor's
+   * signal is aborted and the pending tool calls receive error tool results so
+   * a tool-only assistant turn cannot hang the run forever.
+   *
+   * Set `0` / `undefined` to disable. Default: disabled.
+   */
+  toolBatchTimeoutMs?: number;
   /** Max tokens per LLM response (default: 16384) */
   maxTokens?: number;
   /** Thinking token budget — overrides the level-based default when set */
@@ -1214,25 +1395,29 @@ interface AgentBehavior {
    * Consecutive-identical-call repeat guard. Unlike {@link dedupTools} (keyed
    * on argument hash, replays/blocks per the consumer's hasher) and
    * {@link toolBudgets} (run-cumulative count regardless of payload), the
-   * repeat guard watches a **per-tool streak of back-to-back identical
-   * payloads** and escalates:
-   *
-   * - At `blockThreshold` (default 4) consecutive identical calls: refuse the
-   *   call via `tool:gate` `block` with a pivot suggestion. Fires
-   *   `repeat-guard:exceeded` with `action: 'block'`.
-   * - At `abortThreshold` (default 8) consecutive identical calls: abort the
-   *   whole run via the agent's `AbortController` (the loop then fires
-   *   `agent:abort`, the same path a user cancel takes). A
-   *   `repeat-guard:exceeded` event with `action: 'abort'` fires first so
-   *   consumers can distinguish a guard abort from a user cancel. This is the
-   *   only layer that stops a model which ignores the `Blocked:` reason and
-   *   keeps retrying.
-   *
-   * "Consecutive" is **per tracked tool**: a call to a *different* tracked
-   * tool, or the *same* tool with a different normalized payload, resets that
-   * tool's streak. Calls to *untracked* tools never reset any streak, so
-   * `shell X / read_file Y / shell X` still counts as two consecutive
-   * `shell X`.
+   * repeat guard watches a **run-local chain of back-to-back identical
+   * tool payloads** and escalates:
+   *
+   * - At `blockThreshold` (default 4; `read_file` default 6)
+   *   consecutive identical calls: either refuse the call via `tool:gate`
+   *   `block` or let it execute and append a steering message, depending on
+   *   {@link RepeatGuardConfig.thresholdAction}. Fires
+   *   `repeat-guard:exceeded` with `action: 'block' | 'steer'`.
+   * - At `abortThreshold` (default 8; `read_file` default 12)
+   *   consecutive identical calls: abort the whole run via the agent's
+   *   `AbortController` (the loop then fires `agent:abort`, the same path a
+   *   user cancel takes). A `repeat-guard:exceeded` event with
+   *   `action: 'abort'` fires first so consumers can distinguish a guard abort
+   *   from a user cancel. This is the only layer that stops a model which
+   *   ignores the `Blocked:` reason and keeps retrying.
+   *
+   * "Consecutive" means the next tool call in the run is the same tracked
+   * tool with the same normalized payload. Any intervening tool call, tracked
+   * or not, breaks the chain.
+   *
+   * `mode: 'window'` intentionally relaxes that definition. `mode: 'both'`
+   * keeps the chain guard while also catching interleaved repeats inside
+   * {@link windowSize}.
    *
    * `track` selects which tools the guard watches. Each entry is a predicate
    * over the canonical tool name; a string entry matches that exact name. The
@@ -1361,6 +1546,27 @@ interface AgentBehavior {
    * for elision so the model keeps the freshest tool context. Default: `4`.
    */
   compactKeepTurns?: number;
+  /**
+   * Loop-native auto-compaction. When enabled, the agent loop watches each
+   * turn's input usage and — once it crosses the configured fraction of the
+   * effective context window — runs a real LLM summary over the older turns
+   * mid-run, appends a `compact-summary` marker (+ optional file/skill
+   * restoration) to the session, and continues. The next turn's wire view
+   * is the summary plus the preserved tail.
+   *
+   * `true` enables with defaults (`threshold: 0.85`, restore on); an
+   * {@link AutoCompactConfig} overrides individual knobs. Requires a window
+   * source — `autoCompact.contextWindow` or `provider.meta.contextWindow` —
+   * or the trigger stays inert. Reuses the same `shouldAutoCompact` policy
+   * the chat hosts use.
+   *
+   * Distinct from `compactStrategy` (per-turn wire-only tool-output trim)
+   * and from the always-on reactive `context_exceeded` recovery. Observe
+   * via the `compact:start` / `compact:end` hooks.
+   *
+   * Default: `undefined` (off). The built-in chat profiles enable it.
+   */
+  autoCompact?: AutoCompact;
   /**
    * Prefix every line of `read_file` output with its 1-indexed line number
    * followed by a tab (`<N>\t<content>`) — the compact `cat -n`-style
@@ -1395,6 +1601,28 @@ interface AgentBehavior {
    * Default: `false`.
    */
   elideStaleReads?: boolean;
+  /**
+   * Age base64 media (top-level `image` / `document` blocks AND image /
+   * document parts nested in `tool_result` outputs) off the **wire** once it
+   * is older than the last `mediaKeepTurns` messages. The aged-out block is
+   * replaced with a short text marker carrying a re-resolve handle
+   * (`attachment://<hash>`); the persisted session keeps the original bytes
+   * untouched, so the model can pull any image back on demand with
+   * `read_file path="attachment://<hash>"`.
+   *
+   * This is the long-run de-bloat lever: a screenshot or pasted image is only
+   * carried as base64 for a few recent turns instead of riding the prompt
+   * forever. Distinct from `compactStrategy: 'tail'`, which only stubs
+   * `tool_result` *text* and never counts (or trims) media bytes.
+   *
+   * The frontier is chunk-snapped for prompt-cache stability — media drops
+   * out in discrete jumps, not one block per turn. `0` ages out ALL media;
+   * `undefined` (default) disables the pass entirely (current behavior — media
+   * rides every turn). The built-in chat profiles enable it.
+   *
+   * Default: `undefined` (off).
+   */
+  mediaKeepTurns?: number;
   /**
    * Separator used for provider-facing MCP tool names.
    *
@@ -2503,6 +2731,54 @@ interface SpawnHookContext {
 interface StreamHookContext {
   turnId: string;
 }
+/**
+ * Base context for the loop-native auto-compaction hooks
+ * (`compact:start` / `compact:end`). Fired at a turn boundary by the agent
+ * loop when `behavior.autoCompact` is enabled and the threshold trips — not
+ * during a provider stream, so it carries the run/turn coordinates rather
+ * than extending {@link StreamHookContext}.
+ */
+interface CompactHookContext {
+  /** Run that triggered the compaction. */
+  runId: string;
+  /** Bound session id, when the run has a session. */
+  sessionId?: string;
+  /** 0-based index of the turn after which compaction fired. */
+  turn: number;
+  /** Why compaction ran. Currently only the proactive threshold trigger. */
+  reason: 'auto';
+}
+/** Fired right before the summary call starts. See `compact:start`. */
+interface CompactStartHookContext extends CompactHookContext {
+  /** Fraction of the effective window the last turn's input reached. */
+  usedFraction: number;
+  /** Effective window (raw minus output reserve) used for the ratio. */
+  effectiveWindow: number;
+}
+/**
+ * Fired exactly once after a `compact:start`, on every outcome. `status`
+ * discriminates success (carries the result counts + post-compact size
+ * estimate hosts use to refresh their context indicator) from failure.
+ */
+type CompactEndHookContext = CompactHookContext & ({
+  status: 'success'; /** Number of turn ids the summary replaced on the wire. */
+  replacedCount: number; /** Turns dropped by `prompt_too_long` head-truncation (not summarized). */
+  droppedCount: number; /** Files re-injected by post-compact restoration. */
+  restoredFiles: number; /** Skills re-injected by post-compact restoration. */
+  restoredSkills: number; /** Model that produced the summary. */
+  summaryModel: string;
+  /**
+   * Estimated post-compact effective token size (summary output +
+   * restored attachments). Hosts latch this into their context indicator
+   * so it drops immediately instead of waiting for the next real turn.
+   */
+  effectiveTokens: number;
+  durationMs: number;
+} | {
+  status: 'error'; /** The thrown value from `compactConversation` / restoration. */
+  error: unknown;
+  durationMs: number;
+});
 /** Context for OAuth refresh hooks */
 interface OAuthRefreshHookContext {
   provider: string;
@@ -3366,6 +3642,16 @@ interface StreamCallbacks {
     toolName: string;
     content: unknown;
   }) => void;
+  /**
+   * Fires when the provider observes incremental tool-call activity — a
+   * tool-use content block opening or its input-JSON streaming. Carries no
+   * payload: it exists purely as a liveness signal so the loop's
+   * first-response watchdog doesn't abort a turn that streams ONLY tool
+   * calls (no text / thinking deltas). Optional — providers that can't
+   * surface tool-call deltas simply don't call it (the watchdog then falls
+   * back to the total-stream timeout for such turns).
+   */
+  onToolCallDelta?: () => void;
 }
 interface TurnResult {
   /** Full assistant turn as a SessionMessage */
@@ -4986,6 +5272,27 @@ interface AgentHooks {
     attempt: number;
     err: unknown;
   }) => void;
+  /**
+   * Fires when loop-native auto-compaction (`behavior.autoCompact`) crosses
+   * its threshold and is about to run the summary call, BEFORE the provider
+   * round-trip. Distinct from `context:overflow` (the reactive, wire-only
+   * `context_exceeded` net) — this is the proactive heavy compaction that
+   * summarizes older turns and mutates the session.
+   *
+   * Use it to surface a "Compacting…" banner / footer state. Observational
+   * — handlers cannot cancel the compaction. Always paired with exactly one
+   * `compact:end`.
+   */
+  'compact:start': (ctx: CompactStartHookContext) => void;
+  /**
+   * Fires exactly once after every `compact:start`, on success and failure
+   * (`ctx.status`). On success it carries the replaced/dropped/restored
+   * counts and the post-compact `effectiveTokens` estimate so hosts can drop
+   * their context indicator immediately. On failure it carries `error`; the
+   * loop continues with the un-compacted history (the reactive overflow net
+   * still applies) and the circuit breaker counts the failure.
+   */
+  'compact:end': (ctx: CompactEndHookContext) => void;
   'oauth:refresh': (ctx: OAuthRefreshHookContext) => void;
   /**
    * Resolves persisted content refs into provider-bound payload bytes.
@@ -5892,19 +6199,21 @@ interface AgentHooks {
   }) => void;
   /**
    * Fires when the consecutive-identical {@link AgentBehavior.repeatGuard}
-   * escalates on a tracked tool. `count` is the number of back-to-back
-   * identical calls including the offending one. `action` reflects the
-   * escalation: `'block'` refused this call via `tool:gate`; `'abort'`
-   * additionally aborts the run via the agent's `AbortController` (the loop
-   * then fires `agent:abort`). The `'abort'` event fires BEFORE the abort so
-   * consumers can distinguish a guard abort from a user-driven cancel.
+   * escalates on a tracked tool. In chain mode, `count` is the number of
+   * back-to-back identical calls including the offending one; in window mode it
+   * is the number of occurrences inside the configured window. `action`
+   * reflects the escalation: `'block'` refused this call via `tool:gate`;
+   * `'steer'` let it execute and appended a steering message to the result;
+   * `'abort'` additionally aborts the run via the agent's `AbortController`
+   * (the loop then fires `agent:abort`). The `'abort'` event fires BEFORE the
+   * abort so consumers can distinguish a guard abort from a user-driven cancel.
    */
   'repeat-guard:exceeded': (ctx: {
     tool: string;
     count: number;
     threshold: number;
     turnId: string;
-    action: 'block' | 'abort';
+    action: 'block' | 'steer' | 'abort';
   }) => void;
   /**
    * The run was aborted — fires exactly once per aborted run, on every abort
@@ -6303,5 +6612,5 @@ declare function createAgent({
   clock: agentClock
 }: AgentOptions): Agent;
 //#endregion
-export { EnsureToolResultPairingOptions as $, toolResultToText as $n, planBasetenReasoning as $t, hashContent as A, SessionContentBlock as An, SchemaSanitizeOptions as At, Session as B, ToolOutcome as Bn, classifyOpenAICompatError as Bt, wrapDiscoveredMcpTools as C, PromptVideoPart as Cn, TokenCountPayload as Ct, ReadStateEntry as D, ResolveContentRefBlock as Dn, TurnResult as Dt, ToolMap as E, ResolveContentRef as En, ToolSpec as Et, SkillDiagnostic as F, SpawnHookContext as Fn, OpenRouterParams as Ft, demoteStaleRunningStatus as G, ToolResultImageContent as Gn, LocalParams as Gt, SessionRun as H, ToolResultContent as Hn, openaiCompat as Ht, SkillResource as I, StreamHookContext as In, openrouter as It, createRemoteStore as J, ToolResultVideoContent as Jn, cursor as Jt, loadSession as K, ToolResultImageRefContent as Kn, local as Kt, SkillSource as L, ThinkingLevel as Ln, OpenAICompatAuthHeader as Lt, resolveReadStateMap as M, SessionHookContext as Mn, SchemaSanitizeResult as Mt, ShellInterpolationApproval as N, SessionMessage as Nn, sanitizeToolSchema as Nt, ReadStateMap as O, RetryConfig as On, XaiParams as Ot, SkillConfig as P, SessionTurn as Pn, sanitizeToolSpecs as Pt, createFileMapStore as Q, toolOutputByteLength as Qn, baseten as Qt, SkillsConfig as R, ToolBatchExecutor as Rn, OpenAICompatHttpError as Rt, resultToString as S, PromptTextPart as Sn, StreamOptions as St, ToolDef as T, RepeatGuardToolMatcher as Tn, ToolResult as Tt, SessionStore as U, ToolResultDocumentContent as Un, OpenAIParams as Ut, SessionData as V, ToolResultAudioContent as Vn, mapOAIFinishReason as Vt, createSession as W, ToolResultDocumentRefContent as Wn, openai as Wt, FileMapAdapter as X, TurnUsage as Xn, cerebras as Xt, createMemoryStore as Y, TurnFinishReason as Yn, CerebrasParams as Yt, FileMapStoreOptions as Z, toolOutputBudgetByteLength as Zn, BasetenParams as Zt, attachStderrWarnPump as _, OAuthRefreshHookContext as _n, ContextItem as _r, toOpenAI as _t, McpConnector as a, AgentBehavior as an, AgentToolPairingError as ar, TOOL_USE_INTERRUPTED_MARKER as at, normalizeMcpBlocks as b, PromptImagePart as bn, ContextUsageSplit as br, ProviderCapabilities as bt, createAgent as c, AgentStats as cn, ClassifiedErrorKind as cr, autoDetectAndConvert as ct, DeactivationReason as d, DEFAULT_AGENT_CLOCK as dn, toTypedError as dr, ensureToolResultPairing as dt, ArceeParams as en, AgentAbortedError as er, ORPHANED_TOOL_RESULT_MARKER as et, SkillActivationState as f, DedupHasher as fn, ContextBreakdown as fr, filterUnresolvedToolUses as ft, McpConnection as g, McpToolSchema as gn, ContextExactCounts as gr, toAnthropic as gt, ConnectMcpServersOptions as h, McpToolHookContext as hn, ContextCategoryId as hr, remintDuplicateToolCallIds as ht, AgentOptions as i, applyAnthropicCacheBreakpoints as in, AgentToolNotAllowedError as ir, SYNTHETIC_TOOL_RESULT_PLACEHOLDER as it, readStateKey as j, SessionEndStatus as jn, SchemaSanitizeProfile as jt, getReadState as k, RunHookMap as kn, xai as kt, ActivationVia as l, ChildRunStats as ln, errorMessage as lr, detectTurnInterruption as lt, createSkillActivationState as m, McpServerConfig as mn, ContextCategory as mr, fromOpenAI as mt, AgentHookMap as n, AnthropicParams as nn, AgentContextExceededError as nr, PairingRepairMode as nt, McpToolMeta as o, AgentClock as on, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as or, ToWireMessagesOptions as ot, SkillActivationStateOptions as p, DedupToolConfig as pn, ContextBreakdownOptions as pr, fromAnthropic as pt, RemoteStoreOptions as q, ToolResultTextContent as qn, CursorParams as qt, AgentHooks as r, anthropic as rn, AgentProviderError as rr, RemintResult as rt, McpToolWrap as s, AgentRunOptions as sn, ClassifiedError as sr, TurnInterruptionState as st, Agent as t, arcee as tn, AgentBudgetExceededError as tr, PairingRepair as tt, ActiveSkill as u, CompactFunction as un, matchesContextExceeded as ur, ensureEndsWithUserMessage as ut, connectMcpServers as v, PromptAudioPart as vn, ContextMcpGroup as vr, toWireMessages as vt, ToolContext as w, RepeatGuardConfig as wn, ToolCall as wt, normalizeMcpServers as x, PromptPart as xn, buildContextBreakdown as xr, StreamCallbacks as xt, deriveMcpToolMeta as y, PromptDocumentPart as yn, ContextSnapshot as yr, Provider as yt, CreateSessionOptions as z, ToolHookContext as zn, OpenAICompatParams as zt };
-//# sourceMappingURL=agent-DFxjgQx5.d.ts.map
+export { EnsureToolResultPairingOptions as $, ToolResultVideoContent as $n, planBasetenReasoning as $t, hashContent as A, RepeatGuardToolMatcher as An, SchemaSanitizeOptions as At, Session as B, SpawnHookContext as Bn, classifyOpenAICompatError as Bt, wrapDiscoveredMcpTools as C, PromptAudioPart as Cn, ContextMcpGroup as Cr, TokenCountPayload as Ct, ReadStateEntry as D, PromptTextPart as Dn, TurnResult as Dt, ToolMap as E, PromptPart as En, buildContextBreakdown as Er, ToolSpec as Et, SkillDiagnostic as F, SessionContentBlock as Fn, OpenRouterParams as Ft, demoteStaleRunningStatus as G, ToolOutcome as Gn, LocalParams as Gt, SessionRun as H, ThinkingLevel as Hn, openaiCompat as Ht, SkillResource as I, SessionEndStatus as In, openrouter as It, createRemoteStore as J, ToolResultDocumentContent as Jn, cursor as Jt, loadSession as K, ToolResultAudioContent as Kn, local as Kt, SkillSource as L, SessionHookContext as Ln, OpenAICompatAuthHeader as Lt, resolveReadStateMap as M, ResolveContentRefBlock as Mn, SchemaSanitizeResult as Mt, ShellInterpolationApproval as N, RetryConfig as Nn, sanitizeToolSchema as Nt, ReadStateMap as O, PromptVideoPart as On, XaiParams as Ot, SkillConfig as P, RunHookMap as Pn, sanitizeToolSpecs as Pt, createFileMapStore as Q, ToolResultTextContent as Qn, baseten as Qt, SkillsConfig as R, SessionMessage as Rn, OpenAICompatHttpError as Rt, resultToString as S, OAuthRefreshHookContext as Sn, ContextItem as Sr, StreamOptions as St, ToolDef as T, PromptImagePart as Tn, ContextUsageSplit as Tr, ToolResult as Tt, SessionStore as U, ToolBatchExecutor as Un, OpenAIParams as Ut, SessionData as V, StreamHookContext as Vn, mapOAIFinishReason as Vt, createSession as W, ToolHookContext as Wn, openai as Wt, FileMapAdapter as X, ToolResultImageContent as Xn, cerebras as Xt, createMemoryStore as Y, ToolResultDocumentRefContent as Yn, CerebrasParams as Yt, FileMapStoreOptions as Z, ToolResultImageRefContent as Zn, BasetenParams as Zt, attachStderrWarnPump as _, DedupHasher as _n, ContextBreakdown as _r, toOpenAI as _t, McpConnector as a, AgentBehavior as an, AgentAbortedError as ar, TOOL_USE_INTERRUPTED_MARKER as at, normalizeMcpBlocks as b, McpToolHookContext as bn, ContextCategoryId as br, ProviderCapabilities as bt, createAgent as c, AgentStats as cn, AgentProviderError as cr, autoDetectAndConvert as ct, DeactivationReason as d, ChildRunStats as dn, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as dr, ensureToolResultPairing as dt, ArceeParams as en, TurnFinishReason as er, ORPHANED_TOOL_RESULT_MARKER as et, SkillActivationState as f, CompactEndHookContext as fn, ClassifiedError as fr, filterUnresolvedToolUses as ft, McpConnection as g, DEFAULT_AGENT_CLOCK as gn, toTypedError as gr, toAnthropic as gt, ConnectMcpServersOptions as h, CompactStartHookContext as hn, matchesContextExceeded as hr, remintDuplicateToolCallIds as ht, AgentOptions as i, applyAnthropicCacheBreakpoints as in, toolResultToText as ir, SYNTHETIC_TOOL_RESULT_PLACEHOLDER as it, readStateKey as j, ResolveContentRef as jn, SchemaSanitizeProfile as jt, getReadState as k, RepeatGuardConfig as kn, xai as kt, ActivationVia as l, AutoCompact as ln, AgentToolNotAllowedError as lr, detectTurnInterruption as lt, createSkillActivationState as m, CompactHookContext as mn, errorMessage as mr, fromOpenAI as mt, AgentHookMap as n, AnthropicParams as nn, toolOutputBudgetByteLength as nr, PairingRepairMode as nt, McpToolMeta as o, AgentClock as on, AgentBudgetExceededError as or, ToWireMessagesOptions as ot, SkillActivationStateOptions as p, CompactFunction as pn, ClassifiedErrorKind as pr, fromAnthropic as pt, RemoteStoreOptions as q, ToolResultContent as qn, CursorParams as qt, AgentHooks as r, anthropic as rn, toolOutputByteLength as rr, RemintResult as rt, McpToolWrap as s, AgentRunOptions as sn, AgentContextExceededError as sr, TurnInterruptionState as st, Agent as t, arcee as tn, TurnUsage as tr, PairingRepair as tt, ActiveSkill as u, AutoCompactConfig as un, AgentToolPairingError as ur, ensureEndsWithUserMessage as ut, connectMcpServers as v, DedupToolConfig as vn, ContextBreakdownOptions as vr, toWireMessages as vt, ToolContext as w, PromptDocumentPart as wn, ContextSnapshot as wr, ToolCall as wt, normalizeMcpServers as x, McpToolSchema as xn, ContextExactCounts as xr, StreamCallbacks as xt, deriveMcpToolMeta as y, McpServerConfig as yn, ContextCategory as yr, Provider as yt, CreateSessionOptions as z, SessionTurn as zn, OpenAICompatParams as zt };
+//# sourceMappingURL=agent-Db4ojCSV.d.ts.map