@theokit/sdk 2.25.0 → 2.26.0

package/dist/internal/runtime/processors/run-processors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * SE24 — the guardrail processor runner. Runs an ordered processor pipeline over
+ * a string payload (the user message for input, the model's text for output).
+ * Each processor may rewrite the payload (return a string), `abort()` (→ a
+ * tripwire that short-circuits the rest), or `warn()` (fire `onViolation`,
+ * continue). A processor's own bug (a non-abort throw) propagates (fail-fast).
+ *
+ * @internal
+ */
+export {};

package/dist/internal/runtime/processors/tripwire-run.d.ts

@@ -0,0 +1,16 @@
+/**
+ * SE24 — a terminal {@link Run} born from an input-processor `abort()`. It never
+ * reached the model: `wait()` resolves to a `cancelled` {@link RunResult}
+ * carrying the tripwire; `stream()` yields no content messages. The `tripwire`
+ * run-event is emitted by the caller via `SendOptions.onRunEvent` before this
+ * run is returned.
+ *
+ * @internal
+ */
+import type { ProcessorTripwire } from "../../../types/processors.js";
+import type { Run } from "../../../types/run.js";
+export declare function createTripwireRun(args: {
+    agentId: string;
+    tripwire: ProcessorTripwire;
+    model: ModelSelection | undefined;
+}): Run;

package/dist/internal/runtime/processors/wrap-output-run.d.ts

@@ -0,0 +1,18 @@
+/**
+ * SE24 — wrap a {@link Run} so its `wait()` result passes through the output
+ * processors before reaching the caller. A processor may redact/rewrite the
+ * final text or `abort()` → the result becomes `cancelled` with a tripwire (and
+ * a `tripwire` run-event is emitted). Streaming output redaction is deferred
+ * (v1 processes the buffered `wait()` path only); a Proxy preserves every other
+ * Run member (`stream`, `cancel`, `conversation`, …).
+ *
+ * @internal
+ */
+import type { Run } from "../../../types/run.js";
+import { type RunEventSink } from "../../../types/run-events.js";
+export declare function wrapRunWithOutputProcessors(args: {
+    run: Run;
+    processors: readonly Processor[];
+    agentId: string;
+    onRunEvent: RunEventSink | undefined;
+}): Run;

package/dist/{run-Cr0C6cOM.d.cts → run-CdWiihyU.d.cts}

@@ -87,7 +87,17 @@ interface ToolResultGuardOptions {
  *
  * @public
  */
-type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent;
+type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunTripwireEvent;
+/**
+ * SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.
+ * Delivered via {@link SendOptions.onRunEvent} (mirrors the `RunResult.tripwire`
+ * surfaced on `wait()`).
+ */
+interface RunTripwireEvent {
+    readonly type: "tripwire";
+    readonly reason: string;
+    readonly processorId: string;
+}
 /** A tool call is being dispatched (before its result). */
 interface RunToolProgressEvent {
     readonly type: "tool_progress";
@@ -154,6 +164,91 @@ type RunEventSink = (event: RunEvent) => void;
  */
 declare function emitRunEvent(sink: RunEventSink | undefined, event: RunEvent): void;
 
+/**
+ * SE24 — guardrail processor pipeline. A `Processor` inspects/transforms/blocks
+ * the user message (input) or the model's final text (output). Processors run in
+ * order; each may rewrite its payload, `abort(reason)` to stop the run (surfaced
+ * as {@link RunResult.tripwire} + a `tripwire` run-event), or `warn()` to report
+ * a non-blocking violation. The pipeline is provider-agnostic and carries NO LLM
+ * — an LLM-classifier processor is the consumer's (delegated, see the guardrails
+ * ADR). Mirrors Mastra's `inputProcessors` / `outputProcessors`.
+ *
+ * @public
+ */
+/**
+ * A policy violation surfaced to a processor's {@link Processor.onViolation}
+ * callback — on `abort()` (blocking) AND on `warn()` (non-blocking).
+ *
+ * @public
+ */
+interface ProcessorViolation {
+    processorId: string;
+    message: string;
+    detail?: unknown;
+}
+/**
+ * Controls available to a processor while it runs: `abort()` stops the run with
+ * a tripwire; `warn()` reports a non-blocking violation and continues.
+ *
+ * @public
+ */
+interface ProcessorControls {
+    /** Stop the run immediately with a tripwire. Throws — code after it never runs. */
+    abort(reason: string): never;
+    /** Report a non-blocking violation (fires `onViolation`); the run continues. */
+    warn(message: string, detail?: unknown): void;
+}
+/** Context passed to {@link Processor.processInput}. @public */
+interface InputProcessorContext extends ProcessorControls {
+    /** The user message text for this send. */
+    message: string;
+    agentId: string;
+}
+/** Context passed to {@link Processor.processOutput}. @public */
+interface OutputProcessorContext extends ProcessorControls {
+    /** The model's final assistant text for this run. */
+    text: string;
+    agentId: string;
+}
+/**
+ * A guardrail processor. Provide `processInput` (runs before the LLM) and/or
+ * `processOutput` (runs on the final text). A processor's `strategy` (block /
+ * rewrite / redact / warn) is expressed via the {@link ProcessorControls}:
+ * return the transformed payload to rewrite/redact, `abort()` to block, `warn()`
+ * to report without blocking. The core ships no strategy enum — strategies are a
+ * processor-level convention over these primitives.
+ *
+ * @public
+ */
+interface Processor {
+    /** Stable id — surfaced on {@link ProcessorViolation} and {@link RunResult.tripwire}. */
+    id: string;
+    /**
+     * Transform or block the user message before it reaches the model. Return the
+     * (possibly rewritten) text; returning nothing (void) preserves the message
+     * unchanged. May be `async`.
+     */
+    processInput?(ctx: InputProcessorContext): string | Promise<string> | void;
+    /**
+     * Transform or block the model's final text before it reaches the caller.
+     * Return the (possibly redacted) text; returning nothing (void) preserves the
+     * text unchanged. May be `async`.
+     */
+    processOutput?(ctx: OutputProcessorContext): string | Promise<string> | void;
+    /** Fires on `abort()` and `warn()`. Errors thrown here are swallowed (never break the pipeline). */
+    onViolation?(violation: ProcessorViolation): void;
+}
+/**
+ * The tripwire detail attached to {@link RunResult.tripwire} when a processor
+ * aborts, and carried by the `tripwire` run-event.
+ *
+ * @public
+ */
+interface ProcessorTripwire {
+    reason: string;
+    processorId: string;
+}
+
 /**
  * Type-leaf — primitives shared between `agent.ts`, `run.ts`, and
  * `messages.ts`. Extracted to break LOW type-only cycles #5 and #7
@@ -886,6 +981,18 @@ interface RunResult {
     id: string;
     status: "finished" | "error" | "cancelled";
     result?: string;
+    /**
+     * SE24 — set when a guardrail processor called `abort()`. The run stops
+     * (`status: "cancelled"`) and `tripwire` carries the blocking reason +
+     * processor id. `undefined` on every non-guardrail outcome. A
+     * `throwOnError: true` agent resolves normally on a tripwire (status is
+     * `"cancelled"`, not `"error"`). On an OUTPUT block the model already ran, so
+     * `usage`/`cost` survive (billing) while `result` is suppressed; an INPUT
+     * block never reaches the model, so `usage` is absent.
+     *
+     * @public
+     */
+    tripwire?: ProcessorTripwire;
     model?: ModelSelection;
     durationMs?: number;
     git?: RunGitInfo;
@@ -1290,4 +1397,4 @@ interface GenerateRunResult<O> {
     };
 }
 
-export { type SendOptions as $, type AgentConversationTurn as A, type RunTaskStartedEvent as B, type CustomTool as C, type DoomLoopThresholds as D, type RunTaskUpdatedEvent as E, type RunToCompletionOptions as F, type GenerateOptions as G, type RunToCompletionResult as H, type ImageBlock as I, type RunToolProgressEvent as J, type SDKAssistantMessage as K, type SDKImage as L, type ModelSelection as M, type SDKImageDimension as N, type SDKObjectDelta as O, type PartialToolCallUpdate as P, type SDKRequestMessage as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type SDKStatusMessage as U, type SDKSystemMessage as V, type SDKTaskMessage as W, type SDKThinkingMessage as X, type SDKToolUseMessage as Y, type SDKUserMessage as Z, type SDKUserMessageEvent as _, type McpServerConfig as a, type ShellCommand as a0, type ShellConversationTurn as a1, type ShellOutput as a2, type ShellOutputDeltaUpdate as a3, type StepCompletedUpdate as a4, type StepStartedUpdate as a5, type StreamToCompletionResult as a6, type SummaryCompletedUpdate as a7, type SummaryStartedUpdate as a8, type SummaryUpdate as a9, type TextBlock as aa, type TextDeltaUpdate as ab, type ThinkingCompletedUpdate as ac, type ThinkingDeltaUpdate as ad, type ThinkingMessage as ae, type TokenDeltaUpdate as af, type TokenUsage as ag, type ToolCall as ah, type ToolCallCompletedUpdate as ai, type ToolCallStartedUpdate as aj, type ToolContextMessage as ak, type ToolResult as al, type ToolResultGuardOptions as am, type ToolUseBlock as an, type TurnEndedUpdate as ao, type UserMessage as ap, type UserMessageAppendedUpdate as aq, emitRunEvent as ar, type Run as b, type MessageOrigin as c, type AssistantMessage as d, type ConversationStep as e, type ConversationTurn as f, type CostBreakdown as g, type CostSource as h, type CostStatus as i, type GenerateRunResult as j, type InteractionUpdate as k, type McpAuthConfig as l, type McpHttpServerConfig as m, type McpOAuthConfig as n, type McpStdioServerConfig as o, type ModelParameterValue as p, type RunCompactBoundaryEvent as q, type RunErrorDetail as r, type RunEvent as s, type RunEventSink as t, type RunGitInfo as u, type RunOperation as v, type RunPermissionDeniedEvent as w, type RunRateLimitEvent as x, type RunStatus as y, type RunTaskCompletedEvent as z };
+export { type SDKStatusMessage as $, type AgentConversationTurn as A, type RunOperation as B, type CustomTool as C, type DoomLoopThresholds as D, type RunPermissionDeniedEvent as E, type RunRateLimitEvent as F, type GenerateOptions as G, type RunStatus as H, type ImageBlock as I, type RunTaskCompletedEvent as J, type RunTaskStartedEvent as K, type RunTaskUpdatedEvent as L, type ModelSelection as M, type RunToCompletionOptions as N, type OutputProcessorContext as O, type Processor as P, type RunToCompletionResult as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type RunToolProgressEvent as U, type RunTripwireEvent as V, type SDKAssistantMessage as W, type SDKImage as X, type SDKImageDimension as Y, type SDKObjectDelta as Z, type SDKRequestMessage as _, type McpServerConfig as a, type SDKSystemMessage as a0, type SDKTaskMessage as a1, type SDKThinkingMessage as a2, type SDKToolUseMessage as a3, type SDKUserMessage as a4, type SDKUserMessageEvent as a5, type SendOptions as a6, type ShellCommand as a7, type ShellConversationTurn as a8, type ShellOutput as a9, type ShellOutputDeltaUpdate as aa, type StepCompletedUpdate as ab, type StepStartedUpdate as ac, type StreamToCompletionResult as ad, type SummaryCompletedUpdate as ae, type SummaryStartedUpdate as af, type SummaryUpdate as ag, type TextBlock as ah, type TextDeltaUpdate as ai, type ThinkingCompletedUpdate as aj, type ThinkingDeltaUpdate as ak, type ThinkingMessage as al, type TokenDeltaUpdate as am, type TokenUsage as an, type ToolCall as ao, type ToolCallCompletedUpdate as ap, type ToolCallStartedUpdate as aq, type ToolContextMessage as ar, type ToolResult as as, type ToolResultGuardOptions as at, type ToolUseBlock as au, type TurnEndedUpdate as av, type UserMessage as aw, type UserMessageAppendedUpdate as ax, emitRunEvent as ay, type Run as b, type MessageOrigin as c, type AssistantMessage as d, type ConversationStep as e, type ConversationTurn as f, type CostBreakdown as g, type CostSource as h, type CostStatus as i, type GenerateRunResult as j, type InputProcessorContext as k, type InteractionUpdate as l, type McpAuthConfig as m, type McpHttpServerConfig as n, type McpOAuthConfig as o, type McpStdioServerConfig as p, type ModelParameterValue as q, type PartialToolCallUpdate as r, type ProcessorControls as s, type ProcessorTripwire as t, type ProcessorViolation as u, type RunCompactBoundaryEvent as v, type RunErrorDetail as w, type RunEvent as x, type RunEventSink as y, type RunGitInfo as z };

package/dist/{run-Cr0C6cOM.d.ts → run-CdWiihyU.d.ts}

@@ -87,7 +87,17 @@ interface ToolResultGuardOptions {
  *
  * @public
  */
-type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent;
+type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunTripwireEvent;
+/**
+ * SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.
+ * Delivered via {@link SendOptions.onRunEvent} (mirrors the `RunResult.tripwire`
+ * surfaced on `wait()`).
+ */
+interface RunTripwireEvent {
+    readonly type: "tripwire";
+    readonly reason: string;
+    readonly processorId: string;
+}
 /** A tool call is being dispatched (before its result). */
 interface RunToolProgressEvent {
     readonly type: "tool_progress";
@@ -154,6 +164,91 @@ type RunEventSink = (event: RunEvent) => void;
  */
 declare function emitRunEvent(sink: RunEventSink | undefined, event: RunEvent): void;
 
+/**
+ * SE24 — guardrail processor pipeline. A `Processor` inspects/transforms/blocks
+ * the user message (input) or the model's final text (output). Processors run in
+ * order; each may rewrite its payload, `abort(reason)` to stop the run (surfaced
+ * as {@link RunResult.tripwire} + a `tripwire` run-event), or `warn()` to report
+ * a non-blocking violation. The pipeline is provider-agnostic and carries NO LLM
+ * — an LLM-classifier processor is the consumer's (delegated, see the guardrails
+ * ADR). Mirrors Mastra's `inputProcessors` / `outputProcessors`.
+ *
+ * @public
+ */
+/**
+ * A policy violation surfaced to a processor's {@link Processor.onViolation}
+ * callback — on `abort()` (blocking) AND on `warn()` (non-blocking).
+ *
+ * @public
+ */
+interface ProcessorViolation {
+    processorId: string;
+    message: string;
+    detail?: unknown;
+}
+/**
+ * Controls available to a processor while it runs: `abort()` stops the run with
+ * a tripwire; `warn()` reports a non-blocking violation and continues.
+ *
+ * @public
+ */
+interface ProcessorControls {
+    /** Stop the run immediately with a tripwire. Throws — code after it never runs. */
+    abort(reason: string): never;
+    /** Report a non-blocking violation (fires `onViolation`); the run continues. */
+    warn(message: string, detail?: unknown): void;
+}
+/** Context passed to {@link Processor.processInput}. @public */
+interface InputProcessorContext extends ProcessorControls {
+    /** The user message text for this send. */
+    message: string;
+    agentId: string;
+}
+/** Context passed to {@link Processor.processOutput}. @public */
+interface OutputProcessorContext extends ProcessorControls {
+    /** The model's final assistant text for this run. */
+    text: string;
+    agentId: string;
+}
+/**
+ * A guardrail processor. Provide `processInput` (runs before the LLM) and/or
+ * `processOutput` (runs on the final text). A processor's `strategy` (block /
+ * rewrite / redact / warn) is expressed via the {@link ProcessorControls}:
+ * return the transformed payload to rewrite/redact, `abort()` to block, `warn()`
+ * to report without blocking. The core ships no strategy enum — strategies are a
+ * processor-level convention over these primitives.
+ *
+ * @public
+ */
+interface Processor {
+    /** Stable id — surfaced on {@link ProcessorViolation} and {@link RunResult.tripwire}. */
+    id: string;
+    /**
+     * Transform or block the user message before it reaches the model. Return the
+     * (possibly rewritten) text; returning nothing (void) preserves the message
+     * unchanged. May be `async`.
+     */
+    processInput?(ctx: InputProcessorContext): string | Promise<string> | void;
+    /**
+     * Transform or block the model's final text before it reaches the caller.
+     * Return the (possibly redacted) text; returning nothing (void) preserves the
+     * text unchanged. May be `async`.
+     */
+    processOutput?(ctx: OutputProcessorContext): string | Promise<string> | void;
+    /** Fires on `abort()` and `warn()`. Errors thrown here are swallowed (never break the pipeline). */
+    onViolation?(violation: ProcessorViolation): void;
+}
+/**
+ * The tripwire detail attached to {@link RunResult.tripwire} when a processor
+ * aborts, and carried by the `tripwire` run-event.
+ *
+ * @public
+ */
+interface ProcessorTripwire {
+    reason: string;
+    processorId: string;
+}
+
 /**
  * Type-leaf — primitives shared between `agent.ts`, `run.ts`, and
  * `messages.ts`. Extracted to break LOW type-only cycles #5 and #7
@@ -886,6 +981,18 @@ interface RunResult {
     id: string;
     status: "finished" | "error" | "cancelled";
     result?: string;
+    /**
+     * SE24 — set when a guardrail processor called `abort()`. The run stops
+     * (`status: "cancelled"`) and `tripwire` carries the blocking reason +
+     * processor id. `undefined` on every non-guardrail outcome. A
+     * `throwOnError: true` agent resolves normally on a tripwire (status is
+     * `"cancelled"`, not `"error"`). On an OUTPUT block the model already ran, so
+     * `usage`/`cost` survive (billing) while `result` is suppressed; an INPUT
+     * block never reaches the model, so `usage` is absent.
+     *
+     * @public
+     */
+    tripwire?: ProcessorTripwire;
     model?: ModelSelection;
     durationMs?: number;
     git?: RunGitInfo;
@@ -1290,4 +1397,4 @@ interface GenerateRunResult<O> {
     };
 }
 
-export { type SendOptions as $, type AgentConversationTurn as A, type RunTaskStartedEvent as B, type CustomTool as C, type DoomLoopThresholds as D, type RunTaskUpdatedEvent as E, type RunToCompletionOptions as F, type GenerateOptions as G, type RunToCompletionResult as H, type ImageBlock as I, type RunToolProgressEvent as J, type SDKAssistantMessage as K, type SDKImage as L, type ModelSelection as M, type SDKImageDimension as N, type SDKObjectDelta as O, type PartialToolCallUpdate as P, type SDKRequestMessage as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type SDKStatusMessage as U, type SDKSystemMessage as V, type SDKTaskMessage as W, type SDKThinkingMessage as X, type SDKToolUseMessage as Y, type SDKUserMessage as Z, type SDKUserMessageEvent as _, type McpServerConfig as a, type ShellCommand as a0, type ShellConversationTurn as a1, type ShellOutput as a2, type ShellOutputDeltaUpdate as a3, type StepCompletedUpdate as a4, type StepStartedUpdate as a5, type StreamToCompletionResult as a6, type SummaryCompletedUpdate as a7, type SummaryStartedUpdate as a8, type SummaryUpdate as a9, type TextBlock as aa, type TextDeltaUpdate as ab, type ThinkingCompletedUpdate as ac, type ThinkingDeltaUpdate as ad, type ThinkingMessage as ae, type TokenDeltaUpdate as af, type TokenUsage as ag, type ToolCall as ah, type ToolCallCompletedUpdate as ai, type ToolCallStartedUpdate as aj, type ToolContextMessage as ak, type ToolResult as al, type ToolResultGuardOptions as am, type ToolUseBlock as an, type TurnEndedUpdate as ao, type UserMessage as ap, type UserMessageAppendedUpdate as aq, emitRunEvent as ar, type Run as b, type MessageOrigin as c, type AssistantMessage as d, type ConversationStep as e, type ConversationTurn as f, type CostBreakdown as g, type CostSource as h, type CostStatus as i, type GenerateRunResult as j, type InteractionUpdate as k, type McpAuthConfig as l, type McpHttpServerConfig as m, type McpOAuthConfig as n, type McpStdioServerConfig as o, type ModelParameterValue as p, type RunCompactBoundaryEvent as q, type RunErrorDetail as r, type RunEvent as s, type RunEventSink as t, type RunGitInfo as u, type RunOperation as v, type RunPermissionDeniedEvent as w, type RunRateLimitEvent as x, type RunStatus as y, type RunTaskCompletedEvent as z };
+export { type SDKStatusMessage as $, type AgentConversationTurn as A, type RunOperation as B, type CustomTool as C, type DoomLoopThresholds as D, type RunPermissionDeniedEvent as E, type RunRateLimitEvent as F, type GenerateOptions as G, type RunStatus as H, type ImageBlock as I, type RunTaskCompletedEvent as J, type RunTaskStartedEvent as K, type RunTaskUpdatedEvent as L, type ModelSelection as M, type RunToCompletionOptions as N, type OutputProcessorContext as O, type Processor as P, type RunToCompletionResult as Q, type RunResult as R, type SDKMessage as S, type ToolResultContentBlock as T, type RunToolProgressEvent as U, type RunTripwireEvent as V, type SDKAssistantMessage as W, type SDKImage as X, type SDKImageDimension as Y, type SDKObjectDelta as Z, type SDKRequestMessage as _, type McpServerConfig as a, type SDKSystemMessage as a0, type SDKTaskMessage as a1, type SDKThinkingMessage as a2, type SDKToolUseMessage as a3, type SDKUserMessage as a4, type SDKUserMessageEvent as a5, type SendOptions as a6, type ShellCommand as a7, type ShellConversationTurn as a8, type ShellOutput as a9, type ShellOutputDeltaUpdate as aa, type StepCompletedUpdate as ab, type StepStartedUpdate as ac, type StreamToCompletionResult as ad, type SummaryCompletedUpdate as ae, type SummaryStartedUpdate as af, type SummaryUpdate as ag, type TextBlock as ah, type TextDeltaUpdate as ai, type ThinkingCompletedUpdate as aj, type ThinkingDeltaUpdate as ak, type ThinkingMessage as al, type TokenDeltaUpdate as am, type TokenUsage as an, type ToolCall as ao, type ToolCallCompletedUpdate as ap, type ToolCallStartedUpdate as aq, type ToolContextMessage as ar, type ToolResult as as, type ToolResultGuardOptions as at, type ToolUseBlock as au, type TurnEndedUpdate as av, type UserMessage as aw, type UserMessageAppendedUpdate as ax, emitRunEvent as ay, type Run as b, type MessageOrigin as c, type AssistantMessage as d, type ConversationStep as e, type ConversationTurn as f, type CostBreakdown as g, type CostSource as h, type CostStatus as i, type GenerateRunResult as j, type InputProcessorContext as k, type InteractionUpdate as l, type McpAuthConfig as m, type McpHttpServerConfig as n, type McpOAuthConfig as o, type McpStdioServerConfig as p, type ModelParameterValue as q, type PartialToolCallUpdate as r, type ProcessorControls as s, type ProcessorTripwire as t, type ProcessorViolation as u, type RunCompactBoundaryEvent as v, type RunErrorDetail as w, type RunEvent as x, type RunEventSink as y, type RunGitInfo as z };

package/dist/types/agent.d.ts

@@ -392,6 +392,16 @@ export interface AgentOptions {
      * resolver drives the per-send `<skills>` block.
      */
     skills?: SkillsSettings | SkillsResolver;
+    /**
+     * SE24 — guardrail processors. `inputProcessors` run in order before the LLM
+     * (normalize / validate / block / rewrite the user message); `outputProcessors`
+     * run on the model's final text before it reaches the caller (redact / block).
+     * A processor that `abort()`s stops the run with a {@link RunResult.tripwire}
+     * (+ a `tripwire` run-event). Empty/absent ⇒ unchanged behavior. See
+     * {@link Processor}.
+     */
+    inputProcessors?: readonly import("./processors.js").Processor[];
+    outputProcessors?: readonly import("./processors.js").Processor[];
     /** Memory configuration. Persists durable facts; auto-recalled on send. */
     memory?: MemorySettings;
     /**

package/dist/types/index.d.ts

@@ -9,6 +9,7 @@ export type * from "./goal-events.js";
 export type * from "./mcp.js";
 export type * from "./memory-adapter.js";
 export type * from "./messages.js";
+export type * from "./processors.js";
 export type * from "./providers.js";
 export type * from "./run.js";
 export type * from "./session.js";

package/dist/types/processors.d.ts

@@ -0,0 +1,84 @@
+/**
+ * SE24 — guardrail processor pipeline. A `Processor` inspects/transforms/blocks
+ * the user message (input) or the model's final text (output). Processors run in
+ * order; each may rewrite its payload, `abort(reason)` to stop the run (surfaced
+ * as {@link RunResult.tripwire} + a `tripwire` run-event), or `warn()` to report
+ * a non-blocking violation. The pipeline is provider-agnostic and carries NO LLM
+ * — an LLM-classifier processor is the consumer's (delegated, see the guardrails
+ * ADR). Mirrors Mastra's `inputProcessors` / `outputProcessors`.
+ *
+ * @public
+ */
+/**
+ * A policy violation surfaced to a processor's {@link Processor.onViolation}
+ * callback — on `abort()` (blocking) AND on `warn()` (non-blocking).
+ *
+ * @public
+ */
+export interface ProcessorViolation {
+    processorId: string;
+    message: string;
+    detail?: unknown;
+}
+/**
+ * Controls available to a processor while it runs: `abort()` stops the run with
+ * a tripwire; `warn()` reports a non-blocking violation and continues.
+ *
+ * @public
+ */
+export interface ProcessorControls {
+    /** Stop the run immediately with a tripwire. Throws — code after it never runs. */
+    abort(reason: string): never;
+    /** Report a non-blocking violation (fires `onViolation`); the run continues. */
+    warn(message: string, detail?: unknown): void;
+}
+/** Context passed to {@link Processor.processInput}. @public */
+export interface InputProcessorContext extends ProcessorControls {
+    /** The user message text for this send. */
+    message: string;
+    agentId: string;
+}
+/** Context passed to {@link Processor.processOutput}. @public */
+export interface OutputProcessorContext extends ProcessorControls {
+    /** The model's final assistant text for this run. */
+    text: string;
+    agentId: string;
+}
+/**
+ * A guardrail processor. Provide `processInput` (runs before the LLM) and/or
+ * `processOutput` (runs on the final text). A processor's `strategy` (block /
+ * rewrite / redact / warn) is expressed via the {@link ProcessorControls}:
+ * return the transformed payload to rewrite/redact, `abort()` to block, `warn()`
+ * to report without blocking. The core ships no strategy enum — strategies are a
+ * processor-level convention over these primitives.
+ *
+ * @public
+ */
+export interface Processor {
+    /** Stable id — surfaced on {@link ProcessorViolation} and {@link RunResult.tripwire}. */
+    id: string;
+    /**
+     * Transform or block the user message before it reaches the model. Return the
+     * (possibly rewritten) text; returning nothing (void) preserves the message
+     * unchanged. May be `async`.
+     */
+    processInput?(ctx: InputProcessorContext): string | Promise<string> | void;
+    /**
+     * Transform or block the model's final text before it reaches the caller.
+     * Return the (possibly redacted) text; returning nothing (void) preserves the
+     * text unchanged. May be `async`.
+     */
+    processOutput?(ctx: OutputProcessorContext): string | Promise<string> | void;
+    /** Fires on `abort()` and `warn()`. Errors thrown here are swallowed (never break the pipeline). */
+    onViolation?(violation: ProcessorViolation): void;
+}
+/**
+ * The tripwire detail attached to {@link RunResult.tripwire} when a processor
+ * aborts, and carried by the `tripwire` run-event.
+ *
+ * @public
+ */
+export interface ProcessorTripwire {
+    reason: string;
+    processorId: string;
+}

package/dist/types/run-events.d.ts

@@ -16,7 +16,17 @@
  *
  * @public
  */
-export type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent;
+export type RunEvent = RunToolProgressEvent | RunRateLimitEvent | RunPermissionDeniedEvent | RunTaskStartedEvent | RunTaskUpdatedEvent | RunTaskCompletedEvent | RunCompactBoundaryEvent | RunTripwireEvent;
+/**
+ * SE24 — a guardrail processor called `abort()`; the run stops with a tripwire.
+ * Delivered via {@link SendOptions.onRunEvent} (mirrors the `RunResult.tripwire`
+ * surfaced on `wait()`).
+ */
+export interface RunTripwireEvent {
+    readonly type: "tripwire";
+    readonly reason: string;
+    readonly processorId: string;
+}
 /** A tool call is being dispatched (before its result). */
 export interface RunToolProgressEvent {
     readonly type: "tool_progress";

package/dist/types/run.d.ts

@@ -84,6 +84,18 @@ export interface RunResult {
     id: string;
     status: "finished" | "error" | "cancelled";
     result?: string;
+    /**
+     * SE24 — set when a guardrail processor called `abort()`. The run stops
+     * (`status: "cancelled"`) and `tripwire` carries the blocking reason +
+     * processor id. `undefined` on every non-guardrail outcome. A
+     * `throwOnError: true` agent resolves normally on a tripwire (status is
+     * `"cancelled"`, not `"error"`). On an OUTPUT block the model already ran, so
+     * `usage`/`cost` survive (billing) while `result` is suppressed; an INPUT
+     * block never reaches the model, so `usage` is absent.
+     *
+     * @public
+     */
+    tripwire?: import("./processors.js").ProcessorTripwire;
     model?: ModelSelection;
     durationMs?: number;
     git?: RunGitInfo;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "2.25.0",
+  "version": "2.26.0",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheo/theokit-sdk#readme",