copper-pilot-cli 0.1.7__tar.gz → 0.1.9__tar.gz

copper_pilot_cli-0.1.9/HISTORY.md

@@ -0,0 +1,261 @@
+Changelog
+=========
+
+
+(unreleased)
+------------
+- Merge pull request #18 from CopperPilot/feat/acp-server. [Aditya]
+
+  feat: add `copper-pilot acp` Agent Client Protocol server
+- Fix(acp): surface hosted turn failures in the JSON-RPC error message.
+  [AdityaNG, Claude Fable 5.1]
+
+  T3 Code showed a bare "Internal error" for a prompt the hosted service
+  had refused with "Upgrade to a paid plan to use Intelligence." because the
+  explanation only lived in the error's `data`, which T3 does not display.
+  Carry the hosted message in the error `message` (keeping the code), map a
+  refused websocket handshake to auth_required when it is 401/403, log every
+  failed turn to the diagnostics log, and never let an unexpected exception
+  escape to the SDK's generic handler.
+- Fix(acp): accept `copper-pilot acp auth login` for clients that append
+  login args. [AdityaNG, Claude Fable 5.1]
+
+  T3 Code runs an ACP terminal auth method by appending the method's args to
+  the configured agent command, so the advertised `auth login` was spawned as
+  `copper-pilot acp auth login`. The acp parser rejected the extra arguments
+  with exit code 2 and T3 reported "The provider login command did not finish
+  successfully." Normalize `acp auth ...` onto `auth ...` before parsing and
+  document the alias.
+- Feat: add `copper-pilot acp` Agent Client Protocol server. [AdityaNG,
+  Claude Fable 5.1]
+
+  Serve the hosted CopperPilot agent over ACP stdio so editors such as Zed
+  can drive it with streaming messages, tool calls, permission prompts,
+  session modes (ask/plan/agent), an effort config option, session/load
+  resume of existing threads, and session/cancel.
+
+  - New copper_acp.py built directly on the agent-client-protocol SDK;
+    approvals and clarifying questions map onto session/request_permission.
+  - `acp` optional extra; the command prints an install hint without it.
+  - CI license gate ignores agent-client-protocol (Apache-2.0 LICENSE file,
+    no license metadata in the wheel).
+  - Tests: tests/test_acp.py (100% coverage of copper_acp.py, including a
+    real stdio JSON-RPC round trip), parser and entrypoint tests, and a
+    release-gate check for the extra.
+  - Docs: cli.md, harness.md (Zed setup), README.
+
+
+0.1.8 (2026-10-14)
+------------------
+
+Fix
+~~~
+- Annotate async context managers for ty 0.0.87. [AdityaNG]
+
+  CI resolves the unpinned ty dependency to 0.0.87, which rejects AsyncIterator returns on asynccontextmanager.
+- Upgrade the pinned Deep Agents runtime to 0.7.19. [AdityaNG]
+
+  Keep the exact runtime pin while picking up the filesystem and media-handling fixes from 0.7.14.
+- Align the CLI with hosted usage limits. [AdityaNG]
+
+  Keep blocked turns machine-readable, shrink oversized resumed chats to the desktop frame budget, and report the installed client version.
+
+Other
+~~~~~
+- Release: version 0.1.8 🚀 [AdityaNG]
+- Merge pull request #16 from CopperPilot/update/14_oct_2026. [Aditya]
+
+  Add Intelligence effort, hosted survey workers, and modal keyboard focus
+- Fix(tests/test_tui.py) [AdityaNG]
+- Feat(src/copper_pilot_cli/copper_status_events.py) [AdityaNG]
+- Merge pull request #3 from
+  CopperPilot/dependabot/github_actions/softprops/action-gh-release-3.
+  [Aditya]
+
+  build(deps): bump softprops/action-gh-release from 2 to 3
+- Build(deps): bump softprops/action-gh-release from 2 to 3.
+  [dependabot[bot]]
+
+  Bumps [softprops/action-gh-release](https://github.com/softprops/action-gh-release) from 2 to 3.
+  - [Release notes](https://github.com/softprops/action-gh-release/releases)
+  - [Changelog](https://github.com/softprops/action-gh-release/blob/master/CHANGELOG.md)
+  - [Commits](https://github.com/softprops/action-gh-release/compare/v2...v3)
+
+  ---
+  updated-dependencies:
+  - dependency-name: softprops/action-gh-release
+    dependency-version: '3'
+    dependency-type: direct:production
+    update-type: version-update:semver-major
+  ...
+- Merge pull request #4 from CopperPilot/dependabot/pip/websockets-
+  gte-15-and-lt-18. [Aditya]
+
+  build(deps): update websockets requirement from <17,>=15 to >=15,<18
+- Build(deps): update websockets requirement from <17,>=15 to >=15,<18.
+  [dependabot[bot]]
+
+  Updates the requirements on [websockets](https://github.com/python-websockets/websockets) to permit the latest version.
+  - [Release notes](https://github.com/python-websockets/websockets/releases)
+  - [Commits](https://github.com/python-websockets/websockets/compare/15.0...17.1)
+
+  ---
+  updated-dependencies:
+  - dependency-name: websockets
+    dependency-version: '17.1'
+    dependency-type: direct:production
+  ...
+- Merge pull request #5 from CopperPilot/dependabot/pip/uuid-utils-
+  gte-0.12-and-lt-2. [Aditya]
+
+  build(deps): update uuid-utils requirement from <1,>=0.12 to >=0.12,<2
+- Build(deps): update uuid-utils requirement from <1,>=0.12 to
+  >=0.12,<2. [dependabot[bot]]
+
+  Updates the requirements on [uuid-utils](https://github.com/aminalaee/uuid-utils) to permit the latest version.
+  - [Release notes](https://github.com/aminalaee/uuid-utils/releases)
+  - [Commits](https://github.com/aminalaee/uuid-utils/compare/0.12.0...1.0.0)
+
+  ---
+  updated-dependencies:
+  - dependency-name: uuid-utils
+    dependency-version: 1.0.0
+    dependency-type: direct:production
+  ...
+- Merge pull request #2 from
+  CopperPilot/dependabot/github_actions/actions/setup-python-7. [Aditya]
+
+  build(deps): bump actions/setup-python from 5 to 7
+- Build(deps): bump actions/setup-python from 5 to 7. [dependabot[bot]]
+
+  Bumps [actions/setup-python](https://github.com/actions/setup-python) from 5 to 7.
+  - [Release notes](https://github.com/actions/setup-python/releases)
+  - [Commits](https://github.com/actions/setup-python/compare/v5...v7)
+
+  ---
+  updated-dependencies:
+  - dependency-name: actions/setup-python
+    dependency-version: '7'
+    dependency-type: direct:production
+    update-type: version-update:semver-major
+  ...
+- Merge pull request #13 from
+  CopperPilot/update/deepagents_0_7_19_3_oct. [Aditya]
+
+  Upgrade the pinned Deep Agents runtime to 0.7.19
+- Merge pull request #1 from
+  CopperPilot/dependabot/github_actions/actions/checkout-7. [Aditya]
+
+  build(deps): bump actions/checkout from 4 to 7
+- Build(deps): bump actions/checkout from 4 to 7. [dependabot[bot]]
+
+  Bumps [actions/checkout](https://github.com/actions/checkout) from 4 to 7.
+  - [Release notes](https://github.com/actions/checkout/releases)
+  - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
+  - [Commits](https://github.com/actions/checkout/compare/v4...v7)
+
+  ---
+  updated-dependencies:
+  - dependency-name: actions/checkout
+    dependency-version: '7'
+    dependency-type: direct:production
+    update-type: version-update:semver-major
+  ...
+- Merge pull request #12 from
+  CopperPilot/update/contract_alignment_3_oct. [Aditya]
+
+  Align the CLI with hosted usage limits
+
+
+0.1.7 (2026-10-03)
+------------------
+- Release: version 0.1.7 🚀 [AdityaNG]
+- Merge pull request #11 from
+  CopperPilot/feat/python_versions_support_expansion. [Aditya]
+
+  Support Python 3.11 and future releases
+- Ci: probe Python 3.15 weekly instead of on pull requests. [AdityaNG]
+
+  Keep the upstream install failure visible without turning required pull request checks red.
+- Feat(py11) [AdityaNG]
+- Merge pull request #7 from CopperPilot/feat/example_002_cm5_camera.
+  [Aditya]
+
+  feat(examples/002_cm5_camera): add 3D pose audit and generated carrier
+- Fix(examples/002_cm5_camera): render the README PCB as a dimetric 3D
+  view. [AdityaNG, Cursor]
+
+  Use an orthogonal high-quality camera with a slight isometric tilt so the
+  hero PNG shows connector height instead of a flat top-down shot.
+- Fix(examples/002_cm5_camera): skip library dirs relative to the
+  workspace. [AdityaNG, Cursor]
+
+  Absolute path parts named tmp (Linux /tmp pytest roots) were skipping the
+  entire haystack, so libraries_ready failed on Ubuntu CI.
+- Feat(examples/002_cm5_camera): add 3D pose audit and generated
+  carrier. [AdityaNG, Cursor]
+
+  Lock connector 3D offsets, Module1 pad orientation, and the generated
+  KiCad project so the example reproduces NANO-C assembly parity.
+- Feat(examples/002_cm5_camera/main.py): new example. [AdityaNG]
+
+
+0.1.6 (2026-09-18)
+------------------
+- Release: version 0.1.6 🚀 [AdityaNG]
+- Merge pull request #6 from CopperPilot/feat/plugins. [Aditya]
+
+  feat: add MCP conductor and Claude Code plugin
+- Clarify server restrictions in PR template. [Aditya]
+
+  Updated checklist item to clarify server restrictions.
+- Feat: add MCP conductor and Claude Code plugin. [AdityaNG, Cursor]
+
+  Let Claude Code, Cursor, and Codex delegate electronics work to the hosted agent via copper-pilot mcp, a portable review skill, and an in-repo plugin.
+
+
+0.1.5 (2026-09-17)
+------------------
+- Release: version 0.1.5 🚀 [AdityaNG]
+- Fix(README.md) [AdityaNG]
+
+
+0.1.4 (2026-09-17)
+------------------
+- Release: version 0.1.4 🚀 [AdityaNG]
+- Fix(tests/test_release_gates.py) [AdityaNG]
+
+
+0.1.3 (2026-09-17)
+------------------
+- Release: version 0.1.3 🚀 [AdityaNG]
+- Docs. [AdityaNG]
+
+
+0.1.2 (2026-09-17)
+------------------
+- Release: version 0.1.2 🚀 [AdityaNG]
+- Ci(pyproject.toml) [AdityaNG]
+- Fix(tests/test_tui.py) [AdityaNG]
+
+
+0.1.1 (2026-09-17)
+------------------
+- Release: version 0.1.1 🚀 [AdityaNG]
+
+
+0.1.0 (2026-09-17)
+------------------
+- Release: version 0.1.0 🚀 [AdityaNG]
+- Fix(tests/test_release_gates.py) [AdityaNG]
+- Test. [AdityaNG]
+- Docs. [AdityaNG]
+- Docs. [AdityaNG]
+- Example(examples/001_esp32/) [AdityaNG]
+- Makefile. [AdityaNG]
+- Ci. [AdityaNG]
+- Docs. [AdityaNG]
+- Refactor(name) [AdityaNG]
+- Init. [AdityaNG]
+
+

{copper_pilot_cli-0.1.7 → copper_pilot_cli-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: copper-pilot-cli
-Version: 0.1.7
+Version: 0.1.9
 Summary: CopperPilot hosted agent for the terminal and LangChain
 Project-URL: Homepage, https://copperpilot.ai
 Project-URL: Repository, https://github.com/CopperPilot/copper-pilot-cli
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
 Requires-Dist: aiosqlite<1,>=0.22
 Requires-Dist: certifi>=2024.8.30
-Requires-Dist: deepagents==0.7.14
+Requires-Dist: deepagents==0.7.19
 Requires-Dist: httpx<1,>=0.28
 Requires-Dist: langchain-core<2,>=1.6
 Requires-Dist: langgraph-checkpoint-sqlite<4,>=3.1
@@ -35,9 +35,12 @@ Requires-Dist: pyperclip<2,>=1.11
 Requires-Dist: pyyaml<7,>=6
 Requires-Dist: rich<16,>=15
 Requires-Dist: textual<9,>=8.2.8
-Requires-Dist: uuid-utils<1,>=0.12
-Requires-Dist: websockets<17,>=15
+Requires-Dist: uuid-utils<2,>=0.12
+Requires-Dist: websockets<18,>=15
+Provides-Extra: acp
+Requires-Dist: agent-client-protocol<1,>=0.12; extra == 'acp'
 Provides-Extra: dev
+Requires-Dist: agent-client-protocol<1,>=0.12; extra == 'dev'
 Requires-Dist: build<2,>=1.4; extra == 'dev'
 Requires-Dist: gitchangelog==3.0.4; extra == 'dev'
 Requires-Dist: pip-audit<3,>=2.10; extra == 'dev'
@@ -107,12 +110,18 @@ copper-pilot ./my-board
 copper-pilot --resume
 copper-pilot threads list
 copper-pilot -n -m "Review this board" --json
+copper-pilot --mode plan --effort intelligence -m "Survey and plan this board"
 ```
 
 Both `copper-pilot` and `copper-pilot-cli` run the same program.
 `copper-pilot --help` lists flags; [docs/cli.md](docs/cli.md) is the full
 command reference.
 
+Balanced effort is the default. Paid-plan users can select Intelligence with
+`--effort intelligence` or interactive `/effort`. Intelligence uses
+server-owned survey subagents and shows their lifecycle through the existing
+Deep Agents task rows; Intelligence Plan turns survey before writing a plan.
+
 ## Use from Claude Code, Cursor, or Codex
 
 CopperPilot stays the electronics agent. Copy
@@ -131,8 +140,9 @@ Claude Code can also install the in-repo plugin:
 ```
 
 That plugin starts `copper-pilot mcp` and adds `@copper-pilot` plus
-`/copper-pilot-review`. Setup for Cursor, Codex, and approvals:
-[docs/harness.md](docs/harness.md).
+`/copper-pilot-review`. Editors that speak the Agent Client Protocol, such as
+Zed, can run `copper-pilot acp` after `pip install "copper-pilot-cli[acp]"`.
+Setup for Cursor, Codex, Zed, and approvals: [docs/harness.md](docs/harness.md).
 
 ## Configuration
 
@@ -147,13 +157,16 @@ the parent directory is mode `0700` and the file is mode `0600`.
 ## LangChain
 
 ```python
-from copper_pilot_cli.copper_protocol import CopperMode
+from copper_pilot_cli.copper_protocol import CopperEffort, CopperMode
 from copper_pilot_cli.langchain import CopperPilotAgent
 from helper import drc_violations, erc_errors, render_pcb, run
 
 PLAN = CopperMode.PLAN
 
-copper_pilot = CopperPilotAgent(workspace="esp32")
+copper_pilot = CopperPilotAgent(
+    workspace="esp32",
+    effort=CopperEffort.INTELLIGENCE,
+)
 
 run(copper_pilot, "Build me an ESP32 dev board.", PLAN)
 run(copper_pilot, "Let us build this plan.")
@@ -188,7 +201,8 @@ normalizes hosted tool names, approval decisions, and result envelopes.
 Computer use, model/provider selection, local model execution, LangSmith
 tracing, content telemetry, MCP **host**/plugin-runtime controls, and server
 implementation code are not part of this package. A thin MCP **server**
-(`copper-pilot mcp`) that delegates to the hosted agent is.
+(`copper-pilot mcp`) and an ACP **server** (`copper-pilot acp`) that delegate
+to the hosted agent are.
 
 See [UPSTREAM.md](UPSTREAM.md) and [NOTICE](NOTICE) for the retained Textual
 client attribution.

{copper_pilot_cli-0.1.7 → copper_pilot_cli-0.1.9}/README.md

@@ -56,12 +56,18 @@ copper-pilot ./my-board
 copper-pilot --resume
 copper-pilot threads list
 copper-pilot -n -m "Review this board" --json
+copper-pilot --mode plan --effort intelligence -m "Survey and plan this board"
 ```
 
 Both `copper-pilot` and `copper-pilot-cli` run the same program.
 `copper-pilot --help` lists flags; [docs/cli.md](docs/cli.md) is the full
 command reference.
 
+Balanced effort is the default. Paid-plan users can select Intelligence with
+`--effort intelligence` or interactive `/effort`. Intelligence uses
+server-owned survey subagents and shows their lifecycle through the existing
+Deep Agents task rows; Intelligence Plan turns survey before writing a plan.
+
 ## Use from Claude Code, Cursor, or Codex
 
 CopperPilot stays the electronics agent. Copy
@@ -80,8 +86,9 @@ Claude Code can also install the in-repo plugin:
 ```
 
 That plugin starts `copper-pilot mcp` and adds `@copper-pilot` plus
-`/copper-pilot-review`. Setup for Cursor, Codex, and approvals:
-[docs/harness.md](docs/harness.md).
+`/copper-pilot-review`. Editors that speak the Agent Client Protocol, such as
+Zed, can run `copper-pilot acp` after `pip install "copper-pilot-cli[acp]"`.
+Setup for Cursor, Codex, Zed, and approvals: [docs/harness.md](docs/harness.md).
 
 ## Configuration
 
@@ -96,13 +103,16 @@ the parent directory is mode `0700` and the file is mode `0600`.
 ## LangChain
 
 ```python
-from copper_pilot_cli.copper_protocol import CopperMode
+from copper_pilot_cli.copper_protocol import CopperEffort, CopperMode
 from copper_pilot_cli.langchain import CopperPilotAgent
 from helper import drc_violations, erc_errors, render_pcb, run
 
 PLAN = CopperMode.PLAN
 
-copper_pilot = CopperPilotAgent(workspace="esp32")
+copper_pilot = CopperPilotAgent(
+    workspace="esp32",
+    effort=CopperEffort.INTELLIGENCE,
+)
 
 run(copper_pilot, "Build me an ESP32 dev board.", PLAN)
 run(copper_pilot, "Let us build this plan.")
@@ -137,7 +147,8 @@ normalizes hosted tool names, approval decisions, and result envelopes.
 Computer use, model/provider selection, local model execution, LangSmith
 tracing, content telemetry, MCP **host**/plugin-runtime controls, and server
 implementation code are not part of this package. A thin MCP **server**
-(`copper-pilot mcp`) that delegates to the hosted agent is.
+(`copper-pilot mcp`) and an ACP **server** (`copper-pilot acp`) that delegate
+to the hosted agent are.
 
 See [UPSTREAM.md](UPSTREAM.md) and [NOTICE](NOTICE) for the retained Textual
 client attribution.

copper_pilot_cli-0.1.9/VERSION

@@ -0,0 +1 @@
+0.1.9

{copper_pilot_cli-0.1.7 → copper_pilot_cli-0.1.9}/docs/cli.md

@@ -7,6 +7,7 @@ copper-pilot --help
 copper-pilot auth --help
 copper-pilot threads --help
 copper-pilot mcp --help
+copper-pilot acp --help
 ```
 
 Python 3.11 or newer is required. Install with `pip install copper-pilot-cli`.
@@ -30,6 +31,7 @@ valid.
 | `--no-stream` | Print the final assistant message after the run instead of streaming. |
 | `--json` | Emit JSON events (or a final JSON document with `--no-stream`). |
 | `--mode {agent,plan,ask}` | Hosted chat mode. Default: `agent`. |
+| `--effort {balanced,intelligence}` | Hosted effort. Default: `balanced`; Intelligence requires a paid plan. |
 | `-y`, `--auto-approve` | Auto approval: routine writes and known-safe shell still run; unknown actions prompt. |
 | `--yolo` | Permit local side effects without prompting. Must be set explicitly. |
 | `--version` | Print the package version. |
@@ -41,6 +43,7 @@ copper-pilot ./my-board
 copper-pilot --resume
 copper-pilot -n -m "Review this board" --json
 copper-pilot ./my-board --mode plan -m "Propose a power tree"
+copper-pilot ./my-board --mode plan --effort intelligence -m "Survey and plan the power tree"
 ```
 
 Headless mode is also used when `--message` is set and stdout is not a TTY.
@@ -60,15 +63,61 @@ write to stdout; the protocol owns it.
 | Tool | Role |
 |------|------|
 | `status` | Login state and discovered schematic/PCB paths. No hosted call. |
-| `ask` | `--mode ask`. Auto approval. Optional `thread_id`. |
-| `plan` | `--mode plan`. Auto approval. |
-| `run` | `--mode agent`. `approval` is `auto` (default) or `yolo`. |
-| `resume` | Continue `thread_id`. Same approval as `run`. |
+| `ask` | `--mode ask`. Auto approval. Optional `thread_id` and `effort`. |
+| `plan` | `--mode plan`. Auto approval. Optional `effort`. |
+| `run` | `--mode agent`. Optional `effort`; `approval` is `auto` (default) or `yolo`. |
+| `resume` | Continue `thread_id`. Optional `mode`, `effort`, and the same approval as `run`. |
 | `threads_list` | List threads for this workspace (`limit`, `all_workspaces`). |
 
 Workspace is the tool argument, else `CLAUDE_PROJECT_DIR`, else the process
 current directory. Manual approval is TUI-only. See [harness.md](harness.md).
 
+## ACP
+
+```console
+pip install "copper-pilot-cli[acp]"
+copper-pilot acp
+```
+
+Serves the Agent Client Protocol over stdio for editors such as Zed. The
+`acp` extra is optional; without it the command prints an install hint and
+exits with status 2. `copper-pilot acp auth login` is accepted as an alias for
+`copper-pilot auth login`, because some ACP clients (T3 Code) run the
+advertised login method by appending its arguments to the agent command. One ACP session is one CopperPilot thread, and the
+session `cwd` is the workspace. Uses the stored device-login credential and
+advertises a terminal auth method that runs `copper-pilot auth login`.
+
+| ACP feature | CopperPilot behavior |
+|-------------|----------------------|
+| Session modes | `ask`, `plan`, `agent` (default `agent`) |
+| Config options | `mode` and `effort` (`balanced` default, `intelligence` paid) |
+| `session/load` | Resumes an existing thread id and replays its history |
+| `session/request_permission` | Auto approval; non-routine writes and shell prompt the editor |
+| `session/cancel` | Cancels the hosted turn and local tools |
+
+"Allow all for this session" switches that session to YOLO until the server
+exits; it is never saved. Clarifying questions with options are shown as
+permission choices plus Skip; free-text questions are declined with a message
+to continue in the TUI. See [harness.md](harness.md).
+
+## Effort and Intelligence
+
+Balanced is the default. Intelligence is available on paid plans and lets the
+hosted parent run one to four survey subagents. Intelligence Plan turns survey
+before creating or revising a plan. Workers are server-owned, survey-only, and
+appear in the TUI through the existing Deep Agents task rows; they do not open
+nested chats or execute through the local tool broker.
+
+The interactive `/effort` command changes effort for the current thread.
+Resuming that thread restores it; a new thread starts Balanced. In headless
+text mode, worker state changes print as compact lines. `--json` retains raw
+`status_event` objects.
+
+Interactive clarification can offer suggested answers, custom text, or Skip
+and waits without a client timeout. Headless and MCP calls cannot present that
+UI, so an `ask_user_question` tool request is rejected with a clear error
+instead of guessing or auto-skipping.
+
 ## Auth
 
 ```console
@@ -118,6 +167,37 @@ searches run freely. Writes, edits, deletes, and shell commands are gated:
 
 `--yolo` wins over `--auto-approve`. Saved preferences never enable YOLO.
 
+## Usage limits
+
+The hosted service owns weekly and window usage. The CLI does not show raw
+token balances, sell credits, or complete checkout.
+
+Inside the interactive app, `/tokens` prints the current window as a
+percentage, the next refresh time, and any additional-usage state.
+`/tokens json` prints the member-safe API payload instead.
+
+A blocked turn stays readable in `--json` output. An error event uses `data`
+as an object:
+
+```json
+{
+  "type": "error",
+  "data": {
+    "message": "Usage limit reached.",
+    "code": "http_402",
+    "status": 402,
+    "block_reason": "weekly",
+    "can_purchase_overage": true,
+    "retryable": false
+  }
+}
+```
+
+`block_reason` is `window`, `weekly`, `cost_cap`, `busy`, or `billing` when
+the server sends one. A `busy` block and an ordinary rate limit use status
+`429` with `retryable: true`. `can_purchase_overage` only says whether the
+billing page can offer additional usage. The Textual UI prints `message`.
+
 ## Configuration
 
 | Setting | Location |

{copper_pilot_cli-0.1.7 → copper_pilot_cli-0.1.9}/docs/development.md

@@ -56,6 +56,40 @@ unreleased Python.
 
 Do not commit credentials, `.venv/`, or `dist/`.
 
+## Hosted protocol
+
+The client speaks protocol v1. Agent turns, and plan turns that carry plan
+context, use `/api/copperpilot/analyze/agent/ws`. Ask turns and plan turns
+without that context use `/api/copperpilot/analyze/chat/ws`.
+
+`make_chat_start` in `copper_protocol.py` bounds history before the socket
+send, matching the desktop harness:
+
+| Attempt | Message cap | History cap | Frame cap |
+|---------|-------------|-------------|-----------|
+| 1 | 64 KiB | 4 MiB | 12 MiB |
+| 2 | 32 KiB | 2 MiB | 8 MiB |
+| 3 | 8 KiB | 128 KiB | 8 MiB |
+| 4 | 4 KiB | 64 KiB | 8 MiB |
+
+History is kept newest-first. Inline `data:` attachments are replaced before
+the byte caps apply. A query or workspace snapshot that still cannot fit
+raises `ProtocolError` with `code="PAYLOAD_TOO_LARGE"`.
+
+A WebSocket `error` frame keeps `code`, `status`, `block_reason`,
+`can_purchase_overage`, and `retryable` on both `ProtocolError` and the
+`copper.error` event. Absent fields stay absent. The interactive UI and MCP
+`error` string use `public_message`; `--json` and the MCP event digest keep
+the object.
+
+Device login and the WebSocket `User-Agent` (`CopperPilot CLI/<version>`)
+read the installed package version. That version comes from `VERSION`.
+
+`POST /api/copperpilot/analyze/token_limits` is the account-usage read. It
+returns percentages and reset state even when chat is blocked. Do not add
+token counts, plan allocations, Stripe checkout, or a per-chat context meter
+here. The server does not expose those on this contract.
+
 ## Release
 
 Version is the contents of [`VERSION`](../VERSION). `make release` writes that