@theokit/agents 9.3.0 → 10.0.0

package/dist/{bridge-entry-51lU7LQw.d.ts → bridge-entry-emr2PSXC.d.ts}

@@ -1,12 +1,13 @@
 import { ExecutionContext } from '@theokit/http';
-import { d as AgentOptions, T as ToolOptions, z as ProjectContextOptions, C as CompiledAgentOptions, H as HumanInTheLoopOptions, A as AgentDefinition, a as CompiledTool, R as ReasoningEffort, G as Guardrail, p as SkillsSelection, S as SettingSourcesSelection, l as McpServersMap, M as MainLoopMeta } from './define-agent-3Kuf6iKM.js';
+import { c as AgentOptions, T as ToolOptions, p as ProjectContextOptions, C as CompiledAgentOptions, H as HumanInTheLoopOptions, b as CompiledTool, R as ReasoningEffort, G as Guardrail, S as SkillsSelection, M as McpServersMap } from './agent-compiler-CIPQkehU.js';
 import { SkillsSettings, ContextSettings, SystemPromptResolver, ModelSelection, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, CustomTool, RunEventSink, MemorySettings } from '@theokit/sdk';
+import { S as StreamEvent } from './delegation-scoring-CDvtrYKd.js';
 import { SandboxPosture } from '@theokit/sdk/sandbox';
+import { A as AgentDefinition, S as SettingSourcesSelection } from './define-agent-BO5QSjV8.js';
 import { WireChunk } from '@theokit/presenter/wire';
 import { z } from 'zod';
 import { H as HookHandlers } from './hook-handlers-Cw2FsnE5.js';
 import { TheokitAgentError } from '@theokit/sdk/errors';
-import { RetryOptions } from '@theokit/sdk/retry';
 
 /**
  * AgentExecutionContext — extends http-decorators' ExecutionContext with agent-specific methods.
@@ -119,24 +120,6 @@ declare function projectContextMetadataOnlyKnobs(options: ProjectContextOptions)
  */
 declare function compileProjectContext(options: ProjectContextOptions, base?: string | SystemPromptResolver): SystemPromptResolver;
 
-/**
- * SSE streaming handler — Web Standard Response with ReadableStream.
- *
- * Per ADR D4: SSE is the v1 transport.
- * Per EC-2: uses ReadableStream with controller.enqueue() instead of res.write().
- * Works natively on Node, Bun, Deno, CF Workers.
- */
-/** Minimal event shape matching SDK's SDKMessage discriminated union. */
-interface StreamEvent {
-    type: string;
-    [key: string]: unknown;
-}
-/**
- * Create a Web Standard Response that streams SSE events.
- * Each event becomes: `event: {type}\ndata: {json}\n\n`
- */
-declare function streamAgentResponse(eventStream: AsyncIterable<StreamEvent>): Response;
-
 /**
  * Typed discriminated union for agent SSE stream events.
  *
@@ -426,6 +409,8 @@ interface HitlWiring {
  * an absent rule resolves to `ask`.
  */
 
+/** The map of gated tools that `compileAgentDefinition` produces (`compiled.hitl`). */
+type GatedTools = ReadonlyMap<string, HumanInTheLoopOptions>;
 /**
  * What this surface does when a gated tool asks for approval. Four variants, none of them
  * "omission" — each with a concrete consumer and a written reason.
@@ -478,6 +463,20 @@ type ApprovalPosture = {
     kind: 'owned-by-surface';
     reason: string;
 };
+/**
+ * Writes the plugins the posture requires into `extra` — the object `toAgentFactory` spreads AFTER
+ * `m8` into the `Agent.create` options, and which therefore wins. Plugins already present (from the
+ * agent, via `m8`, and from an override, via `extra`) are preserved: running them over is the M14
+ * regression that `buildExtraCreateOptions` already carries a guard against.
+ *
+ * The legacy `plugins` shape (an `{ enabled }` object) cannot carry both, so a posture that needs to
+ * install a plugin alongside it is refused LOUD AND CLEAR, rather than resolved by dropping one of
+ * them: silently dropping the approval gate is exactly the class of defect this milestone closes
+ * (Rule 8, fail-closed).
+ */
+declare function applyPosture(extra: Record<string, unknown>, m8: {
+    plugins?: unknown;
+}, posturePolicy: ApprovalPosture, gated: GatedTools | undefined): void;
 
 /**
  * A definition, or a THUNK that produces one per session.
@@ -659,6 +658,85 @@ declare function toAgentFactory(def: DefinitionOrThunk, opts: {
     overrides?: RuntimeOverrides;
 }): (sessionId: string) => Promise<SdkAgentHandle>;
 
+/**
+ * T2.1 — "may I auto-approve this tool right now?", as a symbol a surface can call.
+ *
+ * ## Why this exists next to `approval-posture.ts` rather than inside it
+ *
+ * {@link applyPosture} answers a different question: *"construct this agent with a gate?"*. It runs
+ * once, at factory time, mutating an options bag. A surface asks per EVENT, before it decides
+ * whether to render a prompt, and it has no options bag in hand.
+ *
+ * Until this function existed the only reachable half of the rule was the type. `approval-posture.ts`
+ * says in writing that the consumer implemented the refusal twice and calls that a G12 violation —
+ * and it was still true when this was written, because the enforcement stayed private. A rule that
+ * lives in an unexported function lives once for the framework and zero times for everyone else.
+ *
+ * ## The invariant, stated once
+ *
+ * **Nothing auto-approves without positive evidence of enforced confinement.** Two consumer defects
+ * reduce to it:
+ *
+ *  - *B-006* — an absent posture counts as unconfined. Absence of evidence is not evidence of
+ *    confinement, and defaulting the other way silently disables the guard anywhere the posture has
+ *    not been threaded through.
+ *  - *B-021* — the headless path made the posture a required argument precisely because omitting it
+ *    returned "approved" for `full-auto`, skipping the refusal the function exists for.
+ *
+ * `posture` stays OPTIONAL in the type so a surface mid-migration still compiles; it just gets
+ * `false`. Making it required would be the stricter type and the worse outcome — a caller who cannot
+ * yet supply it writes its own predicate instead, which is how the duplication started.
+ *
+ * The peers resolve omission the same way: `codex`'s `GranularApprovalConfig` auto-REJECTS an absent
+ * field, and `opencode` resolves an absent rule to `ask`.
+ */
+
+/**
+ * What a surface does about asking, as the three modes a coding agent actually offers.
+ *
+ * Not a framework invention: these are the values the only real consumer put in front of users, and
+ * naming them here is what lets its two copies of the rule become one call.
+ */
+declare const APPROVAL_MODES: readonly ["suggest", "auto-edit", "full-auto"];
+type ApprovalMode = (typeof APPROVAL_MODES)[number];
+/**
+ * Tools whose writes are bounded by their own write root rather than by the kernel.
+ *
+ * A CATALOG, not a policy. The names are the SDK factories' defaults (`apply-patch.ts:51`,
+ * `edit-file.ts:155`, `write-file.ts:86`), so this answers "does this tool confine its own writes?"
+ * — a fact about the SDK. It does NOT answer "may this tool run without asking a human?", which is
+ * the product's to decide and is why {@link shouldAutoApprove} does not read this by default. See
+ * the `auto-edit` branch there for what conflating the two cost.
+ *
+ * Genuinely immutable, not merely typed that way. `ReadonlySet` is erased at runtime, and one
+ * `as Set<string>` on an approval gate reachable from every consumer of this package would widen
+ * what auto-approves everywhere, with no diff in the module that owns the rule. `Object.freeze`
+ * alone does not do it: a Set keeps its entries in internal slots rather than own properties, so
+ * freezing leaves `add` fully functional — the mutators have to be replaced.
+ */
+declare const WRITE_SCOPED_TOOLS: ReadonlySet<string>;
+interface ShouldAutoApproveOptions {
+    /**
+     * Which tools this PRODUCT lets run without asking, in `auto-edit`.
+     *
+     * Required in practice: absent, `auto-edit` approves nothing. {@link WRITE_SCOPED_TOOLS} is
+     * available for a product that wants every write-scoped tool, but passing it is a decision the
+     * product makes, not a default it inherits.
+     */
+    writeScopedTools?: ReadonlySet<string>;
+}
+/**
+ * Whether a gated tool may run without asking a human.
+ *
+ * Pure over its arguments and holds no state, so a surface can call it per event.
+ *
+ * @param mode - what the user chose.
+ * @param toolName - the name the model sees, which is also the approval key.
+ * @param posture - the sandbox's own answer to "am I kernel-enforced right now?". Absent or
+ *   unenforced means NOT confined, and nothing auto-approves.
+ */
+declare function shouldAutoApprove(mode: ApprovalMode, toolName: string, posture?: Pick<SandboxPosture, 'enforced'>, options?: ShouldAutoApproveOptions): boolean;
+
 /**
  * Model-selection mapping (M1 reasoning-visibility) — the single site that turns a
  * provider-agnostic `ReasoningEffort` into the SDK `ModelSelection`. Kept in its own small module
@@ -1077,373 +1155,6 @@ interface StreamAgentOptions {
  */
 declare function streamAgentUIMessages(compiled: CompiledAgentOptions, apiKey: string, input: StreamAgentOptions): AsyncGenerator<WireChunk>;
 
-/**
- * LoopStrategy — the per-round terminal-decision contract that gives runtime to
- * `@MainLoop({ strategy })`.
- *
- * V4-A proved `@MainLoop`'s `strategy` field was metadata-only (declared +
- * compiled, never executed). This module is the foundation Phase 2's
- * `runReflectiveLoop` branches on. Modeled on Mastra's `agentic-loop`/`stopWhen`
- * (inverted) + `maxSteps` ceiling — NOT Spring's per-call Advisor (plan ADR D1).
- * Config is Zod-validated so an invalid `maxIterations` fails fast at resolve
- * time, never as a silent infinite loop at runtime (plan ADR D3).
- *
- * reference: knowledge-base/references/mastra agentic-loop/index.ts (stopWhen + maxSteps).
- */
-
-/** Why a single round ended (or, for the V4-D terminals, why the whole loop ended). */
-type LoopFinishReason = 'tool-calls' | 'stop' | 'length' | 'error' | 'step_limit' | 'no_progress';
-/** Value object describing one round's result. */
-interface LoopOutcome {
-    /** Why the round ended (the continuation signal). */
-    readonly finishReason: LoopFinishReason;
-    /** 1-indexed round number that just completed. */
-    readonly round: number;
-    /** Tool calls executed during the round (V4-N: `id` correlates the call to its result). */
-    readonly toolCalls: readonly {
-        id: string;
-        name: string;
-        input: unknown;
-        output: string;
-    }[];
-    /** Accumulated assistant text for the round. */
-    readonly responseText: string;
-}
-/** The terminal-decision contract. `shouldContinue` is the inverted `stopWhen`. */
-interface LoopStrategy {
-    /**
-     * The strategy name, surfaced in `finalize`/logs. M54 relaxes this from
-     * `MainLoopMeta['strategy']` to `string` so a caller-injected `.loopStrategy(custom)` can name
-     * itself freely — the three built-ins keep their names, but the seam is no longer union-locked.
-     * The INTERNAL resolution (`loopStrategyConfigSchema`) still validates the three built-in names
-     * via `z.enum`; a custom never passes through it (it enters by the seam, not by name).
-     */
-    readonly name: string;
-    /** Hard ceiling on rounds — guarantees termination (enforced by the runner since M54). */
-    readonly maxIterations: number;
-    /** True ⇒ re-enter for another round; false ⇒ terminate. The runner caps it at `maxIterations`. */
-    shouldContinue(outcome: LoopOutcome): boolean;
-}
-/** Default round ceiling when `@MainLoop` declares no `maxIterations` (EC-3: finite, never Infinity). */
-declare const DEFAULT_MAX_ITERATIONS = 8;
-/** Serializable config for a LoopStrategy. SSoT per type-safety.md (ADR D3). */
-declare const loopStrategyConfigSchema: z.ZodObject<{
-    name: z.ZodEnum<{
-        "simple-chat": "simple-chat";
-        "plan-act-reflect": "plan-act-reflect";
-        react: "react";
-    }>;
-    maxIterations: z.ZodNumber;
-}, z.core.$strip>;
-type LoopStrategyConfig = z.infer<typeof loopStrategyConfigSchema>;
-/**
- * Map a `@MainLoop` strategy + ceiling to a concrete {@link LoopStrategy}.
- *
- * - `simple-chat` ⇒ exactly one round (`shouldContinue` always false).
- * - `react` ⇒ continue while the round ended on `tool-calls` AND the ceiling has not been reached
- *   (`round < maxIterations`) — the reflection is `noop` (no feedback), so the strategy IS the gate.
- * - `plan-act-reflect` ⇒ DEFER continuation to the reflection (V4-S): `shouldContinue` is
- *   `round < maxIterations`, so the loop continues iff the (custom) `ReflectionStrategy` returns
- *   `continue: true` within the ceiling — letting a reflection extend even a terminal (`stop`)
- *   round (e.g. "you answered without editing — make the edit now"). Backward-compatible with the
- *   default `ladderReflectionStrategy`, which itself returns `continue: true` only on `tool-calls`,
- *   so the observable behavior with the shipped ladder is unchanged.
- *
- * Throws (Zod) when `maxIterations < 1` — fail fast, never a silent infinite loop.
- */
-declare function resolveLoopStrategy(strategy: string, maxIterations?: number): LoopStrategy;
-
-interface DelegationResult {
-    response: string;
-    toolCalls: {
-        id: string;
-        name: string;
-        input: unknown;
-        output: string;
-    }[];
-    cost: number;
-    tokens: number;
-    /** V4-N: split token usage accumulated across rounds (`tokens` stays as the total). Absent for the single-shot path. */
-    tokensInput?: number;
-    tokensOutput?: number;
-    /** V4-O: reasoning/cache token buckets accumulated across rounds (0 on any loop-driven run; the loop seeds them). Optional for type compat. */
-    reasoningTokens?: number;
-    cacheReadTokens?: number;
-    cacheWriteTokens?: number;
-    /** Rounds the reflective loop ran (set by `runReflectiveLoop`; absent for the single-shot path). */
-    rounds?: number;
-    /**
-     * The loop's terminal reason (set by `runReflectiveLoop`): `'stop'`/`'length'` natural end,
-     * `'step_limit'` (hit maxIterations), `'no_progress'` (stuck). Absent for the single-shot path. (V4-D)
-     */
-    finishReason?: LoopFinishReason;
-}
-/**
- * DELEGATION budget exceeded — the dollar cost of a delegated agent.
- *
- * ## Why the name changed in M91
- *
- * It was called `BudgetExceededError` and **shadowed** the SDK class of the same name, which belongs
- * to another domain: context-WINDOW budget (`budgetName`/`window`/`mode`) against DELEGATION budget
- * (`agentName`/`actualCost`). Since the consumer holds an unbreakable rule never to import
- * `@theokit/sdk` directly, it **could never reach the SDK's** — and an `instanceof` against this
- * barrel silently matched the wrong domain.
- *
- * It is the failure mode M73 documented in `auth-parity.test.ts`: when two classes compete for the
- * same name, no behavioural test goes red — only an identity `toBe` catches it.
- *
- * `subpath-coverage.test.ts` recorded the collision as a `gap` on `./errors`, with the reason written
- * down and the acknowledgement that renaming was breaking and out of M78's scope. M91 paid the bill.
- */
-/**
- * M80 — extends {@link TheokitAgentError}, not plain `Error`.
- *
- * `isTransientError` is defined over `TheokitAgentError`, so a class outside that hierarchy is
- * INVISIBLE to it and the only recourse left to a consumer is matching on message text. `code` is
- * stable across a rename; `isRetryable` is DECLARED, because a default would be a retry policy
- * nobody chose.
- */
-declare class DelegationBudgetExceededError extends TheokitAgentError {
-    readonly agentName: string;
-    readonly actualCost: number;
-    readonly budgetLimit: number;
-    readonly name = "DelegationBudgetExceededError";
-    constructor(agentName: string, actualCost: number, budgetLimit: number);
-}
-/**
- * @deprecated Use {@link DelegationBudgetExceededError}. The alias is kept for one major so anyone
- * catching by the old name is not broken; it is the **same** class, not a copy — `instanceof` still
- * holds in both directions, and a referential-identity test (`toBe`) pins that.
- */
-declare const BudgetExceededError: typeof DelegationBudgetExceededError;
-/** @deprecated Use {@link DelegationBudgetExceededError}. */
-type BudgetExceededError = DelegationBudgetExceededError;
-/**
- * M80 — extends {@link TheokitAgentError}, not plain `Error`.
- *
- * `isTransientError` is defined over `TheokitAgentError`, so a class outside that hierarchy is
- * INVISIBLE to it and the only recourse left to a consumer is matching on message text. `code` is
- * stable across a rename; `isRetryable` is DECLARED, because a default would be a retry policy
- * nobody chose.
- */
-declare class DelegationError extends TheokitAgentError {
-    readonly agentName: string;
-    readonly cause: unknown;
-    readonly name = "DelegationError";
-    constructor(agentName: string, cause: unknown);
-}
-
-/**
- * ReflectionStrategy — composes INTO the loop between rounds (the loop calls
- * `reflect()` then `LoopStrategy.shouldContinue()`).
- *
- * `'plan-act-reflect'` resolves to the `'ladder'` default shipped here; a custom
- * strategy may be supplied (OCP — plan Drawback #2). `reflect()` is pure (no
- * I/O, no LLM) — it inspects the round's outcome and returns feedback to inject
- * into the next round's prompt plus a `continue` hint. The hard round ceiling
- * lives in `LoopStrategy.shouldContinue` (maxIterations), NOT here.
- *
- * reference: knowledge-base/references/mastra agentic-loop/index.ts (onIterationComplete → { feedback, continue }).
- */
-
-/** Result of reflecting on a completed round. */
-interface ReflectionResult {
-    /** Optional text prepended to the next round's prompt. */
-    readonly feedback?: string;
-    /** Hint: should the loop reflect-and-continue? (the ceiling still bounds it) */
-    readonly continue: boolean;
-}
-/**
- * V4-K: a per-run mutable scratch bag threaded to every `reflect()` call within one
- * `runReflectiveLoopStream` run, so a STATEFUL strategy can accumulate cumulative state
- * (counters, one-shot flags) across rounds. The framework owns the lifecycle (creates
- * one per run, passes the SAME ref each round) but writes NOTHING into it — the strategy
- * owns the contents. Generic by design: the framework cannot know app semantics (e.g.
- * what an "edit" is). A consumer narrows it locally (`ctx as MyState`).
- */
-type ReflectionContext = Record<string, unknown>;
-/** Pluggable between-round reflection. Pure — never performs I/O. */
-interface ReflectionStrategy {
-    /** Strategy identifier (e.g. `'ladder'`). */
-    readonly name: string;
-    /**
-     * Inspect the round outcome; return feedback + continue hint. `ctx` (V4-K) is the
-     * per-run mutable scratch — optional for backward compatibility (shipped strategies
-     * ignore it; stateful custom strategies accumulate in it across rounds).
-     */
-    reflect(outcome: LoopOutcome, ctx?: ReflectionContext): ReflectionResult;
-}
-/** Serializable config for a ReflectionStrategy. SSoT per type-safety.md (ADR D3). */
-declare const reflectionStrategyConfigSchema: z.ZodObject<{
-    name: z.ZodString;
-}, z.core.$strip>;
-type ReflectionStrategyConfig = z.infer<typeof reflectionStrategyConfigSchema>;
-/**
- * The default `'ladder'` reflection (what `'plan-act-reflect'` resolves to).
- *
- * Continues with bounded templated feedback while the round ended on
- * `tool-calls`; terminates on any terminal `finishReason` (`stop`/`error`/
- * `length`). The feedback is a short fixed template (bounded — EC-5; context
- * growth is the SDK's responsibility, not the loop's).
- */
-declare const ladderReflectionStrategy: ReflectionStrategy;
-/**
- * No-op reflection for `'react'` (multi-round WITHOUT reflection feedback).
- *
- * Returns `{ continue: true }` (no feedback) so the round-continuation decision
- * is delegated entirely to `LoopStrategy.shouldContinue` (i.e. `react` loops
- * while `finishReason === 'tool-calls'` under the ceiling). NOTE: the plan's
- * pseudo-code (Files-to-edit) sketched `{ continue: false }`, which would make
- * `react` single-shot — that contradicts the plan's own Deep Dives ("`react`
- * still multi-rounds while finishReason==='tool-calls'"); `continue: true` is
- * the behavior the resolved react LoopStrategy requires.
- */
-declare const noopReflectionStrategy: ReflectionStrategy;
-
-/**
- * runReflectiveLoop — the multi-round reflective driver that gives `@MainLoop`
- * its runtime (closes the metadata-only gap, V4-A / plan ADR D2).
- *
- * Per round it consumes ONE SDK stream turn (the model call stays in the SDK —
- * the factory is `createSdkAgentStream(...)`, injected for testability), derives
- * a {@link LoopOutcome}, asks the {@link ReflectionStrategy} for feedback, then
- * the {@link LoopStrategy} whether to continue. Bounded by `maxIterations`
- * (forced terminal at the ceiling — never an infinite loop). The bridge owns the
- * loop; the SDK owns the model call (sdk-runtime.md / ADR 0031 — no second runtime).
- *
- * `runReflectiveLoop` is INTERNAL (not re-exported from the package barrel,
- * Drawback #4) — consumed by `delegate()` (T2.2) and `AgentRunner` (T3.1).
- *
- * reference: knowledge-base/references/mastra agent.ts (re-enter the loop with feedback).
- */
-
-/** One SDK stream turn: `createSdkAgentStream(...)` returns this shape. */
-/**
- * Opens one round's SDK stream. `opts.disableTools` (step-cap force-close) asks the factory to
- * gate tools OFF for THIS round (the SDK adapter maps it to `tool_choice:"none"` at send-time, so a
- * cached agent — whose tools can't be un-registered — is still forced to a text summary). Optional +
- * ignored by injected test factories ⇒ backward-compatible.
- */
-type RoundStreamFactory = (message: string, sessionId: string, opts?: {
-    disableTools?: boolean;
-}) => AsyncIterable<StreamEvent>;
-
-/**
- * Multi-agent orchestration runtime.
- *
- * Provides `delegate()` — a function that lets a parent agent invoke a
- * sub-agent and receive its result. Handles budget clamping (D4), tool sharing,
- * toolbox auto-instantiation (EC-1), and routes the resolved `@MainLoop` strategy
- * through `runReflectiveLoop` — the SAME driver `AgentRunner.run()` uses, so both
- * on-ramps are one runtime (ADR D4). `simple-chat` ⇒ `shouldContinue:()=>false`
- * ⇒ exactly one round; `react`/`plan-act-reflect` ⇒ multi-round reflective loop.
- */
-
-interface DelegateOptions {
-    /**
-     * M81 — wall-clock cap for the delegation, in milliseconds. Absent ⇒ no clock cap.
-     *
-     * A DIFFERENT guard from `budget`: money is spent by work that progresses, and a delegation that
-     * HANGS burns clock without spending a cent. A consumer wrote its own timeout race with its own
-     * typed error because this was missing. Exceeding it raises `DelegationTimeoutError`, which —
-     * unlike the budget errors — is marked retryable, because a hang is often transient.
-     */
-    readonly timeoutMs?: number;
-    /** Max USD for this sub-agent call. */
-    budget?: number;
-    /** Parent's remaining budget (for clamping). */
-    parentBudgetRemaining?: number;
-    /** Parent's tools (for sharing — sub-agent inherits these). */
-    parentTools?: CompiledTool[];
-    /**
-     * Parent's hooks. The member inherits them, and inheritance may only TIGHTEN: both
-     * `pre_tool_call` gates run and the first refusal wins, so a member cannot widen what the parent
-     * refused.
-     *
-     * Symmetric with `parentTools` on purpose — `delegate` already carried the parent's tools and its
-     * budget into the member's run and left its AUTHORITY behind, which is how a squad member could
-     * call a tool the supervisor had vetoed. The failure was silent: nothing threw, and the member's
-     * own suite passed because the member never declared the gate.
-     *
-     * To scope a member differently, pass its handlers on `spec.compiled.hooks` — they compose with
-     * these rather than replacing them, because a widening that a call site cannot see is the state
-     * this option exists to remove.
-     */
-    parentHooks?: HookHandlers;
-    /** LLM API key (inherited from parent). */
-    apiKey?: string;
-    /** Session ID override (default: crypto.randomUUID for isolation). */
-    sessionId?: string;
-    /** Cancellation — aborts stop the reflective loop from re-entering. */
-    signal?: AbortSignal;
-    /** Per-run model override (`?? SubAgent @Agent model`). */
-    model?: string;
-    /** Per-run working directory → `Agent.create({ local: { cwd } })`. */
-    cwd?: string;
-    /** Per-run plugins (e.g. a read-only permission gate for an explore sub-agent). */
-    plugins?: PluginsSettings;
-    /** Per-run provider routing (e.g. OpenRouter). */
-    providers?: ProviderRoutingSettings;
-    /** Per-run sub-agent definitions. */
-    agents?: Record<string, AgentDefinition$1>;
-    /** Per-run SDK budget tracker (inner tool-loop cap). */
-    budgetTracker?: BudgetTracker;
-    /** Per-run pre-built SDK tools forwarded raw (V4-Q). */
-    sdkTools?: readonly CustomTool[];
-    /** Per-round transient retry (V4-P). */
-    retry?: RetryOptions;
-    /** Custom between-round reflection (default: ladder for `plan-act-reflect`, else noop). */
-    reflection?: ReflectionStrategy;
-    /** Per-run loop-ceiling override (`?? SubAgent @MainLoop maxIterations`). */
-    maxIterations?: number;
-    /**
-     * Called BEFORE the sub-agent runs. Returns the input the sub-agent will receive — return
-     * `ctx.input` unchanged, or a rewritten string (e.g. inject a persona). A transform, not a veto.
-     */
-    onDelegationStart?: (ctx: {
-        subAgent: string;
-        input: string;
-    }) => string | Promise<string>;
-    /**
-     * Called AFTER the sub-agent completes. Returns the result the supervisor sees — return
-     * `ctx.result` unchanged, or a transformed one (e.g. redact, score, re-wrap).
-     */
-    onDelegationComplete?: (ctx: {
-        subAgent: string;
-        result: DelegationResult;
-    }) => DelegationResult | Promise<DelegationResult>;
-    /**
-     * Injected stream factory (parity with `AgentRunnerRunOptions.streamFactory`) — drives the loop
-     * directly instead of the SDK adapter (tests / custom transport). Absent ⇒ `createSdkAgentStream`.
-     */
-    streamFactory?: RoundStreamFactory;
-}
-/**
- * Delegate a task to a sub-agent and collect its result.
- *
- * - Budget clamping: `min(parentBudgetRemaining, budget)` (D4)
- * - Tool sharing: parent tools merged with sub-agent tools (sub wins on collision)
- * - Toolbox auto-instantiation: sub-agent toolboxes instantiated without DI (EC-1)
- * - Session isolation: each delegation gets a unique session ID (EC-4)
- * - `@MainLoop` strategy runtime: routes through `runReflectiveLoop` (the same loop
- *   `AgentRunner.run` uses — one runtime for both on-ramps, ADR D4). The runtime
- *   metric (`THEO_AGENT_MAINLOOP_RUNTIME_APPLIED`) + typed-error + cumulative budget
- *   all live in the shared driver, so they fire identically on both paths.
- */
-/**
- * What `delegate` needs from a sub-agent: a name and already-compiled options (built by
- * `applyCapabilities`). Compatible with {@link AgentRunnerSpec} — one spec drives both on-ramps.
- */
-interface SubAgentSpec {
-    readonly name: string;
-    readonly compiled: CompiledAgentOptions;
-    /** Loop strategy (`@MainLoop({ strategy })`); absent ⇒ the same `'simple-chat'` default. */
-    readonly strategy?: MainLoopMeta['strategy'];
-    /** Loop ceiling (`@MainLoop({ maxIterations })`); a per-run override still wins. */
-    readonly maxIterations?: number;
-}
-declare function delegate(spec: SubAgentSpec, message: string, opts?: DelegateOptions): Promise<DelegationResult>;
-
 /**
  * M10 (theokit-ai-first) — createToolHooksPlugin: `beforeToolCall` / `afterToolCall` observability.
  *
@@ -1592,82 +1303,6 @@ declare function runWithApiErrorHandling<R>(thunk: () => Promise<R>, policy: Api
  */
 declare function createApiErrorHandler<R = unknown>(policy: ApiErrorPolicy<R>): (thunk: () => Promise<R>) => Promise<R>;
 
-/**
- * M25 (theokit-ai-first) — background delegation + task-completion scoring.
- *
- * Two THIN wrappers over the M12 `delegate` (ADR 0038/0040): no new orchestration engine, no second
- * loop, no new store. `delegateBackground` kicks off a sub-agent without blocking the supervisor and
- * hands back a handle to await later. `delegateWithScoring` runs `delegate`, scores the result with
- * an injected scorer, and re-delegates with the scorer's feedback until it passes or `maxRounds` is
- * hit. The `delegate` implementation is injectable (`delegateFn`) so this is testable without a
- * SubAgent class or an LLM — and so it NEVER re-implements the delegation runtime.
- */
-
-/**
- * M81 — anything that can run a delegation.
- *
- * The reach gap this closes: both wrappers took a `SubAgentSpec` produced by the capability
- * compiler, so a consumer holding an SDK `SubAgent` or `Squad` could not feed them. That is why the
- * scoring loop — the layer's highest-value piece — had ZERO adoption in a product that runs an
- * explicit review pass: it was unreachable from the primitives that product actually holds.
- *
- * An SDK `SubAgent` or `Squad` satisfies this by having `run`. So does a test double, which is why
- * the loop is now testable without a compiler, a class or an LLM.
- */
-interface DelegationPort {
-    run(message: string): Promise<DelegationResult>;
-}
-/** What both wrappers accept: the compiled spec (unchanged) or the port (M81, additive). */
-type DelegationTarget = SubAgentSpec | DelegationPort;
-/** The delegation primitive both wrappers drive. Defaults to the M12 {@link delegate}. */
-type DelegateFn = (subAgent: SubAgentSpec, message: string, opts?: DelegateOptions) => Promise<DelegationResult>;
-/** A running background delegation the supervisor can await/poll later. */
-interface BackgroundDelegation {
-    /** Await the sub-agent's result (or rejection). Idempotent — returns the same settled promise. */
-    wait(): Promise<DelegationResult>;
-    /** Whether the underlying delegation has resolved or rejected. */
-    settled(): boolean;
-}
-/**
- * Start a sub-agent WITHOUT blocking the supervisor. Returns immediately with a handle; the
- * supervisor keeps working and calls `wait()` when it needs the result. A thin async wrapper over
- * `delegate` — not a scheduler (Top-risk 1). Rejections are still observable via `wait()`.
- */
-declare function delegateBackground(subAgent: DelegationTarget, message: string, opts?: DelegateOptions & {
-    delegateFn?: DelegateFn;
-}): BackgroundDelegation;
-/** A scorer's verdict on a sub-agent result. `feedback` is fed back into the next round on failure. */
-interface ScoreVerdict {
-    pass: boolean;
-    /** Optional numeric score (0..1) for logging/telemetry. */
-    score?: number;
-    /** Guidance appended to the next delegation when `pass` is false. */
-    feedback?: string;
-}
-/** Scores a sub-agent result. Opt-in (Top-risk 2) — the caller supplies it, and pays its cost. */
-type Scorer = (result: DelegationResult) => ScoreVerdict | Promise<ScoreVerdict>;
-/** The outcome of a scored delegation: the final result plus the per-round verdict trail. */
-interface ScoredDelegation {
-    result: DelegationResult;
-    /** Rounds actually run (1..maxRounds). */
-    rounds: number;
-    /** Whether the final round passed the scorer. */
-    passed: boolean;
-    /** The verdict from each round, in order. */
-    verdicts: ScoreVerdict[];
-}
-/**
- * Run `delegate`, score the result, and re-delegate with the scorer's feedback until it passes or
- * `maxRounds` is reached. Each round is ONE `delegate` call — no second loop, no new store. Returns
- * the final result (passing, or the last attempt) with the per-round verdict trail.
- */
-declare function delegateWithScoring(subAgent: DelegationTarget, message: string, opts: DelegateOptions & {
-    scorer: Scorer;
-    maxRounds?: number;
-    delegateFn?: DelegateFn;
-    feedbackTemplate?: (message: string, feedback: string) => string;
-}): Promise<ScoredDelegation>;
-
 /**
  * M81 — the two gaps around a delegation's LIFE, as opposed to its execution.
  *
@@ -1959,4 +1594,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-export { type LoopStrategyConfig as $, type AgentManifestEntry as A, type BackgroundDelegation as B, type ContextWindowOptions as C, type DelegationResult as D, type CompiledContextWindow as E, ContextualTool as F, DEFAULT_MAX_ITERATIONS as G, type HitlDecision as H, type DefinitionOrThunk as I, type DelegateFn as J, type DelegateOptions as K, type LoopStrategy as L, DelegationBudgetExceededError as M, DelegationError as N, type DelegationPort as O, type DelegationTarget as P, DelegationTimeoutError as Q, type ReflectionStrategy as R, type StreamEvent as S, type DoneEvent as T, type EphemeralAgent as U, type ErrorEvent as V, type FileEditEvent as W, type IterationEvent as X, type LLMCallContext as Y, type LoopFinishReason as Z, type LoopOutcome as _, type RoundStreamFactory as a, resolveMcpServers as a$, type McpApprovalSpec as a0, McpFileError as a1, type McpRegistryConfig as a2, type McpRequestContext as a3, type McpSelection as a4, type PartialToolCallEvent as a5, type ProcessInputContext as a6, type ReflectionContext as a7, type ReflectionResult as a8, type ReflectionStrategyConfig as a9, createThinkTagExtractor as aA, createToolHooksPlugin as aB, delegate as aC, delegateBackground as aD, delegateWithScoring as aE, extractThinkTagStream as aF, generateAgentManifest as aG, generateAgentRoutes as aH, isAgentContext as aI, isApprovalRequired as aJ, isDone as aK, isError as aL, isPartialToolCall as aM, isTextDelta as aN, isToolCall as aO, isToolResult as aP, ladderReflectionStrategy as aQ, loadMcpJson as aR, loopStrategyConfigSchema as aS, mcpRegistry as aT, mcpToolApprovals as aU, noopReflectionStrategy as aV, presentUIMessageStream as aW, projectContextMetadataOnlyKnobs as aX, reasoningEffortOf as aY, reflectionStrategyConfigSchema as aZ, resolveLoopStrategy as a_, type RunStartedEvent as aa, type ScoreVerdict as ab, type ScoredDelegation as ac, type Scorer as ad, type SdkAgentHandle as ae, type SdkMessage as af, type SdkSendOptions as ag, type SdkTurnHandle as ah, type Segment as ai, type StateUpdateEvent as aj, type TextDeltaEvent as ak, type ThinkingEvent as al, type ToolCallEvent as am, type ToolCallVeto as an, type ToolHooks as ao, type ToolHooksPlugin as ap, type ToolResultEvent as aq, agentsPlugin as ar, buildModelSelection as as, compileAgentModule as at, compileContextWindow as au, compileProjectContext as av, compileSkills as aw, createAgentExecutionContext as ax, createApiErrorHandler as ay, createSdkAgentStream as az, type SkillsOptions as b, runWithApiErrorHandling as b0, streamAgentResponse as b1, toAgentFactory as b2, translateSdkEvent as b3, withClockCap as b4, withEphemeralAgent as b5, type ApprovalPosture as c, type AfterToolCallContext as d, AgentBuilder as e, AgentDefinitionError as f, type AgentExecutionContext as g, type AgentManifest as h, type AgentManifestSource as i, type AgentManifestTool as j, type AgentRoute as k, type AgentRouteContext as l, type AgentRunInfo as m, type AgentStreamEvent as n, type AgentTurnMetadata as o, type AgentsPluginOptions as p, type ApiErrorContext as q, type ApiErrorDecision as r, streamAgentUIMessages as s, type ApiErrorPolicy as t, type ApprovalRequiredEvent as u, type ArtifactChunkEvent as v, type ArtifactStartEvent as w, type BeforeToolCallContext as x, BudgetExceededError as y, type CheckpointSavedEvent as z };
+export { type StateUpdateEvent as $, type AgentManifestEntry as A, type BeforeToolCallContext as B, type ContextWindowOptions as C, type DefinitionOrThunk as D, DelegationTimeoutError as E, type DoneEvent as F, type EphemeralAgent as G, type HitlDecision as H, type ErrorEvent as I, type FileEditEvent as J, type IterationEvent as K, type LLMCallContext as L, type McpApprovalSpec as M, McpFileError as N, type McpRegistryConfig as O, type McpRequestContext as P, type McpSelection as Q, type PartialToolCallEvent as R, type SkillsOptions as S, type ProcessInputContext as T, type RunStartedEvent as U, type SdkAgentHandle as V, type SdkMessage as W, type SdkSendOptions as X, type SdkTurnHandle as Y, type Segment as Z, type ShouldAutoApproveOptions as _, type ApprovalPosture as a, type TextDeltaEvent as a0, type ThinkingEvent as a1, type ToolCallEvent as a2, type ToolCallVeto as a3, type ToolHooks as a4, type ToolHooksPlugin as a5, type ToolResultEvent as a6, WRITE_SCOPED_TOOLS as a7, agentsPlugin as a8, applyPosture as a9, reasoningEffortOf as aA, resolveMcpServers as aB, runWithApiErrorHandling as aC, shouldAutoApprove as aD, toAgentFactory as aE, translateSdkEvent as aF, withClockCap as aG, withEphemeralAgent as aH, buildModelSelection as aa, compileAgentModule as ab, compileContextWindow as ac, compileProjectContext as ad, compileSkills as ae, createAgentExecutionContext as af, createApiErrorHandler as ag, createSdkAgentStream as ah, createThinkTagExtractor as ai, createToolHooksPlugin as aj, extractThinkTagStream as ak, generateAgentManifest as al, generateAgentRoutes as am, isAgentContext as an, isApprovalRequired as ao, isDone as ap, isError as aq, isPartialToolCall as ar, isTextDelta as as, isToolCall as at, isToolResult as au, loadMcpJson as av, mcpRegistry as aw, mcpToolApprovals as ax, presentUIMessageStream as ay, projectContextMetadataOnlyKnobs as az, APPROVAL_MODES as b, type AfterToolCallContext as c, AgentBuilder as d, AgentDefinitionError as e, type AgentExecutionContext as f, type AgentManifest as g, type AgentManifestSource as h, type AgentManifestTool as i, type AgentRoute as j, type AgentRouteContext as k, type AgentRunInfo as l, type AgentStreamEvent as m, type AgentTurnMetadata as n, type AgentsPluginOptions as o, type ApiErrorContext as p, type ApiErrorDecision as q, type ApiErrorPolicy as r, streamAgentUIMessages as s, type ApprovalMode as t, type ApprovalRequiredEvent as u, type ArtifactChunkEvent as v, type ArtifactStartEvent as w, type CheckpointSavedEvent as x, type CompiledContextWindow as y, ContextualTool as z };

package/dist/bridge.d.ts

@@ -1,5 +1,7 @@
-export { d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinitionError, g as AgentExecutionContext, h as AgentManifest, A as AgentManifestEntry, i as AgentManifestSource, j as AgentManifestTool, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentStreamEvent, o as AgentTurnMetadata, p as AgentsPluginOptions, q as ApiErrorContext, r as ApiErrorDecision, t as ApiErrorPolicy, c as ApprovalPosture, u as ApprovalRequiredEvent, v as ArtifactChunkEvent, w as ArtifactStartEvent, B as BackgroundDelegation, x as BeforeToolCallContext, y as BudgetExceededError, z as CheckpointSavedEvent, E as CompiledContextWindow, F as ContextualTool, I as DefinitionOrThunk, J as DelegateFn, K as DelegateOptions, M as DelegationBudgetExceededError, N as DelegationError, O as DelegationPort, D as DelegationResult, P as DelegationTarget, Q as DelegationTimeoutError, T as DoneEvent, U as EphemeralAgent, V as ErrorEvent, W as FileEditEvent, X as IterationEvent, Y as LLMCallContext, a0 as McpApprovalSpec, a1 as McpFileError, a2 as McpRegistryConfig, a3 as McpRequestContext, a4 as McpSelection, a5 as PartialToolCallEvent, a6 as ProcessInputContext, aa as RunStartedEvent, ab as ScoreVerdict, ac as ScoredDelegation, ad as Scorer, ae as SdkAgentHandle, af as SdkMessage, ag as SdkSendOptions, ah as SdkTurnHandle, ai as Segment, aj as StateUpdateEvent, S as StreamEvent, ak as TextDeltaEvent, al as ThinkingEvent, am as ToolCallEvent, an as ToolCallVeto, ao as ToolHooks, ap as ToolHooksPlugin, aq as ToolResultEvent, ar as agentsPlugin, as as buildModelSelection, at as compileAgentModule, au as compileContextWindow, av as compileProjectContext, aw as compileSkills, ax as createAgentExecutionContext, ay as createApiErrorHandler, az as createSdkAgentStream, aA as createThinkTagExtractor, aB as createToolHooksPlugin, aC as delegate, aD as delegateBackground, aE as delegateWithScoring, aF as extractThinkTagStream, aG as generateAgentManifest, aH as generateAgentRoutes, aI as isAgentContext, aJ as isApprovalRequired, aK as isDone, aL as isError, aM as isPartialToolCall, aN as isTextDelta, aO as isToolCall, aP as isToolResult, aR as loadMcpJson, aT as mcpRegistry, aU as mcpToolApprovals, aW as presentUIMessageStream, aX as projectContextMetadataOnlyKnobs, aY as reasoningEffortOf, a$ as resolveMcpServers, b0 as runWithApiErrorHandling, b1 as streamAgentResponse, s as streamAgentUIMessages, b2 as toAgentFactory, b3 as translateSdkEvent, b4 as withClockCap, b5 as withEphemeralAgent } from './bridge-entry-51lU7LQw.js';
-export { c as AGENT_BRAND, A as AgentDefinition, C as CompiledAgentOptions, a as CompiledTool, D as DefineAgentConfig, I as InferAgentInput, j as InferAgentToolNames, m as ProjectSettingsGrant, n as SettingSourceCapability, S as SettingSourcesSelection, r as ToolWalkResult, t as ToolboxWalkResult, U as UntrustedSettingSourceError, u as compileAgentDefinition, v as compileTools, w as isAgentDefinition, y as resolveSettingSources } from './define-agent-3Kuf6iKM.js';
+export { b as APPROVAL_MODES, c as AfterToolCallContext, d as AgentBuilder, e as AgentDefinitionError, f as AgentExecutionContext, g as AgentManifest, A as AgentManifestEntry, h as AgentManifestSource, i as AgentManifestTool, j as AgentRoute, k as AgentRouteContext, l as AgentRunInfo, m as AgentStreamEvent, n as AgentTurnMetadata, o as AgentsPluginOptions, p as ApiErrorContext, q as ApiErrorDecision, r as ApiErrorPolicy, t as ApprovalMode, a as ApprovalPosture, u as ApprovalRequiredEvent, v as ArtifactChunkEvent, w as ArtifactStartEvent, B as BeforeToolCallContext, x as CheckpointSavedEvent, y as CompiledContextWindow, z as ContextualTool, D as DefinitionOrThunk, E as DelegationTimeoutError, F as DoneEvent, G as EphemeralAgent, I as ErrorEvent, J as FileEditEvent, K as IterationEvent, L as LLMCallContext, M as McpApprovalSpec, N as McpFileError, O as McpRegistryConfig, P as McpRequestContext, Q as McpSelection, R as PartialToolCallEvent, T as ProcessInputContext, U as RunStartedEvent, V as SdkAgentHandle, W as SdkMessage, X as SdkSendOptions, Y as SdkTurnHandle, Z as Segment, _ as ShouldAutoApproveOptions, $ as StateUpdateEvent, a0 as TextDeltaEvent, a1 as ThinkingEvent, a2 as ToolCallEvent, a3 as ToolCallVeto, a4 as ToolHooks, a5 as ToolHooksPlugin, a6 as ToolResultEvent, a7 as WRITE_SCOPED_TOOLS, a8 as agentsPlugin, a9 as applyPosture, aa as buildModelSelection, ab as compileAgentModule, ac as compileContextWindow, ad as compileProjectContext, ae as compileSkills, af as createAgentExecutionContext, ag as createApiErrorHandler, ah as createSdkAgentStream, ai as createThinkTagExtractor, aj as createToolHooksPlugin, ak as extractThinkTagStream, al as generateAgentManifest, am as generateAgentRoutes, an as isAgentContext, ao as isApprovalRequired, ap as isDone, aq as isError, ar as isPartialToolCall, as as isTextDelta, at as isToolCall, au as isToolResult, av as loadMcpJson, aw as mcpRegistry, ax as mcpToolApprovals, ay as presentUIMessageStream, az as projectContextMetadataOnlyKnobs, aA as reasoningEffortOf, aB as resolveMcpServers, aC as runWithApiErrorHandling, aD as shouldAutoApprove, s as streamAgentUIMessages, aE as toAgentFactory, aF as translateSdkEvent, aG as withClockCap, aH as withEphemeralAgent } from './bridge-entry-emr2PSXC.js';
+export { C as CompiledAgentOptions, b as CompiledTool, l as ToolWalkResult, n as ToolboxWalkResult, o as compileTools } from './agent-compiler-CIPQkehU.js';
+export { B as BackgroundDelegation, d as BudgetExceededError, f as DelegateFn, a as DelegateOptions, g as DelegationBudgetExceededError, h as DelegationError, i as DelegationPort, c as DelegationResult, D as DelegationTarget, p as ScoreVerdict, q as ScoredDelegation, r as Scorer, S as StreamEvent, s as delegate, t as delegateBackground, u as delegateWithScoring, A as streamAgentResponse } from './delegation-scoring-CDvtrYKd.js';
+export { a as AGENT_BRAND, A as AgentDefinition, D as DefineAgentConfig, I as InferAgentInput, b as InferAgentToolNames, P as ProjectSettingsGrant, c as SettingSourceCapability, S as SettingSourcesSelection, U as UntrustedSettingSourceError, d as compileAgentDefinition, i as isAgentDefinition, r as resolveSettingSources } from './define-agent-BO5QSjV8.js';
 import '@theokit/http';
 import '@theokit/sdk';
 import '@theokit/sdk/sandbox';