@statelyai/agent 2.0.0-alpha.20 → 2.0.0-alpha.22

package/dist/{decision-DhsKLYAI.cjs → decision-1o45_ZrS.cjs}

@@ -363,6 +363,13 @@ function getCallUsage(raw) {
 	}
 	return out;
 }
+function textRequestSourceIssue(request) {
+	const hasPrompt = typeof request.prompt === "string" && request.prompt.length > 0;
+	const hasMessages = Array.isArray(request.messages) && request.messages.length > 0;
+	const label = request.name ? ` '${request.name}'` : "";
+	if (hasPrompt && hasMessages) return `Agent text request${label} has both a non-empty \`prompt\` and \`messages\` — provide exactly one so the model has a single input source.`;
+	if (!hasPrompt && !hasMessages) return `Agent text request${label} has neither a non-empty \`prompt\` nor \`messages\` — provide at least one so the model has something to respond to.`;
+}
 const agentTextInputSchema = { "~standard": {
 	version: 1,
 	vendor: "statelyai-agent",
@@ -370,9 +377,8 @@ const agentTextInputSchema = { "~standard": {
 		if (!value || typeof value !== "object") return { issues: [{ message: "Expected agent text input object" }] };
 		const request = value;
 		if (typeof request.model !== "string") return { issues: [{ message: "Expected agent text input with a string `model`" }] };
-		const hasPrompt = typeof request.prompt === "string" && request.prompt.length > 0;
-		const hasMessages = Array.isArray(request.messages) && request.messages.length > 0;
-		if (!hasPrompt && !hasMessages) return { issues: [{ message: `Agent text request${request.name ? ` '${request.name}'` : ""} has neither a non-empty \`prompt\` nor \`messages\` — provide at least one so the model has something to respond to.` }] };
+		const issue = textRequestSourceIssue(request);
+		if (issue) return { issues: [{ message: issue }] };
 		return { value: request };
 	}
 } };
@@ -424,7 +430,7 @@ function createBuiltinTextActor(src, mode, outputSchema) {
 				messages: ({ input }) => input.messages,
 				tools: ({ input }) => input.tools,
 				toolChoice: ({ input }) => input.toolChoice,
-				reasoning: ({ input }) => input.reasoning,
+				includeReasoning: ({ input }) => input.includeReasoning,
 				temperature: ({ input }) => input.temperature,
 				maxOutputTokens: ({ input }) => input.maxOutputTokens,
 				topP: ({ input }) => input.topP,
@@ -487,16 +493,25 @@ function createTextLogic(config, execute) {
 	};
 	const request = (input) => {
 		const args = { input: validateSchemaSync(schemas.input, input) };
+		const name = resolveTextLogicValue(config.name, args);
+		const prompt = resolveTextLogicValue(config.prompt, args);
+		const messages = resolveTextLogicValue(config.messages, args);
+		const sourceIssue = textRequestSourceIssue({
+			name,
+			prompt,
+			messages
+		});
+		if (sourceIssue) throw new Error(sourceIssue);
 		return {
-			name: resolveTextLogicValue(config.name, args),
+			name,
 			model: resolveTextLogicValue(config.model, args),
 			system: resolveTextLogicValue(config.system, args),
-			prompt: resolveTextLogicValue(config.prompt, args),
-			messages: resolveTextLogicValue(config.messages, args),
+			prompt,
+			messages,
 			tools: resolveTextLogicValue(config.tools, args),
 			toolChoice: resolveTextLogicValue(config.toolChoice, args),
 			outputSchema: schemas.output,
-			reasoning: resolveTextLogicValue(config.reasoning, args),
+			includeReasoning: resolveTextLogicValue(config.includeReasoning, args),
 			temperature: resolveTextLogicValue(config.temperature, args),
 			maxOutputTokens: resolveTextLogicValue(config.maxOutputTokens, args),
 			topP: resolveTextLogicValue(config.topP, args),
@@ -643,7 +658,7 @@ function buildEnvelopeSchema(inner, options = {}) {
 */
 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);
+	return validateSchemaSync(buildEnvelopeSchema(request.outputSchema, { reasoning: request.includeReasoning }), value);
 }
 /**
 * Merges request-declared and call-site `tools`, dispatches to the
@@ -663,6 +678,8 @@ async function executeAgentTextRequest(mode, id, input, executors, tools = {}, i
 			...tools
 		}
 	};
+	const sourceIssue = textRequestSourceIssue(request);
+	if (sourceIssue) throw new Error(sourceIssue);
 	const executor = mode === "stream" ? executors.streamText : executors.generateText;
 	if (!executor) throw new Error(`No executor provided for ${mode === "stream" ? "stream" : "generate"} request '${id}'.`);
 	const raw = await executor(request, info);
@@ -911,6 +928,82 @@ function resolveAllowedEventTypes(allowedEvents, input) {
 	const resolved = typeof allowedEvents === "function" ? allowedEvents({ input }) : allowedEvents;
 	return typeof resolved === "string" ? [resolved] : resolved;
 }
+/**
+* Creates reusable, standalone {@link DecisionLogic}: an actor that, when
+* run, resolves to exactly one currently-legal {@link ChosenEvent} by
+* calling the host `decide` executor (passed here as `execute`, or supplied
+* later via {@link DecisionLogic.withExecutor}, `machine.provide(...)`, or
+* `runAgent`'s `decide` option). Register the result under `actors:` and
+* invoke it by name; for a one-off, state-local decision, prefer the
+* `agent.decide` builtin invoke instead — it needs no separate declaration
+* and types `allowedEvents` against the machine's own event schemas.
+*
+* @example
+* ```ts
+* import { createDecisionLogic } from '@statelyai/agent';
+* import { z } from 'zod';
+*
+* export const chooseMove = createDecisionLogic({
+*   schemas: { input: z.object({ playerHp: z.number(), enemyHp: z.number() }) },
+*   model: 'openai/gpt-5.4-mini',
+*   system: 'You are playing a turn-based game. Choose exactly one legal move.',
+*   prompt: ({ input }) => `Player HP: ${input.playerHp}\nEnemy HP: ${input.enemyHp}`,
+*   allowedEvents: ({ input }) =>
+*     input.playerHp <= 6
+*       ? ['ATTACK', 'DEFEND', 'HEAL', 'FLEE']
+*       : ['ATTACK', 'DEFEND', 'FLEE'],
+* });
+* ```
+*/
+function createDecisionLogic(config, execute) {
+	const maxRetries = config.maxRetries ?? 2;
+	const request = (input) => {
+		const parsedInput = config.schemas ? validateSchemaSync(config.schemas.input, input) : input;
+		const args = { input: parsedInput };
+		const allowedEventTypes = resolveAllowedEventTypes(config.allowedEvents, parsedInput);
+		return {
+			kind: "decision",
+			id: "",
+			model: resolveTextLogicValue(config.model, args),
+			system: resolveTextLogicValue(config.system, args),
+			prompt: resolveTextLogicValue(config.prompt, args),
+			messages: resolveTextLogicValue(config.messages, args),
+			events: (allowedEventTypes ?? []).map((type) => ({
+				type,
+				toolName: sanitizeEventToolName(type)
+			})),
+			attempts: [],
+			temperature: resolveTextLogicValue(config.temperature, args),
+			maxOutputTokens: resolveTextLogicValue(config.maxOutputTokens, args),
+			topP: resolveTextLogicValue(config.topP, args),
+			topK: resolveTextLogicValue(config.topK, args),
+			seed: resolveTextLogicValue(config.seed, args),
+			stopSequences: resolveTextLogicValue(config.stopSequences, args),
+			metadata: resolveTextLogicValue(config.metadata, args)
+		};
+	};
+	const logic = (0, xstate.createAsyncLogic)({ run: async ({ input, signal }) => {
+		if (!execute) throw new Error("Decision logic has no host execution. Pass an executor as the second argument to createDecisionLogic(...), provide a runtime adapter, or extract it with getAgentEffects(..., { actors }) and resolveDecision(...).");
+		const allowedEventTypes = resolveAllowedEventTypes(config.allowedEvents, input);
+		if (allowedEventTypes === void 0) throw new Error("Decision logic has omitted `allowedEvents`, which means \"all currently-legal events\" — but that requires a snapshot-aware host (runAgent or the step path) to resolve. Under a bare createActor(...), declare `allowedEvents` explicitly on this logic to use it here.");
+		if (allowedEventTypes.some(isEventPattern)) throw new Error("Decision logic uses wildcard `allowedEvents` patterns, which expand against the live snapshot — that requires a snapshot-aware host (runAgent or the step path). Under a bare createActor(...), list event types explicitly.");
+		return resolveDecision(request(input), { decide: execute }, {
+			maxRetries,
+			signal
+		});
+	} });
+	const decisionLogic = Object.assign(logic, {
+		kind: "statelyai.decisionLogic",
+		maxRetries,
+		request,
+		allowedEventTypes: (input) => resolveAllowedEventTypes(config.allowedEvents, input),
+		withExecutor(nextExecute) {
+			return createDecisionLogic(config, nextExecute);
+		}
+	});
+	if (execute) executorBoundLogics.add(decisionLogic);
+	return decisionLogic;
+}
 /** Type guard: true for any actor logic built by createDecisionLogic/createDecideActor (checks the `kind` marker). @internal */
 function isDecisionLogic(value) {
 	return !!value && typeof value === "object" && value.kind === "statelyai.decisionLogic" && typeof value.request === "function";
@@ -1048,12 +1141,24 @@ Object.defineProperty(exports, "DECIDE_ACTOR", {
 		return DECIDE_ACTOR;
 	}
 });
+Object.defineProperty(exports, "GENERATE_TEXT_ACTOR", {
+	enumerable: true,
+	get: function() {
+		return GENERATE_TEXT_ACTOR;
+	}
+});
 Object.defineProperty(exports, "INTERPRET_SOURCE", {
 	enumerable: true,
 	get: function() {
 		return INTERPRET_SOURCE;
 	}
 });
+Object.defineProperty(exports, "STREAM_TEXT_ACTOR", {
+	enumerable: true,
+	get: function() {
+		return STREAM_TEXT_ACTOR;
+	}
+});
 Object.defineProperty(exports, "USER_INPUT_ACTOR", {
 	enumerable: true,
 	get: function() {
@@ -1096,6 +1201,12 @@ Object.defineProperty(exports, "createDecideActor", {
 		return createDecideActor;
 	}
 });
+Object.defineProperty(exports, "createDecisionLogic", {
+	enumerable: true,
+	get: function() {
+		return createDecisionLogic;
+	}
+});
 Object.defineProperty(exports, "createTextLogic", {
 	enumerable: true,
 	get: function() {

package/dist/{decision-BfhSgCc6.mjs → decision-DxSTqzgZ.mjs}

@@ -362,6 +362,13 @@ function getCallUsage(raw) {
 	}
 	return out;
 }
+function textRequestSourceIssue(request) {
+	const hasPrompt = typeof request.prompt === "string" && request.prompt.length > 0;
+	const hasMessages = Array.isArray(request.messages) && request.messages.length > 0;
+	const label = request.name ? ` '${request.name}'` : "";
+	if (hasPrompt && hasMessages) return `Agent text request${label} has both a non-empty \`prompt\` and \`messages\` — provide exactly one so the model has a single input source.`;
+	if (!hasPrompt && !hasMessages) return `Agent text request${label} has neither a non-empty \`prompt\` nor \`messages\` — provide at least one so the model has something to respond to.`;
+}
 const agentTextInputSchema = { "~standard": {
 	version: 1,
 	vendor: "statelyai-agent",
@@ -369,9 +376,8 @@ const agentTextInputSchema = { "~standard": {
 		if (!value || typeof value !== "object") return { issues: [{ message: "Expected agent text input object" }] };
 		const request = value;
 		if (typeof request.model !== "string") return { issues: [{ message: "Expected agent text input with a string `model`" }] };
-		const hasPrompt = typeof request.prompt === "string" && request.prompt.length > 0;
-		const hasMessages = Array.isArray(request.messages) && request.messages.length > 0;
-		if (!hasPrompt && !hasMessages) return { issues: [{ message: `Agent text request${request.name ? ` '${request.name}'` : ""} has neither a non-empty \`prompt\` nor \`messages\` — provide at least one so the model has something to respond to.` }] };
+		const issue = textRequestSourceIssue(request);
+		if (issue) return { issues: [{ message: issue }] };
 		return { value: request };
 	}
 } };
@@ -423,7 +429,7 @@ function createBuiltinTextActor(src, mode, outputSchema) {
 				messages: ({ input }) => input.messages,
 				tools: ({ input }) => input.tools,
 				toolChoice: ({ input }) => input.toolChoice,
-				reasoning: ({ input }) => input.reasoning,
+				includeReasoning: ({ input }) => input.includeReasoning,
 				temperature: ({ input }) => input.temperature,
 				maxOutputTokens: ({ input }) => input.maxOutputTokens,
 				topP: ({ input }) => input.topP,
@@ -486,16 +492,25 @@ function createTextLogic(config, execute) {
 	};
 	const request = (input) => {
 		const args = { input: validateSchemaSync(schemas.input, input) };
+		const name = resolveTextLogicValue(config.name, args);
+		const prompt = resolveTextLogicValue(config.prompt, args);
+		const messages = resolveTextLogicValue(config.messages, args);
+		const sourceIssue = textRequestSourceIssue({
+			name,
+			prompt,
+			messages
+		});
+		if (sourceIssue) throw new Error(sourceIssue);
 		return {
-			name: resolveTextLogicValue(config.name, args),
+			name,
 			model: resolveTextLogicValue(config.model, args),
 			system: resolveTextLogicValue(config.system, args),
-			prompt: resolveTextLogicValue(config.prompt, args),
-			messages: resolveTextLogicValue(config.messages, args),
+			prompt,
+			messages,
 			tools: resolveTextLogicValue(config.tools, args),
 			toolChoice: resolveTextLogicValue(config.toolChoice, args),
 			outputSchema: schemas.output,
-			reasoning: resolveTextLogicValue(config.reasoning, args),
+			includeReasoning: resolveTextLogicValue(config.includeReasoning, args),
 			temperature: resolveTextLogicValue(config.temperature, args),
 			maxOutputTokens: resolveTextLogicValue(config.maxOutputTokens, args),
 			topP: resolveTextLogicValue(config.topP, args),
@@ -642,7 +657,7 @@ function buildEnvelopeSchema(inner, options = {}) {
 */
 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);
+	return validateSchemaSync(buildEnvelopeSchema(request.outputSchema, { reasoning: request.includeReasoning }), value);
 }
 /**
 * Merges request-declared and call-site `tools`, dispatches to the
@@ -662,6 +677,8 @@ async function executeAgentTextRequest(mode, id, input, executors, tools = {}, i
 			...tools
 		}
 	};
+	const sourceIssue = textRequestSourceIssue(request);
+	if (sourceIssue) throw new Error(sourceIssue);
 	const executor = mode === "stream" ? executors.streamText : executors.generateText;
 	if (!executor) throw new Error(`No executor provided for ${mode === "stream" ? "stream" : "generate"} request '${id}'.`);
 	const raw = await executor(request, info);
@@ -910,6 +927,82 @@ function resolveAllowedEventTypes(allowedEvents, input) {
 	const resolved = typeof allowedEvents === "function" ? allowedEvents({ input }) : allowedEvents;
 	return typeof resolved === "string" ? [resolved] : resolved;
 }
+/**
+* Creates reusable, standalone {@link DecisionLogic}: an actor that, when
+* run, resolves to exactly one currently-legal {@link ChosenEvent} by
+* calling the host `decide` executor (passed here as `execute`, or supplied
+* later via {@link DecisionLogic.withExecutor}, `machine.provide(...)`, or
+* `runAgent`'s `decide` option). Register the result under `actors:` and
+* invoke it by name; for a one-off, state-local decision, prefer the
+* `agent.decide` builtin invoke instead — it needs no separate declaration
+* and types `allowedEvents` against the machine's own event schemas.
+*
+* @example
+* ```ts
+* import { createDecisionLogic } from '@statelyai/agent';
+* import { z } from 'zod';
+*
+* export const chooseMove = createDecisionLogic({
+*   schemas: { input: z.object({ playerHp: z.number(), enemyHp: z.number() }) },
+*   model: 'openai/gpt-5.4-mini',
+*   system: 'You are playing a turn-based game. Choose exactly one legal move.',
+*   prompt: ({ input }) => `Player HP: ${input.playerHp}\nEnemy HP: ${input.enemyHp}`,
+*   allowedEvents: ({ input }) =>
+*     input.playerHp <= 6
+*       ? ['ATTACK', 'DEFEND', 'HEAL', 'FLEE']
+*       : ['ATTACK', 'DEFEND', 'FLEE'],
+* });
+* ```
+*/
+function createDecisionLogic(config, execute) {
+	const maxRetries = config.maxRetries ?? 2;
+	const request = (input) => {
+		const parsedInput = config.schemas ? validateSchemaSync(config.schemas.input, input) : input;
+		const args = { input: parsedInput };
+		const allowedEventTypes = resolveAllowedEventTypes(config.allowedEvents, parsedInput);
+		return {
+			kind: "decision",
+			id: "",
+			model: resolveTextLogicValue(config.model, args),
+			system: resolveTextLogicValue(config.system, args),
+			prompt: resolveTextLogicValue(config.prompt, args),
+			messages: resolveTextLogicValue(config.messages, args),
+			events: (allowedEventTypes ?? []).map((type) => ({
+				type,
+				toolName: sanitizeEventToolName(type)
+			})),
+			attempts: [],
+			temperature: resolveTextLogicValue(config.temperature, args),
+			maxOutputTokens: resolveTextLogicValue(config.maxOutputTokens, args),
+			topP: resolveTextLogicValue(config.topP, args),
+			topK: resolveTextLogicValue(config.topK, args),
+			seed: resolveTextLogicValue(config.seed, args),
+			stopSequences: resolveTextLogicValue(config.stopSequences, args),
+			metadata: resolveTextLogicValue(config.metadata, args)
+		};
+	};
+	const logic = createAsyncLogic({ run: async ({ input, signal }) => {
+		if (!execute) throw new Error("Decision logic has no host execution. Pass an executor as the second argument to createDecisionLogic(...), provide a runtime adapter, or extract it with getAgentEffects(..., { actors }) and resolveDecision(...).");
+		const allowedEventTypes = resolveAllowedEventTypes(config.allowedEvents, input);
+		if (allowedEventTypes === void 0) throw new Error("Decision logic has omitted `allowedEvents`, which means \"all currently-legal events\" — but that requires a snapshot-aware host (runAgent or the step path) to resolve. Under a bare createActor(...), declare `allowedEvents` explicitly on this logic to use it here.");
+		if (allowedEventTypes.some(isEventPattern)) throw new Error("Decision logic uses wildcard `allowedEvents` patterns, which expand against the live snapshot — that requires a snapshot-aware host (runAgent or the step path). Under a bare createActor(...), list event types explicitly.");
+		return resolveDecision(request(input), { decide: execute }, {
+			maxRetries,
+			signal
+		});
+	} });
+	const decisionLogic = Object.assign(logic, {
+		kind: "statelyai.decisionLogic",
+		maxRetries,
+		request,
+		allowedEventTypes: (input) => resolveAllowedEventTypes(config.allowedEvents, input),
+		withExecutor(nextExecute) {
+			return createDecisionLogic(config, nextExecute);
+		}
+	});
+	if (execute) executorBoundLogics.add(decisionLogic);
+	return decisionLogic;
+}
 /** Type guard: true for any actor logic built by createDecisionLogic/createDecideActor (checks the `kind` marker). @internal */
 function isDecisionLogic(value) {
 	return !!value && typeof value === "object" && value.kind === "statelyai.decisionLogic" && typeof value.request === "function";
@@ -1029,4 +1122,4 @@ async function resolveDecision(request, executors, options = {}) {
 	throw new AgentDecisionExhaustedError(attempts);
 }
 //#endregion
-export { isUnboundPlaceholder as A, getMachineStructuralHash as B, parseStructuredEnvelope as C, getMachineIdlePredicate as D, executorBoundLogics as E, djb2Hex as F, toolMessage as G, isStandardSchema as H, findNonSerializableContextPaths as I, userMessage as K, getAgentMessages as L, machineStaticTransitionTargets as M, missingActor as N, getMachineStaticTransitionTargets as O, assistantMessage as P, getJsonSchema as R, parseOutput as S, agentExecutionOptions as T, resolveMachineVersion as U, getStateMeta as V, systemMessage as W, getAgentOutputMode as _, resolveDecision as a, normalizeGeneratorResult as b, AGENT_USAGE_TOKEN_FIELDS as c, USER_INPUT_ACTOR as d, bindRequestExecutor as f, executeAgentTextRequest as g, createTextLogic as h, renderDecisionAttempts as i, machineIdlePredicates as j, getRegisteredAgentExecutionOptions as k, DECIDE_ACTOR as l, builtinTextActors as m, createDecideActor as n, getAcceptedEvents as o, buildEnvelopeSchema as p, validateSchemaSync as q, isDecisionLogic as r, parseAgentEvent as s, AgentDecisionExhaustedError as t, INTERPRET_SOURCE as u, getCallUsage as v, userInputActor as w, parseModelRef as x, isTextLogic as y, getJsonSchemaSync as z };
+export { getMachineIdlePredicate as A, getAgentMessages as B, normalizeGeneratorResult as C, userInputActor as D, parseStructuredEnvelope as E, machineStaticTransitionTargets as F, isStandardSchema as G, getJsonSchemaSync as H, missingActor as I, toolMessage as J, resolveMachineVersion as K, assistantMessage as L, getRegisteredAgentExecutionOptions as M, isUnboundPlaceholder as N, agentExecutionOptions as O, machineIdlePredicates as P, djb2Hex as R, isTextLogic as S, parseOutput as T, getMachineStructuralHash as U, getJsonSchema as V, getStateMeta as W, validateSchemaSync as X, userMessage as Y, builtinTextActors as _, renderDecisionAttempts as a, getAgentOutputMode as b, parseAgentEvent as c, GENERATE_TEXT_ACTOR as d, INTERPRET_SOURCE as f, buildEnvelopeSchema as g, bindRequestExecutor as h, isDecisionLogic as i, getMachineStaticTransitionTargets as j, executorBoundLogics as k, AGENT_USAGE_TOKEN_FIELDS as l, USER_INPUT_ACTOR as m, createDecideActor as n, resolveDecision as o, STREAM_TEXT_ACTOR as p, systemMessage as q, createDecisionLogic as r, getAcceptedEvents as s, AgentDecisionExhaustedError as t, DECIDE_ACTOR as u, createTextLogic as v, parseModelRef as w, getCallUsage as x, executeAgentTextRequest as y, findNonSerializableContextPaths as z };