@statelyai/agent 2.0.0-alpha.18 → 2.0.0-alpha.19

package/dist/validate.cjs

@@ -0,0 +1,436 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+let ajv_dist_2020_js = require("ajv/dist/2020.js");
+ajv_dist_2020_js = __toESM(ajv_dist_2020_js);
+//#region schemas/agent-workflow.json
+var agent_workflow_default = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "https://stately.ai/schemas/agent-workflow.json",
+	title: "Stately Agent Workflow Definition",
+	description: "Static, declarative agent workflow definition that can be lowered to a setupAgent(...) XState machine.",
+	type: "object",
+	required: ["initial", "states"],
+	properties: {
+		"$schema": {
+			"description": "JSON Schema reference an editor attaches to the config file. Ignored by the lowering.",
+			"type": "string"
+		},
+		"key": {
+			"description": "Stable workflow key used by tools, storage, and visual editors.",
+			"type": "string",
+			"minLength": 1
+		},
+		"id": {
+			"description": "Optional XState machine id.",
+			"type": "string",
+			"minLength": 1
+		},
+		"version": {
+			"description": "Definition version chosen by the author.",
+			"type": "string"
+		},
+		"description": { "type": "string" },
+		"schemas": { "$ref": "#/$defs/AgentSchemas" },
+		"context": {
+			"description": "Initial XState context. Values may be JSON literals or whole-string {{ }} expressions evaluated with machine input.",
+			"$ref": "#/$defs/ExpressionObject"
+		},
+		"requests": {
+			"description": "Named model requests that become typed invoke sources.",
+			"type": "object",
+			"propertyNames": { "$ref": "#/$defs/Identifier" },
+			"additionalProperties": { "$ref": "#/$defs/Request" },
+			"default": {}
+		},
+		"actors": {
+			"description": "Placeholder actor sources declared by key. JSON wires no execution; provide the logic via machine.provide({ actors }) after setupAgent.fromConfig(...).",
+			"type": "object",
+			"propertyNames": { "$ref": "#/$defs/Identifier" },
+			"additionalProperties": { "$ref": "#/$defs/Actor" },
+			"default": {}
+		},
+		"initial": {
+			"description": "Initial child state key.",
+			"type": "string"
+		},
+		"states": {
+			"description": "Root state nodes.",
+			"type": "object",
+			"minProperties": 1,
+			"propertyNames": { "$ref": "#/$defs/Identifier" },
+			"additionalProperties": { "$ref": "#/$defs/State" }
+		},
+		"idleTags": {
+			"description": "State tags that mark an intentional wait for an external event (a human approval, an inbound webhook, ...). Lowered by setupAgent.fromConfig(...) into a snapshot.hasTag(...) idle predicate so runAgent settles those states idle deterministically. Every listed tag must appear in some state's 'tags'.",
+			"type": "array",
+			"items": {
+				"type": "string",
+				"minLength": 1
+			}
+		},
+		"meta": { "$ref": "#/$defs/JsonObject" }
+	},
+	additionalProperties: false,
+	$defs: {
+		"Identifier": {
+			"type": "string",
+			"minLength": 1,
+			"pattern": "^[A-Za-z_$][A-Za-z0-9_$.-]*$"
+		},
+		"ExpressionString": {
+			"description": "Whole-string expression delimited by {{ }}.",
+			"type": "string",
+			"pattern": "^\\{\\{[\\s\\S]*\\}\\}$"
+		},
+		"TemplateString": {
+			"description": "String that may contain {{ }} template expressions. Escape literal delimiters according to the selected expression/template evaluator.",
+			"type": "string"
+		},
+		"JsonValue": { "anyOf": [
+			{ "type": "null" },
+			{ "type": "boolean" },
+			{ "type": "number" },
+			{ "type": "string" },
+			{
+				"type": "array",
+				"items": { "$ref": "#/$defs/JsonValue" }
+			},
+			{ "$ref": "#/$defs/JsonObject" }
+		] },
+		"JsonObject": {
+			"type": "object",
+			"propertyNames": { "type": "string" },
+			"additionalProperties": { "$ref": "#/$defs/JsonValue" }
+		},
+		"ExpressionValue": {
+			"description": "JSON value or whole-string {{ }} expression. Use this for typed values, not prompt templating.",
+			"anyOf": [
+				{ "$ref": "#/$defs/ExpressionString" },
+				{ "type": "null" },
+				{ "type": "boolean" },
+				{ "type": "number" },
+				{ "type": "string" },
+				{
+					"type": "array",
+					"items": { "$ref": "#/$defs/ExpressionValue" }
+				},
+				{
+					"type": "object",
+					"propertyNames": { "type": "string" },
+					"additionalProperties": { "$ref": "#/$defs/ExpressionValue" }
+				}
+			]
+		},
+		"ExpressionObject": {
+			"type": "object",
+			"propertyNames": { "type": "string" },
+			"additionalProperties": { "$ref": "#/$defs/ExpressionValue" }
+		},
+		"JsonSchema": {
+			"description": "JSON Schema object.",
+			"type": "object",
+			"propertyNames": { "type": "string" },
+			"additionalProperties": true
+		},
+		"AgentSchemas": {
+			"type": "object",
+			"properties": {
+				"input": { "$ref": "#/$defs/JsonSchema" },
+				"context": { "$ref": "#/$defs/JsonSchema" },
+				"events": {
+					"type": "object",
+					"propertyNames": { "$ref": "#/$defs/Identifier" },
+					"additionalProperties": { "$ref": "#/$defs/JsonSchema" }
+				},
+				"emitted": {
+					"type": "object",
+					"description": "Schemas for events emitted outward by emit actions, keyed by emitted event type.",
+					"propertyNames": { "$ref": "#/$defs/Identifier" },
+					"additionalProperties": { "$ref": "#/$defs/JsonSchema" }
+				},
+				"output": { "$ref": "#/$defs/JsonSchema" },
+				"meta": { "$ref": "#/$defs/JsonSchema" }
+			},
+			"additionalProperties": false
+		},
+		"Request": {
+			"type": "object",
+			"required": [
+				"model",
+				"input",
+				"output"
+			],
+			"properties": {
+				"mode": {
+					"type": "string",
+					"enum": ["generate", "stream"],
+					"default": "generate"
+				},
+				"description": { "type": "string" },
+				"model": { "$ref": "#/$defs/TemplateString" },
+				"system": { "$ref": "#/$defs/TemplateString" },
+				"prompt": { "$ref": "#/$defs/TemplateString" },
+				"messages": { "anyOf": [{ "$ref": "#/$defs/ExpressionString" }, {
+					"type": "array",
+					"items": { "$ref": "#/$defs/Message" }
+				}] },
+				"input": { "$ref": "#/$defs/JsonSchema" },
+				"output": { "$ref": "#/$defs/JsonSchema" },
+				"tools": {
+					"type": "object",
+					"propertyNames": { "$ref": "#/$defs/Identifier" },
+					"additionalProperties": { "$ref": "#/$defs/Tool" }
+				},
+				"toolChoice": {
+					"description": "Passed to the provider as-is; unlike other request fields it is NOT template-evaluated, so {{ }} expressions are not allowed here.",
+					"anyOf": [{
+						"type": "string",
+						"enum": [
+							"auto",
+							"none",
+							"required"
+						]
+					}, {
+						"type": "object",
+						"required": ["type", "name"],
+						"properties": {
+							"type": { "const": "tool" },
+							"name": { "$ref": "#/$defs/Identifier" }
+						},
+						"additionalProperties": false
+					}]
+				},
+				"reasoning": {
+					"description": "Opt into the structured-output envelope's `reasoning` field.",
+					"type": "boolean"
+				},
+				"temperature": { "$ref": "#/$defs/ExpressionValue" },
+				"maxOutputTokens": { "$ref": "#/$defs/ExpressionValue" },
+				"topP": { "$ref": "#/$defs/ExpressionValue" },
+				"topK": { "$ref": "#/$defs/ExpressionValue" },
+				"seed": { "$ref": "#/$defs/ExpressionValue" },
+				"stopSequences": { "anyOf": [{ "$ref": "#/$defs/ExpressionString" }, {
+					"type": "array",
+					"items": { "type": "string" }
+				}] },
+				"metadata": { "$ref": "#/$defs/ExpressionValue" }
+			},
+			"additionalProperties": false
+		},
+		"Message": {
+			"type": "object",
+			"required": ["role", "content"],
+			"properties": {
+				"role": { "$ref": "#/$defs/TemplateString" },
+				"content": { "$ref": "#/$defs/TemplateString" }
+			},
+			"additionalProperties": { "$ref": "#/$defs/ExpressionValue" }
+		},
+		"Actor": {
+			"description": "A placeholder actor source: schemas describe it for authors/editors; the implementation is provided by the host.",
+			"type": "object",
+			"properties": {
+				"description": { "type": "string" },
+				"input": { "$ref": "#/$defs/JsonSchema" },
+				"output": { "$ref": "#/$defs/JsonSchema" }
+			},
+			"additionalProperties": false
+		},
+		"Tool": {
+			"type": "object",
+			"properties": {
+				"description": { "type": "string" },
+				"inputSchema": { "$ref": "#/$defs/JsonSchema" },
+				"outputSchema": { "$ref": "#/$defs/JsonSchema" }
+			},
+			"additionalProperties": { "$ref": "#/$defs/JsonValue" }
+		},
+		"State": {
+			"type": "object",
+			"properties": {
+				"description": { "type": "string" },
+				"type": {
+					"type": "string",
+					"enum": [
+						"parallel",
+						"history",
+						"final",
+						"choice"
+					]
+				},
+				"initial": { "type": "string" },
+				"states": {
+					"type": "object",
+					"propertyNames": { "$ref": "#/$defs/Identifier" },
+					"additionalProperties": { "$ref": "#/$defs/State" }
+				},
+				"invoke": { "anyOf": [{ "$ref": "#/$defs/Invoke" }, {
+					"type": "array",
+					"items": { "$ref": "#/$defs/Invoke" }
+				}] },
+				"choice": {
+					"description": "Choice-state routing, equivalent to XState's type: 'choice' + choice transition function.",
+					"$ref": "#/$defs/TransitionOrArray"
+				},
+				"on": {
+					"type": "object",
+					"propertyNames": { "type": "string" },
+					"additionalProperties": { "$ref": "#/$defs/TransitionOrArray" }
+				},
+				"always": { "$ref": "#/$defs/TransitionOrArray" },
+				"onDone": { "$ref": "#/$defs/TransitionOrArray" },
+				"after": {
+					"type": "object",
+					"propertyNames": { "type": "string" },
+					"additionalProperties": { "$ref": "#/$defs/TransitionOrArray" }
+				},
+				"entry": { "$ref": "#/$defs/ActionOrArray" },
+				"exit": { "$ref": "#/$defs/ActionOrArray" },
+				"tags": {
+					"type": "array",
+					"items": { "type": "string" }
+				},
+				"output": { "$ref": "#/$defs/ExpressionValue" },
+				"meta": {
+					"description": "Static state metadata, passed through verbatim. Not template-evaluated.",
+					"$ref": "#/$defs/JsonObject"
+				}
+			},
+			"additionalProperties": false
+		},
+		"Invoke": {
+			"type": "object",
+			"required": ["src"],
+			"properties": {
+				"id": { "type": "string" },
+				"src": {
+					"description": "Actor source name. 'agent.decide' invokes are special: decision delivery is automatic (the chosen event is sent as soon as the model decides) and 'onDone' must be omitted — see the 'onDone' description.",
+					"$ref": "#/$defs/Identifier"
+				},
+				"input": { "$ref": "#/$defs/ExpressionValue" },
+				"onDone": {
+					"description": "Not valid on an 'agent.decide' invoke — the built-in lowering rejects it at setupAgent.fromConfig(...) time. A decision has no output value of its own (its output IS the chosen event), so delivery is automatic and not configurable from JSON. 'onError' (retries exhausted) still applies to 'agent.decide' invokes.",
+					"$ref": "#/$defs/TransitionOrArray"
+				},
+				"onError": { "$ref": "#/$defs/TransitionOrArray" }
+			},
+			"additionalProperties": false
+		},
+		"TransitionOrArray": { "anyOf": [{ "$ref": "#/$defs/Transition" }, {
+			"type": "array",
+			"items": { "$ref": "#/$defs/Transition" }
+		}] },
+		"Transition": {
+			"type": "object",
+			"properties": {
+				"target": { "anyOf": [{ "type": "string" }, {
+					"type": "array",
+					"items": { "type": "string" }
+				}] },
+				"guard": {
+					"description": "Either a whole-string {{ }} expression evaluated as truthy/falsy, or a named guard reference resolved against the `guards` passed to setupAgent.fromConfig(config, { guards }). Object guards ({ type, params }) are rejected by the lowering.",
+					"anyOf": [{ "$ref": "#/$defs/ExpressionString" }, { "$ref": "#/$defs/Identifier" }]
+				},
+				"assign": {
+					"description": "Context assignments applied when this transition is taken.",
+					"$ref": "#/$defs/ExpressionObject"
+				},
+				"actions": { "$ref": "#/$defs/ActionOrArray" },
+				"description": { "type": "string" },
+				"reenter": { "type": "boolean" },
+				"meta": {
+					"description": "Static transition metadata, passed through verbatim. Not template-evaluated.",
+					"$ref": "#/$defs/JsonObject"
+				}
+			},
+			"additionalProperties": false
+		},
+		"ActionOrArray": { "anyOf": [{ "$ref": "#/$defs/Action" }, {
+			"type": "array",
+			"items": { "$ref": "#/$defs/Action" }
+		}] },
+		"Action": {
+			"type": "object",
+			"properties": {
+				"type": { "type": "string" },
+				"params": { "$ref": "#/$defs/ExpressionValue" },
+				"assign": { "$ref": "#/$defs/ExpressionObject" },
+				"emit": {
+					"description": "Event emitted outward through runAgent's on handlers.",
+					"$ref": "#/$defs/ExpressionValue"
+				}
+			},
+			"anyOf": [
+				{ "required": ["type"] },
+				{ "required": ["assign"] },
+				{ "required": ["emit"] }
+			],
+			"additionalProperties": { "$ref": "#/$defs/ExpressionValue" }
+		}
+	}
+};
+//#endregion
+//#region src/validate/index.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.
+*/
+let compiledWorkflowValidator;
+function getWorkflowValidator() {
+	if (!compiledWorkflowValidator) compiledWorkflowValidator = new ajv_dist_2020_js.default({
+		strict: false,
+		allowUnionTypes: true,
+		allErrors: true
+	}).compile(agent_workflow_default);
+	return compiledWorkflowValidator;
+}
+/**
+* Validates a value against the shipped `schemas/agent-workflow.json` before
+* you hand it to `setupAgent(...).fromConfig(...)`. Returns diagnostics rather
+* than throwing; `valid: true` means the config is structurally sound (it does
+* not check that named guards/actions/actors are implemented, which
+* `fromConfig` does). The compiled validator is cached across calls.
+*/
+function validateAgentConfig(config) {
+	const validate = getWorkflowValidator();
+	if (validate(config)) return {
+		valid: true,
+		errors: []
+	};
+	return {
+		valid: false,
+		errors: (validate.errors ?? []).map((error) => ({
+			severity: "error",
+			path: error.instancePath || "/",
+			message: error.message ?? "is invalid",
+			keyword: error.keyword
+		}))
+	};
+}
+//#endregion
+exports.__toESM = __toESM;
+exports.validateAgentConfig = validateAgentConfig;

package/dist/validate.d.cts

@@ -0,0 +1,31 @@
+//#region src/validate/index.d.ts
+/**
+ * One schema-validation finding from {@link validateAgentConfig}. `path` is a
+ * JSON Pointer into the config (`/states/idle/invoke`, `/` for the root) and
+ * `message` explains what the schema rejected. Mirrors the shape of
+ * `AgentLintDiagnostic` so config validation and machine linting report the
+ * same way.
+ */
+interface AgentConfigDiagnostic {
+  severity: "error";
+  /** JSON Pointer into the config (`/` for the root). */
+  path: string;
+  message: string;
+  /** The schema keyword that failed (`required`, `type`, `enum`, ...). */
+  keyword: string;
+}
+/** Result of {@link validateAgentConfig}. */
+interface AgentConfigValidationResult {
+  valid: boolean;
+  errors: AgentConfigDiagnostic[];
+}
+/**
+ * Validates a value against the shipped `schemas/agent-workflow.json` before
+ * you hand it to `setupAgent(...).fromConfig(...)`. Returns diagnostics rather
+ * than throwing; `valid: true` means the config is structurally sound (it does
+ * not check that named guards/actions/actors are implemented, which
+ * `fromConfig` does). The compiled validator is cached across calls.
+ */
+declare function validateAgentConfig(config: unknown): AgentConfigValidationResult;
+//#endregion
+export { AgentConfigDiagnostic, AgentConfigValidationResult, validateAgentConfig };

package/dist/validate.d.mts

@@ -0,0 +1,31 @@
+//#region src/validate/index.d.ts
+/**
+ * One schema-validation finding from {@link validateAgentConfig}. `path` is a
+ * JSON Pointer into the config (`/states/idle/invoke`, `/` for the root) and
+ * `message` explains what the schema rejected. Mirrors the shape of
+ * `AgentLintDiagnostic` so config validation and machine linting report the
+ * same way.
+ */
+interface AgentConfigDiagnostic {
+  severity: "error";
+  /** JSON Pointer into the config (`/` for the root). */
+  path: string;
+  message: string;
+  /** The schema keyword that failed (`required`, `type`, `enum`, ...). */
+  keyword: string;
+}
+/** Result of {@link validateAgentConfig}. */
+interface AgentConfigValidationResult {
+  valid: boolean;
+  errors: AgentConfigDiagnostic[];
+}
+/**
+ * Validates a value against the shipped `schemas/agent-workflow.json` before
+ * you hand it to `setupAgent(...).fromConfig(...)`. Returns diagnostics rather
+ * than throwing; `valid: true` means the config is structurally sound (it does
+ * not check that named guards/actions/actors are implemented, which
+ * `fromConfig` does). The compiled validator is cached across calls.
+ */
+declare function validateAgentConfig(config: unknown): AgentConfigValidationResult;
+//#endregion
+export { AgentConfigDiagnostic, AgentConfigValidationResult, validateAgentConfig };