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

package/dist/decision-CM9CYZ6t.cjs

@@ -0,0 +1,519 @@
+const require_text_logic = require("./text-logic-C8xyr6Ag.cjs");
+require("./validate.cjs");
+let xstate = require("xstate");
+//#region src/internal/is-record.ts
+/** True for a plain object-like value (arrays excluded). @internal */
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/events.ts
+/**
+* Thrown by {@link parseAgentEvent} (and {@link eventFromInteraction}) when a
+* wire payload is not a usable event: it is not an object with a string
+* `type`, it names a reserved `@agent.*` type, or its fields fail the schema
+* the machine registered for that type. A host turns it into a 400.
+*
+* Not handling an event is NOT this error — a state machine ignores events it
+* has no transition for, so an event the current state does not handle parses
+* fine and settles the run with `result.ignored` set.
+*/
+var AgentInvalidEventPayloadError = class extends require_text_logic.AgentError {
+	eventType;
+	constructor(eventType, detail) {
+		super("invalid-event-payload", `Invalid event payload for '${eventType}': ${detail}`);
+		this.name = "AgentInvalidEventPayloadError";
+		this.eventType = eventType;
+	}
+};
+/** Prefix for the synthetic tool name generated per candidate event (e.g. `send_event_ASK`). @internal */
+const EVENT_TOOL_PREFIX = "send_event_";
+function hashString(value) {
+	let hash = 5381;
+	for (let i = 0; i < value.length; i++) hash = hash * 33 ^ value.charCodeAt(i);
+	return (hash >>> 0).toString(36);
+}
+function sanitizeEventToolName(eventType) {
+	const base = `${EVENT_TOOL_PREFIX}${eventType.replace(/[^a-zA-Z0-9_-]/g, "_") || "event"}`;
+	if (base.length <= 64) return base;
+	const hash = hashString(eventType);
+	const prefixLength = 64 - hash.length - 1;
+	return `${base.slice(0, prefixLength)}_${hash}`;
+}
+function disambiguateEventToolName(toolName, eventType, usedToolNames) {
+	if (!usedToolNames.has(toolName)) {
+		usedToolNames.add(toolName);
+		return toolName;
+	}
+	const suffix = `_${hashString(eventType)}`;
+	const uniqueToolName = `${toolName.slice(0, 64 - suffix.length)}${suffix}`;
+	usedToolNames.add(uniqueToolName);
+	return uniqueToolName;
+}
+/**
+* True when an event type matches an `allowedEvents` entry: an exact type,
+* `'*'` (every event), or a `'prefix.*'` wildcard matching any deeper
+* segment (`'todo.*'` matches `'todo.add'` and `'todo.list.clear'`, not
+* `'todo'` itself — mirroring xstate's partial wildcard events).
+*/
+function matchesEventPattern(eventType, pattern) {
+	if (pattern === "*") return true;
+	if (pattern.endsWith(".*")) return eventType.startsWith(`${pattern.slice(0, -1)}`);
+	return eventType === pattern;
+}
+/**
+* Event types reserved for delivery by the library (`@agent.*`). A machine
+* may declare transitions on them,
+* but they are never model-facing: {@link getAcceptedEvents} drops them before
+* any `allowedEvents` matching, so they cannot be offered as a decision
+* candidate (not even under a `'*'` wildcard) and {@link parseAgentEvent}
+* rejects them — a model or a wire message must not be able to forge one.
+* @internal
+*/
+const RESERVED_AGENT_EVENT_PREFIX = "@agent.";
+function isReservedAgentEvent(eventType) {
+	return eventType.startsWith(RESERVED_AGENT_EVENT_PREFIX);
+}
+/** True when an `allowedEvents` entry is a wildcard pattern rather than a concrete event type. @internal */
+function isEventPattern(entry) {
+	return entry === "*" || entry.endsWith(".*");
+}
+/**
+* Parses a wire payload (a request body, a socket frame) into an
+* event typed as the machine's event union, so it can go straight to
+* `runAgent({ event })` / `actor.send(...)` without a cast. Pass the machine
+* itself, or any snapshot of it.
+*
+* It checks exactly what a schema can check: the payload is an object with a
+* string `type`, that type is not one of the library-reserved `@agent.*` types,
+* and — when the machine registered a schema for it — the fields satisfy that
+* schema (defaults filled, transforms applied). Anything else throws
+* {@link AgentInvalidEventPayloadError}, which a host answers with a 400.
+*
+* It deliberately does NOT check whether the current state handles the event.
+* State machines ignore events they have no transition for; that is normal
+* behavior, not a validation failure. Send the parsed event and read
+* `result.ignored` if the host wants to tell the client nothing happened.
+*
+* @example
+* ```ts
+* const event = parseAgentEvent(machine, await request.json());
+* const result = await runAgent(machine, { store, threadId, event, executors });
+* ```
+*/
+function parseAgentEvent(source, payload, options = {}) {
+	if (!isRecord(payload) || typeof payload.type !== "string") throw new AgentInvalidEventPayloadError("(unknown)", "expected an object with a string `type`.");
+	const event = payload;
+	if (isReservedAgentEvent(event.type)) throw new AgentInvalidEventPayloadError(event.type, "this event type is reserved for the library and cannot be sent from outside.");
+	const registered = require_text_logic.getAgentExecutionOptions(typeof source.provide === "function" ? source : source.machine)?.schemas;
+	const inputSchema = (options.events ?? options.schemas?.events ?? registered?.events)?.[event.type];
+	if (!inputSchema) return event;
+	const { type, ...fields } = event;
+	try {
+		return {
+			...require_text_logic.validateSchemaSync(inputSchema, fields),
+			type
+		};
+	} catch (error) {
+		throw new AgentInvalidEventPayloadError(event.type, error instanceof Error ? error.message : String(error));
+	}
+}
+/**
+* Lists the events a snapshot can currently accept, as {@link AgentEventDescriptor}s
+* a model can be offered (via `resolveDecision`/an adapter's tool-per-event
+* mapping). **Filters by event TYPE only** — it does not evaluate guards, so
+* a type-legal-but-guard-rejected event can still appear here. Guard
+* legality is checked separately, at decision-resolution time, via
+* `snapshot.can(event)` (the `canTake` option of {@link resolveDecision} /
+* {@link ResolveDecisionOptions}). Pass `eventTypes` to further narrow to a
+* declared `allowedEvents` set — entries may be exact types or wildcard
+* patterns (`'*'`, `'todo.*'`; see {@link matchesEventPattern}).
+*
+* XState-internal (`xstate.*`) and library-reserved
+* ({@link RESERVED_AGENT_EVENT_PREFIX}) event types are always excluded, before
+* any `allowedEvents` matching — a machine that handles `'@agent.usage'` still
+* never offers it to a model.
+*/
+function getAcceptedEvents(snapshot, options = {}) {
+	const eventTypes = options.eventTypes;
+	const seen = /* @__PURE__ */ new Set();
+	const usedToolNames = /* @__PURE__ */ new Set();
+	return (0, xstate.getNextTransitions)(snapshot).flatMap((transitionDefinition) => {
+		const eventType = transitionDefinition.eventType;
+		if (!eventType || eventType === "*" || eventType.startsWith("xstate.") || isReservedAgentEvent(eventType) || eventTypes && !eventTypes.some((pattern) => matchesEventPattern(eventType, pattern)) || seen.has(eventType)) return [];
+		seen.add(eventType);
+		const toolName = disambiguateEventToolName(sanitizeEventToolName(eventType), eventType, usedToolNames);
+		const inputSchema = (options.events ?? options.schemas?.events)?.[eventType];
+		return [{
+			type: eventType,
+			toolName,
+			...inputSchema ? { inputSchema } : {}
+		}];
+	});
+}
+//#endregion
+//#region src/decision.ts
+function decideRequestFromInput(input) {
+	const allowedEventTypes = resolveAllowedEventTypes(input.allowedEvents, input) ?? [];
+	return {
+		kind: "decision",
+		id: "",
+		name: input.name,
+		input,
+		model: input.model,
+		system: input.system,
+		prompt: input.prompt,
+		messages: input.messages,
+		events: allowedEventTypes.filter((type) => !isEventPattern(type)).map((type) => ({
+			type,
+			toolName: sanitizeEventToolName(type)
+		})),
+		attempts: [],
+		temperature: input.temperature,
+		maxOutputTokens: input.maxOutputTokens,
+		topP: input.topP,
+		topK: input.topK,
+		seed: input.seed,
+		stopSequences: input.stopSequences,
+		metadata: input.metadata
+	};
+}
+function decideActorWithExecutor(execute) {
+	const logic = (0, xstate.createAsyncLogic)({ run: async ({ input, signal }) => {
+		if (!execute) throw new Error(`'${require_text_logic.DECIDE_ACTOR}' has no host execution. Provide an implementation with machine.provide({ actors: { '${require_text_logic.DECIDE_ACTOR}': ... } }) or resolve the returned agent request with resolveDecision(...).`);
+		const resolvedEventTypes = resolveAllowedEventTypes(input.allowedEvents, input);
+		if (resolvedEventTypes === void 0) throw new Error(`'${require_text_logic.DECIDE_ACTOR}' input has omitted \`allowedEvents\`, which means "all currently-legal events" — but that requires a snapshot-aware host (runAgent or the step path) to resolve. Under a bare createActor(...), declare \`allowedEvents\` explicitly to use this actor here.`);
+		if (resolvedEventTypes.some(isEventPattern)) throw new Error(`'${require_text_logic.DECIDE_ACTOR}' input uses wildcard \`allowedEvents\` patterns, which expand against the live snapshot — that requires a snapshot-aware host (runAgent or the step path). Under a bare createActor(...), list event types explicitly.`);
+		return resolveDecision(decideRequestFromInput(input), { decide: execute }, {
+			maxRetries: input.maxRetries ?? 2,
+			signal
+		});
+	} });
+	return Object.assign(logic, {
+		kind: "statelyai.decisionLogic",
+		maxRetries: 2,
+		request: decideRequestFromInput,
+		allowedEventTypes: (input) => resolveAllowedEventTypes(input.allowedEvents, input),
+		withExecutor: (nextExecute) => decideActorWithExecutor(nextExecute)
+	});
+}
+function createDecideActor() {
+	return decideActorWithExecutor();
+}
+function resolveAllowedEventTypes(allowedEvents, input) {
+	if (allowedEvents === void 0) return;
+	const resolved = typeof allowedEvents === "function" ? allowedEvents({ input }) : allowedEvents;
+	return typeof resolved === "string" ? [resolved] : resolved;
+}
+/**
+* Creates reusable, standalone {@link DecisionLogic}: an actor that, when
+* run, resolves to exactly one currently-legal {@link ChosenEvent} by
+* calling the host `decide` executor (passed here as `execute`, or supplied
+* later via {@link DecisionLogic.withExecutor}, `machine.provide(...)`, or
+* `runAgent`'s `decide` option). Register the result under `actors:` and
+* invoke it by name; for a one-off, state-local decision, prefer the
+* `agent.decide` builtin invoke instead — it needs no separate declaration
+* and types `allowedEvents` against the machine's own event schemas.
+*
+* @example
+* ```ts
+* import { createDecisionLogic } from '@statelyai/agent';
+* import { z } from 'zod';
+*
+* export const chooseMove = createDecisionLogic({
+*   schemas: { input: z.object({ playerHp: z.number(), enemyHp: z.number() }) },
+*   model: 'openai/gpt-5.4-mini',
+*   system: 'You are playing a turn-based game. Choose exactly one legal move.',
+*   prompt: ({ input }) => `Player HP: ${input.playerHp}\nEnemy HP: ${input.enemyHp}`,
+*   allowedEvents: ({ input }) =>
+*     input.playerHp <= 6
+*       ? ['ATTACK', 'DEFEND', 'HEAL', 'FLEE']
+*       : ['ATTACK', 'DEFEND', 'FLEE'],
+* });
+* ```
+*/
+function createDecisionLogic(config, execute) {
+	const maxRetries = config.maxRetries ?? 2;
+	const request = (input) => {
+		const parsedInput = config.schemas ? require_text_logic.validateSchemaSync(config.schemas.input, input) : input;
+		const args = { input: parsedInput };
+		const allowedEventTypes = resolveAllowedEventTypes(config.allowedEvents, parsedInput);
+		return {
+			kind: "decision",
+			id: "",
+			name: require_text_logic.resolveTextLogicValue(config.name, args),
+			input: parsedInput,
+			model: require_text_logic.resolveTextLogicValue(config.model, args),
+			system: require_text_logic.resolveTextLogicValue(config.system, args),
+			prompt: require_text_logic.resolveTextLogicValue(config.prompt, args),
+			messages: require_text_logic.resolveTextLogicValue(config.messages, args),
+			events: (allowedEventTypes ?? []).map((type) => ({
+				type,
+				toolName: sanitizeEventToolName(type)
+			})),
+			attempts: [],
+			temperature: require_text_logic.resolveTextLogicValue(config.temperature, args),
+			maxOutputTokens: require_text_logic.resolveTextLogicValue(config.maxOutputTokens, args),
+			topP: require_text_logic.resolveTextLogicValue(config.topP, args),
+			topK: require_text_logic.resolveTextLogicValue(config.topK, args),
+			seed: require_text_logic.resolveTextLogicValue(config.seed, args),
+			stopSequences: require_text_logic.resolveTextLogicValue(config.stopSequences, args),
+			metadata: require_text_logic.resolveTextLogicValue(config.metadata, args)
+		};
+	};
+	const logic = (0, xstate.createAsyncLogic)({ run: async ({ input, signal }) => {
+		if (!execute) throw new Error("Decision logic has no host execution. Pass an executor as the second argument to createDecisionLogic(...), provide a runtime adapter, or bind it through runAgent/provideExecutors, or call resolveDecision from your host.");
+		const allowedEventTypes = resolveAllowedEventTypes(config.allowedEvents, input);
+		if (allowedEventTypes === void 0) throw new Error("Decision logic has omitted `allowedEvents`, which means \"all currently-legal events\" — but that requires a snapshot-aware host (runAgent or the step path) to resolve. Under a bare createActor(...), declare `allowedEvents` explicitly on this logic to use it here.");
+		if (allowedEventTypes.some(isEventPattern)) throw new Error("Decision logic uses wildcard `allowedEvents` patterns, which expand against the live snapshot — that requires a snapshot-aware host (runAgent or the step path). Under a bare createActor(...), list event types explicitly.");
+		return resolveDecision(request(input), { decide: execute }, {
+			maxRetries,
+			signal
+		});
+	} });
+	const decisionLogic = Object.assign(logic, {
+		kind: "statelyai.decisionLogic",
+		maxRetries,
+		request,
+		allowedEventTypes: (input) => resolveAllowedEventTypes(config.allowedEvents, input),
+		withExecutor(nextExecute) {
+			return createDecisionLogic(config, nextExecute);
+		}
+	});
+	if (execute) require_text_logic.executorBoundLogics.add(decisionLogic);
+	return decisionLogic;
+}
+/** Type guard: true for any actor logic built by createDecisionLogic/createDecideActor (checks the `kind` marker). @internal */
+function isDecisionLogic(value) {
+	return !!value && typeof value === "object" && value.kind === "statelyai.decisionLogic" && typeof value.request === "function";
+}
+/**
+* Builds an {@link AgentDecisionRequest} for {@link resolveDecision}, filling
+* in the fields a hand-written literal has to restate every time: `kind`, an
+* `id`, an empty `attempts` list, and each candidate event's `toolName`.
+*
+* @example
+* ```ts
+* const chosen = await resolveDecision(
+*   createDecisionRequest({
+*     name: 'judge',
+*     model: 'reviewer',
+*     prompt: `Judge this draft.\n\n${snapshot.context.draft}`,
+*     events: getAcceptedEvents(snapshot),
+*   }),
+*   { decide },
+*   { canTake: (event) => snapshot.can(event) },
+* );
+* ```
+*/
+function createDecisionRequest(options) {
+	const { id, name, events, attempts, ...rest } = options;
+	return {
+		...rest,
+		kind: "decision",
+		id: id ?? name ?? "decision",
+		...name === void 0 ? {} : { name },
+		events: dedupeToolNames(events.map((event) => typeof event === "string" ? {
+			type: event,
+			toolName: sanitizeEventToolName(event)
+		} : event)),
+		attempts: attempts ?? []
+	};
+}
+function dedupeToolNames(candidates) {
+	const taken = /* @__PURE__ */ new Set();
+	return candidates.map((candidate) => {
+		if (candidate.toolName === void 0) return candidate;
+		let toolName = candidate.toolName;
+		for (let n = 2; taken.has(toolName); n++) {
+			const suffix = `_${n}`;
+			toolName = `${candidate.toolName.slice(0, 64 - suffix.length)}${suffix}`;
+		}
+		taken.add(toolName);
+		return toolName === candidate.toolName ? candidate : {
+			...candidate,
+			toolName
+		};
+	});
+}
+/**
+* Thrown by {@link resolveDecision} when every attempt (up to
+* `maxRetries + 1` of them) fails one of the three checks recorded in
+* {@link DecisionAttempt.failure}. Carries the full `attempts` list for
+* diagnostics; a machine typically routes this via the decision invoke's
+* `onError`.
+*/
+var AgentDecisionExhaustedError = class extends require_text_logic.AgentError {
+	attempts;
+	constructor(attempts) {
+		super("decision-exhausted", `Decision exhausted after ${attempts.length} attempt${attempts.length === 1 ? "" : "s"}: ` + attempts.map((attempt) => attempt.reason).join("; "));
+		this.name = "AgentDecisionExhaustedError";
+		this.attempts = attempts;
+	}
+};
+/**
+* Renders a decision request's prior failed `attempts` into feedback messages
+* a host appends to the model call so retries converge — the transport-agnostic
+* "your last choice failed because X, choose again from Y" logic every adapter
+* and raw-SDK host repeats. Returns one `user`-role {@link AgentMessage} per
+* attempt (empty when there are none); adapters map each onto their wire
+* message shape (`attempt.content` is always a string). Core never rewrites the
+* request itself — this only turns the recorded attempts into messages.
+*
+* @example
+* ```ts
+* const messages = [...baseMessages, ...renderDecisionAttempts(request)];
+* ```
+*/
+function renderDecisionAttempts(request) {
+	const types = request.events.map((event) => event.type).join(", ") || "(none)";
+	return request.attempts.map((attempt) => require_text_logic.userMessage(`Your previous choice failed: ${attempt.reason}. Choose again from: ${types}`));
+}
+/**
+* Validation + retry core for decisions. No provider mechanics — the
+* `executors.decide` is responsible for making the model choose an event; this
+* function only validates the choice and retries on failure, up to
+* `options.maxRetries` (default 2, i.e. up to 3 attempts total).
+*
+* Each attempt is checked in order and can fail one of three ways (recorded
+* as a {@link DecisionAttempt}): `'unknown-event'` (the chosen `type` is not
+* among `request.events`), `'invalid-payload'` (the payload fails that
+* event's schema), or `'rejected-by-guard'` (passes both checks but
+* `options.canTake` returns `false` — a type/payload-legal event the
+* machine's guard rejects right now; omit `canTake` to skip this check).
+* Every prior failed attempt for this call is fed back to the executor on
+* the next attempt via `request.attempts`, so an adapter can render "your
+* last choice failed because X — try again" into the next model call; core
+* never rewrites the request itself. Exhausting all attempts throws
+* {@link AgentDecisionExhaustedError} with the full attempts list.
+*
+* @example
+* ```ts
+* const event = await resolveDecision(request, executors, {
+*   canTake: (e) => snapshot.can(e),
+* });
+* ```
+*/
+async function resolveDecision(request, executors, options = {}) {
+	const executor = executors?.decide;
+	if (typeof executor !== "function") throw new require_text_logic.AgentError("missing-decide-executor", "resolveDecision(request, executors, ...) takes the EXECUTOR SET (the same object executeAgentRequest takes), and this one has no 'decide' function. Build one with createAiSdkExecutors({ models }), or pass { decide }.");
+	const maxRetries = options.maxRetries ?? 2;
+	const attempts = [];
+	const eventsByType = new Map(request.events.map((event) => [event.type, event]));
+	for (let attempt = 0; attempt <= maxRetries; attempt++) {
+		options.signal?.throwIfAborted();
+		const result = await executor({
+			...request,
+			name: request.name ?? (request.id || "agent.decide"),
+			attempts: [...attempts]
+		}, {
+			...options.signal !== void 0 ? { signal: options.signal } : {},
+			...request.id ? { requestId: request.id } : {}
+		});
+		if (!result || typeof result !== "object" || typeof result.event !== "object" || result.event === null || typeof result.event.type !== "string") throw new Error(`decide executor must return { event: { type: string, ... } }; got ${JSON.stringify(result)}. Wrap the chosen event: return { event: { type: 'SAFE' } }.`);
+		const { event } = result;
+		const descriptor = eventsByType.get(event.type);
+		if (!descriptor) {
+			attempts.push({
+				event,
+				failure: "unknown-event",
+				reason: `'${event.type}' is not among the currently allowed events: ${request.events.map((candidate) => candidate.type).join(", ") || "(none)"}.`
+			});
+			continue;
+		}
+		let validatedEvent = event;
+		if (descriptor.inputSchema) {
+			const { type, ...payload } = event;
+			try {
+				validatedEvent = {
+					...require_text_logic.validateSchemaSync(descriptor.inputSchema, payload),
+					type
+				};
+			} catch (error) {
+				attempts.push({
+					event,
+					failure: "invalid-payload",
+					reason: `'${event.type}' payload failed validation: ${error instanceof Error ? error.message : String(error)}`
+				});
+				continue;
+			}
+		}
+		if (options.canTake?.(validatedEvent) === false) {
+			attempts.push({
+				event: validatedEvent,
+				failure: "rejected-by-guard",
+				reason: `'${validatedEvent.type}' is not currently takeable (guard rejected it).`
+			});
+			continue;
+		}
+		return validatedEvent;
+	}
+	throw new AgentDecisionExhaustedError(attempts);
+}
+//#endregion
+Object.defineProperty(exports, "AgentDecisionExhaustedError", {
+	enumerable: true,
+	get: function() {
+		return AgentDecisionExhaustedError;
+	}
+});
+Object.defineProperty(exports, "AgentInvalidEventPayloadError", {
+	enumerable: true,
+	get: function() {
+		return AgentInvalidEventPayloadError;
+	}
+});
+Object.defineProperty(exports, "createDecideActor", {
+	enumerable: true,
+	get: function() {
+		return createDecideActor;
+	}
+});
+Object.defineProperty(exports, "createDecisionLogic", {
+	enumerable: true,
+	get: function() {
+		return createDecisionLogic;
+	}
+});
+Object.defineProperty(exports, "createDecisionRequest", {
+	enumerable: true,
+	get: function() {
+		return createDecisionRequest;
+	}
+});
+Object.defineProperty(exports, "getAcceptedEvents", {
+	enumerable: true,
+	get: function() {
+		return getAcceptedEvents;
+	}
+});
+Object.defineProperty(exports, "isDecisionLogic", {
+	enumerable: true,
+	get: function() {
+		return isDecisionLogic;
+	}
+});
+Object.defineProperty(exports, "isRecord", {
+	enumerable: true,
+	get: function() {
+		return isRecord;
+	}
+});
+Object.defineProperty(exports, "parseAgentEvent", {
+	enumerable: true,
+	get: function() {
+		return parseAgentEvent;
+	}
+});
+Object.defineProperty(exports, "renderDecisionAttempts", {
+	enumerable: true,
+	get: function() {
+		return renderDecisionAttempts;
+	}
+});
+Object.defineProperty(exports, "resolveDecision", {
+	enumerable: true,
+	get: function() {
+		return resolveDecision;
+	}
+});