Jevspresso
An espresso bar where Jev only picks events an XState v6 (alpha) machine already accepts, plus a lamp demo and an eval page.
Overview
Jevspresso (github.com/statelyai/jevspresso, jevspresso.dev) is Stately's simulated espresso bar. You type an order in plain English, such as a cap with almond milk, and Jev grinds, tamps, pulls shots, steams milk, and serves. You can also break equipment and watch Jev cope. An XState v6 (alpha) machine models what is physically possible. The repo pins xstate 6.0.0-alpha.58. Jev only picks an event the machine accepts right now. Jev never writes an action or a payload. The helper package @xstate/jev lives in packages/jev of this repo. On 2026-10-05 the npm registry returned Not found for @xstate/jev, and the package.json in the repo is private. This listing does not claim a license: the GitHub API reports none, and the repo root has no LICENSE file.
Problem: An agent that writes its own tool calls can ask for moves the world does not allow, so the app has to reject them after the fact.
Built for: Developers who want an XState machine to define the legal moves, and Jev to pick one of those moves.
First indexed on Jev Directory: 2026-10-03
Creator and team
- Name
- Stately
- Organization
- Stately
- Handle
- @statelyai
How Jev is used
- Role in the product flow
- Pick one legal XState event from the set snapshot.can() accepts, then send it only if the machine still accepts it
- Primitives
- ChoiceNoul
- State in
- Default state is the machine value and context. Order parsing adds the customer's words. Lookahead can describe what each event would change.
- Decision out
- One event from the closed set, or a noop, or no send when confidence is low or the machine moved on. Order fields come back as Choice and Noul answers in the same call.
- decide() collects event types the active state handles, builds payloads, and fills finite fields from Zod (Standard Schema) runtime schemas. createJevLogic delivers the chosen event and decides again when the actor changes.
- Events that snapshot.can(event) rejects are dropped. Jev gets one parallel request over the options that remain.
- The chosen event is sent only if the machine still accepts it. types<T>() events throw because they have no runtime shape.
- Orders are one Jev call of closed questions (drinks, quantity, milk). Unclear orders go to a router agent that asks the customer to confirm.
The bar in src/machines/espressoBar.ts is one parallel machine: order intake, grinder, espresso machine, steam wand, one portafilter, one milk pitcher, and the barista's hands. It models physics, not recipes. The barista is a createJevLogic actor. Whenever the bar changes, Jev sees every barista event that can() accepts, described in the machine's own words plus what transition() says would change. The package README's 5 steps are: collect matching event types, fill finite fields from the Zod schema, drop events can() rejects, ask Jev one parallel request, then deliver the event only if it is still legal. A field with no finite set of values and no payload is dropped. An event declared with types<T>() throws, because there is nothing to enumerate at runtime. The client in src/lib/jev.ts calls systemOne() on the server so TYPESAFE_API_KEY stays there. pnpm test runs against a mock and does not need a key. /light (live at jevspresso.dev/light) is the smallest copy of the pattern. /eval (jevspresso.dev/eval) runs scripted rushes and breakdowns against real Jev. This is the first XState listing in the directory. jev-guard scores coding-agent tool calls. Ten levels of Jev teaches questions the agent can write. TanStack decide is a typed helper in application code. Jevspresso keeps the legal set inside the state machine.
Sourced performance claims
- packages/jev README: decide() keeps only events snapshot.can(event) accepts, asks Jev one parallel request, and createJevLogic sends the event only if it is still accepted. Default strategy is auto: flat up to 32 options, hierarchical above that, still one parallel request.Source: github.com/statelyai/jevspresso packages/jev/README.md
- Root README: /light is a lamp. With the bulb broken and the switch on, Jev replaces the bulb. The README says it is never told about bulbs. /eval runs rush, breakdown, and sabotage scenarios against real Jev and reports orders served correctly and cost.Source: github.com/statelyai/jevspresso README
- src/lib/jev.ts calls TypeSafeClient.systemOne on the server. src/lib/jev-core.ts reads order answers as Choice (intent, quantity, milk, size) and Noul (present, milk stated, decaf, iced).Source: github.com/statelyai/jevspresso src/lib/jev.ts and src/lib/jev-core.ts
- Public GitHub repo statelyai/jevspresso had 22 stars and 5 forks on 2026-10-05. Created 2026-10-03. Language TypeScript. No license reported by the GitHub API.Source: GitHub repo metadata, 2026-10-05
Features and stack
Features
- Live espresso bar at jevspresso.dev, plus /light and /eval
- @xstate/jev in packages/jev: createJevLogic, decide, caching, and loop detection
- Zod runtime schemas fill enum, boolean, and const fields so Jev never writes a payload
- Order parser: one call, Choice and Noul questions, router agent when the order is unclear
- pnpm test uses a mock Jev. A real key is read on the server from TYPESAFE_API_KEY
Stack
- TypeScript
- XState v6 (alpha)
- Zod
- TypeSafe JavaScript SDK
- @xstate/jev (in-repo)
Pricing: The repo does not publish a license or a price table. It needs XState v6 alpha. Jev calls spend a TypeSafe key that src/lib/jev.ts keeps on the server. pnpm test does not call Jev.
Links
FAQ
- How does XState keep Jev from writing actions?
- The machine lists the events it accepts right now. @xstate/jev offers only those events, after Zod fills finite fields. Jev picks one. The event is sent only if snapshot.can(event) is still true. The package README says Jev never writes a payload.
- Is @xstate/jev on npm?
- On 2026-10-05 the npm registry returned Not found for @xstate/jev. packages/jev/package.json names the package, sets version 0.0.0, and marks it private. It is a private workspace package, so use it from a clone of the repo.
- What does the lamp example show?
- The README's /light machine is a switch and a bulb. Ask for light with the bulb broken and the switch already on, and Jev replaces the bulb. The README says the agent is never told about bulbs. It sees whether the room is lit.
- What does /eval report?
- The README says /eval runs rush, breakdown, and sabotage scenarios against real Jev and reports how many orders were served correctly and what it cost. It does not publish a fixed score in the README.
Related learn guides
Original Jev guidance that pairs with this product pattern.
- System One model
The model family behind Jev: parallel typed questions, one forward pass, probabilities you can threshold.
- Jev vs LLM classification
When to gate with System One probabilities instead of asking a chat model to label things.
Related products
Hand-picked neighbors with rich profiles or overlapping tags.