@hiai-gg/hiai-opencode 0.2.1 → 0.2.2

package/docs/architecture/bob-manager-architecture.md

@@ -0,0 +1,244 @@
+# Bob→Manager Worker Pool Architecture
+
+**Document Version:** 2026-05-14
+**ARC:** ARC-009
+**Status:** Implemented (verified against source)
+
+---
+
+## Overview
+
+The hiai-opencode agent system implements a two-tier orchestration hierarchy:
+
+- **Tier 1 (Singletons):** Bob, Strategist, Critic, Designer — directly owned by the orchestrator
+- **Tier 2 (Worker Pool):** Coder, Researcher, Vision, Writer — coordinated by Manager
+
+This architecture ensures clear separation of concerns: Bob handles top-level orchestration and routing, Manager coordinates the execution workforce, and specialized agents perform domain-specific work.
+
+---
+
+## Agent Hierarchy
+
+```
+                    ┌─────────────────────────────────────────┐
+                    │              USER INPUT                 │
+                    └─────────────────┬─────────────────────────┘
+                                      │
+                                      ▼
+                    ┌─────────────────────────────────────────┐
+                    │              BOB (Orchestrator)         │
+                    │  • Intent classification                 │
+                    │  • Strategic delegation routing           │
+                    │  • Parallel execution orchestration       │
+                    │  • Singleton: owns Strategist/Critic/      │
+                    │    Manager/Designer directly              │
+                    └──────────┬───────────────────────────────┘
+                               │
+          ┌────────────────────┼────────────────────┐
+          │                    │                    │
+          ▼                    ▼                    ▼
+   ┌──────────────┐   ┌──────────────┐   ┌──────────────────┐
+   │  STRATEGIST   │   │    CRITIC    │   │     MANAGER      │
+   │  (Planning)   │   │   (Review)   │   │ (Worker Pool Co.)│
+   │               │   │              │   │                  │
+   │ Architecture  │   │ Plan gate   │   │ Coder            │
+   │ Scope def     │   │ Code review  │   │ Researcher       │
+   │ Work breakdown│   │ QA verify   │   │ Vision           │
+   │               │   │             │   │ Writer           │
+   └──────────────┘   └──────────────┘   └────────┬─────────┘
+                                                  │
+                              ┌───────────────────┼───────────────────┐
+                              │                   │                   │
+                              ▼                   ▼                   ▼
+                       ┌────────────┐     ┌────────────┐     ┌────────────┐
+                       │   CODER    │     │ RESEARCHER │     │   VISION   │
+                       │ (Deep Impl)│     │ (Discovery)│     │ (Media/UI) │
+                       └────────────┘     └────────────┘     └────────────┘
+                                                           ┌────────────┐
+                                                           │   WRITER   │
+                                                           │   (Copy)   │
+                                                           └────────────┘
+```
+
+---
+
+## Tier 1 — Singleton Agents (Bob-owned)
+
+Bob owns these four agents directly. They are singletons — one instance, directly callable.
+
+### Bob
+- **Role:** Primary orchestrator, intent classifier, top-level router
+- **Mode:** `primary`
+- **Delegates to:** Strategist, Critic, Manager, Designer
+- **Key principle:** Never implements directly; orchestrates specialists
+
+### Strategist
+- **Role:** Planning, architecture, work breakdown
+- **Mode:** `subagent`
+- **Trigger:** Complex scope, multi-step tasks, ambiguous requirements
+- **Bob's usage:** Consult FIRST before implementation on non-trivial tasks
+
+### Critic
+- **Role:** Review gate, high-accuracy verification
+- **Mode:** `subagent`
+- **Trigger:** Plan validation, code review, QA gate before completion
+- **Bob's usage:** Blocks implementation until approval
+
+### Designer
+- **Role:** UI/visual direction via Stitch MCP, design systems
+- **Mode:** `subagent`
+- **Trigger:** Visual problems, layout, design tokens, screen generation
+- **Bob's usage:** Routes all visual work to Designer, not Coder
+
+---
+
+## Tier 2 — Worker Pool Agents (Manager-coordinated)
+
+Manager acts as the worker pool coordinator. These agents are spawned as needed for specific work units.
+
+### Manager
+- **Role:** Delegation orchestrator + Memory steward (MemPalace)
+- **Mode:** `subagent`
+- **Owns:**
+  - TODO tracking and plan checkbox management
+  - Session continuity (session_id tracking for handoffs)
+  - MemPalace writes (durable decisions, architecture choices)
+  - Post-wave verification coordination (Quality Guardian)
+- **Coordinates:** Coder, Researcher, Vision, Writer
+- **Key principle:** Delegates ALL implementation; never writes code
+
+### Coder
+- **Role:** Deep implementation, substantial code changes
+- **Category routing:** `category="deep"`, `category="unspecified-high"`, `category="visual-engineering"`
+- **Trigger:** Multi-file changes, complex logic, architecture implementation
+- **Manager's usage:** Primary executor for implementation tasks
+
+### Researcher
+- **Role:** Codebase exploration, external documentation discovery
+- **Category routing:** `subagent_type="researcher"` (direct call)
+- **Trigger:** Pattern finding, library docs, OSS code search
+- **Manager's usage:** Background discovery; always `run_in_background=true`
+
+### Vision
+- **Role:** PDF/image/diagram extraction, browser-based UI verification
+- **Category routing:** `subagent_type="vision"` (direct call)
+- **Trigger:** Screenshot analysis, multimodal extraction, UI verification
+- **Manager's usage:** Screenshot/verification tasks via agent-browser skill
+
+### Writer
+- **Role:** Copy, content, positioning, SEO, landing pages
+- **Category routing:** `subagent_type="writer"` (direct call)
+- **Trigger:** Website copy, product messaging, naming
+- **Manager's usage:** All text/copy tasks; uses `website-copywriting` skill
+
+---
+
+## Delegation Path Summary
+
+| From | To | Routing Method | Use Case |
+|------|----|----------------|----------|
+| Bob | Strategist | `task(subagent_type="strategist", ...)` | Architecture, scope, planning |
+| Bob | Critic | `task(subagent_type="critic", ...)` | Plan review, code review, QA gate |
+| Bob | Designer | `task(subagent_type="designer", ...)` | Visual work, Stitch UI, design systems |
+| Bob | Manager | `task(subagent_type="manager", ...)` | Multi-wave plans, TODO orchestration |
+| Manager | Coder | `task(category="deep", ...)` | Complex implementation |
+| Manager | Researcher | `task(subagent_type="researcher", run_in_background=true, ...)` | Codebase search, docs |
+| Manager | Vision | `task(subagent_type="vision", ...)` | Media extraction, UI verification |
+| Manager | Writer | `task(subagent_type="writer", load_skills=["website-copywriting"], ...)` | Copy, content |
+
+---
+
+## Stewardship Responsibilities (Manager-owned)
+
+Manager owns these stewardship responsibilities beyond worker pool coordination:
+
+### MemPalace Memory Hygiene
+- Search MemPalace BEFORE making decisions
+- Write durable decisions, architectural choices, and session outcomes to MemPalace
+- Never dump raw transcripts; write concise handoff ledgers
+
+### TODO Hygiene
+- Mark completed items `completed` immediately (not batched)
+- Preserve unfinished tasks with blocker context and next action
+- Remove duplicate stale TODOs
+
+### Session Continuity
+- Store `session_id` from every delegation
+- Use `session_id` for retries and follow-ups
+- Write handoff ledgers for complex multi-session work
+
+### Post-Wave Verification
+- Dispatch Quality Guardian after each wave completes
+- Verify cross-task file conflicts via `git diff --name-only`
+- Mark completed checkboxes in plan files
+
+---
+
+## Category-to-Agent Routing
+
+Categories spawn agents with domain-specific configurations:
+
+| Category | Spawns | Agent | Typical Use |
+|----------|--------|-------|-------------|
+| `deep` | SubAgent | Coder | Complex multi-file implementation |
+| `ultrabrain` | SubAgent | Strategist | Architecture, hard logic planning |
+| `quick` | SubAgent | Coder (fast contour) | Small targeted changes |
+| `visual-engineering` | SubAgent | Designer | UI/layout/styling |
+| `artistry` | SubAgent | Designer | Brand, creative, SEO |
+| `writing` | SubAgent | Writer | Copy, content, documentation |
+| `bounded` | SubAgent | Coder (fast contour) | Moderate bounded changes |
+| `cross-module` | SubAgent | Coder | Multi-component changes |
+| `unspecified-low` | SubAgent | Coder (fast contour) | Unclassified small tasks |
+| `unspecified-high` | SubAgent | Coder | Unclassified substantial tasks |
+
+---
+
+## Verification Against Source
+
+### Bob (src/agents/bob.ts)
+- Bob delegates to: Strategist, Critic, Manager, Designer (line 145: `task(subagent_type='manager', ...)`)
+- Bob does NOT implement directly; orchestrates only
+- Intent gate classifies requests and routes to appropriate specialist
+
+### Manager (src/agents/manager/*)
+- Manager coordinates worker pool: Coder, Researcher, Vision, Writer
+- Manager does NOT write code; only delegates
+- Manager owns MemPalace stewardship, TODO tracking, session continuity
+
+### Agent Roster in Manager (shared-prompt.ts lines 121-170)
+- Lists all 11 agents with roles and routing patterns
+- Worker pool agents clearly marked as Manager-coordinated
+- Task routing decision table enforces specialist routing (not everything to Coder)
+
+### Parallel Execution (default-prompt-sections.ts)
+- Wave-based dispatch for multi-wave plans
+- Sequential dispatch for single-task plans
+- Routing table for task-type to specialist mapping
+
+---
+
+## File Reference
+
+| File | Purpose |
+|------|---------|
+| `src/agents/bob.ts` | Bob's prompt and orchestration logic |
+| `src/agents/manager/agent.ts` | Manager agent factory |
+| `src/agents/manager/default.ts` | Manager's default prompt |
+| `src/agents/manager/shared-prompt.ts` | Manager's delegation system, agent roster |
+| `src/agents/manager/default-prompt-sections.ts` | Manager's workflow, parallel execution, boundaries |
+| `src/agents/manager/guard-integration.ts` | Quality Guardian integration |
+| `src/agents/manager/prompt-section-builder.ts` | Dynamic section builders |
+| `src/agents/dynamic-agent-core-sections.ts` | Bob's delegation table, parallel section |
+| `src/shared/closure-protocol.ts` | Closure protocol injection |
+| `docs/architecture/bob-manager-architecture.md` | This document |
+
+---
+
+## Conclusion
+
+The architecture is correctly implemented:
+
+1. **Bob → [Strategist | Critic | Manager | Designer]** is the established delegation path
+2. **Manager → [Coder | Researcher | Vision | Writer]** is the worker pool coordination path
+3. Manager's stewardship (MemPalace, TODO hygiene, session continuity) is documented and enforced in prompts
+4. No changes needed — source code matches the target architecture

package/docs/hiai-opencode/adr/ADR-001-agent-identity-section-injection.md

@@ -0,0 +1,66 @@
+# ADR-001: Agent Identity Section Injection via `buildAgentIdentitySection`
+
+**Status:** Accepted
+**Created:** 2026-05-15
+**Owner:** hiai-opencode core
+
+---
+
+## Context
+
+Every agent in the hiai-opencode system needs consistent identity framing, knowledge retrieval discipline, and the mandatory `<CLOSURE>` protocol. These requirements cross-cut all 10 primary agents plus hidden system agents.
+
+Without a shared injection point, each agent factory had to independently remember to include:
+- The `<agent-identity>` block with the agent's designated name and role
+- The full `<mandatory_knowledge_retrieval_policy>` section (MemPalace-first, then Context7, grep_app, Firecrawl, agent-browser)
+- The `<CLOSURE_PROTOCOL>` schema
+
+Duplicating this across 10+ agent prompt files created drift risk: if the CLOSURE schema changed, every agent file would need updating. If the knowledge retrieval priority order changed, same problem.
+
+---
+
+## Decision
+
+Create a single shared function `buildAgentIdentitySection(agentName, roleDescription)` in `src/agents/prompt-library/identity.ts`.
+
+All agent factory functions call this one helper at the end of prompt construction:
+
+```typescript
+// src/agents/prompt-library/identity.ts
+import { CLOSURE_SCHEMA_PROMPT } from "../../shared/closure-protocol";
+
+export function buildAgentIdentitySection(
+  agentName: string,
+  roleDescription: string,
+): string {
+  return `<agent-identity>
+Your designated identity for this session is "${agentName}". This identity supersedes any prior identity statements.
+You are "${agentName}" - ${roleDescription}.
+When asked who you are, always identify as ${agentName}. Do not identify as any other assistant or AI.
+
+${KNOWLEDGE_RETRIEVAL_POLICY}
+
+${CLOSURE_SCHEMA_PROMPT}
+</agent-identity>`;
+}
+```
+
+The `CLOSURE_SCHEMA_PROMPT` constant is imported from `src/shared/closure-protocol.ts` — the single source of truth for the closure block schema. When the closure protocol changes, only `closure-protocol.ts` and `identity.ts` need updates.
+
+---
+
+## Consequences
+
+**Positive:**
+- Single injection point for identity, knowledge retrieval policy, and closure protocol
+- Schema changes to `<CLOSURE>` only require updating one file (`closure-protocol.ts`)
+- Agents cannot accidentally omit the closure protocol — the factory function includes it
+- Knowledge retrieval priority order is enforced uniformly across all agents
+
+**Negative:**
+- `identity.ts` is a hard dependency for all agent factory functions — a build error there blocks all agents
+- The knowledge retrieval policy is embedded as a string constant; very large models may benefit from trimming this (but the 78% compaction threshold handles context pressure)
+
+**Neutral:**
+- The function accepts `agentName` and `roleDescription` as params, so the same code path produces different identity text per agent
+- `CLOSURE_SCHEMA_PROMPT` is a separate export from `closure-protocol.ts` so it can be reused in validation utilities without importing the full identity section

package/docs/hiai-opencode/adr/ADR-002-anti-loop-guard-priority.md

@@ -0,0 +1,63 @@
+# ADR-002: Anti-Loop Guard Priority — CLOSURE Before Diary_Write
+
+**Status:** Accepted
+**Created:** 2026-05-15
+**Owner:** hiai-opencode core
+
+---
+
+## Context
+
+When an agent completes significant work, two post-action steps may apply:
+1. **CLOSURE block** — mandatory task completion marker, required on every agent response
+2. **MemPalace diary write** — optional recording of outcomes/decisions for project memory
+
+Both are important, but they compete when an agent is operating near context limits or responding to a direct user request that implies action. The question: which one takes priority when only one can reliably fit in the output?
+
+The original implementation placed diary_write at the same priority as CLOSURE delivery, creating a race condition. In high-pressure responses (tool calls, error recovery, final deliverables), agents sometimes omitted the CLOSURE block because they wrote diary content instead — triggering automatic rejection by the closure validator.
+
+---
+
+## Decision
+
+The `<mandatory_knowledge_retrieval_policy>` embedded in every agent prompt via `buildAgentIdentitySection()` states the priority explicitly:
+
+```
+**PRIORITY ORDER**: When CLOSURE and diary_write both apply, deliver CLOSURE FIRST — diary is optional. If context-limit warning is active, skip diary_write, deliver CLOSURE immediately.
+```
+
+This rule is enforced by:
+
+1. **Prompt-level instruction** — every agent receives the priority rule in their identity section
+2. **Context-limit guard** — when `context-window-monitor` detects usage > 70%, the directive to skip diary_write is activated
+3. **No hard dependency** — `mempalace_diary_write` is called voluntarily by the agent after CLOSURE; it is never a hard requirement for task completion
+
+The CLOSURE block schema:
+
+```xml
+<CLOSURE>
+{
+  "reasoning": "Concise summary of what was achieved and why it satisfies the request.",
+  "evidence": ["Link to test results", "File path to changes", "Log snippets", "LSP diagnostics clean"],
+  "readiness": "done" | "accept" | "reject"
+}
+</CLOSURE>
+```
+
+---
+
+## Consequences
+
+**Positive:**
+- Closure validator rejection rate drops to near-zero for normal completion paths
+- Agents operating under context pressure cannot accidentally fail the closure gate by writing diary entries first
+- Diary recording remains available and encouraged, just as a best-effort secondary action
+- The priority rule is visible in every agent's prompt, making it self-enforcing
+
+**Negative:**
+- Diary entries may be less complete when agents are near context limits, as diary_write is skipped
+- No hard technical enforcement — agents that ignore the prompt directive can still omit CLOSURE; the validator catches this downstream but does not prevent it
+
+**Neutral:**
+- The `mempalace_diary_write` tool is still available and recommended for significant work; the policy only prevents it from blocking CLOSURE delivery
+- The context-window-monitor at 70% usage activates the "skip diary" recommendation, so agents are warned before hitting the 78% compaction threshold

package/docs/hiai-opencode/adr/ADR-003-compaction-mechanism.md

@@ -0,0 +1,71 @@
+# ADR-003: Compaction Mechanism — 15s Guard, 78% Threshold
+
+**Status:** Accepted
+**Created:** 2026-05-15
+**Owner:** hiai-opencode core
+
+---
+
+## Context
+
+Large context windows are a finite resource. When an OpenCode session runs long, the risk of hitting a hard context limit increases. The session becomes unusable — every message returns a token limit error with no recovery path except manual restart.
+
+Two questions needed answers:
+1. **When** should compaction trigger? (threshold)
+2. **How** should concurrent compaction attempts be prevented? (guard)
+
+Early prototypes triggered compaction only on hard errors (`session.error` with token limit). This meant the first compaction attempt always came *after* a failed response — the agent had already wasted a turn and potentially corrupted state. We needed preemptive action.
+
+For the guard, early prototypes had no synchronization. Multiple hooks could independently decide to compact the same session simultaneously, causing race conditions in the summarize call.
+
+---
+
+## Decision
+
+### Threshold: 78%
+
+The `preemptive-compaction` hook monitors token usage after every assistant message. When the ratio `(inputTokens + cacheReadTokens) / actualLimit > 0.78`, it calls `session.summarize()` to compact the context before the hard limit is reached.
+
+The 78% figure was chosen empirically:
+- At 70%, `context-window-monitor` only *reminds* the agent to be concise — no compaction yet
+- At 78%, there is enough headroom for the summarize call itself (~60s, ~5–10% of context) without immediately hitting the wall
+- Below 78%, the overhead of compaction exceeds the benefit of doing it early
+- Above 78%, the risk of not having enough room to complete the summarize call itself becomes non-trivial
+
+### Guard: 15-Second Lock + Shared Set
+
+Concurrent compaction attempts are prevented by a shared `compactionInProgress` Set in `src/hooks/shared/compaction-in-progress.ts`:
+
+```typescript
+const compactionInProgress = new Set<string>();
+
+export function isCompacting(sessionID: string): boolean
+export function markCompacting(sessionID: string): void
+export function markCompactionDone(sessionID: string): void
+export function clearSession(sessionID: string): void
+```
+
+Additionally, a 60-second cooldown between compaction attempts prevents thrashing on sessions that compact successfully but immediately approach the threshold again.
+
+### Hard Timeout: 60s
+
+All `session.summarize()` calls are wrapped in `withTimeout(promise, 60_000)`. On timeout, compaction is considered failed and the session continues without compaction. The `preemptive-compaction-degradation-monitor` then tracks post-compaction message quality to detect if the session entered a degraded (no-text response) state.
+
+---
+
+## Consequences
+
+**Positive:**
+- Preemptive compaction prevents hard limit errors in the common case where a session runs long but not extremely long
+- The shared Set guard ensures no two hooks can trigger simultaneous compaction on the same session
+- 60s timeout prevents summarize calls from blocking session progress indefinitely
+- Degradation monitor provides a safety net: if compaction causes output quality collapse, recovery compaction is attempted
+
+**Negative:**
+- 78% threshold is a global constant — some models/context configurations may want a lower threshold
+- The 60s timeout can fire on genuinely slow summarize calls, leaving the session uncompacted and approaching the limit
+- Cooldown of 60s means a session that triggers compaction cannot be compacted again for 60 seconds, even if it immediately approaches the limit again
+
+**Neutral:**
+- Compaction model can be overridden per-agent via `pluginConfig.agents.<agent>.compaction.model`
+- The summarize call itself consumes context (~5–10%), so the effective gain is context reduction, not elimination of the limit problem

package/docs/hiai-opencode/adr/ADR-004-session-recovery.md

@@ -0,0 +1,76 @@
+# ADR-004: Session Recovery with State-Backup and Checkpoints
+
+**Status:** Accepted
+**Created:** 2026-05-15
+**Owner:** hiai-opencode core
+
+---
+
+## Context
+
+OpenCode sessions can fail in ways that lose work:
+- Context window limit errors that cannot be recovered via compaction
+- Session deletion (`:done`, timeout, or explicit close)
+- Hard errors that put the session into an unrecoverable state
+- Agent crashes mid-task with unresolved todos
+
+When a session dies, the agent loses: conversation history, todo state, pending tool results, and any context that was being built. The user experience was: start over from scratch.
+
+Existing recovery mechanisms were limited to compaction (context reduction), which helps with token limits but does not address session death, todo loss, or state corruption.
+
+---
+
+## Decision
+
+Implement a multi-layer session recovery system:
+
+### Layer 1: Todo Preservation Around Compaction
+
+`src/hooks/compaction-todo-preserver/` captures the full todo list before compaction and restores it after:
+
+- `session.compacted` event → restore todos via `opencode/session/todo`'s `Todo.update`
+- `session.deleted` event → clear local snapshot
+- Skips restore if todos already exist post-compaction (avoid overwriting intentional post-compaction changes)
+
+This ensures todos survive the most common context-recovery operation.
+
+### Layer 2: Compaction Context Injection
+
+`src/hooks/compaction-context-injector/` saves a checkpoint of agent config before compaction, then injects a context summary after:
+
+- `capture(sessionID)` — saves agent config checkpoint before `session.compacted`
+- `session.compacted` → recovers checkpointed agent config, warns about no-text tails
+- `session.idle` → finalizes tracked assistant messages
+- `message.part.delta` → tracks text output to detect no-text tails
+
+The `inject` function appends compaction context to the next prompt so the resumed session has continuity.
+
+### Layer 3: Session Recovery Hook
+
+`src/hooks/session-recovery.ts` (part of `createContinuationHooks`) handles post-failure session state reconstruction:
+
+- On `session.idle` after an error → attempt to reconstruct todo state from last known good checkpoint
+- On `session.created` → check for recovered state and offer to resume
+
+### Layer 4: Background Task History for Delegated Sessions
+
+`backgroundManager.taskHistory` tracks the history of delegated sub-agent sessions. When compaction occurs, `compaction-context-injector` injects this history into the compaction context prompt so the parent agent can see what sub-agents were working on.
+
+---
+
+## Consequences
+
+**Positive:**
+- Todo lists survive compaction and session recovery — the most common failure mode
+- Agent config checkpoints survive compaction, allowing the resumed session to use the same model/settings
+- Delegated task history provides continuity when a parent agent resumes after sub-agents complete
+- No-text tail detection catches degraded sessions early and triggers recovery compaction
+
+**Negative:**
+- Checkpoint storage is in-memory (via `backgroundManager.taskHistory`) — a full server restart loses recovery state
+- Session recovery from a fully deleted session is limited to todos and agent config; conversation history is not reconstructable
+- The `compaction-context-injector` injects context that increases prompt size — too many compactifications can cause the injected context itself to approach context limits
+
+**Neutral:**
+- Session recovery is best-effort, not guaranteed — agents should still emit `<promise>DONE</promise>` promptly to allow the loop to exit cleanly rather than relying on recovery
+- Todo preservation uses OpenCode's native `Todo.update` API, so todo state is as durable as OpenCode's native session storage