@prompty/core 2.0.0-alpha.5 → 2.0.0-alpha.7

package/dist/index.js

@@ -2220,7 +2220,12 @@ var init_property = __esm({
           for (const [key, value] of Object.entries(
             data
           )) {
-            if (value && typeof value === "object" && !Array.isArray(value)) {
+            if (Array.isArray(value)) {
+              throw new Error(
+                `Invalid 'properties' format: key '${key}' has an array value. 'properties' must be a flat list of objects or a name-keyed dict \u2014 not a nested { ${key}: [...] } structure.`
+              );
+            }
+            if (value && typeof value === "object") {
               value["name"] = key;
               result.push(Property.load(value, context));
             } else {
@@ -3128,7 +3133,12 @@ var init_tool = __esm({
           for (const [key, value] of Object.entries(
             data
           )) {
-            if (value && typeof value === "object" && !Array.isArray(value)) {
+            if (Array.isArray(value)) {
+              throw new Error(
+                `Invalid 'bindings' format: key '${key}' has an array value. 'bindings' must be a flat list of objects or a name-keyed dict \u2014 not a nested { ${key}: [...] } structure.`
+              );
+            }
+            if (value && typeof value === "object") {
               value["name"] = key;
               result.push(Binding.load(value, context));
             } else {
@@ -3343,7 +3353,12 @@ var init_tool = __esm({
           for (const [key, value] of Object.entries(
             data
           )) {
-            if (value && typeof value === "object" && !Array.isArray(value)) {
+            if (Array.isArray(value)) {
+              throw new Error(
+                `Invalid 'parameters' format: key '${key}' has an array value. 'parameters' must be a flat list of objects or a name-keyed dict \u2014 not a nested { ${key}: [...] } structure.`
+              );
+            }
+            if (value && typeof value === "object") {
               value["name"] = key;
               result.push(Property.load(value, context));
             } else {
@@ -4100,7 +4115,12 @@ var init_prompty = __esm({
           for (const [key, value] of Object.entries(
             data
           )) {
-            if (value && typeof value === "object" && !Array.isArray(value)) {
+            if (Array.isArray(value)) {
+              throw new Error(
+                `Invalid 'inputs' format: key '${key}' has an array value. 'inputs' must be a flat list of objects or a name-keyed dict \u2014 not a nested { ${key}: [...] } structure.`
+              );
+            }
+            if (value && typeof value === "object") {
               value["name"] = key;
               result.push(Property.load(value, context));
             } else {
@@ -4130,7 +4150,12 @@ var init_prompty = __esm({
           for (const [key, value] of Object.entries(
             data
           )) {
-            if (value && typeof value === "object" && !Array.isArray(value)) {
+            if (Array.isArray(value)) {
+              throw new Error(
+                `Invalid 'outputs' format: key '${key}' has an array value. 'outputs' must be a flat list of objects or a name-keyed dict \u2014 not a nested { ${key}: [...] } structure.`
+              );
+            }
+            if (value && typeof value === "object") {
               value["name"] = key;
               result.push(Property.load(value, context));
             } else {
@@ -4160,7 +4185,12 @@ var init_prompty = __esm({
           for (const [key, value] of Object.entries(
             data
           )) {
-            if (value && typeof value === "object" && !Array.isArray(value)) {
+            if (Array.isArray(value)) {
+              throw new Error(
+                `Invalid 'tools' format: key '${key}' has an array value. 'tools' must be a flat list of objects or a name-keyed dict \u2014 not a nested { ${key}: [...] } structure.`
+              );
+            }
+            if (value && typeof value === "object") {
               value["name"] = key;
               result.push(Tool.load(value, context));
             } else {
@@ -4499,6 +4529,9 @@ var init_common = __esm({
 
 // src/core/tool-dispatch.ts
 import { dirname as dirname2, resolve as resolve2 } from "path";
+function registerTool(name, handler) {
+  nameRegistry.set(name, handler);
+}
 function getTool(name) {
   return nameRegistry.get(name);
 }
@@ -4522,12 +4555,12 @@ async function dispatchTool(toolName, args, userTools, agent, parentInputs) {
       const result = await registeredFn(args);
       return typeof result === "string" ? result : JSON.stringify(result);
     }
-    const tool = agent.tools?.find((t) => t.name === toolName);
-    if (!tool) {
+    const tool2 = agent.tools?.find((t) => t.name === toolName);
+    if (!tool2) {
       const available = Object.keys(userTools).sort().join(", ") || "(none)";
       return `Error: tool "${toolName}" not found in userTools or agent.tools. Available user tools: ${available}`;
     }
-    const kind = tool.kind || "*";
+    const kind = tool2.kind || "*";
     let handler;
     try {
       handler = getToolHandler(kind);
@@ -4539,7 +4572,7 @@ async function dispatchTool(toolName, args, userTools, agent, parentInputs) {
       }
     }
     return await handler.executeTool(
-      tool,
+      tool2,
       args,
       agent,
       parentInputs
@@ -4564,36 +4597,36 @@ var init_tool_dispatch = __esm({
     nameRegistry = /* @__PURE__ */ new Map();
     toolHandlers = /* @__PURE__ */ new Map();
     FunctionToolHandler = class {
-      async executeTool(tool, _args, _agent, _parentInputs) {
-        const name = tool.name ?? "unknown";
+      async executeTool(tool2, _args, _agent, _parentInputs) {
+        const name = tool2.name ?? "unknown";
         throw new Error(
-          `Function tool '${name}' declared but no callable provided. Pass it via tools: { '${name}': fn } in invokeAgent().`
+          `Function tool '${name}' declared but no callable provided. Pass it via tools: { '${name}': fn } in turn().`
         );
       }
     };
     PromptyToolHandler = class {
-      async executeTool(tool, args, agent, _parentInputs) {
+      async executeTool(tool2, args, agent, _parentInputs) {
         const { load: load2 } = await Promise.resolve().then(() => (init_loader(), loader_exports));
-        const { prepare: prepare2, run: run2, invokeAgent: invokeAgent2 } = await Promise.resolve().then(() => (init_pipeline(), pipeline_exports));
+        const { prepare: prepare2, run: run2, turn: turn2 } = await Promise.resolve().then(() => (init_pipeline(), pipeline_exports));
         const parentPath = (agent.metadata ?? {}).__source_path;
         if (!parentPath) {
-          return `Error: cannot resolve PromptyTool '${tool.name}': parent has no __source_path`;
+          return `Error: cannot resolve PromptyTool '${tool2.name}': parent has no __source_path`;
         }
-        const childPath = resolve2(dirname2(parentPath), tool.path);
+        const childPath = resolve2(dirname2(parentPath), tool2.path);
         const stack = (agent.metadata ?? {}).__prompty_tool_stack ?? [];
         const normalizedChild = resolve2(childPath);
         const visited = /* @__PURE__ */ new Set([...stack.map((p) => resolve2(p)), resolve2(parentPath)]);
         if (visited.has(normalizedChild)) {
           const chain = [...stack, parentPath, childPath].join(" \u2192 ");
-          return `Error executing PromptyTool '${tool.name}': circular reference detected: ${chain}`;
+          return `Error executing PromptyTool '${tool2.name}': circular reference detected: ${chain}`;
         }
         try {
           const child = load2(childPath);
           if (!child.metadata) child.metadata = {};
           child.metadata.__prompty_tool_stack = [...stack, parentPath];
-          const mode = tool.mode ?? "single";
+          const mode = tool2.mode ?? "single";
           if (mode === "agentic") {
-            const result = await invokeAgent2(child, args);
+            const result = await turn2(child, args);
             return typeof result === "string" ? result : JSON.stringify(result);
           } else {
             const messages = await prepare2(child, args);
@@ -4601,7 +4634,7 @@ var init_tool_dispatch = __esm({
             return typeof result === "string" ? result : JSON.stringify(result);
           }
         } catch (err) {
-          return `Error executing PromptyTool '${tool.name}': ${err instanceof Error ? err.message : String(err)}`;
+          return `Error executing PromptyTool '${tool2.name}': ${err instanceof Error ? err.message : String(err)}`;
         }
       }
     };
@@ -4628,6 +4661,205 @@ var init_tool_dispatch = __esm({
   }
 });
 
+// src/core/agent-events.ts
+function emitEvent(callback, eventType, data) {
+  if (!callback) return;
+  try {
+    callback(eventType, data);
+  } catch (err) {
+    if (typeof globalThis.console?.debug === "function") {
+      globalThis.console.debug(`Event callback error for ${eventType}:`, err);
+    }
+  }
+}
+var init_agent_events = __esm({
+  "src/core/agent-events.ts"() {
+    "use strict";
+  }
+});
+
+// src/core/cancellation.ts
+function checkCancellation(signal) {
+  if (signal?.aborted) {
+    throw new CancelledError();
+  }
+}
+var CancelledError;
+var init_cancellation = __esm({
+  "src/core/cancellation.ts"() {
+    "use strict";
+    CancelledError = class extends Error {
+      constructor(message = "Agent loop cancelled") {
+        super(message);
+        this.name = "CancelledError";
+      }
+    };
+  }
+});
+
+// src/core/context.ts
+function estimateChars(messages) {
+  let total = 0;
+  for (const msg of messages) {
+    total += msg.role.length + 4;
+    for (const part of msg.parts) {
+      if (part.kind === "text") {
+        total += part.value.length;
+      } else {
+        total += 200;
+      }
+    }
+    const toolCalls = msg.metadata?.tool_calls;
+    if (toolCalls) {
+      total += JSON.stringify(toolCalls).length;
+    }
+  }
+  return total;
+}
+function truncate(text2, maxLen = 200) {
+  return text2.length <= maxLen ? text2 : text2.slice(0, maxLen) + "\u2026";
+}
+function summarizeDropped(messages) {
+  const lines = [];
+  for (const msg of messages) {
+    const msgText = msg.text.trim();
+    if (msg.role === "user" && msgText) {
+      lines.push(`User asked: ${truncate(msgText)}`);
+    } else if (msg.role === "assistant") {
+      if (msgText) lines.push(`Assistant: ${truncate(msgText)}`);
+      const toolCalls = msg.metadata?.tool_calls;
+      if (Array.isArray(toolCalls)) {
+        const names = toolCalls.map(
+          (tc) => tc.name ?? (tc.function?.name ?? "?")
+        );
+        lines.push(`  Called tools: ${names.join(", ")}`);
+      }
+    }
+  }
+  if (lines.length === 0) return "";
+  let result = "[Context summary: ";
+  for (const line of lines) {
+    if (result.length + line.length > 4e3) {
+      result += "\n... (older messages omitted)";
+      break;
+    }
+    result += line + "\n";
+  }
+  return result.trimEnd() + "]";
+}
+function trimToContextWindow(messages, budgetChars) {
+  if (estimateChars(messages) <= budgetChars) {
+    return [0, []];
+  }
+  let systemEnd = 0;
+  for (let i = 0; i < messages.length; i++) {
+    if (messages[i].role !== "system") {
+      systemEnd = i;
+      break;
+    }
+    if (i === messages.length - 1) systemEnd = messages.length;
+  }
+  const systemMsgs = messages.slice(0, systemEnd);
+  const rest = messages.slice(systemEnd);
+  const summaryBudget = Math.min(5e3, Math.floor(budgetChars * 0.05));
+  const dropped = [];
+  while (estimateChars([...systemMsgs, ...rest]) > budgetChars - summaryBudget && rest.length > 2) {
+    dropped.push(rest.shift());
+  }
+  const droppedCount = dropped.length;
+  messages.length = 0;
+  messages.push(...systemMsgs);
+  if (droppedCount > 0) {
+    const summaryText = summarizeDropped(dropped);
+    if (summaryText) {
+      messages.push(new Message("user", [{ kind: "text", value: summaryText }]));
+    }
+  }
+  messages.push(...rest);
+  return [droppedCount, dropped];
+}
+var init_context2 = __esm({
+  "src/core/context.ts"() {
+    "use strict";
+    init_types();
+  }
+});
+
+// src/core/guardrails.ts
+var GuardrailError, Guardrails;
+var init_guardrails = __esm({
+  "src/core/guardrails.ts"() {
+    "use strict";
+    GuardrailError = class extends Error {
+      reason;
+      constructor(reason) {
+        super(`Guardrail denied: ${reason}`);
+        this.name = "GuardrailError";
+        this.reason = reason;
+      }
+    };
+    Guardrails = class {
+      inputHook;
+      outputHook;
+      toolHook;
+      constructor(options) {
+        this.inputHook = options?.input;
+        this.outputHook = options?.output;
+        this.toolHook = options?.tool;
+      }
+      checkInput(messages) {
+        if (!this.inputHook) return { allowed: true };
+        return this.inputHook(messages);
+      }
+      checkOutput(message) {
+        if (!this.outputHook) return { allowed: true };
+        return this.outputHook(message);
+      }
+      checkTool(name, args) {
+        if (!this.toolHook) return { allowed: true };
+        return this.toolHook(name, args);
+      }
+    };
+  }
+});
+
+// src/core/structured.ts
+function createStructuredResult(data, rawJson) {
+  const result = { ...data };
+  Object.defineProperty(result, StructuredResultSymbol, {
+    value: rawJson,
+    writable: false,
+    enumerable: false,
+    configurable: false
+  });
+  return result;
+}
+function isStructuredResult(value) {
+  return typeof value === "object" && value !== null && StructuredResultSymbol in value;
+}
+function cast(result, validator) {
+  let jsonStr;
+  if (isStructuredResult(result)) {
+    jsonStr = result[StructuredResultSymbol];
+  } else if (typeof result === "string") {
+    jsonStr = result;
+  } else {
+    jsonStr = JSON.stringify(result);
+  }
+  const parsed = JSON.parse(jsonStr);
+  if (validator) {
+    return validator(parsed);
+  }
+  return parsed;
+}
+var StructuredResultSymbol;
+var init_structured = __esm({
+  "src/core/structured.ts"() {
+    "use strict";
+    StructuredResultSymbol = /* @__PURE__ */ Symbol("prompty.rawJson");
+  }
+});
+
 // src/core/pipeline.ts
 var pipeline_exports = {};
 __export(pipeline_exports, {
@@ -4639,6 +4871,7 @@ __export(pipeline_exports, {
   render: () => render,
   resolveBindings: () => resolveBindings,
   run: () => run,
+  turn: () => turn,
   validateInputs: () => validateInputs
 });
 function sanitizeNonces(value) {
@@ -4829,129 +5062,27 @@ async function invoke(prompt, inputs, options) {
     emit("description", "Invoke a prompty");
     emit("inputs", { prompt: serializeAgent(agent), inputs: inputs ?? {} });
     const messages = await prepare(agent, inputs);
-    const result = await run(agent, messages, options);
-    emit("result", result);
-    return result;
-  });
-}
-function resolveBindings(agent, toolName, args, parentInputs) {
-  if (!parentInputs || !agent.tools || agent.tools.length === 0) return args;
-  const toolDef = agent.tools.find((t) => t.name === toolName);
-  if (!toolDef || !toolDef.bindings || toolDef.bindings.length === 0) return args;
-  const merged = { ...args };
-  for (const binding of toolDef.bindings) {
-    if (binding.input in parentInputs) {
-      merged[binding.name] = parentInputs[binding.input];
-    }
-  }
-  return merged;
-}
-function isAsyncIterable(value) {
-  return value != null && typeof value === "object" && Symbol.asyncIterator in value;
-}
-function isToolCallLike(item) {
-  return typeof item === "object" && item !== null && "id" in item && "name" in item && "arguments" in item;
-}
-async function consumeStream(agent, response) {
-  const processed = await process2(agent, response);
-  const toolCalls = [];
-  const textParts = [];
-  if (isAsyncIterable(processed)) {
-    for await (const item of processed) {
-      if (isToolCallLike(item)) {
-        toolCalls.push(item);
-      } else if (typeof item === "string") {
-        textParts.push(item);
+    const provider = resolveProvider(agent);
+    const executor = getExecutor(provider);
+    const response = await executor.execute(agent, messages);
+    if (options?.raw) {
+      emit("result", response);
+      if (options?.validator) {
+        return cast(response, options.validator);
       }
+      return response;
     }
-  } else if (typeof processed === "string") {
-    textParts.push(processed);
-  }
-  return { toolCalls, content: textParts.join("") };
-}
-async function buildToolMessagesFromCalls(toolCalls, textContent, tools, agent, parentInputs, parentEmit) {
-  const provider = resolveProvider(agent);
-  const apiType = agent.model?.apiType || "chat";
-  const messages = [];
-  const toolInputs = [];
-  if (provider === "anthropic") {
-    const rawContent = [];
-    if (textContent) rawContent.push({ type: "text", text: textContent });
-    for (const tc of toolCalls) {
-      rawContent.push({
-        type: "tool_use",
-        id: tc.id,
-        name: tc.name,
-        input: JSON.parse(tc.arguments)
-      });
-    }
-    messages.push(
-      new Message("assistant", textContent ? [text(textContent)] : [], { content: rawContent })
-    );
-  } else if (apiType === "responses") {
-    for (const tc of toolCalls) {
-      messages.push(
-        new Message("assistant", [], {
-          responses_function_call: {
-            type: "function_call",
-            call_id: tc.id,
-            name: tc.name,
-            arguments: tc.arguments
-          }
-        })
-      );
-    }
-  } else {
-    const rawToolCalls = toolCalls.map((tc) => ({
-      id: tc.id,
-      type: "function",
-      function: { name: tc.name, arguments: tc.arguments }
-    }));
-    messages.push(
-      new Message("assistant", textContent ? [text(textContent)] : [], {
-        tool_calls: rawToolCalls
-      })
-    );
-  }
-  const toolResultBlocks = [];
-  for (const tc of toolCalls) {
-    let result;
-    let parsedArgs;
-    try {
-      parsedArgs = JSON.parse(tc.arguments);
-      if (parentInputs && typeof parsedArgs === "object" && parsedArgs !== null && !Array.isArray(parsedArgs)) {
-        parsedArgs = resolveBindings(agent, tc.name, parsedArgs, parentInputs);
-      }
-      result = await traceSpan(tc.name, async (toolEmit) => {
-        toolEmit("signature", `prompty.tool.${tc.name}`);
-        toolEmit("description", `Execute tool: ${tc.name}`);
-        toolEmit("inputs", { arguments: parsedArgs, id: tc.id });
-        const r = await dispatchTool(tc.name, parsedArgs, tools, agent, parentInputs ?? {});
-        toolEmit("result", r);
-        return r;
-      });
-    } catch (err) {
-      result = `Error: ${err instanceof Error ? err.message : String(err)}`;
-    }
-    toolInputs.push({ name: tc.name, arguments: parsedArgs, id: tc.id, result });
-    if (provider === "anthropic") {
-      toolResultBlocks.push({ type: "tool_result", tool_use_id: tc.id, content: result });
-    } else {
-      messages.push(
-        new Message("tool", [text(result)], { tool_call_id: tc.id, name: tc.name })
-      );
+    const result = await process2(agent, response);
+    emit("result", result);
+    if (options?.validator) {
+      return cast(result, options.validator);
     }
-  }
-  if (provider === "anthropic" && toolResultBlocks.length > 0) {
-    messages.push(new Message("user", [], { tool_results: toolResultBlocks }));
-  }
-  if (parentEmit) {
-    parentEmit("inputs", { tool_calls: toolInputs });
-  }
-  return messages;
+    return result;
+  });
 }
-async function invokeAgent(prompt, inputs, options) {
-  return traceSpan("invokeAgent", async (emit) => {
+async function turn(prompt, inputs, options) {
+  const label = options?.turn != null ? `turn ${options.turn}` : "turn";
+  const rawResult = await traceSpan(label, async (emit) => {
     const agent = typeof prompt === "string" ? await traceSpan("load", async (loadEmit) => {
       loadEmit("signature", "prompty.load");
       loadEmit("description", "Load a prompty file.");
@@ -4960,23 +5091,126 @@ async function invokeAgent(prompt, inputs, options) {
       loadEmit("result", serializeAgent(loaded));
       return loaded;
     }) : prompt;
+    emit("signature", "prompty.turn");
+    emit("description", label);
+    emit("inputs", sanitizeValue("inputs", inputs));
     const tools = options?.tools ?? {};
+    const hasTools = Object.keys(tools).length > 0;
+    if (!hasTools) {
+      let messages2 = await prepare(agent, inputs);
+      const onEvent2 = options?.onEvent;
+      if (options?.steering) {
+        const pending = options.steering.drain();
+        if (pending.length > 0) {
+          messages2.push(...pending);
+          emitEvent(onEvent2, "messages_updated", { messages: messages2 });
+        }
+      }
+      if (options?.contextBudget !== void 0) {
+        const [droppedCount] = trimToContextWindow(messages2, options.contextBudget);
+        if (droppedCount > 0) {
+          emitEvent(onEvent2, "messages_updated", { messages: messages2 });
+        }
+      }
+      if (options?.guardrails) {
+        const result = options.guardrails.checkInput(messages2);
+        if (!result.allowed) {
+          emitEvent(onEvent2, "error", { message: `Input guardrail denied: ${result.reason}` });
+          throw new GuardrailError(result.reason ?? "Input guardrail denied");
+        }
+        if (result.rewrite) messages2 = result.rewrite;
+      }
+      checkCancellation(options?.signal);
+      const provider2 = resolveProvider(agent);
+      const executor2 = getExecutor(provider2);
+      const response2 = await executor2.execute(agent, messages2);
+      if (options?.raw) {
+        emit("result", response2);
+        return response2;
+      }
+      const processed = await process2(agent, response2);
+      if (options?.guardrails) {
+        const contentStr = typeof processed === "string" ? processed : JSON.stringify(processed);
+        const assistantMsg = new Message("assistant", [text(contentStr)]);
+        const gr = options.guardrails.checkOutput(assistantMsg);
+        if (!gr.allowed) {
+          emitEvent(onEvent2, "error", { message: `Output guardrail denied: ${gr.reason}` });
+          throw new GuardrailError(gr.reason ?? "Output guardrail denied");
+        }
+        if (gr.rewrite !== void 0) {
+          emit("result", gr.rewrite);
+          emitEvent(onEvent2, "done", { response: gr.rewrite, messages: messages2 });
+          return gr.rewrite;
+        }
+      }
+      emit("result", sanitizeValue("result", processed));
+      emitEvent(onEvent2, "done", { response: processed, messages: messages2 });
+      return processed;
+    }
     const maxIterations = options?.maxIterations ?? DEFAULT_MAX_ITERATIONS;
-    emit("signature", "prompty.invokeAgent");
-    emit("description", "Invoke a prompty with tool calling");
-    emit("inputs", { prompt: serializeAgent(agent), tools: Object.keys(tools), inputs: inputs ?? {} });
-    const messages = await prepare(agent, inputs);
+    const onEvent = options?.onEvent;
+    const signal = options?.signal;
+    const contextBudget = options?.contextBudget;
+    const guardrails = options?.guardrails;
+    const steering = options?.steering;
+    const parallelToolCalls = options?.parallelToolCalls ?? false;
+    let messages = await prepare(agent, inputs);
     const parentInputs = inputs ?? {};
     const provider = resolveProvider(agent);
     const executor = getExecutor(provider);
-    let response = await executor.execute(agent, messages);
+    let response = null;
     let iteration = 0;
     while (true) {
+      try {
+        checkCancellation(signal);
+      } catch (err) {
+        emitEvent(onEvent, "cancelled", {});
+        throw err;
+      }
+      if (steering) {
+        const pending = steering.drain();
+        if (pending.length > 0) {
+          messages.push(...pending);
+          emitEvent(onEvent, "messages_updated", { messages });
+          emitEvent(onEvent, "status", { message: `Injected ${pending.length} steering message(s)` });
+        }
+      }
+      if (contextBudget !== void 0) {
+        const [droppedCount] = trimToContextWindow(messages, contextBudget);
+        if (droppedCount > 0) {
+          emitEvent(onEvent, "messages_updated", { messages });
+          emitEvent(onEvent, "status", { message: `Trimmed ${droppedCount} messages for context budget` });
+        }
+      }
+      if (guardrails) {
+        const result = guardrails.checkInput(messages);
+        if (!result.allowed) {
+          emitEvent(onEvent, "error", { message: `Input guardrail denied: ${result.reason}` });
+          throw new GuardrailError(result.reason ?? "Input guardrail denied");
+        }
+        if (result.rewrite) messages = result.rewrite;
+      }
+      try {
+        checkCancellation(signal);
+      } catch (err) {
+        emitEvent(onEvent, "cancelled", {});
+        throw err;
+      }
+      response = await executor.execute(agent, messages);
       if (isAsyncIterable(response)) {
-        const { toolCalls, content } = await consumeStream(agent, response);
+        const { toolCalls, content } = await consumeStream(agent, response, onEvent);
+        if (guardrails && content) {
+          const assistantMsg = new Message("assistant", [text(content)]);
+          const gr = guardrails.checkOutput(assistantMsg);
+          if (!gr.allowed) {
+            emitEvent(onEvent, "error", { message: `Output guardrail denied: ${gr.reason}` });
+            throw new GuardrailError(gr.reason ?? "Output guardrail denied");
+          }
+        }
         if (toolCalls.length === 0) {
           emit("iterations", iteration);
           emit("result", content);
+          emitEvent(onEvent, "done", { response: content, messages });
           return content;
         }
         iteration++;
@@ -4986,17 +5220,57 @@ async function invokeAgent(prompt, inputs, options) {
           );
         }
         const toolMessages2 = await traceSpan("toolCalls", async (toolEmit) => {
-          toolEmit("signature", "prompty.invokeAgent.toolCalls");
+          toolEmit("signature", "prompty.turn.toolCalls");
           toolEmit("description", `Tool call round ${iteration}`);
-          const result2 = await buildToolMessagesFromCalls(toolCalls, content, tools, agent, parentInputs, toolEmit);
-          toolEmit("result", result2.map((m) => ({ role: m.role, content: m.parts.map((p) => p.value ?? "").join(""), metadata: m.metadata })));
-          return result2;
+          const result = await buildToolMessagesFromCallsWithExtensions(
+            toolCalls,
+            content,
+            tools,
+            agent,
+            parentInputs,
+            toolEmit,
+            { onEvent, signal, guardrails, parallel: parallelToolCalls }
+          );
+          toolEmit("result", result.map((m) => ({ role: m.role, content: m.parts.map((p) => p.value ?? "").join(""), metadata: m.metadata })));
+          return result;
         });
         messages.push(...toolMessages2);
-        response = await executor.execute(agent, messages);
+        emitEvent(onEvent, "messages_updated", { messages });
         continue;
       }
-      if (!hasToolCalls(response)) break;
+      if (!hasToolCalls(response)) {
+        const finalResult = options?.raw ? response : await process2(agent, response);
+        if (guardrails) {
+          const contentStr = typeof finalResult === "string" ? finalResult : JSON.stringify(finalResult);
+          const assistantMsg = new Message("assistant", [text(contentStr)]);
+          const gr = guardrails.checkOutput(assistantMsg);
+          if (!gr.allowed) {
+            emitEvent(onEvent, "error", { message: `Output guardrail denied: ${gr.reason}` });
+            throw new GuardrailError(gr.reason ?? "Output guardrail denied");
+          }
+          if (gr.rewrite !== void 0) {
+            emit("iterations", iteration);
+            emit("result", gr.rewrite);
+            emitEvent(onEvent, "done", { response: gr.rewrite, messages });
+            return gr.rewrite;
+          }
+        }
+        emit("iterations", iteration);
+        emit("result", finalResult);
+        emitEvent(onEvent, "done", { response: finalResult, messages });
+        return finalResult;
+      }
+      if (guardrails) {
+        const { textContent } = extractToolInfo(response);
+        if (textContent) {
+          const assistantMsg = new Message("assistant", [text(textContent)]);
+          const gr = guardrails.checkOutput(assistantMsg);
+          if (!gr.allowed) {
+            emitEvent(onEvent, "error", { message: `Output guardrail denied: ${gr.reason}` });
+            throw new GuardrailError(gr.reason ?? "Output guardrail denied");
+          }
+        }
+      }
       iteration++;
       if (iteration > maxIterations) {
         throw new Error(
@@ -5004,24 +5278,64 @@ async function invokeAgent(prompt, inputs, options) {
         );
       }
       const toolMessages = await traceSpan("toolCalls", async (toolEmit) => {
-        toolEmit("signature", "prompty.invokeAgent.toolCalls");
+        toolEmit("signature", "prompty.turn.toolCalls");
         toolEmit("description", `Tool call round ${iteration}`);
-        const result2 = await buildToolResultMessages(response, tools, agent, parentInputs, toolEmit);
-        toolEmit("result", result2.map((m) => ({ role: m.role, content: m.parts.map((p) => p.value ?? "").join(""), metadata: m.metadata })));
-        return result2;
+        const result = await buildToolResultMessagesWithExtensions(
+          response,
+          tools,
+          agent,
+          parentInputs,
+          toolEmit,
+          { onEvent, signal, guardrails, parallel: parallelToolCalls }
+        );
+        toolEmit("result", result.map((m) => ({ role: m.role, content: m.parts.map((p) => p.value ?? "").join(""), metadata: m.metadata })));
+        return result;
       });
       messages.push(...toolMessages);
-      response = await executor.execute(agent, messages);
+      emitEvent(onEvent, "messages_updated", { messages });
     }
-    emit("iterations", iteration);
-    if (options?.raw) {
-      emit("result", response);
-      return response;
-    }
-    const result = await process2(agent, response);
-    emit("result", result);
-    return result;
   });
+  if (options?.validator) {
+    return cast(rawResult, options.validator);
+  }
+  return rawResult;
+}
+function resolveBindings(agent, toolName, args, parentInputs) {
+  if (!parentInputs || !agent.tools || agent.tools.length === 0) return args;
+  const toolDef = agent.tools.find((t) => t.name === toolName);
+  if (!toolDef || !toolDef.bindings || toolDef.bindings.length === 0) return args;
+  const merged = { ...args };
+  for (const binding of toolDef.bindings) {
+    if (binding.input in parentInputs) {
+      merged[binding.name] = parentInputs[binding.input];
+    }
+  }
+  return merged;
+}
+function isAsyncIterable(value) {
+  return value != null && typeof value === "object" && Symbol.asyncIterator in value;
+}
+function isToolCallLike(item) {
+  return typeof item === "object" && item !== null && "id" in item && "name" in item && "arguments" in item;
+}
+async function consumeStream(agent, response, onEvent) {
+  const processed = await process2(agent, response);
+  const toolCalls = [];
+  const textParts = [];
+  if (isAsyncIterable(processed)) {
+    for await (const item of processed) {
+      if (isToolCallLike(item)) {
+        toolCalls.push(item);
+      } else if (typeof item === "string") {
+        textParts.push(item);
+        emitEvent(onEvent, "token", { token: item });
+      }
+    }
+  } else if (typeof processed === "string") {
+    textParts.push(processed);
+    emitEvent(onEvent, "token", { token: processed });
+  }
+  return { toolCalls, content: textParts.join("") };
 }
 function expandThreads(messages, nonces, inputs) {
   if (nonces.size === 0) return messages;
@@ -5090,160 +5404,138 @@ function hasToolCalls(response) {
   }
   return false;
 }
-async function buildToolResultMessages(response, tools, agent, parentInputs, parentEmit) {
+function extractToolInfo(response) {
+  if (typeof response !== "object" || response === null) {
+    return { toolCalls: [], textContent: "" };
+  }
   const r = response;
   if (Array.isArray(r.content) && r.stop_reason === "tool_use") {
-    return buildAnthropicToolResultMessages(r, tools, agent, parentInputs, parentEmit);
+    const content = r.content;
+    const toolCalls = content.filter((b) => b.type === "tool_use").map((b) => ({
+      id: b.id,
+      name: b.name,
+      arguments: JSON.stringify(b.input)
+    }));
+    const textContent = content.filter((b) => b.type === "text").map((b) => b.text).join("");
+    return { toolCalls, textContent };
   }
   if (r.object === "response" && Array.isArray(r.output)) {
-    return buildResponsesToolResultMessages(r, tools, agent, parentInputs, parentEmit);
+    const funcCalls = r.output.filter(
+      (item) => item.type === "function_call"
+    );
+    const toolCalls = funcCalls.map((fc) => ({
+      id: fc.call_id ?? fc.id ?? "",
+      call_id: fc.call_id ?? fc.id ?? "",
+      name: fc.name,
+      arguments: fc.arguments ?? "{}"
+    }));
+    return { toolCalls, textContent: "" };
   }
-  return buildOpenAIToolResultMessages(r, tools, agent, parentInputs, parentEmit);
-}
-async function buildOpenAIToolResultMessages(r, tools, agent, parentInputs, parentEmit) {
   const choices = r.choices;
-  const choice = choices[0];
-  const message = choice.message;
-  const toolCalls = message.tool_calls;
-  const messages = [];
-  const assistantContent = message.content ?? "";
-  messages.push(
-    new Message("assistant", assistantContent ? [text(assistantContent)] : [], {
-      tool_calls: toolCalls
-    })
-  );
-  const toolInputs = [];
-  for (const tc of toolCalls) {
-    const fn = tc.function;
-    const toolName = fn.name;
-    const toolCallId = tc.id;
-    let result;
-    let parsedArgs;
-    try {
-      parsedArgs = JSON.parse(fn.arguments);
-      if (agent && parentInputs && typeof parsedArgs === "object" && parsedArgs !== null && !Array.isArray(parsedArgs)) {
-        parsedArgs = resolveBindings(agent, toolName, parsedArgs, parentInputs);
-      }
-      result = await traceSpan(toolName, async (toolEmit) => {
-        toolEmit("signature", `prompty.tool.${toolName}`);
-        toolEmit("description", `Execute tool: ${toolName}`);
-        toolEmit("inputs", { arguments: parsedArgs, tool_call_id: toolCallId });
-        const r2 = await dispatchTool(toolName, parsedArgs, tools, agent ?? {}, parentInputs ?? {});
-        toolEmit("result", r2);
-        return r2;
+  if (Array.isArray(choices) && choices.length > 0) {
+    const choice = choices[0];
+    const message = choice.message;
+    if (message && Array.isArray(message.tool_calls)) {
+      const toolCalls = message.tool_calls.map((tc) => {
+        const fn = tc.function;
+        return {
+          id: tc.id,
+          name: fn.name,
+          arguments: fn.arguments
+        };
       });
-    } catch (err) {
-      result = `Error: ${err instanceof Error ? err.message : String(err)}`;
+      return { toolCalls, textContent: message.content ?? "" };
     }
-    toolInputs.push({ name: toolName, arguments: parsedArgs, tool_call_id: toolCallId, result });
-    messages.push(
-      new Message("tool", [text(result)], {
-        tool_call_id: toolCallId,
-        name: toolName
-      })
-    );
-  }
-  if (parentEmit) {
-    parentEmit("inputs", { tool_calls: toolInputs });
   }
-  return messages;
+  return { toolCalls: [], textContent: "" };
 }
-async function buildAnthropicToolResultMessages(r, tools, agent, parentInputs, parentEmit) {
-  const content = r.content;
-  const toolUseBlocks = content.filter((block) => block.type === "tool_use");
-  const messages = [];
-  const textParts = content.filter((block) => block.type === "text").map((block) => text(block.text));
-  messages.push(
-    new Message("assistant", textParts, { content })
-  );
-  const toolInputs = [];
-  const toolResultBlocks = [];
-  for (const block of toolUseBlocks) {
-    const toolName = block.name;
-    const toolCallId = block.id;
-    let toolArgs = block.input;
-    if (agent && parentInputs && typeof toolArgs === "object" && toolArgs !== null && !Array.isArray(toolArgs)) {
-      toolArgs = resolveBindings(agent, toolName, toolArgs, parentInputs);
-    }
-    let result;
+async function dispatchOneToolWithExtensions(tc, tools, agent, parentInputs, ext) {
+  const { onEvent, signal, guardrails } = ext;
+  try {
+    checkCancellation(signal);
+  } catch (err) {
+    emitEvent(onEvent, "cancelled", {});
+    throw err;
+  }
+  emitEvent(onEvent, "tool_call_start", { name: tc.name, arguments: tc.arguments });
+  if (guardrails) {
+    let parsedArgs2 = {};
     try {
-      result = await traceSpan(toolName, async (toolEmit) => {
-        toolEmit("signature", `prompty.tool.${toolName}`);
-        toolEmit("description", `Execute tool: ${toolName}`);
-        toolEmit("inputs", { arguments: toolArgs, tool_use_id: toolCallId });
-        const r2 = await dispatchTool(toolName, toolArgs, tools, agent ?? {}, parentInputs ?? {});
-        toolEmit("result", r2);
-        return r2;
-      });
-    } catch (err) {
-      result = `Error: ${err instanceof Error ? err.message : String(err)}`;
+      const parsed = JSON.parse(tc.arguments);
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        parsedArgs2 = parsed;
+      }
+    } catch {
+    }
+    const gr = guardrails.checkTool(tc.name, parsedArgs2);
+    if (!gr.allowed) {
+      const deniedMsg = `Tool denied by guardrail: ${gr.reason}`;
+      emitEvent(onEvent, "tool_result", { name: tc.name, result: deniedMsg });
+      return deniedMsg;
+    }
+    if (gr.rewrite !== void 0) {
+      tc = { ...tc, arguments: typeof gr.rewrite === "string" ? gr.rewrite : JSON.stringify(gr.rewrite) };
     }
-    toolInputs.push({ name: toolName, arguments: toolArgs, tool_use_id: toolCallId, result });
-    toolResultBlocks.push({
-      type: "tool_result",
-      tool_use_id: toolCallId,
-      content: result
-    });
   }
-  if (parentEmit) {
-    parentEmit("inputs", { tool_calls: toolInputs });
+  let result;
+  let parsedArgs;
+  try {
+    parsedArgs = JSON.parse(tc.arguments);
+    if (agent && parentInputs && typeof parsedArgs === "object" && parsedArgs !== null && !Array.isArray(parsedArgs)) {
+      parsedArgs = resolveBindings(agent, tc.name, parsedArgs, parentInputs);
+    }
+    result = await traceSpan(tc.name, async (toolEmit) => {
+      toolEmit("signature", `prompty.tool.${tc.name}`);
+      toolEmit("description", `Execute tool: ${tc.name}`);
+      toolEmit("inputs", { arguments: parsedArgs, id: tc.id });
+      const r = await dispatchTool(tc.name, parsedArgs, tools, agent, parentInputs);
+      toolEmit("result", r);
+      return r;
+    });
+  } catch (err) {
+    if (err instanceof CancelledError) throw err;
+    result = `Error: ${err instanceof Error ? err.message : String(err)}`;
   }
-  messages.push(
-    new Message("user", [], { tool_results: toolResultBlocks })
-  );
-  return messages;
+  emitEvent(onEvent, "tool_result", { name: tc.name, result });
+  return result;
 }
-async function buildResponsesToolResultMessages(r, tools, agent, parentInputs, parentEmit) {
-  const output = r.output;
-  const funcCalls = output.filter((item) => item.type === "function_call");
-  const messages = [];
-  const toolInputs = [];
-  for (const fc of funcCalls) {
-    const toolName = fc.name;
-    const callId = fc.call_id ?? fc.id ?? "";
-    const argsStr = fc.arguments ?? "{}";
-    messages.push(
-      new Message("assistant", [], {
-        responses_function_call: {
-          type: "function_call",
-          call_id: callId,
-          name: toolName,
-          arguments: argsStr
-        }
-      })
-    );
-    let result;
-    let parsedArgs;
-    try {
-      parsedArgs = JSON.parse(argsStr);
-      if (agent && parentInputs && typeof parsedArgs === "object" && parsedArgs !== null && !Array.isArray(parsedArgs)) {
-        parsedArgs = resolveBindings(agent, toolName, parsedArgs, parentInputs);
-      }
-      result = await traceSpan(toolName, async (toolEmit) => {
-        toolEmit("signature", `prompty.tool.${toolName}`);
-        toolEmit("description", `Execute tool: ${toolName}`);
-        toolEmit("inputs", { arguments: parsedArgs, call_id: callId });
-        const r2 = await dispatchTool(toolName, parsedArgs, tools, agent ?? {}, parentInputs ?? {});
-        toolEmit("result", r2);
-        return r2;
-      });
-    } catch (err) {
-      result = `Error: ${err instanceof Error ? err.message : String(err)}`;
-    }
-    toolInputs.push({ name: toolName, arguments: parsedArgs, call_id: callId, result });
-    messages.push(
-      new Message("tool", [text(result)], {
-        tool_call_id: callId,
-        name: toolName
-      })
+async function dispatchToolsWithExtensions(toolCalls, tools, agent, parentInputs, ext) {
+  if (ext.parallel && toolCalls.length > 1) {
+    return Promise.all(
+      toolCalls.map((tc) => dispatchOneToolWithExtensions(tc, tools, agent, parentInputs, ext))
     );
   }
+  const results = [];
+  for (const tc of toolCalls) {
+    results.push(await dispatchOneToolWithExtensions(tc, tools, agent, parentInputs, ext));
+  }
+  return results;
+}
+async function buildToolResultMessagesWithExtensions(response, tools, agent, parentInputs, parentEmit, ext) {
+  const { toolCalls, textContent } = extractToolInfo(response);
+  const toolResults = await dispatchToolsWithExtensions(toolCalls, tools, agent, parentInputs, ext);
   if (parentEmit) {
-    parentEmit("inputs", { tool_calls: toolInputs });
+    parentEmit("inputs", {
+      tool_calls: toolCalls.map((tc, i) => ({ name: tc.name, arguments: tc.arguments, id: tc.id, result: toolResults[i] }))
+    });
+  }
+  const provider = resolveProvider(agent);
+  const executor = getExecutor(provider);
+  return executor.formatToolMessages(response, toolCalls, toolResults, textContent);
+}
+async function buildToolMessagesFromCallsWithExtensions(toolCalls, textContent, tools, agent, parentInputs, parentEmit, ext) {
+  const normalizedCalls = toolCalls.map((tc) => ({ id: tc.id, name: tc.name, arguments: tc.arguments }));
+  const toolResults = await dispatchToolsWithExtensions(normalizedCalls, tools, agent, parentInputs, ext);
+  if (parentEmit) {
+    parentEmit("inputs", {
+      tool_calls: normalizedCalls.map((tc, i) => ({ name: tc.name, arguments: tc.arguments, id: tc.id, result: toolResults[i] }))
+    });
   }
-  return messages;
+  const provider = resolveProvider(agent);
+  const executor = getExecutor(provider);
+  return executor.formatToolMessages(null, normalizedCalls, toolResults, textContent);
 }
-var DEFAULT_FORMAT, DEFAULT_PARSER, DEFAULT_PROVIDER, DEFAULT_MAX_ITERATIONS;
+var DEFAULT_FORMAT, DEFAULT_PARSER, DEFAULT_PROVIDER, DEFAULT_MAX_ITERATIONS, invokeAgent;
 var init_pipeline = __esm({
   "src/core/pipeline.ts"() {
     "use strict";
@@ -5253,10 +5545,16 @@ var init_pipeline = __esm({
     init_tracer();
     init_loader();
     init_tool_dispatch();
+    init_agent_events();
+    init_cancellation();
+    init_context2();
+    init_guardrails();
+    init_structured();
     DEFAULT_FORMAT = "nunjucks";
     DEFAULT_PARSER = "prompty";
     DEFAULT_PROVIDER = "openai";
     DEFAULT_MAX_ITERATIONS = 10;
+    invokeAgent = turn;
   }
 });
 
@@ -5286,6 +5584,101 @@ function clearConnections() {
 init_loader();
 init_pipeline();
 init_tool_dispatch();
+init_agent_events();
+init_cancellation();
+init_context2();
+init_guardrails();
+
+// src/core/steering.ts
+init_types();
+var Steering = class {
+  queue = [];
+  /** Enqueue a message to be injected at the next iteration. */
+  send(message) {
+    this.queue.push(message);
+  }
+  /** Remove and return all queued messages as Message objects. */
+  drain() {
+    const items = this.queue.splice(0);
+    return items.map((text2) => new Message("user", [{ kind: "text", value: text2 }]));
+  }
+  /** Whether there are pending messages without consuming them. */
+  get hasPending() {
+    return this.queue.length > 0;
+  }
+};
+
+// src/core/tool-decorator.ts
+init_tool();
+init_property();
+init_tool_dispatch();
+function tool(fn, options) {
+  const toolName = options?.name ?? fn.name;
+  const toolDesc = options?.description ?? "";
+  const shouldRegister = options?.register !== false;
+  const properties = (options?.parameters ?? []).map(
+    (p) => new Property({
+      name: p.name,
+      kind: p.kind ?? "string",
+      required: p.required ?? p.default === void 0,
+      description: p.description,
+      default: p.default
+    })
+  );
+  const toolDef = new FunctionTool({
+    name: toolName,
+    kind: "function",
+    description: toolDesc,
+    parameters: properties
+  });
+  const wrapped = fn;
+  wrapped.__tool__ = toolDef;
+  if (shouldRegister) {
+    registerTool(toolName, fn);
+  }
+  return wrapped;
+}
+function bindTools(agent, tools) {
+  const handlers = {};
+  for (const fn of tools) {
+    const toolDef = fn.__tool__;
+    if (!toolDef) {
+      throw new Error(
+        `Function '${fn.name || "(anonymous)"}' is not a tool()-wrapped function (missing __tool__ property)`
+      );
+    }
+    const name = toolDef.name;
+    if (name in handlers) {
+      throw new Error(`Duplicate tool handler: '${name}'`);
+    }
+    handlers[name] = fn;
+  }
+  const declaredFunctionTools = /* @__PURE__ */ new Set();
+  for (const toolDef of agent.tools ?? []) {
+    if (toolDef.kind === "function") {
+      declaredFunctionTools.add(toolDef.name);
+    }
+  }
+  for (const name of Object.keys(handlers)) {
+    if (!declaredFunctionTools.has(name)) {
+      const declared = [...declaredFunctionTools].sort().join(", ") || "(none)";
+      throw new Error(
+        `Tool handler '${name}' has no matching 'kind: function' declaration in agent.tools. Declared function tools: ${declared}`
+      );
+    }
+  }
+  for (const name of declaredFunctionTools) {
+    if (!(name in handlers)) {
+      console.warn(
+        `Tool '${name}' is declared in agent.tools but no handler was provided to bindTools()`
+      );
+    }
+  }
+  return handlers;
+}
+
+// src/core/index.ts
+init_structured();
 
 // src/renderers/nunjucks.ts
 init_common();
@@ -5678,11 +6071,14 @@ export {
   ApiKeyConnection,
   ArrayProperty,
   Binding,
+  CancelledError,
   Connection,
   CustomTool,
   FormatConfig,
   FoundryConnection,
   FunctionTool,
+  GuardrailError,
+  Guardrails,
   InvokerError,
   LoadContext,
   McpApprovalMode,
@@ -5708,15 +6104,23 @@ export {
   ReferenceConnection,
   RemoteConnection,
   SaveContext,
+  Steering,
+  StructuredResultSymbol,
   Template,
   ThreadMarker,
   Tool,
   Tracer,
+  bindTools,
+  cast,
+  checkCancellation,
   clearCache,
   clearConnections,
   consoleTracer,
+  createStructuredResult,
   dictContentToPart,
   dictToMessage,
+  emitEvent,
+  estimateChars,
   getConnection,
   getExecutor,
   getParser,
@@ -5724,6 +6128,7 @@ export {
   getRenderer,
   invoke,
   invokeAgent,
+  isStructuredResult,
   load,
   otelTracer,
   parse,
@@ -5738,12 +6143,16 @@ export {
   resolveBindings,
   run,
   sanitizeValue,
+  summarizeDropped,
   text,
   textMessage,
   toSerializable,
+  tool,
   trace,
   traceMethod,
   traceSpan,
+  trimToContextWindow,
+  turn,
   validateInputs
 };
 //# sourceMappingURL=index.js.map