agenttsm is a step loop over a store. The loop is in
packages/core/src/machine.ts; everything else is a port
(Store, LLM) or a convenience around it (http(), test(), toMermaid(), route()).
flowchart TD
start(["start(ctx)"]) --> save0["save snapshot v1<br/>status: running, ctx.lastInput dropped"]
resume(["resume(runId, input)"]) --> load["load snapshot"]
load --> waiting{"status is<br/>waiting?"}
waiting -- no --> noop(["return snapshot unchanged"])
waiting -- yes --> saveR["save snapshot<br/>status: running, ctx.lastInput = input<br/>(removed when there is none)<br/>(version check)"]
save0 --> guards
saveR --> guards
guards{"guards ok?<br/>maxSteps · maxTokens<br/>budgetUsd · deadlineMs"} -- no --> failG["save status: failed<br/>reason: guard breached"]
guards -- yes --> run["run handler on a copy of ctx<br/>step.signal aborts after timeoutMs"]
run -- throws or times out --> retry{"attempts left?<br/>attempt < maxRetries"}
retry -- yes --> saveRetry["save attempt + 1<br/>emit retry"] --> backoff["sleep: exponential<br/>backoff with jitter"] --> guards
retry -- no --> failE["save status: failed<br/>reason: error"]
run -- returns transition --> check{"declared<br/>target?"}
check -- no --> failT["save status: failed"]
check -- "{ done: true }" --> done["save status: done<br/>emit done"]
check -- "name or { to }" --> next["save state: to, step + 1<br/>emit transition"] --> guards
check -- "{ to, wait }" --> park["save state: to, status: waiting<br/>emit transition, wait"]
park --> timer{"sleep or until?"}
timer -- yes --> schedule["timer calls resume()"]
timer -- no --> ret(["return snapshot"])
Every box that says "save" is one store.save(snapshot, events) call. Listeners registered with
on() run after that call succeeds, so an event is never delivered for a step that wasn't
persisted.
- A snapshot is saved after every step, before the next handler runs.
commit()is awaited indrive()before the loop continues. - A failed attempt leaves ctx untouched. Each attempt runs on
structuredClone(snapshot.ctx); only a successful attempt's copy is committed. - The attempt count is part of the snapshot. A retry commits
attempt + 1before sleeping, so a crash during backoff resumes with the right count. - A paused handler never re-runs. A wait transition saves the next state as
state, andresume()starts the loop there. - Unknown targets fail early.
validate()runs indefineMachine(), and theconst Stype parameter makes them compile errors too. - Concurrent resumes do not both proceed. Every save carries
version = previous + 1, and the store rejects any other version withAgentTsmError("conflict"). - Usage is metered.
step.llmwraps the configured LLM, passesstep.signal, and addstokensandcostUsdto the snapshot'susage.
interface Store {
save(snapshot: Snapshot, events: readonly RunEvent[]): Promise<void>;
load(runId: string): Promise<Snapshot | undefined>;
list(filter?: { status?: Status; state?: string }): Promise<Snapshot[]>;
trace(runId: string): Promise<TraceEntry[]>;
}save must be atomic: it writes the snapshot and its events together, or neither, and rejects
unless snapshot.version is exactly one more than the stored version (0 for a new run).
MemoryStore does this with a synchronous check-and-set. A Postgres store can do the same with one
transaction:
UPDATE runs SET snapshot = $2, version = $3 WHERE run_id = $1 AND version = $3 - 1;
-- 0 rows updated: throw AgentTsmError("conflict")
INSERT INTO run_trace (run_id, seq, entry) VALUES ...;trace(runId) returns events and snapshots in the order they were saved: a step's events come
before the snapshot they produced.
sleep and until waits are resumed by an in-process timer. After a restart those timers are
gone; a durable deployment finds the due runs with store.list({ status: "waiting" }) and calls
resume() for each. The version check makes it safe for a timer and a worker to race.
- No LLM SDK, HTTP framework or database driver. They are adapters in user code or the examples.
- No nested or parallel states. A machine is a flat set of states; compose machines by starting one from another state's handler.
- No cancellation of handler work on timeout beyond aborting
step.signal. Handlers should pass the signal to I/O.
The conformance scenarios describe each runtime rule as data. A port implements the same loop and passes the same files.