@statelyai/agent 2.0.0-alpha.6 → 2.0.0-alpha.7

package/dist/ai-sdk.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_decision = require("./decision-CX3YdwrO.cjs");
+const require_decision = require("./decision-BnATHy0W.cjs");
 let ai = require("ai");
 //#region src/ai-sdk/index.ts
 /**
@@ -115,6 +115,56 @@ function isStructuredOutputRequest(request) {
 	return require_decision.getAgentOutputMode(request.outputSchema) === "structured";
 }
 /**
+* Extracts the first complete top-level JSON value from `text`, or returns
+* `undefined` when there is nothing to repair (no complete value, or the value
+* already spans the whole text). Models occasionally emit two structured-output
+* envelopes back to back (`{"result":{…}}{"result":{…}}`), which fails JSON
+* parsing wholesale; the balanced scan below recovers the first value and
+* drops the rest.
+*/
+function extractFirstJsonValue(text) {
+	const start = text.search(/[{[]/);
+	if (start === -1) return;
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let i = start; i < text.length; i++) {
+		const char = text[i];
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === "\"") inString = false;
+			continue;
+		}
+		if (char === "\"") inString = true;
+		else if (char === "{" || char === "[") depth++;
+		else if (char === "}" || char === "]") {
+			depth--;
+			if (depth === 0) {
+				const value = text.slice(start, i + 1);
+				return value === text.trim() ? void 0 : value;
+			}
+		}
+	}
+}
+function withJsonRepair(output) {
+	return {
+		...output,
+		parseCompleteOutput: async (options, context) => {
+			try {
+				return await output.parseCompleteOutput(options, context);
+			} catch (error) {
+				const repaired = extractFirstJsonValue(options.text);
+				if (repaired === void 0) throw error;
+				return await output.parseCompleteOutput({
+					...options,
+					text: repaired
+				}, context);
+			}
+		}
+	};
+}
+/**
 * The canonical Vercel AI SDK adapter: builds the `{ generateText, streamText,
 * decide }` executor set consumed by `runAgent`/`executeAgentRequest`. `ai`
 * must not become a dependency of core `src/` files — this subpath is the one
@@ -138,10 +188,21 @@ function createAiSdkExecutors(options) {
 		};
 		if (isStructuredOutputRequest(request)) {
 			const envelope = require_decision.buildEnvelopeSchema(request.outputSchema, { reasoning: request.reasoning });
-			const result = await (0, ai.generateText)({
-				...common,
-				output: ai.Output.object({ schema: envelope })
-			});
+			const structuredOutput = withJsonRepair(ai.Output.object({ schema: envelope }));
+			const canRetry = !request.tools || Object.keys(request.tools).length === 0;
+			let result;
+			try {
+				result = await (0, ai.generateText)({
+					...common,
+					output: structuredOutput
+				});
+			} catch (error) {
+				if (!canRetry || !ai.NoObjectGeneratedError.isInstance(error) || info?.signal?.aborted) throw error;
+				result = await (0, ai.generateText)({
+					...common,
+					output: structuredOutput
+				});
+			}
 			const { result: output, reasoning } = result.output;
 			return {
 				output,
@@ -241,6 +302,7 @@ function toDecisionMessages(request) {
 //#endregion
 exports.createAiSdkExecutors = createAiSdkExecutors;
 exports.defineModels = defineModels;
+exports.extractFirstJsonValue = extractFirstJsonValue;
 exports.isStructuredOutputRequest = isStructuredOutputRequest;
 exports.toAiSdkCallSettings = toAiSdkCallSettings;
 exports.toAiSdkEventTools = toAiSdkEventTools;

package/dist/ai-sdk.d.cts

@@ -1,5 +1,5 @@
 import { c as AgentTools, f as ChosenEvent } from "./types-BHjeDdch.cjs";
-import { B as AgentEventDescriptor, D as AgentDecisionExecutor, i as AgentRequestExecutor, k as AgentDecisionRequest, l as AgentTextRequest, s as AgentRequestExecutors } from "./text-logic-1ZQkO3zr.cjs";
+import { H as AgentEventDescriptor, i as AgentRequestExecutor, j as AgentDecisionRequest, k as AgentDecisionExecutor, l as AgentTextRequest, s as AgentRequestExecutors } from "./text-logic-4Q2F9kyr.cjs";
 import { FinishReason, LanguageModel, LanguageModelUsage, ModelMessage, Tool, ToolSet, TypedToolCall, TypedToolResult } from "ai";
 
 //#region src/ai-sdk/index.d.ts
@@ -99,6 +99,15 @@ declare function toAiSdkToolChoice(toolChoice: AgentTextRequest["toolChoice"]):
 } | undefined;
 /** `true` when the request should use AI SDK structured `Output.object`. */
 declare function isStructuredOutputRequest(request: Pick<AgentTextRequest, "outputSchema">): boolean;
+/**
+ * Extracts the first complete top-level JSON value from `text`, or returns
+ * `undefined` when there is nothing to repair (no complete value, or the value
+ * already spans the whole text). Models occasionally emit two structured-output
+ * envelopes back to back (`{"result":{…}}{"result":{…}}`), which fails JSON
+ * parsing wholesale; the balanced scan below recovers the first value and
+ * drops the rest.
+ */
+declare function extractFirstJsonValue(text: string): string | undefined;
 /**
  * Raw result shape from {@link AiSdkExecutors.generateText} — the `{ output }`
  * envelope (the validated structured object for structured-output requests,
@@ -165,4 +174,4 @@ declare function toAiSdkEventTools(events: AgentEventDescriptor[]): {
  */
 declare function toDecisionMessages(request: Pick<AgentDecisionRequest, "messages" | "prompt" | "events" | "attempts">): ModelMessage[] | undefined;
 //#endregion
-export { AiSdkDecideResult, AiSdkExecutors, AiSdkGenerateResult, AiSdkModelMap, AiSdkStreamResult, CreateAiSdkExecutorsOptions, createAiSdkExecutors, defineModels, isStructuredOutputRequest, toAiSdkCallSettings, toAiSdkEventTools, toAiSdkToolChoice, toAiSdkTools, toDecisionMessages };
+export { AiSdkDecideResult, AiSdkExecutors, AiSdkGenerateResult, AiSdkModelMap, AiSdkStreamResult, CreateAiSdkExecutorsOptions, createAiSdkExecutors, defineModels, extractFirstJsonValue, isStructuredOutputRequest, toAiSdkCallSettings, toAiSdkEventTools, toAiSdkToolChoice, toAiSdkTools, toDecisionMessages };

package/dist/ai-sdk.d.mts

@@ -1,5 +1,5 @@
 import { c as AgentTools, f as ChosenEvent } from "./types-Cq1YlAQ6.mjs";
-import { B as AgentEventDescriptor, D as AgentDecisionExecutor, i as AgentRequestExecutor, k as AgentDecisionRequest, l as AgentTextRequest, s as AgentRequestExecutors } from "./text-logic-2EMJIS-n.mjs";
+import { H as AgentEventDescriptor, i as AgentRequestExecutor, j as AgentDecisionRequest, k as AgentDecisionExecutor, l as AgentTextRequest, s as AgentRequestExecutors } from "./text-logic-2wFNEznm.mjs";
 import { FinishReason, LanguageModel, LanguageModelUsage, ModelMessage, Tool, ToolSet, TypedToolCall, TypedToolResult } from "ai";
 
 //#region src/ai-sdk/index.d.ts
@@ -99,6 +99,15 @@ declare function toAiSdkToolChoice(toolChoice: AgentTextRequest["toolChoice"]):
 } | undefined;
 /** `true` when the request should use AI SDK structured `Output.object`. */
 declare function isStructuredOutputRequest(request: Pick<AgentTextRequest, "outputSchema">): boolean;
+/**
+ * Extracts the first complete top-level JSON value from `text`, or returns
+ * `undefined` when there is nothing to repair (no complete value, or the value
+ * already spans the whole text). Models occasionally emit two structured-output
+ * envelopes back to back (`{"result":{…}}{"result":{…}}`), which fails JSON
+ * parsing wholesale; the balanced scan below recovers the first value and
+ * drops the rest.
+ */
+declare function extractFirstJsonValue(text: string): string | undefined;
 /**
  * Raw result shape from {@link AiSdkExecutors.generateText} — the `{ output }`
  * envelope (the validated structured object for structured-output requests,
@@ -165,4 +174,4 @@ declare function toAiSdkEventTools(events: AgentEventDescriptor[]): {
  */
 declare function toDecisionMessages(request: Pick<AgentDecisionRequest, "messages" | "prompt" | "events" | "attempts">): ModelMessage[] | undefined;
 //#endregion
-export { AiSdkDecideResult, AiSdkExecutors, AiSdkGenerateResult, AiSdkModelMap, AiSdkStreamResult, CreateAiSdkExecutorsOptions, createAiSdkExecutors, defineModels, isStructuredOutputRequest, toAiSdkCallSettings, toAiSdkEventTools, toAiSdkToolChoice, toAiSdkTools, toDecisionMessages };
+export { AiSdkDecideResult, AiSdkExecutors, AiSdkGenerateResult, AiSdkModelMap, AiSdkStreamResult, CreateAiSdkExecutorsOptions, createAiSdkExecutors, defineModels, extractFirstJsonValue, isStructuredOutputRequest, toAiSdkCallSettings, toAiSdkEventTools, toAiSdkToolChoice, toAiSdkTools, toDecisionMessages };

package/dist/ai-sdk.mjs

@@ -1,5 +1,5 @@
-import { G as isStandardSchema, T as getAgentOutputMode, l as renderDecisionAttempts, x as buildEnvelopeSchema } from "./decision-D1654JdD.mjs";
-import { Output, generateText, stepCountIs, streamText, tool } from "ai";
+import { T as getAgentOutputMode, l as renderDecisionAttempts, q as isStandardSchema, x as buildEnvelopeSchema } from "./decision-mPR_YQd8.mjs";
+import { NoObjectGeneratedError, Output, generateText, stepCountIs, streamText, tool } from "ai";
 //#region src/ai-sdk/index.ts
 /**
 * Maps an {@link AgentTools} map onto AI SDK `tool()` definitions. A tool that
@@ -114,6 +114,56 @@ function isStructuredOutputRequest(request) {
 	return getAgentOutputMode(request.outputSchema) === "structured";
 }
 /**
+* Extracts the first complete top-level JSON value from `text`, or returns
+* `undefined` when there is nothing to repair (no complete value, or the value
+* already spans the whole text). Models occasionally emit two structured-output
+* envelopes back to back (`{"result":{…}}{"result":{…}}`), which fails JSON
+* parsing wholesale; the balanced scan below recovers the first value and
+* drops the rest.
+*/
+function extractFirstJsonValue(text) {
+	const start = text.search(/[{[]/);
+	if (start === -1) return;
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let i = start; i < text.length; i++) {
+		const char = text[i];
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === "\"") inString = false;
+			continue;
+		}
+		if (char === "\"") inString = true;
+		else if (char === "{" || char === "[") depth++;
+		else if (char === "}" || char === "]") {
+			depth--;
+			if (depth === 0) {
+				const value = text.slice(start, i + 1);
+				return value === text.trim() ? void 0 : value;
+			}
+		}
+	}
+}
+function withJsonRepair(output) {
+	return {
+		...output,
+		parseCompleteOutput: async (options, context) => {
+			try {
+				return await output.parseCompleteOutput(options, context);
+			} catch (error) {
+				const repaired = extractFirstJsonValue(options.text);
+				if (repaired === void 0) throw error;
+				return await output.parseCompleteOutput({
+					...options,
+					text: repaired
+				}, context);
+			}
+		}
+	};
+}
+/**
 * The canonical Vercel AI SDK adapter: builds the `{ generateText, streamText,
 * decide }` executor set consumed by `runAgent`/`executeAgentRequest`. `ai`
 * must not become a dependency of core `src/` files — this subpath is the one
@@ -137,10 +187,21 @@ function createAiSdkExecutors(options) {
 		};
 		if (isStructuredOutputRequest(request)) {
 			const envelope = buildEnvelopeSchema(request.outputSchema, { reasoning: request.reasoning });
-			const result = await generateText({
-				...common,
-				output: Output.object({ schema: envelope })
-			});
+			const structuredOutput = withJsonRepair(Output.object({ schema: envelope }));
+			const canRetry = !request.tools || Object.keys(request.tools).length === 0;
+			let result;
+			try {
+				result = await generateText({
+					...common,
+					output: structuredOutput
+				});
+			} catch (error) {
+				if (!canRetry || !NoObjectGeneratedError.isInstance(error) || info?.signal?.aborted) throw error;
+				result = await generateText({
+					...common,
+					output: structuredOutput
+				});
+			}
 			const { result: output, reasoning } = result.output;
 			return {
 				output,
@@ -238,4 +299,4 @@ function toDecisionMessages(request) {
 	return messages;
 }
 //#endregion
-export { createAiSdkExecutors, defineModels, isStructuredOutputRequest, toAiSdkCallSettings, toAiSdkEventTools, toAiSdkToolChoice, toAiSdkTools, toDecisionMessages };
+export { createAiSdkExecutors, defineModels, extractFirstJsonValue, isStructuredOutputRequest, toAiSdkCallSettings, toAiSdkEventTools, toAiSdkToolChoice, toAiSdkTools, toDecisionMessages };

package/dist/cli.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const require_src = require("./src-wBfi-kTA.cjs");
+const require_src = require("./src-MysDmqwT.cjs");
 let node_fs = require("node:fs");
 //#region src/cli.ts
 /**

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as lintAgentMachine, v as setupAgent } from "./src-CEa947Dm.mjs";
+import { r as lintAgentMachine, v as setupAgent } from "./src-BpQdxsKc.mjs";
 import { readFileSync } from "node:fs";
 //#region src/cli.ts
 /**

package/dist/{decision-CX3YdwrO.cjs → decision-BnATHy0W.cjs}

@@ -266,6 +266,27 @@ const DECIDE_ACTOR = "agent.decide";
 const PLAN_ACTOR = "agent.plan";
 /** Synthetic `src` stamped on trace requests produced by `getRequests` state interpretation — NOT a registered actor source (nothing is invoked; the pass makes the call directly). */
 const INTERPRET_SOURCE = "agent.interpret";
+/**
+* Splits a portable `"provider/model-id"` model ref (the convention JSON
+* workflows and registry-less hosts use, e.g. `"openai/gpt-5.4-mini"`) into
+* its parts. A ref with no `/` has no provider — `modelId` is the whole ref.
+* The standard building block for a host's `resolveModel`:
+*
+* @example
+* ```ts
+* const resolveModel = (ref: string) => openai(parseModelRef(ref).modelId);
+* ```
+*/
+function parseModelRef(modelRef) {
+	const slash = modelRef.indexOf("/");
+	return slash === -1 ? {
+		provider: void 0,
+		modelId: modelRef
+	} : {
+		provider: modelRef.slice(0, slash),
+		modelId: modelRef.slice(slash + 1)
+	};
+}
 const agentTextInputSchema = { "~standard": {
 	version: 1,
 	vendor: "statelyai-agent",
@@ -336,7 +357,7 @@ const builtinTextActors = {
 	[GENERATE_TEXT_ACTOR]: createBuiltinTextActor(GENERATE_TEXT_ACTOR, "generate", unknownOutputSchema),
 	[STREAM_TEXT_ACTOR]: createBuiltinTextActor(STREAM_TEXT_ACTOR, "stream", stringOutputSchema)
 };
-/** The unbound `agent.userInput` builtin registered by setupAgent (an unbound-placeholder logic — see internal/registry.ts). @internal */
+/** The unbound `agent.userInput` builtin registered by setupAgent (an unbound-placeholder logic — see internal/registry.ts). Output is `string` — what the human typed. @internal */
 const userInputActor = (0, xstate.createAsyncLogic)({ run: async () => {
 	throw new Error(`'${USER_INPUT_ACTOR}' has no host execution. Provide an implementation with machine.provide({ actorSources: { '${USER_INPUT_ACTOR}': ... } }).`);
 } });
@@ -444,12 +465,15 @@ function createTextLogic(config, execute) {
 * });
 * ```
 */
-function bindRequestExecutor(logic, executor) {
+function bindRequestExecutor(logic, executor, info) {
 	return logic.withExecutor(async ({ request, signal }) => {
 		const { output } = await executor({
 			...request,
 			tools: request.tools ?? {}
-		}, { signal });
+		}, {
+			signal,
+			onChunk: info?.onChunk
+		});
 		return { output };
 	});
 }
@@ -524,6 +548,17 @@ function buildEnvelopeSchema(inner, options = {}) {
 		} }
 	} };
 }
+/**
+* Validates a raw provider value against the structured-output envelope for
+* `request` and returns the unwrapped `{ result, reasoning? }` — the checked
+* replacement for `raw as StructuredOutputEnvelope` in hand-written hosts.
+* Pair with {@link buildEnvelopeSchema} (which produced the schema the
+* provider was asked to satisfy).
+*/
+function parseStructuredEnvelope(request, value) {
+	if (!request.outputSchema) throw new Error("parseStructuredEnvelope: the request declares no outputSchema.");
+	return validateSchemaSync(buildEnvelopeSchema(request.outputSchema, { reasoning: request.reasoning }), value);
+}
 function getStandardSchemaJson(schema) {
 	const jsonSchema = (schema?.["~standard"])?.jsonSchema?.input?.();
 	return jsonSchema && !(jsonSchema instanceof Promise) ? jsonSchema : void 0;
@@ -1177,12 +1212,24 @@ Object.defineProperty(exports, "parseAgentEvent", {
 		return parseAgentEvent;
 	}
 });
+Object.defineProperty(exports, "parseModelRef", {
+	enumerable: true,
+	get: function() {
+		return parseModelRef;
+	}
+});
 Object.defineProperty(exports, "parseOutput", {
 	enumerable: true,
 	get: function() {
 		return parseOutput;
 	}
 });
+Object.defineProperty(exports, "parseStructuredEnvelope", {
+	enumerable: true,
+	get: function() {
+		return parseStructuredEnvelope;
+	}
+});
 Object.defineProperty(exports, "persistSnapshot", {
 	enumerable: true,
 	get: function() {

package/dist/{decision-D1654JdD.mjs → decision-mPR_YQd8.mjs}

@@ -266,6 +266,27 @@ const DECIDE_ACTOR = "agent.decide";
 const PLAN_ACTOR = "agent.plan";
 /** Synthetic `src` stamped on trace requests produced by `getRequests` state interpretation — NOT a registered actor source (nothing is invoked; the pass makes the call directly). */
 const INTERPRET_SOURCE = "agent.interpret";
+/**
+* Splits a portable `"provider/model-id"` model ref (the convention JSON
+* workflows and registry-less hosts use, e.g. `"openai/gpt-5.4-mini"`) into
+* its parts. A ref with no `/` has no provider — `modelId` is the whole ref.
+* The standard building block for a host's `resolveModel`:
+*
+* @example
+* ```ts
+* const resolveModel = (ref: string) => openai(parseModelRef(ref).modelId);
+* ```
+*/
+function parseModelRef(modelRef) {
+	const slash = modelRef.indexOf("/");
+	return slash === -1 ? {
+		provider: void 0,
+		modelId: modelRef
+	} : {
+		provider: modelRef.slice(0, slash),
+		modelId: modelRef.slice(slash + 1)
+	};
+}
 const agentTextInputSchema = { "~standard": {
 	version: 1,
 	vendor: "statelyai-agent",
@@ -336,7 +357,7 @@ const builtinTextActors = {
 	[GENERATE_TEXT_ACTOR]: createBuiltinTextActor(GENERATE_TEXT_ACTOR, "generate", unknownOutputSchema),
 	[STREAM_TEXT_ACTOR]: createBuiltinTextActor(STREAM_TEXT_ACTOR, "stream", stringOutputSchema)
 };
-/** The unbound `agent.userInput` builtin registered by setupAgent (an unbound-placeholder logic — see internal/registry.ts). @internal */
+/** The unbound `agent.userInput` builtin registered by setupAgent (an unbound-placeholder logic — see internal/registry.ts). Output is `string` — what the human typed. @internal */
 const userInputActor = createAsyncLogic({ run: async () => {
 	throw new Error(`'${USER_INPUT_ACTOR}' has no host execution. Provide an implementation with machine.provide({ actorSources: { '${USER_INPUT_ACTOR}': ... } }).`);
 } });
@@ -444,12 +465,15 @@ function createTextLogic(config, execute) {
 * });
 * ```
 */
-function bindRequestExecutor(logic, executor) {
+function bindRequestExecutor(logic, executor, info) {
 	return logic.withExecutor(async ({ request, signal }) => {
 		const { output } = await executor({
 			...request,
 			tools: request.tools ?? {}
-		}, { signal });
+		}, {
+			signal,
+			onChunk: info?.onChunk
+		});
 		return { output };
 	});
 }
@@ -524,6 +548,17 @@ function buildEnvelopeSchema(inner, options = {}) {
 		} }
 	} };
 }
+/**
+* Validates a raw provider value against the structured-output envelope for
+* `request` and returns the unwrapped `{ result, reasoning? }` — the checked
+* replacement for `raw as StructuredOutputEnvelope` in hand-written hosts.
+* Pair with {@link buildEnvelopeSchema} (which produced the schema the
+* provider was asked to satisfy).
+*/
+function parseStructuredEnvelope(request, value) {
+	if (!request.outputSchema) throw new Error("parseStructuredEnvelope: the request declares no outputSchema.");
+	return validateSchemaSync(buildEnvelopeSchema(request.outputSchema, { reasoning: request.reasoning }), value);
+}
 function getStandardSchemaJson(schema) {
 	const jsonSchema = (schema?.["~standard"])?.jsonSchema?.input?.();
 	return jsonSchema && !(jsonSchema instanceof Promise) ? jsonSchema : void 0;
@@ -937,4 +972,4 @@ async function resolveDecision(request, executor, options = {}) {
 	throw new DecisionExhaustedError(attempts);
 }
 //#endregion
-export { userInputActor as A, getAgentMessages as B, createTextLogic as C, isTextLogic as D, isStructuredOutputSchema as E, isUnboundPlaceholder as F, isStandardSchema as G, getJsonSchemaSync as H, machineSuspensionPredicates as I, toolMessage as J, persistSnapshot as K, missingActor as L, executorBoundLogics as M, getMachineSuspensionPredicate as N, normalizeGeneratorResult as O, getRegisteredAgentExecutionOptions as P, assistantMessage as R, builtinTextActors as S, getAgentOutputMode as T, getMachineStructuralHash as U, getJsonSchema as V, getStateMeta as W, validateSchemaSync as X, userMessage as Y, INTERPRET_SOURCE as _, createPlanActor as a, bindRequestExecutor as b, isPlanLogic as c, EVENT_TOOL_PREFIX as d, getAcceptedEvents as f, DECIDE_ACTOR as g, sanitizeEventToolName as h, createDecideActor as i, agentExecutionOptions as j, parseOutput as k, renderDecisionAttempts as l, parseAgentEvent as m, PLAN_DONE_EVENT_TYPE as n, initialPlanLedger as o, matchesEventPattern as p, systemMessage as q, advancePlanLedger as r, isDecisionLogic as s, DecisionExhaustedError as t, resolveDecision as u, PLAN_ACTOR as v, executeAgentTextRequest as w, buildEnvelopeSchema as x, USER_INPUT_ACTOR as y, findNonSerializableContextPaths as z };
+export { parseOutput as A, assistantMessage as B, createTextLogic as C, isTextLogic as D, isStructuredOutputSchema as E, getMachineSuspensionPredicate as F, getMachineStructuralHash as G, getAgentMessages as H, getRegisteredAgentExecutionOptions as I, persistSnapshot as J, getStateMeta as K, isUnboundPlaceholder as L, userInputActor as M, agentExecutionOptions as N, normalizeGeneratorResult as O, executorBoundLogics as P, validateSchemaSync as Q, machineSuspensionPredicates as R, builtinTextActors as S, getAgentOutputMode as T, getJsonSchema as U, findNonSerializableContextPaths as V, getJsonSchemaSync as W, toolMessage as X, systemMessage as Y, userMessage as Z, INTERPRET_SOURCE as _, createPlanActor as a, bindRequestExecutor as b, isPlanLogic as c, EVENT_TOOL_PREFIX as d, getAcceptedEvents as f, DECIDE_ACTOR as g, sanitizeEventToolName as h, createDecideActor as i, parseStructuredEnvelope as j, parseModelRef as k, renderDecisionAttempts as l, parseAgentEvent as m, PLAN_DONE_EVENT_TYPE as n, initialPlanLedger as o, matchesEventPattern as p, isStandardSchema as q, advancePlanLedger as r, isDecisionLogic as s, DecisionExhaustedError as t, resolveDecision as u, PLAN_ACTOR as v, executeAgentTextRequest as w, buildEnvelopeSchema as x, USER_INPUT_ACTOR as y, missingActor as z };

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("./src-wBfi-kTA.cjs");
-const require_decision = require("./decision-CX3YdwrO.cjs");
+const require_src = require("./src-MysDmqwT.cjs");
+const require_decision = require("./decision-BnATHy0W.cjs");
 exports.AgentIdleError = require_src.AgentIdleError;
 exports.DecisionExhaustedError = require_decision.DecisionExhaustedError;
 exports.EVENT_TOOL_PREFIX = require_decision.EVENT_TOOL_PREFIX;
@@ -32,7 +32,9 @@ exports.lintAgentMachine = require_src.lintAgentMachine;
 exports.matchesEventPattern = require_decision.matchesEventPattern;
 exports.messagesSchema = require_src.messagesSchema;
 exports.parseAgentEvent = require_decision.parseAgentEvent;
+exports.parseModelRef = require_decision.parseModelRef;
 exports.parseOutput = require_decision.parseOutput;
+exports.parseStructuredEnvelope = require_decision.parseStructuredEnvelope;
 exports.persistSnapshot = require_decision.persistSnapshot;
 exports.renderDecisionAttempts = require_decision.renderDecisionAttempts;
 exports.resolveAgentRequests = require_src.resolveAgentRequests;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { C as ToolCallPart, D as UserMessage, E as ToolResultPart, S as TextPart, T as ToolResultOutput, _ as ImagePart, a as AgentToolDescriptor, b as StandardSchemaV1, c as AgentTools, d as AssistantMessage, f as ChosenEvent, g as FilePart, h as EventUnion, i as AgentToolChoice, l as AllowedEventPattern, m as EventPayload, n as AgentSnapshotStore, o as AgentToolExecute, p as DataContent, r as AgentTool, s as AgentToolSchema, t as AgentMessage, u as AllowedEvents, v as InferOutput, w as ToolMessage, x as SystemMessage, y as ProviderOptions } from "./types-BHjeDdch.cjs";
-import { A as AgentPlanInput, B as AgentEventDescriptor, C as createTextLogic, D as AgentDecisionExecutor, E as parseOutput, F as DecisionLogicConfig, G as getAcceptedEvents, H as AgentRequestOptions, I as PLAN_DONE_EVENT_TYPE, K as matchesEventPattern, L as ResolveDecisionOptions, M as DecisionAttempt, N as DecisionExhaustedError, O as AgentDecisionInput, P as DecisionLogic, R as renderDecisionAttempts, S as buildEnvelopeSchema, T as isStructuredOutputSchema, U as AgentRequestSource, V as AgentEventToolNameResolver, W as EVENT_TOOL_PREFIX, _ as TextLogicExecuteArgs, a as AgentRequestExecutorInfo, b as TextLogicOutput, c as AgentRequestMode, d as AiSdkShapedStreamResult, f as AiSdkShapedTextResult, g as TextLogicConfig, h as TextLogic, i as AgentRequestExecutor, j as AgentPlanOutput, k as AgentDecisionRequest, l as AgentTextRequest, m as StructuredOutputEnvelope, n as AgentModelRef, o as AgentRequestExecutorResult, p as BuiltinAgentActors, q as parseAgentEvent, r as AgentOutputMode, s as AgentRequestExecutors, t as AgentModelMap, u as AgentUserInput, v as TextLogicExecutor, w as getAgentOutputMode, x as bindRequestExecutor, y as TextLogicInput, z as resolveDecision } from "./text-logic-1ZQkO3zr.cjs";
+import { A as AgentDecisionInput, B as renderDecisionAttempts, C as createTextLogic, D as parseOutput, E as parseModelRef, F as DecisionExhaustedError, G as AgentRequestSource, H as AgentEventDescriptor, I as DecisionLogic, J as matchesEventPattern, K as EVENT_TOOL_PREFIX, L as DecisionLogicConfig, M as AgentPlanInput, N as AgentPlanOutput, O as parseStructuredEnvelope, P as DecisionAttempt, R as PLAN_DONE_EVENT_TYPE, S as buildEnvelopeSchema, T as isStructuredOutputSchema, U as AgentEventToolNameResolver, V as resolveDecision, W as AgentRequestOptions, Y as parseAgentEvent, _ as TextLogicExecuteArgs, a as AgentRequestExecutorInfo, b as TextLogicOutput, c as AgentRequestMode, d as AiSdkShapedStreamResult, f as AiSdkShapedTextResult, g as TextLogicConfig, h as TextLogic, i as AgentRequestExecutor, j as AgentDecisionRequest, k as AgentDecisionExecutor, l as AgentTextRequest, m as StructuredOutputEnvelope, n as AgentModelRef, o as AgentRequestExecutorResult, p as BuiltinAgentActors, q as getAcceptedEvents, r as AgentOutputMode, s as AgentRequestExecutors, t as AgentModelMap, u as AgentUserInput, v as TextLogicExecutor, w as getAgentOutputMode, x as bindRequestExecutor, y as TextLogicInput, z as ResolveDecisionOptions } from "./text-logic-4Q2F9kyr.cjs";
 import { a as getMachineStructuralHash, c as persistSnapshot, d as userMessage, f as validateSchemaSync, i as getJsonSchemaSync, l as systemMessage, n as getAgentMessages, o as getStateMeta, r as getJsonSchema, s as isStandardSchema, t as assistantMessage, u as toolMessage } from "./utils-lK1wnL2i.cjs";
 import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, MachineContext, MetaObject, NonReducibleUnknown, OutputFrom, SetupReturnFromConfig, SetupStateSchema, Snapshot, SnapshotFrom } from "xstate";
 
@@ -256,16 +256,49 @@ type AgentSetupXStateConfig<TContextSchema extends StandardSchemaV1<Record<strin
   guards?: NonNullable<AnySetupConfig["guards"]>;
   delays?: NonNullable<AnySetupConfig["delays"]>;
 };
-type SetupAgentBaseConfig<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TRequestSchemas extends AgentRequestSchemaMap, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>> = ({
+/**
+ * Field-level context-narrowing sugar for one `setupAgent({ states })` entry:
+ * each `context` entry overrides that field's schema inside the state; every
+ * other field keeps the base context schema. Sugar for the full xstate form —
+ * `{ context: { draft: z.string() } }` resolves to
+ * `{ schemas: { context: <base with draft: string> } }` — so only the fields
+ * that change are declared, not the whole context schema.
+ */
+interface AgentStateNarrowing {
+  context: Record<string, StandardSchemaV1>;
+  states?: Record<string, AgentSetupStateSchema>;
+}
+/** One `setupAgent({ states })` entry: xstate's {@link SetupStateSchema} full form, or the {@link AgentStateNarrowing} field-level sugar. */
+type AgentSetupStateSchema = SetupStateSchema | AgentStateNarrowing;
+type NarrowedContext<TContextSchema extends StandardSchemaV1, TFields extends Record<string, StandardSchemaV1>> = Omit<InferOutput<TContextSchema>, keyof TFields> & { [K in keyof TFields]: InferOutput<TFields[K]> };
+type ResolveAgentStateSchema<TContextSchema extends StandardSchemaV1, T> = T extends {
+  context: infer TFields extends Record<string, StandardSchemaV1>;
+} ? {
+  schemas: {
+    context: StandardSchemaV1<NarrowedContext<TContextSchema, TFields>>;
+  };
+} & (T extends {
+  states: infer TChildren extends Record<string, AgentSetupStateSchema>;
+} ? {
+  states: ResolveAgentStateSchemas<TContextSchema, TChildren>;
+} : {}) : T extends {
+  states: infer TChildren extends Record<string, AgentSetupStateSchema>;
+} ? Omit<T, "states"> & {
+  states: ResolveAgentStateSchemas<TContextSchema, TChildren>;
+} : T;
+type ResolveAgentStateSchemas<TContextSchema extends StandardSchemaV1, TStates extends Record<string, AgentSetupStateSchema>> = Constrain<{ [K in keyof TStates]: ResolveAgentStateSchema<TContextSchema, TStates[K]> }, Record<string, SetupStateSchema>>;
+type SetupAgentBaseConfig<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TRequestSchemas extends AgentRequestSchemaMap, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, AgentSetupStateSchema> = Record<string, AgentSetupStateSchema>> = ({
   schemas: AgentSchemaPack<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>;
 } | AgentSchemaConfig<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>) & {
   models?: TModels;
   actorSources?: TActors;
   /**
-   * Per-state schemas, mirroring xstate's `setup({ states })`: declare a
-   * `schemas.context` on a state to narrow `context` inside that state
-   * (invoke `input`, transition fns, final `output`) — e.g. mark a field
-   * non-null in states only reachable after it is set.
+   * Per-state schemas, mirroring xstate's `setup({ states })`: narrow
+   * `context` inside a state (invoke `input`, transition fns, final `output`)
+   * — e.g. mark a field non-null in states only reachable after it is set.
+   * Two forms per state: the {@link AgentStateNarrowing} sugar
+   * (`{ context: { draft: z.string() } }` — only the fields that change) or
+   * xstate's full `{ schemas: { context } }` with a complete context schema.
    */
   states?: TStateSchemas;
   requests?: AgentRequestInput<TRequestSchemas, AgentModelRef<TModels>>;
@@ -284,7 +317,7 @@ type SetupAgentBaseConfig<TContextSchema extends StandardSchemaV1<Record<string,
    */
   isSuspended?: (snapshot: AnyMachineSnapshot) => boolean;
 };
-type SetupAgentXStateResult<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>> = SetupReturnFromConfig<AgentSetupXStateConfig<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>>;
+type SetupAgentXStateResult<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, AgentSetupStateSchema> = Record<string, AgentSetupStateSchema>> = SetupReturnFromConfig<AgentSetupXStateConfig<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, ResolveAgentStateSchemas<TContextSchema, TStateSchemas>>>;
 /**
  * The object returned by {@link setupAgent}: an xstate `setup(...)` result
  * (`createMachine`, `assign`, …) extended with `schemas` (the resolved
@@ -293,7 +326,7 @@ type SetupAgentXStateResult<TContextSchema extends StandardSchemaV1<Record<strin
  * `runAgent` and the free step helpers can resolve their schemas/actors
  * without re-passing them each call.
  */
-type SetupAgentResult<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>> = Omit<SetupAgentXStateResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>, "createMachine"> & {
+type SetupAgentResult<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, AgentSetupStateSchema> = Record<string, AgentSetupStateSchema>> = Omit<SetupAgentXStateResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>, "createMachine"> & {
   /**
    * Creates the agent machine — XState's own `createMachine`, plus: the
    * machine is registered so step helpers and {@link runAgent} can resolve
@@ -358,7 +391,7 @@ type SetupAgentResult<TContextSchema extends StandardSchemaV1<Record<string, unk
  * });
  * ```
  */
-declare function setupAgent<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap = {}, TInputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TMetaSchema extends StandardSchemaV1 = StandardSchemaV1<MetaObject>, TModels extends AgentModelMap = {}, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, const TStateSchemas extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>>(config: SetupAgentBaseConfig<TContextSchema, TEventSchemas, TActors, TInputSchema, TOutputSchema, TMetaSchema, TRequestSchemas, TModels, TEmittedSchemas, TStateSchemas>): SetupAgentResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>;
+declare function setupAgent<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap = {}, TInputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TMetaSchema extends StandardSchemaV1 = StandardSchemaV1<MetaObject>, TModels extends AgentModelMap = {}, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, const TStateSchemas extends Record<string, AgentSetupStateSchema> = Record<string, AgentSetupStateSchema>>(config: SetupAgentBaseConfig<TContextSchema, TEventSchemas, TActors, TInputSchema, TOutputSchema, TMetaSchema, TRequestSchemas, TModels, TEmittedSchemas, TStateSchemas>): SetupAgentResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>;
 declare namespace setupAgent {
   /**
    * Builds a state machine from a serializable {@link AgentWorkflowConfig}
@@ -658,9 +691,9 @@ declare class AgentIdleError extends Error {
   readonly acceptedTypes: string[];
   constructor(snapshot: AnyMachineSnapshot, acceptedTypes: string[]);
 }
-/** Handler for `agent.userInput` invokes passed as {@link RunAgentOptions.userInput}. */
+/** Handler for `agent.userInput` invokes passed as {@link RunAgentOptions.userInput}. Resolves to what the human typed. */
 interface AgentUserInputExecutor {
-  (input: AgentUserInput): PromiseLike<unknown>;
+  (input: AgentUserInput): PromiseLike<string>;
 }
 type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
   runId: string;
@@ -924,7 +957,7 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
  * actor is stopped on every settle path — there is no live actor to resume;
  * resume is always by snapshot.
  */
-/** A pending unhandled `agent.userInput` invoke surfaced on an idle settle — `id` is the invoke's id, `input` its resolved invoke input (prompt, schema, …). Answer it by resuming with a `userInput` handler. */
+/** A pending unhandled `agent.userInput` invoke surfaced on an idle settle — `id` is the invoke's id, `input` its resolved invoke input (prompt, metadata). Answer it by resuming with a `userInput` handler. */
 interface PendingUserInput {
   id: string;
   input: AgentUserInput | undefined;
@@ -1214,4 +1247,4 @@ interface CanReachResult {
  */
 declare function canReach(machine: AnyStateMachine, statePath: string, options?: ExplorePathsOptions): Promise<CanReachResult>;
 //#endregion
-export { type AgentDecisionExecutor, type AgentDecisionInput, type AgentDecisionRequest, type AgentEventDescriptor, type AgentEventToolNameResolver, AgentIdleError, type AgentLintDiagnostic, type AgentLintSeverity, type AgentMessage, type AgentModelMap, type AgentModelRef, type AgentOutputMode, type AgentPathReport, type AgentPathTerminal, type AgentPlanInput, type AgentPlanOutput, type AgentPlanRequest, type AgentRequest, type AgentRequestConfig, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestMode, type AgentRequestOptions, type AgentRequestSource, type AgentSchemaPack, type AgentSnapshotStore, type AgentStateRequest, type AgentStep, type AgentStepRequest, type AgentTextRequest, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentToolSchema, type AgentTools, type AgentTraceEvent, type AgentUserInput, type AgentUserInputExecutor, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AiSdkShapedStreamResult, type AiSdkShapedTextResult, type AllowedEventPattern, type AllowedEvents, type AssistantMessage, type CanReachResult, type ChosenEvent, type DataContent, type DecisionAttempt, DecisionExhaustedError, type DecisionLogic, type DecisionLogicConfig, EVENT_TOOL_PREFIX, type EventPayload, type EventUnion, type ExplorePathsOptions, type FilePart, type FromConfigOptions, IllegalResumeEventError, type ImagePart, type InferOutput, type InspectedActorRef, type LintAgentMachineOptions, PLAN_DONE_EVENT_TYPE, type PendingUserInput, type ProviderOptions, type ResolveAgentRequestsOptions, type ResolveDecisionOptions, type RunAgentOptions, type RunAgentResult, type SchemaCompiler, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, SnapshotVersionMismatchError, type StandardSchemaV1, type StructuredOutputEnvelope, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextLogicInput, type TextLogicOutput, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultOutput, type ToolResultPart, type UserMessage, appendMessages, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentSchemas, createTextLogic, executeAgentRequest, explorePaths, getAcceptedEvents, getAgentMessages, getAgentOutputMode, getAgentRequests, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getStateMeta, initialAgentStep, inspectTransitions, isStandardSchema, isStructuredOutputSchema, lintAgentMachine, matchesEventPattern, messagesSchema, parseAgentEvent, parseOutput, persistSnapshot, renderDecisionAttempts, resolveAgentRequests, resolveAgentStep, resolveDecision, runAgent, runAgentToCompletion, setupAgent, simulateAgent, systemMessage, toolMessage, transitionAgentStep, userMessage, validateSchemaSync };
+export { type AgentDecisionExecutor, type AgentDecisionInput, type AgentDecisionRequest, type AgentEventDescriptor, type AgentEventToolNameResolver, AgentIdleError, type AgentLintDiagnostic, type AgentLintSeverity, type AgentMessage, type AgentModelMap, type AgentModelRef, type AgentOutputMode, type AgentPathReport, type AgentPathTerminal, type AgentPlanInput, type AgentPlanOutput, type AgentPlanRequest, type AgentRequest, type AgentRequestConfig, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestMode, type AgentRequestOptions, type AgentRequestSource, type AgentSchemaPack, type AgentSetupStateSchema, type AgentSnapshotStore, type AgentStateNarrowing, type AgentStateRequest, type AgentStep, type AgentStepRequest, type AgentTextRequest, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentToolSchema, type AgentTools, type AgentTraceEvent, type AgentUserInput, type AgentUserInputExecutor, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AiSdkShapedStreamResult, type AiSdkShapedTextResult, type AllowedEventPattern, type AllowedEvents, type AssistantMessage, type CanReachResult, type ChosenEvent, type DataContent, type DecisionAttempt, DecisionExhaustedError, type DecisionLogic, type DecisionLogicConfig, EVENT_TOOL_PREFIX, type EventPayload, type EventUnion, type ExplorePathsOptions, type FilePart, type FromConfigOptions, IllegalResumeEventError, type ImagePart, type InferOutput, type InspectedActorRef, type LintAgentMachineOptions, PLAN_DONE_EVENT_TYPE, type PendingUserInput, type ProviderOptions, type ResolveAgentRequestsOptions, type ResolveDecisionOptions, type RunAgentOptions, type RunAgentResult, type SchemaCompiler, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, SnapshotVersionMismatchError, type StandardSchemaV1, type StructuredOutputEnvelope, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextLogicInput, type TextLogicOutput, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultOutput, type ToolResultPart, type UserMessage, appendMessages, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentSchemas, createTextLogic, executeAgentRequest, explorePaths, getAcceptedEvents, getAgentMessages, getAgentOutputMode, getAgentRequests, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getStateMeta, initialAgentStep, inspectTransitions, isStandardSchema, isStructuredOutputSchema, lintAgentMachine, matchesEventPattern, messagesSchema, parseAgentEvent, parseModelRef, parseOutput, parseStructuredEnvelope, persistSnapshot, renderDecisionAttempts, resolveAgentRequests, resolveAgentStep, resolveDecision, runAgent, runAgentToCompletion, setupAgent, simulateAgent, systemMessage, toolMessage, transitionAgentStep, userMessage, validateSchemaSync };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { C as ToolCallPart, D as UserMessage, E as ToolResultPart, S as TextPart, T as ToolResultOutput, _ as ImagePart, a as AgentToolDescriptor, b as StandardSchemaV1, c as AgentTools, d as AssistantMessage, f as ChosenEvent, g as FilePart, h as EventUnion, i as AgentToolChoice, l as AllowedEventPattern, m as EventPayload, n as AgentSnapshotStore, o as AgentToolExecute, p as DataContent, r as AgentTool, s as AgentToolSchema, t as AgentMessage, u as AllowedEvents, v as InferOutput, w as ToolMessage, x as SystemMessage, y as ProviderOptions } from "./types-Cq1YlAQ6.mjs";
-import { A as AgentPlanInput, B as AgentEventDescriptor, C as createTextLogic, D as AgentDecisionExecutor, E as parseOutput, F as DecisionLogicConfig, G as getAcceptedEvents, H as AgentRequestOptions, I as PLAN_DONE_EVENT_TYPE, K as matchesEventPattern, L as ResolveDecisionOptions, M as DecisionAttempt, N as DecisionExhaustedError, O as AgentDecisionInput, P as DecisionLogic, R as renderDecisionAttempts, S as buildEnvelopeSchema, T as isStructuredOutputSchema, U as AgentRequestSource, V as AgentEventToolNameResolver, W as EVENT_TOOL_PREFIX, _ as TextLogicExecuteArgs, a as AgentRequestExecutorInfo, b as TextLogicOutput, c as AgentRequestMode, d as AiSdkShapedStreamResult, f as AiSdkShapedTextResult, g as TextLogicConfig, h as TextLogic, i as AgentRequestExecutor, j as AgentPlanOutput, k as AgentDecisionRequest, l as AgentTextRequest, m as StructuredOutputEnvelope, n as AgentModelRef, o as AgentRequestExecutorResult, p as BuiltinAgentActors, q as parseAgentEvent, r as AgentOutputMode, s as AgentRequestExecutors, t as AgentModelMap, u as AgentUserInput, v as TextLogicExecutor, w as getAgentOutputMode, x as bindRequestExecutor, y as TextLogicInput, z as resolveDecision } from "./text-logic-2EMJIS-n.mjs";
+import { A as AgentDecisionInput, B as renderDecisionAttempts, C as createTextLogic, D as parseOutput, E as parseModelRef, F as DecisionExhaustedError, G as AgentRequestSource, H as AgentEventDescriptor, I as DecisionLogic, J as matchesEventPattern, K as EVENT_TOOL_PREFIX, L as DecisionLogicConfig, M as AgentPlanInput, N as AgentPlanOutput, O as parseStructuredEnvelope, P as DecisionAttempt, R as PLAN_DONE_EVENT_TYPE, S as buildEnvelopeSchema, T as isStructuredOutputSchema, U as AgentEventToolNameResolver, V as resolveDecision, W as AgentRequestOptions, Y as parseAgentEvent, _ as TextLogicExecuteArgs, a as AgentRequestExecutorInfo, b as TextLogicOutput, c as AgentRequestMode, d as AiSdkShapedStreamResult, f as AiSdkShapedTextResult, g as TextLogicConfig, h as TextLogic, i as AgentRequestExecutor, j as AgentDecisionRequest, k as AgentDecisionExecutor, l as AgentTextRequest, m as StructuredOutputEnvelope, n as AgentModelRef, o as AgentRequestExecutorResult, p as BuiltinAgentActors, q as getAcceptedEvents, r as AgentOutputMode, s as AgentRequestExecutors, t as AgentModelMap, u as AgentUserInput, v as TextLogicExecutor, w as getAgentOutputMode, x as bindRequestExecutor, y as TextLogicInput, z as ResolveDecisionOptions } from "./text-logic-2wFNEznm.mjs";
 import { a as getMachineStructuralHash, c as persistSnapshot, d as userMessage, f as validateSchemaSync, i as getJsonSchemaSync, l as systemMessage, n as getAgentMessages, o as getStateMeta, r as getJsonSchema, s as isStandardSchema, t as assistantMessage, u as toolMessage } from "./utils-CWUCa3pF.mjs";
 import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnySetupConfig, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, MachineContext, MetaObject, NonReducibleUnknown, OutputFrom, SetupReturnFromConfig, SetupStateSchema, Snapshot, SnapshotFrom } from "xstate";
 
@@ -256,16 +256,49 @@ type AgentSetupXStateConfig<TContextSchema extends StandardSchemaV1<Record<strin
   guards?: NonNullable<AnySetupConfig["guards"]>;
   delays?: NonNullable<AnySetupConfig["delays"]>;
 };
-type SetupAgentBaseConfig<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TRequestSchemas extends AgentRequestSchemaMap, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>> = ({
+/**
+ * Field-level context-narrowing sugar for one `setupAgent({ states })` entry:
+ * each `context` entry overrides that field's schema inside the state; every
+ * other field keeps the base context schema. Sugar for the full xstate form —
+ * `{ context: { draft: z.string() } }` resolves to
+ * `{ schemas: { context: <base with draft: string> } }` — so only the fields
+ * that change are declared, not the whole context schema.
+ */
+interface AgentStateNarrowing {
+  context: Record<string, StandardSchemaV1>;
+  states?: Record<string, AgentSetupStateSchema>;
+}
+/** One `setupAgent({ states })` entry: xstate's {@link SetupStateSchema} full form, or the {@link AgentStateNarrowing} field-level sugar. */
+type AgentSetupStateSchema = SetupStateSchema | AgentStateNarrowing;
+type NarrowedContext<TContextSchema extends StandardSchemaV1, TFields extends Record<string, StandardSchemaV1>> = Omit<InferOutput<TContextSchema>, keyof TFields> & { [K in keyof TFields]: InferOutput<TFields[K]> };
+type ResolveAgentStateSchema<TContextSchema extends StandardSchemaV1, T> = T extends {
+  context: infer TFields extends Record<string, StandardSchemaV1>;
+} ? {
+  schemas: {
+    context: StandardSchemaV1<NarrowedContext<TContextSchema, TFields>>;
+  };
+} & (T extends {
+  states: infer TChildren extends Record<string, AgentSetupStateSchema>;
+} ? {
+  states: ResolveAgentStateSchemas<TContextSchema, TChildren>;
+} : {}) : T extends {
+  states: infer TChildren extends Record<string, AgentSetupStateSchema>;
+} ? Omit<T, "states"> & {
+  states: ResolveAgentStateSchemas<TContextSchema, TChildren>;
+} : T;
+type ResolveAgentStateSchemas<TContextSchema extends StandardSchemaV1, TStates extends Record<string, AgentSetupStateSchema>> = Constrain<{ [K in keyof TStates]: ResolveAgentStateSchema<TContextSchema, TStates[K]> }, Record<string, SetupStateSchema>>;
+type SetupAgentBaseConfig<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TRequestSchemas extends AgentRequestSchemaMap, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, AgentSetupStateSchema> = Record<string, AgentSetupStateSchema>> = ({
   schemas: AgentSchemaPack<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>;
 } | AgentSchemaConfig<TContextSchema, TEventSchemas, TInputSchema, TOutputSchema, TMetaSchema, TEmittedSchemas>) & {
   models?: TModels;
   actorSources?: TActors;
   /**
-   * Per-state schemas, mirroring xstate's `setup({ states })`: declare a
-   * `schemas.context` on a state to narrow `context` inside that state
-   * (invoke `input`, transition fns, final `output`) — e.g. mark a field
-   * non-null in states only reachable after it is set.
+   * Per-state schemas, mirroring xstate's `setup({ states })`: narrow
+   * `context` inside a state (invoke `input`, transition fns, final `output`)
+   * — e.g. mark a field non-null in states only reachable after it is set.
+   * Two forms per state: the {@link AgentStateNarrowing} sugar
+   * (`{ context: { draft: z.string() } }` — only the fields that change) or
+   * xstate's full `{ schemas: { context } }` with a complete context schema.
    */
   states?: TStateSchemas;
   requests?: AgentRequestInput<TRequestSchemas, AgentModelRef<TModels>>;
@@ -284,7 +317,7 @@ type SetupAgentBaseConfig<TContextSchema extends StandardSchemaV1<Record<string,
    */
   isSuspended?: (snapshot: AnyMachineSnapshot) => boolean;
 };
-type SetupAgentXStateResult<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>> = SetupReturnFromConfig<AgentSetupXStateConfig<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>>;
+type SetupAgentXStateResult<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, AgentSetupStateSchema> = Record<string, AgentSetupStateSchema>> = SetupReturnFromConfig<AgentSetupXStateConfig<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, ResolveAgentStateSchemas<TContextSchema, TStateSchemas>>>;
 /**
  * The object returned by {@link setupAgent}: an xstate `setup(...)` result
  * (`createMachine`, `assign`, …) extended with `schemas` (the resolved
@@ -293,7 +326,7 @@ type SetupAgentXStateResult<TContextSchema extends StandardSchemaV1<Record<strin
  * `runAgent` and the free step helpers can resolve their schemas/actors
  * without re-passing them each call.
  */
-type SetupAgentResult<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>> = Omit<SetupAgentXStateResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>, "createMachine"> & {
+type SetupAgentResult<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap, TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetaSchema extends StandardSchemaV1, TModels extends AgentModelMap, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, TStateSchemas extends Record<string, AgentSetupStateSchema> = Record<string, AgentSetupStateSchema>> = Omit<SetupAgentXStateResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>, "createMachine"> & {
   /**
    * Creates the agent machine — XState's own `createMachine`, plus: the
    * machine is registered so step helpers and {@link runAgent} can resolve
@@ -358,7 +391,7 @@ type SetupAgentResult<TContextSchema extends StandardSchemaV1<Record<string, unk
  * });
  * ```
  */
-declare function setupAgent<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap = {}, TInputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TMetaSchema extends StandardSchemaV1 = StandardSchemaV1<MetaObject>, TModels extends AgentModelMap = {}, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, const TStateSchemas extends Record<string, SetupStateSchema> = Record<string, SetupStateSchema>>(config: SetupAgentBaseConfig<TContextSchema, TEventSchemas, TActors, TInputSchema, TOutputSchema, TMetaSchema, TRequestSchemas, TModels, TEmittedSchemas, TStateSchemas>): SetupAgentResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>;
+declare function setupAgent<TContextSchema extends StandardSchemaV1<Record<string, unknown>>, TEventSchemas extends Record<string, StandardSchemaV1>, TActors extends { [K in keyof TActors]: AnyActorLogic }, TRequestSchemas extends AgentRequestSchemaMap = {}, TInputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<NonReducibleUnknown>, TMetaSchema extends StandardSchemaV1 = StandardSchemaV1<MetaObject>, TModels extends AgentModelMap = {}, TEmittedSchemas extends Record<string, StandardSchemaV1> = {}, const TStateSchemas extends Record<string, AgentSetupStateSchema> = Record<string, AgentSetupStateSchema>>(config: SetupAgentBaseConfig<TContextSchema, TEventSchemas, TActors, TInputSchema, TOutputSchema, TMetaSchema, TRequestSchemas, TModels, TEmittedSchemas, TStateSchemas>): SetupAgentResult<TContextSchema, TEventSchemas, TActors, TRequestSchemas, TInputSchema, TOutputSchema, TMetaSchema, TModels, TEmittedSchemas, TStateSchemas>;
 declare namespace setupAgent {
   /**
    * Builds a state machine from a serializable {@link AgentWorkflowConfig}
@@ -658,9 +691,9 @@ declare class AgentIdleError extends Error {
   readonly acceptedTypes: string[];
   constructor(snapshot: AnyMachineSnapshot, acceptedTypes: string[]);
 }
-/** Handler for `agent.userInput` invokes passed as {@link RunAgentOptions.userInput}. */
+/** Handler for `agent.userInput` invokes passed as {@link RunAgentOptions.userInput}. Resolves to what the human typed. */
 interface AgentUserInputExecutor {
-  (input: AgentUserInput): PromiseLike<unknown>;
+  (input: AgentUserInput): PromiseLike<string>;
 }
 type AgentTraceEvent<TMachine extends AnyStateMachine = AnyStateMachine> = {
   runId: string;
@@ -924,7 +957,7 @@ interface RunAgentOptions<TMachine extends AnyStateMachine> {
  * actor is stopped on every settle path — there is no live actor to resume;
  * resume is always by snapshot.
  */
-/** A pending unhandled `agent.userInput` invoke surfaced on an idle settle — `id` is the invoke's id, `input` its resolved invoke input (prompt, schema, …). Answer it by resuming with a `userInput` handler. */
+/** A pending unhandled `agent.userInput` invoke surfaced on an idle settle — `id` is the invoke's id, `input` its resolved invoke input (prompt, metadata). Answer it by resuming with a `userInput` handler. */
 interface PendingUserInput {
   id: string;
   input: AgentUserInput | undefined;
@@ -1214,4 +1247,4 @@ interface CanReachResult {
  */
 declare function canReach(machine: AnyStateMachine, statePath: string, options?: ExplorePathsOptions): Promise<CanReachResult>;
 //#endregion
-export { type AgentDecisionExecutor, type AgentDecisionInput, type AgentDecisionRequest, type AgentEventDescriptor, type AgentEventToolNameResolver, AgentIdleError, type AgentLintDiagnostic, type AgentLintSeverity, type AgentMessage, type AgentModelMap, type AgentModelRef, type AgentOutputMode, type AgentPathReport, type AgentPathTerminal, type AgentPlanInput, type AgentPlanOutput, type AgentPlanRequest, type AgentRequest, type AgentRequestConfig, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestMode, type AgentRequestOptions, type AgentRequestSource, type AgentSchemaPack, type AgentSnapshotStore, type AgentStateRequest, type AgentStep, type AgentStepRequest, type AgentTextRequest, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentToolSchema, type AgentTools, type AgentTraceEvent, type AgentUserInput, type AgentUserInputExecutor, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AiSdkShapedStreamResult, type AiSdkShapedTextResult, type AllowedEventPattern, type AllowedEvents, type AssistantMessage, type CanReachResult, type ChosenEvent, type DataContent, type DecisionAttempt, DecisionExhaustedError, type DecisionLogic, type DecisionLogicConfig, EVENT_TOOL_PREFIX, type EventPayload, type EventUnion, type ExplorePathsOptions, type FilePart, type FromConfigOptions, IllegalResumeEventError, type ImagePart, type InferOutput, type InspectedActorRef, type LintAgentMachineOptions, PLAN_DONE_EVENT_TYPE, type PendingUserInput, type ProviderOptions, type ResolveAgentRequestsOptions, type ResolveDecisionOptions, type RunAgentOptions, type RunAgentResult, type SchemaCompiler, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, SnapshotVersionMismatchError, type StandardSchemaV1, type StructuredOutputEnvelope, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextLogicInput, type TextLogicOutput, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultOutput, type ToolResultPart, type UserMessage, appendMessages, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentSchemas, createTextLogic, executeAgentRequest, explorePaths, getAcceptedEvents, getAgentMessages, getAgentOutputMode, getAgentRequests, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getStateMeta, initialAgentStep, inspectTransitions, isStandardSchema, isStructuredOutputSchema, lintAgentMachine, matchesEventPattern, messagesSchema, parseAgentEvent, parseOutput, persistSnapshot, renderDecisionAttempts, resolveAgentRequests, resolveAgentStep, resolveDecision, runAgent, runAgentToCompletion, setupAgent, simulateAgent, systemMessage, toolMessage, transitionAgentStep, userMessage, validateSchemaSync };
+export { type AgentDecisionExecutor, type AgentDecisionInput, type AgentDecisionRequest, type AgentEventDescriptor, type AgentEventToolNameResolver, AgentIdleError, type AgentLintDiagnostic, type AgentLintSeverity, type AgentMessage, type AgentModelMap, type AgentModelRef, type AgentOutputMode, type AgentPathReport, type AgentPathTerminal, type AgentPlanInput, type AgentPlanOutput, type AgentPlanRequest, type AgentRequest, type AgentRequestConfig, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestMode, type AgentRequestOptions, type AgentRequestSource, type AgentSchemaPack, type AgentSetupStateSchema, type AgentSnapshotStore, type AgentStateNarrowing, type AgentStateRequest, type AgentStep, type AgentStepRequest, type AgentTextRequest, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentToolSchema, type AgentTools, type AgentTraceEvent, type AgentUserInput, type AgentUserInputExecutor, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AiSdkShapedStreamResult, type AiSdkShapedTextResult, type AllowedEventPattern, type AllowedEvents, type AssistantMessage, type CanReachResult, type ChosenEvent, type DataContent, type DecisionAttempt, DecisionExhaustedError, type DecisionLogic, type DecisionLogicConfig, EVENT_TOOL_PREFIX, type EventPayload, type EventUnion, type ExplorePathsOptions, type FilePart, type FromConfigOptions, IllegalResumeEventError, type ImagePart, type InferOutput, type InspectedActorRef, type LintAgentMachineOptions, PLAN_DONE_EVENT_TYPE, type PendingUserInput, type ProviderOptions, type ResolveAgentRequestsOptions, type ResolveDecisionOptions, type RunAgentOptions, type RunAgentResult, type SchemaCompiler, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, SnapshotVersionMismatchError, type StandardSchemaV1, type StructuredOutputEnvelope, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextLogicInput, type TextLogicOutput, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultOutput, type ToolResultPart, type UserMessage, appendMessages, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentSchemas, createTextLogic, executeAgentRequest, explorePaths, getAcceptedEvents, getAgentMessages, getAgentOutputMode, getAgentRequests, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getStateMeta, initialAgentStep, inspectTransitions, isStandardSchema, isStructuredOutputSchema, lintAgentMachine, matchesEventPattern, messagesSchema, parseAgentEvent, parseModelRef, parseOutput, parseStructuredEnvelope, persistSnapshot, renderDecisionAttempts, resolveAgentRequests, resolveAgentStep, resolveDecision, runAgent, runAgentToCompletion, setupAgent, simulateAgent, systemMessage, toolMessage, transitionAgentStep, userMessage, validateSchemaSync };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { _ as createAgentSchemas, a as AgentIdleError, b as messagesSchema, c as inspectTransitions, d as executeAgentRequest, f as getAgentRequests, g as transitionAgentStep, h as resolveAgentStep, i as simulateAgent, l as runAgent, m as resolveAgentRequests, n as explorePaths, o as IllegalResumeEventError, p as initialAgentStep, r as lintAgentMachine, s as SnapshotVersionMismatchError, t as canReach, u as runAgentToCompletion, v as setupAgent, y as appendMessages } from "./src-CEa947Dm.mjs";
-import { B as getAgentMessages, C as createTextLogic, E as isStructuredOutputSchema, G as isStandardSchema, H as getJsonSchemaSync, J as toolMessage, K as persistSnapshot, R as assistantMessage, T as getAgentOutputMode, U as getMachineStructuralHash, V as getJsonSchema, W as getStateMeta, X as validateSchemaSync, Y as userMessage, b as bindRequestExecutor, d as EVENT_TOOL_PREFIX, f as getAcceptedEvents, k as parseOutput, l as renderDecisionAttempts, m as parseAgentEvent, n as PLAN_DONE_EVENT_TYPE, p as matchesEventPattern, q as systemMessage, t as DecisionExhaustedError, u as resolveDecision, x as buildEnvelopeSchema } from "./decision-D1654JdD.mjs";
-export { AgentIdleError, DecisionExhaustedError, EVENT_TOOL_PREFIX, IllegalResumeEventError, PLAN_DONE_EVENT_TYPE, SnapshotVersionMismatchError, appendMessages, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentSchemas, createTextLogic, executeAgentRequest, explorePaths, getAcceptedEvents, getAgentMessages, getAgentOutputMode, getAgentRequests, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getStateMeta, initialAgentStep, inspectTransitions, isStandardSchema, isStructuredOutputSchema, lintAgentMachine, matchesEventPattern, messagesSchema, parseAgentEvent, parseOutput, persistSnapshot, renderDecisionAttempts, resolveAgentRequests, resolveAgentStep, resolveDecision, runAgent, runAgentToCompletion, setupAgent, simulateAgent, systemMessage, toolMessage, transitionAgentStep, userMessage, validateSchemaSync };
+import { _ as createAgentSchemas, a as AgentIdleError, b as messagesSchema, c as inspectTransitions, d as executeAgentRequest, f as getAgentRequests, g as transitionAgentStep, h as resolveAgentStep, i as simulateAgent, l as runAgent, m as resolveAgentRequests, n as explorePaths, o as IllegalResumeEventError, p as initialAgentStep, r as lintAgentMachine, s as SnapshotVersionMismatchError, t as canReach, u as runAgentToCompletion, v as setupAgent, y as appendMessages } from "./src-BpQdxsKc.mjs";
+import { A as parseOutput, B as assistantMessage, C as createTextLogic, E as isStructuredOutputSchema, G as getMachineStructuralHash, H as getAgentMessages, J as persistSnapshot, K as getStateMeta, Q as validateSchemaSync, T as getAgentOutputMode, U as getJsonSchema, W as getJsonSchemaSync, X as toolMessage, Y as systemMessage, Z as userMessage, b as bindRequestExecutor, d as EVENT_TOOL_PREFIX, f as getAcceptedEvents, j as parseStructuredEnvelope, k as parseModelRef, l as renderDecisionAttempts, m as parseAgentEvent, n as PLAN_DONE_EVENT_TYPE, p as matchesEventPattern, q as isStandardSchema, t as DecisionExhaustedError, u as resolveDecision, x as buildEnvelopeSchema } from "./decision-mPR_YQd8.mjs";
+export { AgentIdleError, DecisionExhaustedError, EVENT_TOOL_PREFIX, IllegalResumeEventError, PLAN_DONE_EVENT_TYPE, SnapshotVersionMismatchError, appendMessages, assistantMessage, bindRequestExecutor, buildEnvelopeSchema, canReach, createAgentSchemas, createTextLogic, executeAgentRequest, explorePaths, getAcceptedEvents, getAgentMessages, getAgentOutputMode, getAgentRequests, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getStateMeta, initialAgentStep, inspectTransitions, isStandardSchema, isStructuredOutputSchema, lintAgentMachine, matchesEventPattern, messagesSchema, parseAgentEvent, parseModelRef, parseOutput, parseStructuredEnvelope, persistSnapshot, renderDecisionAttempts, resolveAgentRequests, resolveAgentStep, resolveDecision, runAgent, runAgentToCompletion, setupAgent, simulateAgent, systemMessage, toolMessage, transitionAgentStep, userMessage, validateSchemaSync };

package/dist/openai-compat.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_decision = require("./decision-CX3YdwrO.cjs");
+const require_decision = require("./decision-BnATHy0W.cjs");
 //#region src/openai-compat/index.ts
 /**
 * OpenAI-compatible Chat Completions adapter — a COMPLETE `{ generateText,

package/dist/openai-compat.d.cts

@@ -1,5 +1,5 @@
 import { c as AgentTools } from "./types-BHjeDdch.cjs";
-import { B as AgentEventDescriptor, D as AgentDecisionExecutor, k as AgentDecisionRequest, l as AgentTextRequest, s as AgentRequestExecutors } from "./text-logic-1ZQkO3zr.cjs";
+import { H as AgentEventDescriptor, j as AgentDecisionRequest, k as AgentDecisionExecutor, l as AgentTextRequest, s as AgentRequestExecutors } from "./text-logic-4Q2F9kyr.cjs";
 import { r as getJsonSchema } from "./utils-lK1wnL2i.cjs";
 
 //#region src/openai-compat/index.d.ts

package/dist/openai-compat.d.mts

@@ -1,5 +1,5 @@
 import { c as AgentTools } from "./types-Cq1YlAQ6.mjs";
-import { B as AgentEventDescriptor, D as AgentDecisionExecutor, k as AgentDecisionRequest, l as AgentTextRequest, s as AgentRequestExecutors } from "./text-logic-2EMJIS-n.mjs";
+import { H as AgentEventDescriptor, j as AgentDecisionRequest, k as AgentDecisionExecutor, l as AgentTextRequest, s as AgentRequestExecutors } from "./text-logic-2wFNEznm.mjs";
 import { r as getJsonSchema } from "./utils-CWUCa3pF.mjs";
 
 //#region src/openai-compat/index.d.ts

package/dist/openai-compat.mjs

@@ -1,4 +1,4 @@
-import { G as isStandardSchema, H as getJsonSchemaSync, T as getAgentOutputMode, V as getJsonSchema, l as renderDecisionAttempts, x as buildEnvelopeSchema } from "./decision-D1654JdD.mjs";
+import { T as getAgentOutputMode, U as getJsonSchema, W as getJsonSchemaSync, l as renderDecisionAttempts, q as isStandardSchema, x as buildEnvelopeSchema } from "./decision-mPR_YQd8.mjs";
 //#region src/openai-compat/index.ts
 /**
 * OpenAI-compatible Chat Completions adapter — a COMPLETE `{ generateText,

package/dist/{src-CEa947Dm.mjs → src-BpQdxsKc.mjs}

@@ -1,4 +1,4 @@
-import { A as userInputActor, B as getAgentMessages, C as createTextLogic, D as isTextLogic, F as isUnboundPlaceholder, H as getJsonSchemaSync, I as machineSuspensionPredicates, L as missingActor, M as executorBoundLogics, N as getMachineSuspensionPredicate, O as normalizeGeneratorResult, P as getRegisteredAgentExecutionOptions, R as assistantMessage, S as builtinTextActors, U as getMachineStructuralHash, X as validateSchemaSync, Y as userMessage, _ as INTERPRET_SOURCE, a as createPlanActor, c as isPlanLogic, f as getAcceptedEvents, g as DECIDE_ACTOR, h as sanitizeEventToolName, i as createDecideActor, j as agentExecutionOptions, n as PLAN_DONE_EVENT_TYPE, o as initialPlanLedger, r as advancePlanLedger, s as isDecisionLogic, t as DecisionExhaustedError, u as resolveDecision, v as PLAN_ACTOR, w as executeAgentTextRequest, y as USER_INPUT_ACTOR, z as findNonSerializableContextPaths } from "./decision-D1654JdD.mjs";
+import { B as assistantMessage, C as createTextLogic, D as isTextLogic, F as getMachineSuspensionPredicate, G as getMachineStructuralHash, H as getAgentMessages, I as getRegisteredAgentExecutionOptions, L as isUnboundPlaceholder, M as userInputActor, N as agentExecutionOptions, O as normalizeGeneratorResult, P as executorBoundLogics, Q as validateSchemaSync, R as machineSuspensionPredicates, S as builtinTextActors, V as findNonSerializableContextPaths, W as getJsonSchemaSync, Z as userMessage, _ as INTERPRET_SOURCE, a as createPlanActor, c as isPlanLogic, f as getAcceptedEvents, g as DECIDE_ACTOR, h as sanitizeEventToolName, i as createDecideActor, n as PLAN_DONE_EVENT_TYPE, o as initialPlanLedger, r as advancePlanLedger, s as isDecisionLogic, t as DecisionExhaustedError, u as resolveDecision, v as PLAN_ACTOR, w as executeAgentTextRequest, y as USER_INPUT_ACTOR, z as missingActor } from "./decision-mPR_YQd8.mjs";
 import { createActor, createAsyncLogic, getNextTransitions, initialTransition, setup, transition } from "xstate";
 //#region src/messages.ts
 function addMessages(resolve) {
@@ -278,6 +278,43 @@ function createAgentSchemas(schemas) {
 		emitted: schemas.emitted
 	};
 }
+function mergeContextSchema(base, fields) {
+	return { "~standard": {
+		version: 1,
+		vendor: "statelyai-agent",
+		validate(value) {
+			const baseResult = base["~standard"].validate(value);
+			if (baseResult instanceof Promise) throw new Error("setupAgent: async context schemas are not supported.");
+			if (baseResult.issues) return baseResult;
+			const merged = { ...baseResult.value };
+			const issues = [];
+			for (const [key, fieldSchema] of Object.entries(fields)) {
+				const fieldResult = fieldSchema["~standard"].validate(value[key]);
+				if (fieldResult instanceof Promise) throw new Error("setupAgent: async context schemas are not supported.");
+				if (fieldResult.issues) issues.push(...fieldResult.issues.map((issue) => ({
+					...issue,
+					path: [key, ...issue.path ?? []]
+				})));
+				else merged[key] = fieldResult.value;
+			}
+			return issues.length > 0 ? { issues } : { value: merged };
+		}
+	} };
+}
+function resolveAgentStateSchemas(contextSchema, states) {
+	return Object.fromEntries(Object.entries(states).map(([key, state]) => {
+		if (!state || typeof state !== "object") return [key, state];
+		const children = "states" in state && state.states ? resolveAgentStateSchemas(contextSchema, state.states) : void 0;
+		if ("context" in state && state.context) return [key, {
+			schemas: { context: mergeContextSchema(contextSchema, state.context) },
+			...children ? { states: children } : {}
+		}];
+		return [key, children ? {
+			...state,
+			states: children
+		} : state];
+	}));
+}
 /**
 * Schema-first `setup(...)` for agent machines — the standard entry point
 * for authoring a machine (the blueprint) that this library then runs (via
@@ -418,7 +455,7 @@ function createAgentSetupConfig(schemas, actorSources, config) {
 			meta: schemas.meta,
 			...schemas.emitted && Object.keys(schemas.emitted).length > 0 ? { emitted: schemas.emitted } : {}
 		},
-		...config.states ? { states: config.states } : {},
+		...config.states ? { states: resolveAgentStateSchemas(schemas.context, config.states) } : {},
 		actorSources,
 		actions: config.actions,
 		guards: config.guards,
@@ -463,6 +500,18 @@ function createSetupAgent(config) {
 * `resolveAgentRequests`.
 * @module
 */
+/** @internal Normalizes current and legacy XState invoke effect shapes. */
+function getInvokeEffectMetadata(action) {
+	if (action.type === "@xstate.spawn") return action;
+	if (action.type === "xstate.spawnChild") {
+		const params = action.params;
+		return params ? {
+			...params,
+			logic: action.logic
+		} : void 0;
+	}
+	if (action.type === "@xstate.start" && typeof action.src === "string") return action;
+}
 /**
 * Scans a set of executable actions (as returned by xstate's `transition`/
 * `initialTransition`) for spawned `TextLogic`/`DecisionLogic` invokes and
@@ -478,11 +527,10 @@ function createSetupAgent(config) {
 */
 function getAgentRequestsWith(actions, options = {}) {
 	return [...actions.flatMap((action) => {
-		if (action.type !== "xstate.spawnChild" && action.type !== "@xstate.start") return [];
-		const params = action.type === "@xstate.start" ? action : action.params;
+		const params = getInvokeEffectMetadata(action);
 		if (!params || typeof params.src !== "string") return [];
 		if (typeof params.id !== "string" || params.id.length === 0) throw new Error(`Agent invoke '${params.src}' must define a durable string id.`);
-		const registeredLogic = isTextLogic(action.logic) || isDecisionLogic(action.logic) ? action.logic : options.actorSources?.[params.src];
+		const registeredLogic = isTextLogic(params.logic) || isDecisionLogic(params.logic) ? params.logic : options.actorSources?.[params.src];
 		if (isDecisionLogic(registeredLogic)) {
 			const decisionRequest = registeredLogic.request(params.input);
 			const allowedEventTypes = registeredLogic.allowedEventTypes?.(params.input);
@@ -2143,12 +2191,10 @@ function lintAgentMachine(machine, options = {}) {
 function pendingInvokes(step) {
 	const out = [];
 	for (const action of step.actions) {
-		const type = action.type;
-		if (type !== "xstate.spawnChild" && type !== "@xstate.start") continue;
-		const params = type === "@xstate.start" ? action : action.params ?? {};
-		if (typeof params.src === "string" && typeof params.id === "string") out.push({
-			id: params.id,
-			src: params.src
+		const metadata = getInvokeEffectMetadata(action);
+		if (typeof metadata?.src === "string" && typeof metadata.id === "string") out.push({
+			id: metadata.id,
+			src: metadata.src
 		});
 	}
 	return out;

package/dist/{src-wBfi-kTA.cjs → src-MysDmqwT.cjs}

@@ -1,4 +1,4 @@
-const require_decision = require("./decision-CX3YdwrO.cjs");
+const require_decision = require("./decision-BnATHy0W.cjs");
 let xstate = require("xstate");
 //#region src/messages.ts
 function addMessages(resolve) {
@@ -278,6 +278,43 @@ function createAgentSchemas(schemas) {
 		emitted: schemas.emitted
 	};
 }
+function mergeContextSchema(base, fields) {
+	return { "~standard": {
+		version: 1,
+		vendor: "statelyai-agent",
+		validate(value) {
+			const baseResult = base["~standard"].validate(value);
+			if (baseResult instanceof Promise) throw new Error("setupAgent: async context schemas are not supported.");
+			if (baseResult.issues) return baseResult;
+			const merged = { ...baseResult.value };
+			const issues = [];
+			for (const [key, fieldSchema] of Object.entries(fields)) {
+				const fieldResult = fieldSchema["~standard"].validate(value[key]);
+				if (fieldResult instanceof Promise) throw new Error("setupAgent: async context schemas are not supported.");
+				if (fieldResult.issues) issues.push(...fieldResult.issues.map((issue) => ({
+					...issue,
+					path: [key, ...issue.path ?? []]
+				})));
+				else merged[key] = fieldResult.value;
+			}
+			return issues.length > 0 ? { issues } : { value: merged };
+		}
+	} };
+}
+function resolveAgentStateSchemas(contextSchema, states) {
+	return Object.fromEntries(Object.entries(states).map(([key, state]) => {
+		if (!state || typeof state !== "object") return [key, state];
+		const children = "states" in state && state.states ? resolveAgentStateSchemas(contextSchema, state.states) : void 0;
+		if ("context" in state && state.context) return [key, {
+			schemas: { context: mergeContextSchema(contextSchema, state.context) },
+			...children ? { states: children } : {}
+		}];
+		return [key, children ? {
+			...state,
+			states: children
+		} : state];
+	}));
+}
 /**
 * Schema-first `setup(...)` for agent machines — the standard entry point
 * for authoring a machine (the blueprint) that this library then runs (via
@@ -418,7 +455,7 @@ function createAgentSetupConfig(schemas, actorSources, config) {
 			meta: schemas.meta,
 			...schemas.emitted && Object.keys(schemas.emitted).length > 0 ? { emitted: schemas.emitted } : {}
 		},
-		...config.states ? { states: config.states } : {},
+		...config.states ? { states: resolveAgentStateSchemas(schemas.context, config.states) } : {},
 		actorSources,
 		actions: config.actions,
 		guards: config.guards,
@@ -463,6 +500,18 @@ function createSetupAgent(config) {
 * `resolveAgentRequests`.
 * @module
 */
+/** @internal Normalizes current and legacy XState invoke effect shapes. */
+function getInvokeEffectMetadata(action) {
+	if (action.type === "@xstate.spawn") return action;
+	if (action.type === "xstate.spawnChild") {
+		const params = action.params;
+		return params ? {
+			...params,
+			logic: action.logic
+		} : void 0;
+	}
+	if (action.type === "@xstate.start" && typeof action.src === "string") return action;
+}
 /**
 * Scans a set of executable actions (as returned by xstate's `transition`/
 * `initialTransition`) for spawned `TextLogic`/`DecisionLogic` invokes and
@@ -478,11 +527,10 @@ function createSetupAgent(config) {
 */
 function getAgentRequestsWith(actions, options = {}) {
 	return [...actions.flatMap((action) => {
-		if (action.type !== "xstate.spawnChild" && action.type !== "@xstate.start") return [];
-		const params = action.type === "@xstate.start" ? action : action.params;
+		const params = getInvokeEffectMetadata(action);
 		if (!params || typeof params.src !== "string") return [];
 		if (typeof params.id !== "string" || params.id.length === 0) throw new Error(`Agent invoke '${params.src}' must define a durable string id.`);
-		const registeredLogic = require_decision.isTextLogic(action.logic) || require_decision.isDecisionLogic(action.logic) ? action.logic : options.actorSources?.[params.src];
+		const registeredLogic = require_decision.isTextLogic(params.logic) || require_decision.isDecisionLogic(params.logic) ? params.logic : options.actorSources?.[params.src];
 		if (require_decision.isDecisionLogic(registeredLogic)) {
 			const decisionRequest = registeredLogic.request(params.input);
 			const allowedEventTypes = registeredLogic.allowedEventTypes?.(params.input);
@@ -2143,12 +2191,10 @@ function lintAgentMachine(machine, options = {}) {
 function pendingInvokes(step) {
 	const out = [];
 	for (const action of step.actions) {
-		const type = action.type;
-		if (type !== "xstate.spawnChild" && type !== "@xstate.start") continue;
-		const params = type === "@xstate.start" ? action : action.params ?? {};
-		if (typeof params.src === "string" && typeof params.id === "string") out.push({
-			id: params.id,
-			src: params.src
+		const metadata = getInvokeEffectMetadata(action);
+		if (typeof metadata?.src === "string" && typeof metadata.id === "string") out.push({
+			id: metadata.id,
+			src: metadata.src
 		});
 	}
 	return out;

package/dist/{text-logic-2EMJIS-n.d.mts → text-logic-2wFNEznm.d.mts}

@@ -383,6 +383,21 @@ type AgentModelMap = Record<string, unknown>;
  * adapter's models map / `resolveModel`) resolves them to a real model.
  */
 type AgentModelRef<TModels extends AgentModelMap = {}> = [keyof TModels] extends [never] ? string : (keyof TModels & string) | (string & {});
+/**
+ * Splits a portable `"provider/model-id"` model ref (the convention JSON
+ * workflows and registry-less hosts use, e.g. `"openai/gpt-5.4-mini"`) into
+ * its parts. A ref with no `/` has no provider — `modelId` is the whole ref.
+ * The standard building block for a host's `resolveModel`:
+ *
+ * @example
+ * ```ts
+ * const resolveModel = (ref: string) => openai(parseModelRef(ref).modelId);
+ * ```
+ */
+declare function parseModelRef(modelRef: string): {
+  provider: string | undefined;
+  modelId: string;
+};
 /**
  * Portable, provider-agnostic input a text request passes to a host
  * executor (`generateText`/`streamText` on {@link AgentRequestExecutors}).
@@ -437,17 +452,22 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>> {
    */
   metadata?: TMetadata;
 }
-/** Inline input for the `agent.userInput` builtin actor — a human-input request (CLI prompt, form, chat reply, …). See {@link RunAgentOptions.userInput}. */
+/**
+ * Inline input for the `agent.userInput` builtin actor — a human-input request
+ * (CLI prompt, chat reply, …) that resolves to the `string` the human typed.
+ * See {@link RunAgentOptions.userInput}. For structured input, parse/classify
+ * the string in a follow-up state, or register a custom actor source; host
+ * rendering hints (a form spec, say) belong in `metadata`.
+ */
 interface AgentUserInput<TMetadata = Record<string, unknown>> {
   prompt?: string;
-  schema?: StandardSchemaV1;
   metadata?: TMetadata;
 }
 /** The five `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
 type BuiltinAgentActors<TEvent extends string = string, TModel extends string = string> = {
   [GENERATE_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
   [STREAM_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
-  [USER_INPUT_ACTOR]: AsyncActorLogic<unknown, AgentUserInput>;
+  [USER_INPUT_ACTOR]: AsyncActorLogic<string, AgentUserInput>;
   [DECIDE_ACTOR]: AsyncActorLogic<ChosenEvent, AgentDecisionInput<TEvent, Record<string, unknown>, TModel>>;
   [PLAN_ACTOR]: PlanLogic<StandardSchemaV1<AgentPlanInput<TEvent, Record<string, unknown>, TModel>>>;
 };
@@ -564,7 +584,7 @@ declare function createTextLogic<TInputSchema extends StandardSchemaV1, TOutputS
  * });
  * ```
  */
-declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata>(logic: TextLogic<TInputSchema, TOutputSchema, TMetadata>, executor: AgentRequestExecutor): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
+declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata>(logic: TextLogic<TInputSchema, TOutputSchema, TMetadata>, executor: AgentRequestExecutor, info?: Pick<AgentRequestExecutorInfo, "onChunk">): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
 /**
  * The envelope an {@link AgentRequestExecutor} must return: `{ output }` where
  * `output` is the request's value (a text string or a structured object).
@@ -678,5 +698,13 @@ interface StructuredOutputEnvelope {
 declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
   reasoning?: boolean;
 }): StandardSchemaV1<StructuredOutputEnvelope>;
+/**
+ * Validates a raw provider value against the structured-output envelope for
+ * `request` and returns the unwrapped `{ result, reasoning? }` — the checked
+ * replacement for `raw as StructuredOutputEnvelope` in hand-written hosts.
+ * Pair with {@link buildEnvelopeSchema} (which produced the schema the
+ * provider was asked to satisfy).
+ */
+declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "reasoning">, value: unknown): StructuredOutputEnvelope;
 //#endregion
-export { AgentPlanInput as A, AgentEventDescriptor as B, createTextLogic as C, AgentDecisionExecutor as D, parseOutput as E, DecisionLogicConfig as F, getAcceptedEvents as G, AgentRequestOptions as H, PLAN_DONE_EVENT_TYPE as I, matchesEventPattern as K, ResolveDecisionOptions as L, DecisionAttempt as M, DecisionExhaustedError as N, AgentDecisionInput as O, DecisionLogic as P, renderDecisionAttempts as R, buildEnvelopeSchema as S, isStructuredOutputSchema as T, AgentRequestSource as U, AgentEventToolNameResolver as V, EVENT_TOOL_PREFIX as W, TextLogicExecuteArgs as _, AgentRequestExecutorInfo as a, TextLogicOutput as b, AgentRequestMode as c, AiSdkShapedStreamResult as d, AiSdkShapedTextResult as f, TextLogicConfig as g, TextLogic as h, AgentRequestExecutor as i, AgentPlanOutput as j, AgentDecisionRequest as k, AgentTextRequest as l, StructuredOutputEnvelope as m, AgentModelRef as n, AgentRequestExecutorResult as o, BuiltinAgentActors as p, parseAgentEvent as q, AgentOutputMode as r, AgentRequestExecutors as s, AgentModelMap as t, AgentUserInput as u, TextLogicExecutor as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicInput as y, resolveDecision as z };
+export { AgentDecisionInput as A, renderDecisionAttempts as B, createTextLogic as C, parseOutput as D, parseModelRef as E, DecisionExhaustedError as F, AgentRequestSource as G, AgentEventDescriptor as H, DecisionLogic as I, matchesEventPattern as J, EVENT_TOOL_PREFIX as K, DecisionLogicConfig as L, AgentPlanInput as M, AgentPlanOutput as N, parseStructuredEnvelope as O, DecisionAttempt as P, PLAN_DONE_EVENT_TYPE as R, buildEnvelopeSchema as S, isStructuredOutputSchema as T, AgentEventToolNameResolver as U, resolveDecision as V, AgentRequestOptions as W, parseAgentEvent as Y, TextLogicExecuteArgs as _, AgentRequestExecutorInfo as a, TextLogicOutput as b, AgentRequestMode as c, AiSdkShapedStreamResult as d, AiSdkShapedTextResult as f, TextLogicConfig as g, TextLogic as h, AgentRequestExecutor as i, AgentDecisionRequest as j, AgentDecisionExecutor as k, AgentTextRequest as l, StructuredOutputEnvelope as m, AgentModelRef as n, AgentRequestExecutorResult as o, BuiltinAgentActors as p, getAcceptedEvents as q, AgentOutputMode as r, AgentRequestExecutors as s, AgentModelMap as t, AgentUserInput as u, TextLogicExecutor as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicInput as y, ResolveDecisionOptions as z };

package/dist/{text-logic-1ZQkO3zr.d.cts → text-logic-4Q2F9kyr.d.cts}

@@ -383,6 +383,21 @@ type AgentModelMap = Record<string, unknown>;
  * adapter's models map / `resolveModel`) resolves them to a real model.
  */
 type AgentModelRef<TModels extends AgentModelMap = {}> = [keyof TModels] extends [never] ? string : (keyof TModels & string) | (string & {});
+/**
+ * Splits a portable `"provider/model-id"` model ref (the convention JSON
+ * workflows and registry-less hosts use, e.g. `"openai/gpt-5.4-mini"`) into
+ * its parts. A ref with no `/` has no provider — `modelId` is the whole ref.
+ * The standard building block for a host's `resolveModel`:
+ *
+ * @example
+ * ```ts
+ * const resolveModel = (ref: string) => openai(parseModelRef(ref).modelId);
+ * ```
+ */
+declare function parseModelRef(modelRef: string): {
+  provider: string | undefined;
+  modelId: string;
+};
 /**
  * Portable, provider-agnostic input a text request passes to a host
  * executor (`generateText`/`streamText` on {@link AgentRequestExecutors}).
@@ -437,17 +452,22 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>> {
    */
   metadata?: TMetadata;
 }
-/** Inline input for the `agent.userInput` builtin actor — a human-input request (CLI prompt, form, chat reply, …). See {@link RunAgentOptions.userInput}. */
+/**
+ * Inline input for the `agent.userInput` builtin actor — a human-input request
+ * (CLI prompt, chat reply, …) that resolves to the `string` the human typed.
+ * See {@link RunAgentOptions.userInput}. For structured input, parse/classify
+ * the string in a follow-up state, or register a custom actor source; host
+ * rendering hints (a form spec, say) belong in `metadata`.
+ */
 interface AgentUserInput<TMetadata = Record<string, unknown>> {
   prompt?: string;
-  schema?: StandardSchemaV1;
   metadata?: TMetadata;
 }
 /** The five `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
 type BuiltinAgentActors<TEvent extends string = string, TModel extends string = string> = {
   [GENERATE_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
   [STREAM_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
-  [USER_INPUT_ACTOR]: AsyncActorLogic<unknown, AgentUserInput>;
+  [USER_INPUT_ACTOR]: AsyncActorLogic<string, AgentUserInput>;
   [DECIDE_ACTOR]: AsyncActorLogic<ChosenEvent, AgentDecisionInput<TEvent, Record<string, unknown>, TModel>>;
   [PLAN_ACTOR]: PlanLogic<StandardSchemaV1<AgentPlanInput<TEvent, Record<string, unknown>, TModel>>>;
 };
@@ -564,7 +584,7 @@ declare function createTextLogic<TInputSchema extends StandardSchemaV1, TOutputS
  * });
  * ```
  */
-declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata>(logic: TextLogic<TInputSchema, TOutputSchema, TMetadata>, executor: AgentRequestExecutor): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
+declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata>(logic: TextLogic<TInputSchema, TOutputSchema, TMetadata>, executor: AgentRequestExecutor, info?: Pick<AgentRequestExecutorInfo, "onChunk">): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
 /**
  * The envelope an {@link AgentRequestExecutor} must return: `{ output }` where
  * `output` is the request's value (a text string or a structured object).
@@ -678,5 +698,13 @@ interface StructuredOutputEnvelope {
 declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
   reasoning?: boolean;
 }): StandardSchemaV1<StructuredOutputEnvelope>;
+/**
+ * Validates a raw provider value against the structured-output envelope for
+ * `request` and returns the unwrapped `{ result, reasoning? }` — the checked
+ * replacement for `raw as StructuredOutputEnvelope` in hand-written hosts.
+ * Pair with {@link buildEnvelopeSchema} (which produced the schema the
+ * provider was asked to satisfy).
+ */
+declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "reasoning">, value: unknown): StructuredOutputEnvelope;
 //#endregion
-export { AgentPlanInput as A, AgentEventDescriptor as B, createTextLogic as C, AgentDecisionExecutor as D, parseOutput as E, DecisionLogicConfig as F, getAcceptedEvents as G, AgentRequestOptions as H, PLAN_DONE_EVENT_TYPE as I, matchesEventPattern as K, ResolveDecisionOptions as L, DecisionAttempt as M, DecisionExhaustedError as N, AgentDecisionInput as O, DecisionLogic as P, renderDecisionAttempts as R, buildEnvelopeSchema as S, isStructuredOutputSchema as T, AgentRequestSource as U, AgentEventToolNameResolver as V, EVENT_TOOL_PREFIX as W, TextLogicExecuteArgs as _, AgentRequestExecutorInfo as a, TextLogicOutput as b, AgentRequestMode as c, AiSdkShapedStreamResult as d, AiSdkShapedTextResult as f, TextLogicConfig as g, TextLogic as h, AgentRequestExecutor as i, AgentPlanOutput as j, AgentDecisionRequest as k, AgentTextRequest as l, StructuredOutputEnvelope as m, AgentModelRef as n, AgentRequestExecutorResult as o, BuiltinAgentActors as p, parseAgentEvent as q, AgentOutputMode as r, AgentRequestExecutors as s, AgentModelMap as t, AgentUserInput as u, TextLogicExecutor as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicInput as y, resolveDecision as z };
+export { AgentDecisionInput as A, renderDecisionAttempts as B, createTextLogic as C, parseOutput as D, parseModelRef as E, DecisionExhaustedError as F, AgentRequestSource as G, AgentEventDescriptor as H, DecisionLogic as I, matchesEventPattern as J, EVENT_TOOL_PREFIX as K, DecisionLogicConfig as L, AgentPlanInput as M, AgentPlanOutput as N, parseStructuredEnvelope as O, DecisionAttempt as P, PLAN_DONE_EVENT_TYPE as R, buildEnvelopeSchema as S, isStructuredOutputSchema as T, AgentEventToolNameResolver as U, resolveDecision as V, AgentRequestOptions as W, parseAgentEvent as Y, TextLogicExecuteArgs as _, AgentRequestExecutorInfo as a, TextLogicOutput as b, AgentRequestMode as c, AiSdkShapedStreamResult as d, AiSdkShapedTextResult as f, TextLogicConfig as g, TextLogic as h, AgentRequestExecutor as i, AgentDecisionRequest as j, AgentDecisionExecutor as k, AgentTextRequest as l, StructuredOutputEnvelope as m, AgentModelRef as n, AgentRequestExecutorResult as o, BuiltinAgentActors as p, getAcceptedEvents as q, AgentOutputMode as r, AgentRequestExecutors as s, AgentModelMap as t, AgentUserInput as u, TextLogicExecutor as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicInput as y, ResolveDecisionOptions as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/agent",
-  "version": "2.0.0-alpha.6",
+  "version": "2.0.0-alpha.7",
   "description": "State-machine authoring layer for AI agents",
   "type": "module",
   "main": "dist/index.cjs",
@@ -96,7 +96,7 @@
     "tsx": "^4.21.0",
     "typescript": "^5.6.2",
     "vitest": "^2.1.2",
-    "xstate": "6.0.0-alpha.17",
+    "xstate": "6.0.0-alpha.21",
     "zod": "^4.3.6"
   },
   "publishConfig": {

package/readme.md

@@ -132,6 +132,7 @@ The example has one model decision and two final outcomes. Real machines can add
 <!-- starter examples derived from examples/*/metadata.json and examples/index.ts -->
 
 - [Twenty Questions](examples/twenty-questions) shows a model choosing legal events in a loop.
+- [Go Fish](examples/go-fish) pits a model against a human while the machine enforces hidden-information game rules.
 - [Human in the loop](examples/human-in-the-loop) pauses, stores a snapshot, and resumes after review.
 - [Ticket triage](examples/triage) returns structured data from a model request.
 - [JSON agent](examples/json-agent) runs a machine defined as data.