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

package/dist/{run-agent-CwmzAZwj.d.mts → run-agent-0fpEZ1wJ.d.mts}

@@ -1,6 +1,6 @@
-import { T as WithAgentInputSchema, c as AgentTools, d as ChosenEvent, h as InferInput, n as AgentMessage, v as StandardSchemaV1 } from "./types-DYpK3QF4.mjs";
+import { T as WithAgentInputSchema, c as AgentTools, d as ChosenEvent, h as InferInput, n as AgentMessage, v as StandardSchemaV1 } from "./types-CvWRGFxP.mjs";
 import { t as AgentError } from "./errors-C9rxnWbX.mjs";
-import { H as AgentRequestSource, N as AgentDecisionRequest, V as AgentRequestOptions, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode, z as AgentEventDescriptor } from "./text-logic-Er5KkTX6.mjs";
+import { N as AgentDecisionRequest, U as AgentRequestOptions, V as AgentEventDescriptor, W as AgentRequestSource, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode } from "./text-logic-DhfFWzu9.mjs";
 import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-hrA1vqtN.mjs";
 import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, ExecutableActionObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, createActor } from "xstate";
 
@@ -934,7 +934,7 @@ declare class AgentMaxModelCallsExceededError extends AgentError {
  * declared input schema — and machines reached through `.provide(...)`, which
  * drops the brand — fall back to xstate's `InputFrom`.
  */
-type AgentInputFrom<TMachine extends AnyStateMachine> = InputFrom<TMachine> extends WithAgentInputSchema<infer TInputSchema> ? [TInputSchema] extends [StandardSchemaV1] ? InferInput<TInputSchema> : InputFrom<TMachine> : InputFrom<TMachine>;
+type AgentInputFrom<TMachine extends AnyStateMachine> = [NonNullable<InputFrom<TMachine>>] extends [WithAgentInputSchema<infer TInputSchema>] ? [TInputSchema] extends [StandardSchemaV1] ? InferInput<TInputSchema> : InputFrom<TMachine> : InputFrom<TMachine>;
 /**
  * Runs an agent machine to completion or idle: a `createActor` host that
  * binds `options`' host executors onto the machine's `agent.*`/`TextLogic`/

package/dist/{run-agent--4bbms-D.d.cts → run-agent-Zbkx7XP8.d.cts}

@@ -1,6 +1,6 @@
-import { T as WithAgentInputSchema, c as AgentTools, d as ChosenEvent, h as InferInput, n as AgentMessage, v as StandardSchemaV1 } from "./types-pJ5Hn8fv.cjs";
+import { T as WithAgentInputSchema, c as AgentTools, d as ChosenEvent, h as InferInput, n as AgentMessage, v as StandardSchemaV1 } from "./types-DSdj2tGs.cjs";
 import { t as AgentError } from "./errors-BQRk9eiZ.cjs";
-import { H as AgentRequestSource, N as AgentDecisionRequest, V as AgentRequestOptions, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode, z as AgentEventDescriptor } from "./text-logic-Cavva1W6.cjs";
+import { N as AgentDecisionRequest, U as AgentRequestOptions, V as AgentEventDescriptor, W as AgentRequestSource, d as AgentTextRequest, f as AgentUsage, l as AgentRequestExecutors, p as AgentUserInput, t as AgentCallUsage, u as AgentRequestMode } from "./text-logic-BaxPrcLk.cjs";
 import { i as AgentLogEntry, o as JsonValue } from "./event-log-store-Bz7HDBkE.cjs";
 import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, ExecutableActionObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, createActor } from "xstate";
 
@@ -934,7 +934,7 @@ declare class AgentMaxModelCallsExceededError extends AgentError {
  * declared input schema — and machines reached through `.provide(...)`, which
  * drops the brand — fall back to xstate's `InputFrom`.
  */
-type AgentInputFrom<TMachine extends AnyStateMachine> = InputFrom<TMachine> extends WithAgentInputSchema<infer TInputSchema> ? [TInputSchema] extends [StandardSchemaV1] ? InferInput<TInputSchema> : InputFrom<TMachine> : InputFrom<TMachine>;
+type AgentInputFrom<TMachine extends AnyStateMachine> = [NonNullable<InputFrom<TMachine>>] extends [WithAgentInputSchema<infer TInputSchema>] ? [TInputSchema] extends [StandardSchemaV1] ? InferInput<TInputSchema> : InputFrom<TMachine> : InputFrom<TMachine>;
 /**
  * Runs an agent machine to completion or idle: a `createActor` host that
  * binds `options`' host executors onto the machine's `agent.*`/`TextLogic`/

package/dist/{setup-agent-gISRLxRe.cjs → setup-agent-DkCTy5Eu.cjs}

@@ -1,5 +1,5 @@
 const require_errors = require("./errors-DUBBzRLP.cjs");
-const require_decision = require("./decision-DhsKLYAI.cjs");
+const require_decision = require("./decision-1o45_ZrS.cjs");
 const require_event_log_store = require("./event-log-store-a_TKy1gk.cjs");
 require("./validate.cjs");
 let xstate = require("xstate");
@@ -37,22 +37,88 @@ const KNOWN_PART_TYPES = new Set([
 	"tool-call",
 	"tool-result"
 ]);
+const USER_PART_TYPES = new Set([
+	"text",
+	"image",
+	"file"
+]);
+const ASSISTANT_PART_TYPES = new Set([
+	"text",
+	"file",
+	"tool-call",
+	"tool-result"
+]);
+const TOOL_PART_TYPES = new Set(["tool-result"]);
+const TOOL_RESULT_CONTENT_PART_TYPES = new Set(["text", "image"]);
 function isKnownPart(part) {
-	return !!part && typeof part === "object" && KNOWN_PART_TYPES.has(part.type);
+	const type = part && typeof part === "object" ? part.type : void 0;
+	return typeof type === "string" && KNOWN_PART_TYPES.has(type);
 }
-function validatePartsArray(content) {
-	if (!Array.isArray(content)) return "Expected content to be a string or an array of parts";
-	for (const part of content) if (!isKnownPart(part)) {
+function requireString(part, type, field) {
+	return typeof part[field] === "string" ? void 0 : `${type} part requires a string "${field}"`;
+}
+function isMediaData(value) {
+	return typeof value === "string" || value instanceof Uint8Array || value instanceof ArrayBuffer || value instanceof URL;
+}
+function requireMediaData(part, type, field) {
+	return isMediaData(part[field]) ? void 0 : `${type} part requires "${field}" to be a string, Uint8Array, ArrayBuffer, or URL`;
+}
+const TOOL_RESULT_OUTPUT_TYPES = new Set([
+	"text",
+	"json",
+	"error-text",
+	"error-json",
+	"content"
+]);
+function validateToolResultOutput(output) {
+	if (!output || typeof output !== "object" || Array.isArray(output)) return "tool-result part requires an \"output\" object";
+	const record = output;
+	const outputType = record.type;
+	if (typeof outputType !== "string" || !TOOL_RESULT_OUTPUT_TYPES.has(outputType)) return `Unknown tool-result output type: ${JSON.stringify(outputType)}`;
+	if (outputType === "text" || outputType === "error-text") {
+		if (typeof record.value !== "string") return `tool-result output of type "${outputType}" requires a string "value"`;
+		return;
+	}
+	if (outputType === "content") {
+		if (!Array.isArray(record.value)) return "tool-result output of type \"content\" requires an array \"value\"";
+		for (const contentPart of record.value) {
+			const error = validatePart(contentPart, TOOL_RESULT_CONTENT_PART_TYPES, "tool-result output content");
+			if (error) return error;
+		}
+		return;
+	}
+	return record.value !== void 0 ? void 0 : `tool-result output of type "${outputType}" requires a "value"`;
+}
+function validatePart(part, allowedTypes, location) {
+	if (!isKnownPart(part)) {
 		const type = part && typeof part === "object" ? part.type : void 0;
 		return `Unknown message part type: ${JSON.stringify(type)}`;
 	}
+	if (!allowedTypes.has(part.type)) return `${location} does not allow "${part.type}" parts`;
+	const record = part;
+	switch (record.type) {
+		case "text": return requireString(record, "text", "text");
+		case "image": return requireMediaData(record, "image", "image");
+		case "file": return requireMediaData(record, "file", "data") ?? requireString(record, "file", "mediaType");
+		case "tool-call": return requireString(record, "tool-call", "toolCallId") ?? requireString(record, "tool-call", "toolName") ?? ("input" in record ? void 0 : "tool-call part requires an \"input\" value");
+		case "tool-result": return requireString(record, "tool-result", "toolCallId") ?? requireString(record, "tool-result", "toolName") ?? validateToolResultOutput(record.output);
+		default: return;
+	}
+}
+function validatePartsArray(content, allowedTypes, location) {
+	if (!Array.isArray(content)) return "Expected content to be a string or an array of parts";
+	for (const part of content) {
+		const error = validatePart(part, allowedTypes, location);
+		if (error) return error;
+	}
 }
 /**
 * A {@link StandardSchemaV1} validating an `AgentMessage[]` context field —
 * checks that every message has a known `role` (`system`/`user`/`assistant`/
 * `tool`) and that `content` is either a string (where the role allows it) or
-* an array of parts with a known `type`. Use it directly as a context
-* schema's `messages` field when authoring with `createAgentSchemas`.
+* an array of role-appropriate parts whose required fields and media payloads
+* have the right runtime types (extra fields are allowed). Use it directly as
+* a context schema's `messages` field when authoring with `createAgentSchemas`.
 */
 const messagesSchema = { "~standard": {
 	version: 1,
@@ -69,12 +135,12 @@ const messagesSchema = { "~standard": {
 				continue;
 			}
 			if (role === "tool") {
-				const error = validatePartsArray(content) ?? (content.some((part) => part.type !== "tool-result") ? "tool message content must contain only tool-result parts" : void 0);
+				const error = validatePartsArray(content, TOOL_PART_TYPES, "tool message content");
 				if (error) return { issues: [{ message: error }] };
 				continue;
 			}
 			if (typeof content === "string") continue;
-			const error = validatePartsArray(content);
+			const error = validatePartsArray(content, role === "user" ? USER_PART_TYPES : ASSISTANT_PART_TYPES, `${role} message content`);
 			if (error) return { issues: [{ message: error }] };
 		}
 		return { value };
@@ -374,13 +440,6 @@ function toEvents(history) {
 		return candidate && typeof candidate === "object" && "event" in candidate && candidate.event ? candidate.event : entry;
 	});
 }
-/**
-* Rewrites a journaled actor event's per-incarnation `sessionId` to the
-* current snapshot's child for the same stable `actorId`, so replayed
-* completions match freshly restored children.
-*
-* @internal
-*/
 function rebindActorSession(event, snapshot, sessions) {
 	const actorEvent = event;
 	if (typeof actorEvent.actorId !== "string" || typeof actorEvent.sessionId !== "string") return event;
@@ -926,7 +985,7 @@ function createRequestsFromWorkflowConfig(config, compileSchema) {
 		messages: resolver(request.messages),
 		tools: request.tools,
 		toolChoice: request.toolChoice,
-		reasoning: request.reasoning,
+		includeReasoning: request.includeReasoning,
 		temperature: resolver(request.temperature),
 		maxOutputTokens: resolver(request.maxOutputTokens),
 		topP: resolver(request.topP),
@@ -1616,12 +1675,6 @@ Object.defineProperty(exports, "messagesSchema", {
 		return messagesSchema;
 	}
 });
-Object.defineProperty(exports, "rebindActorSession", {
-	enumerable: true,
-	get: function() {
-		return rebindActorSession;
-	}
-});
 Object.defineProperty(exports, "replay", {
 	enumerable: true,
 	get: function() {

package/dist/{setup-agent-BOcSpsIq.mjs → setup-agent-nSFYrNTP.mjs}

@@ -1,5 +1,5 @@
 import { t as AgentError } from "./errors-CeSXQx0v.mjs";
-import { F as djb2Hex, M as machineStaticTransitionTargets, N as missingActor, T as agentExecutionOptions, U as resolveMachineVersion, d as USER_INPUT_ACTOR, g as executeAgentTextRequest, h as createTextLogic, j as machineIdlePredicates, k as getRegisteredAgentExecutionOptions, l as DECIDE_ACTOR, m as builtinTextActors, n as createDecideActor, o as getAcceptedEvents, q as validateSchemaSync, r as isDecisionLogic, w as userInputActor, y as isTextLogic } from "./decision-BfhSgCc6.mjs";
+import { D as userInputActor, F as machineStaticTransitionTargets, I as missingActor, K as resolveMachineVersion, M as getRegisteredAgentExecutionOptions, O as agentExecutionOptions, P as machineIdlePredicates, R as djb2Hex, S as isTextLogic, X as validateSchemaSync, _ as builtinTextActors, i as isDecisionLogic, m as USER_INPUT_ACTOR, n as createDecideActor, s as getAcceptedEvents, u as DECIDE_ACTOR, v as createTextLogic, y as executeAgentTextRequest } from "./decision-DxSTqzgZ.mjs";
 import { a as assertJsonSerializable, i as assertAgentLogEntry } from "./event-log-store-DmIDosD6.mjs";
 import { createMachineFromConfig, initialTransition, setup, transition } from "xstate";
 //#region src/messages.ts
@@ -36,22 +36,88 @@ const KNOWN_PART_TYPES = new Set([
 	"tool-call",
 	"tool-result"
 ]);
+const USER_PART_TYPES = new Set([
+	"text",
+	"image",
+	"file"
+]);
+const ASSISTANT_PART_TYPES = new Set([
+	"text",
+	"file",
+	"tool-call",
+	"tool-result"
+]);
+const TOOL_PART_TYPES = new Set(["tool-result"]);
+const TOOL_RESULT_CONTENT_PART_TYPES = new Set(["text", "image"]);
 function isKnownPart(part) {
-	return !!part && typeof part === "object" && KNOWN_PART_TYPES.has(part.type);
+	const type = part && typeof part === "object" ? part.type : void 0;
+	return typeof type === "string" && KNOWN_PART_TYPES.has(type);
 }
-function validatePartsArray(content) {
-	if (!Array.isArray(content)) return "Expected content to be a string or an array of parts";
-	for (const part of content) if (!isKnownPart(part)) {
+function requireString(part, type, field) {
+	return typeof part[field] === "string" ? void 0 : `${type} part requires a string "${field}"`;
+}
+function isMediaData(value) {
+	return typeof value === "string" || value instanceof Uint8Array || value instanceof ArrayBuffer || value instanceof URL;
+}
+function requireMediaData(part, type, field) {
+	return isMediaData(part[field]) ? void 0 : `${type} part requires "${field}" to be a string, Uint8Array, ArrayBuffer, or URL`;
+}
+const TOOL_RESULT_OUTPUT_TYPES = new Set([
+	"text",
+	"json",
+	"error-text",
+	"error-json",
+	"content"
+]);
+function validateToolResultOutput(output) {
+	if (!output || typeof output !== "object" || Array.isArray(output)) return "tool-result part requires an \"output\" object";
+	const record = output;
+	const outputType = record.type;
+	if (typeof outputType !== "string" || !TOOL_RESULT_OUTPUT_TYPES.has(outputType)) return `Unknown tool-result output type: ${JSON.stringify(outputType)}`;
+	if (outputType === "text" || outputType === "error-text") {
+		if (typeof record.value !== "string") return `tool-result output of type "${outputType}" requires a string "value"`;
+		return;
+	}
+	if (outputType === "content") {
+		if (!Array.isArray(record.value)) return "tool-result output of type \"content\" requires an array \"value\"";
+		for (const contentPart of record.value) {
+			const error = validatePart(contentPart, TOOL_RESULT_CONTENT_PART_TYPES, "tool-result output content");
+			if (error) return error;
+		}
+		return;
+	}
+	return record.value !== void 0 ? void 0 : `tool-result output of type "${outputType}" requires a "value"`;
+}
+function validatePart(part, allowedTypes, location) {
+	if (!isKnownPart(part)) {
 		const type = part && typeof part === "object" ? part.type : void 0;
 		return `Unknown message part type: ${JSON.stringify(type)}`;
 	}
+	if (!allowedTypes.has(part.type)) return `${location} does not allow "${part.type}" parts`;
+	const record = part;
+	switch (record.type) {
+		case "text": return requireString(record, "text", "text");
+		case "image": return requireMediaData(record, "image", "image");
+		case "file": return requireMediaData(record, "file", "data") ?? requireString(record, "file", "mediaType");
+		case "tool-call": return requireString(record, "tool-call", "toolCallId") ?? requireString(record, "tool-call", "toolName") ?? ("input" in record ? void 0 : "tool-call part requires an \"input\" value");
+		case "tool-result": return requireString(record, "tool-result", "toolCallId") ?? requireString(record, "tool-result", "toolName") ?? validateToolResultOutput(record.output);
+		default: return;
+	}
+}
+function validatePartsArray(content, allowedTypes, location) {
+	if (!Array.isArray(content)) return "Expected content to be a string or an array of parts";
+	for (const part of content) {
+		const error = validatePart(part, allowedTypes, location);
+		if (error) return error;
+	}
 }
 /**
 * A {@link StandardSchemaV1} validating an `AgentMessage[]` context field —
 * checks that every message has a known `role` (`system`/`user`/`assistant`/
 * `tool`) and that `content` is either a string (where the role allows it) or
-* an array of parts with a known `type`. Use it directly as a context
-* schema's `messages` field when authoring with `createAgentSchemas`.
+* an array of role-appropriate parts whose required fields and media payloads
+* have the right runtime types (extra fields are allowed). Use it directly as
+* a context schema's `messages` field when authoring with `createAgentSchemas`.
 */
 const messagesSchema = { "~standard": {
 	version: 1,
@@ -68,12 +134,12 @@ const messagesSchema = { "~standard": {
 				continue;
 			}
 			if (role === "tool") {
-				const error = validatePartsArray(content) ?? (content.some((part) => part.type !== "tool-result") ? "tool message content must contain only tool-result parts" : void 0);
+				const error = validatePartsArray(content, TOOL_PART_TYPES, "tool message content");
 				if (error) return { issues: [{ message: error }] };
 				continue;
 			}
 			if (typeof content === "string") continue;
-			const error = validatePartsArray(content);
+			const error = validatePartsArray(content, role === "user" ? USER_PART_TYPES : ASSISTANT_PART_TYPES, `${role} message content`);
 			if (error) return { issues: [{ message: error }] };
 		}
 		return { value };
@@ -373,13 +439,6 @@ function toEvents(history) {
 		return candidate && typeof candidate === "object" && "event" in candidate && candidate.event ? candidate.event : entry;
 	});
 }
-/**
-* Rewrites a journaled actor event's per-incarnation `sessionId` to the
-* current snapshot's child for the same stable `actorId`, so replayed
-* completions match freshly restored children.
-*
-* @internal
-*/
 function rebindActorSession(event, snapshot, sessions) {
 	const actorEvent = event;
 	if (typeof actorEvent.actorId !== "string" || typeof actorEvent.sessionId !== "string") return event;
@@ -925,7 +984,7 @@ function createRequestsFromWorkflowConfig(config, compileSchema) {
 		messages: resolver(request.messages),
 		tools: request.tools,
 		toolChoice: request.toolChoice,
-		reasoning: request.reasoning,
+		includeReasoning: request.includeReasoning,
 		temperature: resolver(request.temperature),
 		maxOutputTokens: resolver(request.maxOutputTokens),
 		topP: resolver(request.topP),
@@ -1525,4 +1584,4 @@ function createAgentActors(actors, requestActors) {
 	};
 }
 //#endregion
-export { initialAgentStep as _, AGENT_USAGE_EVENT_TYPE as a, appendMessages as b, createReplayEntry as c, initEntry as d, rebindActorSession as f, getInvokeEffectMetadata as g, executeAgentRequest as h, AGENT_INIT_EVENT_TYPE as i, diffEventLogs as l, validateReplayEntries as m, getAgentSchemas as n, AgentReplayDivergenceError as o, replay as p, setupAgent as r, AgentReplayMachineMismatchError as s, createAgentSchemas as t, getAgentEffects as u, resolveAgentStep as v, messagesSchema as x, transitionAgentStep as y };
+export { resolveAgentStep as _, AGENT_USAGE_EVENT_TYPE as a, messagesSchema as b, createReplayEntry as c, initEntry as d, replay as f, initialAgentStep as g, getInvokeEffectMetadata as h, AGENT_INIT_EVENT_TYPE as i, diffEventLogs as l, executeAgentRequest as m, getAgentSchemas as n, AgentReplayDivergenceError as o, validateReplayEntries as p, setupAgent as r, AgentReplayMachineMismatchError as s, createAgentSchemas as t, getAgentEffects as u, transitionAgentStep as v, appendMessages as y };

package/dist/sqlite.d.cts

@@ -1,4 +1,4 @@
-import { r as AgentSnapshotStore } from "./types-pJ5Hn8fv.cjs";
+import { r as AgentSnapshotStore } from "./types-DSdj2tGs.cjs";
 import { r as AgentEventLogStore } from "./event-log-store-Bz7HDBkE.cjs";
 
 //#region src/sqlite/index.d.ts

package/dist/sqlite.d.mts

@@ -1,4 +1,4 @@
-import { r as AgentSnapshotStore } from "./types-DYpK3QF4.mjs";
+import { r as AgentSnapshotStore } from "./types-CvWRGFxP.mjs";
 import { r as AgentEventLogStore } from "./event-log-store-hrA1vqtN.mjs";
 
 //#region src/sqlite/index.d.ts

package/dist/{text-logic-Cavva1W6.d.cts → text-logic-BaxPrcLk.d.cts}

@@ -1,4 +1,4 @@
-import { a as AgentToolChoice, c as AgentTools, d as ChosenEvent, g as InferOutput, l as AllowedEvents, n as AgentMessage, v as StandardSchemaV1 } from "./types-pJ5Hn8fv.cjs";
+import { a as AgentToolChoice, c as AgentTools, d as ChosenEvent, g as InferOutput, l as AllowedEvents, n as AgentMessage, v as StandardSchemaV1 } from "./types-DSdj2tGs.cjs";
 import { t as AgentError } from "./errors-BQRk9eiZ.cjs";
 import { AnyMachineSnapshot, AsyncActorLogic, EventObject, MachineSnapshot } from "xstate";
 
@@ -124,6 +124,49 @@ interface DecisionLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSc
   stopSequences?: ResolveTextLogicValue<string[] | undefined, InferOutput<TInputSchema>>;
   metadata?: ResolveTextLogicValue<TMetadata | undefined, InferOutput<TInputSchema>>;
 }
+/**
+ * Actor logic for a decision: an async effect that resolves to exactly one
+ * currently-legal {@link ChosenEvent} (never a plain value). Under `runAgent`
+ * the chosen event is delivered to the invoking actor automatically — the
+ * transition it triggers usually exits the invoking state and ends the invoke.
+ * Built by {@link createDecisionLogic}. Register it under `actors:` to reuse/export/
+ * test it standalone; for a state-local, zero-config decision, use the
+ * `agent.decide` builtin invoke instead.
+ */
+interface DecisionLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TMetadata extends Record<string, unknown> = Record<string, unknown>> extends AsyncActorLogic<ChosenEvent, InferOutput<TInputSchema>> {
+  readonly kind: "statelyai.decisionLogic";
+  readonly maxRetries: number;
+  request(input: InferOutput<TInputSchema>): AgentDecisionRequest;
+  withExecutor(execute: AgentDecisionExecutor): DecisionLogic<TInputSchema, TMetadata>;
+}
+/**
+ * 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'],
+ * });
+ * ```
+ */
+declare function createDecisionLogic<TInputSchema extends StandardSchemaV1, TEvent extends string = string, TMetadata extends Record<string, unknown> = Record<string, unknown>, TModel extends string = string>(config: DecisionLogicConfig<TInputSchema, TEvent, TMetadata, TModel>, execute?: AgentDecisionExecutor): DecisionLogic<TInputSchema, TMetadata>;
 /**
  * A decision request: resolves to exactly one currently-legal event. See
  * `resolveDecision`.
@@ -342,8 +385,11 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>> {
    * structured-output envelope schema, nudging the model to reason before
    * committing to the result. The reasoning is surfaced on the executor's raw
    * result (never in machine context/output). Ignored for text-mode requests.
+   *
+   * Not a provider setting: reasoning EFFORT belongs to the host, which owns
+   * how hard a model thinks. See `createAiSdkExecutors({ settings })`.
    */
-  reasoning?: boolean;
+  includeReasoning?: boolean;
   temperature?: number;
   /**
    * Maximum number of output tokens to generate. Named `maxOutputTokens` (not
@@ -479,8 +525,8 @@ interface TextLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSchema
   messages?: ResolveTextLogicValue<AgentMessage[] | undefined, InferOutput<TInputSchema>>;
   tools?: ResolveTextLogicValue<AgentTools | undefined, InferOutput<TInputSchema>>;
   toolChoice?: ResolveTextLogicValue<AgentToolChoice | undefined, InferOutput<TInputSchema>>;
-  /** Opt into the structured-output envelope's `reasoning` field (see {@link AgentTextRequest.reasoning}). */
-  reasoning?: ResolveTextLogicValue<boolean | undefined, InferOutput<TInputSchema>>;
+  /** Opt into the structured-output envelope's `reasoning` field (see {@link AgentTextRequest.includeReasoning}). */
+  includeReasoning?: ResolveTextLogicValue<boolean | undefined, InferOutput<TInputSchema>>;
   temperature?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
   maxOutputTokens?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
   topP?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
@@ -739,6 +785,6 @@ declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
  * 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;
+declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "includeReasoning">, value: unknown): StructuredOutputEnvelope;
 //#endregion
-export { AgentDecisionExecutor as A, AgentEventToolNameResolver as B, buildEnvelopeSchema as C, parseModelRef as D, getCallUsage as E, DecisionLogicConfig as F, parseAgentEvent as G, AgentRequestSource as H, ResolveDecisionOptions as I, renderDecisionAttempts as L, AgentDecisionInput as M, AgentDecisionRequest as N, parseOutput as O, DecisionAttempt as P, resolveDecision as R, bindRequestExecutor as S, getAgentOutputMode as T, AgentSchemas as U, AgentRequestOptions as V, getAcceptedEvents as W, StructuredOutputEnvelope as _, AgentOutputMode as a, TextLogicExecuteArgs as b, AgentRequestExecutorResult as c, AgentTextRequest as d, AgentUsage as f, BuiltinAgentActors as g, AiSdkShapedTextResult as h, AgentModelRef as i, AgentDecisionExhaustedError as j, parseStructuredEnvelope as k, AgentRequestExecutors as l, AiSdkShapedStreamResult as m, AgentExecutorTextRequest as n, AgentRequestExecutor as o, AgentUserInput as p, AgentModelMap as r, AgentRequestExecutorInfo as s, AgentCallUsage as t, AgentRequestMode as u, TextLogic as v, createTextLogic as w, TextLogicExecutor as x, TextLogicConfig as y, AgentEventDescriptor as z };
+export { AgentDecisionExecutor as A, resolveDecision as B, buildEnvelopeSchema as C, parseModelRef as D, getCallUsage as E, DecisionLogic as F, AgentSchemas as G, AgentEventToolNameResolver as H, DecisionLogicConfig as I, getAcceptedEvents as K, ResolveDecisionOptions as L, AgentDecisionInput as M, AgentDecisionRequest as N, parseOutput as O, DecisionAttempt as P, createDecisionLogic as R, bindRequestExecutor as S, getAgentOutputMode as T, AgentRequestOptions as U, AgentEventDescriptor as V, AgentRequestSource as W, StructuredOutputEnvelope as _, AgentOutputMode as a, TextLogicExecuteArgs as b, AgentRequestExecutorResult as c, AgentTextRequest as d, AgentUsage as f, BuiltinAgentActors as g, AiSdkShapedTextResult as h, AgentModelRef as i, AgentDecisionExhaustedError as j, parseStructuredEnvelope as k, AgentRequestExecutors as l, AiSdkShapedStreamResult as m, AgentExecutorTextRequest as n, AgentRequestExecutor as o, AgentUserInput as p, parseAgentEvent as q, AgentModelMap as r, AgentRequestExecutorInfo as s, AgentCallUsage as t, AgentRequestMode as u, TextLogic as v, createTextLogic as w, TextLogicExecutor as x, TextLogicConfig as y, renderDecisionAttempts as z };

package/dist/{text-logic-Er5KkTX6.d.mts → text-logic-DhfFWzu9.d.mts}

@@ -1,4 +1,4 @@
-import { a as AgentToolChoice, c as AgentTools, d as ChosenEvent, g as InferOutput, l as AllowedEvents, n as AgentMessage, v as StandardSchemaV1 } from "./types-DYpK3QF4.mjs";
+import { a as AgentToolChoice, c as AgentTools, d as ChosenEvent, g as InferOutput, l as AllowedEvents, n as AgentMessage, v as StandardSchemaV1 } from "./types-CvWRGFxP.mjs";
 import { t as AgentError } from "./errors-C9rxnWbX.mjs";
 import { AnyMachineSnapshot, AsyncActorLogic, EventObject, MachineSnapshot } from "xstate";
 
@@ -124,6 +124,49 @@ interface DecisionLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSc
   stopSequences?: ResolveTextLogicValue<string[] | undefined, InferOutput<TInputSchema>>;
   metadata?: ResolveTextLogicValue<TMetadata | undefined, InferOutput<TInputSchema>>;
 }
+/**
+ * Actor logic for a decision: an async effect that resolves to exactly one
+ * currently-legal {@link ChosenEvent} (never a plain value). Under `runAgent`
+ * the chosen event is delivered to the invoking actor automatically — the
+ * transition it triggers usually exits the invoking state and ends the invoke.
+ * Built by {@link createDecisionLogic}. Register it under `actors:` to reuse/export/
+ * test it standalone; for a state-local, zero-config decision, use the
+ * `agent.decide` builtin invoke instead.
+ */
+interface DecisionLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TMetadata extends Record<string, unknown> = Record<string, unknown>> extends AsyncActorLogic<ChosenEvent, InferOutput<TInputSchema>> {
+  readonly kind: "statelyai.decisionLogic";
+  readonly maxRetries: number;
+  request(input: InferOutput<TInputSchema>): AgentDecisionRequest;
+  withExecutor(execute: AgentDecisionExecutor): DecisionLogic<TInputSchema, TMetadata>;
+}
+/**
+ * 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'],
+ * });
+ * ```
+ */
+declare function createDecisionLogic<TInputSchema extends StandardSchemaV1, TEvent extends string = string, TMetadata extends Record<string, unknown> = Record<string, unknown>, TModel extends string = string>(config: DecisionLogicConfig<TInputSchema, TEvent, TMetadata, TModel>, execute?: AgentDecisionExecutor): DecisionLogic<TInputSchema, TMetadata>;
 /**
  * A decision request: resolves to exactly one currently-legal event. See
  * `resolveDecision`.
@@ -342,8 +385,11 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>> {
    * structured-output envelope schema, nudging the model to reason before
    * committing to the result. The reasoning is surfaced on the executor's raw
    * result (never in machine context/output). Ignored for text-mode requests.
+   *
+   * Not a provider setting: reasoning EFFORT belongs to the host, which owns
+   * how hard a model thinks. See `createAiSdkExecutors({ settings })`.
    */
-  reasoning?: boolean;
+  includeReasoning?: boolean;
   temperature?: number;
   /**
    * Maximum number of output tokens to generate. Named `maxOutputTokens` (not
@@ -479,8 +525,8 @@ interface TextLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSchema
   messages?: ResolveTextLogicValue<AgentMessage[] | undefined, InferOutput<TInputSchema>>;
   tools?: ResolveTextLogicValue<AgentTools | undefined, InferOutput<TInputSchema>>;
   toolChoice?: ResolveTextLogicValue<AgentToolChoice | undefined, InferOutput<TInputSchema>>;
-  /** Opt into the structured-output envelope's `reasoning` field (see {@link AgentTextRequest.reasoning}). */
-  reasoning?: ResolveTextLogicValue<boolean | undefined, InferOutput<TInputSchema>>;
+  /** Opt into the structured-output envelope's `reasoning` field (see {@link AgentTextRequest.includeReasoning}). */
+  includeReasoning?: ResolveTextLogicValue<boolean | undefined, InferOutput<TInputSchema>>;
   temperature?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
   maxOutputTokens?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
   topP?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
@@ -739,6 +785,6 @@ declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
  * 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;
+declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "includeReasoning">, value: unknown): StructuredOutputEnvelope;
 //#endregion
-export { AgentDecisionExecutor as A, AgentEventToolNameResolver as B, buildEnvelopeSchema as C, parseModelRef as D, getCallUsage as E, DecisionLogicConfig as F, parseAgentEvent as G, AgentRequestSource as H, ResolveDecisionOptions as I, renderDecisionAttempts as L, AgentDecisionInput as M, AgentDecisionRequest as N, parseOutput as O, DecisionAttempt as P, resolveDecision as R, bindRequestExecutor as S, getAgentOutputMode as T, AgentSchemas as U, AgentRequestOptions as V, getAcceptedEvents as W, StructuredOutputEnvelope as _, AgentOutputMode as a, TextLogicExecuteArgs as b, AgentRequestExecutorResult as c, AgentTextRequest as d, AgentUsage as f, BuiltinAgentActors as g, AiSdkShapedTextResult as h, AgentModelRef as i, AgentDecisionExhaustedError as j, parseStructuredEnvelope as k, AgentRequestExecutors as l, AiSdkShapedStreamResult as m, AgentExecutorTextRequest as n, AgentRequestExecutor as o, AgentUserInput as p, AgentModelMap as r, AgentRequestExecutorInfo as s, AgentCallUsage as t, AgentRequestMode as u, TextLogic as v, createTextLogic as w, TextLogicExecutor as x, TextLogicConfig as y, AgentEventDescriptor as z };
+export { AgentDecisionExecutor as A, resolveDecision as B, buildEnvelopeSchema as C, parseModelRef as D, getCallUsage as E, DecisionLogic as F, AgentSchemas as G, AgentEventToolNameResolver as H, DecisionLogicConfig as I, getAcceptedEvents as K, ResolveDecisionOptions as L, AgentDecisionInput as M, AgentDecisionRequest as N, parseOutput as O, DecisionAttempt as P, createDecisionLogic as R, bindRequestExecutor as S, getAgentOutputMode as T, AgentRequestOptions as U, AgentEventDescriptor as V, AgentRequestSource as W, StructuredOutputEnvelope as _, AgentOutputMode as a, TextLogicExecuteArgs as b, AgentRequestExecutorResult as c, AgentTextRequest as d, AgentUsage as f, BuiltinAgentActors as g, AiSdkShapedTextResult as h, AgentModelRef as i, AgentDecisionExhaustedError as j, parseStructuredEnvelope as k, AgentRequestExecutors as l, AiSdkShapedStreamResult as m, AgentExecutorTextRequest as n, AgentRequestExecutor as o, AgentUserInput as p, parseAgentEvent as q, AgentModelMap as r, AgentRequestExecutorInfo as s, AgentCallUsage as t, AgentRequestMode as u, TextLogic as v, createTextLogic as w, TextLogicExecutor as x, TextLogicConfig as y, renderDecisionAttempts as z };

package/dist/{types-DYpK3QF4.d.mts → types-CvWRGFxP.d.mts}

@@ -203,7 +203,12 @@ type AgentToolSchema = object;
  * SDK you built the tool with owns its precise input typing.
  */
 interface AgentToolDescriptor {
-  description?: string;
+  /**
+   * Text shown to the model. Typed loosely enough to accept an SDK tool whose
+   * description is computed per call (the AI SDK v7 `tool({ description })`
+   * accepts a function of the call's context); core never reads it.
+   */
+  description?: string | ((...args: any[]) => string);
   inputSchema?: AgentToolSchema;
   outputSchema?: AgentToolSchema;
   execute?: (...args: any[]) => unknown;

package/dist/{types-pJ5Hn8fv.d.cts → types-DSdj2tGs.d.cts}

@@ -203,7 +203,12 @@ type AgentToolSchema = object;
  * SDK you built the tool with owns its precise input typing.
  */
 interface AgentToolDescriptor {
-  description?: string;
+  /**
+   * Text shown to the model. Typed loosely enough to accept an SDK tool whose
+   * description is computed per call (the AI SDK v7 `tool({ description })`
+   * accepts a function of the call's context); core never reads it.
+   */
+  description?: string | ((...args: any[]) => string);
   inputSchema?: AgentToolSchema;
   outputSchema?: AgentToolSchema;
   execute?: (...args: any[]) => unknown;

package/dist/validate.cjs

@@ -22,7 +22,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 //#endregion
 let ajv_dist_2020_js = require("ajv/dist/2020.js");
-ajv_dist_2020_js = __toESM(ajv_dist_2020_js);
+ajv_dist_2020_js = __toESM(ajv_dist_2020_js, 1);
 //#region schemas/agent-workflow.json
 var agent_workflow_default = {
 	$schema: "https://json-schema.org/draft/2020-12/schema",
@@ -221,7 +221,7 @@ var agent_workflow_default = {
 						"additionalProperties": false
 					}]
 				},
-				"reasoning": {
+				"includeReasoning": {
 					"description": "Opt into the structured-output envelope's `reasoning` field.",
 					"type": "boolean"
 				},

package/dist/validate.mjs

@@ -197,7 +197,7 @@ var agent_workflow_default = {
 						"additionalProperties": false
 					}]
 				},
-				"reasoning": {
+				"includeReasoning": {
 					"description": "Opt into the structured-output envelope's `reasoning` field.",
 					"type": "boolean"
 				},