@statelyai/agent 2.0.0-alpha.24 → 2.0.0-alpha.26

package/dist/text-logic-C8xyr6Ag.cjs

@@ -0,0 +1,1091 @@
+require("./validate.cjs");
+let xstate = require("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 = (0, xstate.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 = (0, xstate.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 = (0, xstate.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
+Object.defineProperty(exports, "AGENT_USAGE_TOKEN_FIELDS", {
+	enumerable: true,
+	get: function() {
+		return AGENT_USAGE_TOKEN_FIELDS;
+	}
+});
+Object.defineProperty(exports, "AgentError", {
+	enumerable: true,
+	get: function() {
+		return AgentError;
+	}
+});
+Object.defineProperty(exports, "AgentTruncatedError", {
+	enumerable: true,
+	get: function() {
+		return AgentTruncatedError;
+	}
+});
+Object.defineProperty(exports, "DECIDE_ACTOR", {
+	enumerable: true,
+	get: function() {
+		return DECIDE_ACTOR;
+	}
+});
+Object.defineProperty(exports, "GENERATE_TEXT_ACTOR", {
+	enumerable: true,
+	get: function() {
+		return GENERATE_TEXT_ACTOR;
+	}
+});
+Object.defineProperty(exports, "STREAM_TEXT_ACTOR", {
+	enumerable: true,
+	get: function() {
+		return STREAM_TEXT_ACTOR;
+	}
+});
+Object.defineProperty(exports, "assistantMessage", {
+	enumerable: true,
+	get: function() {
+		return assistantMessage;
+	}
+});
+Object.defineProperty(exports, "bindRequestExecutor", {
+	enumerable: true,
+	get: function() {
+		return bindRequestExecutor;
+	}
+});
+Object.defineProperty(exports, "builtinTextActors", {
+	enumerable: true,
+	get: function() {
+		return builtinTextActors;
+	}
+});
+Object.defineProperty(exports, "createTextLogic", {
+	enumerable: true,
+	get: function() {
+		return createTextLogic;
+	}
+});
+Object.defineProperty(exports, "djb2Hex", {
+	enumerable: true,
+	get: function() {
+		return djb2Hex;
+	}
+});
+Object.defineProperty(exports, "executeAgentTextRequest", {
+	enumerable: true,
+	get: function() {
+		return executeAgentTextRequest;
+	}
+});
+Object.defineProperty(exports, "executorBoundLogics", {
+	enumerable: true,
+	get: function() {
+		return executorBoundLogics;
+	}
+});
+Object.defineProperty(exports, "findNonSerializableContextPaths", {
+	enumerable: true,
+	get: function() {
+		return findNonSerializableContextPaths;
+	}
+});
+Object.defineProperty(exports, "getAgentExecutionOptions", {
+	enumerable: true,
+	get: function() {
+		return getAgentExecutionOptions;
+	}
+});
+Object.defineProperty(exports, "getAgentOutputMode", {
+	enumerable: true,
+	get: function() {
+		return getAgentOutputMode;
+	}
+});
+Object.defineProperty(exports, "getCallFinishReason", {
+	enumerable: true,
+	get: function() {
+		return getCallFinishReason;
+	}
+});
+Object.defineProperty(exports, "getCallUsage", {
+	enumerable: true,
+	get: function() {
+		return getCallUsage;
+	}
+});
+Object.defineProperty(exports, "getJsonSchema", {
+	enumerable: true,
+	get: function() {
+		return getJsonSchema;
+	}
+});
+Object.defineProperty(exports, "getJsonSchemaSync", {
+	enumerable: true,
+	get: function() {
+		return getJsonSchemaSync;
+	}
+});
+Object.defineProperty(exports, "getMachineIdlePredicate", {
+	enumerable: true,
+	get: function() {
+		return getMachineIdlePredicate;
+	}
+});
+Object.defineProperty(exports, "getMachineStructuralHash", {
+	enumerable: true,
+	get: function() {
+		return getMachineStructuralHash;
+	}
+});
+Object.defineProperty(exports, "getMessageText", {
+	enumerable: true,
+	get: function() {
+		return getMessageText;
+	}
+});
+Object.defineProperty(exports, "getRegisteredAgentExecutionOptions", {
+	enumerable: true,
+	get: function() {
+		return getRegisteredAgentExecutionOptions;
+	}
+});
+Object.defineProperty(exports, "getStateMeta", {
+	enumerable: true,
+	get: function() {
+		return getStateMeta;
+	}
+});
+Object.defineProperty(exports, "getStatePath", {
+	enumerable: true,
+	get: function() {
+		return getStatePath;
+	}
+});
+Object.defineProperty(exports, "isStandardSchema", {
+	enumerable: true,
+	get: function() {
+		return isStandardSchema;
+	}
+});
+Object.defineProperty(exports, "isTextLogic", {
+	enumerable: true,
+	get: function() {
+		return isTextLogic;
+	}
+});
+Object.defineProperty(exports, "isUnboundPlaceholder", {
+	enumerable: true,
+	get: function() {
+		return isUnboundPlaceholder;
+	}
+});
+Object.defineProperty(exports, "machineIdlePredicates", {
+	enumerable: true,
+	get: function() {
+		return machineIdlePredicates;
+	}
+});
+Object.defineProperty(exports, "missingActor", {
+	enumerable: true,
+	get: function() {
+		return missingActor;
+	}
+});
+Object.defineProperty(exports, "normalizeGeneratorResult", {
+	enumerable: true,
+	get: function() {
+		return normalizeGeneratorResult;
+	}
+});
+Object.defineProperty(exports, "parseOutput", {
+	enumerable: true,
+	get: function() {
+		return parseOutput;
+	}
+});
+Object.defineProperty(exports, "parseProviderOutput", {
+	enumerable: true,
+	get: function() {
+		return parseProviderOutput;
+	}
+});
+Object.defineProperty(exports, "providerOutputSchema", {
+	enumerable: true,
+	get: function() {
+		return providerOutputSchema;
+	}
+});
+Object.defineProperty(exports, "resolveMachineVersion", {
+	enumerable: true,
+	get: function() {
+		return resolveMachineVersion;
+	}
+});
+Object.defineProperty(exports, "resolveTextLogicValue", {
+	enumerable: true,
+	get: function() {
+		return resolveTextLogicValue;
+	}
+});
+Object.defineProperty(exports, "responseMessagesOf", {
+	enumerable: true,
+	get: function() {
+		return responseMessagesOf;
+	}
+});
+Object.defineProperty(exports, "setAgentExecutionOptions", {
+	enumerable: true,
+	get: function() {
+		return setAgentExecutionOptions;
+	}
+});
+Object.defineProperty(exports, "systemMessage", {
+	enumerable: true,
+	get: function() {
+		return systemMessage;
+	}
+});
+Object.defineProperty(exports, "toolMessage", {
+	enumerable: true,
+	get: function() {
+		return toolMessage;
+	}
+});
+Object.defineProperty(exports, "userMessage", {
+	enumerable: true,
+	get: function() {
+		return userMessage;
+	}
+});
+Object.defineProperty(exports, "validateSchemaSync", {
+	enumerable: true,
+	get: function() {
+		return validateSchemaSync;
+	}
+});