agent-orchestrator/docs/opencode-workflows-spec.md

OpenCode Workflow Spec (Agent Orchestrator)

This document defines intended behavior for Agent Orchestrator when agent: opencode is selected, including edge cases and expected outcomes.

Scope

• CLI workflows: ao start, ao spawn, ao status, ao send, ao session cleanup, ao session restore, ao session remap.
• Core lifecycle paths in SessionManager and plugin resolution.
• OpenCode session mapping and deletion semantics.

Configuration Contract

• defaults.agent: opencode or projects.<id>.agent: opencode selects the OpenCode agent plugin.
• projects.<id>.orchestratorSessionStrategy controls orchestrator session behavior:
  • reuse: reuse existing alive orchestrator runtime; otherwise restart and reuse mapped OpenCode session id when available.
  • delete: destroy alive runtime, delete previously mapped/discovered OpenCode orchestrator sessions, then start fresh.
  • ignore: destroy alive runtime and start fresh without deleting prior OpenCode sessions.
  • delete-new and kill-previous normalize to delete.
  • ignore-new normalizes to ignore.
• projects.<id>.opencodeIssueSessionStrategy controls issue-session reuse for ao spawn with OpenCode:
  • reuse (default): reuse mapped OpenCode session for same issue when available.
  • delete: delete mapped OpenCode sessions for same issue, then spawn fresh.
  • ignore: spawn fresh without deleting prior issue sessions.

Workflow Behavior

1) Plugin Resolution

• CLI must resolve opencode via getAgentByName and getAgent without error.
• Core plugin registry built-ins must include @aoagents/ao-plugin-agent-opencode under slot agent.
• Expected failure mode: unknown agent names fail fast with Unknown agent plugin: <name>.

2) ao start (orchestrator session)

• Always delegates orchestrator session lifecycle to SessionManager.spawnOrchestrator.
• For orchestratorSessionStrategy: reuse:
  • if existing runtime is alive, return existing session without creating a new runtime.
  • if existing runtime is dead and metadata contains opencodeSessionId, pass it to launch config for continuation.
• For delete strategy:
  • delete mapped/discovered OpenCode orchestrator sessions (AO:<prefix>-orchestrator) before launching new orchestrator.
• For ignore strategy:
  • do not delete old OpenCode sessions; launch fresh runtime.

3) ao spawn

• Uses selected agent (default/project/override) and launches OpenCode command from plugin launch config.
• OpenCode launch behavior:
  • no mapped id: run with --title AO:<session> and then continue via discovered session id.
  • mapped id (agentConfig.opencodeSessionId): launch directly with --session <id>.
• Model/subagent/system prompt inputs are forwarded into OpenCode launch command.

4) ao send

• Resolves agent by project config; when session metadata indicates OpenCode and mapping missing, core send() attempts title-based discovery and persists mapping.
• Sends message through runtime plugin handle; fails if session/runtime cannot be resolved.
• Busy detection is plugin-driven (detectActivity).

5) ao status

• Uses project/default configured agent for session enrichment and activity checks.
• Must not fail solely because project default agent is opencode.
• Fallback mode (no config) uses claude-code for best-effort tmux introspection only.

6) ao session cleanup

• Never cleans up orchestrator sessions (by explicit role=orchestrator or -orchestrator suffix).
• For OpenCode sessions with mapped opencodeSessionId:
  • on cleanup kill path, delete corresponding OpenCode session first, then archive AO session metadata.
  • archived sessions with mapping are cleaned once; opencodeCleanedAt prevents repeated deletion attempts.
• If OpenCode delete returns "session not found", treat as already cleaned.

7) ao session restore

• For OpenCode session restore, mapping is required.
• If mapping missing:
  • attempt title discovery using longer interactive timeout.
  • if still missing, fail with non-restorable error (OpenCode session mapping is missing).
• Restore must recreate runtime with preserved metadata/session fields and keep mapping persisted.

8) ao session remap

• Only valid for OpenCode sessions.
• remap(session, force=false):
  • reuse existing mapping if present; otherwise discover and persist.
• remap(session, force=true):
  • always re-discover by title and overwrite persisted mapping.
• If discovery fails, return explicit mapping-missing error.

Edge Cases and Expected Outcomes

• OpenCode binary missing: OpenCode-specific operations relying on opencode session ... discovery/deletion degrade gracefully where coded (discovery returns none), and explicit operations report mapping/deletion errors when required.
• Corrupted runtimeHandle metadata: send fails with Corrupted runtime handle.
• Existing orchestrator metadata present but runtime dead under reuse: restart runtime and pass mapped opencodeSessionId when available.
• Duplicate OpenCode sessions with same AO title: title match drives selection for remap/discovery (no timestamp ranking).
• Archived OpenCode sessions already cleaned: cleanup skips duplicate deletion via opencodeCleanedAt.
• Unknown project/agent: fail fast with clear error.

Revalidation Baseline (Current)

• Unit/integration validation that should remain green for OpenCode workflows:
  • @aoagents/ao-plugin-agent-opencode tests.
  • @aoagents/ao-core tests: session-manager.test.ts, plugin-registry.test.ts.
  • @aoagents/ao-cli tests: plugins.test.ts, start.test.ts, session.test.ts, send.test.ts, status.test.ts.
  • @aoagents/ao-integration-tests with test:integration (includes agent-opencode.integration.test.ts, conditionally skipped tests where prerequisites are unavailable).