@theokit/sdk 2.25.0 → 2.26.0

package/dist/index.cjs

@@ -7737,8 +7737,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 exports.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 exports.ConfigurationError(
@@ -17677,6 +17687,145 @@ function ponyfillAny(signals) {
   return ctrl.signal;
 }
 
+// src/internal/runtime/processors/run-processors.ts
+var ProcessorAbort = class {
+  constructor(processorId, reason) {
+    this.processorId = processorId;
+    this.reason = reason;
+  }
+  processorId;
+  reason;
+};
+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");
+}
+
+// src/internal/runtime/processors/tripwire-run.ts
+var SUPPORTED = /* @__PURE__ */ new Set([
+  "stream",
+  "wait",
+  "cancel",
+  "conversation"
+]);
+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;
+}
+
+// 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);
+    }
+  });
+}
+
 // src/internal/runtime/local-agent/local-agent-memory-hooks.ts
 var DEFAULT_MAX_RECALL_BYTES = 16e3;
 async function applyPreUserSendHook(args) {
@@ -17724,11 +17873,38 @@ function wrapRunWithPostReplyHook(args) {
 }
 
 // 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 exports.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,
@@ -17740,7 +17916,7 @@ async function executeSendLocked(inputs, message, options) {
     pluginManager: inputs.pluginManagerCode,
     agentId: inputs.agentId,
     options: inputs.options,
-    original: message,
+    original: effectiveMessage,
     userText,
     sendOptions: options
   });
@@ -17778,11 +17954,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
   });
 }
@@ -19141,6 +19324,48 @@ var Budget = class {
   }
 };
 
+// src/built-in-processors.ts
+var CHARS_PER_TOKEN = 4;
+function estimateTokens(text) {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+var CONTROL_CHARS = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
+function createUnicodeNormalizer(opts = {}) {
+  const stripControlChars = opts.stripControlChars ?? false;
+  const collapseWhitespace = opts.collapseWhitespace ?? false;
+  return {
+    id: "unicode-normalizer",
+    processInput(ctx) {
+      let s = ctx.message.normalize("NFC");
+      if (stripControlChars) s = s.replace(CONTROL_CHARS, "");
+      if (collapseWhitespace) {
+        s = s.replace(/[^\S\n]+/g, " ").replace(/ *\n */g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+      }
+      return s;
+    }
+  };
+}
+function createTokenLimiter(opts) {
+  if (!Number.isInteger(opts.limit) || opts.limit <= 0) {
+    throw new Error("createTokenLimiter: `limit` must be a positive integer.");
+  }
+  const limit = opts.limit;
+  const strategy = opts.strategy ?? "truncate";
+  const cap2 = (text, controls) => {
+    const estimated = estimateTokens(text);
+    if (estimated <= limit) return text;
+    if (strategy === "block") {
+      controls.abort(`exceeds token limit ${limit} (~${estimated} estimated)`);
+    }
+    return [...text].slice(0, limit * CHARS_PER_TOKEN).join("");
+  };
+  return {
+    id: "token-limiter",
+    processInput: (ctx) => cap2(ctx.message, ctx),
+    processOutput: (ctx) => cap2(ctx.text, ctx)
+  };
+}
+
 // src/create-skill.ts
 function createSkill(spec) {
   if (!spec.name) throw new Error("createSkill: `name` is required.");
@@ -19822,7 +20047,7 @@ function createCounterBudgetTracker(options = {}) {
 }
 
 // src/internal/runtime/context/replay-history.ts
-var CHARS_PER_TOKEN = 4;
+var CHARS_PER_TOKEN2 = 4;
 var DEFAULT_RESERVE_TOKENS = 8e3;
 function finiteOr(value, fallback) {
   return Number.isFinite(value) ? value : fallback;
@@ -19830,7 +20055,7 @@ function finiteOr(value, fallback) {
 function charBudget(options) {
   const window = finiteOr(options.contextWindowTokens, 0);
   const reserve = finiteOr(options.reserveTokens ?? DEFAULT_RESERVE_TOKENS, DEFAULT_RESERVE_TOKENS);
-  return Math.max(0, window - reserve) * CHARS_PER_TOKEN;
+  return Math.max(0, window - reserve) * CHARS_PER_TOKEN2;
 }
 function assistantText2(event) {
   return event.message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
@@ -21542,11 +21767,14 @@ exports.createPermissionPlugin = createPermissionPlugin;
 exports.createSessionManager = createSessionManager;
 exports.createSkill = createSkill;
 exports.createSquad = createSquad;
+exports.createTokenLimiter = createTokenLimiter;
+exports.createUnicodeNormalizer = createUnicodeNormalizer;
 exports.definePlugin = definePlugin;
 exports.defineProvider = defineProvider;
 exports.defineSkillReadTool = defineSkillReadTool;
 exports.defineTool = defineTool;
 exports.emitRunEvent = emitRunEvent;
+exports.estimateTokens = estimateTokens;
 exports.extractRawId = extractRawId;
 exports.getPricingEntry = getPricingEntry;
 exports.inferApiMode = inferApiMode;