Sessions and shared files
Choose a fresh conversation or a continuation, and understand what session.exec actually uses.
A session holds conversation state and an execution environment. A workspace supplies files. Sharing files does not share the model conversation.
Choose the conversation boundary
| Need | Use |
|---|---|
| A fresh summary or independent review | Session.run for one turn and automatic lifecycle |
| Revise using the same conversation | Session.open, then multiple ask calls |
| Run a real command alongside coding work | A workspace-bound session's exec |
| End a continuous conversation | Explicit session.close() |
Session.open returns a handle; its first operation allocates the environment.
Only handles opened with both workspace and access expose exec.
Two sessions, one workspace
Reviewer conversation ─┐
├── same workspace files
Writer conversation ──┘The sessions have separate histories and, with Docker, separate containers. A file written into the shared workspace can be visible to the other session. The agent still needs to read it; the runtime does not insert changed files into its prompt. Docker read-only operations can overlap; a workspace writer excludes readers and other writers for the operation's lease. This is not a lock for the entire conversation. Avoid parallel mutation of shared files.
Two independent workspace copies require separate runs in this release: each run has one managed workspace. Opening it a second time does not allocate another.
Why the command belongs to the session
session.exec({ key, command }) runs in the session's environment with its
workspace as the working directory. The workspace itself has no exec method.
Container packages and process state may differ between sessions even when their
files are shared.
session.exec("bun test") → command in this session's environment
→ exitCode, stdout, stderr
→ your code decides pass/failThe method actually takes { key: "verify", command: "bun test" }; the diagram
abbreviates that call. It makes no model turn and does not automatically add
stdout to the conversation. Pass relevant command output to the next ask.
A nonzero exit code is a result you must check, not automatically a failed Effect.
Keep cleanup deliberate
Continuous sessions need an explicit close at the intended durable boundary, including handled failure paths. Generic finalizers can run when a workflow suspends for a human decision and discard state you expected to resume. A close failure also needs to be retained alongside the original error.
Use the complete implement → test → report example for the full cleanup pattern. Start with one-shot sessions when you do not need conversation continuity.
Reference: Session · Workspace
← Agents, tools and skills · Next: Structured data and real checks →