Skip to main content
Session is the primary runtime object in the current Agent layer. If you remember only one thing, remember this:
  • the agent definition is durable
  • the environment is reusable
  • the session is what actually runs

​
What a session owns

A session owns:
  • one sessionId
  • one agentId
  • one environmentId
  • one append-only event stream
  • one isolated runtime memory directory
  • one attached resource list
  • one stop reason and status
It does not own:
  • global company truth
  • shared chat truth
  • other sessions for the same agent

​
Status model

The current status model is:
  • idle
  • running
  • rescheduling
  • terminated
The corresponding stop reasons are:
  • idle
  • requires_action
  • rescheduling
  • terminated
requires_action is how the runtime pauses for custom tool results without inventing a separate approval system in the Agent core.

​
Event model

Each session has an append-only events.jsonl. Current event families:
  • user.message
  • user.tool_confirmation
  • user.custom_tool_result
  • session.status_changed
  • session.status_idle
  • agent.message
  • agent.tool_use
  • agent.custom_tool_use
Pending means:
  • processedAt == null
This is the reason wake(sessionId) can stay small. Orchestration does not need to carry the whole prompt payload because the session already contains the unprocessed work.

​
Storage layout

Each session lives here: 
.openboa/agents/<agent-id>/sessions/<session-id>/
  session.json
  events.jsonl
  runtime/
    checkpoint.json
    session-state.md
    working-buffer.md
  wake-queue.jsonl
Meaning:
  • session.json
    • canonical durable state
  • events.jsonl
    • append-only event journal
  • runtime/
    • local continuity for the harness
  • wake-queue.jsonl
    • internal revisit scheduling

​
Session isolation

Multiple sessions can exist for the same agent. That is important because:
  • one agent may have many distinct threads of work
  • context isolation matters
  • one bad thread should not contaminate another
  • learnings can be shared at the agent level without sharing runtime scratch state
What is isolated per session:
  • event history
  • runtime memory
  • pending custom-tool request
  • wake queue
What is shared across sessions for the same agent:
  • workspace substrate
  • agent definition
  • agent-level learnings

​
Wake semantics

The public orchestration seam is: 
wake(sessionId) -> void
Operationally, that means:
  1. load the session
  2. read pending events
  3. if nothing is pending and no revisit is due, do nothing
  4. otherwise run one bounded harness cycle
This is intentionally weaker than “run with this payload”. That weakness is a feature. It keeps orchestration decoupled from:
  • provider-specific logic
  • upper-layer product semantics
  • exact context assembly rules

​
CLI

Create a session: 
pnpm openboa agent session create --name alpha
Send a message into a session: 
pnpm openboa agent session send --session <uuid-v7> --message "Summarize your state."
Inspect it: 
pnpm openboa agent session status --session <uuid-v7>
pnpm openboa agent session events --session <uuid-v7> --limit 10
Wake it: 
pnpm openboa agent wake --session <uuid-v7>

​
Design rule

Any new Agent feature should answer this first: Does this belong on the session, or does it belong above the Agent layer? If it is:
  • transient runtime continuity
  • pending execution work
  • bounded tool pause/resume
  • per-thread execution history
it probably belongs on the session. If it is:
  • shared company coordination
  • work publication
  • governance or observation across many sessions
it probably belongs above the session runtime.