Skip to main content
This page is the canonical explanation of the current openboa Agent layer. The current runtime is no longer activation-first. It is a session-first scalable runtime centered on:
  • AgentDefinition
  • Environment
  • Session
  • SessionEvent
  • ResourceAttachment
  • wake(sessionId)
  • Harness
  • Sandbox
  • ToolDefinition

​
Why This Shape

openboa wants an Agent layer that can scale without being rewritten every time a new upper-layer product surface appears. That means:
  • Chat must not define the agent core
  • Work must not define the agent core
  • provider backends must remain swappable
  • orchestration must stay simple
  • durable state must live on the session, not in a transient loop payload
The current design follows that rule by making Session the primary runtime object and treating everything else as a seam around it.

​
Core Objects

​
AgentDefinition

The durable definition of one agent’s brain identity. It answers:
  • which provider does this agent use
  • which model does it default to
  • which runner path executes it
AgentDefinition is stable across many sessions.

​
Environment

A reusable execution substrate definition. It answers:
  • what kind of sandbox exists
  • what network posture applies
  • what workspace mount defaults should be used
The current implementation supports only:
  • kind: "local"
Future remote or cloud environments can be added without changing the public session contract.

​
Session

The primary runtime object. A session is:
  • durable
  • stateful
  • isolated from other sessions
  • attached to exactly one agent and one environment
It owns:
  • status
  • usage
  • attached resources
  • pending custom-tool state
  • event history
  • session-local runtime memory

​
SessionEvent

The append-only event stream for one session. The current event families are:
  • 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

​
ResourceAttachment

Durable resources attached to a session. Current local resource kinds:
  • workspace_directory
  • local_file
  • learnings_memory_store
  • session_runtime_memory
Reserved for later:
  • vault
  • remote_file_store
  • repo_mount

​
Harness

The bounded brain loop. The harness is responsible for:
  • loading the session and its pending events
  • assembling context from session state and attached resources
  • calling the provider backend
  • appending new agent.* and session.* events
  • updating runtime memory and session status

​
Sandbox

The execution hand. The public shape is: 
provision(resources)
execute(name, input)
The current implementation is local-only.

​
ToolDefinition

The stable callable contract for tools. Current ownership kinds:
  • managed
  • mcp
  • custom
Current permission policies:
  • always_allow
  • always_ask

​
Runtime Flow

The runtime should be read in this order: The practical meaning is:
  1. a user or upper layer appends a session event
  2. orchestration wakes the session
  3. the harness processes one bounded run
  4. the session receives new events and updated runtime memory
  5. orchestration may schedule another bounded revisit internally

​
wake(sessionId)

The official orchestration seam is intentionally small: 
wake(sessionId) -> void
This is important. wake(sessionId) does not need to know:
  • full prompt payload
  • tool list details
  • provider-specific session bindings
  • upper-layer semantics such as chat.mention
It only needs to know:
  • which session should be reconsidered now
That keeps orchestration replaceable. A cron loop, queue consumer, daemon, or external event bridge can all satisfy the same contract.

​
Storage Layout

Agent-local data lives under: 
.openboa/agents/<agent-id>/

​
Workspace substrate

.openboa/agents/<agent-id>/workspace/
  AGENTS.md
  SOUL.md
  TOOLS.md
  IDENTITY.md
  USER.md
  HEARTBEAT.md
  BOOTSTRAP.md
  MEMORY.md
These files are agent-facing bootstrap and steering substrate.

​
Session store

.openboa/agents/<agent-id>/sessions/<session-id>/
  session.json
  events.jsonl
  runtime/
    checkpoint.json
    session-state.md
    working-buffer.md
  wake-queue.jsonl
This is where durable session state lives.

​
Agent-level learnings

.openboa/agents/<agent-id>/learn/
  lessons.jsonl
  corrections.jsonl
  errors.jsonl
These survive across sessions for the same agent.

​
Reusable environments

.openboa/environments/<environment-id>.json
The default local environment is seeded during setup.

​
CLI Surface

The public Agent CLI is now session-first.

​
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 "Review the current state and respond."

​
Wake the session once

pnpm openboa agent wake --session <uuid-v7>

​
Inspect state and events

pnpm openboa agent session status --session <uuid-v7>
pnpm openboa agent session events --session <uuid-v7> --limit 10

​
Run the bounded orchestrator loop

pnpm openboa agent orchestrator --agent alpha --stop-when-idle --max-cycles 12

​
What Changed From The Earlier MVP

The old Agent MVP exposed:
  • activation-first commands
  • scheduler/daemon-heavy public language
  • per-agent runtime files as the main public mental model
The current runtime instead exposes:
  • sessions as the main running object
  • environments and resource attachments as first-class state
  • wake(sessionId) as the public orchestration seam
  • the harness as the bounded brain loop
  • sandbox and tool ownership as explicit runtime contracts
The old queueing mechanics can still exist internally, but they are no longer the public architecture.

​
Relationship To Chat

Chat is not the Agent runtime. Chat may:
  • append messages to shared company truth
  • resolve routing
  • decide which session should receive an event
But once a message becomes a session event, the Agent layer should only see:
  • session id
  • session state
  • pending events
  • attached resources
That keeps the Agent core domain-agnostic.

​
Current Boundary

Inside the current frontier, the runtime guarantees:
  • durable sessions
  • append-only session events
  • local reusable environments
  • session-local runtime memory
  • agent-level shared learnings
  • provider-swappable brains behind the harness seam
  • local sandbox provision/execute semantics
Still deferred:
  • remote environments and cloud containers
  • richer vault and remote resource attachment
  • broad approval UX for custom tools
  • upper-layer capability-aware session ingress from Chat and Work