@cognipeer/agent-sdk 0.1.1 → 0.1.2

package/dist/index.cjs

@@ -1,60 +1,136 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+'use strict';
 
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  applyTokenLimits: () => applyTokenLimits,
-  buildSystemPrompt: () => buildSystemPrompt,
-  bumpStep: () => bumpStep,
-  countApproxTokens: () => countApproxTokens,
-  createAgent: () => createAgent,
-  createAgentNode: () => createAgentNode,
-  createContextSummarizeNode: () => createContextSummarizeNode,
-  createContextTools: () => createContextTools,
-  createDebugSession: () => createDebugSession,
-  createResolverNode: () => createResolverNode,
-  createSmartAgent: () => createSmartAgent,
-  createSmartTool: () => createSmartTool,
-  createTool: () => createTool,
-  createToolLimitFinalizeNode: () => createToolLimitFinalizeNode,
-  createToolsNode: () => createToolsNode,
-  formatMarkdown: () => formatMarkdown,
-  fromLangchainModel: () => fromLangchainModel,
-  getModelName: () => getModelName,
-  isSmartModel: () => isSmartModel,
-  resolveLogsBaseDir: () => resolveLogsBaseDir,
-  serializeAgentTools: () => serializeAgentTools,
-  withTools: () => withTools,
-  writeStepMarkdown: () => writeStepMarkdown
-});
-module.exports = __toCommonJS(index_exports);
+var zod = require('zod');
+var module$1 = require('module');
+var fs = require('fs');
+var path = require('path');
+var buffer = require('buffer');
+var nanoid = require('nanoid');
+var AjvModule = require('ajv');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var fs__default = /*#__PURE__*/_interopDefault(fs);
+var path__default = /*#__PURE__*/_interopDefault(path);
+var AjvModule__default = /*#__PURE__*/_interopDefault(AjvModule);
+
+// src/adapters/langchain.ts
+var moduleName = "@langchain/core/tools";
+var cachedToolFactory;
+var cachedHasAttemptedFactory = false;
+var requireFn = null;
+try {
+  requireFn = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
+} catch {
+  requireFn = null;
+}
+function getExecutor(tool) {
+  if (typeof tool.invoke === "function") return (input) => tool.invoke(input);
+  if (typeof tool.call === "function") return (input) => tool.call(input);
+  if (typeof tool.func === "function") return (input) => tool.func(input);
+  if (typeof tool.run === "function") return (input) => tool.run(input);
+  if (typeof tool === "function") {
+    return tool;
+  }
+  throw new Error(`Tool ${tool?.name ?? "<unnamed>"} is not invokable`);
+}
+function loadLangchainToolFactory() {
+  if (cachedHasAttemptedFactory) return cachedToolFactory ?? null;
+  cachedHasAttemptedFactory = true;
+  cachedToolFactory = null;
+  if (!requireFn) return null;
+  try {
+    const mod = requireFn(moduleName);
+    const factory = typeof mod?.tool === "function" ? mod.tool : void 0;
+    if (typeof factory === "function") {
+      cachedToolFactory = factory;
+    }
+  } catch {
+    cachedToolFactory = null;
+  }
+  return cachedToolFactory ?? null;
+}
+function ensureSchema(candidate) {
+  if (!candidate) return zod.z.any();
+  if (candidate instanceof zod.z.ZodType) return candidate;
+  return candidate;
+}
+function toLangchainTools(tools) {
+  const factory = loadLangchainToolFactory();
+  if (!factory) return tools;
+  return tools.map((tool) => {
+    if (!tool) return tool;
+    if (tool.__lcTool) return tool.__lcTool;
+    const executor = getExecutor(tool);
+    try {
+      const lcTool = factory(async (input) => executor(input), {
+        name: tool.name,
+        description: tool.description,
+        schema: ensureSchema(tool.schema)
+      });
+      tool.__lcTool = lcTool;
+      return lcTool;
+    } catch {
+      return tool;
+    }
+  });
+}
+function fromLangchainTools(tools) {
+  return tools.map((tool) => {
+    if (!tool) return tool;
+    if (tool.__source === "smart") return tool;
+    if (typeof tool === "function" && !tool.name) {
+      const wrapped2 = createSimpleTool({
+        name: "anonymous_tool",
+        description: void 0,
+        schema: zod.z.any(),
+        executor: tool
+      });
+      wrapped2.__source = "langchain";
+      wrapped2.__lc = tool;
+      return wrapped2;
+    }
+    const name = tool.name || tool?.lc_kwargs?.name || tool?.config?.name || "tool";
+    const description = tool.description || tool?.lc_kwargs?.description;
+    const schema = tool.schema || tool?.lc_kwargs?.schema || zod.z.any();
+    const executor = (input) => {
+      if (typeof tool.invoke === "function") return tool.invoke(input);
+      if (typeof tool.call === "function") return tool.call(input);
+      if (typeof tool._call === "function") return tool._call(input);
+      if (typeof tool.run === "function") return tool.run(input);
+      if (typeof tool.func === "function") return tool.func(input);
+      if (typeof tool === "function") return tool(input);
+      throw new Error(`LangChain tool ${name} is not invokable`);
+    };
+    const wrapped = createSimpleTool({
+      name,
+      description,
+      schema,
+      executor
+    });
+    wrapped.__source = "langchain";
+    wrapped.__lc = tool;
+    return wrapped;
+  });
+}
+function createSimpleTool({
+  name,
+  description,
+  schema,
+  executor
+}) {
+  const invoke = async (input) => executor(input);
+  return {
+    name,
+    description,
+    schema,
+    invoke,
+    call: invoke,
+    run: invoke,
+    func: invoke
+  };
+}
 
 // src/model.ts
 function isSmartModel(m) {
@@ -115,8 +191,13 @@ function fromLangchainModel(lcModel) {
       return { role: "assistant", content: String(response ?? "") };
     },
     bindTools: (tools) => {
+      const lcReady = toLangchainTools(tools);
       if (typeof lcModel.bindTools === "function") {
-        const bound = lcModel.bindTools(tools);
+        const bound = lcModel.bindTools(lcReady);
+        return fromLangchainModel(bound);
+      }
+      if (typeof lcModel.bind === "function") {
+        const bound = lcModel.bind({ tools: lcReady });
         return fromLangchainModel(bound);
       }
       return adapted;
@@ -128,28 +209,38 @@ function fromLangchainModel(lcModel) {
 }
 
 // src/tool.ts
-var import_tools = require("@langchain/core/tools");
-function createSmartTool({
+function createTool({
   name,
   description,
   schema,
-  func
+  func,
+  needsApproval,
+  approvalPrompt,
+  approvalDefaults
 }) {
-  return (0, import_tools.tool)(async (input) => {
-    return func(input);
-  }, {
+  const execute = async (input) => func(input);
+  const toolRecord = {
     name,
     description,
-    schema
-  });
-}
-function createTool({
-  name,
-  description,
-  schema,
-  func
-}) {
-  return createSmartTool({ name, description, schema, func });
+    schema,
+    // Our runtime prefers invoke but fallback helpers keep compatibility with LC-style tools.
+    invoke: execute,
+    call: execute,
+    run: execute,
+    func: execute
+  };
+  if (typeof needsApproval === "boolean") {
+    toolRecord.needsApproval = needsApproval;
+  }
+  if (approvalPrompt !== void 0) {
+    toolRecord.approvalPrompt = approvalPrompt;
+  }
+  if (approvalDefaults !== void 0) {
+    toolRecord.approvalDefaults = approvalDefaults;
+  }
+  toolRecord.__source = toolRecord.__source || "smart";
+  toolRecord.__impl = func;
+  return toolRecord;
 }
 
 // src/prompts.ts
@@ -181,8 +272,12 @@ Rules:
   ].filter(Boolean).join("\n");
 }
 
-// src/agent.ts
-var import_zod = require("zod");
+// src/types.ts
+var GuardrailPhase = /* @__PURE__ */ ((GuardrailPhase2) => {
+  GuardrailPhase2["Request"] = "request";
+  GuardrailPhase2["Response"] = "response";
+  return GuardrailPhase2;
+})(GuardrailPhase || {});
 
 // src/nodes/resolver.ts
 function createResolverNode() {
@@ -196,6 +291,7 @@ function createResolverNode() {
       toolCache: state.toolCache || {},
       toolHistory: state.toolHistory || [],
       toolHistoryArchived: state.toolHistoryArchived || [],
+      pendingApprovals: state.pendingApprovals || [],
       plan: state.plan || null,
       planVersion: state.planVersion || 0
     };
@@ -247,157 +343,744 @@ function safe(v) {
   const n = Number(v);
   return Number.isFinite(n) && n >= 0 ? n : 0;
 }
-
-// src/utils/debugLogger.ts
-var import_node_fs = __toESM(require("fs"), 1);
-var import_node_path = __toESM(require("path"), 1);
-function ensureDir(p) {
-  if (!import_node_fs.default.existsSync(p)) import_node_fs.default.mkdirSync(p, { recursive: true });
+var DEFAULT_COGNIPEER_URL = "https://api.cognipeer.com/v1/client/tracing/sessions";
+function fileSink(path2) {
+  return { type: "file", path: path2 };
+}
+function customSink(handler) {
+  if (typeof handler === "function") {
+    return { type: "custom", onEvent: handler };
+  }
+  return {
+    type: "custom",
+    onEvent: typeof handler?.onEvent === "function" ? handler.onEvent : void 0,
+    onSession: typeof handler?.onSession === "function" ? handler.onSession : void 0
+  };
+}
+function cognipeerSink(first, second) {
+  if (second === void 0) {
+    const apiKey = first ?? "";
+    return { type: "cognipeer", apiKey };
+  }
+  const url = typeof first === "string" && first.trim().length > 0 ? first.trim() : void 0;
+  return { type: "cognipeer", url, apiKey: second };
+}
+function httpSink(url, headers) {
+  return { type: "http", url, headers };
 }
-function resolveLogsBaseDir(customPath) {
+function resolveLogsBaseDir(customPath, ensureDirectory = true) {
   const root = process.cwd();
-  const base = customPath && customPath.trim().length > 0 ? customPath : import_node_path.default.join(root, "logs");
-  ensureDir(base);
+  const base = customPath && customPath.trim().length > 0 ? customPath : path__default.default.join(root, "logs");
+  if (ensureDirectory) {
+    ensureDir(base);
+  }
   return base;
 }
-function createDebugSession(opts) {
-  const dbg = opts.debug;
-  if (!dbg?.enabled) return void 0;
-  const baseDir = resolveLogsBaseDir(dbg.path);
-  const sessionId = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const sessionDir = import_node_path.default.join(baseDir, sessionId);
-  if (!dbg.callback) ensureDir(sessionDir);
-  return { sessionId, baseDir, sessionDir, stepIndex: 0, callback: dbg.callback };
+function coerceToString(value) {
+  if (value == null) return void 0;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : void 0;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (typeof value === "function" && value.length === 0) {
+    try {
+      return coerceToString(value());
+    } catch {
+      return void 0;
+    }
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const normalized = coerceToString(item);
+      if (normalized) return normalized;
+    }
+    return void 0;
+  }
+  return void 0;
 }
-function bumpStep(session) {
-  session.stepIndex += 1;
-  return session.stepIndex - 1;
+function firstNonEmptyString(...candidates) {
+  for (const candidate of candidates) {
+    const normalized = coerceToString(candidate);
+    if (normalized) return normalized;
+  }
+  return void 0;
 }
 function getModelName(model) {
-  return model?.model ?? model?.modelName ?? model?.options?.model ?? model?.lc_alias ?? model?.constructor?.name ?? void 0;
+  if (!model) return void 0;
+  const maybeLc = model?._lc;
+  const direct = firstNonEmptyString(
+    model?.model,
+    model?.options?.model,
+    model?.params?.model,
+    model?.config?.model,
+    model?.configuration?.model,
+    model?.metadata?.model,
+    model?.lc_kwargs?.model,
+    maybeLc?.model,
+    maybeLc?.options?.model,
+    maybeLc?.params?.model,
+    maybeLc?.config?.model,
+    maybeLc?.configuration?.model,
+    maybeLc?.metadata?.model,
+    maybeLc?.lc_kwargs?.model,
+    model?.metadata?.modelName,
+    maybeLc?.metadata?.modelName,
+    model?.modelName,
+    maybeLc?.modelName,
+    model?.lc_alias,
+    model?.model_id,
+    model?.id,
+    maybeLc?.model_id,
+    maybeLc?.id,
+    model?._model,
+    model?._modelName,
+    model?.__model
+  );
+  if (direct) return direct;
+  const maybeClient = model?.client || model?.api || model?.service;
+  const clientValue = firstNonEmptyString(
+    maybeClient?.model,
+    maybeClient?.config?.model,
+    maybeClient?.options?.model,
+    maybeClient?.default?.model
+  );
+  if (clientValue) return clientValue;
+  const fnNames = firstNonEmptyString(model?._modelId, model?._llmType, maybeLc?._modelId, maybeLc?._llmType, model?.constructor?.name);
+  return fnNames;
 }
-function serializeAgentTools(tools) {
-  return (tools || []).map((t) => {
-    const name = t.name ?? t.lc_alias ?? t.constructor?.name ?? "tool";
-    const description = t.description ?? t.lc_description ?? void 0;
-    const params = t.schema ?? t.lc_kwargs?.schema ?? t.argsSchema ?? void 0;
-    return {
-      function: {
-        name,
-        description,
-        parameters: params
-      },
-      type: "function"
-    };
-  });
+function getProviderName(model) {
+  if (!model) return void 0;
+  const direct = firstNonEmptyString(
+    model?.provider,
+    model?.options?.provider,
+    model?.params?.provider,
+    model?.config?.provider,
+    model?.configuration?.provider,
+    model?.metadata?.provider,
+    model?.lc_kwargs?.provider,
+    model?.lc_alias,
+    model?.__provider
+  );
+  if (direct) return direct;
+  const maybeLc = model?._lc;
+  const lcValue = maybeLc ? firstNonEmptyString(
+    maybeLc?.provider,
+    maybeLc?.options?.provider,
+    maybeLc?.config?.provider,
+    maybeLc?.configuration?.provider,
+    maybeLc?.metadata?.provider,
+    maybeLc?.lc_kwargs?.provider,
+    maybeLc?.client?.config?.provider
+  ) : void 0;
+  if (lcValue) return lcValue;
+  const maybeClient = model?.client || model?.api || model?.service;
+  return firstNonEmptyString(
+    maybeClient?.provider,
+    maybeClient?.config?.provider,
+    maybeClient?.options?.provider,
+    maybeClient?.metadata?.provider
+  );
 }
-function formatTools(tools) {
-  try {
-    return JSON.stringify(
-      tools.map((t) => ({
-        function: t?.function ? {
-          name: t.function.name,
-          description: t.function.description,
-          parameters: t.function.parameters
-        } : void 0,
-        type: t?.type
-      })),
-      null,
-      4
+function inferModelFromMessages(messageList) {
+  if (!Array.isArray(messageList)) return void 0;
+  for (let i = messageList.length - 1; i >= 0; i -= 1) {
+    const message = messageList[i];
+    if (!message) continue;
+    const candidate = firstNonEmptyString(
+      message?.metadata?.model,
+      message?.metadata?.modelName,
+      message?.metadata?.modelNames,
+      message?.metadata?.model_id,
+      message?.response_metadata?.model,
+      message?.response_metadata?.modelName,
+      message?.response_metadata?.modelNames,
+      message?.response_metadata?.model_id,
+      message?.usage_metadata?.model,
+      message?.model,
+      message?.modelName,
+      message?.model_id,
+      message?.additional_kwargs?.model,
+      message?.additional_kwargs?.modelName,
+      message?.info?.model,
+      message?.annotations?.model
     );
-  } catch {
-    return "[]";
-  }
-}
-function formatMessages(messages) {
-  const lines = [];
-  const push = (s = "") => lines.push(s);
-  for (const m of messages) {
-    const anyM = m;
-    const role = anyM.role || (typeof anyM.getType === "function" ? anyM.getType() : void 0);
-    if (role === "system") {
-      push("### System\n");
-      push(String(anyM.content));
-      push("");
-    } else if (role === "user" || role === "human") {
-      push("### User\n");
-      push(typeof anyM.content === "string" ? anyM.content : JSON.stringify(anyM.content, null, 2));
-      push("");
-    } else if (role === "assistant" || role === "ai") {
-      push("### AI\n");
-      const toolCalls = Array.isArray(anyM.tool_calls) ? anyM.tool_calls : [];
-      if (toolCalls.length) {
-        push("Tool Calls:");
-        for (const tc of toolCalls) {
-          push("```");
-          push(JSON.stringify(tc, null, 2));
-          push("```");
-        }
+    if (candidate) return candidate;
+  }
+  return void 0;
+}
+function inferProviderFromMessages(messageList) {
+  if (!Array.isArray(messageList)) return void 0;
+  for (let i = messageList.length - 1; i >= 0; i -= 1) {
+    const message = messageList[i];
+    if (!message) continue;
+    const candidate = firstNonEmptyString(
+      message?.metadata?.provider,
+      message?.metadata?.providers,
+      message?.response_metadata?.provider,
+      message?.response_metadata?.providers,
+      message?.usage_metadata?.provider,
+      message?.provider,
+      message?.additional_kwargs?.provider,
+      message?.info?.provider,
+      message?.annotations?.provider
+    );
+    if (candidate) return candidate;
+  }
+  return void 0;
+}
+var DEFAULT_TRACE_CONFIG = {
+  logData: true
+};
+function ensureDir(p) {
+  if (!fs__default.default.existsSync(p)) {
+    fs__default.default.mkdirSync(p, { recursive: true });
+  }
+}
+function withDefaults(config) {
+  const enabled = Boolean(config?.enabled);
+  const logData = config?.logData ?? DEFAULT_TRACE_CONFIG.logData;
+  let sink;
+  try {
+    sink = resolveSink(config?.sink);
+  } catch (err) {
+    if (typeof console !== "undefined" && typeof console.warn === "function") {
+      console.warn("Invalid tracing sink configuration. Falling back to file sink.", err);
+    }
+    sink = resolveSink({ type: "file" });
+  }
+  return {
+    enabled,
+    logData,
+    mode: "batched",
+    sink
+  };
+}
+function resolveSink(sink) {
+  const candidate = sink ?? { type: "file" };
+  switch (candidate.type) {
+    case "file": {
+      const baseDir = resolveLogsBaseDir(candidate.path, false);
+      return { type: "file", baseDir };
+    }
+    case "custom": {
+      const onEvent = typeof candidate.onEvent === "function" ? candidate.onEvent : void 0;
+      const onSession = typeof candidate.onSession === "function" ? candidate.onSession : void 0;
+      return { type: "custom", onEvent, onSession };
+    }
+    case "cognipeer": {
+      const apiKey = typeof candidate.apiKey === "string" ? candidate.apiKey.trim() : "";
+      if (!apiKey) {
+        throw new Error("cognipeer sink requires a non-empty apiKey");
+      }
+      const url = typeof candidate.url === "string" && candidate.url.trim().length > 0 ? candidate.url.trim() : DEFAULT_COGNIPEER_URL;
+      return { type: "cognipeer", url, apiKey };
+    }
+    case "http": {
+      const url = typeof candidate.url === "string" ? candidate.url.trim() : "";
+      if (!url) {
+        throw new Error("http sink requires a non-empty url");
+      }
+      const headers = candidate.headers ? { ...candidate.headers } : void 0;
+      return headers ? { type: "http", url, headers } : { type: "http", url };
+    }
+    default: {
+      if (typeof console !== "undefined" && typeof console.warn === "function") {
+        console.warn("Unknown tracing sink type. Falling back to file sink.", candidate);
       }
-      push(typeof anyM.content === "string" ? anyM.content : JSON.stringify(anyM.content, null, 2));
-      push("");
-    } else if (role === "tool") {
-      push("### ToolResponse\n");
-      const hdr = { name: anyM.name, tool_call_id: anyM.tool_call_id, executionId: anyM.executionId };
-      push("```");
-      push(JSON.stringify(hdr, null, 2));
-      push("```");
-      push(typeof anyM.content === "string" ? anyM.content : JSON.stringify(anyM.content, null, 2));
-      push("");
+      return resolveSink({ type: "file" });
+    }
+  }
+}
+function snapshotSink(runtime) {
+  const sink = runtime.resolvedConfig.sink;
+  switch (sink.type) {
+    case "file":
+      return { type: "file", path: runtime.fileBaseDir || sink.baseDir };
+    case "custom":
+      return { type: "custom" };
+    case "cognipeer":
+      return { type: "cognipeer", url: sink.url };
+    case "http":
+      return { type: "http", url: sink.url };
+    default:
+      return { type: "custom" };
+  }
+}
+function buildConfigSnapshot(runtime) {
+  return {
+    enabled: runtime.resolvedConfig.enabled,
+    logData: runtime.resolvedConfig.logData,
+    sink: snapshotSink(runtime)
+  };
+}
+async function postTraceSession(url, headers, payload) {
+  const fetchFn = typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : void 0;
+  if (!fetchFn) {
+    throw new Error("HTTP sink requires fetch to be available in this runtime.");
+  }
+  const finalHeaders = { ...headers || {} };
+  if (!Object.keys(finalHeaders).some((key) => key.toLowerCase() === "content-type")) {
+    finalHeaders["content-type"] = "application/json";
+  }
+  const response = await fetchFn(url, {
+    method: "POST",
+    headers: finalHeaders,
+    body: JSON.stringify(payload)
+  });
+  if (!response.ok) {
+    let responseText = "";
+    try {
+      responseText = await response.text();
+    } catch {
+    }
+    const statusLine = `HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ""}`;
+    const bodyPreview = responseText ? ` - ${responseText.slice(0, 200)}` : "";
+    throw new Error(`${statusLine}${bodyPreview}`);
+  }
+}
+function createEmptySummary() {
+  return {
+    totalDurationMs: 0,
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalCachedInputTokens: 0,
+    totalBytesIn: 0,
+    totalBytesOut: 0,
+    eventCounts: {}
+  };
+}
+function generateSessionId() {
+  return `sess_${nanoid.nanoid(18)}`;
+}
+function generateEventId(sequence) {
+  return `evt_${String(sequence).padStart(4, "0")}_${nanoid.nanoid(4)}`;
+}
+function defaultEventLabel(type) {
+  switch (type) {
+    case "ai_call":
+      return "Assistant Response";
+    case "tool_call":
+      return "Tool Execution";
+    case "session":
+      return "Session Event";
+    default:
+      return type.replace(/_/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
+  }
+}
+function ensureUniqueSections(eventId, sections) {
+  if (!sections || sections.length === 0) return void 0;
+  const labelCounts = /* @__PURE__ */ new Map();
+  const normalized = [];
+  let counter = 1;
+  for (const section of sections) {
+    const baseLabel = section.label?.trim().length ? section.label.trim() : defaultSectionLabel(section.kind);
+    const nextCount = (labelCounts.get(baseLabel) || 0) + 1;
+    labelCounts.set(baseLabel, nextCount);
+    const finalLabel = nextCount > 1 ? `${baseLabel} (${nextCount})` : baseLabel;
+    let id = section.id?.trim();
+    if (!id) {
+      id = `${section.kind}-${eventId}-${String(counter).padStart(2, "0")}`;
     }
+    counter += 1;
+    normalized.push({
+      ...section,
+      id,
+      label: finalLabel
+    });
   }
-  return lines.join("\n");
+  return normalized;
 }
-function formatMarkdown(params) {
-  const { modelName, date, limits, usage, tools = [], messages } = params;
+function defaultSectionLabel(kind) {
+  switch (kind) {
+    case "message":
+      return "Message";
+    case "tool_call":
+      return "Tool Call";
+    case "tool_result":
+      return "Tool Result";
+    case "tool_response":
+      return "Tool Response";
+    case "summary":
+      return "Summary";
+    case "metadata":
+      return "Details";
+    default:
+      return "Section";
+  }
+}
+function buildMessageLabel(role, index) {
+  const normalized = role?.trim().length ? role.trim() : "message";
+  const base = `${normalized.charAt(0).toUpperCase()}${normalized.slice(1)} Message`;
+  return index > 1 ? `${base} #${index}` : base;
+}
+function toDisplayString(value) {
+  const sanitized = sanitizeTracePayload(value);
+  if (sanitized == null) return "";
+  if (typeof sanitized === "string") return sanitized;
+  if (Array.isArray(sanitized)) {
+    return sanitized.map((item) => toDisplayString(item)).filter((part) => part && part.trim().length > 0).join("\n");
+  }
+  if (typeof sanitized === "object") {
+    if (typeof sanitized.text === "string" && Object.keys(sanitized).length === 1) {
+      return sanitized.text;
+    }
+    if (typeof sanitized.content === "string") {
+      return sanitized.content;
+    }
+    try {
+      return JSON.stringify(sanitized, null, 2);
+    } catch {
+      return String(sanitized);
+    }
+  }
+  return String(sanitized);
+}
+function parseToolArguments(args) {
+  if (args == null) return void 0;
+  if (typeof args === "string") {
+    try {
+      return JSON.parse(args);
+    } catch {
+      return args;
+    }
+  }
+  return args;
+}
+function collectToolCallSectionsFromMessage(message) {
   const sections = [];
-  const add = (s = "") => sections.push(s);
-  add(`# modelName`);
-  add(String(modelName ?? "unknown"));
-  add("");
-  add(`# date`);
-  add(date);
-  add("");
-  add(`# limitler`);
-  add("```");
-  add(JSON.stringify(limits ?? {}, null, 2));
-  add("```");
-  add("");
-  add(`# usage`);
-  if (usage) {
-    add("```");
-    add(JSON.stringify(usage));
-    add("```");
-  } else {
-    add("(none)");
-  }
-  add("");
-  add(`# tools`);
-  add("```");
-  add(formatTools(tools));
-  add("```");
-  add("");
-  add(`# Messages`);
-  add(formatMessages(messages));
-  return sections.join("\n");
-}
-async function writeStepMarkdown(session, fileName, markdown, payload) {
-  if (session.callback) {
-    session.callback({
-      sessionId: session.sessionId,
-      stepIndex: session.stepIndex,
-      fileName,
-      markdown,
-      messages: payload?.messages ?? [],
-      usage: payload?.usage,
-      modelName: payload?.modelName,
-      limits: payload?.limits,
-      tools: payload?.tools
+  if (!message) return sections;
+  const addCall = (call) => {
+    if (!call) return;
+    const toolName = call?.name || call?.tool || call?.function?.name || call?.function_call?.name || "tool";
+    const rawArgs = call?.arguments ?? call?.args ?? call?.input ?? call?.function?.arguments ?? call?.function_call?.arguments;
+    const parsedArgs = parseToolArguments(rawArgs);
+    const argumentsPayload = sanitizeTracePayload(parsedArgs ?? rawArgs ?? {});
+    sections.push({
+      kind: "tool_call",
+      label: `Tool Call: ${toolName}`,
+      tool: toolName,
+      arguments: argumentsPayload
+    });
+  };
+  const directCalls = Array.isArray(message?.tool_calls) ? message.tool_calls : void 0;
+  if (directCalls) {
+    directCalls.forEach((call) => addCall(call));
+  }
+  return sections;
+}
+function convertMessageListToSections(messageList) {
+  if (!Array.isArray(messageList) || messageList.length === 0) return void 0;
+  const sections = [];
+  const roleCounts = /* @__PURE__ */ new Map();
+  for (const message of messageList) {
+    if (!message) continue;
+    const toolSections = collectToolCallSectionsFromMessage(message);
+    if (toolSections.length > 0) {
+      sections.push(...toolSections);
+      continue;
+    }
+    const role = typeof message?.role === "string" ? message.role : "assistant";
+    const next = (roleCounts.get(role) || 0) + 1;
+    roleCounts.set(role, next);
+    let content = toDisplayString(message?.content ?? "");
+    if (!content || !content.trim().length) {
+      if (toolSections.length > 0) {
+        content = "[tool call]";
+      } else if (typeof message?.content === "undefined" || message?.content === null) {
+        continue;
+      } else {
+        content = toDisplayString(sanitizeTracePayload(message?.content));
+        if (!content || !content.trim().length) continue;
+      }
+    }
+    sections.push({
+      kind: "message",
+      label: buildMessageLabel(role, next),
+      role,
+      content,
+      metadata: typeof message?.name === "string" ? { name: message.name } : void 0
     });
-    return;
   }
-  const fp = import_node_path.default.join(session.sessionDir, fileName);
-  await import_node_fs.default.promises.writeFile(fp, markdown, "utf8");
+  return sections.length > 0 ? sections : void 0;
+}
+function createTraceSession(opts) {
+  const cfg = withDefaults(opts.tracing);
+  if (!cfg.enabled) return void 0;
+  const sessionId = generateSessionId();
+  const runtime = {
+    sessionId,
+    startedAt: Date.now(),
+    resolvedConfig: cfg,
+    events: [],
+    summary: createEmptySummary(),
+    status: "in_progress",
+    errors: []
+  };
+  if (cfg.sink.type === "file") {
+    const baseDir = cfg.sink.baseDir;
+    ensureDir(baseDir);
+    const sessionDir = path__default.default.join(baseDir, sessionId);
+    ensureDir(sessionDir);
+    runtime.fileBaseDir = baseDir;
+    runtime.fileSessionDir = sessionDir;
+  }
+  return runtime;
+}
+function recordTraceEvent(session, event) {
+  if (!session) return void 0;
+  const sequence = session.events.length + 1;
+  const id = generateEventId(sequence);
+  const timestampIso = event.timestamp || (/* @__PURE__ */ new Date()).toISOString();
+  const status = event.status ?? "success";
+  const baseLabel = event.label?.trim().length ? event.label.trim() : defaultEventLabel(event.type);
+  const eventLabel = `${baseLabel} #${sequence}`;
+  const durationMs = event.durationMs !== void 0 ? Number(event.durationMs) : void 0;
+  if (!Number.isNaN(durationMs ?? NaN) && durationMs !== void 0) {
+    session.summary.totalDurationMs += durationMs;
+  }
+  const inputTokens = event.inputTokens !== void 0 ? Number(event.inputTokens) : void 0;
+  if (!Number.isNaN(inputTokens ?? NaN) && inputTokens !== void 0) {
+    session.summary.totalInputTokens += inputTokens;
+  }
+  const outputTokens = event.outputTokens !== void 0 ? Number(event.outputTokens) : void 0;
+  if (!Number.isNaN(outputTokens ?? NaN) && outputTokens !== void 0) {
+    session.summary.totalOutputTokens += outputTokens;
+  }
+  const cachedInputTokens = event.cachedInputTokens !== void 0 ? Number(event.cachedInputTokens) : void 0;
+  if (!Number.isNaN(cachedInputTokens ?? NaN) && cachedInputTokens !== void 0) {
+    session.summary.totalCachedInputTokens += cachedInputTokens;
+  }
+  const totalTokens = event.totalTokens !== void 0 ? Number(event.totalTokens) : void 0;
+  const requestBytes = event.requestBytes !== void 0 ? Number(event.requestBytes) : void 0;
+  if (!Number.isNaN(requestBytes ?? NaN) && requestBytes !== void 0) {
+    session.summary.totalBytesIn += requestBytes;
+  }
+  const responseBytes = event.responseBytes !== void 0 ? Number(event.responseBytes) : void 0;
+  if (!Number.isNaN(responseBytes ?? NaN) && responseBytes !== void 0) {
+    session.summary.totalBytesOut += responseBytes;
+  }
+  session.summary.eventCounts[event.type] = (session.summary.eventCounts[event.type] || 0) + 1;
+  let sections;
+  if (session.resolvedConfig.logData) {
+    const converted = convertMessageListToSections(event.messageList);
+    sections = ensureUniqueSections(id, converted);
+  }
+  const resolvedModel = event.model ?? inferModelFromMessages(event.messageList);
+  const resolvedProvider = event.provider ?? inferProviderFromMessages(event.messageList);
+  const isAiCall = event.type === "ai_call";
+  const record = {
+    sessionId: session.sessionId,
+    id,
+    type: event.type,
+    label: eventLabel,
+    sequence,
+    timestamp: timestampIso,
+    actor: event.actor,
+    status,
+    durationMs,
+    ...isAiCall ? {
+      inputTokens: inputTokens ?? 0,
+      outputTokens: outputTokens ?? 0,
+      totalTokens: totalTokens ?? 0,
+      cachedInputTokens: cachedInputTokens ?? 0
+    } : {
+      ...inputTokens !== void 0 && { inputTokens },
+      ...outputTokens !== void 0 && { outputTokens },
+      ...totalTokens !== void 0 && { totalTokens },
+      ...cachedInputTokens !== void 0 && { cachedInputTokens }
+    },
+    requestBytes,
+    responseBytes,
+    model: resolvedModel,
+    provider: resolvedProvider,
+    toolExecutionId: event.toolExecutionId,
+    retryOf: event.retryOf,
+    error: event.error ?? (status === "error" ? { message: "Unknown error" } : void 0) ?? void 0,
+    data: sections ? { sections } : void 0,
+    debug: event.debug
+  };
+  if (status === "error") {
+    const errorInfo = event.error ?? { message: "Unknown error" };
+    session.errors.push({
+      eventId: id,
+      message: errorInfo.message,
+      stack: errorInfo.stack,
+      type: event.type,
+      timestamp: timestampIso
+    });
+  }
+  session.events.push(record);
+  const sink = session.resolvedConfig.sink;
+  if (sink.type === "custom" && typeof sink.onEvent === "function") {
+    try {
+      const cloned = JSON.parse(JSON.stringify(record));
+      const result = sink.onEvent(cloned);
+      if (result && typeof result.then === "function") {
+        result.then(void 0, (error) => {
+          if (typeof console !== "undefined" && typeof console.warn === "function") {
+            console.warn("Trace custom sink onEvent rejected", error);
+          }
+        });
+      }
+    } catch (err) {
+      if (typeof console !== "undefined" && typeof console.warn === "function") {
+        console.warn("Trace custom sink onEvent failed", err);
+      }
+    }
+  }
+  return record;
+}
+async function finalizeTraceSession(session, params = {}) {
+  if (!session) return void 0;
+  const endedAtMs = Date.now();
+  const endedAtIso = new Date(endedAtMs).toISOString();
+  const durationMs = endedAtMs - session.startedAt;
+  const startedAtIso = new Date(session.startedAt).toISOString();
+  const agentInfo = params.agentRuntime ? {
+    name: params.agentRuntime.name,
+    version: params.agentRuntime.version,
+    model: getModelName(params.agentRuntime.model),
+    provider: getProviderName(params.agentRuntime.model)
+  } : void 0;
+  if (params.error) {
+    session.errors.push({
+      eventId: "session",
+      message: params.error.message || "Unknown error",
+      stack: params.error.stack,
+      type: "session",
+      timestamp: endedAtIso
+    });
+  }
+  const configSnapshot = buildConfigSnapshot(session);
+  const initialStatus = params.status ? params.status : session.errors.length > 0 ? "error" : "success";
+  const buildPayload = (status2) => ({
+    sessionId: session.sessionId,
+    startedAt: startedAtIso,
+    endedAt: endedAtIso,
+    durationMs,
+    agent: agentInfo,
+    config: configSnapshot,
+    summary: session.summary,
+    events: session.events,
+    status: status2,
+    errors: session.errors
+  });
+  const payloadForSink = buildPayload(initialStatus);
+  let sinkFailed = false;
+  const sink = session.resolvedConfig.sink;
+  if (sink.type === "cognipeer" || sink.type === "http") {
+    try {
+      const headers = sink.type === "cognipeer" ? { Authorization: `Bearer ${sink.apiKey}` } : sink.headers;
+      await postTraceSession(sink.url, headers, payloadForSink);
+    } catch (err) {
+      sinkFailed = true;
+      const message = err instanceof Error ? err.message : String(err);
+      session.errors.push({
+        eventId: "sink",
+        message,
+        type: "sink",
+        timestamp: endedAtIso
+      });
+    }
+  }
+  const hadNonSinkErrors = session.errors.some((error) => error.type && error.type !== "sink");
+  let status = params.status ?? (hadNonSinkErrors ? "error" : "success");
+  if (status === "success" && sinkFailed) {
+    status = "partial";
+  }
+  let finalPayload = buildPayload(status);
+  if (sink.type === "file" && session.fileSessionDir) {
+    try {
+      const filePath = path__default.default.join(session.fileSessionDir, "trace.session.json");
+      await fs__default.default.promises.writeFile(filePath, JSON.stringify(finalPayload, null, 2), "utf8");
+    } catch (err) {
+      sinkFailed = true;
+      const message = err instanceof Error ? err.message : String(err);
+      session.errors.push({
+        eventId: "sink",
+        message,
+        type: "sink",
+        timestamp: endedAtIso
+      });
+      if (status === "success") {
+        status = "partial";
+        finalPayload = buildPayload(status);
+      }
+    }
+  }
+  if (sink.type === "custom" && typeof sink.onSession === "function") {
+    try {
+      const cloned = JSON.parse(JSON.stringify(finalPayload));
+      await sink.onSession(cloned);
+    } catch (err) {
+      sinkFailed = true;
+      const message = err instanceof Error ? err.message : String(err);
+      session.errors.push({
+        eventId: "sink",
+        message,
+        type: "sink",
+        timestamp: endedAtIso
+      });
+      if (status === "success") {
+        status = "partial";
+        finalPayload = buildPayload(status);
+      }
+    }
+  }
+  if (!params.status) {
+    const finalHadNonSinkErrors = session.errors.some((error) => error.type && error.type !== "sink");
+    const hasSinkErrors = session.errors.some((error) => error.type === "sink");
+    let computedStatus = finalHadNonSinkErrors ? "error" : "success";
+    if (computedStatus === "success" && hasSinkErrors) {
+      computedStatus = "partial";
+    }
+    if (computedStatus !== status) {
+      status = computedStatus;
+      finalPayload = buildPayload(status);
+    }
+  }
+  return finalPayload;
+}
+function sanitizeTracePayload(value) {
+  try {
+    const cache = /* @__PURE__ */ new WeakSet();
+    const json = JSON.stringify(
+      value,
+      (_key, val) => {
+        if (typeof val === "function") return `[Function ${val.name || "anonymous"}]`;
+        if (typeof val === "bigint") return val.toString();
+        if (val instanceof Error) return { message: val.message, stack: val.stack };
+        if (val && typeof val === "object") {
+          if (cache.has(val)) return "[Circular]";
+          cache.add(val);
+        }
+        return val;
+      },
+      2
+    );
+    return JSON.parse(json);
+  } catch {
+    try {
+      return typeof value === "string" ? value : String(value);
+    } catch {
+      return "[Unserializable]";
+    }
+  }
+}
+function estimatePayloadBytes(value) {
+  try {
+    const json = JSON.stringify(value);
+    return buffer.Buffer.byteLength(json ?? "", "utf8");
+  } catch {
+    try {
+      return buffer.Buffer.byteLength(String(value ?? ""), "utf8");
+    } catch {
+      return 0;
+    }
+  }
 }
 
 // src/nodes/agentCore.ts
@@ -405,16 +1088,42 @@ function createAgentCoreNode(opts) {
   return async (state) => {
     const runtime = state.agent || {
       name: opts.name,
+      version: opts.version,
       model: opts.model,
       tools: opts.tools || [],
-      systemPrompt: void 0,
+      guardrails: opts.guardrails,
       limits: opts.limits,
-      useTodoList: void 0,
-      outputSchema: opts.outputSchema
+      outputSchema: opts.outputSchema,
+      tracing: opts.tracing
     };
     const tools = runtime.tools ?? [];
     const modelWithTools = runtime.model?.bindTools ? runtime.model.bindTools(tools) : runtime.model;
-    const response = await modelWithTools.invoke([...state.messages]);
+    const traceSession = state.ctx?.__traceSession;
+    const actorName = runtime.name ?? opts.name ?? "agent";
+    const actorVersion = runtime.version ?? opts.version;
+    const start = Date.now();
+    const shouldLogPrompt = !!traceSession && traceSession.resolvedConfig.logData;
+    const promptPayload = shouldLogPrompt ? sanitizeTracePayload(state.messages) : void 0;
+    const promptBytes = promptPayload !== void 0 ? estimatePayloadBytes(promptPayload) : void 0;
+    let response;
+    try {
+      response = await modelWithTools.invoke([...state.messages]);
+    } catch (err) {
+      const durationMs2 = Date.now() - start;
+      recordTraceEvent(traceSession, {
+        type: "ai_call",
+        label: "Assistant Error",
+        actor: { scope: "agent", name: actorName, role: "assistant", version: actorVersion },
+        status: "error",
+        durationMs: durationMs2,
+        requestBytes: promptBytes,
+        model: getModelName(runtime.model || opts.model),
+        provider: getProviderName(runtime.model || opts.model),
+        error: { message: err?.message || String(err), stack: err?.stack },
+        messageList: state.messages
+      });
+      throw err;
+    }
     const messagesWithResponse = [
       ...state.messages,
       response
@@ -422,6 +1131,25 @@ function createAgentCoreNode(opts) {
     const rawUsage = response?.usage || response?.response_metadata?.token_usage || response?.response_metadata?.usage;
     const normalized = normalizeUsage(rawUsage);
     const modelName = getModelName(runtime.model || opts.model) || "unknown_model";
+    const durationMs = Date.now() - start;
+    const shouldLogResponse = !!traceSession && traceSession.resolvedConfig.logData;
+    const responsePayload = shouldLogResponse ? sanitizeTracePayload(response) : void 0;
+    const responseBytes = responsePayload !== void 0 ? estimatePayloadBytes(responsePayload) : void 0;
+    recordTraceEvent(traceSession, {
+      type: "ai_call",
+      label: "Assistant Response",
+      actor: { scope: "agent", name: actorName, role: "assistant", version: actorVersion },
+      durationMs,
+      inputTokens: normalized?.prompt_tokens,
+      outputTokens: normalized?.completion_tokens,
+      totalTokens: normalized?.total_tokens,
+      cachedInputTokens: normalized?.prompt_tokens_details?.cached_tokens,
+      requestBytes: promptBytes,
+      responseBytes,
+      model: modelName,
+      provider: getProviderName(runtime.model || opts.model),
+      messageList: messagesWithResponse
+    });
     if (normalized) {
       const usageState = state.usage || { perRequest: [], totals: {} };
       const id = `${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
@@ -445,10 +1173,6 @@ function createAgentCoreNode(opts) {
     return { messages: messagesWithResponse, usage: state.usage };
   };
 }
-
-// src/nodes/tools.ts
-var import_nanoid = require("nanoid");
-var import_messages = require("@langchain/core/messages");
 function createToolsNode(initialTools, opts) {
   const baseToolByName = /* @__PURE__ */ new Map();
   for (const t of initialTools) baseToolByName.set(t.name, t);
@@ -471,6 +1195,10 @@ function createToolsNode(initialTools, opts) {
     };
     const appended = [];
     const onEvent = state.ctx?.__onEvent;
+    const traceSession = state.ctx?.__traceSession;
+    const pendingApprovals = Array.isArray(state.pendingApprovals) ? state.pendingApprovals.map((entry) => ({ ...entry })) : [];
+    const pendingByCallId = new Map(pendingApprovals.map((entry) => [entry.toolCallId, entry]));
+    let awaitingApproval = false;
     for (const t of toolByName.values()) {
       const anyT = t;
       if (anyT._stateRef && typeof anyT._stateRef === "object") {
@@ -490,25 +1218,51 @@ function createToolsNode(initialTools, opts) {
     const skipped = toolCalls.slice(remaining);
     for (const tc of skipped) {
       onEvent?.({ type: "tool_call", phase: "skipped", name: tc.name, id: tc.id, args: tc.args });
-      appended.push(new import_messages.ToolMessage({
+      const sanitizedArgs = sanitizeTracePayload(tc.args);
+      const messageList = [
+        {
+          role: "assistant",
+          name: tc.name,
+          content: `Skipped tool due to tool-call limit: ${tc.name}`,
+          tool_calls: [
+            {
+              id: tc.id,
+              type: "function",
+              function: {
+                name: tc.name,
+                arguments: sanitizedArgs
+              }
+            }
+          ]
+        }
+      ];
+      recordTraceEvent(traceSession, {
+        type: "tool_call",
+        label: `Tool Skipped - ${tc.name}`,
+        actor: { scope: "tool", name: tc.name, role: "tool" },
+        status: "skipped",
+        toolExecutionId: tc.id,
+        messageList
+      });
+      appended.push({
+        role: "tool",
         content: `Skipped tool due to tool-call limit: ${tc.name}`,
         tool_call_id: tc.id || `${tc.name}_${appended.length}`,
         name: tc.name
-      }));
+      });
     }
     const runOne = async (tc) => {
       const t = toolByName.get(tc.name);
       if (!t) {
         onEvent?.({ type: "tool_call", phase: "error", name: tc.name, id: tc.id, args: tc.args, error: { message: "Tool not found" } });
-        appended.push(
-          new import_messages.ToolMessage({
-            content: `Tool not found: ${tc.name}`,
-            tool_call_id: tc.id || `${tc.name}_${appended.length}`,
-            name: tc.name
-          })
-        );
+        appended.push({
+          role: "tool",
+          content: `Tool not found: ${tc.name}`,
+          tool_call_id: tc.id || `${tc.name}_${appended.length}`,
+          name: tc.name
+        });
         toolCount += 1;
-        return;
+        return { status: "error" };
       }
       let args = tc.args;
       if (typeof args === "string") {
@@ -517,9 +1271,67 @@ function createToolsNode(initialTools, opts) {
         } catch (_) {
         }
       }
+      const toolCallId = tc.id || `${tc.name}_${toolCount + 1}`;
+      let approvalEntry = pendingByCallId.get(toolCallId);
+      const needsApproval = Boolean(t.needsApproval);
+      if (needsApproval) {
+        if (!approvalEntry) {
+          approvalEntry = {
+            id: nanoid.nanoid(),
+            toolCallId,
+            toolName: t.name || tc.name,
+            args,
+            status: "pending",
+            requestedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            metadata: t.approvalPrompt || t.approvalDefaults ? { prompt: t.approvalPrompt, defaults: t.approvalDefaults } : void 0
+          };
+          pendingApprovals.push(approvalEntry);
+          pendingByCallId.set(toolCallId, approvalEntry);
+          onEvent?.({ type: "tool_approval", status: "pending", id: approvalEntry.id, toolName: approvalEntry.toolName, toolCallId: approvalEntry.toolCallId, args });
+        } else if (!approvalEntry.args) {
+          approvalEntry.args = args;
+        }
+        if (approvalEntry.status === "pending") {
+          awaitingApproval = true;
+          const ctx = state.ctx = state.ctx || {};
+          ctx.__awaitingApproval = {
+            approvalId: approvalEntry.id,
+            toolCallId: approvalEntry.toolCallId,
+            toolName: approvalEntry.toolName,
+            requestedAt: approvalEntry.requestedAt
+          };
+          ctx.__resumeStage = "tools";
+          return { status: "awaiting_approval", approval: approvalEntry };
+        }
+        if (approvalEntry.status === "rejected") {
+          const rejectionMessage = approvalEntry.comment || "Tool call rejected by reviewer.";
+          appended.push({
+            role: "tool",
+            content: `Tool call rejected: ${rejectionMessage}`,
+            tool_call_id: toolCallId,
+            name: tc.name
+          });
+          onEvent?.({ type: "tool_approval", status: "rejected", id: approvalEntry.id, toolName: approvalEntry.toolName, toolCallId: approvalEntry.toolCallId, comment: approvalEntry.comment, decidedBy: approvalEntry.decidedBy });
+          approvalEntry.metadata = { ...approvalEntry.metadata || {}, resolution: "rejected" };
+          approvalEntry.status = "executed";
+          approvalEntry.resolvedAt = (/* @__PURE__ */ new Date()).toISOString();
+          toolHistory.push({ executionId: nanoid.nanoid(), toolName: t.name, args, output: `Rejected: ${rejectionMessage}`, rawOutput: null, timestamp: (/* @__PURE__ */ new Date()).toISOString(), tool_call_id: tc.id });
+          pendingByCallId.set(toolCallId, approvalEntry);
+          toolCount += 1;
+          return { status: "rejected", approval: approvalEntry };
+        }
+        if (approvalEntry.status === "approved") {
+          if (approvalEntry.approvedArgs !== void 0) {
+            args = approvalEntry.approvedArgs;
+          }
+          onEvent?.({ type: "tool_approval", status: "approved", id: approvalEntry.id, toolName: approvalEntry.toolName, toolCallId: approvalEntry.toolCallId, decidedBy: approvalEntry.decidedBy, comment: approvalEntry.comment });
+        }
+      }
+      const start = Date.now();
       try {
-        const start = Date.now();
         onEvent?.({ type: "tool_call", phase: "start", name: t.name, id: tc.id, args });
+        const sanitizedArgs = sanitizeTracePayload(args);
+        const inputBytes = traceSession?.resolvedConfig.logData ? estimatePayloadBytes(sanitizedArgs) : void 0;
         let output;
         const anyTool = t;
         if (typeof anyTool.func === "function") output = await anyTool.func(args);
@@ -530,14 +1342,20 @@ function createToolsNode(initialTools, opts) {
         else throw new Error("Tool is not invokable");
         if (output && typeof output === "object" && output.__handoff && output.__handoff.runtime) {
           const newRuntime = output.__handoff.runtime;
-          const executionId2 = (0, import_nanoid.nanoid)();
+          const executionId2 = nanoid.nanoid();
           toolHistory.push({ executionId: executionId2, toolName: t.name, args, output: "handoff:ok", rawOutput: output, timestamp: (/* @__PURE__ */ new Date()).toISOString(), tool_call_id: tc.id });
-          appended.push(new import_messages.ToolMessage({ content: "ok", tool_call_id: tc.id || `${tc.name}_${appended.length}`, name: tc.name }));
+          appended.push({ role: "tool", content: "ok", tool_call_id: tc.id || `${tc.name}_${appended.length}`, name: tc.name });
           onEvent?.({ type: "handoff", from: runtime.name, to: newRuntime.name, toolName: t.name });
           state.agent = newRuntime;
           onEvent?.({ type: "tool_call", phase: "success", name: t.name, id: tc.id, args, result: "handoff", durationMs: Date.now() - start });
           toolCount += 1;
-          return;
+          if (needsApproval && approvalEntry) {
+            approvalEntry.status = "executed";
+            approvalEntry.resolvedAt = (/* @__PURE__ */ new Date()).toISOString();
+            approvalEntry.executionId = executionId2;
+            pendingByCallId.set(toolCallId, approvalEntry);
+          }
+          return { status: "success", approval: approvalEntry };
         }
         const content = typeof output === "string" ? output : JSON.stringify(output);
         if (output && typeof output === "object" && output.__finalStructuredOutput) {
@@ -545,25 +1363,124 @@ function createToolsNode(initialTools, opts) {
           state.ctx.__structuredOutputParsed = output.data;
           state.ctx.__finalizedDueToStructuredOutput = true;
         }
-        const executionId = (0, import_nanoid.nanoid)();
+        const durationMs = Date.now() - start;
+        const executionId = nanoid.nanoid();
         toolHistory.push({ executionId, toolName: t.name, args, output, rawOutput: output, timestamp: (/* @__PURE__ */ new Date()).toISOString(), tool_call_id: tc.id });
-        appended.push(new import_messages.ToolMessage({ content, tool_call_id: tc.id || `${tc.name}_${appended.length}`, name: tc.name }));
-        onEvent?.({ type: "tool_call", phase: "success", name: t.name, id: tc.id, args, result: output, durationMs: Date.now() - start });
+        appended.push({ role: "tool", content, tool_call_id: tc.id || `${tc.name}_${appended.length}`, name: tc.name });
+        onEvent?.({ type: "tool_call", phase: "success", name: t.name, id: tc.id, args, result: output, durationMs });
+        if (needsApproval && approvalEntry) {
+          approvalEntry.status = "executed";
+          approvalEntry.resolvedAt = (/* @__PURE__ */ new Date()).toISOString();
+          approvalEntry.executionId = executionId;
+          pendingByCallId.set(toolCallId, approvalEntry);
+        }
+        const sanitizedOutput = sanitizeTracePayload(output);
+        const outputBytes = traceSession?.resolvedConfig.logData ? estimatePayloadBytes(sanitizedOutput) : void 0;
+        const toolName = t.name || tc.name;
+        const messageList = [
+          {
+            role: "assistant",
+            name: toolName,
+            content: "",
+            tool_calls: [
+              {
+                id: tc.id || executionId,
+                type: "function",
+                function: {
+                  name: toolName,
+                  arguments: sanitizedArgs
+                }
+              }
+            ]
+          },
+          {
+            role: "tool",
+            name: toolName,
+            content: sanitizedOutput ?? output ?? ""
+          }
+        ];
+        recordTraceEvent(traceSession, {
+          type: "tool_call",
+          label: `Tool Execution - ${toolName}`,
+          actor: { scope: "tool", name: toolName, role: "tool" },
+          durationMs,
+          requestBytes: inputBytes,
+          responseBytes: outputBytes,
+          toolExecutionId: executionId,
+          messageList
+        });
         toolCount += 1;
+        return { status: "success", approval: approvalEntry };
       } catch (e) {
-        const executionId = (0, import_nanoid.nanoid)();
+        const durationMs = Date.now() - start;
+        const executionId = nanoid.nanoid();
         toolHistory.push({ executionId, toolName: t.name, args, output: `Error executing tool: ${e?.message || String(e)}`, rawOutput: null, timestamp: (/* @__PURE__ */ new Date()).toISOString(), tool_call_id: tc.id });
-        appended.push(new import_messages.ToolMessage({ content: `Error executing tool: ${e?.message || String(e)}`, tool_call_id: tc.id || `${tc.name}_${appended.length}`, name: tc.name }));
+        appended.push({ role: "tool", content: `Error executing tool: ${e?.message || String(e)}`, tool_call_id: tc.id || `${tc.name}_${appended.length}`, name: tc.name });
         onEvent?.({ type: "tool_call", phase: "error", name: t.name, id: tc.id, args, error: { message: e?.message || String(e) } });
+        const sanitizedArgs = sanitizeTracePayload(args);
+        const inputBytes = traceSession?.resolvedConfig.logData ? estimatePayloadBytes(sanitizedArgs) : void 0;
+        const toolName = t.name || tc.name;
+        const errorMessage = e?.message || String(e);
+        const messageList = [
+          {
+            role: "assistant",
+            name: toolName,
+            content: "",
+            tool_calls: [
+              {
+                id: tc.id || executionId,
+                type: "function",
+                function: {
+                  name: toolName,
+                  arguments: sanitizedArgs
+                }
+              }
+            ]
+          },
+          {
+            role: "tool",
+            name: toolName,
+            content: `Error executing tool: ${errorMessage}`
+          }
+        ];
+        recordTraceEvent(traceSession, {
+          type: "tool_call",
+          label: `Tool Error - ${toolName}`,
+          actor: { scope: "tool", name: toolName, role: "tool" },
+          status: "error",
+          durationMs,
+          requestBytes: inputBytes,
+          toolExecutionId: executionId,
+          error: { message: e?.message || String(e), stack: e?.stack },
+          messageList
+        });
         toolCount += 1;
+        return { status: "error", approval: approvalEntry };
       }
     };
-    const concurrency = Math.max(1, limits.maxParallelTools);
-    for (let i = 0; i < planned.length; i += concurrency) {
-      const batch = planned.slice(i, i + concurrency);
-      await Promise.all(batch.map(runOne));
+    for (const tc of planned) {
+      if (awaitingApproval) break;
+      const result = await runOne(tc);
+      if (result?.status === "awaiting_approval") {
+        awaitingApproval = true;
+        break;
+      }
     }
-    return { messages: [...state.messages, ...appended], toolCallCount: toolCount, toolHistory, agent: state.agent };
+    if (!awaitingApproval && state.ctx?.__awaitingApproval) {
+      const ctx = { ...state.ctx };
+      delete ctx.__awaitingApproval;
+      if (!pendingApprovals.some((entry) => entry.status !== "executed")) {
+        delete ctx.__resumeStage;
+      }
+      state.ctx = Object.keys(ctx).length > 0 ? ctx : void 0;
+    }
+    return {
+      messages: [...state.messages, ...appended],
+      toolCallCount: toolCount,
+      toolHistory,
+      agent: state.agent,
+      pendingApprovals
+    };
   };
 }
 
@@ -575,6 +1492,207 @@ function createToolLimitFinalizeNode(_opts) {
     return { messages: [...state.messages, notice], ctx };
   };
 }
+function ensureArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+function buildContext(params) {
+  const latest = params.state.messages[params.state.messages.length - 1];
+  return {
+    phase: params.phase,
+    messages: params.state.messages,
+    latestMessage: latest,
+    state: params.state,
+    runtime: params.runtime,
+    options: params.options
+  };
+}
+function normalizeDisposition(passed, disposition) {
+  if (disposition) return disposition;
+  return passed ? "allow" : "block";
+}
+async function evaluateGuardrails(params) {
+  const incidents = [];
+  const guardrails = ensureArray(params.guardrails).filter(
+    (guardrail) => ensureArray(guardrail.appliesTo).includes(params.phase)
+  );
+  if (guardrails.length === 0) {
+    return { ok: true, incidents };
+  }
+  const context = buildContext(params);
+  for (const guardrail of guardrails) {
+    for (const rule of ensureArray(guardrail.rules)) {
+      let result;
+      try {
+        result = await rule.evaluate(context);
+      } catch (err) {
+        result = {
+          passed: false,
+          reason: err instanceof Error ? err.message : String(err ?? "Unknown error"),
+          details: { thrown: true },
+          disposition: "block"
+        };
+      }
+      const passed = result?.passed !== false;
+      const disposition = normalizeDisposition(passed, result?.disposition);
+      if (passed && disposition === "allow") {
+        continue;
+      }
+      const incident = {
+        guardrailId: guardrail.id ?? rule.id ?? nanoid.nanoid(8),
+        guardrailTitle: guardrail.title,
+        ruleId: rule.id,
+        ruleTitle: rule.title,
+        phase: params.phase,
+        reason: result?.reason,
+        details: result?.details,
+        disposition
+      };
+      let effectiveDisposition = incident.disposition;
+      if (typeof guardrail.onViolation === "function") {
+        try {
+          const override = await guardrail.onViolation(incident, context);
+          if (override) {
+            effectiveDisposition = override;
+            incident.disposition = override;
+          }
+        } catch (err) {
+          effectiveDisposition = "block";
+          incident.disposition = "block";
+          incident.details = {
+            ...incident.details || {},
+            onViolationError: err instanceof Error ? err.message : String(err ?? "Unknown error")
+          };
+          if (!incident.reason) {
+            incident.reason = "Guardrail onViolation handler threw an error.";
+          }
+        }
+      }
+      incidents.push(incident);
+      params.emit?.({
+        type: "guardrail",
+        phase: params.phase,
+        guardrailId: incident.guardrailId,
+        guardrailTitle: incident.guardrailTitle,
+        ruleId: incident.ruleId,
+        ruleTitle: incident.ruleTitle,
+        disposition: effectiveDisposition,
+        reason: incident.reason,
+        details: incident.details
+      });
+      if (effectiveDisposition === "block" && guardrail.haltOnViolation !== false) {
+        break;
+      }
+    }
+  }
+  const ok = incidents.every((incident) => incident.disposition !== "block");
+  return { ok, incidents };
+}
+function createGuardrail(options) {
+  const appliesTo = options.appliesTo?.length ? options.appliesTo : ["request" /* Request */, "response" /* Response */];
+  return {
+    id: options.id,
+    title: options.title,
+    description: options.description,
+    appliesTo,
+    rules: options.checks,
+    haltOnViolation: options.haltOnViolation,
+    onViolation: options.onViolation,
+    metadata: options.metadata
+  };
+}
+
+// src/utils/stateSnapshot.ts
+var DISALLOWED_CTX_KEYS = /* @__PURE__ */ new Set(["__onEvent", "__traceSession", "__paused"]);
+var clone = (value) => {
+  if (typeof globalThis.structuredClone === "function") {
+    return globalThis.structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value));
+};
+var cleanCtx = (ctx) => {
+  if (!ctx) return void 0;
+  const entries = Object.entries(ctx).filter(([key]) => !DISALLOWED_CTX_KEYS.has(key));
+  if (entries.length === 0) return void 0;
+  return Object.fromEntries(entries);
+};
+var runtimeHintFromAgent = (agent) => {
+  if (!agent) return void 0;
+  const tools = Array.isArray(agent.tools) ? agent.tools.map((tool) => tool?.name).filter(Boolean) : void 0;
+  return {
+    name: agent.name,
+    version: agent.version,
+    tools: tools && tools.length > 0 ? tools : void 0
+  };
+};
+function captureSnapshot(state, options) {
+  const { agent, ctx, ...rest } = state;
+  const metadata = {
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    tag: options?.tag,
+    paused: ctx?.__paused ?? null
+  };
+  const safeState = clone({
+    ...rest,
+    ctx: cleanCtx(ctx)
+  });
+  if (safeState.ctx && "__paused" in safeState.ctx) {
+    delete safeState.ctx.__paused;
+  }
+  return {
+    state: safeState,
+    runtimeHint: options?.includeRuntimeHint !== false ? runtimeHintFromAgent(agent) : void 0,
+    metadata
+  };
+}
+function restoreSnapshot(snapshot, restoreOptions) {
+  const base = clone(snapshot.state);
+  const incomingCtx = restoreOptions?.ctx;
+  const mergedCtx = restoreOptions?.mergeCtx === false ? cleanCtx(incomingCtx) : {
+    ...base.ctx || {},
+    ...cleanCtx(incomingCtx)
+  };
+  const ctx = {
+    ...mergedCtx || {},
+    __restoredFromSnapshot: true
+  };
+  const restored = {
+    ...base,
+    ctx
+  };
+  if (restoreOptions?.agent) {
+    restored.agent = restoreOptions.agent;
+  }
+  return restored;
+}
+
+// src/utils/toolApprovals.ts
+var cloneApprovals = (approvals) => Array.isArray(approvals) ? approvals.map((entry) => ({ ...entry })) : [];
+function resolveToolApprovalState(state, resolution) {
+  const approvals = cloneApprovals(state.pendingApprovals);
+  const matchIndex = approvals.findIndex((entry2) => entry2.id === resolution.id || entry2.toolCallId === resolution.id);
+  if (matchIndex === -1) {
+    throw new Error(`Pending approval not found for id: ${resolution.id}`);
+  }
+  const entry = { ...approvals[matchIndex] };
+  if (entry.status === "executed") {
+    throw new Error(`Tool approval ${entry.id} already completed.`);
+  }
+  entry.status = resolution.approved ? "approved" : "rejected";
+  entry.approvedArgs = resolution.approved ? resolution.approvedArgs ?? entry.args : void 0;
+  entry.decidedBy = resolution.decidedBy;
+  entry.comment = resolution.comment;
+  entry.decidedAt = (/* @__PURE__ */ new Date()).toISOString();
+  approvals[matchIndex] = entry;
+  const ctx = { ...state.ctx || {} };
+  delete ctx.__awaitingApproval;
+  ctx.__resumeStage = "tools";
+  ctx.__approvalResolved = { id: entry.id, status: entry.status };
+  return {
+    ...state,
+    pendingApprovals: approvals,
+    ctx
+  };
+}
 
 // src/agent.ts
 function createAgent(opts) {
@@ -582,7 +1700,7 @@ function createAgent(opts) {
   const agentCore = createAgentCoreNode(opts);
   const toolsBase = [...opts.tools ?? []];
   if (opts.outputSchema) {
-    const responseTool = createSmartTool({
+    const responseTool = createTool({
       name: "response",
       description: "Finalize the answer by returning the final structured JSON matching the required schema. Call exactly once when you are fully done, then stop.",
       schema: opts.outputSchema,
@@ -591,15 +1709,180 @@ function createAgent(opts) {
     toolsBase.push(responseTool);
   }
   const toolsNode = createToolsNode(toolsBase, opts);
-  const finalizeNode = createToolLimitFinalizeNode(opts);
-  async function runLoop(initial, config) {
+  const finalizeNode = createToolLimitFinalizeNode();
+  const mergeGuardrailOutcomes = (prev, next) => {
+    if (!prev) return next;
+    return {
+      ok: prev.ok && next.ok,
+      incidents: [...prev.incidents, ...next.incidents]
+    };
+  };
+  const ensureGuardrailStore = (state) => {
+    const ctx = state.ctx = state.ctx || {};
+    const existing = ctx.__guardrailStore || {
+      lastRequestLength: -1,
+      lastResponseLength: -1
+    };
+    ctx.__guardrailStore = existing;
+    return existing;
+  };
+  const getGuardrailConfig = (state) => {
+    const agentGuardrails = state.agent?.guardrails;
+    return Array.isArray(agentGuardrails) ? agentGuardrails : Array.isArray(opts.guardrails) ? opts.guardrails : [];
+  };
+  const runtime = {
+    name: opts.name,
+    version: opts.version,
+    model: opts.model,
+    tools: toolsBase,
+    guardrails: opts.guardrails,
+    systemPrompt: void 0,
+    limits: opts.limits,
+    useTodoList: void 0,
+    outputSchema: opts.outputSchema,
+    tracing: opts.tracing
+  };
+  async function runLoop(initial, config, emit) {
     let state = await resolver(initial);
+    if (state.ctx?.__paused) {
+      const nextCtx = { ...state.ctx };
+      delete nextCtx.__paused;
+      state = { ...state, ctx: Object.keys(nextCtx).length > 0 ? nextCtx : void 0 };
+    }
+    let resumeStage = null;
+    if (state.ctx?.__resumeStage) {
+      const nextCtx = { ...state.ctx };
+      if (nextCtx.__resumeStage === "tools") {
+        resumeStage = "tools";
+      }
+      delete nextCtx.__resumeStage;
+      state = { ...state, ctx: Object.keys(nextCtx).length > 0 ? nextCtx : void 0 };
+    }
     const maxToolCalls = opts.limits?.maxToolCalls ?? 10;
     const iterationLimit = Math.max(maxToolCalls * 3 + 10, 40);
     let iterations = 0;
+    const onStateChange = config?.onStateChange;
+    const checkpointReason = config?.checkpointReason;
+    let pausedStage = null;
+    const checkpointIfRequested = (stage) => {
+      if (typeof onStateChange !== "function") return false;
+      let result = false;
+      try {
+        result = onStateChange(state);
+      } catch {
+        result = false;
+      }
+      if (!result) return false;
+      const ctx = { ...state.ctx || {} };
+      ctx.__paused = {
+        stage,
+        iteration: iterations,
+        reason: checkpointReason,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      state = { ...state, ctx };
+      pausedStage = stage;
+      return true;
+    };
     while (iterations < iterationLimit) {
       iterations++;
-      state = { ...state, ...await agentCore(state) };
+      const skippingAgent = resumeStage === "tools";
+      if (!skippingAgent) {
+        if (checkpointIfRequested("before_guardrails")) break;
+        const preGuardrails = getGuardrailConfig(state);
+        if (preGuardrails.length > 0) {
+          const store = ensureGuardrailStore(state);
+          if (store.lastRequestLength !== state.messages.length) {
+            const outcome = await evaluateGuardrails({
+              guardrails: preGuardrails,
+              phase: "request" /* Request */,
+              state,
+              runtime: state.agent || runtime,
+              options: opts,
+              emit
+            });
+            store.lastRequestLength = state.messages.length;
+            state.guardrailResult = mergeGuardrailOutcomes(state.guardrailResult, outcome);
+            const blocking = outcome.incidents.find((incident) => incident.disposition === "block");
+            if (blocking) {
+              const guardMessage = {
+                role: "assistant",
+                name: "guardrail",
+                content: blocking.reason || "Request blocked by guardrail policy.",
+                metadata: {
+                  guardrail: {
+                    phase: "request" /* Request */,
+                    incidents: outcome.incidents
+                  }
+                }
+              };
+              state = { ...state, messages: [...state.messages, guardMessage] };
+              const ctx = state.ctx = state.ctx || {};
+              ctx.__guardrailBlocked = {
+                phase: "request" /* Request */,
+                incident: blocking
+              };
+              break;
+            }
+          }
+        }
+        state = { ...state, ...await agentCore(state) };
+        if (checkpointIfRequested("after_agent")) break;
+        const postGuardrails = getGuardrailConfig(state);
+        if (postGuardrails.length > 0) {
+          const store = ensureGuardrailStore(state);
+          if (store.lastResponseLength !== state.messages.length) {
+            const outcome = await evaluateGuardrails({
+              guardrails: postGuardrails,
+              phase: "response" /* Response */,
+              state,
+              runtime: state.agent || runtime,
+              options: opts,
+              emit
+            });
+            store.lastResponseLength = state.messages.length;
+            state.guardrailResult = mergeGuardrailOutcomes(state.guardrailResult, outcome);
+            const blocking = outcome.incidents.find((incident) => incident.disposition === "block");
+            if (blocking) {
+              const updatedMessages = [...state.messages];
+              const replaced = updatedMessages.pop();
+              updatedMessages.push({
+                role: "assistant",
+                name: "guardrail",
+                content: blocking.reason || "Response blocked by guardrail policy.",
+                metadata: {
+                  guardrail: {
+                    phase: "response" /* Response */,
+                    incidents: outcome.incidents,
+                    replaced
+                  }
+                }
+              });
+              state = { ...state, messages: updatedMessages };
+              const ctx = state.ctx = state.ctx || {};
+              ctx.__guardrailBlocked = {
+                phase: "response" /* Response */,
+                incident: blocking,
+                replaced
+              };
+              break;
+            } else if (outcome.incidents.length > 0) {
+              const last = state.messages[state.messages.length - 1];
+              if (last) {
+                last.metadata = {
+                  ...last.metadata || {},
+                  guardrail: {
+                    phase: "response" /* Response */,
+                    incidents: outcome.incidents
+                  }
+                };
+              }
+            }
+          }
+        }
+      } else {
+        resumeStage = null;
+      }
       const lastMsg = state.messages[state.messages.length - 1];
       const toolCalls = Array.isArray(lastMsg?.tool_calls) ? lastMsg.tool_calls : [];
       const toolCallCount = state.toolCallCount || 0;
@@ -612,79 +1895,99 @@ function createAgent(opts) {
       }
       if (toolCalls.length === 0) break;
       state = { ...state, ...await toolsNode(state) };
+      if (state.ctx?.__awaitingApproval) break;
+      if (checkpointIfRequested("after_tools")) break;
       if (state.ctx?.__finalizedDueToStructuredOutput) break;
     }
+    if (!pausedStage && typeof onStateChange === "function" && onStateChange(state)) {
+      checkpointIfRequested("after_loop");
+    }
     return state;
   }
-  const runtime = {
-    name: opts.name,
-    model: opts.model,
-    tools: toolsBase,
-    systemPrompt: void 0,
-    limits: opts.limits,
-    useTodoList: void 0,
-    outputSchema: opts.outputSchema
+  const invokeAgent = async (input, config) => {
+    const onEvent = config?.onEvent;
+    const emit = (e) => {
+      try {
+        onEvent?.(e);
+      } catch {
+      }
+    };
+    const traceSession = createTraceSession(opts);
+    const ctx = { ...input.ctx || {}, __onEvent: onEvent };
+    if (traceSession) ctx.__traceSession = traceSession;
+    const initial = {
+      messages: input.messages || [],
+      toolCallCount: input.toolCallCount || 0,
+      toolCache: input.toolCache || {},
+      toolHistory: input.toolHistory || [],
+      metadata: input.metadata,
+      ctx,
+      pendingApprovals: input.pendingApprovals || [],
+      agent: input.agent || runtime,
+      usage: input.usage || { perRequest: [], totals: {} }
+    };
+    let res;
+    try {
+      res = await runLoop(initial, config, emit);
+    } catch (err) {
+      await finalizeTraceSession(traceSession, {
+        agentRuntime: runtime,
+        status: "error",
+        error: { message: err?.message, stack: err?.stack }
+      });
+      throw err;
+    }
+    await finalizeTraceSession(traceSession, {
+      agentRuntime: res.agent || runtime,
+      status: "success"
+    });
+    const finalMsg = res.messages[res.messages.length - 1];
+    let content = "";
+    if (typeof finalMsg?.content === "string") content = finalMsg.content;
+    else if (Array.isArray(finalMsg?.content)) content = finalMsg.content.map((c) => typeof c === "string" ? c : c?.text ?? c?.content ?? "").join("");
+    let parsed = void 0;
+    const schema = opts.outputSchema;
+    if (schema && res.ctx?.__structuredOutputParsed) {
+      parsed = res.ctx.__structuredOutputParsed;
+    } else if (schema && content) {
+      let jsonText = null;
+      const fenced = content.match(/```(?:json)?\n([\s\S]*?)```/i);
+      if (fenced && fenced[1]) jsonText = fenced[1].trim();
+      else {
+        const braceIdx = content.indexOf("{");
+        const bracketIdx = content.indexOf("[");
+        const start = [braceIdx, bracketIdx].filter((i) => i >= 0).sort((a, b) => a - b)[0];
+        if (start !== void 0) jsonText = content.slice(start).trim();
+      }
+      try {
+        const raw = JSON.parse(jsonText ?? content);
+        parsed = schema.parse(raw);
+      } catch {
+      }
+    }
+    emit({ type: "finalAnswer", content: typeof finalMsg?.content === "string" ? finalMsg.content : content });
+    return {
+      content,
+      output: parsed,
+      metadata: { usage: res.usage },
+      messages: res.messages,
+      state: res
+    };
   };
+  const snapshotState = (state, options) => captureSnapshot(state, options);
+  const resumeAgent = async (snapshot, config, restoreOptions) => {
+    const restoredState = restoreSnapshot(snapshot, restoreOptions);
+    return invokeAgent(restoredState, config);
+  };
+  const resolveToolApproval = (state, resolution) => resolveToolApprovalState(state, resolution);
   const instance = {
-    invoke: async (input, config) => {
-      const onEvent = config?.onEvent;
-      const emit = (e) => {
-        try {
-          onEvent?.(e);
-        } catch {
-        }
-      };
-      const initial = {
-        messages: input.messages || [],
-        summaries: input.summaries || [],
-        toolCallCount: input.toolCallCount || 0,
-        toolCache: input.toolCache || {},
-        toolHistory: input.toolHistory || [],
-        toolHistoryArchived: input.toolHistoryArchived || [],
-        metadata: input.metadata,
-        ctx: { ...input.ctx || {}, __onEvent: onEvent },
-        plan: input.plan || null,
-        planVersion: input.planVersion || 0,
-        agent: input.agent || runtime,
-        usage: input.usage || { perRequest: [], totals: {} }
-      };
-      const res = await runLoop(initial, config);
-      const finalMsg = res.messages[res.messages.length - 1];
-      let content = "";
-      if (typeof finalMsg?.content === "string") content = finalMsg.content;
-      else if (Array.isArray(finalMsg?.content)) content = finalMsg.content.map((c) => typeof c === "string" ? c : c?.text ?? c?.content ?? "").join("");
-      let parsed = void 0;
-      const schema = opts.outputSchema;
-      if (schema && res.ctx?.__structuredOutputParsed) {
-        parsed = res.ctx.__structuredOutputParsed;
-      } else if (schema && content) {
-        let jsonText = null;
-        const fenced = content.match(/```(?:json)?\n([\s\S]*?)```/i);
-        if (fenced && fenced[1]) jsonText = fenced[1].trim();
-        else {
-          const braceIdx = content.indexOf("{");
-          const bracketIdx = content.indexOf("[");
-          const start = [braceIdx, bracketIdx].filter((i) => i >= 0).sort((a, b) => a - b)[0];
-          if (start !== void 0) jsonText = content.slice(start).trim();
-        }
-        try {
-          const raw = JSON.parse(jsonText ?? content);
-          parsed = schema.parse(raw);
-        } catch {
-        }
-      }
-      emit({ type: "finalAnswer", content: typeof finalMsg?.content === "string" ? finalMsg.content : content });
-      return {
-        content,
-        output: parsed,
-        metadata: { usage: res.usage },
-        messages: res.messages,
-        state: res
-      };
-    },
+    invoke: invokeAgent,
+    snapshot: snapshotState,
+    resume: resumeAgent,
+    resolveToolApproval,
     asTool: ({ toolName, description, inputDescription }) => {
-      const schema = import_zod.z.object({ input: import_zod.z.string().describe(inputDescription || "Input for delegated agent") });
-      return createSmartTool({
+      const schema = zod.z.object({ input: zod.z.string().describe(inputDescription || "Input for delegated agent") });
+      return createTool({
         name: toolName,
         description: description || `Delegate task to agent ${opts.name || "Agent"}`,
         schema,
@@ -696,8 +1999,8 @@ function createAgent(opts) {
     },
     asHandoff: ({ toolName, description, schema }) => {
       const finalName = toolName || `handoff_to_${runtime.name || "agent"}`;
-      const zschema = schema || import_zod.z.object({ reason: import_zod.z.string().describe("Reason for handoff") });
-      const tool3 = createSmartTool({
+      const zschema = schema || zod.z.object({ reason: zod.z.string().describe("Reason for handoff") });
+      createTool({
         name: finalName,
         description: description || `Handoff control to agent ${runtime.name || "Agent"}`,
         schema: zschema,
@@ -709,8 +2012,8 @@ function createAgent(opts) {
   };
   if (opts.handoffs && Array.isArray(opts.handoffs)) {
     const handoffTools = opts.handoffs.map((h) => {
-      const schema = h.schema || import_zod.z.object({ reason: import_zod.z.string().describe("Reason for handoff") });
-      return createSmartTool({
+      const schema = h.schema || zod.z.object({ reason: zod.z.string().describe("Reason for handoff") });
+      return createTool({
         name: h.toolName,
         description: h.description || `Handoff to ${h.target.__runtime.name || "agent"}`,
         schema,
@@ -727,6 +2030,7 @@ function createAgentNode(opts) {
   return async (state) => {
     const runtime = state.agent || {
       name: opts.name,
+      version: opts.version,
       model: opts.model,
       tools: opts.tools || [],
       systemPrompt: opts.systemPrompt,
@@ -735,12 +2039,6 @@ function createAgentNode(opts) {
       outputSchema: opts.outputSchema
     };
     const tools = runtime.tools ?? [];
-    const limits = {
-      maxToolCalls: runtime.limits?.maxToolCalls ?? 10,
-      toolOutputTokenLimit: runtime.limits?.toolOutputTokenLimit ?? 5e3,
-      contextTokenLimit: runtime.limits?.contextTokenLimit ?? 6e4,
-      summaryTokenLimit: runtime.limits?.summaryTokenLimit ?? 5e4
-    };
     const modelWithTools = runtime.model?.bindTools ? runtime.model.bindTools(tools) : runtime.model;
     const structuredOutputHint = runtime.outputSchema ? [
       "A structured output schema is active.",
@@ -757,19 +2055,60 @@ function createAgentNode(opts) {
       )
     };
     const messages = [systemMsg, ...state.messages];
-    const debugSession = state.ctx?.__debugSession;
-    const response = await modelWithTools.invoke([systemMsg, ...state.messages]);
+    const traceSession = state.ctx?.__traceSession;
+    const actorName = runtime.name ?? opts.name ?? "agent";
+    const actorVersion = runtime.version ?? opts.version;
+    const start = Date.now();
+    const promptMessages = [systemMsg, ...state.messages];
+    const shouldLogPrompt = !!traceSession && traceSession.resolvedConfig.logData;
+    const promptPayload = shouldLogPrompt ? sanitizeTracePayload(promptMessages) : void 0;
+    const promptBytes = promptPayload !== void 0 ? estimatePayloadBytes(promptPayload) : void 0;
+    let response;
+    try {
+      response = await modelWithTools.invoke(promptMessages);
+    } catch (err) {
+      const durationMs2 = Date.now() - start;
+      recordTraceEvent(traceSession, {
+        type: "ai_call",
+        label: "Assistant Error",
+        actor: { scope: "agent", name: actorName, role: "assistant", version: actorVersion },
+        status: "error",
+        durationMs: durationMs2,
+        requestBytes: promptBytes,
+        model: getModelName(runtime.model || opts.model),
+        provider: getProviderName(runtime.model || opts.model),
+        error: { message: err?.message || String(err), stack: err?.stack },
+        messageList: promptMessages
+      });
+      throw err;
+    }
     const messagesWithResponse = [
       ...messages,
       response
     ];
-    const messagesWithSystem = [
-      systemMsg,
-      ...messagesWithResponse
-    ];
     const rawUsage = response?.usage || response?.response_metadata?.token_usage || response?.response_metadata?.usage;
     const normalized = normalizeUsage(rawUsage);
     const modelName = getModelName(runtime.model || opts.model) || "unknown_model";
+    const providerName = getProviderName(runtime.model || opts.model);
+    const durationMs = Date.now() - start;
+    const shouldLogResponse = !!traceSession && traceSession.resolvedConfig.logData;
+    const responsePayload = shouldLogResponse ? sanitizeTracePayload(response) : void 0;
+    const responseBytes = responsePayload !== void 0 ? estimatePayloadBytes(responsePayload) : void 0;
+    recordTraceEvent(traceSession, {
+      type: "ai_call",
+      label: "Assistant Response",
+      actor: { scope: "agent", name: actorName, role: "assistant", version: actorVersion },
+      durationMs,
+      inputTokens: normalized?.prompt_tokens,
+      outputTokens: normalized?.completion_tokens,
+      totalTokens: normalized?.total_tokens,
+      cachedInputTokens: normalized?.prompt_tokens_details?.cached_tokens,
+      requestBytes: promptBytes,
+      responseBytes,
+      model: modelName,
+      provider: providerName,
+      messageList: messagesWithResponse
+    });
     if (normalized) {
       const usageState = state.usage || { perRequest: [], totals: {} };
       const id = `${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
@@ -790,33 +2129,10 @@ function createAgentNode(opts) {
       };
       state.usage = usageState;
     }
-    if (debugSession) {
-      const idx = bumpStep(debugSession);
-      const fileName = `${String(idx).padStart(2, "0")}.md`;
-      const markdown = formatMarkdown({
-        modelName: getModelName(runtime.model || opts.model),
-        date: (/* @__PURE__ */ new Date()).toISOString(),
-        limits: runtime.limits,
-        // IMPORTANT: log only per-request normalized usage
-        usage: normalized,
-        tools: serializeAgentTools(tools),
-        messages: messagesWithSystem
-      });
-      await writeStepMarkdown(debugSession, fileName, markdown, {
-        messages: messagesWithSystem,
-        usage: normalized,
-        modelName: getModelName(runtime.model || opts.model),
-        limits: runtime.limits,
-        tools: serializeAgentTools(tools)
-      });
-    }
     return { messages: messagesWithResponse, usage: state.usage };
   };
 }
 
-// src/nodes/contextSummarize.ts
-var import_nanoid2 = require("nanoid");
-
 // src/utils/utilTokens.ts
 function countApproxTokens(text) {
   if (!text) return 0;
@@ -830,7 +2146,7 @@ var toolMessage = (name, content, tool_call_id) => ({ role: "tool", name, conten
 function createContextSummarizeNode(opts) {
   return async (state) => {
     const messages = state.messages || [];
-    const summaryTokenLimit = opts.limits?.summaryTokenLimit ?? opts.limits?.summary_token_limit ?? 1e5;
+    const summaryTokenLimit = opts.limits?.summaryTokenLimit ?? 1e5;
     const model = opts.model;
     const archived = state.toolHistoryArchived ? [...state.toolHistoryArchived] : [];
     const live = state.toolHistory ? [...state.toolHistory] : [];
@@ -842,7 +2158,7 @@ function createContextSummarizeNode(opts) {
       if (item.tool_call_id) byCallId.set(item.tool_call_id, item);
     }
     for (const item of live) {
-      if (!item.executionId) item.executionId = (0, import_nanoid2.nanoid)();
+      if (!item.executionId) item.executionId = nanoid.nanoid();
     }
     const getText = (m) => {
       if (!m) return "";
@@ -983,11 +2299,11 @@ Merged summary:`);
           continue;
         }
         const callId = toolMessageObj.tool_call_id;
-        const safeId = callId || `summarized_${(0, import_nanoid2.nanoid)(6)}`;
+        const safeId = callId || `summarized_${nanoid.nanoid(6)}`;
         let hist = callId ? byCallId.get(callId) : void 0;
         if (!hist) {
           hist = {
-            executionId: (0, import_nanoid2.nanoid)(),
+            executionId: nanoid.nanoid(),
             toolName: toolMessageObj.name || "unknown_tool",
             args: null,
             output: typeof toolMessageObj.content === "string" ? toolMessageObj.content : Array.isArray(toolMessageObj.content) ? toolMessageObj.content.map((p) => typeof p === "string" ? p : p?.text ?? p?.content ?? "").join("") : String(toolMessageObj.content ?? ""),
@@ -1001,7 +2317,7 @@ Merged summary:`);
           if (callId) byCallId.set(callId, hist);
           archived.push({ ...hist });
         }
-        if (!hist.executionId) hist.executionId = (0, import_nanoid2.nanoid)();
+        if (!hist.executionId) hist.executionId = nanoid.nanoid();
         hist.summarized = true;
         rewritten.push({
           role: "tool",
@@ -1013,7 +2329,7 @@ Merged summary:`);
       }
       rewritten.push(m);
     }
-    const summarizeCallId = `summarize_${(0, import_nanoid2.nanoid)(6)}`;
+    const summarizeCallId = `summarize_${nanoid.nanoid(6)}`;
     const summarizeArgs = { reason: "Exceeded token limit: summarize prior tool outputs for context." };
     const syntheticAssistant = {
       role: "assistant",
@@ -1024,7 +2340,6 @@ Merged summary:`);
         ]
       }
     };
-    const summaryExecId = (0, import_nanoid2.nanoid)();
     const syntheticToolResp = {
       role: "tool",
       content: `${summaryText}`,
@@ -1053,7 +2368,6 @@ Merged summary:`);
 // src/utils/tokenManager.ts
 async function applyTokenLimits({
   state,
-  model,
   limits
 }) {
   const messages = state.messages || [];
@@ -1063,15 +2377,23 @@ async function applyTokenLimits({
   const newMessages = [...messages];
   return { ...state, messages: newMessages };
 }
-
-// src/contextTools.ts
-var import_tools3 = require("@langchain/core/tools");
-var import_zod2 = require("zod");
 function createContextTools(stateRef, opts) {
   const tools = [];
   if (opts?.planningEnabled) {
-    const manageTodo = (0, import_tools3.tool)(
-      async ({ operation, todoList }) => {
+    const manageTodo = createTool({
+      name: "manage_todo_list",
+      description: "Manage a structured todo list to track progress and plan tasks throughout your coding session. Use this tool VERY frequently to ensure task visibility and proper planning.\n\nWhen to use this tool:\n- Complex multi-step work requiring planning and tracking\n- When user provides multiple tasks or requests (numbered/comma-separated)\n- After receiving new instructions that require multiple steps\n- BEFORE starting work on any todo (mark as in-progress)\n- IMMEDIATELY after completing each todo (mark completed individually)\n- When breaking down larger tasks into smaller actionable steps\n- To give users visibility into your progress and planning\n\nWhen NOT to use:\n- Single, trivial tasks that can be completed in one step\n- Purely conversational/informational requests\n- When just reading files or performing simple searches\n\nCRITICAL workflow:\n1. Plan tasks by writing todo list with specific, actionable items\n2. Complete the work for that specific todo\n3. Mark that todo as completed IMMEDIATELY\n4. Move to next todo and repeat\n\nTodo states:\n- not-started: Todo not yet begun\n- in-progress: Currently working (limit ONE at a time)\n- completed: Finished successfully\n\nIMPORTANT: Mark todos completed as soon as they are done. Do not batch completions.",
+      schema: zod.z.object({
+        operation: zod.z.enum(["write", "read"]),
+        todoList: zod.z.array(zod.z.object({
+          id: zod.z.number().int().positive().describe("Sequential id starting from 1"),
+          title: zod.z.string().min(1),
+          description: zod.z.string().min(1),
+          status: zod.z.enum(["not-started", "in-progress", "completed"]),
+          evidence: zod.z.string().max(200).optional()
+        })).optional()
+      }),
+      func: async ({ operation, todoList }) => {
         const onEvent = manageTodo._stateRef?.__onEvent;
         if (operation === "read") {
           const list = stateRef.todoList || [];
@@ -1088,27 +2410,16 @@ function createContextTools(stateRef, opts) {
         };
         onEvent?.({ type: "plan", source: "manage_todo_list", operation: "write", todoList });
         return payload;
-      },
-      {
-        name: "manage_todo_list",
-        description: "Manage a structured todo list to track progress and plan tasks throughout your coding session. Use this tool VERY frequently to ensure task visibility and proper planning.\n\nWhen to use this tool:\n- Complex multi-step work requiring planning and tracking\n- When user provides multiple tasks or requests (numbered/comma-separated)\n- After receiving new instructions that require multiple steps\n- BEFORE starting work on any todo (mark as in-progress)\n- IMMEDIATELY after completing each todo (mark completed individually)\n- When breaking down larger tasks into smaller actionable steps\n- To give users visibility into your progress and planning\n\nWhen NOT to use:\n- Single, trivial tasks that can be completed in one step\n- Purely conversational/informational requests\n- When just reading files or performing simple searches\n\nCRITICAL workflow:\n1. Plan tasks by writing todo list with specific, actionable items\n2. Complete the work for that specific todo\n3. Mark that todo as completed IMMEDIATELY\n4. Move to next todo and repeat\n\nTodo states:\n- not-started: Todo not yet begun\n- in-progress: Currently working (limit ONE at a time)\n- completed: Finished successfully\n\nIMPORTANT: Mark todos completed as soon as they are done. Do not batch completions.",
-        schema: import_zod2.z.object({
-          operation: import_zod2.z.enum(["write", "read"]),
-          todoList: import_zod2.z.array(import_zod2.z.object({
-            id: import_zod2.z.number().int().positive().describe("Sequential id starting from 1"),
-            title: import_zod2.z.string().min(1),
-            description: import_zod2.z.string().min(1),
-            status: import_zod2.z.enum(["not-started", "in-progress", "completed"]),
-            evidence: import_zod2.z.string().max(200).optional()
-          })).optional()
-        })
       }
-    );
+    });
     manageTodo._stateRef = stateRef;
     tools.push(manageTodo);
   }
-  const getTool = (0, import_tools3.tool)(
-    async ({ executionId }) => {
+  const getTool = createTool({
+    name: "get_tool_response",
+    description: "RETRIEVE tool execution response: Use this to access the full output of a tool execution that shows as 'SUMMARIZED' in the tool history.",
+    schema: zod.z.object({ executionId: zod.z.string().describe("Tool execution id") }),
+    func: async ({ executionId }) => {
       let execution = stateRef.toolHistory?.find((t) => t.executionId === executionId);
       if (!execution) {
         execution = stateRef.toolHistoryArchived?.find((t) => t.executionId === executionId);
@@ -1117,32 +2428,24 @@ function createContextTools(stateRef, opts) {
         return execution.rawOutput || execution.output;
       }
       return "Execution not found. Please check the executionId.";
-    },
-    {
-      name: "get_tool_response",
-      description: "RETRIEVE tool execution response: Use this to access the full output of a tool execution that shows as 'SUMMARIZED' in the tool history.",
-      schema: import_zod2.z.object({ executionId: import_zod2.z.string().describe("Tool execution id") })
     }
-  );
+  });
   getTool._stateRef = stateRef;
   tools.push(getTool);
   if (opts?.outputSchema) {
-    const responseTool = (0, import_tools3.tool)(
-      async (data) => {
+    const responseTool = createTool({
+      name: "response",
+      description: "Finalize the answer by returning the final structured JSON matching the required schema. Call exactly once when you are fully done, then stop.",
+      schema: opts.outputSchema.shape ? opts.outputSchema : zod.z.any(),
+      func: async (data) => {
         try {
           const validated = opts.outputSchema.parse ? opts.outputSchema.parse(data) : data;
           return { __finalStructuredOutput: true, data: validated };
         } catch (e) {
           return { error: "Schema validation failed", details: e?.message };
         }
-      },
-      {
-        name: "response",
-        description: "Finalize the answer by returning the final structured JSON matching the required schema. Call exactly once when you are fully done, then stop.",
-        // Use schema directly; if not Zod, fall back to any-object
-        schema: opts.outputSchema.shape ? opts.outputSchema : import_zod2.z.any()
       }
-    );
+    });
     responseTool._stateRef = stateRef;
     tools.push(responseTool);
   }
@@ -1236,36 +2539,326 @@ function createSmartAgent(opts) {
       }
       return lastResult;
     },
+    snapshot: base.snapshot,
+    resume: base.resume,
+    resolveToolApproval: base.resolveToolApproval,
     asTool: base.asTool,
     asHandoff: base.asHandoff,
     __runtime: base.__runtime
   };
   return instance;
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  applyTokenLimits,
-  buildSystemPrompt,
-  bumpStep,
-  countApproxTokens,
-  createAgent,
-  createAgentNode,
-  createContextSummarizeNode,
-  createContextTools,
-  createDebugSession,
-  createResolverNode,
-  createSmartAgent,
-  createSmartTool,
-  createTool,
-  createToolLimitFinalizeNode,
-  createToolsNode,
-  formatMarkdown,
-  fromLangchainModel,
-  getModelName,
-  isSmartModel,
-  resolveLogsBaseDir,
-  serializeAgentTools,
-  withTools,
-  writeStepMarkdown
+
+// src/utils/content.ts
+function contentToString(content) {
+  try {
+    if (content == null) return "";
+    if (typeof content === "string") return content;
+    if (Array.isArray(content)) {
+      return content.map((p) => {
+        if (!p || typeof p !== "object") return String(p);
+        if (p.type === "text") return String(p.text ?? "");
+        if (p.type === "image_url") {
+          const img = p.image_url;
+          const url = typeof img === "string" ? img : img?.url;
+          const detail = typeof img === "string" ? void 0 : img?.detail;
+          return `[image:${url || "unknown"}${detail ? ` detail=${detail}` : ""}]`;
+        }
+        return JSON.stringify(p);
+      }).join("\n");
+    }
+    return JSON.stringify(content);
+  } catch {
+    return String(content);
+  }
+}
+function mergeContentsToString(contents) {
+  return contents.map((c) => contentToString(c)).join("\n");
+}
+
+// src/guardrails/checks.ts
+var Ajv = AjvModule__default.default?.default ?? AjvModule__default.default;
+var defaultAjv = new Ajv({ allErrors: true });
+defaultAjv.opts.strict = false;
+function ensureRegExp(pattern, flags) {
+  if (pattern instanceof RegExp) return pattern;
+  return new RegExp(pattern, flags ?? "i");
+}
+function latestText(context) {
+  return contentToString(context.latestMessage?.content ?? "");
+}
+function threadText(context) {
+  return mergeContentsToString(context.messages.map((msg) => msg.content));
+}
+function regexRule(options) {
+  const regex = ensureRegExp(options.pattern, options.flags);
+  const selector = options.selector || latestText;
+  const failureMessage = options.failureMessage || `Message violates pattern: ${regex.toString()}`;
+  const matchDisposition = options.matchDisposition || "block";
+  const allowIfMatch = options.allowIfMatch === true;
+  return {
+    id: options.id,
+    title: options.title || "Regex compliance",
+    description: options.description,
+    async evaluate(context) {
+      const text = selector(context) ?? "";
+      const matches = regex.test(text);
+      const passed = allowIfMatch ? matches : !matches;
+      const disposition = matches ? matchDisposition : "allow";
+      return {
+        passed,
+        reason: matches ? failureMessage : void 0,
+        disposition,
+        details: matches ? { pattern: regex.toString(), textSnippet: text.slice(0, 200) } : void 0
+      };
+    }
+  };
+}
+function compileValidator(schema) {
+  if (schema?._def) {
+    const typed = schema;
+    return (input) => {
+      const result = typed.safeParse(input);
+      return {
+        valid: result.success,
+        errors: result.success ? void 0 : result.error.issues.map((issue) => issue.message)
+      };
+    };
+  }
+  const validator = defaultAjv.compile(schema);
+  return (input) => {
+    const valid = validator(input);
+    const errors = validator.errors?.map((err) => {
+      const path2 = "instancePath" in err && typeof err.instancePath === "string" && err.instancePath.length > 0 ? err.instancePath : err.dataPath;
+      return `${path2 || "/"} ${err.message || "invalid"}`;
+    });
+    return { valid: !!valid, errors };
+  };
+}
+function jsonSchemaRule(options) {
+  const selector = options.selector || latestText;
+  const disposition = options.disposition || "block";
+  const validator = compileValidator(options.schema);
+  return {
+    id: options.id,
+    title: options.title || "JSON schema validation",
+    description: options.description,
+    async evaluate(context) {
+      const text = selector(context) ?? "";
+      let parsed;
+      try {
+        parsed = JSON.parse(text);
+      } catch (err) {
+        if (options.allowOnParseError) {
+          return { passed: true };
+        }
+        return {
+          passed: false,
+          disposition,
+          reason: "Message content is not valid JSON.",
+          details: { error: err instanceof Error ? err.message : String(err) }
+        };
+      }
+      const result = validator(parsed);
+      if (result.valid) {
+        return { passed: true };
+      }
+      return {
+        passed: false,
+        disposition,
+        reason: "Message JSON failed schema validation.",
+        details: { errors: result.errors }
+      };
+    }
+  };
+}
+function containsAllowListed(text, allowList) {
+  if (!allowList?.length) return false;
+  return allowList.some((pattern) => ensureRegExp(pattern).test(text));
+}
+var codePattern = /```[\s\S]*?```|\b(function|class|import|export|const|let|var)\b|<[^>]+>/i;
+function codePresenceRule(options = {}) {
+  const selector = options.selector || latestText;
+  const disposition = options.disposition || "warn";
+  return {
+    id: options.id,
+    title: options.title || "Code presence detection",
+    description: options.description,
+    async evaluate(context) {
+      const text = selector(context) ?? "";
+      if (!text) return { passed: true };
+      if (containsAllowListed(text, options.allowList)) {
+        return { passed: true };
+      }
+      const matches = codePattern.test(text);
+      if (!matches) return { passed: true };
+      return {
+        passed: false,
+        disposition,
+        reason: "Potential code content detected in message.",
+        details: { snippet: text.slice(0, 200) }
+      };
+    }
+  };
+}
+var guardianSchema = zod.z.object({
+  allow: zod.z.boolean().describe("Whether the message should be allowed."),
+  disposition: zod.z.enum(["allow", "warn", "block"]).optional(),
+  reason: zod.z.string().max(400, "Reason must be 400 characters or fewer.").optional(),
+  details: zod.z.record(zod.z.any()).optional()
 });
+function defaultPayload(context) {
+  const latest = latestText(context);
+  const transcript = threadText(context);
+  return JSON.stringify(
+    {
+      phase: context.phase,
+      latestMessage: latest,
+      transcript,
+      metadata: {
+        runtime: {
+          name: context.runtime?.name,
+          version: context.runtime?.version
+        }
+      }
+    },
+    null,
+    2
+  );
+}
+function agentVerdictRule(options) {
+  const payloadBuilder = options.payloadBuilder || defaultPayload;
+  const fallbackDisposition = options.dispositionFallback || "block";
+  return {
+    id: options.id,
+    title: options.title || "Agent-based guardrail",
+    description: options.description,
+    async evaluate(context) {
+      const payload = payloadBuilder(context);
+      const systemPrompt = options.systemPrompt || "You are a safety auditor. Review the provided conversation payload and decide whether it should continue. Return JSON with keys allow (boolean), optional disposition ('allow' | 'warn' | 'block'), optional reason (string), and optional details (object).";
+      const review = await options.agent.invoke({
+        messages: [
+          { role: "system", content: systemPrompt },
+          { role: "user", content: payload }
+        ]
+      });
+      let parsed = review.output;
+      if (!parsed) {
+        try {
+          parsed = guardianSchema.parse(JSON.parse(review.content));
+        } catch {
+          parsed = guardianSchema.parse({ allow: false, reason: "Guard agent did not return structured output." });
+        }
+      }
+      const disposition = parsed.disposition || (parsed.allow ? "allow" : fallbackDisposition);
+      return {
+        passed: parsed.allow,
+        disposition,
+        reason: parsed.reason,
+        details: parsed.details
+      };
+    }
+  };
+}
+function customCallbackRule(options) {
+  const fallbackDisposition = options.defaultDisposition || "block";
+  return {
+    id: options.id,
+    title: options.title || "Custom callback guardrail",
+    description: options.description,
+    async evaluate(context) {
+      const outcome = await options.callback(context);
+      if (typeof outcome === "boolean") {
+        return {
+          passed: outcome,
+          disposition: outcome ? "allow" : fallbackDisposition
+        };
+      }
+      return {
+        passed: outcome.allow,
+        disposition: outcome.disposition || (outcome.allow ? "allow" : fallbackDisposition),
+        reason: outcome.reason,
+        details: outcome.details
+      };
+    }
+  };
+}
+
+// src/guardrails/index.ts
+function createRegexGuardrail(pattern, options) {
+  const rule = regexRule({ pattern, ...options?.rule || {} });
+  return createGuardrail({
+    id: options?.guardrailId,
+    title: options?.guardrailTitle || options?.rule?.title || "Regex Guardrail",
+    description: options?.guardrailDescription || options?.rule?.description,
+    appliesTo: options?.phases,
+    checks: [rule],
+    haltOnViolation: options?.haltOnViolation,
+    onViolation: options?.onViolation,
+    metadata: options?.metadata
+  });
+}
+function createJsonGuardrail(schema, options) {
+  const rule = jsonSchemaRule({ schema, ...options?.rule || {} });
+  return createGuardrail({
+    id: options?.guardrailId,
+    title: options?.guardrailTitle || options?.rule?.title || "JSON Schema Guardrail",
+    description: options?.guardrailDescription || options?.rule?.description,
+    appliesTo: options?.phases,
+    checks: [rule],
+    haltOnViolation: options?.haltOnViolation,
+    onViolation: options?.onViolation,
+    metadata: options?.metadata
+  });
+}
+function createCodeGuardrail(options) {
+  const ruleOptions = { disposition: "warn", ...options?.rule || {} };
+  const rule = codePresenceRule(ruleOptions);
+  return createGuardrail({
+    id: options?.guardrailId,
+    title: options?.guardrailTitle || ruleOptions.title || "Code Presence Guardrail",
+    description: options?.guardrailDescription || ruleOptions.description,
+    appliesTo: options?.phases,
+    checks: [rule],
+    haltOnViolation: options?.haltOnViolation,
+    onViolation: options?.onViolation,
+    metadata: options?.metadata
+  });
+}
+
+exports.GuardrailPhase = GuardrailPhase;
+exports.agentVerdictRule = agentVerdictRule;
+exports.applyTokenLimits = applyTokenLimits;
+exports.buildSystemPrompt = buildSystemPrompt;
+exports.captureSnapshot = captureSnapshot;
+exports.codePresenceRule = codePresenceRule;
+exports.cognipeerSink = cognipeerSink;
+exports.countApproxTokens = countApproxTokens;
+exports.createAgent = createAgent;
+exports.createAgentNode = createAgentNode;
+exports.createCodeGuardrail = createCodeGuardrail;
+exports.createContextSummarizeNode = createContextSummarizeNode;
+exports.createContextTools = createContextTools;
+exports.createGuardrail = createGuardrail;
+exports.createJsonGuardrail = createJsonGuardrail;
+exports.createRegexGuardrail = createRegexGuardrail;
+exports.createResolverNode = createResolverNode;
+exports.createSmartAgent = createSmartAgent;
+exports.createTool = createTool;
+exports.createToolLimitFinalizeNode = createToolLimitFinalizeNode;
+exports.createToolsNode = createToolsNode;
+exports.customCallbackRule = customCallbackRule;
+exports.customSink = customSink;
+exports.evaluateGuardrails = evaluateGuardrails;
+exports.fileSink = fileSink;
+exports.fromLangchainModel = fromLangchainModel;
+exports.fromLangchainTools = fromLangchainTools;
+exports.httpSink = httpSink;
+exports.isSmartModel = isSmartModel;
+exports.jsonSchemaRule = jsonSchemaRule;
+exports.regexRule = regexRule;
+exports.resolveToolApprovalState = resolveToolApprovalState;
+exports.restoreSnapshot = restoreSnapshot;
+exports.withTools = withTools;
+//# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map