@theokit/sdk 2.24.0 → 2.26.0

package/dist/index.cjs

@@ -575,10 +575,10 @@ function buildToolPrompt(prompt) {
 Respond by calling the \`output\` tool with the structured answer that matches the schema.`;
 }
 function setupStructuredOutput(schema, maxRetries) {
-  const z8 = requireZod();
+  const z9 = requireZod();
   const jsonSchema = toJsonSchema(schema, { unrepresentable: "any" });
   return {
-    z: z8,
+    z: z9,
     jsonSchema,
     maxRetries: maxRetries ?? 1,
     initialUsage: { inputTokens: 0, outputTokens: 0 }
@@ -6046,7 +6046,8 @@ function stripSecretsFromOptions(options) {
     local: serializeLocal(options.local),
     cloud: serializeCloud(options.cloud),
     memory: serializeMemory(options.memory),
-    skills: serializeEnabledList(options.skills),
+    // SE22 — a SkillsResolver function isn't serializable; persist only the static form.
+    skills: serializeEnabledList(typeof options.skills === "function" ? void 0 : options.skills),
     // Code-`Plugin` objects are closures and cannot be persisted (like custom
     // tools); only the named-enable settings form is serialized.
     plugins: serializeEnabledList(asPluginsSettings(options.plugins)),
@@ -6354,6 +6355,7 @@ function serializeCloud2(cloud) {
   return result;
 }
 function serializeSkills(skills) {
+  if (typeof skills === "function") return void 0;
   if (skills?.enabled === void 0 || skills.enabled.length === 0) return void 0;
   return { enabled: [...skills.enabled] };
 }
@@ -7734,8 +7736,19 @@ init_errors();
 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(
@@ -7744,6 +7757,14 @@ function rejectFunctionSystemPrompt(options) {
     );
   }
 }
+function rejectFunctionSkills(options) {
+  if (typeof options.skills === "function") {
+    throw new exports.ConfigurationError(
+      "Cloud agents require skills as a static settings object. SkillsResolver functions can't run on PaaS \u2014 resolve to a SkillsSettings object before Agent.create() or move the dynamic logic into a hook rule.",
+      { code: "cloud_incompatible_function_resolver" }
+    );
+  }
+}
 function rejectStdioMcpLocalPaths(options) {
   if (options.mcpServers === void 0) return;
   for (const [name, config] of Object.entries(options.mcpServers)) {
@@ -9570,9 +9591,224 @@ function parseFrontmatterFields(frontmatter) {
   return out;
 }
 
+// src/internal/runtime/skills/discover-skills.ts
+init_errors();
+init_path_guard();
+
+// src/internal/runtime/skills/skill-frontmatter.ts
+init_errors();
+init_yaml_frontmatter();
+function asString(v) {
+  return typeof v === "string" ? v : void 0;
+}
+function toStringFields(raw) {
+  const out = {};
+  for (const [k, v] of Object.entries(raw)) out[k] = asString(v);
+  return out;
+}
+function parseSkillFrontmatter(raw, fallbackName) {
+  const fields = extractAndParseFrontmatter(raw, fallbackName);
+  const name = resolveName(fields, fallbackName);
+  ensureRequiredFields(fields, name);
+  return buildFrontmatter(fields, name);
+}
+function stripSkillFrontmatter(raw) {
+  const match = /^---\s*\n[\s\S]*?\n---\s*\n/.exec(raw);
+  return (match === null ? raw : raw.slice(match[0].length)).trim();
+}
+function extractAndParseFrontmatter(raw, fallbackName) {
+  const match = /^---\s*\n([\s\S]*?)\n---\s*\n/.exec(raw);
+  if (match === null) {
+    throw new exports.ConfigurationError(`Skill ${fallbackName} is missing frontmatter`, {
+      code: "missing_frontmatter"
+    });
+  }
+  const frontmatter = match[1] ?? "";
+  try {
+    return toStringFields(parseSimpleYaml(frontmatter));
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    throw new exports.ConfigurationError(
+      `Skill ${fallbackName} has malformed YAML frontmatter: ${detail}`,
+      { code: "schema_invalid", cause }
+    );
+  }
+}
+function resolveName(fields, fallbackName) {
+  if (hasContent(fields.name)) return fields.name;
+  if (hasContent(fallbackName)) return fallbackName;
+  throw new exports.ConfigurationError("Skill at unknown path is missing required field: name", {
+    code: "schema_invalid"
+  });
+}
+function ensureRequiredFields(fields, name) {
+  if (!hasContent(fields.description)) {
+    throw new exports.ConfigurationError(`Skill ${name} is missing required field: description`, {
+      code: "schema_invalid"
+    });
+  }
+}
+function buildFrontmatter(fields, name) {
+  const description = fields.description;
+  if (description === void 0) {
+    throw new exports.ConfigurationError(`Skill ${name} missing description`, { code: "schema_invalid" });
+  }
+  const result = { name, description };
+  if (hasContent(fields.category)) result.category = fields.category;
+  const deps = parseDependencies(fields.dependencies);
+  if (deps !== void 0) result.dependencies = deps;
+  return result;
+}
+function parseDependencies(raw) {
+  if (!hasContent(raw)) return void 0;
+  const deps = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  return deps.length > 0 ? deps : void 0;
+}
+function hasContent(value) {
+  return value !== void 0 && value.trim().length > 0;
+}
+
+// src/internal/runtime/skills/discover-skills.ts
+async function discoverSkills(dir, options) {
+  let entries;
+  try {
+    entries = await readWorkspaceDir(dir, "skills_read_error", "skills directory");
+  } catch {
+    return [];
+  }
+  const skills = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    let skillDir;
+    try {
+      skillDir = safePathJoin(dir, entry.name);
+      assertNoSymlinkEscape(skillDir, dir);
+    } catch {
+      continue;
+    }
+    const skillPath = path.join(skillDir, "SKILL.md");
+    let raw;
+    try {
+      raw = await promises.readFile(skillPath, "utf8");
+    } catch {
+      continue;
+    }
+    const skill = tryParseSkill(raw, entry.name, skillPath, options);
+    if (skill !== void 0) skills.push(skill);
+  }
+  return skills;
+}
+function tryParseSkill(raw, fallbackName, source, options) {
+  try {
+    const frontmatter = parseSkillFrontmatter(raw, fallbackName);
+    const skill = {
+      name: frontmatter.name,
+      description: frontmatter.description,
+      source
+    };
+    if (frontmatter.category !== void 0) skill.category = frontmatter.category;
+    if (frontmatter.dependencies !== void 0) skill.dependencies = frontmatter.dependencies;
+    return skill;
+  } catch (cause) {
+    if (cause instanceof exports.ConfigurationError) {
+      options?.onInvalidSkill?.({
+        name: fallbackName,
+        source,
+        code: cause.code ?? "unknown",
+        message: cause.message
+      });
+      return void 0;
+    }
+    throw cause;
+  }
+}
+
+// src/internal/runtime/skills/skills-manager.ts
+var SkillsManager = class {
+  constructor(cwd, _enabled, settingSourcesIncludeProject, skillsDir, inline) {
+    this.cwd = cwd;
+    this.settingSourcesIncludeProject = settingSourcesIncludeProject;
+    this.skillsDir = skillsDir;
+    this.inline = inline;
+  }
+  cwd;
+  settingSourcesIncludeProject;
+  skillsDir;
+  inline;
+  skills = [];
+  async initialize() {
+    if (!this.settingSourcesIncludeProject) {
+      this.skills = this.mergeInline([]);
+      return;
+    }
+    await this.refresh();
+  }
+  async refresh() {
+    const skillsRoot = this.skillsDir ?? path.join(this.cwd, ".theokit", "skills");
+    const discovered = await discoverSkills(skillsRoot, {
+      onInvalidSkill: (info) => {
+        process.stderr.write(
+          `[theokit-sdk] skill ${info.name} skipped (${info.code}): ${info.message}
+`
+        );
+      }
+    });
+    this.skills = this.mergeInline(discovered);
+  }
+  /** M22 — merge inline skills over discovered ones; inline wins on a name conflict. */
+  mergeInline(discovered) {
+    if (this.inline === void 0 || this.inline.length === 0) return discovered;
+    const inlineNames = new Set(this.inline.map((s) => s.name));
+    return [...discovered.filter((s) => !inlineNames.has(s.name)), ...this.inline];
+  }
+  list() {
+    return Promise.resolve(this.skills);
+  }
+  /**
+   * SE20 — resolve a skill by name INCLUDING its body. Inline (`createSkill`)
+   * skills carry `instructions` on the object; filesystem skills read the body
+   * from their `source` SKILL.md (frontmatter stripped). `undefined` when no
+   * enabled skill matches (malformed skills were already excluded at discovery).
+   */
+  async get(name) {
+    const skill = this.skills.find((s) => s.name === name);
+    if (skill === void 0) return void 0;
+    const instructions = typeof skill.instructions === "string" ? skill.instructions : stripSkillFrontmatter(await promises.readFile(skill.source, "utf8"));
+    const references = skill.references;
+    return {
+      name: skill.name,
+      description: skill.description,
+      instructions,
+      ...references !== void 0 ? { references } : {}
+    };
+  }
+};
+
 // src/internal/runtime/system-prompt/local-assembly.ts
-async function buildSystemPromptContext(inputs, userText, memoryFacts) {
-  const skills = inputs.skillsManager !== void 0 ? await inputs.skillsManager.list() : [];
+async function resolveSendSkills(inputs, userText, memoryFacts) {
+  const skills = inputs.options.skills;
+  if (typeof skills !== "function") {
+    return { manager: inputs.skillsManager, autoInject: skills?.autoInject ?? true };
+  }
+  const settings = await skills({
+    agentId: inputs.agentId,
+    cwd: inputs.workspaceCwd,
+    model: inputs.model,
+    userMessage: userText,
+    memory: memoryFacts.map((fact) => ({ text: fact.text }))
+  });
+  const manager = new SkillsManager(
+    inputs.workspaceCwd,
+    settings.enabled,
+    inputs.settingSourcesIncludeProject,
+    settings.skillsDir,
+    settings.inline
+  );
+  await manager.initialize();
+  return { manager, autoInject: settings.autoInject ?? true };
+}
+async function buildSystemPromptContext(inputs, userText, memoryFacts, manager = inputs.skillsManager) {
+  const skills = manager !== void 0 ? await manager.list() : [];
   return {
     agentId: inputs.agentId,
     cwd: inputs.workspaceCwd,
@@ -9583,10 +9819,11 @@ async function buildSystemPromptContext(inputs, userText, memoryFacts) {
   };
 }
 async function buildAssemblyContext(inputs, userText, baseSystemPrompt, memoryFacts, activeMemorySummary) {
-  const baseCtx = await buildSystemPromptContext(inputs, userText, memoryFacts);
+  const resolved = await resolveSendSkills(inputs, userText, memoryFacts);
+  const baseCtx = await buildSystemPromptContext(inputs, userText, memoryFacts, resolved.manager);
   const assemblyCtx = {
     ...baseCtx,
-    skillsAutoInject: inputs.options.skills?.autoInject ?? true,
+    skillsAutoInject: resolved.autoInject,
     memoryAutoInject: inputs.options.memory?.autoInject ?? true
   };
   if (baseSystemPrompt !== void 0) assemblyCtx.baseSystemPrompt = baseSystemPrompt;
@@ -10839,177 +11076,6 @@ async function loadPluginManifestFromMarkdown(pluginsRoot, folderName) {
   return metadata;
 }
 
-// src/internal/runtime/skills/discover-skills.ts
-init_errors();
-init_path_guard();
-
-// src/internal/runtime/skills/skill-frontmatter.ts
-init_errors();
-init_yaml_frontmatter();
-function asString(v) {
-  return typeof v === "string" ? v : void 0;
-}
-function toStringFields(raw) {
-  const out = {};
-  for (const [k, v] of Object.entries(raw)) out[k] = asString(v);
-  return out;
-}
-function parseSkillFrontmatter(raw, fallbackName) {
-  const fields = extractAndParseFrontmatter(raw, fallbackName);
-  const name = resolveName(fields, fallbackName);
-  ensureRequiredFields(fields, name);
-  return buildFrontmatter(fields, name);
-}
-function extractAndParseFrontmatter(raw, fallbackName) {
-  const match = /^---\s*\n([\s\S]*?)\n---\s*\n/.exec(raw);
-  if (match === null) {
-    throw new exports.ConfigurationError(`Skill ${fallbackName} is missing frontmatter`, {
-      code: "missing_frontmatter"
-    });
-  }
-  const frontmatter = match[1] ?? "";
-  try {
-    return toStringFields(parseSimpleYaml(frontmatter));
-  } catch (cause) {
-    const detail = cause instanceof Error ? cause.message : String(cause);
-    throw new exports.ConfigurationError(
-      `Skill ${fallbackName} has malformed YAML frontmatter: ${detail}`,
-      { code: "schema_invalid", cause }
-    );
-  }
-}
-function resolveName(fields, fallbackName) {
-  if (hasContent(fields.name)) return fields.name;
-  if (hasContent(fallbackName)) return fallbackName;
-  throw new exports.ConfigurationError("Skill at unknown path is missing required field: name", {
-    code: "schema_invalid"
-  });
-}
-function ensureRequiredFields(fields, name) {
-  if (!hasContent(fields.description)) {
-    throw new exports.ConfigurationError(`Skill ${name} is missing required field: description`, {
-      code: "schema_invalid"
-    });
-  }
-}
-function buildFrontmatter(fields, name) {
-  const description = fields.description;
-  if (description === void 0) {
-    throw new exports.ConfigurationError(`Skill ${name} missing description`, { code: "schema_invalid" });
-  }
-  const result = { name, description };
-  if (hasContent(fields.category)) result.category = fields.category;
-  const deps = parseDependencies(fields.dependencies);
-  if (deps !== void 0) result.dependencies = deps;
-  return result;
-}
-function parseDependencies(raw) {
-  if (!hasContent(raw)) return void 0;
-  const deps = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-  return deps.length > 0 ? deps : void 0;
-}
-function hasContent(value) {
-  return value !== void 0 && value.trim().length > 0;
-}
-
-// src/internal/runtime/skills/discover-skills.ts
-async function discoverSkills(dir, options) {
-  let entries;
-  try {
-    entries = await readWorkspaceDir(dir, "skills_read_error", "skills directory");
-  } catch {
-    return [];
-  }
-  const skills = [];
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    let skillDir;
-    try {
-      skillDir = safePathJoin(dir, entry.name);
-      assertNoSymlinkEscape(skillDir, dir);
-    } catch {
-      continue;
-    }
-    const skillPath = path.join(skillDir, "SKILL.md");
-    let raw;
-    try {
-      raw = await promises.readFile(skillPath, "utf8");
-    } catch {
-      continue;
-    }
-    const skill = tryParseSkill(raw, entry.name, skillPath, options);
-    if (skill !== void 0) skills.push(skill);
-  }
-  return skills;
-}
-function tryParseSkill(raw, fallbackName, source, options) {
-  try {
-    const frontmatter = parseSkillFrontmatter(raw, fallbackName);
-    const skill = {
-      name: frontmatter.name,
-      description: frontmatter.description,
-      source
-    };
-    if (frontmatter.category !== void 0) skill.category = frontmatter.category;
-    if (frontmatter.dependencies !== void 0) skill.dependencies = frontmatter.dependencies;
-    return skill;
-  } catch (cause) {
-    if (cause instanceof exports.ConfigurationError) {
-      options?.onInvalidSkill?.({
-        name: fallbackName,
-        source,
-        code: cause.code ?? "unknown",
-        message: cause.message
-      });
-      return void 0;
-    }
-    throw cause;
-  }
-}
-
-// src/internal/runtime/skills/skills-manager.ts
-var SkillsManager = class {
-  constructor(cwd, _enabled, settingSourcesIncludeProject, skillsDir, inline) {
-    this.cwd = cwd;
-    this.settingSourcesIncludeProject = settingSourcesIncludeProject;
-    this.skillsDir = skillsDir;
-    this.inline = inline;
-  }
-  cwd;
-  settingSourcesIncludeProject;
-  skillsDir;
-  inline;
-  skills = [];
-  async initialize() {
-    if (!this.settingSourcesIncludeProject) {
-      this.skills = this.mergeInline([]);
-      return;
-    }
-    await this.refresh();
-  }
-  async refresh() {
-    const skillsRoot = this.skillsDir ?? path.join(this.cwd, ".theokit", "skills");
-    const discovered = await discoverSkills(skillsRoot, {
-      onInvalidSkill: (info) => {
-        process.stderr.write(
-          `[theokit-sdk] skill ${info.name} skipped (${info.code}): ${info.message}
-`
-        );
-      }
-    });
-    this.skills = this.mergeInline(discovered);
-  }
-  /** M22 — merge inline skills over discovered ones; inline wins on a name conflict. */
-  mergeInline(discovered) {
-    if (this.inline === void 0 || this.inline.length === 0) return discovered;
-    const inlineNames = new Set(this.inline.map((s) => s.name));
-    return [...discovered.filter((s) => !inlineNames.has(s.name)), ...this.inline];
-  }
-  list() {
-    return Promise.resolve(this.skills);
-  }
-};
-
 // src/internal/runtime/local-agent/local-agent-bootstrap.ts
 function registerLocalAgent(args) {
   registerAgent({
@@ -11045,16 +11111,23 @@ function bootstrapSubmanagers(args) {
     );
   }
   if (args.options.skills !== void 0 || args.settingSourcesIncludeProject) {
+    const staticSkills = typeof args.options.skills === "function" ? void 0 : args.options.skills;
     out.skillsManager = new SkillsManager(
       args.workspaceCwd,
-      args.options.skills?.enabled,
+      staticSkills?.enabled,
       args.settingSourcesIncludeProject,
       // M22 — custom skills directory + inline (code-defined) skills.
-      args.options.skills?.skillsDir,
-      args.options.skills?.inline
+      staticSkills?.skillsDir,
+      staticSkills?.inline
     );
     const localSkills = out.skillsManager;
-    out.skills = { list: () => localSkills.list() };
+    out.skills = {
+      // Project to the public shape (name + description only). Inline skills carry
+      // their body + references on the object; `list()` must never leak them —
+      // the body is reachable exclusively through `get()`.
+      list: async () => (await localSkills.list()).map((s) => ({ name: s.name, description: s.description })),
+      get: (name) => localSkills.get(name)
+    };
   }
   if (args.options.plugins !== void 0 || args.settingSourcesIncludePlugins) {
     out.pluginsManager = new PluginsManager(
@@ -17614,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) {
@@ -17661,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,
@@ -17677,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
   });
@@ -17715,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
   });
 }
@@ -17968,7 +18214,7 @@ var LocalAgent = class {
   }
   // biome-ignore format: G8 budget — thin accessor for the assembly inputs.
   assemblyInputs() {
-    return { agentId: this.agentId, workspaceCwd: this.workspaceCwd, model: this.model, options: this.options, context: this.context, skillsManager: this.skillsManager, systemPromptPipeline: this.systemPromptPipeline };
+    return { agentId: this.agentId, workspaceCwd: this.workspaceCwd, model: this.model, options: this.options, context: this.context, skillsManager: this.skillsManager, settingSourcesIncludeProject: this.settingSourcesIncludeProject, systemPromptPipeline: this.systemPromptPipeline };
   }
   async resolveSystemPrompt(userText, options, memoryFacts) {
     const base = await resolveSystemPromptForSend(
@@ -19078,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.");
@@ -19088,7 +19376,8 @@ function createSkill(spec) {
     source: `inline://${spec.name}`,
     instructions: spec.instructions,
     ...spec.category !== void 0 ? { category: spec.category } : {},
-    ...spec.dependencies !== void 0 ? { dependencies: spec.dependencies } : {}
+    ...spec.dependencies !== void 0 ? { dependencies: spec.dependencies } : {},
+    ...spec.references !== void 0 ? { references: spec.references } : {}
   };
 }
 
@@ -19515,6 +19804,46 @@ function defineProvider(profile, opts) {
   };
 }
 
+// src/define-skill-read-tool.ts
+init_to_json_schema();
+var SkillReadInputSchema = zod.z.object({
+  name: zod.z.string().min(1, "skill_read: `name` is required.")
+});
+function renderSkill(skill) {
+  const parts = [`# Skill: ${skill.name}`, "", skill.instructions];
+  const refs = skill.references;
+  if (refs !== void 0 && Object.keys(refs).length > 0) {
+    parts.push("", "## References");
+    for (const [file, content] of Object.entries(refs)) {
+      parts.push("", `### ${file}`, content);
+    }
+  }
+  return parts.join("\n");
+}
+function defineSkillReadTool(skills) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const skill of skills) {
+    if (seen.has(skill.name)) {
+      throw new Error(`defineSkillReadTool: duplicate skill name "${skill.name}".`);
+    }
+    seen.add(skill.name);
+  }
+  return {
+    name: "skill_read",
+    description: "Read a skill's full instructions (and any bundled reference documents) by its name. Use this to load the body of a skill listed in the <skills> block before acting on it.",
+    inputSchema: toJsonSchema(SkillReadInputSchema),
+    handler: (input) => {
+      const { name } = SkillReadInputSchema.parse(input);
+      const skill = skills.find((s) => s.name === name);
+      if (skill === void 0) {
+        const available = skills.map((s) => s.name).join(", ");
+        return `Skill "${name}" not found. Available skills: ${available.length > 0 ? available : "(none)"}.`;
+      }
+      return renderSkill(skill);
+    }
+  };
+}
+
 // src/define-tool.ts
 init_to_json_schema();
 function shapeToolResult(spec, out) {
@@ -19718,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;
@@ -19726,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("");
@@ -21438,10 +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;