@statelyai/agent 1.1.6 → 2.0.0-alpha.11

package/dist/decision-D8wJrM8W.cjs

@@ -0,0 +1,286 @@
+const require_events = require("./events-CRQj3VtP.cjs");
+let xstate = require("xstate");
+//#region src/decision.ts
+function decideRequestFromInput(input) {
+	const allowedEventTypes = resolveAllowedEventTypes(input.allowedEvents, input) ?? [];
+	return {
+		kind: "decision",
+		id: "",
+		model: input.model,
+		system: input.system,
+		prompt: input.prompt,
+		messages: input.messages,
+		events: allowedEventTypes.filter((type) => !require_events.isEventPattern(type)).map((type) => ({
+			type,
+			toolName: require_events.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_events.DECIDE_ACTOR}' has no host execution. Provide an implementation with machine.provide({ actorSources: { '${require_events.DECIDE_ACTOR}': ... } }) or resolve the returned agent request with resolveDecision(...).`);
+		const resolvedEventTypes = resolveAllowedEventTypes(input.allowedEvents, input);
+		if (resolvedEventTypes === void 0) throw new Error(`'${require_events.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(require_events.isEventPattern)) throw new Error(`'${require_events.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), 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();
+}
+/**
+* Reserved event type the `agent.plan` builtin adds to every step's
+* candidates as the explicit "no further action needed" move. Choosing it
+* ends the plan (`stopped: 'done'`); it is never sent to the machine, so
+* machines need no no-op sentinel event of their own.
+*/
+const PLAN_DONE_EVENT_TYPE = "agent.plan.done";
+function createPlanActor() {
+	const logic = (0, xstate.createLogic)({
+		context: ({ input }) => ({
+			applied: [],
+			stepsRemaining: input.maxSteps ?? 8,
+			stopped: null
+		}),
+		run: ({ context, event }) => event.type === "plan.applied" ? { context: {
+			...context,
+			applied: [...context.applied, event.event],
+			stepsRemaining: context.stepsRemaining - 1
+		} } : event.type === "plan.ended" ? {
+			context: {
+				...context,
+				stopped: event.stopped
+			},
+			status: "done",
+			output: {
+				steps: context.applied,
+				stopped: event.stopped
+			}
+		} : void 0
+	});
+	return Object.assign(logic, {
+		kind: "statelyai.planLogic",
+		maxRetries: 2,
+		request: decideRequestFromInput,
+		allowedEventTypes: (input) => resolveAllowedEventTypes(input.allowedEvents, input)
+	});
+}
+const PLAN_LEDGER_SCOPE = { emit: () => {} };
+/**
+* Builds a fresh plan ledger snapshot from resolved plan input — the shared
+* starting point for BOTH hosts (the step path reads the invoke child's own
+* initial snapshot; runAgent seeds a local ledger with this). @internal
+*/
+function initialPlanLedger(logic, input) {
+	return logic.getInitialSnapshot(PLAN_LEDGER_SCOPE, input);
+}
+/**
+* Advances a plan ledger by one {@link PlanLedgerEvent}, returning the next
+* snapshot (unwrapping `createLogic`'s `[snapshot, effects]` tuple). Pure — no
+* mutation of the input snapshot. @internal
+*/
+function advancePlanLedger(logic, snapshot, event) {
+	const result = logic.transition(snapshot, event, PLAN_LEDGER_SCOPE);
+	return Array.isArray(result) ? result[0] : result;
+}
+/** Type guard: true for the `agent.plan` builtin logic (checks the `kind` marker). @internal */
+function isPlanLogic(logic) {
+	return !!logic && logic.kind === "statelyai.planLogic";
+}
+function resolveAllowedEventTypes(allowedEvents, input) {
+	if (allowedEvents === void 0) return;
+	const resolved = typeof allowedEvents === "function" ? allowedEvents({ input }) : allowedEvents;
+	return typeof resolved === "string" ? [resolved] : resolved;
+}
+/** 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";
+}
+/**
+* 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 DecisionExhaustedError = class extends Error {
+	attempts;
+	constructor(attempts) {
+		super(`Decision exhausted after ${attempts.length} attempt${attempts.length === 1 ? "" : "s"}: ` + attempts.map((attempt) => attempt.reason).join("; "));
+		this.name = "DecisionExhaustedError";
+		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_events.userMessage(`Your previous choice failed: ${attempt.reason}. Choose again from: ${types}`));
+}
+/**
+* Validation + retry core for decisions. No provider mechanics — the
+* `executor` 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 DecisionExhaustedError} with the full attempts list.
+*
+* @example
+* ```ts
+* const event = await resolveDecision(request, decide, {
+*   canTake: (e) => snapshot.can(e),
+* });
+* ```
+*/
+async function resolveDecision(request, executor, options = {}) {
+	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,
+			attempts: [...attempts],
+			signal: options.signal
+		});
+		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_events.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 DecisionExhaustedError(attempts);
+}
+//#endregion
+Object.defineProperty(exports, "DecisionExhaustedError", {
+	enumerable: true,
+	get: function() {
+		return DecisionExhaustedError;
+	}
+});
+Object.defineProperty(exports, "PLAN_DONE_EVENT_TYPE", {
+	enumerable: true,
+	get: function() {
+		return PLAN_DONE_EVENT_TYPE;
+	}
+});
+Object.defineProperty(exports, "advancePlanLedger", {
+	enumerable: true,
+	get: function() {
+		return advancePlanLedger;
+	}
+});
+Object.defineProperty(exports, "createDecideActor", {
+	enumerable: true,
+	get: function() {
+		return createDecideActor;
+	}
+});
+Object.defineProperty(exports, "createPlanActor", {
+	enumerable: true,
+	get: function() {
+		return createPlanActor;
+	}
+});
+Object.defineProperty(exports, "initialPlanLedger", {
+	enumerable: true,
+	get: function() {
+		return initialPlanLedger;
+	}
+});
+Object.defineProperty(exports, "isDecisionLogic", {
+	enumerable: true,
+	get: function() {
+		return isDecisionLogic;
+	}
+});
+Object.defineProperty(exports, "isPlanLogic", {
+	enumerable: true,
+	get: function() {
+		return isPlanLogic;
+	}
+});
+Object.defineProperty(exports, "renderDecisionAttempts", {
+	enumerable: true,
+	get: function() {
+		return renderDecisionAttempts;
+	}
+});
+Object.defineProperty(exports, "resolveDecision", {
+	enumerable: true,
+	get: function() {
+		return resolveDecision;
+	}
+});