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

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.
@@ -2138,19 +2148,108 @@ declare function clearConnections(): void;
 declare function load(path: string): Prompty;
 
 /**
- * Four-step execution pipeline.
+ * §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;
+}
+
+/**
+ * Execution pipeline — two top-level APIs plus building blocks.
  *
  * ```
- * invoke(prompt, inputs)               → top-level orchestrator
+ * invoke(prompt, inputs)               → one-shot: load + prepare + execute + process
+ *   ├── load(path)                     → file → agent (when path given)
  *   ├── prepare(agent, inputs)         → template → wire format
  *   │     ├── render(agent, inputs)    → template + inputs → rendered string
  *   │     └── parse(agent, rendered)   → rendered string → Message[]
- *   └── run(agent, messages)           → LLM call → clean result
- *         ├── Executor.execute(...)    → messages → raw LLM response
- *         └── process(agent, response) → raw response → clean result
+ *   ├── Executor.execute(...)          → messages → raw LLM response
+ *   └── Processor.process(...)         → raw response → clean result
+ *
+ * turn(agent, inputs, options?)        → conversational round-trip
+ *   ├── prepare(agent, inputs)         → template → wire format
+ *   ├── Executor.execute(...)          → LLM call
+ *   ├── [toolCalls → Executor]*        → agent loop (when tools provided)
+ *   └── Processor.process(...)         → final result extraction
+ *
+ * run(agent, messages, options?)       → standalone: execute + process
+ *   ├── Executor.execute(...)          → messages → raw LLM response
+ *   └── Processor.process(...)         → raw response → clean result
  * ```
  *
- * Each leaf step is independently traced. Users can bring their own
+ * `invoke` = "call this prompty like a function" (one-shot, embeddings, tool JSON).
+ * `turn`   = "one round of a conversation" (thread history, turn numbering, tool loops).
+ * `run`    = standalone building block for advanced users.
+ *
+ * Each step is independently traced. Users can bring their own
  * Renderer, Parser, Executor, Processor via the registry.
  *
  * @module
@@ -2188,12 +2287,95 @@ declare function prepare(agent: Prompty, inputs?: Record<string, unknown>): Prom
 declare function run(agent: Prompty, messages: Message[], options?: {
     raw?: boolean;
 }): Promise<unknown>;
+/** Options for {@link invoke}. */
+interface InvokeOptions {
+    /** Return raw executor response without processing. */
+    raw?: boolean;
+}
 /**
- * Full pipeline: load → prepare → run.
+ * One-shot pipeline: load → prepare → execute → process.
+ *
+ * Use `invoke` to call a prompty like a function — give inputs, get output.
+ * No conversation context or turn numbering. Supports file paths or
+ * pre-loaded agents.
+ *
+ * Trace structure (flat):
+ * ```
+ * invoke
+ *   load           (only when path given)
+ *   prepare
+ *     Renderer
+ *     Parser
+ *   Executor
+ *   Processor
+ * ```
+ *
+ * @overload Untyped — returns `unknown`.
  */
-declare function invoke(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: {
+declare function invoke(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: InvokeOptions): Promise<unknown>;
+/**
+ * One-shot pipeline with typed result: load → prepare → execute → process → 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: InvokeOptions & {
+    validator: (data: unknown) => T;
+}): Promise<T>;
+/** Options for {@link turn}. */
+interface TurnOptions {
+    /** Runtime tool handlers. When provided, triggers the agent loop. */
+    tools?: Record<string, (...args: unknown[]) => unknown>;
+    /** Turn number for trace labeling (e.g., "turn 3"). */
+    turn?: number;
+    /** Maximum agent-loop iterations before throwing (default: 10). */
+    maxIterations?: number;
+    /** Return raw executor response without processing. */
     raw?: boolean;
-}): Promise<unknown>;
+    /** Callback for agent loop events (token, tool_call, done, etc.). */
+    onEvent?: EventCallback;
+    /** Abort signal for cancellation (§13.2). */
+    signal?: AbortSignal;
+    /** Max character budget for context window trimming (§13.3). */
+    contextBudget?: number;
+    /** Input/output/tool guardrails (§13.4). */
+    guardrails?: Guardrails;
+    /** Steering queue for injecting messages mid-loop (§13.5). */
+    steering?: Steering;
+    /** Allow parallel tool execution within a single round (§13.6). */
+    parallelToolCalls?: boolean;
+}
+/**
+ * One conversational turn: prepare messages from inputs, then either execute a
+ * single LLM call or enter the agent loop (when tools are provided).
+ *
+ * Trace structure (flat — no redundant wrappers):
+ * ```
+ * turn N
+ *   prepare → Renderer → Parser
+ *   Executor                        (each LLM call)
+ *   toolCalls → tool1, tool2        (if tools provided)
+ *   Executor                        (follow-up LLM call)
+ *   Processor                       (final result extraction)
+ * ```
+ *
+ * @overload Untyped — returns `unknown`.
+ */
+declare function turn(prompt: string | Prompty, inputs: Record<string, unknown>, options?: TurnOptions): Promise<unknown>;
+/**
+ * One conversational turn with typed result.
+ *
+ * When a `validator` is provided the final result is deserialized from JSON
+ * and passed through the validator (e.g. a Zod `.parse` function).
+ *
+ * @overload Typed — returns `Promise<T>`.
+ */
+declare function turn<T>(prompt: string | Prompty, inputs: Record<string, unknown>, options: TurnOptions & {
+    validator: (data: unknown) => T;
+}): Promise<T>;
 /**
  * Resolve tool bindings: inject values from parentInputs into tool arguments.
  *
@@ -2202,13 +2384,168 @@ declare function invoke(prompt: string | Prompty, inputs?: Record<string, unknow
  */
 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.
+ * @deprecated Use {@link turn} with `tools` option instead.
+ * Kept for backward compatibility — delegates to `turn()`.
  */
-declare function invokeAgent(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: {
-    tools?: Record<string, (...args: unknown[]) => unknown>;
-    maxIterations?: number;
-    raw?: boolean;
-}): Promise<unknown>;
+declare const invokeAgent: typeof turn;
+/** @deprecated Use {@link TurnOptions} instead. */
+type InvokeAgentOptions = TurnOptions;
+
+/**
+ * §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 `turn(..., { 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.
@@ -2469,4 +2806,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, getConnection, getExecutor, getParser, getProcessor, getRenderer, invoke, invokeAgent, load, otelTracer, parse, prepare, process, registerConnection, registerExecutor, registerParser, registerProcessor, registerRenderer, render, resolveBindings, run, 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, type InvokeOptions, 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, type TurnOptions, 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, turn, validateInputs };