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

package/dist/index.d.cts

@@ -2223,19 +2223,33 @@ declare class Steering {
 }
 
 /**
- * Four-step execution pipeline.
+ * 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
@@ -2273,16 +2287,34 @@ 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?: {
-    raw?: boolean;
-}): Promise<unknown>;
+declare function invoke(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: InvokeOptions): Promise<unknown>;
 /**
- * Full pipeline with typed result: load → prepare → run → cast.
+ * 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
@@ -2290,49 +2322,74 @@ declare function invoke(prompt: string | Prompty, inputs?: Record<string, unknow
  *
  * @overload Typed — returns `Promise<T>`.
  */
-declare function invoke<T>(prompt: string | Prompty, inputs: Record<string, unknown> | undefined, options: {
-    raw?: boolean;
+declare function invoke<T>(prompt: string | Prompty, inputs: Record<string, unknown> | undefined, options: InvokeOptions & {
     validator: (data: unknown) => T;
 }): Promise<T>;
-/**
- * Resolve tool bindings: inject values from parentInputs into tool arguments.
- *
- * For each binding on the matched tool, looks up `binding.input` in parentInputs
- * 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>;
-/** Options for {@link invokeAgent}. */
-interface InvokeAgentOptions {
+/** 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;
+    /** 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;
 }
 /**
- * Run a prompt with automatic tool-call execution loop.
+ * One conversational turn: prepare messages from inputs, then either execute a
+ * single LLM call or enter the agent loop (when tools are provided).
  *
- * Supports §13 extensions: events, cancellation, context window
- * management, guardrails, steering, and parallel tool calls.
+ * 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 invokeAgent(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: InvokeAgentOptions): Promise<unknown>;
+declare function turn(prompt: string | Prompty, inputs: Record<string, unknown>, options?: TurnOptions): Promise<unknown>;
 /**
- * Run a prompt with automatic tool-call execution loop, returning a typed result.
+ * One conversational turn with typed result.
  *
- * When a `validator` is provided in the options the final result is
- * deserialized from JSON and passed through the validator.
+ * 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 invokeAgent<T>(prompt: string | Prompty, inputs: Record<string, unknown> | undefined, options: InvokeAgentOptions & {
+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.
+ *
+ * For each binding on the matched tool, looks up `binding.input` in parentInputs
+ * 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>;
+/**
+ * @deprecated Use {@link turn} with `tools` option instead.
+ * Kept for backward compatibility — delegates to `turn()`.
+ */
+declare const invokeAgent: typeof turn;
+/** @deprecated Use {@link TurnOptions} instead. */
+type InvokeAgentOptions = TurnOptions;
 
 /**
  * §13.2 Cancellation — cooperative cancellation via AbortSignal.
@@ -2438,7 +2495,7 @@ declare function tool<T extends (...args: unknown[]) => unknown>(fn: T, options?
  *
  * @param agent - A loaded Prompty agent (has `.tools` property)
  * @param tools - Array of `tool()`-wrapped functions
- * @returns Handler record suitable for `invokeAgent(..., { tools: result })`
+ * @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: {
@@ -2749,4 +2806,4 @@ interface OtelTracerOptions {
  */
 declare function otelTracer(api: OtelApi, options?: OtelTracerOptions): TracerFactory;
 
-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 };
+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 };

package/dist/index.d.ts

@@ -2223,19 +2223,33 @@ declare class Steering {
 }
 
 /**
- * Four-step execution pipeline.
+ * 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
@@ -2273,16 +2287,34 @@ 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?: {
-    raw?: boolean;
-}): Promise<unknown>;
+declare function invoke(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: InvokeOptions): Promise<unknown>;
 /**
- * Full pipeline with typed result: load → prepare → run → cast.
+ * 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
@@ -2290,49 +2322,74 @@ declare function invoke(prompt: string | Prompty, inputs?: Record<string, unknow
  *
  * @overload Typed — returns `Promise<T>`.
  */
-declare function invoke<T>(prompt: string | Prompty, inputs: Record<string, unknown> | undefined, options: {
-    raw?: boolean;
+declare function invoke<T>(prompt: string | Prompty, inputs: Record<string, unknown> | undefined, options: InvokeOptions & {
     validator: (data: unknown) => T;
 }): Promise<T>;
-/**
- * Resolve tool bindings: inject values from parentInputs into tool arguments.
- *
- * For each binding on the matched tool, looks up `binding.input` in parentInputs
- * 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>;
-/** Options for {@link invokeAgent}. */
-interface InvokeAgentOptions {
+/** 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;
+    /** 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;
 }
 /**
- * Run a prompt with automatic tool-call execution loop.
+ * One conversational turn: prepare messages from inputs, then either execute a
+ * single LLM call or enter the agent loop (when tools are provided).
  *
- * Supports §13 extensions: events, cancellation, context window
- * management, guardrails, steering, and parallel tool calls.
+ * 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 invokeAgent(prompt: string | Prompty, inputs?: Record<string, unknown>, options?: InvokeAgentOptions): Promise<unknown>;
+declare function turn(prompt: string | Prompty, inputs: Record<string, unknown>, options?: TurnOptions): Promise<unknown>;
 /**
- * Run a prompt with automatic tool-call execution loop, returning a typed result.
+ * One conversational turn with typed result.
  *
- * When a `validator` is provided in the options the final result is
- * deserialized from JSON and passed through the validator.
+ * 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 invokeAgent<T>(prompt: string | Prompty, inputs: Record<string, unknown> | undefined, options: InvokeAgentOptions & {
+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.
+ *
+ * For each binding on the matched tool, looks up `binding.input` in parentInputs
+ * 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>;
+/**
+ * @deprecated Use {@link turn} with `tools` option instead.
+ * Kept for backward compatibility — delegates to `turn()`.
+ */
+declare const invokeAgent: typeof turn;
+/** @deprecated Use {@link TurnOptions} instead. */
+type InvokeAgentOptions = TurnOptions;
 
 /**
  * §13.2 Cancellation — cooperative cancellation via AbortSignal.
@@ -2438,7 +2495,7 @@ declare function tool<T extends (...args: unknown[]) => unknown>(fn: T, options?
  *
  * @param agent - A loaded Prompty agent (has `.tools` property)
  * @param tools - Array of `tool()`-wrapped functions
- * @returns Handler record suitable for `invokeAgent(..., { tools: result })`
+ * @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: {
@@ -2749,4 +2806,4 @@ interface OtelTracerOptions {
  */
 declare function otelTracer(api: OtelApi, options?: OtelTracerOptions): TracerFactory;
 
-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 };
+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 };