@statelyai/agent 1.1.6 → 2.0.0-alpha.11

package/dist/steps-CVe54GPP.cjs

@@ -0,0 +1,420 @@
+const require_events = require("./events-CRQj3VtP.cjs");
+const require_decision = require("./decision-D8wJrM8W.cjs");
+let xstate = require("xstate");
+//#region src/steps.ts
+/**
+* The step path: durable, per-model-call-checkpoint hosting of an agent
+* machine. Public vocabulary — `initialAgentStep`, `transitionAgentStep`,
+* `resolveAgentStep`, `getAgentRequests`, `executeAgentRequest`,
+* `resolveAgentRequests`.
+* @module
+*/
+/** @internal Normalizes current and legacy XState invoke effect shapes. */
+function getInvokeEffectMetadata(action) {
+	if (action.type === "@xstate.spawn") return action;
+	if (action.type === "xstate.spawnChild") {
+		const params = action.params;
+		return params ? {
+			...params,
+			logic: action.logic
+		} : void 0;
+	}
+	if (action.type === "@xstate.start" && typeof action.src === "string") return action;
+}
+/**
+* Scans a set of executable actions (as returned by xstate's `transition`/
+* `initialTransition`) for spawned `TextLogic`/`DecisionLogic` invokes and
+* lowers each into an {@link AgentStepRequest}. The hand-passed-schemas
+* implementation detail behind the public {@link getAgentRequests} — it needs
+* `schemas`/`actorSources` passed explicitly, whereas `getAgentRequests`
+* pre-fills them from the machine's registered `setupAgent` options.
+* `options.snapshot` is required to resolve a decision's candidate events
+* (intersecting declared `allowedEvents` with what's currently legal) — omit
+* it and decision requests report an empty `events` list.
+*
+* @internal
+*/
+function getAgentRequestsWith(actions, options = {}) {
+	return [...actions.flatMap((action) => {
+		const params = getInvokeEffectMetadata(action);
+		if (!params || typeof params.src !== "string") return [];
+		if (typeof params.id !== "string" || params.id.length === 0) throw new Error(`Agent invoke '${params.src}' must define a durable string id.`);
+		const registeredLogic = require_events.isTextLogic(params.logic) || require_decision.isDecisionLogic(params.logic) ? params.logic : options.actorSources?.[params.src];
+		if (require_decision.isDecisionLogic(registeredLogic)) {
+			const decisionRequest = registeredLogic.request(params.input);
+			const allowedEventTypes = registeredLogic.allowedEventTypes?.(params.input);
+			const events = options.snapshot ? require_events.getAcceptedEvents(options.snapshot, {
+				events: options.events,
+				schemas: options.schemas,
+				eventTypes: allowedEventTypes,
+				eventToolName: options.eventToolName
+			}) : [];
+			return [{
+				...decisionRequest,
+				id: params.id,
+				events
+			}];
+		}
+		const textLogic = require_events.isTextLogic(registeredLogic) ? registeredLogic : void 0;
+		const input = textLogic ? textLogic.request(params.input) : void 0;
+		if (!input) return [];
+		return [{
+			kind: "text",
+			id: params.id,
+			src: params.src,
+			...textLogic ? { mode: textLogic.mode } : {},
+			input,
+			tools: input.tools ?? {},
+			events: []
+		}];
+	}), ...getActivePlanRequests(options)];
+}
+/**
+* Scans the live snapshot's children for active `agent.plan` (plan-logic)
+* invokes and lowers each into an {@link AgentPlanRequest} — the re-surfacing
+* half of plan discovery. Reads the applied-event trail and remaining budget
+* from the child's own ledger `context` ({@link PlanLedgerContext}), recomputes
+* the currently-legal candidates (∩ declared `allowedEvents`) plus the reserved
+* `agent.plan.done` move, and takes `stepsRemaining` from the ledger (falling
+* back to `maxSteps - applied.length` for a snapshot with no context yet).
+* Returns `[]` when no snapshot is available (candidates need a live snapshot).
+*
+* @internal
+*/
+function getActivePlanRequests(options) {
+	const snapshot = options.snapshot;
+	if (!snapshot) return [];
+	const children = snapshot.children;
+	if (!children) return [];
+	const requests = [];
+	for (const [id, child] of Object.entries(children)) {
+		const ref = child;
+		if (typeof ref?.getSnapshot !== "function") continue;
+		const src = typeof ref.src === "string" ? ref.src : void 0;
+		const logic = (src ? options.actorSources?.[src] : void 0) ?? ref.logic;
+		if (!require_decision.isPlanLogic(logic)) continue;
+		const childSnapshot = ref.getSnapshot();
+		if (childSnapshot?.status !== "active") continue;
+		const input = childSnapshot.input ?? {};
+		const maxSteps = input.maxSteps ?? 8;
+		const ledger = childSnapshot.context ?? {};
+		const applied = ledger.applied ?? [];
+		const stepsRemaining = ledger.stepsRemaining ?? maxSteps - applied.length;
+		const machineEvents = require_events.getAcceptedEvents(snapshot, {
+			events: options.events,
+			schemas: options.schemas,
+			eventTypes: logic.allowedEventTypes(input) ?? void 0,
+			eventToolName: options.eventToolName
+		});
+		const events = machineEvents.some((event) => event.type === "agent.plan.done") ? machineEvents : [...machineEvents, {
+			type: require_decision.PLAN_DONE_EVENT_TYPE,
+			toolName: require_events.sanitizeEventToolName(require_decision.PLAN_DONE_EVENT_TYPE)
+		}];
+		requests.push({
+			kind: "plan",
+			id,
+			src: src ?? "",
+			input,
+			events,
+			applied,
+			stepsRemaining: Math.max(0, stepsRemaining)
+		});
+	}
+	return requests;
+}
+/**
+* Builds the synthetic `xstate.done.actor.<id>` event xstate's `transition()`
+* expects to resolve a spawned invoke — the event {@link resolveAgentStep}
+* applies internally.
+*
+* @internal
+*/
+function doneEvent(request, output) {
+	return {
+		type: `xstate.done.actor.${typeof request === "string" ? request : request.id}`,
+		output
+	};
+}
+/**
+* Applies a request's `output` as a done event via `transition(...)`,
+* returning the raw `[snapshot, actions]` tuple. Lower-level than
+* {@link resolveAgentStep} — that helper wraps this and also runs
+* {@link getAgentRequests} to produce the next {@link AgentStep}.
+*
+* @internal
+*/
+function transitionResult(logic, snapshot, request, output) {
+	const event = doneEvent(request, output);
+	const result = (0, xstate.transition)(logic, snapshot, event);
+	applyFinalStateOutput(logic, result[0], event);
+	return result;
+}
+/**
+* Starts a machine and returns its first {@link AgentStep} — the step-path
+* equivalent of `initialTransition` plus request discovery. Begins the
+* durable/per-model-call-checkpoint loop: resolve each `step.requests` entry
+* (via {@link executeAgentRequest} for `kind: 'text'`, or
+* {@link resolveDecision} for `kind: 'decision'`), then advance with
+* {@link resolveAgentStep} or {@link transitionAgentStep}.
+*/
+function initialAgentStep(machine, input, options) {
+	const [snapshot, actions] = (0, xstate.initialTransition)(machine, input);
+	return createAgentStep(machine, snapshot, actions, require_events.getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Applies an externally-sent event (e.g. a decision's chosen event, or a
+* human's reply) and returns the next {@link AgentStep}. Accepts **either**
+* a raw snapshot **or** a prior `AgentStep` as the second argument —
+* `.snapshot` is unwrapped automatically, so callers can thread the whole
+* step object through without manually plucking the snapshot out.
+*/
+function transitionAgentStep(machine, snapshotOrStep, event, options) {
+	const [nextSnapshot, actions] = (0, xstate.transition)(machine, isAgentStep(snapshotOrStep) ? snapshotOrStep.snapshot : snapshotOrStep, event);
+	return createAgentStep(machine, nextSnapshot, actions, require_events.getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Applies a resolved text request's output (a `kind: 'text'`
+* {@link AgentRequest} — not a decision) as a done event and returns the
+* next {@link AgentStep}. For decisions, resolve with `resolveDecision`
+* (which returns a {@link ChosenEvent}) and apply it with
+* {@link transitionAgentStep} instead — a decision has no output value of
+* its own to feed here.
+*/
+function resolveAgentStep(machine, step, request, output, options) {
+	const [snapshot, actions] = transitionResult(machine, step.snapshot, request, output);
+	return createAgentStep(machine, snapshot, actions, require_events.getRegisteredAgentExecutionOptions(machine, options));
+}
+/**
+* Snapshot in, requests out: scans executable actions for spawned agent
+* invokes and lowers each into an {@link AgentStepRequest}, pre-filled with
+* the machine's registered `setupAgent` schemas/actorSources (so callers
+* don't pass them by hand each call) — merged with any `options` passed here,
+* which take precedence. The step path's public discovery primitive;
+* `initialAgentStep`/`transitionAgentStep`/`resolveAgentStep` call it
+* internally to populate `AgentStep.requests`.
+*/
+function getAgentRequests(machine, actions, snapshot, options = {}) {
+	return getAgentRequestsWith(actions, {
+		...require_events.getRegisteredAgentExecutionOptions(machine, options),
+		...options,
+		snapshot
+	});
+}
+async function executeAgentRequest(request, executors, options) {
+	if (request.kind === "decision") throw new Error("executeAgentRequest(...) is text-only. Resolve a 'decision' request with resolveDecision(request, executors.decide, ...) instead.");
+	assertTextExecutor(request, executors);
+	const { output, raw } = await require_events.executeAgentTextRequest(request.mode ?? "generate", request.id, request.input, executors, request.tools);
+	const normalizedOutput = request.input.outputSchema ? require_events.validateSchemaSync(request.input.outputSchema, output) : output;
+	return options?.verbose ? {
+		output: normalizedOutput,
+		raw
+	} : normalizedOutput;
+}
+/**
+* Resolves the current step's pending requests and returns the next
+* {@link AgentStep} — one iteration of the durable step loop, collapsing the
+* manual `request.kind` dispatch a host would otherwise write by hand.
+*
+* For each pending request, in order: a `kind: 'text'` request is run with
+* {@link executeAgentRequest} then fed back via {@link resolveAgentStep}; a
+* `kind: 'decision'` request is resolved with `resolveDecision` (wiring
+* `canTake` to `step.snapshot.can` so guard-rejected choices retry) then
+* applied with {@link transitionAgentStep}. The **current** step is re-read
+* after each application — the machine may advance and its `requests` change —
+* so this always resolves against the live step, never a stale list.
+*
+* A `kind: 'plan'` request (`agent.plan`) is resolved natively too: one plan
+* step per call. It resolves a single decision from `request.events` (wiring
+* `canTake` to `step.snapshot.can`, exempting the reserved `agent.plan.done`
+* move and `stopOn` events), then either applies the chosen machine event and
+* lets the next step re-surface the plan, or completes the plan (feeding its
+* `{ steps, stopped }` output back) on the done move / a `stopOn` event / an
+* exhausted budget / no legal events. The plan's applied trail is carried in
+* the invoke child's snapshot, so persisting the step between calls resumes the
+* plan identically.
+*
+* Missing the executor a request needs throws a clear error
+* (`generateText`/`streamText` for text, `decide` for decisions and plans).
+*
+* A complete durable host is two lines:
+*
+* ```ts
+* let step = initialAgentStep(machine, input);
+* while (!step.done) step = await resolveAgentRequests(machine, step, executors);
+* ```
+*
+* All pending **text** requests of a step are resolved in parallel
+* (`Promise.all`) — parallel statechart regions are genuinely concurrent, so
+* their model calls run concurrently — then their outputs apply in
+* **request-array order** (deterministic for durable replay regardless of which
+* call finishes first). Decisions and plans stay **one at a time**: applying
+* either changes the set of legal candidates for what follows, so they cannot be
+* resolved against a stale snapshot. A host that instead wants strictly
+* sequential text resolution loops the manual per-request helpers
+* ({@link executeAgentRequest} + {@link resolveAgentStep}) one at a time.
+*/
+async function resolveAgentRequests(machine, step, executors, options) {
+	const [request] = step.requests;
+	if (!request) return step;
+	if (request.kind === "decision") {
+		if (!executors.decide) throw new Error(`this step's decision request '${request.id}' needs a 'decide' executor but none was provided.`);
+		return transitionAgentStep(machine, step, await require_decision.resolveDecision(request, executors.decide, {
+			canTake: (event) => step.snapshot.can(event),
+			maxRetries: options?.maxRetries
+		}), options);
+	}
+	if (request.kind === "plan") return resolvePlanRequest(machine, step, request, executors, options);
+	const textRequests = step.requests.filter((candidate) => candidate.kind === "text");
+	for (const textRequest of textRequests) assertTextExecutor(textRequest, executors);
+	const outputs = await Promise.all(textRequests.map((textRequest) => executeAgentRequest(textRequest, executors)));
+	let next = step;
+	for (let index = 0; index < textRequests.length; index++) next = resolveAgentStep(machine, next, textRequests[index], outputs[index], options);
+	return next;
+}
+function assertTextExecutor(request, executors) {
+	const mode = request.mode ?? "generate";
+	const kind = mode === "stream" ? "streamText" : "generateText";
+	if (!(mode === "stream" ? executors.streamText : executors.generateText)) throw new Error(`this step's text request '${request.src}' needs a '${kind}' executor but none was provided.`);
+}
+async function resolvePlanRequest(machine, step, request, executors, options) {
+	if (!executors.decide) throw new Error(`this step's plan request '${request.src}' needs a 'decide' executor but none was provided.`);
+	const stopOn = new Set(request.input.stopOn ?? []);
+	if (request.stepsRemaining <= 0) return completePlan(machine, step, request.id, request.applied, "max-steps", options);
+	if (request.events.filter((event) => event.type !== "agent.plan.done").length === 0) return completePlan(machine, step, request.id, request.applied, "no-legal-events", options);
+	const chosen = await require_decision.resolveDecision(planStepDecisionRequest(request), executors.decide, {
+		maxRetries: options?.maxRetries,
+		canTake: (event) => {
+			if (event.type === "agent.plan.done" || stopOn.has(event.type)) return true;
+			return step.snapshot.can(event);
+		}
+	});
+	if (chosen.type === "agent.plan.done") return completePlan(machine, step, request.id, request.applied, "done", options);
+	const applied = [...request.applied, chosen];
+	advancePlanChildLedger(step.snapshot, request.id, {
+		type: "plan.applied",
+		event: chosen
+	});
+	const next = transitionAgentStep(machine, step, chosen, options);
+	if (stopOn.has(chosen.type)) {
+		if (isPlanActive(next.snapshot, request.id)) return completePlan(machine, next, request.id, applied, "stop-event", options);
+	}
+	return next;
+}
+function completePlan(machine, step, id, steps, stopped, options) {
+	return resolveAgentStep(machine, step, { id }, {
+		steps,
+		stopped
+	}, options);
+}
+function planStepDecisionRequest(request) {
+	const { input, applied, events, id } = request;
+	const trail = applied.length === 0 ? "" : `\n\nEvents already applied in this plan, in order:\n${applied.map((step) => JSON.stringify(step)).join("\n")}\nContinue from here; do not repeat applied events.`;
+	const doneHint = `\n\nWhen the request is fully handled (or no action is needed), choose '${require_decision.PLAN_DONE_EVENT_TYPE}'.`;
+	return {
+		kind: "decision",
+		id: `${id}[${applied.length}]`,
+		model: input.model,
+		system: input.system,
+		prompt: `${input.prompt ?? ""}${trail}${doneHint}`,
+		messages: input.messages,
+		events,
+		attempts: [],
+		temperature: input.temperature,
+		maxOutputTokens: input.maxOutputTokens,
+		topP: input.topP,
+		topK: input.topK,
+		seed: input.seed,
+		stopSequences: input.stopSequences,
+		metadata: input.metadata
+	};
+}
+function advancePlanChildLedger(snapshot, id, event) {
+	const child = snapshot.children?.[id];
+	const childSnapshot = child?.getSnapshot?.();
+	if (!require_decision.isPlanLogic(child?.logic) || !childSnapshot || typeof childSnapshot !== "object") return;
+	Object.assign(childSnapshot, require_decision.advancePlanLedger(child.logic, childSnapshot, event));
+}
+function isPlanActive(snapshot, id) {
+	return (snapshot.children?.[id])?.getSnapshot?.()?.status === "active";
+}
+function createAgentStep(machine, snapshot, actions, options) {
+	applyFinalStateOutput(machine, snapshot);
+	return {
+		snapshot,
+		actions,
+		requests: getAgentRequestsWith(actions, {
+			...options,
+			snapshot
+		}),
+		done: snapshot.status === "done"
+	};
+}
+function resolveStateValueConfig(config, value) {
+	if (typeof value === "string") return config.states?.[value];
+	if (!value || typeof value !== "object") return;
+	for (const [key, childValue] of Object.entries(value)) {
+		const childConfig = config.states?.[key];
+		if (!childConfig) continue;
+		if (childConfig.type === "final") return childConfig;
+		const nested = resolveStateValueConfig(childConfig, childValue);
+		if (nested) return nested;
+	}
+}
+function applyFinalStateOutput(logic, snapshot, event) {
+	const machineSnapshot = snapshot;
+	if (machineSnapshot.status !== "done" || machineSnapshot.output !== void 0 || !("config" in logic)) return;
+	const config = logic.config;
+	if (!config) return;
+	const output = resolveStateValueConfig(config, machineSnapshot.value)?.output;
+	if (output === void 0) return;
+	machineSnapshot.output = typeof output === "function" ? output({
+		context: machineSnapshot.context,
+		event
+	}) : output;
+}
+function isAgentStep(value) {
+	return !!value && typeof value === "object" && "snapshot" in value && "actions" in value && "requests" in value;
+}
+//#endregion
+Object.defineProperty(exports, "executeAgentRequest", {
+	enumerable: true,
+	get: function() {
+		return executeAgentRequest;
+	}
+});
+Object.defineProperty(exports, "getAgentRequests", {
+	enumerable: true,
+	get: function() {
+		return getAgentRequests;
+	}
+});
+Object.defineProperty(exports, "getInvokeEffectMetadata", {
+	enumerable: true,
+	get: function() {
+		return getInvokeEffectMetadata;
+	}
+});
+Object.defineProperty(exports, "initialAgentStep", {
+	enumerable: true,
+	get: function() {
+		return initialAgentStep;
+	}
+});
+Object.defineProperty(exports, "resolveAgentRequests", {
+	enumerable: true,
+	get: function() {
+		return resolveAgentRequests;
+	}
+});
+Object.defineProperty(exports, "resolveAgentStep", {
+	enumerable: true,
+	get: function() {
+		return resolveAgentStep;
+	}
+});
+Object.defineProperty(exports, "transitionAgentStep", {
+	enumerable: true,
+	get: function() {
+		return transitionAgentStep;
+	}
+});