Repository navigation
feat: Squad 2.0 decoupled backend and multi-host client adapters (Claude, Kiro, OpenCode, Cursor, Codex, Antigravity) - #2238
Closed
tamirdresher wants to merge 47 commits into
Closed
tamirdresher wants to merge 47 commits into
tamirdresher wants to merge 47 commits into
Conversation
Add SquadBackend contract with versioned envelope protocol, local and durable-http backends, harness registry, capability negotiation, versioned approvals, cancel-by-runId, and squad_backend_* MCP transport adapter. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Add security/isolation proposal and executable contract suite covering path/MCP/epoch guards, configured-vs-negotiated capabilities, versioned approvals with runId cancellation, loss-tolerant projection, and the golden cross-adapter conformance trace. Include packages/squad-sdk tests in vitest config. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Add ClientAdapter/ProjectionFile architecture in squad-sdk (copilot, claude, kiro, opencode, cursor) with host-agnostic coordinator core, per-host dispatch sections, declared ClientCapabilities, resolveEffectiveCapabilities, and portable clients[] sanitization. Non-clobbering JSON/marker-block merging. CLI: --client <list|all> on init and upgrade, persisted to .squad/config.json clients[]; upgrade refreshes configured clients. Tests in test/clients.test.ts. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Bring Brady's specification suite updates into the Squad 2.0 worktree, add the new v0.2 client/backend and client/harness protocol specs, and freeze the rc1 protocol baseline with ADR and immutable fixtures. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…store clobbered spec docs Backend capabilities now use the v0.2 capability-matrix vocabulary; lastAcceptedSeq is the last accepted event sequence; conversation.created no longer leaks the lease epoch; MCP send_message accepts typed parts without content. Restore Charter/Core/Ceremony/Governance/Interop/README/inventory docs that the spec branch regressed to older revisions, keeping only the v0.2 profile additions. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…ebase Covers client projections, capability intersection vs capability-matrix.json, LocalSquadBackend across 5 harnesses, DurableHttpSquadBackend against a mock DurableSquad, the MCP bridge on local and durable-http, and the normative golden trace. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Closes github#2069 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…tion, clean-room) Add uninstallClients/removeProjection for clean rollback of client projections, make harness event delivery idempotent (duplicate/out-of-order), and rehydrate harness subscriptions for in-flight turns after a broker restart. New e2e tests cover v0.1 upgrade+rollback, partial/duplicate/shuffled delivery and restart with an approval in flight, and a clean-room client+harness checked against golden-trace.json and capability-matrix.json. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Project claude/opencode/kiro configs, parse them from disk, spawn state-mcp as a real child process over stdio JSON-RPC and exercise squad_state_* and all squad_backend_* tools including process restart and resume. Smoke-test installed claude/opencode/kiro binaries against the workspaces when present on PATH. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…I tests Real Kiro CLI resolves agent `resources` file:// paths against the workspace root (only `prompt` is relative to the agent config), so use file://.squad/team.md rather than ../../. Skip the Coordinator row when projecting Claude member subagents (it produced a bogus squad-squad agent). Add real-binary tests (claude, opencode, kiro-cli) that skip when absent. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…I tests Real Kiro CLI resolves agent `resources` file:// paths against the workspace root (only `prompt` is relative to the agent config), so use file://.squad/team.md rather than ../../. Skip the Coordinator row when projecting Claude member subagents (it produced a bogus squad-squad agent). Add real-binary tests (claude, opencode, kiro-cli) that skip when absent. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Codex: AGENTS.md managed block (id-scoped), .codex/config.toml [mcp_servers.squad_state] via a non-destructive TOML table merge (startup timeout defaulted to 60s for cold npx), .codex/agents/squad-<member>.toml. Antigravity: .agents/agents/squad.md (+ member subagents, mcpServers frontmatter) and a GEMINI.md block. Block markers can carry an id so several clients share one file. Real-binary tests for codex and agy; verified against codex-cli 0.163 and agy 1.4.0. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…le state Found with real models: opencode's Glob skipped .squad/ so the coordinator concluded no team existed and re-cast it over the real team; models also tried squad_state_write for team.md/routing.md/charters, which the state tools reject. Add a guarded Init Mode that decides via squad_state_read, never re-casts an existing team, and document static config as ordinary files. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…tigravity to capability matrix Make removeProjection handle text (TOML) projections and block ids introduced with the codex/antigravity adapters, add both clients to the v0.2 capability matrix fixture, and generalize the all-scenarios projection assertions to every client. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…e in shared prompt opencode now projects .opencode/agent/squad-<member>.md (mode: subagent); claude/opencode/codex/antigravity member agents accept an optional model from .squad/config.json clientModels (per client, per member slug, '*' wildcard; values validated). Shared coordinator prompt gains host-agnostic Ralph mode (coordinator-driven gh scan/route/PR loop). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…lot prompt Shared prompt now carries Response Mode Selection, Scribe drop-box protocol, reviewer rejection + strict lockout, Rai traffic light, Fact Checker + devil's advocate, ceremonies, 5-root skill-aware routing, memory/state handshake, GitHub Issues + PRD mode, cross-squad delegation, human/@copilot members, anti-patterns, Ralph mode, and a guarded Init Mode (auto-confirm, no glob on .squad, scratch dir, cast via 'squad cast', never hand-edit the checksummed casting registry, stop after casting). Verified live with Claude Code: headless 'proceed' now casts in one turn, Scribe merges the inbox; hand-written casting registry broke 'squad upgrade', hence the cast-CLI rule. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…y image name Found in live Claude demos: Ralph ran taskkill /IM node.exe (killed its own proxy) and Claude left embedded worktree repos that broke git add. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
- squad cast --sync registers hand-written team.md members in the checksummed casting registry (idempotent); prompt uses it when 'cast --name' is unavailable (old npx-cached squad). - Antigravity agents declare tools (omitted list = none: agent had no shell, Ralph could not use gh). - Member slugs normalize diacritics consistently in adapters and cast. Found in live Kiro/Antigravity/interactive-Claude (cli-tunnel) runs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…idence, claude --mcp-config note Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…s, explicit fallback From reviewer feedback on live runs: model asked for squad_state_read but hosts expose prefixed names; directory keys read as files (EISDIR); Scribe/Ralph/Rai/Fact Checker subagents missing when team.md was rewritten; silent owner substitution. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…shed via claude-sonnet-4-6 model, per-model quota) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Default is now a single coordinator file per host, like Copilot. Member subagent files are projected only with --member-agents, config.json memberAgents: true, or when clientModels is configured. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Hosts now use only .squad/agents/<name>/charter.md (inlined into generic subagent spawns), like Copilot. Removes member/clientModels projection, --member-agents, roster parsing and the accent-stripping slug change. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
… evidence --sync was added in this branch and is not needed: the coordinator registers members with squad cast --name. Screenshots show the interactive Claude session (via cli-tunnel) casting, building in parallel and Scribe merging. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…igravity Fresh repos, squad init --client X, casting with squad cast --name, parallel build. Antigravity's build step hit the per-model quota; Kiro is unavailable (monthly limit). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…ames Adds phase captions and a permissive-mode disclaimer to the interactive screenshots, plus restart/recovery + Scribe-merge frames for opencode and Codex (replacing the mid-"Working" Codex ending). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…issues, Ralph) Fresh private repo tamirdresher/squad-ralph-claude: init -> cast for the project -> parallel build -> two squad-labelled issues -> "Ralph, go" until both PRs merged (34/34 tests on main). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
… layout, capability tokens
Per Bubu's green light on the spec-alignment questions:
- HostProjection is the pure workspace projection (no runtime dependency);
ClientAdapter (client/adapter-contract.ts) is the thin spec-compliant facade
(describe, projectWorkspace, getCapabilities; submit/subscribe/cancel/
respondApproval delegate to a bound runtime, else AdapterUnboundError).
- Canonical home is packages/squad-sdk/src/client/{adapter-contract.ts,adapters/};
src/clients re-exports the exact same symbols (deprecated).
- Canonical string[] capability tokens are authoritative; boolean flags are a
derived view; conflicting token+flag input throws. Advertised capabilities
stay separate from negotiated effective capabilities.
- Update stale e2e tests for coordinator-only projection and prompt wording.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…alph blocked by usage limit) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…he fork branch) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Contributor
🔴 Impact Analysis — PR #2238Risk tier: 🔴 CRITICAL 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (15 files)
root (8 files)
squad-cli (7 files)
squad-sdk (20 files)
tests (8 files)
|
Contributor
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 47 commits — consider squashing before review |
| ✅ | Not in draft | Ready for review |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | Changeset file found |
| ✅ | Scope clean | |
| ✅ | No merge conflicts | No merge conflicts |
| ❌ | Copilot threads resolved | 3 unresolved Copilot thread(s) — fix and resolve before merging |
| ❌ | CI passing | 6 check(s) still running |
Files Changed (58 files, +10685 −16)
| File | +/− |
|---|---|
.changeset/squad-2-0-multi-host-clients.md |
+6 −0 |
CONTRIBUTING.md |
+11 −0 |
README.md |
+13 −2 |
cspell.json |
+3 −0 |
docs/SQUAD-2.0-OVERVIEW.md |
+333 −0 |
docs/proposals/squad-2.0-security-and-isolation.md |
+103 −0 |
docs/specification/README.md |
+6 −0 |
docs/specification/adr-001-client-control-execution-boundary.md |
+59 −0 |
docs/specification/client-backend-decoupling-v0.2.md |
+487 −0 |
docs/specification/client-harness-adapters-v0.2.md |
+481 −0 |
docs/src/content/docs/concepts/squad-2-0-architecture.md |
+145 −0 |
docs/src/content/docs/reference/cli.md |
+2 −0 |
docs/src/content/docs/reference/config.md |
+2 −0 |
docs/src/content/docs/reference/sdk.md |
+9 −0 |
docs/src/content/docs/scenarios/client-compatibility.md |
+2 −0 |
docs/src/content/docs/scenarios/using-squad-across-clients.md |
+127 −0 |
docs/src/navigation.ts |
+2 −0 |
docs/tutorials/durable-backend-and-custom-harness.md |
+390 −0 |
docs/tutorials/multi-client-quickstart.md |
+361 −0 |
packages/squad-cli/src/cli-entry.ts |
+22 −2 |
packages/squad-cli/src/cli/commands/state-mcp.ts |
+20 −5 |
packages/squad-cli/src/cli/core/backend-mcp.ts |
+201 −0 |
packages/squad-cli/src/cli/core/clients.ts |
+101 −0 |
packages/squad-cli/src/cli/core/command-help.ts |
+2 −0 |
packages/squad-cli/src/cli/core/init.ts |
+30 −2 |
packages/squad-cli/src/cli/core/upgrade.ts |
+36 −2 |
packages/squad-sdk/package.json |
+8 −0 |
packages/squad-sdk/src/backend/durable-http-backend.ts |
+232 −0 |
packages/squad-sdk/src/backend/harness-registry.ts |
+47 −0 |
packages/squad-sdk/src/backend/index.ts |
+27 −0 |
packages/squad-sdk/src/backend/local-backend.ts |
+620 −0 |
packages/squad-sdk/src/backend/types.ts |
+415 −0 |
packages/squad-sdk/src/casting/handwritten-registry.ts |
+261 −0 |
packages/squad-sdk/src/casting/index.ts |
+10 −0 |
packages/squad-sdk/src/client/adapter-contract.ts |
+201 −0 |
packages/squad-sdk/src/client/adapters/adapters.ts |
+334 −0 |
packages/squad-sdk/src/client/adapters/apply.ts |
+363 −0 |
packages/squad-sdk/src/client/adapters/capabilities.ts |
+120 −0 |
packages/squad-sdk/src/client/adapters/coordinator.ts |
+108 −0 |
packages/squad-sdk/src/client/adapters/index.ts |
+6 −0 |
packages/squad-sdk/src/client/adapters/portable.ts |
+49 −0 |
packages/squad-sdk/src/client/adapters/types.ts |
+82 −0 |
packages/squad-sdk/src/client/index.ts |
+5 −0 |
packages/squad-sdk/src/clients/index.ts |
+9 −0 |
packages/squad-sdk/src/config/init.ts |
+4 −1 |
packages/squad-sdk/src/index.ts |
+3 −0 |
test-fixtures/spec/suite-v0.1/index.json |
+38 −0 |
test-fixtures/spec/suite-v0.2/capability-matrix.json |
+155 −0 |
test-fixtures/spec/suite-v0.2/golden-trace.json |
+63 −0 |
test/backend.test.ts |
+791 −0 |
| ... | +8 more files |
Total: +10685 −16
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
🏗️ Architectural Review
Automated architectural review — informational only. |
…c/capability-matrix updates, casting registry repair/backfill, 126-test e2e suite) Tree equals squad/2.0 (e74920c) minus docs/demos/squad-2.0-clients/ (kept off the upstream PR). Fixes test/cli-command-wiring.test.ts by moving the internal backend-mcp helper to cli/core/. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved filesystem confinement, lease fencing, lifecycle recovery, and concurrent persistence defects block safe adoption.
19 open issues
What changed in this PR
Introduces Squad 2.0’s shared backend contract and native projections for seven client hosts, separating host integration from conversation state and execution.
Changes:
- Adds backend contracts, local/HTTP implementations, and MCP transport tools.
- Adds host adapters and persistent
--clientsupport for initialization and upgrades. - Adds specifications, conformance fixtures, CLI checks, and tutorials.
| File | Description |
|---|---|
| vitest.config.ts | Resolves SDK source and includes SDK tests. |
| test/specification-suite.test.ts | Registers new specification documents. |
| test/docs-build.test.ts | Adds expected documentation pages. |
| test/clients-real-cli.test.ts | Checks projections with installed host CLIs. |
| test-fixtures/spec/suite-v0.2/golden-trace.json | Defines recovery and cancellation trace. |
| test-fixtures/spec/suite-v0.2/capability-matrix.json | Defines capability negotiation baseline. |
| test-fixtures/spec/suite-v0.1/index.json | Registers draft profiles. |
| packages/squad-sdk/src/index.ts | Exports backend APIs. |
| packages/squad-sdk/src/clients/index.ts | Provides compatibility re-exports. |
| packages/squad-sdk/src/client/index.ts | Exports client adapter APIs. |
| packages/squad-sdk/src/client/adapters/types.ts | Defines host projection types. |
| packages/squad-sdk/src/client/adapters/portable.ts | Normalizes portable client identifiers. |
| packages/squad-sdk/src/client/adapters/index.ts | Exports projection utilities. |
| packages/squad-sdk/src/client/adapters/coordinator.ts | Adds shared and host-specific instructions. |
| packages/squad-sdk/src/client/adapters/capabilities.ts | Defines capabilities and intersection helpers. |
| packages/squad-sdk/src/client/adapters/apply.ts | Applies and removes projected files. |
| packages/squad-sdk/src/client/adapters/adapters.ts | Implements seven host projections. |
| packages/squad-sdk/src/client/adapter-contract.ts | Defines runtime-bound client adapters. |
| packages/squad-sdk/src/backend/types.ts | Defines backend and harness contracts. |
| packages/squad-sdk/src/backend/local-backend.ts | Implements local conversation persistence and lifecycle. |
| packages/squad-sdk/src/backend/index.ts | Exports APIs and backend factory. |
| packages/squad-sdk/src/backend/harness-registry.ts | Registers harnesses and validates extensions. |
| packages/squad-sdk/src/backend/durable-http-backend.ts | Implements remote HTTP backend client. |
| packages/squad-sdk/package.json | Exposes clients and backend entrypoints. |
| packages/squad-cli/src/cli/core/upgrade.ts | Refreshes configured client projections. |
| packages/squad-cli/src/cli/core/init.ts | Projects requested clients during initialization. |
| packages/squad-cli/src/cli/core/command-help.ts | Documents client flags. |
| packages/squad-cli/src/cli/core/clients.ts | Parses, persists, and synchronizes clients. |
| packages/squad-cli/src/cli/commands/state-mcp.ts | Exposes backend tools through MCP. |
| packages/squad-cli/src/cli/commands/backend-mcp.ts | Translates MCP calls into backend operations. |
| packages/squad-cli/src/cli-entry.ts | Wires client options into CLI commands. |
| docs/tutorials/multi-client-quickstart.md | Explains multi-host setup. |
| docs/tutorials/durable-backend-and-custom-harness.md | Demonstrates backend and harness integration. |
| docs/src/navigation.ts | Links new documentation pages. |
| docs/src/content/docs/scenarios/using-squad-across-clients.md | Adds multi-client walkthroughs. |
| docs/src/content/docs/scenarios/client-compatibility.md | Links Squad 2.0 guidance. |
| docs/src/content/docs/concepts/squad-2-0-architecture.md | Explains architectural boundaries. |
| docs/SQUAD-2.0-OVERVIEW.md | Summarizes architecture and conformance goals. |
| docs/specification/README.md | Registers profiles and dependencies. |
| docs/specification/client-harness-adapters-v0.2.md | Specifies adapter responsibilities. |
| docs/specification/client-backend-decoupling-v0.2.md | Specifies portable backend semantics. |
| docs/specification/adr-001-client-control-execution-boundary.md | Records architectural decisions. |
| docs/proposals/squad-2.0-security-and-isolation.md | Defines proposed security and isolation gates. |
Review effort: Balanced
- move squad-20-security-contracts test under test/ so eslint's project service finds it - add changeset (Policy Gates: changelog) and cspell words (kiro, affordances, Bubu, resumability) - docs: --client in README, CLI/config/SDK references, scenarios page (Codex, Antigravity, troubleshooting, no per-member files), quickstart tutorials, CONTRIBUTING adapter checklist Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…e fixtures from docs/tests Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…ngeset Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
tamirdresher
force-pushed
the
squad/2.0-client-adapters-pr
branch
from
October 18, 2026 17:48
cd92b26 to
cb86aef
Compare
- containment guard (no ../, absolute or symlinked components) for install/uninstall - forward --client on 'init --mode remote' - never overwrite a malformed .squad/config.json when persisting clients - reject wrong-typed MCP containers/entries instead of replacing them - TOML: replace multiline arrays whole, tolerant headers, remove sub-tables on uninstall - keep the shared .mcp.json entry while another host still uses it (uninstallClients keep) - apply squadDir to the dispatch section as well Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…11 comments) Symlink-safe file store, cross-process lock + single-transaction state changes, epoch fencing for harness events and omitted epochs, retryable approval/cancel delivery, run-identity lookups, approval cancel versioning, idempotent HTTP createConversation, per-conversation learned epochs. 10 regression tests; fix duplicate imports in test/clients.test.ts. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
…, restart, lost response, per-conversation epochs, symlink parents) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 995eea17-c356-4912-90ea-5e5b144e7ba9
Collaborator
Author
|
Superseded by #2239 (same commits, moved to the in-repo branch squad/2.0-preview). Copilot's 19 review comments on this PR are all addressed there. Closing this one. |
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
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.
Squad 2.0: decoupled backend + multi-host client adapters
Squad can now run natively in Claude Code, Kiro, OpenCode, Cursor, OpenAI Codex and Google Antigravity (plus Copilot), with the host client decoupled from the state/backend. Hosts own native bootstrap/projection and capability declaration; conversation semantics, routing, durable state and authorization stay in the shared backend contract. MCP (
squad_state) is a local tool transport bridge behind that contract, not the wire contract.This branch is the integrated Squad 2.0 line (over
dev), so it carries the earlier backend/spec work as well as the client adapters.Reviewer map (suggested order: spec → interfaces → backend → projections → CLI → tests → docs)
docs/specification/client-backend-decoupling-v0.2.md,docs/specification/client-harness-adapters-v0.2.md,docs/specification/adr-001-client-control-execution-boundary.md, normative fixturestest-fixtures/spec/suite-v0.2/capability-matrix.jsonandtest-fixtures/spec/suite-v0.2/golden-trace.json.packages/squad-sdk/src/backend/types.ts(SquadBackend, envelope/cursor/error/capability types,HarnessAdapterSPI) andpackages/squad-sdk/src/client/adapter-contract.ts(ClientAdapterfacade,AdapterUnboundError,createClientAdapter).packages/squad-sdk/src/backend/local-backend.ts,durable-http-backend.ts,harness-registry.ts,index.ts(createSquadBackend); the MCP transport adapterpackages/squad-cli/src/cli/core/backend-mcp.tswired throughpackages/squad-cli/src/cli/commands/state-mcp.ts.packages/squad-sdk/src/client/adapters/{types,adapters,capabilities,apply,portable,coordinator}.ts; casting-registry repair/backfill inpackages/squad-sdk/src/casting/handwritten-registry.ts.packages/squad-cli/src/cli/core/clients.ts,init.ts,upgrade.ts,packages/squad-cli/src/cli-entry.ts,packages/squad-cli/src/cli/commands/cast.ts.test/specification-suite.test.ts,test/backend.test.ts,test/clients.test.ts,test/clients-real-cli.test.ts,test/squad-20-security-contracts.test.ts,test/squad-20-all-scenarios.e2e.test.ts,test/squad-20-real-clients-stdio.e2e.test.ts,test/docs-build.test.ts,test/cli-command-wiring.test.ts.docs/SQUAD-2.0-OVERVIEW.md,docs/tutorials/multi-client-quickstart.md,docs/tutorials/durable-backend-and-custom-harness.md,docs/src/content/docs/concepts/squad-2-0-architecture.md,docs/src/content/docs/scenarios/using-squad-across-clients.md,docs/proposals/squad-2.0-security-and-isolation.md.What's in it
packages/squad-sdk/src/backend/): decoupled backend, harness SPI, MCP bridge, security/conformance contracts, RC1-to-stable exit-criteria tests.packages/squad-sdk/src/client/):HostProjection: pure workspace projection forcopilot,claude,kiro,opencode,cursor,codex,antigravity(no runtime dependency).ClientAdapter(adapter-contract.ts): thin spec-compliant facade (describe,projectWorkspace,getCapabilities;submit/subscribe/cancel/respondApprovaldelegate to a bound runtime, otherwiseAdapterUnboundError).string[]capability tokens are authoritative; booleanClientCapabilitiesflags are a derived view (conflicts throw). Advertised vs negotiated (effectiveCapabilities= client ∩ backend ∩ policy) kept separate.@bradygaster/squad-sdk/clientsre-exports the same symbols..mcp.json,.kiro/settings/mcp.json,opencode.json,.cursor/mcp.json,.codex/config.tomlsurvivesquad upgrade.squad init --client <list|all>andsquad upgrade --client, persisted in.squad/config.jsonclients[](portable ids only; credentials/paths rejected). Hosts use only the coordinator file plus.squad/agents/<name>/charter.md(no per-member subagent files).docs/specification/*,docs/SQUAD-2.0-OVERVIEW.md, multi-client tutorials.Verification
npx vitest runovertest/cli-command-wiring.test.ts,test/specification-suite.test.ts,test/backend.test.ts,test/clients.test.ts,test/clients-real-cli.test.ts,test/squad-20-security-contracts.test.ts,test/squad-20-all-scenarios.e2e.test.ts(126 tests),test/squad-20-real-clients-stdio.e2e.test.ts,test/docs-build.test.ts; 17 conditional skips).test/clients-real-cli.test.tsruns the real claude, opencode, kiro, codex, agy and cursor-agent binaries against the generated config (run it alone if the machine is under load);squad-20-real-clients-stdio.e2espawns the realstate-mcpover stdio from each host's generated config.Known issues / caveats
test/cli-command-wiring.test.tsis fixed: the internalbackend-mcphelper moved fromcommands/tocli/core/backend-mcp.ts(it is imported bystate-mcp, not a CLI command). The spec deltas (7 hosts,HostProjection, capability tokens) are now inclient-harness-adapters-v0.2.mdandsuite-v0.2/capability-matrix.json.casting/handwritten-registry.ts), non-TTY-safesquad initprompts, and.gitignoreentries for.claude/worktrees/andNUL.npm run buildreports pre-existing@github/copilot-sdktyping errors insrc/adapter/client.ts;tscstill emits.squad(0.13.x) on PATH has a stubcast --name; the local build must come first on PATH.squad initlinks repos to a personal squad when one exists (existing behaviour; setSQUAD_NO_PERSONAL=1for clean demos).