@prompty/core 2.0.0-alpha.4 → 2.0.0-alpha.6

package/dist/index.d.cts

@@ -2055,6 +2055,16 @@ interface Parser {
  */
 interface Executor {
     execute(agent: Prompty, messages: Message[]): Promise<unknown>;
+    /**
+     * Format tool call results into provider-specific message format.
+     * Called after tool dispatch; the pipeline provides extracted tool calls
+     * and their string results.
+     */
+    formatToolMessages(rawResponse: unknown, toolCalls: {
+        id: string;
+        name: string;
+        arguments: string;
+    }[], toolResults: string[], textContent?: string): Message[];
 }
 /**
  * Extracts clean results from raw LLM responses.
@@ -2137,11 +2147,86 @@ declare function clearConnections(): void;
  */
 declare function load(path: string): Prompty;
 
+/**
+ * §13.1 Agent Loop Events — structured event callbacks.
+ * @module
+ */
+/** Event types emitted during the agent loop. */
+type AgentEventType = "token" | "thinking" | "tool_call_start" | "tool_result" | "status" | "messages_updated" | "done" | "error" | "cancelled";
+/** Callback signature for agent loop events. */
+type EventCallback = (eventType: AgentEventType, data: Record<string, unknown>) => void;
+/**
+ * Safely emit an event. Swallows errors from callback (spec §13.1:
+ * event callbacks MUST NOT block the loop).
+ */
+declare function emitEvent(callback: EventCallback | undefined, eventType: AgentEventType, data: Record<string, unknown>): void;
+
+/**
+ * §13.4 Guardrails — optional validation hooks for the agent loop.
+ * @module
+ */
+
+/** Result of a guardrail check. */
+interface GuardrailResult {
+    allowed: boolean;
+    reason?: string;
+    rewrite?: any;
+}
+/** Error thrown when a guardrail denies the operation. */
+declare class GuardrailError extends Error {
+    reason: string;
+    constructor(reason: string);
+}
+/** Input guardrail hook signature. */
+type InputGuardrail = (messages: Message[]) => GuardrailResult;
+/** Output guardrail hook signature. */
+type OutputGuardrail = (message: Message) => GuardrailResult;
+/** Tool guardrail hook signature. */
+type ToolGuardrail = (name: string, args: Record<string, unknown>) => GuardrailResult;
+/** Configuration for guardrail hooks. */
+interface GuardrailsOptions {
+    input?: InputGuardrail;
+    output?: OutputGuardrail;
+    tool?: ToolGuardrail;
+}
+/**
+ * Guardrails with input, output, and tool hooks.
+ * All hooks are optional — when not set, execution proceeds normally.
+ */
+declare class Guardrails {
+    private inputHook?;
+    private outputHook?;
+    private toolHook?;
+    constructor(options?: GuardrailsOptions);
+    checkInput(messages: Message[]): GuardrailResult;
+    checkOutput(message: Message): GuardrailResult;
+    checkTool(name: string, args: Record<string, unknown>): GuardrailResult;
+}
+
+/**
+ * §13.5 Steering — inject user messages into a running agent loop.
+ * @module
+ */
+
+/**
+ * A handle for injecting user messages into a running agent loop.
+ * Thread-safe in the JS single-threaded model (no locking needed).
+ */
+declare class Steering {
+    private queue;
+    /** Enqueue a message to be injected at the next iteration. */
+    send(message: string): void;
+    /** Remove and return all queued messages as Message objects. */
+    drain(): Message[];
+    /** Whether there are pending messages without consuming them. */
+    get hasPending(): boolean;
+}
+
 /**
  * Four-step execution pipeline.
  *
  * ```
- * execute(prompt, inputs)              → top-level orchestrator
+ * invoke(prompt, inputs)               → top-level orchestrator
  *   ├── prepare(agent, inputs)         → template → wire format
  *   │     ├── render(agent, inputs)    → template + inputs → rendered string
  *   │     └── parse(agent, rendered)   → rendered string → Message[]
@@ -2190,10 +2275,25 @@ declare function run(agent: Prompty, messages: Message[], options?: {
 }): Promise<unknown>;
 /**
  * Full pipeline: load → prepare → run.
+ *
+ * @overload Untyped — returns `unknown`.
  */
-declare function execute(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: {
+declare function invoke(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: {
     raw?: boolean;
 }): Promise<unknown>;
+/**
+ * Full pipeline with typed result: load → prepare → run → cast.
+ *
+ * When a `validator` is provided the raw result is deserialized from JSON
+ * and passed through the validator (e.g. a Zod `.parse` function), giving
+ * you a fully typed return value.
+ *
+ * @overload Typed — returns `Promise<T>`.
+ */
+declare function invoke<T>(prompt: string | Prompty, inputs: Record<string, unknown> | undefined, options: {
+    raw?: boolean;
+    validator: (data: unknown) => T;
+}): Promise<T>;
 /**
  * Resolve tool bindings: inject values from parentInputs into tool arguments.
  *
@@ -2201,15 +2301,194 @@ declare function execute(prompt: string | Prompty, inputs?: Record<string, unkno
  * and sets `args[binding.name]` to that value. Returns a new args object.
  */
 declare function resolveBindings(agent: Prompty, toolName: string, args: Record<string, unknown>, parentInputs?: Record<string, unknown>): Record<string, unknown>;
-/**
- * Run a prompt with automatic tool-call execution loop.
- */
-declare function executeAgent(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: {
+/** Options for {@link invokeAgent}. */
+interface InvokeAgentOptions {
     tools?: Record<string, (...args: unknown[]) => unknown>;
     maxIterations?: number;
     raw?: boolean;
-}): Promise<unknown>;
-declare const runAgent: typeof executeAgent;
+    onEvent?: EventCallback;
+    signal?: AbortSignal;
+    contextBudget?: number;
+    guardrails?: Guardrails;
+    steering?: Steering;
+    parallelToolCalls?: boolean;
+}
+/**
+ * Run a prompt with automatic tool-call execution loop.
+ *
+ * Supports §13 extensions: events, cancellation, context window
+ * management, guardrails, steering, and parallel tool calls.
+ *
+ * @overload Untyped — returns `unknown`.
+ */
+declare function invokeAgent(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: InvokeAgentOptions): Promise<unknown>;
+/**
+ * Run a prompt with automatic tool-call execution loop, returning a typed result.
+ *
+ * When a `validator` is provided in the options the final result is
+ * deserialized from JSON and passed through the validator.
+ *
+ * @overload Typed — returns `Promise<T>`.
+ */
+declare function invokeAgent<T>(prompt: string | Prompty, inputs: Record<string, unknown> | undefined, options: InvokeAgentOptions & {
+    validator: (data: unknown) => T;
+}): Promise<T>;
+
+/**
+ * §13.2 Cancellation — cooperative cancellation via AbortSignal.
+ * @module
+ */
+/**
+ * Error thrown when the agent loop is cancelled.
+ */
+declare class CancelledError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Check if the signal is aborted, and throw CancelledError if so.
+ */
+declare function checkCancellation(signal?: AbortSignal): void;
+
+/**
+ * §13.3 Context Window Management — trimming and summarization.
+ * @module
+ */
+
+/**
+ * Estimate the character cost of a message list.
+ * Per spec §13.3: role + 4 overhead per message, text parts by length,
+ * non-text parts at 200-char estimate.
+ */
+declare function estimateChars(messages: Message[]): number;
+/**
+ * Build a compact string summary from dropped messages.
+ */
+declare function summarizeDropped(messages: Message[]): string;
+/**
+ * Trim messages in-place to fit within a character budget.
+ * Returns [droppedCount, droppedMessages].
+ */
+declare function trimToContextWindow(messages: Message[], budgetChars: number): [number, Message[]];
+
+/**
+ * `tool()` wrapper for typed tool functions (spec §11.2).
+ *
+ * Creates a FunctionTool definition from a function's metadata and
+ * auto-registers it in the global tool name registry.
+ *
+ * @module
+ */
+
+/** Options for the tool() wrapper. */
+interface ToolOptions {
+    /** Override the tool name (defaults to fn.name). */
+    name?: string;
+    /** Override the description. */
+    description?: string;
+    /** Parameter definitions (since JS can't introspect type hints). */
+    parameters?: ToolParameter[];
+    /** If false, skip global registration. Default: true. */
+    register?: boolean;
+}
+/** A parameter definition for a tool function. */
+interface ToolParameter {
+    name: string;
+    kind?: string;
+    description?: string;
+    required?: boolean;
+    default?: unknown;
+}
+/** Extended function with __tool__ metadata. */
+interface ToolFunction<T extends (...args: unknown[]) => unknown = (...args: unknown[]) => unknown> {
+    (...args: Parameters<T>): ReturnType<T>;
+    __tool__: FunctionTool;
+}
+/**
+ * Wrap a function as a typed tool.
+ *
+ * Unlike Python's @tool which can introspect type hints, the JS version
+ * requires explicit parameter definitions. The function itself is returned
+ * unchanged but with a `__tool__` property containing the FunctionTool.
+ *
+ * @example
+ * ```ts
+ * const getWeather = tool(
+ *   (city: string, units?: string) => `72°F in ${city}`,
+ *   {
+ *     name: "get_weather",
+ *     description: "Get the current weather",
+ *     parameters: [
+ *       { name: "city", kind: "string", required: true },
+ *       { name: "units", kind: "string", default: "celsius" },
+ *     ],
+ *   },
+ * );
+ *
+ * getWeather.__tool__; // FunctionTool instance
+ * getWeather("NYC");   // "72°F in NYC"
+ * ```
+ */
+declare function tool<T extends (...args: unknown[]) => unknown>(fn: T, options?: ToolOptions): ToolFunction<T>;
+/**
+ * Validate tool handlers against an agent's tool declarations and return a handler record.
+ *
+ * Each function must have a `__tool__` property (set by `tool()`). `bindTools` matches
+ * each handler's name against `kind: "function"` tools declared in `agent.tools`,
+ * raising on mismatches and warning on missing handlers.
+ *
+ * @param agent - A loaded Prompty agent (has `.tools` property)
+ * @param tools - Array of `tool()`-wrapped functions
+ * @returns Handler record suitable for `invokeAgent(..., { tools: result })`
+ * @throws Error if a handler has no `__tool__` property or no matching declaration
+ */
+declare function bindTools(agent: {
+    tools?: Array<{
+        name: string;
+        kind?: string;
+    }>;
+}, tools: Array<ToolFunction>): Record<string, (...args: unknown[]) => unknown>;
+
+/**
+ * Structured result casting for typed LLM output.
+ *
+ * When a processor parses structured JSON from an LLM response, it wraps
+ * the result in a `StructuredResult` that carries both the parsed data
+ * (accessible as normal properties) and the raw JSON string (hidden behind
+ * a Symbol). The `cast()` function lets callers deserialize directly from
+ * the raw JSON, optionally running a validator (e.g., Zod `.parse`).
+ *
+ * @module
+ */
+/**
+ * Symbol used to store the raw JSON string on a StructuredResult.
+ * Using a Symbol keeps the raw JSON invisible to normal property iteration.
+ */
+declare const StructuredResultSymbol: unique symbol;
+/**
+ * A plain object carrying structured output from an LLM.
+ * Behaves like a normal Record<string, unknown> but also stores the raw JSON
+ * string so that cast() can deserialize directly to typed objects.
+ */
+interface StructuredResult extends Record<string, unknown> {
+    readonly [StructuredResultSymbol]: string;
+}
+/**
+ * Create a StructuredResult wrapping parsed data + raw JSON.
+ */
+declare function createStructuredResult(data: Record<string, unknown>, rawJson: string): StructuredResult;
+/**
+ * Type guard: is this value a StructuredResult?
+ */
+declare function isStructuredResult(value: unknown): value is StructuredResult;
+/**
+ * Cast a result to a typed object. When the result is a StructuredResult,
+ * deserializes directly from the raw JSON (no intermediate round-trip).
+ *
+ * @param result - The result to cast (StructuredResult, string, or object)
+ * @param validator - Optional runtime validator (e.g., Zod .parse)
+ * @returns The typed result
+ */
+declare function cast<T = Record<string, unknown>>(result: unknown, validator?: (data: unknown) => T): T;
 
 /**
  * Nunjucks renderer — Jinja2-compatible template rendering for TypeScript.
@@ -2470,4 +2749,4 @@ interface OtelTracerOptions {
  */
 declare function otelTracer(api: OtelApi, options?: OtelTracerOptions): TracerFactory;
 
-export { Prompty as AgentDefinition, AnonymousConnection, ApiKeyConnection, ArrayProperty, type AudioPart, Binding, Connection, type ContentPart, CustomTool, type Executor, type FilePart, FormatConfig, FoundryConnection, FunctionTool, type ImagePart, InvokerError, LoadContext, McpApprovalMode, McpTool, Message, Model, ModelOptions, MustacheRenderer, NunjucksRenderer, OAuthConnection, ObjectProperty, OpenApiTool, type OtelApi, type OtelTracerOptions, type Parser, ParserConfig, type Processor, Prompty as PromptAgent, Prompty, PromptyChatParser, PromptyStream, PromptyTool, PromptyTracer, Property, RICH_KINDS, ROLES, ReferenceConnection, RemoteConnection, type Renderer, type Role, SaveContext, type SpanEmitter, Template, type TextPart, ThreadMarker, Tool, type ToolCall, Tracer, type TracerBackend, type TracerFactory, clearCache, clearConnections, consoleTracer, dictContentToPart, dictToMessage, execute, executeAgent, getConnection, getExecutor, getParser, getProcessor, getRenderer, load, otelTracer, parse, prepare, process, registerConnection, registerExecutor, registerParser, registerProcessor, registerRenderer, render, resolveBindings, run, runAgent, sanitizeValue, text, textMessage, toSerializable, trace, traceMethod, traceSpan, validateInputs };
+export { Prompty as AgentDefinition, type AgentEventType, AnonymousConnection, ApiKeyConnection, ArrayProperty, type AudioPart, Binding, CancelledError, Connection, type ContentPart, CustomTool, type EventCallback, type Executor, type FilePart, FormatConfig, FoundryConnection, FunctionTool, GuardrailError, type GuardrailResult, Guardrails, type GuardrailsOptions, type ImagePart, type InputGuardrail, type InvokeAgentOptions, InvokerError, LoadContext, McpApprovalMode, McpTool, Message, Model, ModelOptions, MustacheRenderer, NunjucksRenderer, OAuthConnection, ObjectProperty, OpenApiTool, type OtelApi, type OtelTracerOptions, type OutputGuardrail, type Parser, ParserConfig, type Processor, Prompty as PromptAgent, Prompty, PromptyChatParser, PromptyStream, PromptyTool, PromptyTracer, Property, RICH_KINDS, ROLES, ReferenceConnection, RemoteConnection, type Renderer, type Role, SaveContext, type SpanEmitter, Steering, type StructuredResult, StructuredResultSymbol, Template, type TextPart, ThreadMarker, Tool, type ToolCall, type ToolFunction, type ToolGuardrail, type ToolOptions, type ToolParameter, Tracer, type TracerBackend, type TracerFactory, bindTools, cast, checkCancellation, clearCache, clearConnections, consoleTracer, createStructuredResult, dictContentToPart, dictToMessage, emitEvent, estimateChars, getConnection, getExecutor, getParser, getProcessor, getRenderer, invoke, invokeAgent, isStructuredResult, load, otelTracer, parse, prepare, process, registerConnection, registerExecutor, registerParser, registerProcessor, registerRenderer, render, resolveBindings, run, sanitizeValue, summarizeDropped, text, textMessage, toSerializable, tool, trace, traceMethod, traceSpan, trimToContextWindow, validateInputs };

package/dist/index.d.ts

@@ -2055,6 +2055,16 @@ interface Parser {
  */
 interface Executor {
     execute(agent: Prompty, messages: Message[]): Promise<unknown>;
+    /**
+     * Format tool call results into provider-specific message format.
+     * Called after tool dispatch; the pipeline provides extracted tool calls
+     * and their string results.
+     */
+    formatToolMessages(rawResponse: unknown, toolCalls: {
+        id: string;
+        name: string;
+        arguments: string;
+    }[], toolResults: string[], textContent?: string): Message[];
 }
 /**
  * Extracts clean results from raw LLM responses.
@@ -2137,11 +2147,86 @@ declare function clearConnections(): void;
  */
 declare function load(path: string): Prompty;
 
+/**
+ * §13.1 Agent Loop Events — structured event callbacks.
+ * @module
+ */
+/** Event types emitted during the agent loop. */
+type AgentEventType = "token" | "thinking" | "tool_call_start" | "tool_result" | "status" | "messages_updated" | "done" | "error" | "cancelled";
+/** Callback signature for agent loop events. */
+type EventCallback = (eventType: AgentEventType, data: Record<string, unknown>) => void;
+/**
+ * Safely emit an event. Swallows errors from callback (spec §13.1:
+ * event callbacks MUST NOT block the loop).
+ */
+declare function emitEvent(callback: EventCallback | undefined, eventType: AgentEventType, data: Record<string, unknown>): void;
+
+/**
+ * §13.4 Guardrails — optional validation hooks for the agent loop.
+ * @module
+ */
+
+/** Result of a guardrail check. */
+interface GuardrailResult {
+    allowed: boolean;
+    reason?: string;
+    rewrite?: any;
+}
+/** Error thrown when a guardrail denies the operation. */
+declare class GuardrailError extends Error {
+    reason: string;
+    constructor(reason: string);
+}
+/** Input guardrail hook signature. */
+type InputGuardrail = (messages: Message[]) => GuardrailResult;
+/** Output guardrail hook signature. */
+type OutputGuardrail = (message: Message) => GuardrailResult;
+/** Tool guardrail hook signature. */
+type ToolGuardrail = (name: string, args: Record<string, unknown>) => GuardrailResult;
+/** Configuration for guardrail hooks. */
+interface GuardrailsOptions {
+    input?: InputGuardrail;
+    output?: OutputGuardrail;
+    tool?: ToolGuardrail;
+}
+/**
+ * Guardrails with input, output, and tool hooks.
+ * All hooks are optional — when not set, execution proceeds normally.
+ */
+declare class Guardrails {
+    private inputHook?;
+    private outputHook?;
+    private toolHook?;
+    constructor(options?: GuardrailsOptions);
+    checkInput(messages: Message[]): GuardrailResult;
+    checkOutput(message: Message): GuardrailResult;
+    checkTool(name: string, args: Record<string, unknown>): GuardrailResult;
+}
+
+/**
+ * §13.5 Steering — inject user messages into a running agent loop.
+ * @module
+ */
+
+/**
+ * A handle for injecting user messages into a running agent loop.
+ * Thread-safe in the JS single-threaded model (no locking needed).
+ */
+declare class Steering {
+    private queue;
+    /** Enqueue a message to be injected at the next iteration. */
+    send(message: string): void;
+    /** Remove and return all queued messages as Message objects. */
+    drain(): Message[];
+    /** Whether there are pending messages without consuming them. */
+    get hasPending(): boolean;
+}
+
 /**
  * Four-step execution pipeline.
  *
  * ```
- * execute(prompt, inputs)              → top-level orchestrator
+ * invoke(prompt, inputs)               → top-level orchestrator
  *   ├── prepare(agent, inputs)         → template → wire format
  *   │     ├── render(agent, inputs)    → template + inputs → rendered string
  *   │     └── parse(agent, rendered)   → rendered string → Message[]
@@ -2190,10 +2275,25 @@ declare function run(agent: Prompty, messages: Message[], options?: {
 }): Promise<unknown>;
 /**
  * Full pipeline: load → prepare → run.
+ *
+ * @overload Untyped — returns `unknown`.
  */
-declare function execute(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: {
+declare function invoke(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: {
     raw?: boolean;
 }): Promise<unknown>;
+/**
+ * Full pipeline with typed result: load → prepare → run → cast.
+ *
+ * When a `validator` is provided the raw result is deserialized from JSON
+ * and passed through the validator (e.g. a Zod `.parse` function), giving
+ * you a fully typed return value.
+ *
+ * @overload Typed — returns `Promise<T>`.
+ */
+declare function invoke<T>(prompt: string | Prompty, inputs: Record<string, unknown> | undefined, options: {
+    raw?: boolean;
+    validator: (data: unknown) => T;
+}): Promise<T>;
 /**
  * Resolve tool bindings: inject values from parentInputs into tool arguments.
  *
@@ -2201,15 +2301,194 @@ declare function execute(prompt: string | Prompty, inputs?: Record<string, unkno
  * and sets `args[binding.name]` to that value. Returns a new args object.
  */
 declare function resolveBindings(agent: Prompty, toolName: string, args: Record<string, unknown>, parentInputs?: Record<string, unknown>): Record<string, unknown>;
-/**
- * Run a prompt with automatic tool-call execution loop.
- */
-declare function executeAgent(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: {
+/** Options for {@link invokeAgent}. */
+interface InvokeAgentOptions {
     tools?: Record<string, (...args: unknown[]) => unknown>;
     maxIterations?: number;
     raw?: boolean;
-}): Promise<unknown>;
-declare const runAgent: typeof executeAgent;
+    onEvent?: EventCallback;
+    signal?: AbortSignal;
+    contextBudget?: number;
+    guardrails?: Guardrails;
+    steering?: Steering;
+    parallelToolCalls?: boolean;
+}
+/**
+ * Run a prompt with automatic tool-call execution loop.
+ *
+ * Supports §13 extensions: events, cancellation, context window
+ * management, guardrails, steering, and parallel tool calls.
+ *
+ * @overload Untyped — returns `unknown`.
+ */
+declare function invokeAgent(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: InvokeAgentOptions): Promise<unknown>;
+/**
+ * Run a prompt with automatic tool-call execution loop, returning a typed result.
+ *
+ * When a `validator` is provided in the options the final result is
+ * deserialized from JSON and passed through the validator.
+ *
+ * @overload Typed — returns `Promise<T>`.
+ */
+declare function invokeAgent<T>(prompt: string | Prompty, inputs: Record<string, unknown> | undefined, options: InvokeAgentOptions & {
+    validator: (data: unknown) => T;
+}): Promise<T>;
+
+/**
+ * §13.2 Cancellation — cooperative cancellation via AbortSignal.
+ * @module
+ */
+/**
+ * Error thrown when the agent loop is cancelled.
+ */
+declare class CancelledError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Check if the signal is aborted, and throw CancelledError if so.
+ */
+declare function checkCancellation(signal?: AbortSignal): void;
+
+/**
+ * §13.3 Context Window Management — trimming and summarization.
+ * @module
+ */
+
+/**
+ * Estimate the character cost of a message list.
+ * Per spec §13.3: role + 4 overhead per message, text parts by length,
+ * non-text parts at 200-char estimate.
+ */
+declare function estimateChars(messages: Message[]): number;
+/**
+ * Build a compact string summary from dropped messages.
+ */
+declare function summarizeDropped(messages: Message[]): string;
+/**
+ * Trim messages in-place to fit within a character budget.
+ * Returns [droppedCount, droppedMessages].
+ */
+declare function trimToContextWindow(messages: Message[], budgetChars: number): [number, Message[]];
+
+/**
+ * `tool()` wrapper for typed tool functions (spec §11.2).
+ *
+ * Creates a FunctionTool definition from a function's metadata and
+ * auto-registers it in the global tool name registry.
+ *
+ * @module
+ */
+
+/** Options for the tool() wrapper. */
+interface ToolOptions {
+    /** Override the tool name (defaults to fn.name). */
+    name?: string;
+    /** Override the description. */
+    description?: string;
+    /** Parameter definitions (since JS can't introspect type hints). */
+    parameters?: ToolParameter[];
+    /** If false, skip global registration. Default: true. */
+    register?: boolean;
+}
+/** A parameter definition for a tool function. */
+interface ToolParameter {
+    name: string;
+    kind?: string;
+    description?: string;
+    required?: boolean;
+    default?: unknown;
+}
+/** Extended function with __tool__ metadata. */
+interface ToolFunction<T extends (...args: unknown[]) => unknown = (...args: unknown[]) => unknown> {
+    (...args: Parameters<T>): ReturnType<T>;
+    __tool__: FunctionTool;
+}
+/**
+ * Wrap a function as a typed tool.
+ *
+ * Unlike Python's @tool which can introspect type hints, the JS version
+ * requires explicit parameter definitions. The function itself is returned
+ * unchanged but with a `__tool__` property containing the FunctionTool.
+ *
+ * @example
+ * ```ts
+ * const getWeather = tool(
+ *   (city: string, units?: string) => `72°F in ${city}`,
+ *   {
+ *     name: "get_weather",
+ *     description: "Get the current weather",
+ *     parameters: [
+ *       { name: "city", kind: "string", required: true },
+ *       { name: "units", kind: "string", default: "celsius" },
+ *     ],
+ *   },
+ * );
+ *
+ * getWeather.__tool__; // FunctionTool instance
+ * getWeather("NYC");   // "72°F in NYC"
+ * ```
+ */
+declare function tool<T extends (...args: unknown[]) => unknown>(fn: T, options?: ToolOptions): ToolFunction<T>;
+/**
+ * Validate tool handlers against an agent's tool declarations and return a handler record.
+ *
+ * Each function must have a `__tool__` property (set by `tool()`). `bindTools` matches
+ * each handler's name against `kind: "function"` tools declared in `agent.tools`,
+ * raising on mismatches and warning on missing handlers.
+ *
+ * @param agent - A loaded Prompty agent (has `.tools` property)
+ * @param tools - Array of `tool()`-wrapped functions
+ * @returns Handler record suitable for `invokeAgent(..., { tools: result })`
+ * @throws Error if a handler has no `__tool__` property or no matching declaration
+ */
+declare function bindTools(agent: {
+    tools?: Array<{
+        name: string;
+        kind?: string;
+    }>;
+}, tools: Array<ToolFunction>): Record<string, (...args: unknown[]) => unknown>;
+
+/**
+ * Structured result casting for typed LLM output.
+ *
+ * When a processor parses structured JSON from an LLM response, it wraps
+ * the result in a `StructuredResult` that carries both the parsed data
+ * (accessible as normal properties) and the raw JSON string (hidden behind
+ * a Symbol). The `cast()` function lets callers deserialize directly from
+ * the raw JSON, optionally running a validator (e.g., Zod `.parse`).
+ *
+ * @module
+ */
+/**
+ * Symbol used to store the raw JSON string on a StructuredResult.
+ * Using a Symbol keeps the raw JSON invisible to normal property iteration.
+ */
+declare const StructuredResultSymbol: unique symbol;
+/**
+ * A plain object carrying structured output from an LLM.
+ * Behaves like a normal Record<string, unknown> but also stores the raw JSON
+ * string so that cast() can deserialize directly to typed objects.
+ */
+interface StructuredResult extends Record<string, unknown> {
+    readonly [StructuredResultSymbol]: string;
+}
+/**
+ * Create a StructuredResult wrapping parsed data + raw JSON.
+ */
+declare function createStructuredResult(data: Record<string, unknown>, rawJson: string): StructuredResult;
+/**
+ * Type guard: is this value a StructuredResult?
+ */
+declare function isStructuredResult(value: unknown): value is StructuredResult;
+/**
+ * Cast a result to a typed object. When the result is a StructuredResult,
+ * deserializes directly from the raw JSON (no intermediate round-trip).
+ *
+ * @param result - The result to cast (StructuredResult, string, or object)
+ * @param validator - Optional runtime validator (e.g., Zod .parse)
+ * @returns The typed result
+ */
+declare function cast<T = Record<string, unknown>>(result: unknown, validator?: (data: unknown) => T): T;
 
 /**
  * Nunjucks renderer — Jinja2-compatible template rendering for TypeScript.
@@ -2470,4 +2749,4 @@ interface OtelTracerOptions {
  */
 declare function otelTracer(api: OtelApi, options?: OtelTracerOptions): TracerFactory;
 
-export { Prompty as AgentDefinition, AnonymousConnection, ApiKeyConnection, ArrayProperty, type AudioPart, Binding, Connection, type ContentPart, CustomTool, type Executor, type FilePart, FormatConfig, FoundryConnection, FunctionTool, type ImagePart, InvokerError, LoadContext, McpApprovalMode, McpTool, Message, Model, ModelOptions, MustacheRenderer, NunjucksRenderer, OAuthConnection, ObjectProperty, OpenApiTool, type OtelApi, type OtelTracerOptions, type Parser, ParserConfig, type Processor, Prompty as PromptAgent, Prompty, PromptyChatParser, PromptyStream, PromptyTool, PromptyTracer, Property, RICH_KINDS, ROLES, ReferenceConnection, RemoteConnection, type Renderer, type Role, SaveContext, type SpanEmitter, Template, type TextPart, ThreadMarker, Tool, type ToolCall, Tracer, type TracerBackend, type TracerFactory, clearCache, clearConnections, consoleTracer, dictContentToPart, dictToMessage, execute, executeAgent, getConnection, getExecutor, getParser, getProcessor, getRenderer, load, otelTracer, parse, prepare, process, registerConnection, registerExecutor, registerParser, registerProcessor, registerRenderer, render, resolveBindings, run, runAgent, sanitizeValue, text, textMessage, toSerializable, trace, traceMethod, traceSpan, validateInputs };
+export { Prompty as AgentDefinition, type AgentEventType, AnonymousConnection, ApiKeyConnection, ArrayProperty, type AudioPart, Binding, CancelledError, Connection, type ContentPart, CustomTool, type EventCallback, type Executor, type FilePart, FormatConfig, FoundryConnection, FunctionTool, GuardrailError, type GuardrailResult, Guardrails, type GuardrailsOptions, type ImagePart, type InputGuardrail, type InvokeAgentOptions, InvokerError, LoadContext, McpApprovalMode, McpTool, Message, Model, ModelOptions, MustacheRenderer, NunjucksRenderer, OAuthConnection, ObjectProperty, OpenApiTool, type OtelApi, type OtelTracerOptions, type OutputGuardrail, type Parser, ParserConfig, type Processor, Prompty as PromptAgent, Prompty, PromptyChatParser, PromptyStream, PromptyTool, PromptyTracer, Property, RICH_KINDS, ROLES, ReferenceConnection, RemoteConnection, type Renderer, type Role, SaveContext, type SpanEmitter, Steering, type StructuredResult, StructuredResultSymbol, Template, type TextPart, ThreadMarker, Tool, type ToolCall, type ToolFunction, type ToolGuardrail, type ToolOptions, type ToolParameter, Tracer, type TracerBackend, type TracerFactory, bindTools, cast, checkCancellation, clearCache, clearConnections, consoleTracer, createStructuredResult, dictContentToPart, dictToMessage, emitEvent, estimateChars, getConnection, getExecutor, getParser, getProcessor, getRenderer, invoke, invokeAgent, isStructuredResult, load, otelTracer, parse, prepare, process, registerConnection, registerExecutor, registerParser, registerProcessor, registerRenderer, render, resolveBindings, run, sanitizeValue, summarizeDropped, text, textMessage, toSerializable, tool, trace, traceMethod, traceSpan, trimToContextWindow, validateInputs };