Skip to main content

Glossary

flow-state.dev is built in layers. A small set of primitives in Core (blocks, flows, sessions, resources) carries everything above it. Orchestration builds task boards out of those primitives, Workforce builds workers, coordinators and projects out of flows, sessions and resources, and Shift Manager is an app that reads what Workforce writes.

Most terms higher up are a lower term with a name and a rule added. A worker is a resource one user owns, naming the flow that runs it. A coordinator is a worker. A project is one resource in a resource collection. The Built from column tells you where each term's data lives.

Most terms link to their full page.

The layers​

Each layer is built from the ones below it
Five stacked layers. Contracts at the bottom holds the item types and block instance ids. Core above it holds blocks, flows, actions, scopes, resources and capabilities. The third layer holds Engine, which runs flows and stores what they write, Client and React for the browser, Orchestration, which builds tasks and task boards, and the smaller packages Memory, Tools and Workspace. The fourth layer holds the hosts and stores built on Engine, Workforce built on Core and Orchestration, and Patterns and Harness manager. Shift Manager sits on top: an app that serves a Workforce through the Engine and reads it.LAYER 05Shift Manageran app, not published · serves a Workforce through the EngineScreens over a Lab: Shift Coordinator, Inbox, Tasks, Roster, workstreams, projectsUSESworkforce · engine · node · client · react · fsdev · store-sqlite · devtool · design-systemLAYER 04Hosts and storesnode · next · vercelstore-sqlitestore-postgresUSESengineWorkforceWorkers, coordinators and projects, with rosters,the inventory and workstreams@flow-state-dev/workforceUSEScore · orchestrationYour app passes in engine calls.Patternssupervisor, debate …Harness managersupervised coding runsUSEScore · orchestrationLAYER 03EngineFlowState, requests,stores, HTTP routes,streaming and resumeUSEScoreClient · ReactCall actions, opensessions from thebrowserUSEScore · contractsreact also uses clientOrchestrationTasks, task boards,claim orders, skillsand the task toolsUSEScoreSmaller packagesmemory · toolsworkspaceUSEScoretools also uses workspaceLAYER 02CoreBlocks (handler, generator, evaluator, sequencer, router), actions, flows and flow instances,scopes and state, resources and resource collections, capabilities, tools, model resolverLAYER 01ContractsThe item types every request streams, and block instance ids. Shared by server and browser.01A package imports only from the layers under it. The USES line in each box names exactly which.LAYERPART OF A LAYER

A package uses only the layers under it. Workforce imports Core and Orchestration and nothing from Engine: when it needs to register a flow or open a session, your app passes in the function that does it.

Core and Engine: from a block to a running flow​

Core: from a block to a running flow
Core builds up in five steps. A block is a typed unit of work, in one of five kinds. A sequencer is a block that runs other blocks in order. An action wraps one root block under a name. A flow is a kind that declares its actions, scopes, resources and capabilities. A flow instance is the flow called with an id and settings. The Engine registers instances and opens sessions on them, and each request on a session runs one action and streams items. Beside the chain, a tool is a block a generator may call, a capability bundles resources, state and tools a block pulls in with uses, and a resource collection is a family of resources keyed by a pattern.DEFINE@flow-state-dev/coreSTEP 01BlockA typed unitof work. Fivekinds:handlergeneratorevaluatorroutersequencerSTEP 02SequencerA block thatruns blocks inorder..step .tap.sideChain.rescueSTEP 03ActionA name on oneroot block,plus an inputschema andhooks.STEP 04FlowdefineFlow({kind})Declares actions,scopes, resourcesand capabilities.STEP 05Flow instanceflow({id, config})The flow with anid and settings.The id is itsaddress.REGISTERED BY IDRUN@flow-state-dev/engineStoresKeep sessions,state,resources andrequests.Memory, SQLiteor Postgres.ItemsStreamed asthe requestruns.Resumable.RequestRuns oneaction on asession.SessionOne conversation,opened against aninstance.FlowStateRegisters eachinstance at its idand serves routes.BESIDE THE CHAIN@flow-state-dev/coreToolA block listed in agenerator's tools.No separate type.CapabilityResources, state,context, tools andhelpers in one bundle.A block or flow pullsit in with uses.Resource collectionA family of resourceskeyed by a pattern,files/* · projects/*ScopesWhere state lives:requestsessionuserorgResources: session,user, org01Each box in the top row is made of the one before it: a sequencer is a block, an action wraps one root block,a flow declares its actions, and an instance is the flow called with an id and settings.02FlowState registers each instance at its id. A session is opened against one instance, and each request on itruns one action and streams items back as it runs.THE NEXT STEP

The top row builds left to right: each box is made of the one before it. The Engine row runs what the top row defines. A tool is an ordinary block, and so is a dispatcher.

Contracts and Core​

@flow-state-dev/contracts holds the shapes shared by the server and the browser. @flow-state-dev/core re-exports them and adds the builders.

TermPackageWhat it isBuilt from
ItemcontractsOne typed record a request streams: a message, reasoning, a tool output, a component, a status, an error, a state or resource change, a suspension, and a few more. See Items.Content and a visibility setting
Block instance idcontractsThe id of one attempt at one step in one run, requestId:path:attempt. A retry gets the next attempt number; a resumed request rebuilds the same id for the same attempt.The request id and the step's path
BlockcoreA typed unit of work with an input schema and an output schema. You define it, and the framework runs it. See Blocks.Zod schemas and a block context (ctx)
Block kindcoreExactly five: handler (plain code), generator (a model call), evaluator (a model judgment), sequencer (runs blocks in order) and router (picks one block to run).Block
SequencercoreA block that composes other blocks with step, tap, sideChain, parallel, forEach, loopBack, rescue and the rest. See Composition.Blocks and connectors
ConnectorcoreA small function that reshapes a value between two composed blocks (connectInput, connectOutput, or the first argument to step). See Connectors.Block context
Side chaincoreA block a sequencer starts without waiting for it. Its items are marked as side-chain output.Sequencer, block
ToolcoreA block listed in a generator's tools, so the model can call it. There is no separate tool type.Block
Dispatcher blockcoredispatcher() builds a handler that sends its input to an entry on another flow. It is not a sixth kind.Handler
Model resolvercoreTurns a model string such as openai/gpt-6-luna into a model a generator can call, with fallbacks. See Models.Configuration
ActioncoreA named entry point on a flow. It wraps one root block and adds an input schema, hooks, a token budget and durability settings. See Actions.One block
ScopecoreWhere state lives and how long it lasts. There are four: request, session, user and org. See State and scopes.None
StatecoreZod-typed data on a scope, or on one block (ctx.self).Scope
SessioncoreThe scope that lasts as long as one conversation: its state, its history, its items. You open one against a flow instance.Scope, flow instance
ResourcecoreNamed, typed data, with optional content, kept at session, user or org scope. See Resources.Scope, state
Resource collectioncoreA family of resources keyed by a pattern such as files/*, with get, list, create, upsert and delete. See Collections.Resource
CapabilitycoreA bundle of resources, state schemas, prompt context, tools and helper functions a block or flow pulls in with uses. See Capabilities.Resources, state, tools, other capabilities
FlowcoredefineFlow with a kind. It declares actions, scope state, resources, capabilities, authentication and schedules. See Flows.Actions, scopes, resources, capabilities
Flow instancecoreA flow called with an id and settings: myFlow({ id, config }). Its id is its address. A singleton flow defaults the id to its kind; a collection flow needs one per instance.Flow
Harness blockcoreThe shape every coding-agent block shares: it takes a prompt and returns a handle with an outcome, a final message, usage and cost. Claude Code, Codex and Cursor each ship one. See Coding agents.Block
SuspensioncoreA run that stops to wait for a person's approval or answer, then resumes where it stopped.Item, session
PrincipalcoreThe verified caller of a request: a userId and an orgId. If you don't configure resolvePrincipal, every request runs in a built-in development organization. See Authentication.None
UsercoreA person, signed in, always inside one org. Every action is taken by one user. The framework has no system users: an app can make one, and to the framework it is just another user.Principal

Engine​

@flow-state-dev/engine runs flows. Store adapters (store-sqlite, store-postgres) and host adapters (node, next, vercel) plug into it.

TermPackageWhat it isBuilt from
FlowStateengineWhat createFlowState returns: the server, holding your flow instances, stores and principal resolver. It serves the HTTP routes. See Server setup.Flow instances, stores
Flow registryengineThe instances a FlowState answers for, each at its id. Two instances can't share an id.Flow instance
RequestengineOne run of one action on one session. It streams items and can be resumed from where a client left off. See Streaming.Action, session, items
StoresengineWhere sessions, requests, user and org state, resources, checkpoints and traces are kept. In-memory by default, SQLite or Postgres to persist. See Persistence.None
Host adapternode, next, vercelServes a FlowState from one kind of host. See Host adapters.FlowState
Durable actioncore, engineAn action that writes a checkpoint at each step, so a crashed run resumes from its last one. See Durable execution.Action, block instance id, stores
Scheduled actioncore, scheduledAn action that runs on a cron schedule. See Scheduled actions.Action

Orchestration: a task board​

Orchestration: what a task board is made of
A task is a row with a goal, a status and an optional assignee. Tasks live in a task collection, kept either in state or in a resource collection. A task board is a sequencer that drains the collection: a claim order picks the next ready task, the assignee routes it to a board worker, and a board worker is any block. Built on the board: the goal-seek loop wraps a drain with a judge, the harness manager is a board worker that runs a coding agent, and four patterns use a board.TaskA goal, a status,dependencies, an optionalassignee, input and output.pending · in_progressheld · completed …Task collectionOne API: add, claim,complete, fail, hold,whichever store backs it.KEPT IN · YOU CHOOSEStateORA resource collection0102Task boarda sequencer that drains the collectiontaskBoard()Claim orderPicks the next ready task:topological (default),fifo, priority, or oneyou pass in.Board workerAny block. Runs oneclaimed task.The assignee picks which.03 DRAINS04ORCHESTRATIONGoal-seek loopDrains, asks a judge if the goalis met, replans, drains again.HARNESS-MANAGERHarness managerA board worker: one task becomesone supervised coding run.PATTERNSPatternssupervisor · planAndExecuteparallelTasks · eventActors05 BUILT ON A TASK BOARD01A task is a row with a goal, a status and an optional assignee. Tasks live in a task collection.02The collection is kept in state, or in a resource collection. You choose; the API is the same.03A task board is a sequencer that drains the collection. Its claim order picks the next ready task.04The task's assignee routes it to a board worker, which is any block. An assignee names a board worker,or a Workforce worker that takes tasks. The board runs the list; Workforce finds the worker.05The goal-seek loop wraps a drain with a judge. The harness manager is a board worker that runs a coding agent.Four patterns use a board.A RELATION, NUMBERED IN THE NOTESPART OF THE BOARD
TermPackageWhat it isBuilt from
TaskorchestrationOne unit of work: a goal, a status (pending, in_progress, held, completed, errored or cancelled), dependencies, an optional assignee, input and output. See Task substrate.None
Task collectionorchestrationWhere tasks are kept, with one API (add, claim, complete, fail, park) whichever store backs it.State, or a resource collection
Task boardorchestrationtaskBoard(): drains a task collection with a pool of workers, holding back tasks whose dependencies aren't done. See Task board.Sequencer, task collection, capability
Task toolsorchestrationWhat a model changes a task with: the filer's createTask, getTask, listTasks and updateTask, and the worker's reportProgress. Each updateTask field has one rule: edits before the task starts, a cancel until it finishes. See One task, five tools.Task, task board
Board workerorchestrationA block that runs one claimed task.Block
AssigneeorchestrationWho a task goes to: an entry in a task board's workers, or a name the board's assignee check accepts, such as one of a Workforce worker's delegates. A task's assignee names it, and it runs the task inline or dispatches it to a dispatch run in another session. A task whose assignee names no entry goes to the default assignee, or fails. See Task board.Board worker, task
Claim orderorchestrationThe rule that picks the next ready task. By name: topological (the default), fifo or priority. You can also pass your own ClaimOrder.Task collection
Dispatch a taskorchestrationStart a task on another worker now. How a recorded task starts depends on the board. On a conversation's board, createTask starts a task as soon as it is filed, and a task filed held doesn't start until updateTask releases it. On a board a drain runs, recording is enough: the drain starts each task when it claims it, and dispatches it when its assignee holds a dispatcher().Task, wait, dispatcher block
WaitorchestrationWhat a caller does on a task it filed, or a request it dispatched, when its next step needs the result: getTask({ id, wait: true }), or dispatcher({ wait: true }). Its turn pauses until the work ends, or until the deadline, when it carries on with the work as it stands; the deadline cancels nothing. Nothing holds a request open while it lasts, and waits nest up to five deep. A board's onIdle: "wait" is a different setting: the board stays alive when it has nothing to do.Dispatch a task
Hand-offorchestrationA session that was doing the work passes it to another session, mid-work. Giving another worker new work isn't a hand-off; it's dispatching a task.Dispatch a task
Goal-seek looporchestrationDrains a board, asks a judge whether the goal is met, replans, and drains again. See Goal-seek loop.Task board, sequencer
Flow policyorchestrationWhich earlier tasks' results a worker sees. See Flow policy.Capability
SkillorchestrationA SKILL.md folder, stored as a resource and loaded into a generator when needed. See Skills.Resource collection, capability, tools
Harness managerharness-managerA board worker that turns one task into one supervised coding run in its own checkout, and checks the run's result before marking the task completed or errored. A run that asks a question parks its task until someone answers. See Harness manager.Board worker, sequencer, harness block, resource collection
PatternpatternsA function that returns a composed block for a common shape. supervisor, planAndExecute, parallelTasks and eventActors run a task board; debate, roundRobin and responseAuditor don't. See Patterns.Sequencer, generators, sometimes a task board

Smaller packages​

These sit beside Orchestration on Core and don't use a task board.

TermPackageWhat it isBuilt from
Memory tiermemoryworking (one session), episodic, semantic and digest. Each tier is one resource. See Memory.Resource, capability
PlaceworkspaceWherever an agent actually works, such as a folder on the host or in memory. Files sync between a place and resources. See Workspace.Resource collection

Workforce: workers, coordinators, projects​

Workforce: what each term is made of
Each Workforce term beside what it is made of. A worker is a resource in one user's scope that names its worker flow. A standard worker is read from the installation's files, the same for every user. A roster is one user's workers. A coordinator is a worker on the coordinator flow, with delegates from the same roster in its session. A project is one row, in the user's scope or the org's; a workstream is an entry in a shared project that only its owner writes, plus its lead's session. A project coordinator is one session per user per project.WORKFORCE TERMBUILT FROMWorkera resource, one ownerRESOURCECOREA resource in one user's scope that names its workerflow, with its own instructions, skills and tools.Standard workerWORKER.mdFILESYOURSRead from the installation's files, the same forevery user. Fork one to make a worker of your own.Rosterone user's workersRESOURCE COLL.COREOne user's workers, standard ones included. Auser's own workers come back after a restart.Coordinatorflow: coordinatorWORKERWORKFORCEA worker on the coordinator flow. Its delegates,from the same roster, are in its session.Projecta body of workRESOURCE COLL.COREOne row, in the user's scope when private or theorg's when shared: title, brief, owner.Workstreamone owner eachENTRY + SESSIONCOREAn entry in a shared project that only its ownerwrites, plus its lead's workstream session.Project coordinatorone per user per projectWORKER SESSIONWORKFORCEA coordinator's session, one per user per project.It hands work only to that user's own workstreams.010201A coordinator is a worker: a resource in one user's scope that names the coordinator flow.02A project coordinator is a coordinator's session, one per user per project.03Workforce adds files and rules. Everything lands in a Core piece, in your files, or in a Workforce term above it;the second label on the right says which.IS MADE OFOUTLIVES THE REQUEST
TermPackageWhat it isBuilt from
WorkerworkforceWhat you might call an agent: a configuration with an owner. It names the flow that runs it and carries its own instructions, skills and tools. A worker belongs to one user and acts as them. See Workers on disk.A resource in the user's scope
Worker flowworkforceThe flow a worker runs on: the built-in agent, the coordinator, or a flow your app registers as a worker flow. Each is registered once, and every worker that names it shares that copy. See The built-in worker.Flow
Standard workerworkforceA worker every user has, read from the installation's files and the same for everyone. Nobody can edit one. To change it for yourself, fork it.Worker, the installation's files
ForkworkforceCopies a standard worker into a worker of your own, starting from its configuration.Worker
RosterworkforceThe workers one user has, standard ones included. See Hiring and forking.Workers
AddressworkforceA worker's id: team.name for a team worker, the bare name for an org worker. A user's own worker is addressed by the id it was hired or forked under, on that user's roster.None
TeamworkforceA folder of workers under teams/<name>/, with an optional TEAM.md whose body every worker on the team reads. A team is not a flow and has no address.Workers
Org workerworkforceA standard worker under org/workers/<name>/. It belongs to no team.Standard worker
HireworkforceA user adds a worker of their own to their roster. hireWorkforce gives back one copy of each worker flow, which your app registers.Worker
FireworkforceRemoves one of a user's own workers from their roster. A standard worker leaves when its folder is deleted.Worker
CoordinatorworkforceA worker that hands each message to other workers on the same roster, its delegates, as routed tasks. It picks by its own judgment, by best fit, in turn, or sends to everyone. See Coordinators.Worker, the coordinator flow
DelegateworkforceA worker a conversation may delegate to, and the only workers it can give work to. A worker's file lists its delegates under delegates:, or delegates: all for the whole roster as it stands, and each conversation starts from that list. Always on the same user's roster; each works in its own session.Worker
DelegationworkforceHanding work to one of your delegates: giving work to a worker on your roster, checked against your roster. A coordinator delegates a message as a routed task; any worker with a delegate delegates a task. See Delegating work.Dispatch a task, roster
Doorworkforcerespond, the one public action that takes a message to a worker, on every worker flow.Action
RoleworkforceWhat a worker flow does beside taking a message: contributor takes tasks on work, manager files tasks for its delegates and runs its board on dispatch, coordinator routes messages. A flow declares its roles when it is registered, and the hire refuses a role whose entries are missing. See A worker flow's roles.Worker flow, entry
InventoryworkforceOrg-wide records of every standard worker registered in an organization. See Inventory.An org resource collection
ProjectworkforceA body of work, private to you or shared with your org. See Projects.One row, in user or org scope
WorkstreamworkforceOne area of a shared project, with one owner. Its entry is read by the org and written only by its owner; its lead works it in a workstream session.A resource row, a session
Project coordinatorworkforceYour coordinator for one project: one session per user per project. It reads every workstream's entry and hands work only to your own.Coordinator, session
Shift CoordinatorworkforceThe standard coordinator a user asks who works here, and asks to hire or fire. See The Shift Coordinator.Standard worker, coordinator
PackageworkforceA PACKAGE.md folder of instructions and tools a worker can hold. See Packages on disk.Tools, instructions

Shift Manager: screens over a Workforce​

Shift Manager: what each screen reads
Each Shift Manager screen beside what it reads. A Lab is a FlowState loaded from one fsdev config. The Shift Coordinator screen is a user's session with the Lab's Shift Coordinator worker. Inbox lists asks, which are suspended runs in workers' sessions waiting on a user. Tasks lists the tasks on your boards. Roster lists your workers, with on shift and off shift worked out from their tasks and asks. A project view shows a project, its workstreams with their progress, your own workstreams' boards, and your own project coordinator.SCREENREADSLab--configFLOWSTATEENGINEThe FlowState one fsdev.config.mts default-exports.Shift Manager serves it and reads only its routes.Shift Coordinatorthe home screenWORKER + SESSIONWORKFORCEYour session with your Shift Coordinator, under asummary of what waits and runs.Inbox/inboxSUSPENSIONSCOREAsks in sessions you started and their runs: worksuspended until a user approves or answers.Tasks/tasksTASKSORCHESTRATIONEvery task not done on your boards, grouped bystate, worker or workstream.Roster/rosterROSTERWORKFORCEYour workers. On shift and off shift are workedout from their tasks and asks.Project view/p/<project id>PROJECTWORKFORCEIts workstreams and their progress, your ownboards, and your own project coordinator to talk to it.0101Shift Manager stores nothing of its own. Every screen is a read of the Lab: each source here is read throughthe Lab's routes.02The second label on each source names where it comes from: Workforce, Orchestration, Core or the Engine.READSOUTLIVES THE REQUEST

Shift Manager is a browser app, published as @flow-state-dev/shift-manager. It stores nothing of its own: every screen is a read of the Lab it serves.

TermWhereWhat it isBuilt from
LabShift ManagerThe server one fsdev.config.mts default-exports, which Shift Manager serves and reads.FlowState
Team profileShift ManagerA Lab config kept beside Shift Manager in this repository, which its start and dev scripts open. devteam is the one there. It isn't in the published package.Lab
Shift CoordinatorShift ManagerThe home screen: a summary of what is waiting and running, then your conversation with your Shift Coordinator worker.Shift Coordinator worker, session
AskShift ManagerAn approval or a question a worker's run is suspended on, waiting for a user.Suspension
InboxShift ManagerEverything a worker waits on you for, oldest first: the pending asks in sessions you started and the runs they started, and the questions a task waits on, one item per task. See Building an Inbox.Asks, task holds
TasksShift ManagerEvery task not done on your boards, grouped by state, worker or workstream.Task, board
RosterShift ManagerYour workers, grouped as on shift (running a task, or waiting on you with a task waiting on questions or a pending ask) or off shift. Worked out on each read, not stored.Roster, tasks, asks
GeneralShift ManagerThe group that lists org workers, the ones on no team.Org worker

Words that mean two things​

A few words are used in two places. The package tells you which one you're reading.

  • Worker. In Workforce, a configuration one user owns. On a task board, a board worker: the block that runs a task. A task's assignee names a board worker, or, on a board that asks Workforce's worker lookup, one of your workers.
  • Kind. A flow's kind is its name to the engine. Workforce calls the flow a worker runs on its worker flow.
  • Roster. Your Workforce roster is your workers. Shift Manager's Roster screen shows them by what they are doing.