Sessions and runs
A session holds a durable conversation, events and recovery state in the selected store. A run performs admitted work against an application graph. Each process constructs its own CayuApp; shared stores carry coordination across those processes.
Choose the entrypoint
Section titled “Choose the entrypoint”| Need | Entry point |
|---|---|
| A new immediate interaction | CayuApp.run(RunRequest(...)) |
| Continue a stored conversation | CayuApp.resume(ResumeRequest(...)) |
| A descendant with an independent future | CayuApp.fork_session(...) |
| Placement through configured dispatch | Dispatch API and dispatcher |
| Durable queued or scheduled work | Task store plus a worker |
| Model-selected bounded delegation | Subagent tool and child-session policy |
Resume retains the session’s recorded history and admitted execution semantics. Changing an agent’s current prompt does not silently replace that history. Use an explicit fork policy when a descendant must install a changed prompt or execution profile.
Persistence and concurrency
Section titled “Persistence and concurrency”The generated application configures durable local stores. A bare CayuApp() uses in-memory defaults suited to tests and bounded examples. Two apps constructed in separate processes share state only when configured against suitable shared stores.
For concurrent server and worker deployments, select a supported shared store and explicit process ownership. An in-memory object or module global cannot coordinate them. Application anatomy explains the boot and shutdown contract; storage explains selection and migration.
Inspect before continuing
Section titled “Inspect before continuing”Use the dashboard or session CLI to retrieve events, transcript, status and pending actions. Resolve the exact pending action under its owning session. Replaying a message is not an approval, and retrying a run is not proof that an uncertain external action did nothing.