@statelyai/agent 2.0.0-alpha.28 → 2.0.0-alpha.30

package/dist/validate.mjs

@@ -1,3 +1,6 @@
+import { D as STREAM_TEXT_ACTOR, E as GENERATE_TEXT_ACTOR, T as DECIDE_ACTOR } from "./event-log-DJCMHek_.mjs";
+import { i as setupAgentFromConfig } from "./setup-agent-7rV_cujV.mjs";
+import { a as explorePaths, o as lintAgentMachine } from "./verify-COFWyprJ.mjs";
 import Ajv2020 from "ajv/dist/2020.js";
 //#region schemas/agent-workflow.json
 var agent_workflow_default = {
@@ -359,13 +362,10 @@ var agent_workflow_default = {
 	}
 };
 //#endregion
-//#region src/validate/index.ts
+//#region src/validate/validate-config.ts
 /**
-* Schema validation for agent workflow configs.
-*
-* Lives behind the `@statelyai/agent/validate` subpath so the core package
-* stays dependency-free. This module imports `ajv`, which is declared as an
-* optional peer dependency.
+* Schema validation for agent workflow configs. Imports `ajv`, an optional
+* peer dependency of the package.
 */
 let compiledWorkflowValidator;
 function getWorkflowValidator() {
@@ -400,4 +400,235 @@ function validateAgentConfig(config) {
 	};
 }
 //#endregion
-export { validateAgentConfig };
+//#region src/validate/verify-config.ts
+const BUILTIN_SRCS = [
+	DECIDE_ACTOR,
+	GENERATE_TEXT_ACTOR,
+	STREAM_TEXT_ACTOR
+];
+const MAX_DETAIL_LINES = 10;
+/**
+* Runs every pre-run gate on a model-authored workflow config and stops at
+* the first failure. Never throws on a bad config: each failure becomes a gate
+* record whose `detail` is a repair prompt.
+*
+* - `validate`: the config's shape, against the shipped JSON Schema.
+* - `vocabulary`: names the config references, against `allow`.
+* - `lower`: `setupAgent.fromConfig` (unresolved guards/actions, bad targets).
+* - `lint`: `lintAgentMachine` (errors fail; warnings fail with `lint.warnings`).
+* - `explore`: `explorePaths` from each `explore.inputs` entry; every terminal
+*   must be one of `explore.terminals`, no cap (`maxPaths`, `maxNodes`) may cut
+*   it short, every event's payloads must be tried (`unexpandedEvents`), and
+*   every reached text request or invoke needs an `explore.outputs` entry.
+*
+* @example
+* ```ts
+* const result = await verifyAgentConfig(candidate, { compileSchema, allow: { events: ["APPROVE", "DENY"] } });
+* const failed = result.gates.find((gate) => !gate.ok);
+* if (failed) feedback.push(`gate '${failed.name}' failed: ${failed.detail}`);
+* ```
+*/
+async function verifyAgentConfig(config, options) {
+	const gates = [];
+	const record = (name, problems, notes = []) => {
+		const lines = problems.length ? problems : notes;
+		gates.push({
+			name,
+			ok: problems.length === 0,
+			...lines.length ? { detail: formatDetail(lines) } : {}
+		});
+		return problems.length === 0;
+	};
+	const fail = (extra = {}) => ({
+		ok: false,
+		gates,
+		...extra
+	});
+	if (!record("validate", validateAgentConfig(config).errors.map((error) => `${error.path} ${error.message}`))) return fail();
+	const typed = config;
+	if (options.allow && !record("vocabulary", checkVocabulary(typed, options.allow))) return fail({ config: typed });
+	let machine;
+	try {
+		machine = setupAgentFromConfig(typed, {
+			compileSchema: options.compileSchema,
+			...options.guards ? { guards: options.guards } : {},
+			...options.actions ? { actions: options.actions } : {}
+		}).machine;
+		if (options.actors) machine = machine.provide({ actors: options.actors });
+	} catch (error) {
+		record("lower", [errorMessage(error)]);
+		return fail({ config: typed });
+	}
+	record("lower", []);
+	const diagnostics = lintAgentMachine(machine).map((d) => ({
+		failing: d.severity === "error" || options.lint?.warnings === true,
+		line: `${d.severity} ${d.code} at '${d.path}': ${d.message}`
+	}));
+	if (!record("lint", diagnostics.filter((d) => d.failing).map((d) => d.line), diagnostics.map((d) => d.line))) return fail({
+		config: typed,
+		machine
+	});
+	if (options.explore && !record("explore", await checkExplore(machine, options.explore))) return fail({
+		config: typed,
+		machine
+	});
+	return {
+		ok: true,
+		gates,
+		config: typed,
+		machine
+	};
+}
+/** A config's `T | T[]` field as a list of objects. */
+const nodes = (value) => (value === void 0 ? [] : Array.isArray(value) ? value : [value]).filter((node) => !!node && typeof node === "object");
+const hasTemplate = (value) => typeof value === "string" && value.includes("{{");
+const list = (names) => names.length ? names.join(", ") : "(none)";
+/** Every state in the config, depth-first, with its dotted path. */
+function walkStates(states, prefix = "") {
+	if (!states || typeof states !== "object") return [];
+	return Object.entries(states).flatMap(([key, state]) => {
+		const path = prefix ? `${prefix}.${key}` : key;
+		return [{
+			path,
+			state
+		}, ...walkStates(state?.states, path)];
+	});
+}
+/** Every transition on a state: `on`, `after`, `always`, `choice`, `onDone`, and invoke done/error. */
+function transitionsOf(state) {
+	return [
+		...Object.values(state.on ?? {}).flatMap(nodes),
+		...Object.values(state.after ?? {}).flatMap(nodes),
+		...nodes(state.always),
+		...nodes(state.choice),
+		...nodes(state.onDone),
+		...nodes(state.invoke).flatMap((invoke) => [...nodes(invoke.onDone), ...nodes(invoke.onError)])
+	];
+}
+/**
+* Paths of raw xstate expression slots (`{ "@expr": ... }`, `{ "@code": ... }`).
+* xstate evaluates such an object whole, ignoring its literal siblings, so a
+* slot would hide the model ref or `allowedEvents` the checks below read.
+*/
+function rawExpressionPaths(value, path) {
+	if (Array.isArray(value)) return value.flatMap((item, index) => rawExpressionPaths(item, `${path}[${index}]`));
+	if (!value || typeof value !== "object") return [];
+	const node = value;
+	if (typeof node["@expr"] === "string" || typeof node["@code"] === "string") return [path];
+	return Object.entries(node).flatMap(([key, item]) => rawExpressionPaths(item, path ? `${path}.${key}` : key));
+}
+function checkVocabulary(config, allow) {
+	const problems = rawExpressionPaths(config, "").map((path) => `${path || "(root)"} uses a raw '@expr' slot, which the vocabulary cannot check; write {{ }} templates instead`);
+	const checkModel = (where, model) => {
+		if (!allow.models) return;
+		if (typeof model !== "string" || hasTemplate(model)) problems.push(`${where} needs a literal string model ref; allowed: ${list(allow.models)}`);
+		else if (!allow.models.includes(model)) problems.push(`${where} uses model '${model}'; allowed: ${list(allow.models)}`);
+	};
+	for (const [kind, declared, allowed] of [[
+		"request",
+		config.requests,
+		allow.requests
+	], [
+		"actor",
+		config.actors,
+		allow.actors
+	]]) {
+		if (!allowed) continue;
+		for (const key of Object.keys(declared ?? {})) if (!allowed.includes(key)) problems.push(`${kind} '${key}' is not in the vocabulary; allowed: ${list(allowed)}`);
+	}
+	for (const [key, request] of Object.entries(config.requests ?? {})) checkModel(`request '${key}'`, request.model);
+	const srcs = allow.actors ? [
+		...BUILTIN_SRCS,
+		...allow.actors,
+		...allow.requests ?? Object.keys(config.requests ?? {})
+	] : void 0;
+	for (const { path, state } of walkStates(config.states)) {
+		for (const invoke of nodes(state.invoke)) {
+			const src = String(invoke.src);
+			if (srcs && !srcs.includes(src)) {
+				problems.push(`state '${path}' invokes unknown src '${src}'; allowed: ${list(srcs)}`);
+				continue;
+			}
+			if (!BUILTIN_SRCS.includes(src)) continue;
+			const input = invoke.input;
+			if ((allow.models || src === "agent.decide" && allow.events) && !isPlainObject(input)) {
+				problems.push(`state '${path}': '${src}' input must be a literal object`);
+				continue;
+			}
+			checkModel(`state '${path}': '${src}'`, input?.model);
+			if (src !== "agent.decide" || !allow.events) continue;
+			const allowedEvents = input.allowedEvents;
+			if (!Array.isArray(allowedEvents) || allowedEvents.length === 0) {
+				problems.push(`state '${path}': agent.decide needs a literal, non-empty allowedEvents list; allowed: ${list(allow.events)}`);
+				continue;
+			}
+			for (const type of allowedEvents) if (typeof type !== "string" || !allow.events.includes(type)) problems.push(`state '${path}': agent.decide allowedEvents entry '${String(type)}' is not allowed; allowed: ${list(allow.events)}`);
+		}
+		const actionsAt = [["entry", state.entry], ["exit", state.exit]];
+		for (const transition of transitionsOf(state)) {
+			const guard = transition.guard;
+			if (allow.guards && typeof guard === "string" && !hasTemplate(guard) && !allow.guards.includes(guard)) problems.push(`state '${path}' uses unknown named guard '${guard}'; allowed: ${list(allow.guards)}`);
+			actionsAt.push(["a transition", transition.actions]);
+		}
+		if (!allow.actions) continue;
+		for (const [where, actions] of actionsAt) for (const action of nodes(actions)) if (typeof action.type === "string" && !allow.actions.includes(action.type)) problems.push(`state '${path}' ${where} uses unknown named action '${action.type}'; allowed: ${list(allow.actions)}`);
+	}
+	return problems;
+}
+const isPlainObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+async function checkExplore(machine, options) {
+	const { inputs, terminals = ["done"], ...rest } = options;
+	if (inputs.length === 0) return ["explore.inputs is empty, so no path was explored; give at least one input"];
+	const allowed = terminals;
+	const maxDepth = options.maxDepth ?? 8;
+	const problems = /* @__PURE__ */ new Set();
+	for (const [index, input] of inputs.entries()) {
+		const at = inputs.length > 1 ? `input ${index}: ` : "";
+		let report;
+		try {
+			report = await explorePaths(machine, {
+				...rest,
+				input
+			});
+		} catch (error) {
+			problems.add(`${at}exploration threw: ${errorMessage(error)}`);
+			continue;
+		}
+		for (const terminal of report.terminals) {
+			if (allowed.includes(terminal.status)) continue;
+			const trail = `path [${terminal.path.map((event) => event.type).join(", ")}]`;
+			const state = JSON.stringify(terminal.state);
+			switch (terminal.status) {
+				case "max-depth":
+					problems.add(`${at}${trail} hit maxDepth ${maxDepth} in state ${state} without ending; the workflow may loop`);
+					break;
+				case "needs-output":
+					problems.add(`${at}${trail} reached '${terminal.missingSrc}' in state ${state}, which has no output to explore with; add an explore.outputs entry for it`);
+					break;
+				case "error":
+					problems.add(`${at}${trail} errored in state ${state} with no onError: ${errorMessage(terminal.error)}`);
+					break;
+				default: problems.add(`${at}${trail} ends '${terminal.status}' in state ${state}; every path must end ${allowed.map((t) => `'${t}'`).join(" or ")}`);
+			}
+		}
+		if (report.hitPathCap) problems.add(`${at}a cap (maxPaths ${options.maxPaths ?? 200} or maxNodes ${options.maxNodes ?? 1e5}) cut exploration short; the workflow branches too much to verify`);
+		if (report.unexpandedEvents.length > 0) problems.add(`${at}explore did not try every payload of: ${report.unexpandedEvents.join(", ")}; add explore.payloads entries for them`);
+	}
+	return [...problems];
+}
+function formatDetail(lines) {
+	const shown = lines.slice(0, MAX_DETAIL_LINES);
+	const hidden = lines.length - shown.length;
+	return [...shown, ...hidden > 0 ? [`(${hidden} more)`] : []].join("\n");
+}
+function errorMessage(error) {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	try {
+		return JSON.stringify(error);
+	} catch {
+		return String(error);
+	}
+}
+//#endregion
+export { validateAgentConfig, verifyAgentConfig };