Skip to content

docs + server: ACP research-state schema and transport adapter skeleton - #232

Closed
n24q02m wants to merge 1 commit into
OpenLAIR:mainfrom
n24q02m:docs/acp-research-state
Closed

n24q02m wants to merge 1 commit into
OpenLAIR:mainfrom
n24q02m:docs/acp-research-state

Conversation

@n24q02m

@n24q02m n24q02m commented Sep 20, 2026 •

Copy link
Copy Markdown

Summary

Dr. Claw research sessions accumulate structure that a linear transcript cannot express: open questions, evidence for and against claims, blockers, and append-only decision records. This PR adds:

  1. docs/acp-research-state.md — a wire format for research state based on the Agent Client Protocol (ACP v1): four object types (task-graph nodes, typed edges, decision log entries, and claim→evidence expressed as typed edges) plus two JSON-RPC methods (session/record_research, session/get_research_state) over the standard ACP stdio transport.
  2. server/acp-transport.js — a dependency-free skeleton for hosting any ACP-speaking agent as a provider (stdio subprocess, JSON-RPC client side, session/update event surface, and an in-memory research-state mirror that answers the agent's session/record_research requests).

The goal is interoperability without code merges: any agent that speaks ACP (e.g. an agent daemon exposing sessions over ACP) can run inside Dr. Claw, and any ACP client can render a Dr. Claw research session's task graph and decision log in the same format. The identical schema is being proposed upstream to ACP as a "Research Process Extensions" RFD.

Notes

  • No new dependencies — Node core modules only (child_process, readline); plain JS ES modules per server/AGENTS.md.
  • The adapter is a skeleton: it is not wired into server/index.js yet. I left the wiring point for discussion (provider picker + spawn-command config), since it touches UI and config plumbing.
  • Original work authored from the public ACP specification; no third-party code or text is included.

Testing

  • node --check server/acp-transport.js passes.
  • A local two-peer round-trip (two linked createAcpPeer instances over in-memory streams) verifies: initialize handshake, unknown-method error (JSON-RPC -32601), a session/record_research batch (upsert node, add edge, record decision) acknowledged with a bumped stateVersion, and peer notification delivery.
  • The module is intentionally not imported anywhere, so no existing behavior changes.

Questions for maintainers

  1. Should the ACP provider be a first-class entry in the provider picker with a configurable spawn command, or an extension of the existing CLI-agent adapters?
  2. Preferred persistence for the research-state mirror (per-session file vs. the existing session database)?
  3. Interested in this direction at all — happy to iterate or split into smaller steps.

- docs/acp-research-state.md: wire format for research state over ACP v1
  (task-graph nodes, typed edges, append-only decision log, claim->evidence
  via supports/contradicts edges) plus session/record_research and
  session/get_research_state methods.
- server/acp-transport.js: dependency-free skeleton for hosting any
  ACP-speaking agent over stdio (JSON-RPC client side, session/update
  event surface, in-memory research-state mirror).

The adapter is intentionally not wired into server/index.js yet; the
integration point is discussed in the doc and the PR.
@n24q02m

n24q02m commented Sep 24, 2026

Copy link
Copy Markdown
Author

Withdrawing this PR — superseded by internal direction change. Thanks for the review effort.

@n24q02m n24q02m closed this Sep 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant