@chorded/cursor-cloud-acp 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Katsuba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @chorded/cursor-cloud-acp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cursor's cloud agents as an [Agent Client Protocol](https://agentclientprotocol.com)
+v1 agent on stdin and stdout, written on Cursor's TypeScript SDK,
+`@cursor/sdk`. [chord](https://github.com/IKatsuba/chord) starts it as its
+`cursor-cloud` agent.
+
+Requires Node 22.13 or newer. The commands below require 0.2.0
+to be published; the owner publishes it before chord's next release.
+
+## Signing in
+
+```sh
+npx -y @chorded/cursor-cloud-acp@0.2.0 login    # Cursor's browser login, the key kept in the OS keychain
+npx -y @chorded/cursor-cloud-acp@0.2.0 status   # whether the keychain holds a login
+npx -y @chorded/cursor-cloud-acp@0.2.0 logout   # the key removed from the keychain
+```
+
+`CURSOR_API_KEY`, when set, is used instead of the keychain's key. Where no
+keychain is there (Linux without a Secret Service), `login` refuses and
+points to `CURSOR_API_KEY`; no key is written to a file. The SDK's own
+login file is not used. Keychain calls time out after 10 seconds.
+ACP `auth/status` reports the account's name and email when given, with
+the key's source and keychain expiry when known; chord shows them in
+`/status`. Changes push at the next status request, session start, list,
+resume or load, without polling.
+
+What each prints, on stdout (the SDK's own lines, the login URL among
+them, go to stderr):
+
+| Command | Says |
+| --- | --- |
+| `login` | `Signed in to Cursor as <email>; the key expires <YYYY-MM-DD>.`, each part only when the SDK gives it |
+| `login` without a keychain | `No keychain to keep the key in: <the keychain's error>. Set CURSOR_API_KEY instead.` on stderr, status 1 |
+| `logout` | `Signed out of Cursor: the key is removed from this machine's keychain.` |
+| `status` | as `login`, or `Not signed in to Cursor.`; then `CURSOR_API_KEY is set; it is used instead.` when it is |
+| any other word | `Usage: cursor-cloud-acp [login \| logout \| status]` on stderr, status 2 |
+
+## Running
+
+```sh
+chord cursor-cloud
+# Or serve ACP v1 to another client in the current directory:
+npx -y @chorded/cursor-cloud-acp@0.2.0
+```
+
+Start in a git work tree on a pushed branch with a push remote. The check
+uses the local remote-tracking ref, without fetching. A refusal tells you
+what to fix. Cursor starts from the remote branch; local changes are not
+uploaded. The first message names the repository, branch and agent link.
+Work runs in Cursor's cloud, pushes a branch of its own and keeps running
+when the client closes. Results name branches, PR links and artifact paths;
+nothing is downloaded.
+
+Creating a session is refused while the Cursor account's prepaid balance
+is empty: top up or enable auto top-up. `usage_limit_exceeded` appears as
+one plain line with Cursor's message. After each run, ACP `usage_update`
+reports the whole agent's undiscounted token cost in USD when available.
+Cost may lag until a later run. chord's `/cost` counts it per session, so
+resuming does not count earlier runs again. No context meter is shown:
+the SDK gives no context window.
+
+Agent and Plan modes apply from the next prompt. Models have one entry
+each, with separate parameter options; choosing a model starts outside
+max mode when possible. Cursor's default is offered until a model is set.
+Text, thinking, tool results and plans arrive as ACP updates. Cursor
+requests for input or approval are text only; the adapter cannot answer
+them. Cancel stops the run, with a warning if Cursor has not confirmed it
+within 10 seconds. A lost connection ends the turn with the agent link.
+
+In chord, `/resume` lists chord's records;
+`chord cursor-cloud --resume bc-…` also reopens an agent started elsewhere.
+The adapter replays the history Cursor provides. A run still going is
+reported, not followed live; prompts are refused until it ends.
+ACP `session/list` lists the account's cloud agents for the repository.
+Cursor's agent name becomes the title only when it changes after a run,
+never on new, resume or load. `/rename` changes chord's title alone; a later
+change to Cursor's name replaces it.
+MCP servers are not forwarded: chord holds them back by default; servers
+sent by another client are named unreachable in the first message.
+
+## Development
+
+From the repository root, `bun install` installs the workspace.
+`bun dev quality cursor-cloud-acp` checks types, tooling types, coverage,
+lint and format, then runs tests, the build and a packed Node smoke.
+`--static` leaves out tests, build and smoke. Tests use a fake Cursor and
+keychain; the smoke installs dependencies but reaches neither Cursor nor
+the keychain. The [guide](../../docs/guide.md#development) gives the offline
+window fixture command.
+
+The owner's `bun dev release cursor-cloud-acp` runs install, quality,
+build, pack and publish, tags `cursor-cloud-acp-v<version>` and creates no
+GitHub release. `@cursor/sdk` 1.3.1 is an external dependency, as are the
+ACP SDK and keyring. The package bundles none of them; chord's binary
+contains neither the Cursor SDK nor the keyring.
+
+## License
+
+MIT

package/dist/bin.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+// packages/cursor-cloud-acp/src/bin.ts
+var [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+if (major < 22 || major === 22 && minor < 13) {
+  process.stderr.write(`cursor-cloud-acp needs Node 22.13 or newer; this is Node ${process.versions.node}.
+`);
+  process.exit(1);
+}
+import("./main.js").then(({ main }) => main(process.argv.slice(2))).then((status) => {
+  process.stdout.write("", () => process.exit(status));
+}, (error) => {
+  process.stderr.write(`cursor-cloud-acp: ${error instanceof Error ? error.message : String(error)}
+`);
+  process.exitCode = 1;
+});