fix(providers/opencode): address code review findings

- Add CHANGELOG.md entry for assistants.opencode provider (#1703)
- Elevate silent debug catches to warn level with context (session, multi-agent, runtime)
- Preserve error cause chain in retry loop (provider.ts)
- Include retry count in final throw message
- Fix doc typo: cofnig -> config
- Update CLAUDE.md monorepo layout with community/opencode/

Author: cropse0219

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`assistants.opencode` provider**: community provider that runs OpenCode as an embedded runtime, with per-node agent materialization, multi-agent sessions, structured output, token usage, and multi-agent MCP tool execution (#1703).
 - MCP server support for Codex workflow nodes via the shared `loadMcpConfig` module — pass `mcp: <path>` on a Codex node and the config is translated to Codex's `mcp_servers` overrides at runtime. MCP client errors are surfaced to the workflow author as `system` chunks when MCP is explicitly configured for the node (#1459).
 
 ## [0.3.12] - 2026-05-14

CLAUDE.md

@@ -285,6 +285,7 @@ packages/
 │       ├── claude/           # ClaudeProvider + parseClaudeConfig + MCP/hooks/skills translation
 │       ├── codex/            # CodexProvider + parseCodexConfig + binary-resolver
 │       ├── community/pi/     # PiProvider (builtIn: false) — @mariozechner/pi-coding-agent, ~20 LLM backends
+│       ├── community/opencode/ # OpenCodeProvider (builtIn: false) — @archon/opencode SDK, local embedded runtime
 │       └── index.ts          # Package exports
 ├── core/                     # @archon/core - Shared business logic
 │   └── src/

packages/docs-web/src/content/docs/getting-started/ai-assistants.md

@@ -286,7 +286,7 @@ assistants:
 | Tool restrictions | ✅ | `tools` / `disallowedTools` per agent; deny wins over allow |
 | Inline agents (`agents:`) | ✅ | File-materialized agents; single and parallel multi-agent fan-out |
 | Hooks | ✅ | Plugin hook system (tool, session, message hooks) |
-| Effort / reasoning control | ❌ | No per-request param; not configurable in agent file, opencode put it in cofnig file. |
+| Effort / reasoning control | ❌ | No per-request param; not configurable in agent file, opencode puts it in config. |
 | Thinking control | ❌ | No explicit `thinking` field in agent frontmatter; OpenCode auto-enables reasoning when `agents[].model` is a reasoning-capable model (e.g. `anthropic/claude-sonnet-4-5`) |
 | Fallback model | ❌ | No native failover in the SDK |
 | Sandbox | ❌ | Not native in the SDK; Archon uses worktree isolation |

packages/providers/src/community/opencode/multi-agent.ts

@@ -55,10 +55,7 @@ async function readStructuredOutput(
       return info.structured_output;
     }
   } catch (error) {
-    getLog().debug(
-      { err: error, sessionId, messageId },
-      'opencode.structured_output_lookup_failed'
-    );
+    getLog().warn({ err: error, sessionId, messageId }, 'opencode.structured_output_lookup_failed');
   }
   return undefined;
 }

packages/providers/src/community/opencode/provider.ts

@@ -199,13 +199,16 @@ export class OpencodeProvider implements IAgentProvider {
         const delayMs = this.retryBaseDelayMs * 2 ** attempt;
         getLog().info({ attempt, delayMs, errorClass }, 'opencode.retrying_query');
         await delay(delayMs);
+        if (lastError) {
+          enrichedError.cause = lastError;
+        }
         lastError = enrichedError;
       } finally {
         runtime.release();
       }
     }
 
-    throw lastError ?? new Error('OpenCode query failed after retries');
+    throw lastError ?? new Error(`OpenCode query failed after ${MAX_RETRIES} retries`);
   }
 
   getType(): string {

packages/providers/src/community/opencode/runtime.ts

@@ -123,7 +123,7 @@ function killProcess(pid: number): void {
       process.kill(pid, 'SIGKILL');
     }
   } catch (error) {
-    getLog().debug({ err: error, pid }, 'opencode.process_kill_failed');
+    getLog().warn({ err: error, pid }, 'opencode.process_kill_failed');
   }
 }
 
@@ -270,7 +270,7 @@ export async function disposeInstanceForDirectory(
   try {
     await client.instance.dispose({ query: { directory } });
   } catch (error) {
-    getLog().debug(
+    getLog().warn(
       {
         err: error,
         directory,

packages/providers/src/community/opencode/session.ts

@@ -38,8 +38,8 @@ export async function resolveSessionId(
       if (typeof sessionId === 'string' && sessionId.length > 0) {
         return { sessionId, resumed: true };
       }
-    } catch {
-      // Fall through to fresh session creation and surface a warning upstream.
+    } catch (error) {
+      getLog().warn({ err: error, resumeSessionId, cwd }, 'opencode.session_resume_failed');
     }
   }
 
@@ -110,10 +110,7 @@ async function readStructuredOutput(
       return info.structured_output;
     }
   } catch (error) {
-    getLog().debug(
-      { err: error, sessionId, messageId },
-      'opencode.structured_output_lookup_failed'
-    );
+    getLog().warn({ err: error, sessionId, messageId }, 'opencode.structured_output_lookup_failed');
   }
 
   return undefined;