@statelyai/agent 2.0.0-alpha.23 → 2.0.0-alpha.25

package/dist/text-logic-Bl_ZRxDi.mjs

@@ -0,0 +1,833 @@
+import { createAsyncLogic } from "xstate";
+//#region src/errors.ts
+/**
+* Base class for every error this package throws. Carries a stable, kebab-case
+* `code` so hosts can branch on the failure without `instanceof` (useful across
+* bundle/realm boundaries and after serialization).
+*
+* @example
+* ```ts
+* catch (error) {
+*   if (error instanceof AgentError && error.code === 'agent-idle') { ... }
+* }
+* ```
+*/
+var AgentError = class extends Error {
+	code;
+	constructor(code, message, options) {
+		super(message, options);
+		this.name = "AgentError";
+		this.code = code;
+	}
+};
+/**
+* A model call ran out of output tokens before it produced anything usable.
+* Core never throws this: it is the adapter's signal that a `'length'` finish
+* reason left nothing to return — a structured request whose JSON never
+* closed, say. A text request that WAS cut off still returns its text, with
+* `finishReason: 'length'`.
+*
+* The code is `'truncated'`, so an invoke's `onError` can branch on it without
+* `instanceof`:
+*
+* @example
+* ```ts
+* onError: [
+*   { guard: ({ event }) => event.error.code === 'truncated', target: 'retryShorter' },
+*   { target: 'failed' },
+* ]
+* ```
+*/
+var AgentTruncatedError = class extends AgentError {
+	/** The request that was cut off — `AgentTextRequest.name`. */
+	requestName;
+	/** The durable invoke id of the request, when the host knows it. */
+	requestId;
+	/** Whatever the model did produce before it hit the limit, if anything. */
+	partialOutput;
+	constructor(message, options) {
+		super("truncated", message, { cause: options.cause });
+		this.name = "AgentTruncatedError";
+		this.requestName = options.requestName;
+		if (options.requestId !== void 0) this.requestId = options.requestId;
+		if (options.partialOutput !== void 0) this.partialOutput = options.partialOutput;
+	}
+};
+//#endregion
+//#region src/utils.ts
+/** Returns the human-readable text carried by a message, ignoring non-text parts. */
+function getMessageText(message) {
+	if (typeof message.content === "string") return message.content;
+	const text = [];
+	for (const part of message.content) {
+		if (part.type === "text") {
+			text.push(part.text);
+			continue;
+		}
+		if (part.type !== "tool-result") continue;
+		if (part.output.type === "text" || part.output.type === "error-text") text.push(part.output.value);
+		else if (part.output.type === "content") text.push(...part.output.value.flatMap((item) => item.type === "text" ? [item.text] : []));
+	}
+	return text.join("\n");
+}
+/**
+* Walks a context value and returns the dot-paths of the first few values that
+* would NOT survive a JSON persist/resume round-trip (persist with XState's
+* `actor.getPersistedSnapshot()`, resume with `createActor(machine, { snapshot })`):
+* `Date`, `Map`, `Set`, `RegExp`, functions, `undefined`, `bigint`, class
+* instances (non-plain objects), and circular references. Plain objects,
+* arrays, and JSON primitives are walked/allowed. Returns `[]` for a
+* fully-JSON-safe value. Cheap and bounded (stops after `limit` findings) —
+* intended for a dev-only warning at the moment persistence matters.
+*/
+function findNonSerializableContextPaths(context, limit = 5) {
+	const paths = [];
+	const seen = /* @__PURE__ */ new WeakSet();
+	const walk = (value, path) => {
+		if (paths.length >= limit) return;
+		if (value === null) return;
+		const type = typeof value;
+		if (type === "string" || type === "number" || type === "boolean") return;
+		if (type === "undefined" || type === "bigint" || type === "function" || type === "symbol") {
+			paths.push(`${path} (${type})`);
+			return;
+		}
+		const obj = value;
+		if (seen.has(obj)) {
+			paths.push(`${path} (circular)`);
+			return;
+		}
+		if (Array.isArray(value)) {
+			seen.add(obj);
+			value.forEach((item, index) => walk(item, `${path}[${index}]`));
+			seen.delete(obj);
+			return;
+		}
+		const proto = Object.getPrototypeOf(value);
+		if (proto === Object.prototype || proto === null) {
+			seen.add(obj);
+			for (const [key, item] of Object.entries(value)) walk(item, `${path}.${key}`);
+			seen.delete(obj);
+			return;
+		}
+		const ctorName = value.constructor?.name ?? "object";
+		paths.push(`${path} (${ctorName})`);
+	};
+	walk(context, "context");
+	return paths;
+}
+/**
+* A stable, dependency-free structural fingerprint of a machine — a short hex
+* `djb2` hash over its **structural** config only: state ids/nesting, transition
+* event types and targets, invoke `src`s, `initial`, and any other serializable
+* config fields. Function values (context/output builders, prompts, inline
+* guards/actions) are excluded entirely, so two machines that differ only in
+* their prompts or executors hash identically; adding/removing/retargeting a
+* state or transition changes the hash.
+*
+* Used by {@link runAgent} to stamp settled snapshots with a `version` and to
+* detect a structurally-edited machine on resume. It is a change detector, not
+* a cryptographic digest — collisions are possible but unlikely for real
+* configs. Declare `createMachine({ version })` to pin an explicit version instead.
+*/
+function getMachineStructuralHash(machine) {
+	return djb2Hex(stableStructuralString(machine.config));
+}
+/**
+* The version a machine is stamped with everywhere: an explicitly declared
+* `createMachine({ version })` when present, else its
+* {@link getMachineStructuralHash}. Single source of truth so `runAgent`,
+* `provideExecutors`/`traceTransitions` trace envelopes agree.
+* @internal
+*/
+function resolveMachineVersion(machine) {
+	return machine.version ?? getMachineStructuralHash(machine);
+}
+function stableStructuralString(value, seen = /* @__PURE__ */ new WeakSet()) {
+	if (value === null) return "null";
+	const type = typeof value;
+	if (type === "function" || type === "undefined" || type === "symbol") return "";
+	if (type === "string") return JSON.stringify(value);
+	if (type === "number" || type === "boolean") return String(value);
+	if (type === "bigint") return `${value}n`;
+	const obj = value;
+	if (seen.has(obj)) return "\"[circular]\"";
+	seen.add(obj);
+	let out;
+	if (Array.isArray(value)) out = `[${value.map((item) => stableStructuralString(item, seen)).join(",")}]`;
+	else {
+		const parts = [];
+		for (const key of Object.keys(obj).sort()) {
+			const child = obj[key];
+			const childType = typeof child;
+			if (childType === "function" || childType === "undefined" || childType === "symbol") continue;
+			parts.push(`${JSON.stringify(key)}:${stableStructuralString(child, seen)}`);
+		}
+		out = `{${parts.join(",")}}`;
+	}
+	seen.delete(obj);
+	return out;
+}
+/**
+* djb2 → unsigned 32-bit → 8-char hex. No dependencies. A change detector, not
+* a cryptographic digest.
+*
+* @internal
+*/
+function djb2Hex(input) {
+	let hash = 5381;
+	for (let i = 0; i < input.length; i++) hash = (hash << 5) + hash + input.charCodeAt(i) | 0;
+	return (hash >>> 0).toString(16).padStart(8, "0");
+}
+/** Builds a {@link UserMessage} from a string or multimodal content parts. */
+function userMessage(content) {
+	return {
+		role: "user",
+		content
+	};
+}
+/** Builds an {@link AssistantMessage} from a string or content parts (text, files, tool calls/results). */
+function assistantMessage(content) {
+	return {
+		role: "assistant",
+		content
+	};
+}
+/** Builds a {@link SystemMessage}. */
+function systemMessage(content) {
+	return {
+		role: "system",
+		content
+	};
+}
+/** Builds a {@link ToolMessage} from one or more tool-result parts. */
+function toolMessage(content) {
+	return {
+		role: "tool",
+		content
+	};
+}
+/**
+* Returns the merged `meta` of a snapshot's active state(s) — the typed
+* replacement for the `Object.values(snapshot.getMeta())[0]` dance.
+*
+* `snapshot.getMeta()` is keyed by state id; a leaf machine has one active
+* state, but parallel/nested machines can have several. This shallow-merges
+* every active state's meta into one object and returns `{}` when no active
+* state declares meta.
+*
+* Merge order is fixed and does not depend on XState's internal node order:
+* entries are sorted by structural depth (the state node's distance from the
+* root, regardless of custom `id` strings), then by state id lexicographically,
+* and merged in that order. So a deeper state's key wins over an ancestor's,
+* and between equal-depth parallel siblings the later state id alphabetically
+* wins.
+*
+* The return type is recovered from the snapshot's own `getMeta()` type, so a
+* schema-typed machine (`setupAgent({ meta })`) yields the meta schema's
+* output type. Pass an explicit `TMeta` to override when the snapshot is
+* untyped (e.g. `AnyMachineSnapshot`).
+*
+* @example HITL: read the current state's interaction protocol off an idle
+* snapshot to render for a human.
+* ```ts
+* const { interaction } = getStateMeta(result.snapshot);
+* ```
+*/
+function getStateMeta(snapshot) {
+	const nodes = snapshot.nodes;
+	const depthById = new Map(nodes?.map((node) => [node.id, node.path.length]));
+	const depth = (id) => depthById.get(id) ?? id.split(".").length;
+	const entries = Object.entries(snapshot.getMeta()).filter((entry) => entry[1] != null).sort(([a], [b]) => depth(a) - depth(b) || (a < b ? -1 : a > b ? 1 : 0));
+	return Object.assign({}, ...entries.map(([, meta]) => meta));
+}
+/**
+* Renders a snapshot's state value as one deterministic string, so a log line,
+* a progress field, or a test assertion reads the same on every run.
+*
+* - An atomic state is its own name: `'writing'`.
+* - A nested state joins with dots: `{ review: { editing: 'draft' } }` →
+*   `'review.editing.draft'`.
+* - A parallel state brackets its regions, sorted by region name, so key order
+*   never leaks into the string: `{ p: { left: 'x', right: { a: 'b' } } }` →
+*   `'p:{left.x,right.a.b}'`.
+*
+* Prefer this over `String(snapshot.value)`, which renders every non-atomic
+* value as `[object Object]`.
+*
+* @example
+* ```ts
+* onTransition: (snapshot) => console.log(getStatePath(snapshot));
+* ```
+*/
+function getStatePath(snapshot) {
+	return serializeStateValue(typeof snapshot === "object" && snapshot !== null && "value" in snapshot && ("status" in snapshot || typeof snapshot.matches === "function") ? snapshot.value : snapshot);
+}
+function serializeStateValue(value) {
+	if (typeof value === "string") return value;
+	const entries = Object.entries(value).map(([key, child]) => {
+		const rendered = serializeStateValue(child);
+		if (!rendered) return [key, key];
+		return [key, `${key}${rendered.startsWith("{") ? ":" : "."}${rendered}`];
+	}).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+	if (entries.length === 0) return "";
+	if (entries.length === 1) return entries[0][1];
+	return `{${entries.map(([, rendered]) => rendered).join(",")}}`;
+}
+/**
+* Structural guard for a {@link StandardSchemaV1}: `true` when `value` carries
+* the `~standard` marker. Used to tell an already-schema'd tool `inputSchema`
+* (a Zod/Valibot/… schema) apart from an SDK-specific schema wrapper that core
+* can't read directly — see the `ai-sdk` tool pass-through.
+*/
+function isStandardSchema(value) {
+	return typeof value === "object" && value !== null && "~standard" in value;
+}
+/**
+* Pulls the JSON Schema off a {@link StandardSchemaV1} via its optional
+* `~standard.jsonSchema.input()` extension (implemented by e.g. Zod v4's
+* `z.toJSONSchema`), awaiting it when the producer is async. Returns
+* `undefined` when the schema doesn't expose the extension. Use this to build
+* a provider request's `response_format`/tool `parameters` from a schema.
+*/
+async function getJsonSchema(schema) {
+	const jsonSchemaFn = schema?.["~standard"].jsonSchema?.input;
+	if (!jsonSchemaFn) return;
+	const result = jsonSchemaFn();
+	return result instanceof Promise ? await result : result;
+}
+/**
+* Synchronous variant of {@link getJsonSchema}, for call sites that can't
+* await (building tool/event descriptors inline). An async JSON Schema
+* producer is treated as absent (returns `undefined`) — in practice Zod's
+* `z.toJSONSchema` resolves synchronously.
+*/
+function getJsonSchemaSync(schema) {
+	const jsonSchemaFn = schema?.["~standard"].jsonSchema?.input;
+	if (!jsonSchemaFn) return;
+	const result = jsonSchemaFn();
+	return result instanceof Promise ? void 0 : result;
+}
+/**
+* Validates `value` against a {@link StandardSchemaV1}, synchronously.
+* Throws if the schema's `validate` returns a `Promise` (async validation is
+* not supported anywhere in this library) or if validation reports issues —
+* in which case the thrown `Error.message` joins every issue message with
+* `', '`.
+*/
+function validateSchemaSync(schema, value) {
+	const result = schema["~standard"].validate(value);
+	if (result instanceof Promise) throw new Error("Async schema validation is not supported.");
+	if (result.issues) throw new Error(result.issues.map((issue) => issue.message).join(", "));
+	return result.value;
+}
+//#endregion
+//#region src/internal/registry.ts
+/**
+* Registered execution options, keyed on BOTH the machine object and its root
+* `config` object. `config` is shared by reference across `machine.provide(...)`
+* (unlike the machine itself), so the `config` key is what lets a machine
+* rebound by `runAgent` — or by any host `.provide(...)` — still resolve the
+* schemas/actors `setupAgent` registered. Always write through
+* {@link setAgentExecutionOptions} and read through
+* {@link getAgentExecutionOptions}.
+*/
+const agentExecutionOptions = /* @__PURE__ */ new WeakMap();
+/** The root `config` object a machine shares with every `.provide(...)` of itself. */
+function machineConfigKey(machine) {
+	const config = machine?.config;
+	return config && typeof config === "object" ? config : void 0;
+}
+/** Registers `options` for `machine` and for every `.provide(...)` of it. */
+function setAgentExecutionOptions(machine, options) {
+	if (!machine || typeof machine !== "object") return;
+	agentExecutionOptions.set(machine, options);
+	const config = machineConfigKey(machine);
+	if (config) agentExecutionOptions.set(config, options);
+}
+/**
+* Reads the options registered for `machine`, falling back to the root `config`
+* key so a `.provide(...)`-rebound machine (e.g. the one behind a `runAgent`
+* result snapshot) resolves the same pack.
+*/
+function getAgentExecutionOptions(machine) {
+	if (!machine || typeof machine !== "object") return void 0;
+	const direct = agentExecutionOptions.get(machine);
+	if (direct) return direct;
+	const config = machineConfigKey(machine);
+	return config ? agentExecutionOptions.get(config) : void 0;
+}
+/**
+* Machine-carried wait-state predicates, keyed on the machine's root `config`
+* object. `config` is shared by reference across `machine.provide(...)` (unlike
+* the machine object itself), so a predicate registered here travels with the
+* machine through `.provide` — which is why it is keyed on `config`, not the
+* machine. Set by `setupAgent({ isIdle })` in `createMachine` and by
+* `setupAgent.fromConfig` (its `isIdle` option or the config's
+* `idleTags`), read by `runAgent` before its structural default.
+*/
+const machineIdlePredicates = /* @__PURE__ */ new WeakMap();
+/** Reads the {@link machineIdlePredicates} predicate carried by `machine` (via its root `config`), if any. */
+function getMachineIdlePredicate(machine) {
+	const config = machine.config;
+	return config ? machineIdlePredicates.get(config) : void 0;
+}
+const unboundPlaceholderLogics = /* @__PURE__ */ new WeakSet();
+/** Text/decision logics created WITH their own executor (withExecutor or the
+* factory's second arg) — these are runnable as-is, so runAgent's bind check
+* must not reject them as direct-object invoke srcs. */
+const executorBoundLogics = /* @__PURE__ */ new WeakSet();
+function missingActor(src) {
+	const logic = createAsyncLogic({ run: async () => {
+		throw new Error(`'${src}' has no host execution. Provide an implementation with machine.provide({ actors: { '${src}': ... } }).`);
+	} });
+	unboundPlaceholderLogics.add(logic);
+	return logic;
+}
+function isUnboundPlaceholder(logic) {
+	return !!logic && typeof logic === "object" && unboundPlaceholderLogics.has(logic);
+}
+function getRegisteredAgentExecutionOptions(machine, options) {
+	return {
+		...getAgentExecutionOptions(machine),
+		...options
+	};
+}
+//#endregion
+//#region src/text-logic.ts
+const GENERATE_TEXT_ACTOR = "agent.generateText";
+const STREAM_TEXT_ACTOR = "agent.streamText";
+const DECIDE_ACTOR = "agent.decide";
+const AGENT_FINISH_REASONS = new Set([
+	"stop",
+	"length",
+	"tool-calls",
+	"content-filter",
+	"other"
+]);
+/**
+* Reads a settled call's {@link AgentFinishReason} off a RAW executor result's
+* `finishReason` field — the finish-reason sibling of {@link getCallUsage},
+* applied by `runAgent` before it puts the reason on the `request.end` trace.
+* A provider's `'error'` normalizes to `'other'`; anything else the union does
+* not name (an un-normalized provider string, a missing field) returns
+* `undefined`.
+*/
+function getCallFinishReason(raw) {
+	const value = raw?.finishReason;
+	if (typeof value !== "string") return;
+	if (value === "error") return "other";
+	return AGENT_FINISH_REASONS.has(value) ? value : void 0;
+}
+/** The token fields {@link AgentUsage} aggregates. @internal */
+const AGENT_USAGE_TOKEN_FIELDS = [
+	"inputTokens",
+	"outputTokens",
+	"totalTokens",
+	"reasoningTokens",
+	"cachedInputTokens"
+];
+/**
+* Reads a settled call's per-call {@link AgentCallUsage} off a RAW executor
+* result's `usage` field, keeping only finite numbers — the same normalization
+* `runAgent` applies before it delivers `'@agent.usage'`. Returns `undefined`
+* when the result reports no usage at all. Works for our `{ result, usage }`
+* shape, for a raw Vercel AI SDK result (its `LanguageModelUsage` carries
+* the same flat field names), and for any custom executor that follows the
+* shape.
+*
+* The seam for the step-loop path, where the host holds the raw result itself:
+*
+* ```ts
+* const { result, messages } = await executeAgentRequest(effect, executors);
+* const usage = getCallUsage(raw);
+* if (usage) append({ type: AGENT_USAGE_EVENT_TYPE, usage }); // journal + transition, like any event
+* append(effect.toDoneEvent(output));
+* ```
+*
+* See "Token usage on this path" in docs/steps.md for the full loop.
+*/
+function getCallUsage(raw) {
+	const usage = raw?.usage;
+	if (!usage || typeof usage !== "object") return;
+	let out;
+	for (const field of AGENT_USAGE_TOKEN_FIELDS) {
+		const value = usage[field];
+		if (typeof value === "number" && Number.isFinite(value)) (out ??= {})[field] = value;
+	}
+	return out;
+}
+/**
+* The response messages off an executor result, or none. Fields
+* holding `undefined` are dropped on the way in: SDK message objects often
+* carry optional slots as explicit `undefined` (the AI SDK's
+* `providerOptions`, for one), and the messages now travel inside the
+* invoke's done event, which the event log requires to be strict JSON.
+* @internal
+*/
+function responseMessagesOf(raw) {
+	const messages = raw?.messages;
+	return Array.isArray(messages) ? dropUndefined(messages) : [];
+}
+function dropUndefined(value) {
+	if (Array.isArray(value)) return value.map(dropUndefined);
+	if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+		const out = {};
+		for (const [key, entry] of Object.entries(value)) if (entry !== void 0) out[key] = dropUndefined(entry);
+		return out;
+	}
+	return value;
+}
+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",
+	validate(value) {
+		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 issue = textRequestSourceIssue(request);
+		if (issue) return { issues: [{ message: issue }] };
+		return { value: request };
+	}
+} };
+const passthroughSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		return { value };
+	}
+} };
+const unknownOutputSchema = passthroughSchema;
+const stringOutputSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate(value) {
+		return typeof value === "string" ? { value } : { issues: [{ message: "Expected string output" }] };
+	}
+} };
+const noInputSchema = passthroughSchema;
+function createBuiltinTextActor(src, mode, outputSchema) {
+	const logic = createAsyncLogic({ run: async () => {
+		throw new Error(`'${src}' has no host execution. Provide an implementation with machine.provide({ actors: { '${src}': ... } }) or execute the returned agent request with executeAgentRequest(...).`);
+	} });
+	return Object.assign(logic, {
+		kind: "statelyai.textLogic",
+		mode,
+		schemas: {
+			input: agentTextInputSchema,
+			output: outputSchema
+		},
+		request(input) {
+			return validateSchemaSync(agentTextInputSchema, input);
+		},
+		async execute(input, executors) {
+			const { result: output, raw } = await executeAgentTextRequest(mode, src, validateSchemaSync(agentTextInputSchema, input), executors);
+			return {
+				result: validateSchemaSync(outputSchema, output),
+				messages: responseMessagesOf(raw)
+			};
+		},
+		withExecutor(execute) {
+			return createTextLogic({
+				mode,
+				schemas: {
+					input: agentTextInputSchema,
+					output: outputSchema
+				},
+				name: ({ input }) => input.name,
+				model: ({ input }) => input.model,
+				system: ({ input }) => input.system,
+				prompt: ({ input }) => input.prompt,
+				messages: ({ input }) => input.messages,
+				tools: ({ input }) => input.tools,
+				toolChoice: ({ input }) => input.toolChoice,
+				includeReasoning: ({ input }) => input.includeReasoning,
+				temperature: ({ input }) => input.temperature,
+				maxOutputTokens: ({ input }) => input.maxOutputTokens,
+				topP: ({ input }) => input.topP,
+				topK: ({ input }) => input.topK,
+				seed: ({ input }) => input.seed,
+				stopSequences: ({ input }) => input.stopSequences,
+				maxSteps: ({ input }) => input.maxSteps,
+				metadata: ({ input }) => input.metadata
+			}, execute);
+		}
+	});
+}
+/** The unbound `agent.generateText`/`agent.streamText` builtins registered by setupAgent. @internal */
+const builtinTextActors = {
+	[GENERATE_TEXT_ACTOR]: createBuiltinTextActor(GENERATE_TEXT_ACTOR, "generate", unknownOutputSchema),
+	[STREAM_TEXT_ACTOR]: createBuiltinTextActor(STREAM_TEXT_ACTOR, "stream", stringOutputSchema)
+};
+/**
+* Validates a raw model/executor output against `schema`, returning the
+* parsed value. Thin wrapper over {@link validateSchemaSync} for parsing a
+* text request's structured output outside of `TextLogic.execute`/
+* `executeAgentRequest` (e.g. a custom host loop).
+*/
+function parseOutput(schema, output) {
+	return validateSchemaSync(schema, output);
+}
+/** Resolves a `ResolveTextLogicValue` (calls it if it's a function, else returns it as-is). @internal */
+function resolveTextLogicValue(value, args) {
+	return typeof value === "function" ? value(args) : value;
+}
+/**
+* Creates reusable, standalone {@link TextLogic}: an actor that, when run,
+* resolves typed input to typed output via a model call. Register the
+* result under `actors:` and invoke it by name (equivalent to what
+* `setupAgent({ requests })` builds internally for each request entry). Pass
+* `execute` here, or bind it later with `.withExecutor(...)`, a runtime
+* adapter's `machine.provide(...)`, or `runAgent`'s `generateText`/
+* `streamText` options.
+*
+* @example
+* ```ts
+* export const tellJoke = createTextLogic({
+*   mode: 'stream',
+*   schemas: { input: z.object({ topic: z.string() }), output: z.string() },
+*   model: 'openai/gpt-5.4-mini',
+*   system: 'You tell short, punchy jokes.',
+*   prompt: ({ input }) => `Tell a joke about ${input.topic}.`,
+* });
+* ```
+*/
+function createTextLogic(config, execute) {
+	const schemas = {
+		input: config.schemas?.input ?? noInputSchema,
+		output: config.schemas?.output ?? stringOutputSchema
+	};
+	const request = (input) => {
+		const parsedInput = validateSchemaSync(schemas.input, input);
+		const args = { input: parsedInput };
+		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,
+			input: parsedInput,
+			model: resolveTextLogicValue(config.model, args),
+			system: resolveTextLogicValue(config.system, args),
+			prompt,
+			messages,
+			tools: resolveTextLogicValue(config.tools, args),
+			toolChoice: resolveTextLogicValue(config.toolChoice, args),
+			outputSchema: schemas.output,
+			includeReasoning: resolveTextLogicValue(config.includeReasoning, args),
+			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),
+			maxSteps: resolveTextLogicValue(config.maxSteps, args),
+			metadata: resolveTextLogicValue(config.metadata, args)
+		};
+	};
+	const logic = createAsyncLogic({ run: async ({ input, signal, system, self }, enq) => {
+		const resolvedRequest = request(input);
+		if (!execute) throw new Error("Text logic has no host execution. Pass an executor as the second argument to createTextLogic(...), provide a runtime adapter, or bind it through runAgent/provideExecutors, or execute the XState effect in your host.");
+		const result = await execute({
+			input,
+			request: resolvedRequest,
+			signal,
+			system,
+			self,
+			emit: enq.emit
+		});
+		const selfId = self?.id;
+		const output = await normalizeGeneratorResult(result, typeof selfId === "string" ? selfId : "text logic");
+		return {
+			result: validateSchemaSync(schemas.output, output),
+			messages: responseMessagesOf(result)
+		};
+	} });
+	const textLogic = Object.assign(logic, {
+		kind: "statelyai.textLogic",
+		mode: config.mode ?? "generate",
+		schemas,
+		request,
+		async execute(input, executors) {
+			const { result: output, raw } = await executeAgentTextRequest(config.mode ?? "generate", "textLogic", request(input), executors);
+			return {
+				result: validateSchemaSync(schemas.output, output),
+				messages: responseMessagesOf(raw)
+			};
+		},
+		withExecutor(nextExecute) {
+			return createTextLogic(config, nextExecute);
+		}
+	});
+	if (execute) executorBoundLogics.add(textLogic);
+	return textLogic;
+}
+/**
+* Binds a child machine's {@link TextLogic} to a raw
+* {@link AgentRequestExecutor} (the `generateText`/`streamText` shape hosts
+* implement). Encapsulates the `withExecutor` idiom child agents repeat:
+* default the request's `tools` to `{}`, forward the actor `signal`, call the
+* executor, and return its `{ result }`. Use this to share ONE
+* executor across a parent and its nested children.
+*
+* @example
+* ```ts
+* childMachine.provide({
+*   actors: {
+*     researchTopic: bindRequestExecutor(setup.requests.researchTopic, generateText),
+*   },
+* });
+* ```
+*/
+function bindRequestExecutor(logic, executor, info) {
+	return logic.withExecutor(async ({ request, signal }) => {
+		const { result, messages } = await executor({
+			...request,
+			tools: request.tools ?? {}
+		}, {
+			signal,
+			onChunk: info?.onChunk
+		});
+		return {
+			result,
+			messages
+		};
+	});
+}
+/** Type guard: true for any actor logic built by createTextLogic (checks the `kind` marker). @internal */
+function isTextLogic(value) {
+	return !!value && typeof value === "object" && value.kind === "statelyai.textLogic" && typeof value.request === "function";
+}
+/**
+* Classifies a text request's output schema as `'structured'` (its JSON
+* Schema is `type: 'object'`, `type: 'array'`, or a top-level union/
+* composition — `anyOf`/`oneOf`/`allOf`, which a bare `z.union`/
+* `z.discriminatedUnion` emits with no top-level `type`) or `'text'`
+* (anything else, including no schema). Reads the schema's
+* `~standard.jsonSchema.input()` extension — schemas without it are treated
+* as `'text'`.
+*/
+function getAgentOutputMode(schema) {
+	const jsonSchema = getJsonSchemaSync(schema);
+	if (!jsonSchema) return "text";
+	if (jsonSchema.type === "object" || jsonSchema.type === "array") return "structured";
+	if (jsonSchema.type === void 0 && ("anyOf" in jsonSchema || "oneOf" in jsonSchema || "allOf" in jsonSchema)) return "structured";
+	return "text";
+}
+/**
+* Builds the schema every structured request is sent to the provider as: a
+* root object `{ result: <inner> }` wrapping the declared schema, plus — when
+* `options.reasoning` is `true` — an optional string `reasoning` property listed
+* BEFORE `result` (property order nudges the model to reason first). This is THE
+* wire contract for structured output: a root object is universally accepted as
+* a provider response schema, unlike a bare union/array root that many providers
+* reject.
+*
+* The returned {@link StandardSchemaV1} validates the `{ reasoning?, result }`
+* object (validating `result` through the original schema, capturing a string
+* `reasoning` when present) and exposes the wrapped JSON Schema. An executor
+* returns the parsed `{ result, reasoning? }` as-is: `result` is what the
+* machine validates against the declared schema, and `reasoning` stays on the
+* raw executor result, never in machine context/output.
+*/
+function providerOutputSchema(inner, options = {}) {
+	const includeReasoning = options.reasoning === true;
+	const buildJson = (innerJson) => ({
+		type: "object",
+		properties: {
+			...includeReasoning ? { reasoning: { type: "string" } } : {},
+			result: innerJson ?? {}
+		},
+		required: ["result"],
+		additionalProperties: false
+	});
+	return { "~standard": {
+		version: 1,
+		vendor: "statelyai-agent",
+		validate(value) {
+			if (!value || typeof value !== "object" || !("result" in value)) return { issues: [{ message: "Expected a { result } object" }] };
+			const innerResult = inner["~standard"].validate(value.result);
+			if (innerResult instanceof Promise) throw new Error("Async schema validation is not supported.");
+			if (innerResult.issues) return innerResult;
+			const parsed = { result: innerResult.value };
+			const reasoning = value.reasoning;
+			if (typeof reasoning === "string") parsed.reasoning = reasoning;
+			return { value: parsed };
+		},
+		jsonSchema: { input: () => {
+			const innerJson = inner["~standard"].jsonSchema?.input?.();
+			return innerJson instanceof Promise ? innerJson.then(buildJson) : buildJson(innerJson);
+		} }
+	} };
+}
+/**
+* Validates a raw provider value against the provider output schema for
+* `request` and returns the unwrapped `{ result, reasoning? }` — the checked
+* replacement for `raw as ProviderStructuredOutput` in hand-written hosts.
+* Pair with {@link providerOutputSchema} (which produced the schema the
+* provider was asked to satisfy).
+*/
+function parseProviderOutput(request, value) {
+	if (!request.outputSchema) throw new Error("parseProviderOutput: the request declares no outputSchema.");
+	return validateSchemaSync(providerOutputSchema(request.outputSchema, { reasoning: request.includeReasoning }), value);
+}
+/**
+* Merges request-declared and call-site `tools`, dispatches to the
+* `mode`-appropriate executor (`generateText`/`streamText`), and normalizes
+* the raw result via {@link normalizeGeneratorResult}. Shared by
+* `TextLogic.execute`, `executeAgentRequest`, and the `agent.generateText`/
+* `agent.streamText` builtins. Throws if no executor is registered for
+* `mode`.
+*
+* @internal
+*/
+async function executeAgentTextRequest(mode, id, input, executors, tools = {}, info) {
+	const request = {
+		...input,
+		name: input.name ?? id,
+		tools: {
+			...input.tools,
+			...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);
+	return {
+		result: await normalizeGeneratorResult(raw, id),
+		raw
+	};
+}
+/**
+* Unwraps an executor result into the request's final value: awaits and
+* returns `result` from the `{ result }` {@link AgentRequestExecutorResult}.
+* Anything else is a runtime error naming `id`. This is
+* generator-result unwrapping only — decision results are extracted separately
+* by `resolveDecision`.
+*
+* @internal
+*/
+async function normalizeGeneratorResult(result, id = "text request") {
+	const resolved = await result;
+	if (!resolved || typeof resolved !== "object" || !("result" in resolved)) throw invalidGeneratorResult(id);
+	return await resolved.result;
+}
+function invalidGeneratorResult(id) {
+	return /* @__PURE__ */ new Error(`Executor for '${id}' returned an invalid result: executors must return { result } (the text string or structured object as \`result\`, plus optional \`messages\`, \`usage\` and other passthrough fields). Wrap a raw SDK result with an adapter such as createAiSdkExecutors.`);
+}
+//#endregion
+export { getJsonSchema as A, userMessage as B, isUnboundPlaceholder as C, assistantMessage as D, setAgentExecutionOptions as E, getStatePath as F, AgentError as H, isStandardSchema as I, resolveMachineVersion as L, getMachineStructuralHash as M, getMessageText as N, djb2Hex as O, getStateMeta as P, systemMessage as R, getRegisteredAgentExecutionOptions as S, missingActor as T, AgentTruncatedError as U, validateSchemaSync as V, resolveTextLogicValue as _, bindRequestExecutor as a, getAgentExecutionOptions as b, executeAgentTextRequest as c, getCallUsage as d, isTextLogic as f, providerOutputSchema as g, parseProviderOutput as h, STREAM_TEXT_ACTOR as i, getJsonSchemaSync as j, findNonSerializableContextPaths as k, getAgentOutputMode as l, parseOutput as m, DECIDE_ACTOR as n, builtinTextActors as o, normalizeGeneratorResult as p, GENERATE_TEXT_ACTOR as r, createTextLogic as s, AGENT_USAGE_TOKEN_FIELDS as t, getCallFinishReason as u, responseMessagesOf as v, machineIdlePredicates as w, getMachineIdlePredicate as x, executorBoundLogics as y, toolMessage as z };