@statelyai/agent 2.0.0-alpha.10 → 2.0.0-alpha.12

package/schemas/agent-workflow.json

@@ -6,6 +6,10 @@
   "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",
@@ -23,11 +27,6 @@
     "description": {
       "type": "string"
     },
-    "queryLanguage": {
-      "description": "Expression language used inside {{ }} expressions. The built-in setupAgent.fromConfig lowering currently supports simple dot-path expressions over input, context, and event.",
-      "type": "string",
-      "default": "path"
-    },
     "schemas": {
       "$ref": "#/$defs/AgentSchemas"
     },
@@ -46,6 +45,17 @@
       },
       "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"
@@ -234,6 +244,7 @@
           }
         },
         "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",
@@ -251,10 +262,13 @@
                 }
               },
               "additionalProperties": false
-            },
-            { "$ref": "#/$defs/ExpressionString" }
+            }
           ]
         },
+        "reasoning": {
+          "description": "Opt into the structured-output envelope's `reasoning` field.",
+          "type": "boolean"
+        },
         "temperature": {
           "$ref": "#/$defs/ExpressionValue"
         },
@@ -302,7 +316,8 @@
         "$ref": "#/$defs/ExpressionValue"
       }
     },
-    "Tool": {
+    "Actor": {
+      "description": "A placeholder actor source: schemas describe it for authors/editors; the implementation is provided by the host.",
       "type": "object",
       "properties": {
         "description": {
@@ -315,6 +330,21 @@
           "$ref": "#/$defs/JsonSchema"
         }
       },
+      "additionalProperties": false
+    },
+    "Tool": {
+      "type": "object",
+      "properties": {
+        "description": {
+          "type": "string"
+        },
+        "inputSchema": {
+          "$ref": "#/$defs/JsonSchema"
+        },
+        "outputSchema": {
+          "$ref": "#/$defs/JsonSchema"
+        }
+      },
       "additionalProperties": {
         "$ref": "#/$defs/JsonValue"
       }
@@ -396,7 +426,8 @@
           "$ref": "#/$defs/ExpressionValue"
         },
         "meta": {
-          "$ref": "#/$defs/ExpressionObject"
+          "description": "Static state metadata, passed through verbatim. Not template-evaluated.",
+          "$ref": "#/$defs/JsonObject"
         }
       },
       "additionalProperties": false
@@ -421,9 +452,6 @@
         },
         "onError": {
           "$ref": "#/$defs/TransitionOrArray"
-        },
-        "meta": {
-          "$ref": "#/$defs/ExpressionObject"
         }
       },
       "additionalProperties": false
@@ -454,21 +482,10 @@
           ]
         },
         "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" },
-            {
-              "type": "object",
-              "required": ["type"],
-              "properties": {
-                "type": {
-                  "type": "string"
-                },
-                "params": {
-                  "$ref": "#/$defs/ExpressionValue"
-                }
-              },
-              "additionalProperties": false
-            }
+            { "$ref": "#/$defs/Identifier" }
           ]
         },
         "assign": {
@@ -485,7 +502,8 @@
           "type": "boolean"
         },
         "meta": {
-          "$ref": "#/$defs/ExpressionObject"
+          "description": "Static transition metadata, passed through verbatim. Not template-evaluated.",
+          "$ref": "#/$defs/JsonObject"
         }
       },
       "additionalProperties": false

package/skills/generate-machine/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: generate-machine
+description: Author a @statelyai/agent workflow as JSON and check it before it runs. Use when asked to generate or author an agent machine, create a workflow config, write an AgentWorkflowConfig, or produce an LLM-authored state machine for an agent — and when a generated config fails Ajv validation or agent lint and needs repair.
+---
+
+# Generate an agent machine
+
+An agent machine is data. You author a JSON `AgentWorkflowConfig`, then run it through gates that all work with no API key: Ajv → `fromConfig` → lint → simulate. Do not hand back a config that has not passed all four.
+
+```
+author → validate (Ajv 2020) → lower (fromConfig) → lint (assertAgentMachine) → simulate → hand back
+```
+
+## 1. Read the schema
+
+The config shape is fixed by a shipped JSON Schema. Read it first; it is the contract.
+
+- Consuming the package: `node_modules/@statelyai/agent/agent-workflow.json` (importable as `@statelyai/agent/agent-workflow.json`)
+- In the `statelyai/agent` repo: `schemas/agent-workflow.json`
+
+## 2. Author the config
+
+Rules the runtime enforces. Each one maps to a build error or a lint diagnostic:
+
+- Every value is a JSON literal or a whole-string `"{{ }}"` expression reading a dot path on `input`, `context`, or `event`. No JavaScript.
+- Guard expressions are truthy-only: no comparisons, operators, or negation.
+- A model call is either a named `requests` entry invoked with `src: "<requestName>"`, or an inline invoke with `src: "agent.decide"` plus an `allowedEvents` list.
+- A state invoking `agent.decide` MUST handle every allowed event in its `on`.
+- An `agent.decide` invoke has no `onDone` (a decision produces no output). Use `onError` for the retries-exhausted path.
+- A request invoke reads its result via `onDone.assign` from `"{{ event.output.<field> }}"`.
+- Every path must reach a `"type": "final"` state, and each final state needs an `output` when `schemas.output` is declared.
+- Do not invent guard or action names. Only `"{{ }}"` guards, `assign`, and `emit` exist unless the host tells you which named guards/actions it implements.
+- Model refs are strings (`"openai/gpt-5.4-mini"`); the host resolves them.
+
+Reference config — decision, text request, idle human step, one final state:
+
+```json
+{
+  "id": "support-ticket",
+  "schemas": {
+    "input": {
+      "type": "object",
+      "properties": { "ticket": { "type": "string" } },
+      "required": ["ticket"]
+    },
+    "context": {
+      "type": "object",
+      "properties": {
+        "ticket": { "type": "string" },
+        "reply": { "type": "string" },
+        "resolution": { "type": "string" }
+      },
+      "required": ["ticket"]
+    },
+    "events": {
+      "ESCALATE": {
+        "type": "object",
+        "properties": { "reason": { "type": "string" } },
+        "required": ["reason"]
+      },
+      "REPLY": { "type": "object", "properties": {} },
+      "APPROVE": { "type": "object", "properties": {} },
+      "REJECT": { "type": "object", "properties": {} }
+    },
+    "output": {
+      "type": "object",
+      "properties": { "resolution": { "type": "string" }, "reply": { "type": "string" } },
+      "required": ["resolution"]
+    }
+  },
+  "context": { "ticket": "{{ input.ticket }}" },
+  "requests": {
+    "draftReply": {
+      "model": "openai/gpt-5.4-mini",
+      "system": "Draft a short, courteous support reply.",
+      "prompt": "{{ context.ticket }}",
+      "input": {
+        "type": "object",
+        "properties": { "ticket": { "type": "string" } },
+        "required": ["ticket"]
+      },
+      "output": {
+        "type": "object",
+        "properties": { "reply": { "type": "string" } },
+        "required": ["reply"]
+      }
+    }
+  },
+  "initial": "triaging",
+  "states": {
+    "triaging": {
+      "invoke": {
+        "id": "triageDecision",
+        "src": "agent.decide",
+        "input": {
+          "model": "openai/gpt-5.4-mini",
+          "system": "Decide whether this ticket needs escalation or a drafted reply.",
+          "prompt": "{{ context.ticket }}",
+          "allowedEvents": ["ESCALATE", "REPLY"],
+          "maxRetries": 2
+        },
+        "onError": { "target": "resolved", "assign": { "resolution": "escalated" } }
+      },
+      "on": {
+        "ESCALATE": { "target": "resolved", "assign": { "resolution": "escalated" } },
+        "REPLY": { "target": "drafting" }
+      }
+    },
+    "drafting": {
+      "invoke": {
+        "id": "draft",
+        "src": "draftReply",
+        "input": { "ticket": "{{ context.ticket }}" },
+        "onDone": {
+          "target": "awaitingApproval",
+          "assign": { "reply": "{{ event.output.reply }}" }
+        }
+      }
+    },
+    "awaitingApproval": {
+      "description": "Idle: nothing to do until a human approves or rejects the draft.",
+      "on": {
+        "APPROVE": { "target": "resolved", "assign": { "resolution": "replied" } },
+        "REJECT": { "target": "resolved", "assign": { "resolution": "escalated" } }
+      }
+    },
+    "resolved": {
+      "type": "final",
+      "output": { "resolution": "{{ context.resolution }}", "reply": "{{ context.reply }}" }
+    }
+  }
+}
+```
+
+## 3. Validate with Ajv 2020
+
+The workflow schema is draft 2020-12, so it needs Ajv's 2020 build. Run this before anything else touches the config.
+
+```ts
+import Ajv2020 from "ajv/dist/2020.js";
+import workflowSchema from "@statelyai/agent/agent-workflow.json";
+import type { AgentWorkflowConfig } from "@statelyai/agent";
+
+const validateWorkflow = new Ajv2020({ strict: false }).compile(workflowSchema);
+
+function validateGeneratedConfig(candidate: unknown): AgentWorkflowConfig {
+  if (validateWorkflow(candidate)) return candidate as AgentWorkflowConfig;
+  throw new Error(
+    (validateWorkflow.errors ?? [])
+      .map((error) => `${error.instancePath || "(root)"} ${error.message}`)
+      .join("\n"),
+  );
+}
+```
+
+Ajv errors carry `instancePath`, so a repair prompt can name the exact bad field.
+
+## 4. Lower with `fromConfig`
+
+`fromConfig` needs a `compileSchema` that turns the JSON Schemas _inside_ the config into Standard Schema validators. Two engines, two jobs: the 2020 build above checks the config document; this one compiles the per-field schemas. The library bundles no JSON Schema engine, by design.
+
+```ts
+import Ajv from "ajv";
+import { setupAgent, type SchemaCompiler, type StandardSchemaV1 } from "@statelyai/agent";
+
+const ajv = new Ajv({ strict: false });
+
+export const ajvCompileSchema: SchemaCompiler = (jsonSchema, name): StandardSchemaV1 => {
+  const validate = ajv.compile(jsonSchema);
+  return {
+    "~standard": {
+      version: 1,
+      vendor: "ajv",
+      validate: (value) =>
+        validate(value)
+          ? { value }
+          : {
+              issues: (validate.errors ?? []).map((e) => ({
+                message: `${name}${e.instancePath} ${e.message}`,
+              })),
+            },
+      // Expose the source JSON Schema so lint's serializability checks can read the shape.
+      jsonSchema: { input: () => jsonSchema },
+    },
+  };
+};
+
+const { machine, schemas } = setupAgent.fromConfig(config, { compileSchema: ajvCompileSchema });
+```
+
+Lowering is itself a gate: it throws on an unresolved named guard/action and on an `onDone` attached to an `agent.decide` invoke.
+
+## 5. Lint
+
+```ts
+import { assertAgentMachine, lintAgentMachine } from "@statelyai/agent";
+
+const diagnostics = lintAgentMachine(machine);
+assertAgentMachine(machine); // throws AgentLintError on error-severity findings
+```
+
+Every check applies to config-built machines, reachability included — the lowering keeps the config's transition targets, so `unreachable-state` and `missing-final` read the real graph. Do not disable checks.
+
+The one that bites most often is `decide-without-events`: an `allowedEvents` list with no matching `on` transitions produces a decision the machine can never deliver.
+
+## 6. Simulate a dry run
+
+Lint is structural. A dry run proves a path actually settles. No API key needed.
+
+```ts
+import { simulateAgent } from "@statelyai/agent";
+
+const dryRun = await simulateAgent(machine, {
+  input: { ticket: "" },
+  script: {
+    decisions: { "agent.decide": [{ type: "REPLY" }] },
+    text: { draftReply: [{ reply: "" }] },
+  },
+});
+// dryRun.status: 'done' | 'idle' | 'exhausted'
+```
+
+Derive the script from the config rather than guessing: take the first entry of each decision's `allowedEvents`, and stub each request's output from its declared `output` schema (`""` for string, `0` for number, `[]` for array, recurse on `properties`).
+
+- `'exhausted'` → the machine loops. Reject it.
+- `'idle'` → it stopped at a human step. Expected when the config has one.
+- To cover every branch instead of one path, use `explorePaths` / `canReach`.
+
+## 7. Repair loop
+
+Every gate throws with a message naming the offending field, state, or path. Feed that message back verbatim and regenerate:
+
+```ts
+for (let attempt = 0; attempt < 3; attempt++) {
+  try {
+    return buildAndVet(await author({ system, prompt }));
+  } catch (error) {
+    prompt = `${originalTask}\n\nYour previous config was rejected:\n${(error as Error).message}\nReturn a corrected config.`;
+  }
+}
+```
+
+Keep the cap at ~3. A config that fails three schema-shaped repairs is usually asking for something the data form cannot express — author it in TypeScript with `setupAgent` instead.
+
+## 8. Hand back
+
+Deliver the config JSON plus how to run it:
+
+```ts
+import { runAgent } from "@statelyai/agent";
+import { createAiSdkExecutors } from "@statelyai/agent/ai-sdk";
+
+const result = await runAgent(machine, {
+  input: { ticket: "Export downloads a 0-byte CSV on Safari." },
+  executors: createAiSdkExecutors({ resolveModel }),
+});
+```
+
+Say which gates passed, list any warning-severity lint diagnostics, and report the dry-run status. Model refs are strings, so the host supplies `resolveModel`.
+
+## Known limits
+
+- **Named guards and actions are host-resolved.** A config carries no functions. `guard: "isReady"` only works if the host passes an `isReady` implementation to `fromConfig`; an unresolved name is a build-time throw. Either list the host's names in the prompt or forbid named guards/actions entirely.
+- **Expressions are dot-path templates only.** `"{{ context.a.b }}"` — no comparisons, no arithmetic, no method calls, no partial interpolation inside a larger string.
+- **Ajv validity is not semantic validity.** A config can validate and still invoke a request that does not exist or route to a state that solves nothing. That is what lint and simulate are for.
+- **A dry run covers one path.** Use `explorePaths` when the branch structure matters.
+- **Model refs and tool names are unchecked strings.** They resolve at run time, in the host.

package/dist/cli.cjs

@@ -1,64 +0,0 @@
-#!/usr/bin/env node
-const require_run_agent = require("./run-agent-BFMkuI1F.cjs");
-const require_src = require("./src-D-77Ha5p.cjs");
-let node_fs = require("node:fs");
-//#region src/cli.ts
-/**
-* `statelyai-agent lint <workflow.json>` — keyless static verification for an
-* agent machine authored as data (an {@link AgentWorkflowConfig} JSON file).
-*
-* The library bundles no JSON Schema engine, so the CLI lints STRUCTURE ONLY:
-* it compiles the config with a permissive pass-through schema compiler (each
-* JSON Schema is kept as-is for structural checks, validation is a no-op) and
-* runs {@link lintAgentMachine}. Exits `1` on any error-severity finding.
-*
-* For full schema-aware linting, import the API and compile with a real engine:
-* `lintAgentMachine(setupAgent.fromConfig(config, { compileSchema }))`.
-*
-* @module
-*/
-function stubCompileSchema(jsonSchema) {
-	return { "~standard": {
-		version: 1,
-		vendor: "statelyai-agent-cli",
-		validate: (value) => ({ value }),
-		jsonSchema: { input: () => jsonSchema }
-	} };
-}
-function printUsage() {
-	process.stderr.write("Usage: statelyai-agent lint <workflow.json> [--no-schemas]\n\n  Statically verifies an agent-machine JSON config (structure-only).\n  Exits 1 on any error-severity finding.\n");
-}
-function main(argv) {
-	const args = argv.slice(2);
-	const command = args[0];
-	const file = args.find((arg, index) => index > 0 && !arg.startsWith("-"));
-	if (command !== "lint" || !file) {
-		printUsage();
-		return 2;
-	}
-	let config;
-	try {
-		config = JSON.parse((0, node_fs.readFileSync)(file, "utf8"));
-	} catch (error) {
-		process.stderr.write(`statelyai-agent: could not read/parse '${file}': ${error instanceof Error ? error.message : String(error)}\n`);
-		return 2;
-	}
-	let machine;
-	try {
-		machine = require_run_agent.setupAgent.fromConfig(config, { compileSchema: stubCompileSchema });
-	} catch (error) {
-		process.stderr.write(`statelyai-agent: '${file}' is not a valid agent-machine config: ${error instanceof Error ? error.message : String(error)}\n`);
-		return 2;
-	}
-	const diagnostics = require_src.lintAgentMachine(machine);
-	const errors = diagnostics.filter((d) => d.severity === "error");
-	const warnings = diagnostics.filter((d) => d.severity === "warning");
-	for (const d of diagnostics) {
-		const label = d.severity === "error" ? "error" : "warn ";
-		process.stdout.write(`  ${label}  ${d.code}  ${d.path}\n         ${d.message}\n`);
-	}
-	process.stdout.write(`\n${file}: ${errors.length} error(s), ${warnings.length} warning(s) (structure-only; schemas not compiled).\n`);
-	return errors.length > 0 ? 1 : 0;
-}
-process.exit(main(process.argv));
-//#endregion

package/dist/cli.d.cts

@@ -1 +0,0 @@
-export { };

package/dist/cli.d.mts

@@ -1 +0,0 @@
-export { };

package/dist/cli.mjs

@@ -1,65 +0,0 @@
-#!/usr/bin/env node
-import { c as setupAgent } from "./run-agent-BoAOq_0Z.mjs";
-import { a as lintAgentMachine } from "./src-DUeIFjv-.mjs";
-import { readFileSync } from "node:fs";
-//#region src/cli.ts
-/**
-* `statelyai-agent lint <workflow.json>` — keyless static verification for an
-* agent machine authored as data (an {@link AgentWorkflowConfig} JSON file).
-*
-* The library bundles no JSON Schema engine, so the CLI lints STRUCTURE ONLY:
-* it compiles the config with a permissive pass-through schema compiler (each
-* JSON Schema is kept as-is for structural checks, validation is a no-op) and
-* runs {@link lintAgentMachine}. Exits `1` on any error-severity finding.
-*
-* For full schema-aware linting, import the API and compile with a real engine:
-* `lintAgentMachine(setupAgent.fromConfig(config, { compileSchema }))`.
-*
-* @module
-*/
-function stubCompileSchema(jsonSchema) {
-	return { "~standard": {
-		version: 1,
-		vendor: "statelyai-agent-cli",
-		validate: (value) => ({ value }),
-		jsonSchema: { input: () => jsonSchema }
-	} };
-}
-function printUsage() {
-	process.stderr.write("Usage: statelyai-agent lint <workflow.json> [--no-schemas]\n\n  Statically verifies an agent-machine JSON config (structure-only).\n  Exits 1 on any error-severity finding.\n");
-}
-function main(argv) {
-	const args = argv.slice(2);
-	const command = args[0];
-	const file = args.find((arg, index) => index > 0 && !arg.startsWith("-"));
-	if (command !== "lint" || !file) {
-		printUsage();
-		return 2;
-	}
-	let config;
-	try {
-		config = JSON.parse(readFileSync(file, "utf8"));
-	} catch (error) {
-		process.stderr.write(`statelyai-agent: could not read/parse '${file}': ${error instanceof Error ? error.message : String(error)}\n`);
-		return 2;
-	}
-	let machine;
-	try {
-		machine = setupAgent.fromConfig(config, { compileSchema: stubCompileSchema });
-	} catch (error) {
-		process.stderr.write(`statelyai-agent: '${file}' is not a valid agent-machine config: ${error instanceof Error ? error.message : String(error)}\n`);
-		return 2;
-	}
-	const diagnostics = lintAgentMachine(machine);
-	const errors = diagnostics.filter((d) => d.severity === "error");
-	const warnings = diagnostics.filter((d) => d.severity === "warning");
-	for (const d of diagnostics) {
-		const label = d.severity === "error" ? "error" : "warn ";
-		process.stdout.write(`  ${label}  ${d.code}  ${d.path}\n         ${d.message}\n`);
-	}
-	process.stdout.write(`\n${file}: ${errors.length} error(s), ${warnings.length} warning(s) (structure-only; schemas not compiled).\n`);
-	return errors.length > 0 ? 1 : 0;
-}
-process.exit(main(process.argv));
-//#endregion
-export {};