# Run coding agents through ACP in Harness Studio ## Traceability - Spec ID: harness-studio-acp-live-runs - Status: Implemented ## Intent Allow the Harness Studio Debugger to start a real local coding-agent session through stable ACP v1 while preserving the existing Harness compile/resolve boundary and AG-UI browser projection. The Studio server, rather than browser JavaScript, owns the local Agent process, ACP connection, workspace root, permission decisions, cancellation, and protocol evidence. ## Acceptance Scenarios - AC-1: When Studio is configured with an allowlisted ACP Agent command, the Debugger composer offers that Agent alongside the existing workspace-default Qoder runtime. When no ACP Agent is configured, no ACP control or endpoint is advertised. - AC-2: Starting an ACP run launches the configured command with an argv array, negotiates stable ACP v1, creates a session rooted at the selected local workspace, submits the harness-prefixed prompt, and projects the resulting assistant and Tool Call updates through the existing live Debugger. - AC-3: Studio retains a bounded, credential-redacted protocol trace containing real ACP directions, methods, session ids, request ids, and payloads. The live State Inspector labels this as ACP evidence and does not construct synthetic `run/*` methods for an ACP run. - AC-4: An ACP `session/request_permission` request appears in the live State Inspector with only the Agent-provided bounded choices. A same-origin decision route resolves that exact pending request; disconnect, cancellation, and timeout resolve it as cancelled rather than auto-approving an action. - AC-5: Cancelling an active ACP run sends `session/cancel`, allows a bounded cooperative shutdown window, then closes an unresponsive Agent process and terminates the browser stream with an honest cancelled/error state. Qoder runs retain their existing behavior. - AC-6: ACP is an honest prompt-session adapter. It delivers Harness skills in the prompt preamble but exposes no standard Harness tool or MCP capability merely because an Agent implements ACP; tool requirements therefore continue to fail closed during resolution. - AC-7: Focused adapter, protocol projection, server, and browser tests prove initialization, workspace rooting, updates, permission decisions, cancellation, redaction, missing-command failure, and the unchanged Qoder path on macOS/Linux/Windows-compatible Node APIs. ## Non-goals - Adding a generic browser-to-stdio bridge or accepting an arbitrary executable, argv, environment, or workspace path from browser input. - Advertising ACP v2, remote ACP HTTP/WebSocket Agents, client-owned filesystem or terminal capabilities, session load/resume, or multi-turn chat in this first integration. - Treating ACP Tool Calls as proof that a Harness `require tool` contract was materialized. - Replacing AG-UI as the browser transport, changing saved historical Session ownership, or adding workspace restoration/replay semantics. - Changing the existing Qoder/Pi adapters, supported-host claims, release notes, versions, or changelog. ## Plan and Tasks 1. Add a prompt-only `@harness/adapter-acp` descriptor and an ACP v1 executor backed by the official TypeScript SDK. Use `node:child_process.spawn` with an argv array and Web Stream adapters for stdio. 2. Map ACP message chunks, Tool Calls, prompt completion, permission requests, and cancellation onto the neutral Harness run lifecycle plus a bounded protocol-evidence event. 3. Extend the AG-UI projection/store with namespaced ACP evidence while keeping existing AG-UI event behavior backward compatible. 4. Add an optional Studio ACP configuration, run/permission/cancel routes, and a per-run server registry that owns pending permission promises and abort state. 5. Add an ACP runtime choice and live permission/cancel/raw-evidence controls to the existing Debugger composer and State Inspector using shared design tokens. 6. Configure the repository-local workspace launcher for the installed `codex-acp` command without making the published server auto-execute discovered binaries. 7. Add deterministic fixture-Agent tests, then exercise the built Studio at wide, compact, and narrow widths with console/page-error and screenshot checks. ## Test and Review Evidence - AC-2/AC-3/AC-5/AC-6: focused `@qoder-ai/harness` tests using a deterministic ACP fixture process, plus adapter-registry and redaction assertions. - AC-2/AC-3: `@qoder-ai/harness-ui` translator/store tests for ACP protocol evidence and unchanged core AG-UI ordering. - AC-1/AC-4/AC-5: Harness Studio server tests with an injected ACP command and same-origin permission/cancel requests. - AC-1 through AC-5: built-app Playwright flow covering Agent selection, live updates, permission choice, cancellation, real Raw ACP metadata, keyboard focus, bounded overflow, and no browser console/page errors. - Package gates: focused typecheck/tests first, then package tests, root tests, `git diff --check`, the Markdown doc-link test, and the required preview health and `/canvas-module.js` smoke checks. - Risk: an ACP Agent is a real coding process. The executable is server-configured, the workspace root stays server-owned, browser requests are same-origin, no client filesystem/terminal capability is advertised, and permissions default to cancelled on every incomplete decision path. - Risk: protocol projection can overclaim raw fidelity. Each retained protocol item records whether it is a client request or Agent notification and contains the real ACP method/payload observed at that boundary; semantic AG-UI projection remains a separate view. ### Implemented evidence - `npm test --workspace @qoder-ai/harness`: 20 files and 165 tests passed before the final missing-command/redaction additions; the final focused ACP suite passed 4/4. - `npm test --workspace @qoder-ai/harness-ui`: 3 files and 30 tests passed. - Focused Studio ACP server/store checks passed 3/3; the ACP browser check passed at 1440×900, 1024×768, and 390×844 with no horizontal overflow, console error, or page error. - `npm run typecheck` passed for `@qoder-ai/harness`, `@qoder-ai/harness-ui`, and `@qoder-ai/harness-studio`; `git diff --check`, the focused doc-link graph test, and the public plugin-manifest test passed. - The existing preview process answered `200` for `/health` and `/canvas-module.js` (`application/javascript`). - A live `codex-acp` 0.12.0 smoke at the built Debugger completed with `ACP_READY`, zero Tool Calls, and ten observed ACP frames. The local Codex config's `service_tier="default"` is not accepted by that ACP binary; the smoke used server-owned argv overrides for `service_tier="fast"` and `model="gpt-5.4"` without editing the user's config. - Known unrelated gates: the full Studio suite has two existing Artifact renderer expectation failures (DOCX/XLSX Studio fallback versus provisioned Qoder Canvas); the root suite initially failed only because the local npm mirror URL entered the new SDK lock entry, which was normalized to npmjs and its focused manifest gate then passed. ### Review Readiness Check - Story: none supplied; this dated maintenance feature spec is the visible intent and acceptance owner. - Spec/tests/risk: present in this document and backed by focused executor, translation, store, server, browser, type, and live-runtime evidence above. - Changed modules: Harness adapter/executor, Harness UI protocol projection, Studio server/configuration, Debugger UI, launcher/CLI, tests, and lockfile. - Generated files: only `package-lock.json` is part of the source diff; compiled `dist` output and Playwright screenshots remain ignored validation artifacts. - Staged split: no files are staged. The working tree also contains a separate in-progress Artifact workspace change that overlaps Studio shell/server/style files; ACP work was not committed or staged across that user-owned boundary. - AI marker: no commit exists for this local diff, so there is no commit-level AI marker to review yet.