@theokit/agents 6.4.2 → 7.0.0

package/dist/{chunk-UJPG3K26.js → chunk-3YPKTOJ6.js}

@@ -1,6 +1,6 @@
 import {
   __name
-} from "./chunk-7QVYU63E.js";
+} from "./chunk-Z4QWC7IK.js";
 
 // src/errors.ts
 import { ConfigurationError } from "@theokit/sdk/errors";
@@ -455,6 +455,198 @@ function generateAgentRoutes(ctx) {
 }
 __name(generateAgentRoutes, "generateAgentRoutes");
 
+// src/guardrails/types.ts
+var GuardrailViolationError = class extends Error {
+  static {
+    __name(this, "GuardrailViolationError");
+  }
+  guardName;
+  phase;
+  reason;
+  constructor(guardName, phase, reason) {
+    super(`Guardrail "${guardName}" blocked ${phase}: ${reason}`), this.guardName = guardName, this.phase = phase, this.reason = reason;
+    this.name = "GuardrailViolationError";
+  }
+};
+var CostBudgetExceededError = class extends Error {
+  static {
+    __name(this, "CostBudgetExceededError");
+  }
+  usedTokens;
+  maxTokens;
+  constructor(usedTokens, maxTokens) {
+    super(`Cost budget exceeded: ${usedTokens} > ${maxTokens} tokens`), this.usedTokens = usedTokens, this.maxTokens = maxTokens;
+    this.name = "CostBudgetExceededError";
+  }
+};
+
+// src/guardrails/detectors.ts
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+__name(estimateTokens, "estimateTokens");
+var INJECTION_PHRASES = [
+  "previous instructions",
+  "disregard the above",
+  "you are now dan",
+  "system prompt",
+  "no restrictions",
+  "without restrictions",
+  "no rules",
+  "override your"
+];
+function normalizeForMatch(text) {
+  return text.toLowerCase().replace(/\s+/g, " ");
+}
+__name(normalizeForMatch, "normalizeForMatch");
+function promptInjectionDetector(options = {}) {
+  const phrases = [
+    ...INJECTION_PHRASES,
+    ...(options.extra ?? []).map((p) => p.toLowerCase())
+  ];
+  return {
+    name: "prompt-injection",
+    checkInput(text) {
+      const normalized = normalizeForMatch(text);
+      for (const phrase of phrases) {
+        if (normalized.includes(phrase)) {
+          return {
+            action: "block",
+            reason: `prompt injection phrase matched: "${phrase}"`
+          };
+        }
+      }
+      return {
+        action: "allow"
+      };
+    }
+  };
+}
+__name(promptInjectionDetector, "promptInjectionDetector");
+var CPF = /\b\d{3}\.?\d{3}\.?\d{3}-?\d{2}\b/g;
+var EMAIL = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g;
+var PHONE = /\+?\d[\d\s()-]{7,13}\d/g;
+function piiDetector(options = {}) {
+  const placeholder = options.placeholder ?? "[REDACTED]";
+  return {
+    name: "pii",
+    checkInput(text) {
+      let redacted = text;
+      redacted = redacted.replace(EMAIL, placeholder);
+      redacted = redacted.replace(CPF, placeholder);
+      redacted = redacted.replace(PHONE, placeholder);
+      if (redacted === text) return {
+        action: "allow"
+      };
+      return {
+        action: "redact",
+        text: redacted,
+        reason: "PII detected and redacted"
+      };
+    }
+  };
+}
+__name(piiDetector, "piiDetector");
+var OBFUSCATION_CHARS = /[\u200B-\u200D\uFEFF\u202A-\u202E\u2066-\u2069]/g;
+function unicodeNormalizer() {
+  return {
+    name: "unicode-normalizer",
+    checkInput(text) {
+      const cleaned = text.normalize("NFKC").replace(OBFUSCATION_CHARS, "");
+      if (cleaned === text) return {
+        action: "allow"
+      };
+      return {
+        action: "redact",
+        text: cleaned,
+        reason: "obfuscation characters normalized"
+      };
+    }
+  };
+}
+__name(unicodeNormalizer, "unicodeNormalizer");
+function costGuard(options) {
+  let used = 0;
+  return {
+    name: "cost-guard",
+    // Returns a Promise explicitly (not `async`) so a budget breach REJECTS uniformly — never a
+    // sync throw — safe for direct callers and for the pipeline's `await g.checkInput()`.
+    checkInput(text) {
+      used += estimateTokens(text);
+      if (used > options.maxTokens) {
+        return Promise.reject(new CostBudgetExceededError(used, options.maxTokens));
+      }
+      return Promise.resolve({
+        action: "allow"
+      });
+    }
+  };
+}
+__name(costGuard, "costGuard");
+function outputModeration(options) {
+  return {
+    name: "output-moderation",
+    async checkOutput(text) {
+      const flagged = await options.moderate(text);
+      return flagged ? {
+        action: "block",
+        reason: "output flagged by moderation predicate"
+      } : {
+        action: "allow"
+      };
+    }
+  };
+}
+__name(outputModeration, "outputModeration");
+
+// src/guardrails/pipeline.ts
+async function runInputGuards(text, guards) {
+  let current = text;
+  for (const g of guards) {
+    if (!g.checkInput) continue;
+    const r = await g.checkInput(current);
+    if (r.action === "block") {
+      throw new GuardrailViolationError(g.name, "input", r.reason ?? "blocked");
+    }
+    if (r.action === "redact" && r.text !== void 0) current = r.text;
+  }
+  return current;
+}
+__name(runInputGuards, "runInputGuards");
+async function runOutputGuards(text, guards) {
+  let current = text;
+  for (const g of guards) {
+    if (!g.checkOutput) continue;
+    const r = await g.checkOutput(current);
+    if (r.action === "block") {
+      throw new GuardrailViolationError(g.name, "output", r.reason ?? "blocked");
+    }
+    if (r.action === "redact" && r.text !== void 0) current = r.text;
+  }
+  return current;
+}
+__name(runOutputGuards, "runOutputGuards");
+
+// src/guardrails/stream.ts
+async function* moderateOutputStream(inner, guards, extractText) {
+  const hasOutputGuard = guards.some((g) => g.checkOutput != null);
+  if (!hasOutputGuard) return yield* inner;
+  const buffered = [];
+  let accumulated = "";
+  let step = await inner.next();
+  while (!step.done) {
+    const event = step.value;
+    const text = extractText(event);
+    if (text !== void 0) accumulated += text;
+    buffered.push(event);
+    step = await inner.next();
+  }
+  await runOutputGuards(accumulated, guards);
+  for (const event of buffered) yield event;
+  return step.value;
+}
+__name(moderateOutputStream, "moderateOutputStream");
+
 // src/bridge/tool-hooks-plugin.ts
 function createToolHooksPlugin(hooks) {
   return {
@@ -508,6 +700,33 @@ function createToolHooksPlugin(hooks) {
 }
 __name(createToolHooksPlugin, "createToolHooksPlugin");
 
+// src/bridge/model-selection.ts
+var PARAM_THINKING = "thinking";
+function buildModelSelection(model, effort) {
+  const base = typeof model === "string" ? {
+    id: model
+  } : {
+    ...model
+  };
+  if (!effort) return base;
+  return {
+    ...base,
+    params: [
+      ...base.params ?? [],
+      {
+        id: PARAM_THINKING,
+        value: effort
+      }
+    ]
+  };
+}
+__name(buildModelSelection, "buildModelSelection");
+function reasoningEffortOf(model) {
+  const params = typeof model === "string" ? void 0 : model.params;
+  return params?.find((p) => p.id === PARAM_THINKING)?.value;
+}
+__name(reasoningEffortOf, "reasoningEffortOf");
+
 // src/bridge/event-translator.ts
 function asString(value, fallback) {
   if (typeof value === "string") return value;
@@ -551,7 +770,11 @@ function translateAssistantEvent(msg) {
     if (b.type === "tool_use") {
       events.push({
         type: "tool_call",
-        callId: b.id ?? `tc-${Date.now()}`,
+        // #138 — era `tc-${Date.now()}`. Um id novo a cada chamada NUNCA está no conjunto de
+        // dedup, então o fallback derrotava a dedup por construção — e ainda parecia um id de
+        // verdade para quem lê. String vazia é honesta: `isDuplicatedByDelta` a trata como
+        // "não sei identificar" e prefere um duplo-render visível a uma supressão silenciosa.
+        callId: b.id ?? "",
         toolName: b.name ?? "unknown",
         input: b.input ?? {}
       });
@@ -562,7 +785,7 @@ function translateAssistantEvent(msg) {
 __name(translateAssistantEvent, "translateAssistantEvent");
 function translateToolCallEvent(msg) {
   const status = msg.status;
-  const callId = asString(msg.call_id, `tc-${Date.now()}`);
+  const callId = asString(msg.call_id, "");
   const toolName = asString(msg.name, "unknown");
   if (status === "completed") {
     return [
@@ -631,6 +854,22 @@ function translateStatusEvent(msg) {
   return [];
 }
 __name(translateStatusEvent, "translateStatusEvent");
+var jaAvisados = /* @__PURE__ */ new Set();
+function avisarSeDesconhecido(tipo, ignoradosDeProposito) {
+  if (ignoradosDeProposito.has(tipo) || jaAvisados.has(tipo)) return;
+  jaAvisados.add(tipo);
+  console.warn(`[theokit] agents.bridge: evento "${tipo}" do SDK n\xE3o \xE9 traduzido e foi descartado. Se ele carrega informa\xE7\xE3o que a UI precisa, o tradutor precisa de um caso para ele (#141).`);
+}
+__name(avisarSeDesconhecido, "avisarSeDesconhecido");
+var SDK_MESSAGE_IGNORADOS = /* @__PURE__ */ new Set([
+  "user"
+]);
+var INTERACTION_UPDATE_IGNORADOS = /* @__PURE__ */ new Set([
+  "thinking-completed",
+  "token-delta",
+  "step-started",
+  "step-completed"
+]);
 function translateSdkEvent(msg, runId) {
   switch (msg.type) {
     case "system":
@@ -648,7 +887,31 @@ function translateSdkEvent(msg, runId) {
       ];
     case "status":
       return translateStatusEvent(msg);
+    case "request":
+      return [
+        {
+          type: "input_requested",
+          requestId: asString(msg.request_id, "")
+        }
+      ];
+    case "task": {
+      const status = typeof msg.status === "string" ? msg.status : void 0;
+      const text = typeof msg.text === "string" ? msg.text : void 0;
+      if (status === void 0 && text === void 0) return [];
+      return [
+        {
+          type: "task_progress",
+          ...status !== void 0 ? {
+            status
+          } : {},
+          ...text !== void 0 ? {
+            text
+          } : {}
+        }
+      ];
+    }
     default:
+      avisarSeDesconhecido(msg.type, SDK_MESSAGE_IGNORADOS);
       return [];
   }
 }
@@ -698,39 +961,20 @@ function translateInteractionUpdate(update) {
           isError: false
         }
       ];
+    case "shell-output-delta":
+      return [
+        {
+          type: "shell_output",
+          event: update.event
+        }
+      ];
     default:
+      avisarSeDesconhecido(update.type, INTERACTION_UPDATE_IGNORADOS);
       return [];
   }
 }
 __name(translateInteractionUpdate, "translateInteractionUpdate");
 
-// src/bridge/model-selection.ts
-var PARAM_THINKING = "thinking";
-function buildModelSelection(model, effort) {
-  const base = typeof model === "string" ? {
-    id: model
-  } : {
-    ...model
-  };
-  if (!effort) return base;
-  return {
-    ...base,
-    params: [
-      ...base.params ?? [],
-      {
-        id: PARAM_THINKING,
-        value: effort
-      }
-    ]
-  };
-}
-__name(buildModelSelection, "buildModelSelection");
-function reasoningEffortOf(model) {
-  const params = typeof model === "string" ? void 0 : model.params;
-  return params?.find((p) => p.id === PARAM_THINKING)?.value;
-}
-__name(reasoningEffortOf, "reasoningEffortOf");
-
 // src/bridge/think-tag-extractor.ts
 var TAG = "think";
 var OPEN = `<${TAG}>`;
@@ -1059,6 +1303,134 @@ function realUsageDone(result, t0) {
 }
 __name(realUsageDone, "realUsageDone");
 
+// src/bridge/sdk-adapter-merge.ts
+function createAsyncQueue() {
+  const items = [];
+  let wake = null;
+  let closed = false;
+  return {
+    push(item) {
+      items.push(item);
+      if (wake) {
+        wake();
+        wake = null;
+      }
+    },
+    close() {
+      closed = true;
+      if (wake) {
+        wake();
+        wake = null;
+      }
+    },
+    async *[Symbol.asyncIterator]() {
+      for (; ; ) {
+        while (items.length > 0) {
+          const next = items.shift();
+          if (next !== void 0) yield next;
+        }
+        if (closed) return;
+        await new Promise((resolve) => {
+          wake = resolve;
+        });
+      }
+    }
+  };
+}
+__name(createAsyncQueue, "createAsyncQueue");
+function streamCallId(ev) {
+  return typeof ev.callId === "string" ? ev.callId : "";
+}
+__name(streamCallId, "streamCallId");
+function idsDaMesmaChamada(ev, update) {
+  const ids = [];
+  const call = streamCallId(ev);
+  if (call !== "") ids.push(call);
+  const model = update?.modelCallId;
+  if (typeof model === "string" && model !== "" && model !== call) ids.push(model);
+  return ids;
+}
+__name(idsDaMesmaChamada, "idsDaMesmaChamada");
+function isDuplicatedByDelta(ev, state) {
+  if (ev.type === "text_delta") return state.sawTextDelta;
+  if (ev.type === "thinking") return state.sawThinkingDelta;
+  if (ev.type === "tool_call") {
+    const id = streamCallId(ev);
+    return id !== "" && state.emittedToolCallIds.has(id);
+  }
+  if (ev.type === "tool_result") {
+    const id = streamCallId(ev);
+    return id !== "" && state.emittedToolResultIds.has(id);
+  }
+  return false;
+}
+__name(isDuplicatedByDelta, "isDuplicatedByDelta");
+async function* mergeDeltaStream(queue, openStream, runId, state) {
+  let pumpError;
+  const pump = (async () => {
+    try {
+      const stream = await openStream();
+      for await (const msg of stream) queue.push({
+        kind: "sdk",
+        msg
+      });
+    } finally {
+      queue.close();
+    }
+  })().catch((thrown) => {
+    pumpError = {
+      thrown
+    };
+  });
+  for await (const item of queue) {
+    if (item.kind === "delta") {
+      state.lastEventType = item.event.type;
+      yield item.event;
+      continue;
+    }
+    for (const out of translateSdkEvent(item.msg, runId)) {
+      if (out.type === "done") continue;
+      if (isDuplicatedByDelta(out, state)) continue;
+      if (out.type === "error") state.sawError = true;
+      state.lastEventType = out.type;
+      yield out;
+    }
+  }
+  await pump;
+  if (pumpError) throw pumpError.thrown;
+}
+__name(mergeDeltaStream, "mergeDeltaStream");
+function createDeltaSink(queue) {
+  const state = {
+    sawTextDelta: false,
+    sawThinkingDelta: false,
+    emittedToolCallIds: /* @__PURE__ */ new Set(),
+    emittedToolResultIds: /* @__PURE__ */ new Set(),
+    sawError: false,
+    lastEventType: ""
+  };
+  const onDelta = /* @__PURE__ */ __name((d) => {
+    for (const event of translateInteractionUpdate(d.update)) {
+      if (event.type === "text_delta") state.sawTextDelta = true;
+      else if (event.type === "thinking") state.sawThinkingDelta = true;
+      else if (event.type === "tool_call") {
+        for (const id of idsDaMesmaChamada(event, d.update)) state.emittedToolCallIds.add(id);
+      } else if (event.type === "tool_result") {
+        for (const id of idsDaMesmaChamada(event, d.update)) state.emittedToolResultIds.add(id);
+      }
+      queue.push({
+        kind: "delta",
+        event
+      });
+    }
+  }, "onDelta");
+  return {
+    state,
+    onDelta
+  };
+}
+__name(createDeltaSink, "createDeltaSink");
+
 // src/bridge/tool-dialect-stripper.ts
 var OPEN2 = "<function=";
 var CLOSE2 = "</tool_call>";
@@ -1207,122 +1579,6 @@ async function loadSdkRuntime() {
   }
 }
 __name(loadSdkRuntime, "loadSdkRuntime");
-function createAsyncQueue() {
-  const items = [];
-  let wake = null;
-  let closed = false;
-  return {
-    push(item) {
-      items.push(item);
-      if (wake) {
-        wake();
-        wake = null;
-      }
-    },
-    close() {
-      closed = true;
-      if (wake) {
-        wake();
-        wake = null;
-      }
-    },
-    async *[Symbol.asyncIterator]() {
-      for (; ; ) {
-        while (items.length > 0) {
-          const next = items.shift();
-          if (next !== void 0) yield next;
-        }
-        if (closed) return;
-        await new Promise((resolve) => {
-          wake = resolve;
-        });
-      }
-    }
-  };
-}
-__name(createAsyncQueue, "createAsyncQueue");
-function streamCallId(ev) {
-  return typeof ev.callId === "string" ? ev.callId : "";
-}
-__name(streamCallId, "streamCallId");
-function isDuplicatedByDelta(ev, state) {
-  if (ev.type === "text_delta") return state.sawTextDelta;
-  if (ev.type === "thinking") return state.sawThinkingDelta;
-  if (ev.type === "tool_call") {
-    const id = streamCallId(ev);
-    return id !== "" && state.emittedToolCallIds.has(id);
-  }
-  if (ev.type === "tool_result") {
-    const id = streamCallId(ev);
-    return id !== "" && state.emittedToolResultIds.has(id);
-  }
-  return false;
-}
-__name(isDuplicatedByDelta, "isDuplicatedByDelta");
-async function* mergeDeltaStream(queue, openStream, runId, state) {
-  let pumpError;
-  const pump = (async () => {
-    try {
-      const stream = await openStream();
-      for await (const msg of stream) queue.push({
-        kind: "sdk",
-        msg
-      });
-    } finally {
-      queue.close();
-    }
-  })().catch((thrown) => {
-    pumpError = {
-      thrown
-    };
-  });
-  for await (const item of queue) {
-    if (item.kind === "delta") {
-      yield item.event;
-      continue;
-    }
-    for (const out of translateSdkEvent(item.msg, runId)) {
-      if (out.type === "done") continue;
-      if (isDuplicatedByDelta(out, state)) continue;
-      if (out.type === "error") state.sawError = true;
-      yield out;
-    }
-  }
-  await pump;
-  if (pumpError) throw pumpError.thrown;
-}
-__name(mergeDeltaStream, "mergeDeltaStream");
-function createDeltaSink(queue) {
-  const state = {
-    sawTextDelta: false,
-    sawThinkingDelta: false,
-    emittedToolCallIds: /* @__PURE__ */ new Set(),
-    emittedToolResultIds: /* @__PURE__ */ new Set(),
-    sawError: false
-  };
-  const onDelta = /* @__PURE__ */ __name((d) => {
-    for (const event of translateInteractionUpdate(d.update)) {
-      if (event.type === "text_delta") state.sawTextDelta = true;
-      else if (event.type === "thinking") state.sawThinkingDelta = true;
-      else if (event.type === "tool_call") {
-        const id = streamCallId(event);
-        if (id !== "") state.emittedToolCallIds.add(id);
-      } else if (event.type === "tool_result") {
-        const id = streamCallId(event);
-        if (id !== "") state.emittedToolResultIds.add(id);
-      }
-      queue.push({
-        kind: "delta",
-        event
-      });
-    }
-  }, "onDelta");
-  return {
-    state,
-    onDelta
-  };
-}
-__name(createDeltaSink, "createDeltaSink");
 function resolveTextTransformFlags(compiled, overrides) {
   return {
     parseThinkTags: overrides.parseThinkTags ?? compiled.parseThinkTags ?? false,
@@ -1466,6 +1722,7 @@ async function* streamSdkAgent(rt, compiled, sdkTools, opts) {
       onDelta
     };
     if (factoryOpts?.disableTools === true) sendOptions.toolChoice = "none";
+    if (overrides.onRunEvent !== void 0) sendOptions.onRunEvent = overrides.onRunEvent;
     const sendInput = overrides.images && overrides.images.length > 0 ? {
       text: message,
       images: overrides.images
@@ -1479,7 +1736,16 @@ async function* streamSdkAgent(rt, compiled, sdkTools, opts) {
     })) {
       yield event;
     }
-    if (!state.sawError) {
+    if (state.sawError) {
+      if (state.lastEventType !== "error") {
+        yield {
+          type: "error",
+          code: "RUN_FAILED",
+          message: "O turno terminou com erro; veja o evento `error` anterior.",
+          retryable: false
+        };
+      }
+    } else {
       yield realUsageDone(await (await sendPromise).wait(), t0);
     }
   } finally {
@@ -1519,10 +1785,34 @@ function toAgentFactory(def, opts) {
       ...m8,
       ...extra
     });
-    return agent;
+    return withGuardrails(agent, compiled.guardrails);
   };
 }
 __name(toAgentFactory, "toAgentFactory");
+function withGuardrails(handle, guardrails) {
+  if (guardrails === void 0 || guardrails.length === 0) return handle;
+  return {
+    get agentId() {
+      return handle.agentId;
+    },
+    dispose: /* @__PURE__ */ __name(() => handle.dispose(), "dispose"),
+    send: /* @__PURE__ */ __name(async (msg, sendOpts) => {
+      const guarded = await runInputGuards(msg, guardrails);
+      const turn = await handle.send(guarded, sendOpts);
+      return {
+        wait: /* @__PURE__ */ __name(async () => {
+          const out = await turn.wait();
+          if (out.result === void 0) return out;
+          return {
+            ...out,
+            result: await runOutputGuards(out.result, guardrails)
+          };
+        }, "wait")
+      };
+    }, "send")
+  };
+}
+__name(withGuardrails, "withGuardrails");
 
 // ../presenter/dist/index.js
 var __defProp = Object.defineProperty;
@@ -2089,6 +2379,61 @@ function doneToMetadata(event) {
   };
 }
 __name(doneToMetadata, "doneToMetadata");
+var ERROR_CODE_DATA_PART = "data-error-code";
+var INPUT_REQUESTED_DATA_PART = "data-input-requested";
+var TASK_PROGRESS_DATA_PART = "data-task-progress";
+var SHELL_OUTPUT_DATA_PART = "data-shell-output";
+function dataPart(type, data) {
+  return {
+    type,
+    data,
+    transient: true
+  };
+}
+__name(dataPart, "dataPart");
+function* errorChunks(errorText, code) {
+  if (code !== void 0) yield dataPart(ERROR_CODE_DATA_PART, {
+    code
+  });
+  yield {
+    type: "error",
+    errorText
+  };
+}
+__name(errorChunks, "errorChunks");
+function diagnosticDataPart(event) {
+  switch (event.type) {
+    case "checkpoint_saved":
+      return dataPart("data-checkpoint", {
+        checkpointId: event.checkpointId,
+        resumeToken: event.resumeToken,
+        step: event.step
+      });
+    // theokit#141 — without these cases the three restored events would be dropped by the loop's
+    // catch-all, which is the reported defect one layer down: translating an event and never
+    // presenting it leaves the consumer just as blind, minus even the warning.
+    case "input_requested":
+      return dataPart(INPUT_REQUESTED_DATA_PART, {
+        requestId: event.requestId
+      });
+    case "task_progress":
+      return dataPart(TASK_PROGRESS_DATA_PART, {
+        ...event.status !== void 0 ? {
+          status: event.status
+        } : {},
+        ...event.text !== void 0 ? {
+          text: event.text
+        } : {}
+      });
+    case "shell_output":
+      return dataPart(SHELL_OUTPUT_DATA_PART, {
+        event: event.event
+      });
+    default:
+      return null;
+  }
+}
+__name(diagnosticDataPart, "diagnosticDataPart");
 async function* presentUIMessageStream(events, opts) {
   const presenter = new UIMessageStreamPresenter({
     textId: opts.textId
@@ -2123,28 +2468,14 @@ async function* presentUIMessageStream(events, opts) {
         };
         continue;
       }
-      if (event.type === "checkpoint_saved") {
+      const diagnostic = diagnosticDataPart(event);
+      if (diagnostic !== null) {
         yield* presenter.closeBlock();
-        yield {
-          type: "data-checkpoint",
-          data: {
-            checkpointId: event.checkpointId,
-            resumeToken: event.resumeToken,
-            step: event.step
-          },
-          transient: true
-        };
+        yield diagnostic;
         continue;
       }
       if (event.type === "error") {
-        const code = event.code;
-        yield {
-          type: "error",
-          errorText: event.message,
-          ...code !== void 0 ? {
-            errorCode: code
-          } : {}
-        };
+        yield* errorChunks(event.message, event.code);
         break;
       }
       if (event.type === "done") {
@@ -2154,13 +2485,7 @@ async function* presentUIMessageStream(events, opts) {
     }
   } catch (err) {
     const code = err.code;
-    yield {
-      type: "error",
-      errorText: String(err),
-      ...typeof code === "string" ? {
-        errorCode: code
-      } : {}
-    };
+    yield* errorChunks(String(err), typeof code === "string" ? code : void 0);
   }
   yield* presenter.finish(turnMetadata);
 }
@@ -2364,6 +2689,7 @@ function streamAgentUIMessages(compiled, apiKey, input) {
   if (input.cwd !== void 0) overrides.cwd = input.cwd;
   if (input.baseDir !== void 0) overrides.baseDir = input.baseDir;
   if (input.images !== void 0) overrides.images = input.images;
+  if (input.onRunEvent !== void 0) overrides.onRunEvent = input.onRunEvent;
   let source;
   if (!input.hitl || input.hitl.gated.size === 0) {
     const events2 = createSdkAgentStream(compiled, compiled.tools, apiKey, overrides)(input.message, input.sessionId);
@@ -2414,198 +2740,6 @@ function streamAgentUIMessages(compiled, apiKey, input) {
 }
 __name(streamAgentUIMessages, "streamAgentUIMessages");
 
-// src/guardrails/types.ts
-var GuardrailViolationError = class extends Error {
-  static {
-    __name(this, "GuardrailViolationError");
-  }
-  guardName;
-  phase;
-  reason;
-  constructor(guardName, phase, reason) {
-    super(`Guardrail "${guardName}" blocked ${phase}: ${reason}`), this.guardName = guardName, this.phase = phase, this.reason = reason;
-    this.name = "GuardrailViolationError";
-  }
-};
-var CostBudgetExceededError = class extends Error {
-  static {
-    __name(this, "CostBudgetExceededError");
-  }
-  usedTokens;
-  maxTokens;
-  constructor(usedTokens, maxTokens) {
-    super(`Cost budget exceeded: ${usedTokens} > ${maxTokens} tokens`), this.usedTokens = usedTokens, this.maxTokens = maxTokens;
-    this.name = "CostBudgetExceededError";
-  }
-};
-
-// src/guardrails/detectors.ts
-function estimateTokens(text) {
-  return Math.ceil(text.length / 4);
-}
-__name(estimateTokens, "estimateTokens");
-var INJECTION_PHRASES = [
-  "previous instructions",
-  "disregard the above",
-  "you are now dan",
-  "system prompt",
-  "no restrictions",
-  "without restrictions",
-  "no rules",
-  "override your"
-];
-function normalizeForMatch(text) {
-  return text.toLowerCase().replace(/\s+/g, " ");
-}
-__name(normalizeForMatch, "normalizeForMatch");
-function promptInjectionDetector(options = {}) {
-  const phrases = [
-    ...INJECTION_PHRASES,
-    ...(options.extra ?? []).map((p) => p.toLowerCase())
-  ];
-  return {
-    name: "prompt-injection",
-    checkInput(text) {
-      const normalized = normalizeForMatch(text);
-      for (const phrase of phrases) {
-        if (normalized.includes(phrase)) {
-          return {
-            action: "block",
-            reason: `prompt injection phrase matched: "${phrase}"`
-          };
-        }
-      }
-      return {
-        action: "allow"
-      };
-    }
-  };
-}
-__name(promptInjectionDetector, "promptInjectionDetector");
-var CPF = /\b\d{3}\.?\d{3}\.?\d{3}-?\d{2}\b/g;
-var EMAIL = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g;
-var PHONE = /\+?\d[\d\s()-]{7,13}\d/g;
-function piiDetector(options = {}) {
-  const placeholder = options.placeholder ?? "[REDACTED]";
-  return {
-    name: "pii",
-    checkInput(text) {
-      let redacted = text;
-      redacted = redacted.replace(EMAIL, placeholder);
-      redacted = redacted.replace(CPF, placeholder);
-      redacted = redacted.replace(PHONE, placeholder);
-      if (redacted === text) return {
-        action: "allow"
-      };
-      return {
-        action: "redact",
-        text: redacted,
-        reason: "PII detected and redacted"
-      };
-    }
-  };
-}
-__name(piiDetector, "piiDetector");
-var OBFUSCATION_CHARS = /[\u200B-\u200D\uFEFF\u202A-\u202E\u2066-\u2069]/g;
-function unicodeNormalizer() {
-  return {
-    name: "unicode-normalizer",
-    checkInput(text) {
-      const cleaned = text.normalize("NFKC").replace(OBFUSCATION_CHARS, "");
-      if (cleaned === text) return {
-        action: "allow"
-      };
-      return {
-        action: "redact",
-        text: cleaned,
-        reason: "obfuscation characters normalized"
-      };
-    }
-  };
-}
-__name(unicodeNormalizer, "unicodeNormalizer");
-function costGuard(options) {
-  let used = 0;
-  return {
-    name: "cost-guard",
-    // Returns a Promise explicitly (not `async`) so a budget breach REJECTS uniformly — never a
-    // sync throw — safe for direct callers and for the pipeline's `await g.checkInput()`.
-    checkInput(text) {
-      used += estimateTokens(text);
-      if (used > options.maxTokens) {
-        return Promise.reject(new CostBudgetExceededError(used, options.maxTokens));
-      }
-      return Promise.resolve({
-        action: "allow"
-      });
-    }
-  };
-}
-__name(costGuard, "costGuard");
-function outputModeration(options) {
-  return {
-    name: "output-moderation",
-    async checkOutput(text) {
-      const flagged = await options.moderate(text);
-      return flagged ? {
-        action: "block",
-        reason: "output flagged by moderation predicate"
-      } : {
-        action: "allow"
-      };
-    }
-  };
-}
-__name(outputModeration, "outputModeration");
-
-// src/guardrails/pipeline.ts
-async function runInputGuards(text, guards) {
-  let current = text;
-  for (const g of guards) {
-    if (!g.checkInput) continue;
-    const r = await g.checkInput(current);
-    if (r.action === "block") {
-      throw new GuardrailViolationError(g.name, "input", r.reason ?? "blocked");
-    }
-    if (r.action === "redact" && r.text !== void 0) current = r.text;
-  }
-  return current;
-}
-__name(runInputGuards, "runInputGuards");
-async function runOutputGuards(text, guards) {
-  let current = text;
-  for (const g of guards) {
-    if (!g.checkOutput) continue;
-    const r = await g.checkOutput(current);
-    if (r.action === "block") {
-      throw new GuardrailViolationError(g.name, "output", r.reason ?? "blocked");
-    }
-    if (r.action === "redact" && r.text !== void 0) current = r.text;
-  }
-  return current;
-}
-__name(runOutputGuards, "runOutputGuards");
-
-// src/guardrails/stream.ts
-async function* moderateOutputStream(inner, guards, extractText) {
-  const hasOutputGuard = guards.some((g) => g.checkOutput != null);
-  if (!hasOutputGuard) return yield* inner;
-  const buffered = [];
-  let accumulated = "";
-  let step = await inner.next();
-  while (!step.done) {
-    const event = step.value;
-    const text = extractText(event);
-    if (text !== void 0) accumulated += text;
-    buffered.push(event);
-    step = await inner.next();
-  }
-  await runOutputGuards(accumulated, guards);
-  for (const event of buffered) yield event;
-  return step.value;
-}
-__name(moderateOutputStream, "moderateOutputStream");
-
 // src/loop/compaction-strategy.ts
 import { compactTranscript } from "@theokit/sdk/compaction";
 import { z } from "zod";
@@ -3415,13 +3549,13 @@ __name(mcpToolApprovals, "mcpToolApprovals");
 import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 import { TheokitAgentError } from "@theokit/sdk/errors";
-function canalDeAviso(opts) {
-  return opts.onWarn ?? ((aviso) => {
-    process.stderr.write(`[@theokit/agents] ${aviso}
+function warningChannel(opts) {
+  return opts.onWarn ?? ((warning) => {
+    process.stderr.write(`[@theokit/agents] ${warning}
 `);
   });
 }
-__name(canalDeAviso, "canalDeAviso");
+__name(warningChannel, "warningChannel");
 var McpFileError = class extends TheokitAgentError {
   static {
     __name(this, "McpFileError");
@@ -3447,7 +3581,7 @@ function loadMcpJson(cwd, opts = {}) {
   } catch (err) {
     throw new McpFileError(`${path} is not valid JSON: ${descrever(err)}`);
   }
-  return parseMcpJson(parsed, path, canalDeAviso(opts));
+  return parseMcpJson(parsed, path, warningChannel(opts));
 }
 __name(loadMcpJson, "loadMcpJson");
 function parseMcpJson(raw, source, onWarn) {
@@ -3466,7 +3600,7 @@ function parseMcpJson(raw, source, onWarn) {
       onWarn(`${source}: server "${name}" ignorado \u2014 ${motivo}`);
       continue;
     }
-    out[name] = montarEntrada(entryRaw);
+    out[name] = buildEntry(entryRaw);
   }
   return out;
 }
@@ -3514,16 +3648,16 @@ function validarRemoto(entry) {
   return void 0;
 }
 __name(validarRemoto, "validarRemoto");
-function montarEntrada(entry) {
+function buildEntry(entry) {
   if (entry.url !== void 0) {
-    const remoto = {
+    const remote = {
       url: entry.url
     };
-    if (entry.type !== void 0) remoto.type = entry.type;
-    if (entry.headers !== void 0) remoto.headers = entry.headers;
-    if (entry.auth !== void 0) remoto.auth = entry.auth;
-    if (entry.requestTimeoutMs !== void 0) remoto.requestTimeoutMs = entry.requestTimeoutMs;
-    return remoto;
+    if (entry.type !== void 0) remote.type = entry.type;
+    if (entry.headers !== void 0) remote.headers = entry.headers;
+    if (entry.auth !== void 0) remote.auth = entry.auth;
+    if (entry.requestTimeoutMs !== void 0) remote.requestTimeoutMs = entry.requestTimeoutMs;
+    return remote;
   }
   const stdio = {
     command: entry.command
@@ -3533,7 +3667,7 @@ function montarEntrada(entry) {
   if (entry.cwd !== void 0) stdio.cwd = entry.cwd;
   return stdio;
 }
-__name(montarEntrada, "montarEntrada");
+__name(buildEntry, "buildEntry");
 function descrever(err) {
   return err instanceof Error ? err.message : String(err);
 }
@@ -3704,10 +3838,21 @@ export {
   isError,
   isApprovalRequired,
   generateAgentRoutes,
+  GuardrailViolationError,
+  CostBudgetExceededError,
+  estimateTokens,
+  promptInjectionDetector,
+  piiDetector,
+  unicodeNormalizer,
+  costGuard,
+  outputModeration,
+  runInputGuards,
+  runOutputGuards,
+  moderateOutputStream,
   createToolHooksPlugin,
-  translateSdkEvent,
   buildModelSelection,
   reasoningEffortOf,
+  translateSdkEvent,
   createThinkTagExtractor,
   extractThinkTagStream,
   createSdkAgentStream,
@@ -3718,17 +3863,6 @@ export {
   AgentDefinitionError,
   compileAgentModule,
   streamAgentUIMessages,
-  GuardrailViolationError,
-  CostBudgetExceededError,
-  estimateTokens,
-  promptInjectionDetector,
-  piiDetector,
-  unicodeNormalizer,
-  costGuard,
-  outputModeration,
-  runInputGuards,
-  runOutputGuards,
-  moderateOutputStream,
   DEFAULT_KEEP_TOKENS,
   compactionStrategyConfigSchema,
   resolveCompactionStrategy,
@@ -3759,4 +3893,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-UJPG3K26.js.map
+//# sourceMappingURL=chunk-3YPKTOJ6.js.map