@theokit/sdk 2.25.0 → 2.26.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 2.26.0
+
+### Minor Changes
+
+- d31e2ca: **SE24 — guardrail processor pipeline (`inputProcessors` / `outputProcessors`).**
+
+  `AgentOptions.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` is `{ id; processInput?; processOutput?; onViolation? }`; each handler receives `ctx` with `abort(reason)` (block → the run stops with `RunResult.tripwire { reason, processorId }` + a `tripwire` run-event via `SendOptions.onRunEvent`) and `warn(message, detail?)` (non-blocking → fires `onViolation`, continues), and returns the (possibly rewritten) payload.
+
+  The core ships no `strategy` enum — block/rewrite/redact/warn reduce to `abort` / return-string / `warn` (the built-in SE25 processors expose a `strategy` option over these). An input block never reaches the model (a terminal tripwire run); an output block turns a finished run's result into a tripwire on `wait()`. Streaming output redaction is deferred (v1 processes the buffered `wait()` path). Cloud agents reject processors (function handlers don't serialize). Back-compat: no processors ⇒ unchanged. New public types `Processor` / `ProcessorViolation` / `InputProcessorContext` / `OutputProcessorContext` / `ProcessorControls` / `ProcessorTripwire` / `RunTripwireEvent` + `RunResult.tripwire`. ADR 0008. Mirrors Mastra Guardrails input/output processors. From the Mastra Guardrails comparison (SDK Evolution roadmap SE24).
+
+- cc8efee: **SE25 — deterministic in-tree guardrail processors (`createUnicodeNormalizer`, `createTokenLimiter`).**
+
+  Two churn-free, no-LLM processors built on the SE24 seam:
+
+  - `createUnicodeNormalizer({ stripControlChars?, collapseWhitespace? })` — an input processor: Unicode NFC normalization (stdlib `String.prototype.normalize`) plus optional C0/DEL control-char stripping (keeps tab/newline/carriage-return) and whitespace collapsing.
+  - `createTokenLimiter({ limit, strategy? })` — caps text to a token budget using a char-based estimate (~chars/4, no tokenizer dep; `estimateTokens` is exported). `strategy: "truncate"` (default, cut to fit) or `"block"` (abort → tripwire). Fires on whichever array it is placed in (input caps the prompt, output caps the response).
+
+  Both are OPT-IN (add to `inputProcessors`/`outputProcessors`); nothing auto-injects them; back-compat preserved.
+
+  **`BatchPartsProcessor` is intentionally DEFERRED**, not shipped: TheoKit's `run.stream()` emits full `SDKAssistantMessage`s, not token-granular deltas, so there is no SSE chunk stream to coalesce in the in-process runtime (Mastra's BatchParts cuts HTTP network overhead). It becomes meaningful only alongside a future HTTP/SSE streaming transport (the same milestone as SE24's deferred streaming-output redaction). Mirrors Mastra's deterministic guardrail processors. From the Mastra Guardrails comparison (SDK Evolution roadmap SE25).
+
+### Patch Changes
+
+- 0685363: **SE26 — delegate LLM-classifier guardrail processors (ADR + recommendation + example).**
+
+  Records the decision (ADR 0009) to DELEGATE the LLM-classifier guardrail processors — moderation, PII, prompt-injection, language, prompt-scrubber — to specialist libraries / consumer code built ON the SE24 seam, rather than shipping concrete classifiers in `@theokit/sdk` core (mirrors the AUTH-DELEGATION lock: constant churn — provider/model deltas, taxonomies, thresholds, jailbreak patterns — vs a stable seam a single-maintainer core can own). No classifier is added to core.
+
+  Ships the paved path: `docs/concepts/guardrails.md` (how to build moderation / PII / injection processors on the seam + recommended external classifiers) and `examples/guardrails/` (a runnable moderation + PII-redaction example over a pluggable classifier). No public API change. From the Mastra Guardrails comparison (SDK Evolution roadmap SE26).
+
 ## 2.25.0
 
 ### Minor Changes

package/dist/a2a/index.cjs

@@ -3454,8 +3454,18 @@ function validateCloudToolParity(options) {
   if (options.cloud === void 0) return;
   rejectFunctionSystemPrompt(options);
   rejectFunctionSkills(options);
+  rejectProcessors(options);
   rejectStdioMcpLocalPaths(options);
 }
+function rejectProcessors(options) {
+  const hasProcessors = (options.inputProcessors?.length ?? 0) > 0 || (options.outputProcessors?.length ?? 0) > 0;
+  if (hasProcessors) {
+    throw new ConfigurationError(
+      "Cloud agents can't run guardrail processors \u2014 a Processor carries function handlers that don't survive serialization to PaaS. Run processors on a local agent, or move the guardrail into a server-side gateway in front of TheoCloud.",
+      { code: "cloud_incompatible_function_resolver" }
+    );
+  }
+}
 function rejectFunctionSystemPrompt(options) {
   if (typeof options.systemPrompt === "function") {
     throw new ConfigurationError(
@@ -16356,6 +16366,162 @@ var init_abort_utils = __esm({
   }
 });
 
+// src/internal/runtime/processors/run-processors.ts
+function fireViolation(processor, violation) {
+  try {
+    processor.onViolation?.(violation);
+  } catch {
+  }
+}
+function controlsFor(processor) {
+  return {
+    abort(reason) {
+      throw new ProcessorAbort(processor.id, reason);
+    },
+    warn(message, detail) {
+      fireViolation(processor, {
+        processorId: processor.id,
+        message,
+        ...detail !== void 0 ? { detail } : {}
+      });
+    }
+  };
+}
+function selectHandler(processor, phase) {
+  if (phase === "input") {
+    return processor.processInput ? { kind: "input", fn: processor.processInput } : void 0;
+  }
+  return processor.processOutput ? { kind: "output", fn: processor.processOutput } : void 0;
+}
+function invokeHandler(handler, value, agentId, controls) {
+  return handler.kind === "input" ? handler.fn({ message: value, agentId, ...controls }) : handler.fn({ text: value, agentId, ...controls });
+}
+async function runOneProcessor(processor, value, agentId, phase) {
+  const handler = selectHandler(processor, phase);
+  if (handler === void 0) return { value };
+  try {
+    const out = await invokeHandler(handler, value, agentId, controlsFor(processor));
+    return { value: typeof out === "string" ? out : value };
+  } catch (err) {
+    if (!(err instanceof ProcessorAbort)) throw err;
+    fireViolation(processor, { processorId: err.processorId, message: err.reason });
+    return { tripwire: { reason: err.reason, processorId: err.processorId } };
+  }
+}
+async function runPipeline(processors, initial, agentId, phase) {
+  let value = initial;
+  for (const processor of processors) {
+    const step = await runOneProcessor(processor, value, agentId, phase);
+    if ("tripwire" in step) return { kind: "tripwire", tripwire: step.tripwire };
+    value = step.value;
+  }
+  return { kind: "ok", value };
+}
+function runInputProcessors(processors, message, agentId) {
+  return runPipeline(processors, message, agentId, "input");
+}
+function runOutputProcessors(processors, text, agentId) {
+  return runPipeline(processors, text, agentId, "output");
+}
+var ProcessorAbort;
+var init_run_processors = __esm({
+  "src/internal/runtime/processors/run-processors.ts"() {
+    ProcessorAbort = class {
+      constructor(processorId, reason) {
+        this.processorId = processorId;
+        this.reason = reason;
+      }
+      processorId;
+      reason;
+    };
+  }
+});
+
+// src/internal/runtime/processors/tripwire-run.ts
+function emptyStream() {
+  return {
+    next: () => Promise.resolve({ done: true, value: void 0 }),
+    return: () => Promise.resolve({ done: true, value: void 0 }),
+    throw: (err) => Promise.reject(err),
+    [Symbol.asyncIterator]() {
+      return this;
+    }
+  };
+}
+function createTripwireRun(args) {
+  const id = globalThis.crypto.randomUUID();
+  const result = {
+    id,
+    status: "cancelled",
+    tripwire: args.tripwire,
+    ...args.model !== void 0 ? { model: args.model } : {}
+  };
+  const run = {
+    id,
+    agentId: args.agentId,
+    status: "cancelled",
+    ...args.model !== void 0 ? { model: args.model } : {},
+    stream: () => emptyStream(),
+    wait: () => Promise.resolve(result),
+    cancel: () => Promise.resolve(),
+    conversation: () => Promise.resolve([]),
+    supports: (op) => SUPPORTED.has(op),
+    unsupportedReason: (op) => SUPPORTED.has(op) ? void 0 : `operation "${op}" is not available on a tripwire run`,
+    onDidChangeStatus: () => () => {
+    }
+    // already terminal — status never changes
+  };
+  registerRun(run);
+  return run;
+}
+var SUPPORTED;
+var init_tripwire_run = __esm({
+  "src/internal/runtime/processors/tripwire-run.ts"() {
+    init_run_registry();
+    SUPPORTED = /* @__PURE__ */ new Set([
+      "stream",
+      "wait",
+      "cancel",
+      "conversation"
+    ]);
+  }
+});
+
+// src/internal/runtime/processors/wrap-output-run.ts
+function wrapRunWithOutputProcessors(args) {
+  if (args.processors.length === 0) return args.run;
+  const compute = async () => {
+    const result = await args.run.wait();
+    if (result.status !== "finished" || result.result === void 0) return result;
+    const res = await runOutputProcessors(args.processors, result.result, args.agentId);
+    if (res.kind === "ok") return { ...result, result: res.value };
+    emitRunEvent(args.onRunEvent, {
+      type: "tripwire",
+      reason: res.tripwire.reason,
+      processorId: res.tripwire.processorId
+    });
+    const { result: _suppressed, ...metadata } = result;
+    return { ...metadata, status: "cancelled", tripwire: res.tripwire };
+  };
+  let processed;
+  const wrappedWait = () => {
+    processed ??= compute();
+    return processed;
+  };
+  return new Proxy(args.run, {
+    get(target, prop, receiver) {
+      if (prop === "wait") return wrappedWait;
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+var init_wrap_output_run = __esm({
+  "src/internal/runtime/processors/wrap-output-run.ts"() {
+    init_run_events();
+    init_run_processors();
+  }
+});
+
 // src/internal/runtime/local-agent/local-agent-memory-hooks.ts
 async function applyPreUserSendHook(args) {
   const handlers = args.pluginManager.hooksFor("pre_user_send");
@@ -16408,11 +16574,38 @@ var init_local_agent_memory_hooks = __esm({
 });
 
 // src/internal/runtime/local-agent/local-agent-send.ts
+async function applyInputProcessors(inputs, message, rawUserText, options, sendModel) {
+  const processors = inputs.options.inputProcessors;
+  if (processors === void 0 || processors.length === 0) {
+    return { userText: rawUserText, effectiveMessage: message };
+  }
+  const res = await runInputProcessors(processors, rawUserText, inputs.agentId);
+  if (res.kind === "tripwire") {
+    emitRunEvent(options.onRunEvent, {
+      type: "tripwire",
+      reason: res.tripwire.reason,
+      processorId: res.tripwire.processorId
+    });
+    return {
+      tripwireRun: createTripwireRun({
+        agentId: inputs.agentId,
+        tripwire: res.tripwire,
+        model: sendModel
+      })
+    };
+  }
+  const effectiveMessage = typeof message === "string" ? res.value : { ...message, text: res.value };
+  return { userText: res.value, effectiveMessage };
+}
 async function executeSendLocked(inputs, message, options) {
   if (inputs.disposed) throw new AgentDisposedError(inputs.agentId);
   await consumePending(inputs.agentId, inputs.invalidationPending, inputs.clearInvalidation, inputs.reload);
-  inputs.applyModelOverride(normalizeModel(options.model));
-  const userText = typeof message === "string" ? message : message.text;
+  const sendModel = normalizeModel(options.model);
+  inputs.applyModelOverride(sendModel);
+  const rawUserText = typeof message === "string" ? message : message.text;
+  const gated = await applyInputProcessors(inputs, message, rawUserText, options, sendModel);
+  if ("tripwireRun" in gated) return gated.tripwireRun;
+  const { userText, effectiveMessage } = gated;
   if (inputs.options.onBeforeSend !== void 0) {
     await inputs.options.onBeforeSend({
       conversationId: inputs.agentId,
@@ -16424,7 +16617,7 @@ async function executeSendLocked(inputs, message, options) {
     pluginManager: inputs.pluginManagerCode,
     agentId: inputs.agentId,
     options: inputs.options,
-    original: message,
+    original: effectiveMessage,
     userText,
     sendOptions: options
   });
@@ -16462,11 +16655,18 @@ async function executeSendLocked(inputs, message, options) {
     memoryTools,
     effectiveMemoryProvider
   );
+  const outputProcessors = inputs.options.outputProcessors;
+  const processedRun = outputProcessors !== void 0 && outputProcessors.length > 0 ? wrapRunWithOutputProcessors({
+    run,
+    processors: outputProcessors,
+    agentId: inputs.agentId,
+    onRunEvent: options.onRunEvent
+  }) : run;
   return wrapRunWithPostReplyHook({
     pluginManager: inputs.pluginManagerCode,
     agentId: inputs.agentId,
     options: inputs.options,
-    run,
+    run: processedRun,
     userText
   });
 }
@@ -16477,10 +16677,14 @@ function readMemoryForSend(workspaceCwd, memoryConfig) {
 var init_local_agent_send = __esm({
   "src/internal/runtime/local-agent/local-agent-send.ts"() {
     init_errors();
+    init_run_events();
     init_abort_utils();
     init_memory_path_selector();
     init_memory_store();
     init_model_selection();
+    init_run_processors();
+    init_tripwire_run();
+    init_wrap_output_run();
     init_agent_session();
     init_safe_call();
     init_local_agent_invalidate();