Single-Agent Runtime (Pi)

​

CLI-first bootstrap (OpenClaw-style)

​

Global install (next-step, CLI-first)

• build once:
  • pnpm build
• install from source tree:
  • pnpm install -g . (or package-specific publish flow)
• then run directly:
  • openboa setup
  • openboa agent spawn --name <agent_id>
  • openboa agent chat --name <agent_id>

• pnpm openboa setup
  • creates .openboa workspace scaffold (bootstrap/runtime.json, system/base.prompt, required folders)
• pnpm openboa agent spawn --name <agent_id>
  • creates agent runtime config under .openboa/agents/<agent_id>/agent.json
• pnpm openboa agent list
  • lists configured agents
• pnpm openboa agent chat --name <agent_id>
  • starts interactive chat with that agent
• pnpm openboa setup-codex-pi-agent <agent_id>
  • legacy alias of agent spawn
• pnpm openboa codex-login
  • launches oauth flow and writes .openboa/auth/codex.oauth.json

• pnpm dev -- "hello pi runtime" for one-shot turn with default agent
• pnpm dev -- tui [agentId] for direct TUI

​

What It Includes

• Unified turn envelope protocol for both Agent ↔ Human and Agent ↔ Agent:
  • protocol: "boa.turn.v1"
• Minimal gateway WebSocket route handler:
  • BoaGateway.handleWebSocketMessage(rawJson)
• Runtime turn loop:
  • inbound persist -> context build -> adapter stream -> outbound persist -> checkpoint append
• Local JSONL boundaries:
  • Chat source of truth: .openboa/chat/chats/<chatId>.jsonl
  • Session metadata/checkpoints: .openboa/agents/<agentId>/sessions/<sessionId>.jsonl
• Bootstrap/system prompt/context path:
  • .openboa/bootstrap/runtime.json (tokenBudget)
  • .openboa/system/base.prompt
  • .openboa/system/agents/<agentId>.prompt
• Minimal Codex auth reference path:
  • CODEX_API_KEY env first
  • fallback .openboa/auth/codex.oauth.json

​

New quick flow (recommended)

pnpm openboa setup
pnpm openboa agent spawn --name agent_1
pnpm openboa agent chat --name agent_1

# first-time setup
pnpm openboa setup

# optional: use env key per shell
export CODEX_API_KEY=...

# create one isolated agent runtime
pnpm openboa agent spawn --name agent_1

# start a persistent interactive session
pnpm openboa agent chat --name agent_1
# type 'exit' to quit

• Agent config is created with auth.required: true by default.
• If code key is unavailable, use pnpm openboa codex-login first.
• No secrets are printed or committed.

​

API Mode (Pi, API-key only)

export OPENAI_API_KEY="<your-openai-api-key>"
pnpm dev -- serve

curl -s http://127.0.0.1:8787/health

curl -s http://127.0.0.1:8787/chat \
  -H 'content-type: application/json' \
  -d '{"message":"hello from pi"}'

• API key is env-only (OPENAI_API_KEY), never committed in files.
• /chat enforces request size limit and timeout with normalized error responses.
• Session continuity is preserved through default ids (api-chat / api-session) or caller-provided ids.

​

Operation Modes (Pi)

• One-loop (single turn):
  • pnpm dev -- "hello pi runtime"
• Forever (HTTP service):
  • pnpm dev -- serve

[Unit]
Description=openboa pi chat api
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/openboa
Environment=CODEX_API_KEY=REDACTED
Environment=OPENBOA_API_HOST=0.0.0.0
Environment=OPENBOA_API_PORT=8787
ExecStart=/usr/bin/env pnpm dev -- serve
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

​

Failure Modes / Quick Triage

• Auth required but missing:
  • run 'openboa codex-login' for oauth
  • or set CODEX_API_KEY
• Token lookup order to verify quickly:
  • CODEX_API_KEY -> .openboa/auth/codex.oauth.json
• Inspect runtime artifacts:
  • .openboa/chat/chats/*.jsonl
  • .openboa/agents/*/sessions/*.jsonl

​

Recovery / Triage

• Storage locations:
  • chat: .openboa/chat/chats/<chatId>.jsonl
  • session: .openboa/agents/<agentId>/sessions/<sessionId>.jsonl
• Missing file behavior:
  • treated as empty history (no crash)
• Error split:
  • malformed payload / missing required fields / invalid participant kind => invalid turn envelope
  • unsupported protocol version => unsupported protocol: <value>
• Malformed file behavior:
  • malformed trailing line is skipped (tolerated)
  • malformed non-trailing line fails fast for integrity
• Quick inspection commands:
  • tail -n 20 .openboa/chat/chats/<chatId>.jsonl
  • tail -n 20 .openboa/agents/<agentId>/sessions/<sessionId>.jsonl
  • tail -n 20 .openboa/chat/chats/<chatId>.jsonl | jq -c .

• sender.kind and recipient.kind must be one of: human, agent
• Other values are rejected as invalid turn envelope

{
  "protocol": "boa.turn.v0",
  "chatId": "local-chat",
  "sessionId": "local-session",
  "agentId": "pi-agent",
  "sender": { "kind": "human", "id": "operator" },
  "recipient": { "kind": "agent", "id": "pi-agent" },
  "message": "status check"
}

​

Protocol Envelope Example

{
  "protocol": "boa.turn.v1",
  "chatId": "local-chat",
  "sessionId": "local-session",
  "agentId": "pi-agent",
  "sender": { "kind": "human", "id": "operator" },
  "recipient": { "kind": "agent", "id": "pi-agent" },
  "message": "status check"
}

​

CI / PR Triage (Issue #16 scope)

• check job runs format/lint/type/test when non-doc files changed
• docs job runs markdown + link checks when docs changed
• required-ci is the single gate expected by branch protection

pnpm check
pnpm check:docs
pnpm docs:linkcheck

​

Validation Matrix (Canonical)

pnpm check
pnpm check:docs
pnpm -s vitest run test/runtime.single-agent.test.ts test/runtime.gateway.validation.test.ts test/runtime.context-builder.test.ts test/smoke.test.ts