Stately Agent

Least privilege: the machine admits only legal events and executors are plain functions; no elevated built-in permissions, score 2 (no demonstrated authz/tool-permission boundary for model callers). User confirmation: human-in-the-loop and approval states are referenced via docs/Chameleon, but no implementation shown in-sample — deducted. Data flow transparency: append-only journal with stateHash, mermaid architecture, machine never touches the model directly — score 3. Sensitive data handling: README does not address user data in prompts or key handling beyond tests forcing OPENAI_API_KEY empty — score 1. Dependency security: all extra peers optional with explicit ranges, CI uses frozen lockfile and minimal workflow permissions — score 2; no audit/SBOM. External effects: model calls and email sends live in app-level executors and tests avoid billed calls — score 2; no mandatory pre-send confirmation demonstrated. Rollback: snapshot migration and journal folding, failed appends leave the log untouched — score 2; no explicit rollback API. Source attribution: MIT LICENSE, clear author and repository fields — score 2; publisher unverified.

Self-consistency: README, package., examples and tests describe runAgent/setupAgent/executors coherently; install comments match peer ranges — score 3. Dependency availability: xstate is an alpha (v6 alpha.46+) and ai@^7 matching is explained, score 2; the core dependency itself is pre-stable, an objective deduction. Failure messages: tests assert 'does not apply' 400s, 500 instead of TypeError, structured 'Invalid JSON' errors, and refusal to fabricate events from unparseable model responses — score 3.

Audience and scenarios: three starting points target distinct audiences; examples span games, email drafting, triage — score 3. Capability boundaries: 'the machine owns control flow, the model only picks a legal event' is a clear boundary, but alpha-API instability is only noted up top — score 2. Trigger precision: allowedEvents, guard rejection with retry, and illegal events leaving state unchanged are all test-proven — score 3. Environment fit: Node 22.18+, dual ESM/CJS builds, native workerd tests; Next/TanStack hosts appear only as typecheck targets without run verification — score 2.

Information architecture: README is well-structured with complete doc links — score 3. Install notes: cover the prerelease channel, peer-mismatch pitfall, and Node version — score 3. Naming stability: export map is thorough but the package is 2.0.0-alpha.22 with declared API churn — score 2. Examples and FAQ: eight named examples plus patterns and a LangGraph comparison — score 3; no explicit FAQ. Known limitations: alpha status declared, but storage/concurrency limits undiscussed — score 2. License: full MIT, consistent with package. — score 3. Versioning/changelog: changesets workflow present but no CHANGELOG content in-sample — score 2. Maintenance responsibility: author, repo URL, OIDC trusted publishing visible; maintainer team and response channels not shown — score 2.

Output usability: typed zod outputs, typed events, clear result.status/output — score 3. Marginal value: constraining LLM actions with state machines is a genuine differentiator; guard-rejection-with-retry is hard to get for free elsewhere — score 3. Cost benefit: keyless scripted-executor testing, usage metering, and no-billed-call test design show cost awareness; but the xstate-alpha + Node 22.18 requirement is an adoption tax — score 2.

Claim traceability: README claims link to docs/examples, and tests map to documented durability/replay/400/500 behavior — score 3. Cross-source corroboration: README, package., CI, and Cloudflare tests agree on versions, executors, and the conformance suite — score 3. Fact/inference separation: factual claims are mixed with marketing language ('deterministic, inspectable') that is supported by architecture and tests but not fully proven — score 2.