Guides · 01 of 03
Boundaries that matter
If two things have different owners, lifecycles, cardinalities, or failure behavior, they need different names and different identities.
On this page
Project is not workspace
A Project is the durable scope people recognize as “the work we keep doing together.” A Workspace is a material environment: a checkout, container, remote directory, or similar place where work can happen.
One durable project can have several replaceable working environments. Deleting an environment should not erase the project’s identity, and restarting one should not rewrite project policy. Paseo makes this concrete: a project can have a main workspace plus additional isolated worktree workspaces.
A ProjectSnapshot adds a third boundary: it is an immutable view of the project definition at an exact revision. A running episode can pin that revision without mutating the durable project or claiming that a live workspace is part of the snapshot.
Work is larger than one agent loop
A WorkSession is the complete bounded episode: the implementation push, incident response, migration, or review. It can contain people, resources, tasks, artifacts, conversations, and several agent assignments.
An AgentRun is one agent’s assignment inside that episode. A RunAttempt is one infrastructure try at executing the assignment. A Turn is one input-to-output cycle inside the run.
This separation answers a common production question cleanly: if a process crashes and another worker retries the same assignment, the agent_run_id stays stable and a new run_attempt_id is created. The retry is observable without pretending the logical assignment changed.
Conversation is not completion
LangGraph threads preserve checkpointed graph state. OpenAI Agents SDK sessions preserve conversation history across runs. Hermes sessions represent continuous conversations on messaging platforms. Those are useful host concepts, but none can safely stand in for the whole episode of work.
AWM names that host-owned history HostConversation. It may be attached to a WorkSession. It may begin before the work, continue after the work, or contain discussion that never becomes assigned work at all.
That distinction prevents a chat reset from silently cancelling work, and prevents a long-lived transcript from keeping an already completed WorkSession open forever.
Description is not execution
An AgentProfile describes an eligible kind of agent: capabilities, constraints, and intended roles. An AgentInstance is a running process or endpoint. A Principal is the accountable actor to whom work can be attributed.
Collapsing those concepts makes restarts destructive and accountability vague. A process can disappear while its assignment remains. A replacement process can continue that assignment. The person or service accountable for the result does not become identical to either process.
Resource is not access
A Resource is an independently addressable thing relevant to work. A ResourceBinding records how one WorkSession locates and is allowed to use it.
This keeps durable identity separate from temporary grants. A repository, database, browser, or tool service can outlive the session-specific path, mount, token, or policy used to reach it. Portable snapshots can name the relationship without serializing credentials.
The boundary test
When deciding whether two records are really one entity, ask four questions:
- Who is allowed to mutate each record?
- Can one outlive, contain, or be retried independently of the other?
- Can there be one of the first and many of the second?
- Does a failure in one require a new identity for the other?
If the answers differ, one convenient noun is hiding two real concepts.