AI 原生开放教材

外观

Better Harness（QoderAI）工程手册·英文原文 ↗原件 ↓仓库 ↗

ACP connection discovery and authentication ​

Traceability ​

  • Spec ID: acp-connection-actions
  • Status: Implemented; local acceptance verified

Intent ​

Continue the user-requested Zed parity work with connection-level interfaces. Hosts must be able to discover Agent sessions and explicitly authenticate before session creation. Local saved records are not Agent discovery results.

Acceptance scenarios ​

  • AC-1: Node and native executors expose a connection callback after initialize and before session/new; finishing execution invalidates the handle.
  • AC-2: session/list requires advertised support and forwards cwd and opaque cursor unchanged, retaining nextCursor and session metadata.
  • AC-3: authenticate only accepts an advertised agent/default method; terminal methods and unknown ids are rejected without invoking the Agent.
  • AC-4: Authentication is never automatic; an explicit callback action can authenticate and then allow session/new to proceed. Errors reach the caller.
  • AC-5: Existing callers without the callback retain their lifecycle.

Plan and tasks ​

Add a shared guarded connection control, executor hooks, native wire calls and fixture integration tests. Keep initialization metadata outside redacted trace extraction so discovery remains available even when traces are truncated.

Non-goals ​

The Studio picker lists Agent sessions filtered to the active Project. Browsing other projects is outside this increment. No terminal login process, credential storage, logout, checkpoint or implicit authentication is introduced.

Test and review evidence ​

  • AC-1–5: Harness focused suite, 49 tests passed including child-process discovery/authentication, unchanged callers and closed-handle rejection.
  • AC-1–5: Native suite, 19 tests passed including discovery/authentication over Rust stdio and macOS NSXPC.
  • Rust library: 61 tests passed; release host/bridge build passed.
  • Harness TypeScript check passed; doc routing regenerated and unchanged.
  • Capability gating and explicit callback authentication have executable tests; no real account login or installed desktop replacement was performed.

References: ACP session list and ACP authentication. Native filesystem filtering uses node:path and PathBuf; macOS tests do not prove Windows/Linux execution.

Studio integration increment ​

  • AC-6: Compare and Debugger offer an explicit Choose session entry. Connecting pauses before session creation; new/session selection releases the same connection.
  • AC-7: A compact shared panel offers project-filtered Agent history with bounded pagination, manual refresh, empty/unsupported states and explicit authentication. Only session IDs actually returned for this project can be selected for recovery.
  • AC-8: Failure preserves the panel and prompt for retry; Close and disconnect release the preparation gate and reap the connection. Inactive handles reject actions.
  • AC-9: Keyboard controls, visible focus, wide/compact/narrow layouts, console and page errors are verified in Playwright. Existing direct runs remain one-click.

Implementation uses a typed stream event and the existing injected action adapter. No credentials are accepted by Studio; terminal authentication stays unsupported.

Studio acceptance evidence ​

  • AC-6–9: 3 browser scenarios pass on Node stdio, Rust stdio and macOS NSXPC: discovery/authentication/pagination/restore/next turn, closing preparation, and direct-run failure followed by login and retry of the original prompt.
  • Existing controls, stream and conversation browser regression: 11 cases pass including the 3 connection cases. Wide 1440, compact 1024 and narrow 390 screenshots checked; reduced motion prevents transition frames contaminating layout receipts. Browser page errors and console errors checked.
  • Studio suite: 80 files / 596 tests pass (includes other work in this checkout).
  • Root preview health and canvas-module.js return HTTP 200; document links: 8 pass.
  • Lists retain at most 500 sessions / 100 pagination cursors per preparation. Preparation expires after 5 minutes; close and disconnect release the gate.
  • Historical analysis remains an analysis-time snapshot. Native checkpoint, terminal authentication, interactive terminal controls and filesystem/editor actions are still separate host integration work.

Review readiness ​

The user request is the requirement source; no Story id was supplied. This is an AI-authored, spec-backed ACP change spanning the Harness executors, Rust ACP wire, shared Studio panel, action route and tests. The independently modified Rust evidence host, desktop packaging, workflow deletion and sidebar tests are outside this change. Generated build products and local screenshot receipts are not staged. No push, publication or installed-app replacement is included.