@theokit/agents 0.30.1 → 0.31.0

package/dist/{bridge-entry-DVhOQc_f.d.ts → bridge-entry-DtDotZGW.d.ts}

@@ -102,6 +102,75 @@ declare function walkAgentMetadata(AgentClass: Function, toolboxClasses?: Functi
  */
 declare function validateUniqueRoutes(results: AgentWalkResult[]): void;
 
+/**
+ * M9 (theokit-ai-first) — guardrail contract + typed errors.
+ *
+ * ADR-0040 § D2: guardrails are a HOME/BOUNDARY concern (filter user input before the SDK,
+ * filter model output before the client). They REUSE the SDK runtime — this module makes zero
+ * LLM calls. A guard reports one of three actions; the pipeline (`pipeline.ts`) enforces them.
+ */
+/** What a guard decided for a piece of text. */
+type GuardrailAction = 'allow' | 'block' | 'redact';
+/**
+ * The result of a single guard check.
+ * - `allow`  — text passes untouched.
+ * - `block`  — the pipeline throws {@link GuardrailViolationError}; the run stops fail-fast.
+ * - `redact` — the pipeline replaces the text with {@link GuardrailResult.text} and continues.
+ */
+interface GuardrailResult {
+    action: GuardrailAction;
+    /** Human-readable reason — required in spirit for `block`, surfaced in the thrown error. */
+    reason?: string;
+    /** The transformed text — present (and used) only when `action === 'redact'`. */
+    text?: string;
+}
+/**
+ * A guardrail. A guard MAY inspect input (before the model), output (after the model), or both.
+ * A guard that omits a phase hook is skipped for that phase.
+ */
+interface Guardrail {
+    readonly name: string;
+    checkInput?(text: string): GuardrailResult | Promise<GuardrailResult>;
+    checkOutput?(text: string): GuardrailResult | Promise<GuardrailResult>;
+}
+/** Which boundary phase a violation happened in. */
+type GuardrailPhase = 'input' | 'output';
+/** Thrown (fail-fast) when a guard returns `action: 'block'`. Typed per error-handling.md. */
+declare class GuardrailViolationError extends Error {
+    readonly guardName: string;
+    readonly phase: GuardrailPhase;
+    readonly reason: string;
+    constructor(guardName: string, phase: GuardrailPhase, reason: string);
+}
+/** Thrown when {@link costGuard}'s cumulative token budget is exceeded. */
+declare class CostBudgetExceededError extends Error {
+    readonly usedTokens: number;
+    readonly maxTokens: number;
+    constructor(usedTokens: number, maxTokens: number);
+}
+
+/**
+ * M13 (theokit-ai-first) — per-request skills resolution (ADR-0040 § D2, home/boundary concern).
+ *
+ * The static `skills.enabled` filter already works (`compile-skills` maps `include` → the SDK's
+ * `enabled`). This adds a PER-REQUEST resolver so multi-tenant apps expose different skill sets to
+ * different users. A selection is either a static list or a function of the request context (the M7
+ * run-context). Discovery + injection stay in the SDK; this only CHOOSES the enabled set per call.
+ */
+/** The request context handed to a skills resolver (the M7 run-context — opaque per-request data). */
+type SkillsRequestContext = Record<string, unknown>;
+/**
+ * How the enabled skill set is chosen:
+ * - `string[]`  — a static list (same shape `skills.enabled` accepts today).
+ * - a function  — resolved per request from the {@link SkillsRequestContext} (sync or async).
+ */
+type SkillsSelection = readonly string[] | ((ctx: SkillsRequestContext) => readonly string[] | Promise<readonly string[]>);
+/**
+ * Resolve the enabled skill names for a request. Returns `undefined` when no selection is given (the
+ * SDK then enables every discovered skill). Fails fast if a resolver returns a non-array.
+ */
+declare function resolveEnabledSkills(selection: SkillsSelection | undefined, ctx: SkillsRequestContext): Promise<string[] | undefined>;
+
 /**
  * Agent compiler — transforms decorator metadata into SDK calls.
  *
@@ -116,7 +185,17 @@ interface CompiledTool {
     name: string;
     description: string;
     inputSchema: unknown;
-    handler: (input: unknown) => string | Promise<string>;
+    /**
+     * M7 — the optional 2nd `ctx` arg carries the SDK run context: `ctx.context` is the
+     * `defineAgent({ context })` / per-run value, `ctx.signal` the abort signal. Optional so the
+     * decorator `@Tool` handlers (which ignore it) stay assignable. The SDK calls the tool with
+     * both args; a handler that needs run-context (e.g. a filesystem tool reading `projectRoot`)
+     * reads `ctx?.context`.
+     */
+    handler: (input: unknown, ctx?: {
+        signal?: AbortSignal;
+        context?: unknown;
+    }) => string | Promise<string>;
 }
 /**
  * Compile @Tool metadata into tool definitions.
@@ -155,6 +234,13 @@ interface CompiledAgentOptions {
     memory?: MemoryOptions;
     skills?: SkillsSettings;
     context?: ContextSettings;
+    /**
+     * M7 — run-context injected into every tool handler's `ctx.context` by the theokit adapter
+     * (`buildSdkTools` wrapper). Populated by `defineAgent({ context })` (functional surface).
+     * NAME NOTE: distinct from the context-window `context` (`ContextSettings`) above — this is
+     * per-run user data for tools, not token-budget config.
+     */
+    runContext?: Record<string, unknown>;
     /** Raw @ProjectContext config; the adapter builds the (async) systemPrompt resolver from it. */
     projectContext?: ProjectContextOptions;
     mcpServers?: McpServersMap;
@@ -171,6 +257,18 @@ interface CompiledAgentOptions {
      * durable SDK conversation storage (`storage: 'filesystem'`) so a same-`sessionId` request resumes.
      */
     checkpoint?: CheckpointOptions;
+    /**
+     * M9 — guardrails: input/output guards applied at the framework boundary (ADR-0040 § D2).
+     * Input guards run on the user message BEFORE the SDK runtime sees it (fail-fast on `block`).
+     * They REUSE the runtime; they never reimplement it. Absent/empty ⇒ no guards.
+     */
+    guardrails?: readonly Guardrail[];
+    /**
+     * M13 — per-request skills resolver (from `defineAgent({ skills: (ctx) => [...] })`). The request
+     * path resolves it against the run-context (`resolveEnabledSkills`) and sets `skills.enabled`
+     * before the SDK runs. Not consumed by the SDK directly (it reads `skills`). Absent ⇒ no resolver.
+     */
+    skillsResolver?: SkillsSelection;
 }
 /**
  * Compile @Agent metadata into SDK-compatible options.
@@ -474,6 +572,12 @@ interface RuntimeOverrides {
     recoverLeakedToolCalls?: boolean;
     /** Per-run cwd → `Agent.create({ local: { cwd } })` → `SystemPromptContext.cwd`. */
     cwd?: string;
+    /**
+     * M7 — per-run run-context override (`?? compiled.runContext`). Injected into every tool
+     * handler's `ctx.context` by `buildSdkTools`. Lets a single request override the agent-level
+     * `defineAgent({ context })` (mirrors `model`/`cwd`).
+     */
+    runContext?: Record<string, unknown>;
     /**
      * Per-run plugins (e.g. permission gate selected by request mode). Accepts EITHER
      * named-plugin discovery settings (`{ enabled: [...] }`) OR an array of code `Plugin`
@@ -626,15 +730,62 @@ interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
     system?: string;
     /** Extended-thinking effort (mirrors `@Agent({ reasoningEffort })`). */
     reasoningEffort?: ReasoningEffort;
-    /** Pre-built tools (SDK-ready `CompiledTool` shape). */
-    tools?: CompiledTool[];
+    /**
+     * Pre-built tools. Accepts the `@theokit/sdk` `CustomTool` that `defineAgentTool`
+     * (theokit/server) and every `@theokit/sdk-tools` factory return (issue #81) — they are
+     * normalized to the internal {@link CompiledTool} shape at compile time.
+     */
+    tools?: readonly CustomTool[];
+    /**
+     * M7 — run-context: an opaque, per-agent object forwarded to every tool handler's
+     * `ctx.context` at run time (injected by the theokit adapter's tool wrapper). Set shared config
+     * (e.g. `{ projectRoot }`) ONCE at the agent level instead of baking it into each tool
+     * factory. Mirrors ai-sdk `experimental_context`, mastra `RuntimeContext`, and
+     * openai-agents-js `RunContext`. Distinct from `@Agent`'s context-window `context`.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * M9 — guardrails: input/output guards applied at the framework boundary (ADR-0040 § D2).
+     * Input guards run on the user message before the SDK runtime; a `block` fails the run fast.
+     * Built-ins live in `@theokit/agents` (`promptInjectionDetector`, `piiDetector`, `costGuard`,
+     * `unicodeNormalizer`, `outputModeration`).
+     */
+    guardrails?: readonly Guardrail[];
+    /**
+     * M14 — HITL approvals keyed by tool name. Each gated tool pauses the run and emits an
+     * `approval_required` event until approved (reuses the same `compiled.hitl` wiring the `@Agent`
+     * + `@HumanInTheLoop` path produces). A key that does not match a declared tool fails fast at
+     * compile time.
+     */
+    approvals?: Record<string, HumanInTheLoopOptions>;
+    /**
+     * M13 — skills selection: a static list (compiled straight to the SDK `skills.enabled`) OR a
+     * per-request resolver `(ctx) => string[]` (carried on `compiled.skillsResolver`, resolved by the
+     * request path against the run-context). Absent ⇒ the SDK enables every discovered skill.
+     */
+    skills?: SkillsSelection;
 }
-/** A branded agent definition — the value {@link defineAgent} returns. */
-type AgentDefinition<TInput extends z.ZodType = z.ZodType> = DefineAgentConfig<TInput> & {
+/**
+ * A branded agent definition — the value {@link defineAgent} returns.
+ *
+ * `TTools` (M8) is a phantom type parameter carrying the tool-name union: the `agent()` builder
+ * threads its accumulated literal tool names here (`.build()` returns `AgentDefinition<TInput,
+ * 'a' | 'b'>`), so the generated client (`.theokit/agents.d.ts`) can expose them via
+ * {@link InferAgentToolNames}. `defineAgent` leaves it `string` (its tools array carries no literal
+ * names). Never present at runtime.
+ */
+type AgentDefinition<TInput extends z.ZodType = z.ZodType, TTools extends string = string> = DefineAgentConfig<TInput> & {
     readonly [AGENT_BRAND]: true;
+    readonly __toolNames?: TTools;
 };
 /** Infer the request type of an agent definition from its `input` Zod schema. */
 type InferAgentInput<T> = T extends AgentDefinition<infer S> ? (S extends z.ZodType ? z.infer<S> : never) : never;
+/**
+ * Infer the tool-name union of an agent definition (M8). Yields the literal union for agents built
+ * with the `agent()` builder (`'read_file' | 'count_lines'`), or `string` for `defineAgent` agents
+ * whose tools array carries no literal names.
+ */
+type InferAgentToolNames<T> = T extends AgentDefinition<z.ZodType, infer N> ? N : never;
 /**
  * Define a zero-config agent. Identity/normalizer (like `defineRoute`) — returns the config
  * branded so the scanner recognizes it. Compilation is deferred to {@link compileAgentDefinition}.
@@ -648,6 +799,106 @@ declare function isAgentDefinition(value: unknown): value is AgentDefinition;
  */
 declare function compileAgentDefinition(def: AgentDefinition): CompiledAgentOptions;
 
+/**
+ * M8 — `agent()`, the fluent agent builder with accumulative **type-state**.
+ *
+ * `agent().context<C>().tool(t).model(id).system(s).build()` accumulates type parameters the way
+ * the most-loved TS DX does (tRPC `t.procedure.input().query()`, Zod, Hono) and resolves to the
+ * **SAME branded `AgentDefinition`** that {@link defineAgent} produces — one runtime, N syntaxes
+ * (ADR-B1). The value is entirely at the type level; `.build()` delegates to `defineAgent`, so
+ * convergence with the `defineAgent` / `@Agent` surfaces is by construction.
+ *
+ * Compile-time guarantees (proven by `tests/type/agent-builder.test-d.ts`):
+ * - `.build()` is a compile error when `.model()` was never called (UnsetMarker technique — tRPC
+ *   `utils.ts:2-4` / `procedureBuilder.ts:362-379`).
+ * - `.tool(t)` is a compile error when the tool declares a required run-context ⊄ the agent's `C`.
+ * - tool names accumulate into a union type parameter (`TTools`).
+ *
+ * PURE metadata (sdk-runtime.md / G2): the builder describes an agent, it NEVER calls an LLM.
+ */
+
+/**
+ * A required-but-unset builder field. Branded (a literal intersected with a unique brand) so no
+ * ordinary value can satisfy it — the terminal-method guards below key off it. tRPC's UnsetMarker.
+ */
+type UnsetMarker = 'theokit.unset' & {
+    readonly __brand: 'theokit.unset';
+};
+/**
+ * Compile-error carriers. When a guarded method's precondition fails, its signature demands an
+ * argument of one of these types, which the caller cannot supply — the labeled tuple element
+ * surfaces the reason in the error. (Idiomatic gate for zero-arg terminal methods.)
+ */
+interface MissingModelError {
+    readonly __theokitError: 'call .model(id) before .build()';
+}
+interface ToolContextError<TRequired> {
+    readonly __theokitError: 'this tool requires a run-context not provided via .context()';
+    readonly required: TRequired;
+}
+/** The agent context before `.context()` is called — satisfies only tools with no requirement. */
+type EmptyContext = Record<never, never>;
+/**
+ * A tool that MAY declare, at the type level, the run-context shape it needs. A plain
+ * {@link CustomTool} (`TRequired = unknown`) is satisfied by any agent context. Build one that
+ * carries a literal name + optional required-context via {@link contextualTool}.
+ */
+interface ContextualTool<TName extends string = string, TRequired = unknown> extends CustomTool {
+    readonly name: TName;
+    /** Phantom — never present at runtime; carries the required run-context type for `.tool()`. */
+    readonly __requiredContext?: TRequired;
+}
+/**
+ * Tag a {@link CustomTool} with a literal name (so `.tool()` can accumulate the tool-name union)
+ * and, optionally, a required run-context type. The `requiredContext` argument is a type-only
+ * witness — pass `undefined as C` or a sample value; it is never read at runtime.
+ */
+declare function contextualTool<TName extends string, TRequired = unknown>(tool: CustomTool & {
+    name: TName;
+}, _requiredContext?: TRequired): ContextualTool<TName, TRequired>;
+/**
+ * The fluent builder. Each method returns a NEW builder type with the relevant type parameter
+ * advanced (immutable chaining). Runtime state is a plain {@link DefineAgentConfig} accumulator.
+ */
+interface AgentBuilder<TInput extends z.ZodType | UnsetMarker = UnsetMarker, TModel extends string | UnsetMarker = UnsetMarker, TContext = EmptyContext, TTools extends string = never> {
+    /** Set the request schema (lifted into the typed client via {@link AgentDefinition}). */
+    input<S extends z.ZodType>(schema: S): AgentBuilder<S, TModel, TContext, TTools>;
+    /**
+     * Set the model id. Required before `.build()`. COMPILE ERROR when called twice — the argument
+     * type collapses to `never` once the model is set (tRPC's set-once technique).
+     */
+    model(id: TModel extends UnsetMarker ? string : never): AgentBuilder<TInput, string, TContext, TTools>;
+    /** Set the static system prompt. */
+    system(prompt: string): AgentBuilder<TInput, TModel, TContext, TTools>;
+    /** Set the extended-thinking effort. */
+    reasoningEffort(effort: ReasoningEffort): AgentBuilder<TInput, TModel, TContext, TTools>;
+    /** Set the run-context (M7) — the object every tool handler receives as `ctx.context`. */
+    context<C extends Record<string, unknown>>(value: C): AgentBuilder<TInput, TModel, C, TTools>;
+    /**
+     * Add a tool. Accumulates its name into `TTools`. COMPILE ERROR when the tool declares a
+     * required run-context (`ContextualTool<_, TRequired>`) that the agent's `TContext` does not
+     * satisfy — set it first with `.context()`.
+     */
+    tool<TName extends string, TRequired>(tool: ContextualTool<TName, TRequired>, ...guard: TContext extends TRequired ? [] : [error: ToolContextError<TRequired>]): AgentBuilder<TInput, TModel, TContext, TTools | TName>;
+    /**
+     * Apply a reusable partial chain (Spring-Boot-style composition). `preset` receives the current
+     * builder and returns an advanced one; its accumulated type-state flows through.
+     */
+    use<TResult>(preset: (builder: AgentBuilder<TInput, TModel, TContext, TTools>) => TResult): TResult;
+    /**
+     * Resolve to the branded {@link AgentDefinition} — the SAME value `defineAgent` returns.
+     * COMPILE ERROR when `.model()` was never called.
+     */
+    build(...guard: TModel extends UnsetMarker ? [error: MissingModelError] : []): AgentDefinition<TInput extends z.ZodType ? TInput : z.ZodType, TTools>;
+    /** Phantom — lets type tests read the accumulated tool-name union. Never present at runtime. */
+    readonly __toolNames?: TTools;
+}
+/**
+ * Start a fluent agent definition. Chain `.model()` (required) + `.context()` / `.system()` /
+ * `.input()` / `.tool()` / `.use()`, then `.build()` to get the branded {@link AgentDefinition}.
+ */
+declare function agent(): AgentBuilder;
+
 /**
  * M4 (theokit-ai-first) — the HITL producer: a `pre_tool_call` plugin that pauses the SDK run
  * for a human-in-the-loop tool approval.
@@ -670,7 +921,7 @@ interface HitlWiring {
     /** Push the approval-required event into the agent stream (the translator emits the chunk). */
     emit: (event: ApprovalRequiredEvent) => void;
     /** Await the human decision for `approvalId`; resolves true=approve, false=deny (or timeout). */
-    awaitApproval: (approvalId: string, opts: HumanInTheLoopOptions) => Promise<boolean>;
+    awaitApproval: (approvalId: string, opts: HumanInTheLoopOptions, toolName: string) => Promise<boolean>;
 }
 
 /**
@@ -917,6 +1168,34 @@ declare const ladderReflectionStrategy: ReflectionStrategy;
  */
 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).
+ *
+ * referencia: 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.
  *
@@ -963,6 +1242,27 @@ interface DelegateOptions {
     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.
@@ -978,6 +1278,75 @@ interface DelegateOptions {
  */
 declare function delegate(SubAgentClass: Function, message: string, opts?: DelegateOptions): Promise<DelegationResult>;
 
+/**
+ * M10 (theokit-ai-first) — createToolHooksPlugin: `beforeToolCall` / `afterToolCall` observability.
+ *
+ * ADR-0040 § D2: a HOME/BOUNDARY plugin over the SDK's OWN `pre_tool_call` / `post_tool_call`
+ * hooks (mirrors {@link createHitlPlugin}). It calls no LLM, dispatches no tool, runs no second
+ * loop — the SDK owns the run. `beforeToolCall` may VETO a call; `afterToolCall` observes the
+ * result. The processor pipeline's remaining lifecycle hooks (LLM request/response) live in the
+ * SDK; this ships the two tool-boundary hooks the framework can wire today.
+ */
+/** A tool call about to run (mirrored from the SDK `pre_tool_call` context — type-only). */
+interface BeforeToolCallContext {
+    name: string;
+    args: Record<string, unknown>;
+}
+/** A veto returned from `beforeToolCall` — blocks the tool; the SDK surfaces `message` to the model. */
+interface ToolCallVeto {
+    block: true;
+    message: string;
+}
+/** A completed tool call (mirrored from the SDK `post_tool_call` context — type-only). */
+interface AfterToolCallContext {
+    name: string;
+    result: unknown;
+}
+interface ToolHooks {
+    /** Observe (and optionally VETO) every tool call before it runs. Return a veto or nothing. */
+    beforeToolCall?: (ctx: BeforeToolCallContext) => ToolCallVeto | undefined | Promise<ToolCallVeto | undefined>;
+    /** Observe every tool call's result after it runs. */
+    afterToolCall?: (ctx: AfterToolCallContext) => void | Promise<void>;
+    /**
+     * M10 — observe every LLM turn BEFORE it runs (SDK `pre_llm_call`). Observability only — the
+     * SDK's LLM-call context carries `{ agentId, runId, iteration }`, not the mutable request body.
+     */
+    beforeLLMCall?: (ctx: LLMCallContext) => void | Promise<void>;
+    /** M10 — observe every LLM turn AFTER it completes (SDK `post_llm_call`). Observability only. */
+    afterLLMCall?: (ctx: LLMCallContext) => void | Promise<void>;
+}
+/** Context of an LLM turn (mirrors the SDK `LlmCallContext` for `pre_llm_call`/`post_llm_call`). */
+interface LLMCallContext {
+    agentId: string;
+    runId: string;
+    /** 0-based iteration index of the current turn, when available. */
+    iteration?: number;
+}
+/**
+ * Minimal SDK hook context (type-only — no runtime import, keeps the SDK peer optional). Tool hooks
+ * carry `name`/`args`/`result`; LLM hooks carry `iteration`. All optional so one shape covers both.
+ */
+interface ToolHookRawContext {
+    agentId: string;
+    runId: string;
+    name?: string;
+    args?: Record<string, unknown>;
+    result?: unknown;
+    iteration?: number;
+}
+interface ToolHooksPluginContext {
+    on(hook: string, handler: (ctx: ToolHookRawContext) => unknown): void;
+}
+interface ToolHooksPlugin {
+    name: string;
+    register(ctx: ToolHooksPluginContext): void;
+}
+/**
+ * Build the tool-hooks plugin. Registers ONLY the hooks provided (inert when none) so it adds no
+ * overhead unless used. The returned object is a structural `@theokit/sdk` `Plugin`.
+ */
+declare function createToolHooksPlugin(hooks: ToolHooks): ToolHooksPlugin;
+
 /**
  * Agent manifest generator — build-time JSON describing all agents, tools, guards, policies.
  *
@@ -1061,4 +1430,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-export { buildModelSelection as $, AGENT_BRAND as A, BudgetExceededError as B, type CompiledAgentOptions as C, type DelegationResult as D, type ErrorEvent as E, type FileEditEvent as F, type LoopOutcome as G, type LoopStrategyConfig as H, type InferAgentInput as I, type ReflectionContext as J, type ReflectionResult as K, type LoopStrategy as L, type ReflectionStrategyConfig as M, type RunStartedEvent as N, type SdkMessage as O, type PartialToolCallEvent as P, type Segment as Q, type ReflectionStrategy as R, type StreamEvent as S, type StateUpdateEvent as T, type TextDeltaEvent as U, type ThinkingEvent as V, type ToolCallEvent as W, type ToolResultEvent as X, type ToolWalkResult as Y, type ToolboxWalkResult as Z, agentsPlugin as _, type CompiledTool as a, compileAgent as a0, compileAgentDefinition as a1, compileAgentModule as a2, compileContextWindow as a3, compileProjectContext as a4, compileSkills as a5, compileTools as a6, createAgentExecutionContext as a7, createSdkAgentStream as a8, createThinkTagExtractor as a9, defineAgent as aa, delegate as ab, extractThinkTagStream as ac, generateAgentManifest as ad, generateAgentRoutes as ae, isAgentContext as af, isAgentDefinition as ag, isApprovalRequired as ah, isDone as ai, isError as aj, isPartialToolCall as ak, isTextDelta as al, isToolCall as am, isToolResult as an, ladderReflectionStrategy as ao, loopStrategyConfigSchema as ap, noopReflectionStrategy as aq, projectContextMetadataOnlyKnobs as ar, reflectionStrategyConfigSchema as as, resolveLoopStrategy as at, streamAgentResponse as au, streamAgentUIMessages as av, translateSdkEvent as aw, translateToUIMessageStream as ax, validateUniqueRoutes as ay, walkAgentMetadata as az, type AgentDefinition as b, AgentDefinitionError as c, type AgentExecutionContext as d, type AgentManifest as e, type AgentManifestEntry as f, type AgentManifestTool as g, type AgentRoute as h, type AgentRouteContext as i, type AgentRunInfo as j, type AgentStreamEvent as k, type AgentWalkResult as l, AgentWarningCode as m, type AgentsPluginOptions as n, type ApprovalRequiredEvent as o, type ArtifactChunkEvent as p, type ArtifactStartEvent as q, type CheckpointSavedEvent as r, type CompiledContextWindow as s, DEFAULT_MAX_ITERATIONS as t, type DefineAgentConfig as u, type DelegateOptions as v, DelegationError as w, type DoneEvent as x, type IterationEvent as y, type LoopFinishReason as z };
+export { type ReflectionResult as $, type AgentManifestEntry as A, type BeforeToolCallContext as B, type CompiledAgentOptions as C, type DelegationResult as D, type DefineAgentConfig as E, type DelegateOptions as F, type Guardrail as G, DelegationError as H, type DoneEvent as I, type ErrorEvent as J, type FileEditEvent as K, type LoopStrategy as L, type GuardrailAction as M, type GuardrailPhase as N, type GuardrailResult as O, GuardrailViolationError as P, type InferAgentInput as Q, type ReflectionStrategy as R, type StreamEvent as S, type InferAgentToolNames as T, type IterationEvent as U, type LLMCallContext as V, type LoopFinishReason as W, type LoopOutcome as X, type LoopStrategyConfig as Y, type PartialToolCallEvent as Z, type ReflectionContext as _, type CompiledTool as a, type ReflectionStrategyConfig as a0, type RunStartedEvent as a1, type SdkMessage as a2, type Segment as a3, type SkillsRequestContext as a4, type SkillsSelection as a5, type StateUpdateEvent as a6, type TextDeltaEvent as a7, type ThinkingEvent as a8, type ToolCallEvent as a9, isAgentContext as aA, isAgentDefinition as aB, isApprovalRequired as aC, isDone as aD, isError as aE, isPartialToolCall as aF, isTextDelta as aG, isToolCall as aH, isToolResult as aI, ladderReflectionStrategy as aJ, loopStrategyConfigSchema as aK, noopReflectionStrategy as aL, projectContextMetadataOnlyKnobs as aM, reflectionStrategyConfigSchema as aN, resolveEnabledSkills as aO, resolveLoopStrategy as aP, streamAgentResponse as aQ, streamAgentUIMessages as aR, translateSdkEvent as aS, translateToUIMessageStream as aT, validateUniqueRoutes as aU, walkAgentMetadata as aV, type ToolCallVeto as aa, type ToolHooks as ab, type ToolHooksPlugin as ac, type ToolResultEvent as ad, type ToolWalkResult as ae, type ToolboxWalkResult as af, agent as ag, agentsPlugin as ah, buildModelSelection as ai, compileAgent as aj, compileAgentDefinition as ak, compileAgentModule as al, compileContextWindow as am, compileProjectContext as an, compileSkills as ao, compileTools as ap, contextualTool as aq, createAgentExecutionContext as ar, createSdkAgentStream as as, createThinkTagExtractor as at, createToolHooksPlugin as au, defineAgent as av, delegate as aw, extractThinkTagStream as ax, generateAgentManifest as ay, generateAgentRoutes as az, type RoundStreamFactory as b, AGENT_BRAND as c, type AfterToolCallContext as d, type AgentBuilder as e, type AgentDefinition as f, AgentDefinitionError as g, type AgentExecutionContext as h, type AgentManifest as i, type AgentManifestTool as j, type AgentRoute as k, type AgentRouteContext as l, type AgentRunInfo as m, type AgentStreamEvent as n, type AgentWalkResult as o, AgentWarningCode as p, type AgentsPluginOptions as q, type ApprovalRequiredEvent as r, type ArtifactChunkEvent as s, type ArtifactStartEvent as t, BudgetExceededError as u, type CheckpointSavedEvent as v, type CompiledContextWindow as w, type ContextualTool as x, CostBudgetExceededError as y, DEFAULT_MAX_ITERATIONS as z };

package/dist/bridge.d.ts

@@ -1,4 +1,4 @@
-export { A as AGENT_BRAND, b as AgentDefinition, c as AgentDefinitionError, d as AgentExecutionContext, e as AgentManifest, f as AgentManifestEntry, g as AgentManifestTool, h as AgentRoute, i as AgentRouteContext, j as AgentRunInfo, k as AgentStreamEvent, l as AgentWalkResult, m as AgentWarningCode, n as AgentsPluginOptions, o as ApprovalRequiredEvent, p as ArtifactChunkEvent, q as ArtifactStartEvent, B as BudgetExceededError, r as CheckpointSavedEvent, C as CompiledAgentOptions, s as CompiledContextWindow, a as CompiledTool, u as DefineAgentConfig, v as DelegateOptions, w as DelegationError, D as DelegationResult, x as DoneEvent, E as ErrorEvent, F as FileEditEvent, I as InferAgentInput, y as IterationEvent, P as PartialToolCallEvent, N as RunStartedEvent, O as SdkMessage, Q as Segment, T as StateUpdateEvent, S as StreamEvent, U as TextDeltaEvent, V as ThinkingEvent, W as ToolCallEvent, X as ToolResultEvent, Y as ToolWalkResult, Z as ToolboxWalkResult, _ as agentsPlugin, $ as buildModelSelection, a0 as compileAgent, a1 as compileAgentDefinition, a2 as compileAgentModule, a3 as compileContextWindow, a4 as compileProjectContext, a5 as compileSkills, a6 as compileTools, a7 as createAgentExecutionContext, a8 as createSdkAgentStream, a9 as createThinkTagExtractor, aa as defineAgent, ab as delegate, ac as extractThinkTagStream, ad as generateAgentManifest, ae as generateAgentRoutes, af as isAgentContext, ag as isAgentDefinition, ah as isApprovalRequired, ai as isDone, aj as isError, ak as isPartialToolCall, al as isTextDelta, am as isToolCall, an as isToolResult, ar as projectContextMetadataOnlyKnobs, au as streamAgentResponse, av as streamAgentUIMessages, aw as translateSdkEvent, ax as translateToUIMessageStream, ay as validateUniqueRoutes, az as walkAgentMetadata } from './bridge-entry-DVhOQc_f.js';
+export { c as AGENT_BRAND, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinition, g as AgentDefinitionError, h as AgentExecutionContext, i as AgentManifest, A as AgentManifestEntry, j as AgentManifestTool, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentStreamEvent, o as AgentWalkResult, p as AgentWarningCode, q as AgentsPluginOptions, r as ApprovalRequiredEvent, s as ArtifactChunkEvent, t as ArtifactStartEvent, B as BeforeToolCallContext, u as BudgetExceededError, v as CheckpointSavedEvent, C as CompiledAgentOptions, w as CompiledContextWindow, a as CompiledTool, x as ContextualTool, E as DefineAgentConfig, F as DelegateOptions, H as DelegationError, D as DelegationResult, I as DoneEvent, J as ErrorEvent, K as FileEditEvent, Q as InferAgentInput, T as InferAgentToolNames, U as IterationEvent, V as LLMCallContext, Z as PartialToolCallEvent, a1 as RunStartedEvent, a2 as SdkMessage, a3 as Segment, a6 as StateUpdateEvent, S as StreamEvent, a7 as TextDeltaEvent, a8 as ThinkingEvent, a9 as ToolCallEvent, aa as ToolCallVeto, ab as ToolHooks, ac as ToolHooksPlugin, ad as ToolResultEvent, ae as ToolWalkResult, af as ToolboxWalkResult, ag as agent, ah as agentsPlugin, ai as buildModelSelection, aj as compileAgent, ak as compileAgentDefinition, al as compileAgentModule, am as compileContextWindow, an as compileProjectContext, ao as compileSkills, ap as compileTools, aq as contextualTool, ar as createAgentExecutionContext, as as createSdkAgentStream, at as createThinkTagExtractor, au as createToolHooksPlugin, av as defineAgent, aw as delegate, ax as extractThinkTagStream, ay as generateAgentManifest, az as generateAgentRoutes, aA as isAgentContext, aB as isAgentDefinition, aC as isApprovalRequired, aD as isDone, aE as isError, aF as isPartialToolCall, aG as isTextDelta, aH as isToolCall, aI as isToolResult, aM as projectContextMetadataOnlyKnobs, aQ as streamAgentResponse, aR as streamAgentUIMessages, aS as translateSdkEvent, aT as translateToUIMessageStream, aU as validateUniqueRoutes, aV as walkAgentMetadata } from './bridge-entry-DtDotZGW.js';
 import '@theokit/http';
 import './skills-Dx_KJ6Eg.js';
 import '@theokit/sdk';

package/dist/bridge.js

@@ -4,6 +4,7 @@ import {
   AgentWarningCode,
   BudgetExceededError,
   DelegationError,
+  agent,
   agentsPlugin,
   buildModelSelection,
   compileAgent,
@@ -13,9 +14,11 @@ import {
   compileProjectContext,
   compileSkills,
   compileTools,
+  contextualTool,
   createAgentExecutionContext,
   createSdkAgentStream,
   createThinkTagExtractor,
+  createToolHooksPlugin,
   defineAgent,
   delegate,
   extractThinkTagStream,
@@ -37,7 +40,7 @@ import {
   translateToUIMessageStream,
   validateUniqueRoutes,
   walkAgentMetadata
-} from "./chunk-XCQNYAVU.js";
+} from "./chunk-BWYBOMKR.js";
 import "./chunk-FI6ZG2YP.js";
 import "./chunk-7QVYU63E.js";
 export {
@@ -46,6 +49,7 @@ export {
   AgentWarningCode,
   BudgetExceededError,
   DelegationError,
+  agent,
   agentsPlugin,
   buildModelSelection,
   compileAgent,
@@ -55,9 +59,11 @@ export {
   compileProjectContext,
   compileSkills,
   compileTools,
+  contextualTool,
   createAgentExecutionContext,
   createSdkAgentStream,
   createThinkTagExtractor,
+  createToolHooksPlugin,
   defineAgent,
   delegate,
   extractThinkTagStream,