docs: add OpenCode server integration specification#94
Merged
khaliqgant merged 3 commits intomainfrom Jan 10, 2026
Merged
Conversation
Detailed spec for integrating OpenCode server capabilities with agent relay: - OpenCodeWrapper class using HTTP API instead of PTY - WrapperFactory for automatic backend selection - Session forking for context inheritance between agents - mDNS discovery for multi-host coordination - Dashboard API extensions for OpenCode features The spec includes component interfaces, data flows, implementation phases, and testing strategy for seamless integration.
Expands the OpenCode integration spec with: - Cloud production architecture diagram - OpenCode as provider type with credential management - OpenCodeCloudWrapper for cloud-hosted instances - Cloud OpenCode Orchestrator design - CloudSyncService extensions for credential sync - Dashboard integration with provider settings - Cloud API specification with all endpoints - SSE event streaming from cloud - Updated implementation phases (5 phases) - Detailed open questions with recommendations The goal is seamless UX: user connects OpenCode provider, agents work automatically with no config changes needed.
- Add 6 detailed user flow diagrams with ASCII art: 1. First-time OpenCode setup (cloud) 2. Spawning an agent with OpenCode 3. Agent-to-agent communication 4. Session forking (context inheritance) 5. Local OpenCode server (no cloud) 6. BYOK (bring your own keys) setup - Fix authentication model confusion: - OpenCode Zen uses API key (not OAuth) - BYOK uses underlying provider OAuth (Anthropic/OpenAI) - Updated OpenCodeProvider code with connectWithZenApiKey() - Add authentication model summary table - Add spec review section documenting: - What the proposal does well - Issues identified and fixed - Remaining considerations - Architecture validation - Recommended implementation order
khaliqgant
added a commit
that referenced
this pull request
Feb 18, 2026
…low definitions Three major additions to the workflows spec: 1. Reflection Protocol — event-driven reflection inspired by the Generative Agents paper (Park et al., 2023). Importance-weighted message accumulation triggers focal point generation, synthesis, and course correction. Includes ReflectionEngine implementation, REFLECT message protocol, and per-pattern reflection behavior. 2. Trajectory Integration — formal integration with the agent-trajectories SDK (v0.4.0). Workflows auto-record messages, reflections, and decisions as trajectory events. Auto-generates retrospectives on completion. Enables cross-workflow learning and compliance/attribution. 3. YAML Workflow Definitions — portable YAML schema for defining workflows, compatible with relay-cloud's relay.yaml (PR #94). Supports template variables, DAG-based step parallelism, built-in templates, and progressive configuration (one-liner to full custom). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
khaliqgant
added a commit
that referenced
this pull request
Feb 18, 2026
DAG-based execution plan with 9 nodes covering shared types, DB migration, workflow runner, swarm coordinator, templates, API endpoints, CLI commands, dashboard panel, and integration tests. Uses broker SDK for agent lifecycle. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
khaliqgant
added a commit
that referenced
this pull request
Feb 18, 2026
…tor script Adds stigmergic state store, agent pool manager, auction engine, branch pruner, and gossip disseminator to WORKFLOWS_SPEC.md (Phase 5). These bring coverage from 67% to 88% of the 42 swarm techniques catalogued from multi-agent orchestration literature. Also adds executable broker SDK script (scripts/run-swarm-implementation.ts) that uses a DAG pattern to coordinate 9 work nodes implementing relay-cloud PR #94, with dependency-aware parallel execution and convention injection. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
khaliqgant
added a commit
that referenced
this pull request
Feb 18, 2026
* sdk workflow spec * spec: add reflection protocol, trajectory integration, and YAML workflow definitions Three major additions to the workflows spec: 1. Reflection Protocol — event-driven reflection inspired by the Generative Agents paper (Park et al., 2023). Importance-weighted message accumulation triggers focal point generation, synthesis, and course correction. Includes ReflectionEngine implementation, REFLECT message protocol, and per-pattern reflection behavior. 2. Trajectory Integration — formal integration with the agent-trajectories SDK (v0.4.0). Workflows auto-record messages, reflections, and decisions as trajectory events. Auto-generates retrospectives on completion. Enables cross-workflow learning and compliance/attribution. 3. YAML Workflow Definitions — portable YAML schema for defining workflows, compatible with relay-cloud's relay.yaml (PR #94). Supports template variables, DAG-based step parallelism, built-in templates, and progressive configuration (one-liner to full custom). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * spec: add 5 new workflow patterns and primitives audit New patterns (6-10): - handoff: dynamic routing with circuit breaker (max hops) - cascade: cost-aware LLM escalation (cheap → capable) - dag: directed acyclic graph with parallel execution - debate: adversarial refinement with structured rounds + judge - hierarchical: multi-level delegation tree (lead → coordinators → workers) New primitives required: - DAG Scheduler (topological sort, parallel dispatch, join tracking) - Handoff Controller (active agent tracking, context transfer) - Round Manager (debate rounds, turn order, convergence detection) - Confidence Parser (extract [confidence=X.X] from DONE messages) - Tree Validator (structural validation, sub-team computation) New message protocol signals: - HANDOFF, CONFIDENCE, ARGUMENT, CONCEDE, VERDICT, TEAM_DONE Includes pattern × primitive matrix showing what each pattern needs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add choosing-swarm-patterns skill with 10 orchestration patterns Decision framework and reference for fan-out, pipeline, hub-spoke, consensus, mesh, handoff, cascade, dag, debate, and hierarchical patterns. Includes reflection protocol, YAML workflow definitions, and common mistakes guide. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: add implementation plan for relay-cloud PR #94 DAG-based execution plan with 9 nodes covering shared types, DB migration, workflow runner, swarm coordinator, templates, API endpoints, CLI commands, dashboard panel, and integration tests. Uses broker SDK for agent lifecycle. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add 5 extended primitives for 42-technique coverage + DAG executor script Adds stigmergic state store, agent pool manager, auction engine, branch pruner, and gossip disseminator to WORKFLOWS_SPEC.md (Phase 5). These bring coverage from 67% to 88% of the 42 swarm techniques catalogued from multi-agent orchestration literature. Also adds executable broker SDK script (scripts/run-swarm-implementation.ts) that uses a DAG pattern to coordinate 9 work nodes implementing relay-cloud PR #94, with dependency-aware parallel execution and convention injection. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: apply DAG executor improvements from review feedback Script fixes: - Use Promise.allSettled instead of Promise.race for batch execution - Add --resume support with state persistence to .relay/swarm-impl-state.json - Propagate failures to downstream nodes immediately (mark as "blocked") - Add readFirst field to DAG nodes so agents read existing code first - Require detailed DONE messages with type signatures and file paths - Add resolved guard to prevent double-resolution in polling loop - Add "blocked" status to NodeResult for better reporting Skill updates: - Add "DAG Executor Pitfalls" section with 6 common implementation mistakes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: use agent-relay CLI positional args for DAG executor Updated spawn/send/release/logs commands to match actual CLI syntax (positional args, not --flag format). Verified with --dry-run. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * refactor: use @agent-relay/broker-sdk instead of CLI shell-outs Import AgentRelayClient, getLogs, and BrokerEvent directly from the broker SDK sub-paths (client, logs, protocol) which avoid the @relaycast/sdk transitive dependency. Replaces all execSync calls with proper SDK methods: spawnPty, release, listAgents, onEvent. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: point broker SDK client at Rust binary (target/debug/agent-relay) The AgentRelayClient expects the Rust broker binary which has init --name --channels for protocol mode. The Node.js CLI binary has a different init command (setup wizard). Built Rust binary with cargo build and pointed binaryPath to target/debug/agent-relay. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: use unique broker name to avoid Relaycast 409 workspace conflict The Relaycast API returns 409 when creating a workspace with a name that already exists. Without cached credentials the broker can't recover. Use a timestamped broker name to ensure uniqueness. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: use broker events (worker_stream/relay_inbound) instead of log polling The Rust broker doesn't write worker-logs/ files — that's a Node.js CLI feature. Switch watchForDone to use broker events: - worker_stream: accumulate PTY output chunks, scan for DONE/ERROR - relay_inbound: relay messages from agents - agent_exited: detect agent termination Remove unused getLogs import. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: use agent_exited as completion signal, relay messages for summaries Instead of parsing PTY output for DONE signals (which matched the prompt template text), agents now: 1. Do their work 2. Send a relay message with "DONE: <summary>" to the workflow channel 3. Exit naturally The orchestrator watches for: - relay_inbound: captures DONE/ERROR summaries for downstream deps - agent_exited: definitive completion signal (code 0 = success) Removed all "DONE: <detailed summary>" template text from task prompts to prevent false positives. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: use summary files instead of relay messages for agent output Spawned PTY agents don't have MCP relay tools, so they can't send relay messages. Instead, agents now write their summary to .relay/summaries/{nodeId}.md before exiting. The orchestrator waits for agent_exited, then reads the summary file for downstream deps. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: add 4 new DAG executor pitfalls from real execution failures New pitfalls from running the swarm implementation script: - PTY prompt echo matching signal keywords (false DONE completion) - Assuming agent capabilities (PTY agents lack MCP tools) - Rust broker vs Node.js CLI binary confusion - Log polling assumes Node.js daemon (Rust broker doesn't write logs) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * sdk based workflows * remove specs * relay workflows * sdk for workflows * exclude tests * remove validation * fixes * pr review * run any language * fix: address remaining devin review comments - runner.ts: executeStep now throws after marking step failed, enabling fail-fast/continue error strategies to trigger via Promise.allSettled - cli/index.ts: runScriptFile now only catches ENOENT errors, properly propagating script execution failures instead of trying next runner Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * docs: add telemetry disclosure document Similar to Wrangler's telemetry.md, this document explains: - What data is collected and why - What is explicitly NOT collected - How to opt out (CLI, env var, config file) - How to view telemetry events for debugging Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Agent Relay <agent@agent-relay.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Detailed spec for integrating OpenCode server capabilities with agent relay:
The spec includes component interfaces, data flows, implementation phases,
and testing strategy for seamless integration.