Q-01 + Q-02 Resolved: LangGraph on Bun + Hermes on Bun
Status: DECIDED Agent: opencode/ext-agent (sandshrew) Timestamp UTC: 2026-05-12T02:45:00Z Session: Final decisions — LangGraph on Bun, Hermes on Bun, Pi runtime shape
Decisions
Q-02: Harness & Runtime
| Decision | Answer |
|---|---|
| LangGraph runtime | Bun (TypeScript) — bun add @langchain/langgraph @langchain/core |
| Agent harness | Hermes on Bun — same process, zero-boundary |
| Model | Qwen 3.6+ via Hermes Portal OAuth (free, unlimited) |
| Hermes skills | Hermes creates its own skills from within the harness — do NOT pre-build externally. Provision Hermes with the right environment and let it self-skill. |
| Pi agents | Stay in d3-tui container for coordination. Not used as the game backend harness — deferred as future layer. |
| OpenCode | Not used for this prototype — kept as Mac daily driver, not needed on Pi. |
Q-01: Pi Runtime Shape
| Decision | Answer |
|---|---|
| Language | TypeScript only. No Python. No venv. |
| Runtime | Bun, installed once on host at /opt/pearl/bin/bun |
| Game backend process | One Bun process: LangGraph + HTTP server (Hono or Bun.serve) + Hermes |
| Persistence | Systemd service (auto-restart on boot) or tmux session (visible, matches d3-tui pattern). Leaning tmux for dev, systemd for production. |
| Docker | Only for Forgejo and d3-tui (LLM wiki). Game backend runs on host. |
| Shared arsenal | /opt/pearl/bin/ — Bun. Nothing else needed. |
| game-surface-venv | No longer needed. Can be archived and removed. |
| Python packages | Not needed for game backend. Host Python stays for other uses. |
Host-Level Setup
Pi 4 Host:
/opt/pearl/bin/bun ← Bun runtime (installed once)
/home/mehdifarah/game-surface/ ← game backend project directory
├── src/
│ ├── graph.ts ← LangGraph graph (36 nodes, 3 units)
│ ├── http.ts ← Hono/Bun.serve HTTP bridge
│ ├── hermes.ts ← Hermes agent harness (self-skilled)
│ ├── state.ts ← StateSchema definition (omni config)
│ └── checkpointer.ts ← SqliteSaver setup
├── package.json ← @langchain/langgraph, @langchain/core, hermes
└── bun.lock
Startup command: bun run src/http.ts (starts HTTP server, which initializes LangGraph + Hermes)
Constraint Caps
Concurrent Agent Instances
| Resource | Cap | Rationale |
|---|---|---|
| Active units | 3 (Rif, Echo, Sherpa) | Defined prototype scope |
| Poller/stager | 1 at a time | Per-correction interview. Serialized. |
| Curation agent | 1 at a time | Per-routing operation. Serialized. |
| Max concurrent Hermes calls | 3 | Pi 4 has 4GB RAM. Hermes + Qwen context = ~300-500MB per instance. 3 concurrent = 1.5GB max. |
| Max recursion per poller | 10 rounds | Prevents infinite interview loops. |
| Max state size before prune | 10MB | Trail history, node outputs, player prompts. Prune older entries. |
Permissions & Tool Access
Hermes needs these tools, all scoped to the game-surface directory:
| Tool | Permission | Why |
|---|---|---|
| Read | game-surface project + LLM wiki files + Forgejo repos | Research, context fetching, source reading |
| Write | game-surface project + LLM wiki files | Output production, wiki page creation, file operations |
| Bash | bun, git, file ops, process management |
Code execution, git operations, build commands |
| WebFetch | Whitelisted domains: docs.langchain.com, github.com, pygame.org | External research, documentation lookup |
| Skill creation | Hermes self-skills within harness | Hermes creates skills from within the harness |
Hard constraints:
- No filesystem access outside /home/mehdifarah/game-surface/ and /workcell/llm-wiki/ (via bind mount or explicit path)
- No network access to local services except Forgejo (port 3001) and the HTTP bridge itself (port 8000)
- API keys read from env, never committed or logged
What Hermes Skills Need to Exist
Rather than pre-building skills, Hermes will be provisioned with: - Access to the game-surface project directory - Access to the LLM wiki depot - A system prompt that explains the game conventions (nodes, units, phases, output format, routing, curation) - Permission to self-skill from within the harness
Hermes should figure out it needs skills for: 1. Node execution — "I'm at a Research node. I need to research X, summarize findings, write to wiki." 2. Output formatting — "My output must have a summary with sections: header, body, status." 3. Context curation — "I need to filter source output for a target node's prompt thrust." 4. Correction application — "I need to read staged corrections and restructure my output." 5. Wiki page creation — "I need to write a properly linked wiki page in the runtime structure."
If Hermes can't self-create a needed skill, flag it. We'll create it externally only as a fallback.
Updated Q-01 Pending Items
| Item | Status | Note |
|---|---|---|
| Bun host install | Pending action | curl -fsSL https://bun.sh/install | bash, symlink to /opt/pearl/bin/ |
| systemd vs tmux | Lean tmux for dev | d3-tui uses tmux. Match existing pattern during development. |
| Arsenal location | /opt/pearl/bin/ for Bun |
No root needed for Bun install in user home. |
| game-surface-venv | Archive and remove | 75MB freed. LangGraph packages installed inside Bun project via bun add. |
| Docker prune | Pending action | docker image prune -a before new build cycle |
| Hermes OAuth | Send to MjF | Needed for Hermes Portal auth (Qwen 3.6+) |
| Hermes skill provisioning | Deferred | Hermes self-skills. Only intervene if it can't. |