From ca91c1de41cbdc513b1a47acceff5b018120230e Mon Sep 17 00:00:00 2001 From: nav Date: Sat, 11 Apr 2026 06:39:54 +0000 Subject: [PATCH] docs: add initial ContractorAgent planning --- docs/claude/PLAN.md | 249 +++++++++++++++++++++++++++++++++++++++++++ docs/gemini/.gitkeep | 0 2 files changed, 249 insertions(+) create mode 100644 docs/claude/PLAN.md create mode 100644 docs/gemini/.gitkeep diff --git a/docs/claude/PLAN.md b/docs/claude/PLAN.md new file mode 100644 index 0000000..bd271f4 --- /dev/null +++ b/docs/claude/PLAN.md @@ -0,0 +1,249 @@ +# ContractorAgent Plan + +## Project Goal + +Build an OpenClaw integration that turns contractor coding agents such as Claude Code into OpenClaw-managed agents. + +Phase 1 focuses on Claude Code only. Gemini support is deferred. + +## Product Direction + +The goal is not merely to launch Claude Code from OpenClaw, but to make Claude Code behave like an OpenClaw-managed agent while preserving Claude Code's own model capability and execution workflow. + +Desired properties: + +- OpenClaw manages agent identity, routing, workspace, and session ownership +- Claude Code manages the live conversational and task context for its own session +- OpenClaw tools and skills are adapted into forms Claude Code can consume +- OpenClaw channels and sessions remain the outer control plane + +## Core Design + +### Session Proxy Runtime + +Use a session proxy runtime rather than replaying full OpenClaw-managed context into Claude Code on every turn. + +Core idea: + +- map each OpenClaw session to a Claude Code session +- on each new user message, find the mapped Claude session +- resume or continue that Claude session +- forward only the newest actionable message plus minimal metadata +- avoid rebuilding full prompt history on every turn + +This reduces: + +- duplicated context management +- token waste +- divergence between OpenClaw-visible history and Claude's actual working memory + +### Control Plane Split + +OpenClaw remains source of truth for: + +- agent registration +- routing and bindings +- workspace ownership +- permissions and approvals +- channel transport +- tool hosting + +Claude Code remains source of truth for: + +- live conversation state within a contractor session +- reasoning and coding flow +- internal execution trajectory + +## Feasibility Notes from Docs + +### OpenClaw ACP Agents + +OpenClaw already supports Claude Code as an ACP harness runtime. + +Relevant doc statements: + +> "ACP sessions let OpenClaw run external coding harnesses (for example ... Claude Code ...) through an ACP backend plugin." + +> "For Claude Code through ACP, the stack is: +> 1. OpenClaw ACP session control plane +> 2. bundled `acpx` runtime plugin +> 3. Claude ACP adapter +> 4. Claude-side runtime/session machinery" + +This indicates Claude Code session hosting is already available as a foundation. + +Source: +- https://docs.openclaw.ai/tools/acp-agents + +### OpenClaw ACP Session Semantics + +Relevant doc statements: + +> "Follow-up messages in that conversation route to the same ACP session." + +> "`/new` and `/reset` reset the same bound ACP session in place." + +> "Use `resumeSessionId` to continue a previous ACP session instead of starting fresh." + +These features support a persistent contractor-session bridge. + +Source: +- https://docs.openclaw.ai/tools/acp-agents + +### OpenClaw Plugin Extensibility + +Relevant doc statements: + +> "Plugins extend OpenClaw with new capabilities: channels, model providers, ... agent tools, or any combination." + +> "Agent tools | `api.registerTool(...)`" + +> "For provider plugins, tool plugins, hook plugins, and anything that is not a messaging channel." + +These suggest a native OpenClaw plugin can host the contractor-agent bridge logic. + +Sources: +- https://docs.openclaw.ai/plugins/building-plugins +- https://docs.openclaw.ai/plugins/sdk-entrypoints + +### OpenClaw CLI Extension Surface + +Plugins can register CLI commands, but current docs do not show support for patching an existing core command such as `openclaw agents add` with extra flags. + +Relevant doc statements: + +> "Common registration methods: ... `registerCommand` / `registerCli` | CLI commands" + +> "For plugin-owned root CLI commands, prefer `api.registerCli(..., { descriptors: [...] })` ..." + +Therefore the safer design is to add a plugin-owned command root rather than extending `openclaw agents add` directly. + +Sources: +- https://docs.openclaw.ai/tools/plugin +- https://docs.openclaw.ai/plugins/sdk-entrypoints + +### Claude Code Plugin Surface + +Claude Code has a plugin model with skills, agents, hooks, MCP servers, and LSP servers. + +Relevant doc statements: + +> "A plugin is a self-contained directory of components that extends Claude Code with custom functionality. Plugin components include skills, agents, hooks, MCP servers, and LSP servers." + +> "Plugins add skills to Claude Code ... Claude can invoke them automatically based on task context" + +This supports the idea that OpenClaw skills and tooling may be adapted into Claude Code-friendly forms instead of being injected as raw prompt only. + +Source: +- https://code.claude.com/docs/en/plugins-reference + +## Initial CLI Plan + +Introduce a plugin-owned command: + +```bash +openclaw contractor-agents add --agent-id --workspace --contractor +``` + +For phase 1, only `claude` is supported. + +### Intended behavior + +For `--contractor claude`, the command should: + +1. call: + +```bash +openclaw agents add --workspace --model --non-interactive +``` + +2. mark the created agent as a contractor-backed agent +3. persist contractor runtime metadata for that agent +4. prepare storage for OpenClaw-session to Claude-session mappings + +## Proposed Agent Config Shape + +Exact schema TBD, but directionally: + +```json5 +{ + agents: { + list: [ + { + id: "my-agent", + workspace: "/path/to/workspace", + model: "contractor-claude-bridge", + runtime: { + type: "contractor", + contractor: { + kind: "claude", + backend: "acp", + mode: "persistent" + } + } + } + ] + } +} +``` + +## Session Mapping Store + +Keep dynamic mappings out of main config. + +Suggested runtime state file location: + +```text +/.openclaw/contractor-agent/session-map.json +``` + +Possible structure: + +```json +{ + "sessions": [ + { + "openclawSessionKey": "agent:my-agent:main", + "claudeSessionId": "", + "createdAt": "2026-04-10T00:00:00Z", + "lastActivityAt": "2026-04-10T00:00:00Z", + "state": "active" + } + ] +} +``` + +## Phase 1 Scope + +### In scope + +- Claude contractor agent creation flow +- plugin-owned CLI for contractor agent management +- bridge model placeholder for Claude-backed agents +- persistent mapping of OpenClaw sessions to Claude sessions +- initial Claude-only runtime design +- planning documents and repository structure + +### Out of scope for now + +- Gemini implementation +- full OpenClaw skill auto-conversion +- complete tool surface bridging +- advanced recovery and replay semantics +- UI polish and operational tooling + +## Open Questions + +1. What is the best implementation seam for the bridge model inside OpenClaw, provider plugin, tool plugin, or service-backed pseudo model? +2. How should contractor metadata be persisted, agent runtime stanza, plugin config, or both? +3. What is the canonical identifier for Claude session continuation, ACP session id, adapter resume id, or plugin-owned alias? +4. Which minimal OpenClaw tools should be exposed first to Claude? +5. How should reset/new map to Claude-side session recreation? + +## Immediate Next Steps + +1. Design the `openclaw contractor-agents add` CLI surface in detail +2. Define config schema for contractor-backed agents +3. Define session-map file schema and lifecycle +4. Determine how the bridge model id is registered by the plugin +5. Draft implementation skeleton for Claude-only support diff --git a/docs/gemini/.gitkeep b/docs/gemini/.gitkeep new file mode 100644 index 0000000..e69de29