@buildify-cli/cursor-agent 0.1.1 → 0.2.1

package/README.md

@@ -1,27 +1,35 @@
-# @buildify/cursor-agent
+# Buildify Cursor Agent
 
-Node.js client runner for the Buildify **Cursor Broker** bundle. It connects to `CursorBrokerTriggerNode`, receives submitted tasks over SSE/HTTP, and executes them locally with [`@cursor/sdk`](https://cursor.com/docs/sdk/typescript).
+`buildify-cursor-agent` connects Buildify Agent Broker to the local Cursor CLI. It pulls `cursor.task` jobs from Broker, runs them through Cursor `agent acp`, then reports task results, token usage, and errors back to Broker.
 
-## Architecture
+## Requirements
 
-```
-Buildify Workflow
-  └── CursorBrokerTriggerNode (Java Netty HTTP server)
-        └── CursorSubmitTaskNode (submit task)
-        └── CursorCancelTaskNode (cancel task)
-              ↕ HTTP + SSE
-        @buildify/cursor-agent (this package)
-              └── @cursor/sdk Agent.create() + agent.send()
+- Node.js 18 or newer
+- Cursor CLI installed on the agent machine
+- A Cursor API key for the task model
+- Network access from the agent machine to Buildify Agent Broker
+
+Check Cursor CLI:
+
+```bash
+agent --version
+agent --help
 ```
 
-## Requirements
+If `agent` is not available, install the Cursor CLI:
 
-- Node.js 18+
-- macOS (for `install-service`; foreground/daemon mode works on any OS)
-- Buildify workflow with `CursorBrokerTriggerNode` running and reachable
+```bash
+buildify-cursor-agent install-cursor
+```
 
 ## Install
 
+From npm:
+
+```bash
+npm install -g @buildify-cli/cursor-agent
+```
+
 From this repository:
 
 ```bash
@@ -31,158 +39,270 @@ npm run build
 npm link
 ```
 
-Or after publishing:
+Verify:
 
 ```bash
-npm install -g @buildify/cursor-agent
+buildify-cursor-agent --version
+buildify-cursor-agent --help
 ```
 
-## Configuration
+## Quick Start
 
-Initialize defaults:
+Create the default config file:
 
 ```bash
 buildify-cursor-agent config init
 ```
 
-Edit `~/.buildify/cursor-agent.json`:
+Set Broker connection values:
 
-```json
-{
-  "server": "http://localhost:8080",
-  "clientId": "my-macbook",
-  "defaultCwd": "/Users/you/projects",
-  "maxConcurrent": 2,
-  "token": "",
-  "logLevel": "info",
-  "streamLogs": false,
-  "requestTimeoutMs": 30000,
-  "reconnectMinDelayMs": 1000,
-  "reconnectMaxDelayMs": 30000
-}
+```bash
+buildify-cursor-agent config set \
+  server=http://localhost:8080 \
+  token=<broker-token> \
+  clientId=<agent-client-id>
 ```
 
-Or set values via CLI:
+Optionally set a default Cursor API key for model discovery:
 
 ```bash
-buildify-cursor-agent config set \
-  server=http://192.168.1.10:9001 \
-  clientId=my-macbook \
-  defaultCwd=/Users/you/projects \
-  token=broker_server_key
+buildify-cursor-agent config set cursorApiKey=<cursor-api-key>
 ```
 
-| Key | Description |
-|-----|-------------|
-| `server` | Base URL of the Java Cursor Broker (from `CursorBrokerTriggerNode` status) |
-| `clientId` | Unique agent identifier; must match `CursorSubmitTaskNode.clientId` |
-| `defaultCwd` | Default working directory when a task has no `cwd` |
-| `maxConcurrent` | Max parallel Cursor SDK runs (reported at connect) |
-| `token` | Bearer token when Buildify auth is enabled (`Authorization: Bearer <serverKey>`) |
-| `logLevel` | `error`, `warn`, `info`, or `debug` |
-| `streamLogs` | Print Cursor SDK stream messages to stdout for debugging |
-| `requestTimeoutMs` | HTTP timeout for broker calls |
-| `reconnectMinDelayMs` | Minimum reconnect backoff |
-| `reconnectMaxDelayMs` | Maximum reconnect backoff |
-
-Show current config (secrets masked):
+Start in the foreground:
 
 ```bash
-buildify-cursor-agent config show
+buildify-cursor-agent start --logs
 ```
 
-## Usage
+Start as a background daemon:
+
+```bash
+buildify-cursor-agent start --daemon
+buildify-cursor-agent status
+buildify-cursor-agent stop
+```
 
-### Foreground
+Install as a macOS launchd service:
 
 ```bash
-buildify-cursor-agent start
+buildify-cursor-agent install-service
+buildify-cursor-agent status
+buildify-cursor-agent uninstall-service
 ```
 
-Press `Ctrl+C` to disconnect cleanly (`DELETE /disconnect`).
+## Configuration
+
+Config file:
 
-### Debug logs
+```text
+~/.buildify/cursor-agent.json
+```
+
+Show current config:
 
 ```bash
-buildify-cursor-agent start --log-level debug --stream-logs
+buildify-cursor-agent config show
 ```
 
-`--stream-logs` prints Cursor SDK stream events such as status, assistant text, thinking, and tool calls. The runner also reports task progress events back to `CursorBrokerTriggerNode`.
+Set config values:
 
-When a task provides `cwd`, the runner resolves it on the agent machine and creates the directory recursively if it does not already exist. If the path exists but is not a directory, the task fails.
+```bash
+buildify-cursor-agent config set key=value [key=value ...]
+```
 
-### Background daemon
+Common keys:
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `server` | `http://localhost:8080` | Buildify Agent Broker URL |
+| `clientId` | host name | Agent client ID registered with Broker |
+| `token` | empty | Broker auth token |
+| `defaultCwd` | `~/projects` | Default working directory on the agent machine |
+| `maxConcurrent` | `2` | Max parallel Cursor tasks |
+| `cursorApiKey` | empty | Cursor API key used for model discovery |
+| `cursorBin` | `agent` | Cursor CLI executable path |
+| `defaultModel` | `composer-2.5` | Fallback model when discovery fails |
+| `usageProbe` | `true` | Probe Cursor print mode for usage if ACP omits it |
+| `logs` | `false` | Print local agent logs |
+
+Configuration priority:
+
+1. CLI flags
+2. Environment variables
+3. `~/.buildify/cursor-agent.json`
+4. Built-in defaults
+
+## Environment Variables
+
+| Variable | Description |
+| --- | --- |
+| `BUILDIFY_SERVER` | Broker server URL |
+| `BUILDIFY_TOKEN` | Broker auth token |
+| `BUILDIFY_CLIENT_ID` | Agent client ID |
+| `BUILDIFY_LOGS` | Enable local logs |
+| `CURSOR_API_KEY` | Cursor API key |
+| `BUILDIFY_CURSOR_API_KEY` | Cursor API key alias |
+| `BUILDIFY_CURSOR_BIN` | Cursor `agent` executable path |
+| `BUILDIFY_CURSOR_USAGE_PROBE` | Enable or disable usage probing |
+
+Example:
 
 ```bash
-buildify-cursor-agent start --daemon
-buildify-cursor-agent status
+BUILDIFY_SERVER=http://localhost:8080 \
+BUILDIFY_TOKEN=<broker-token> \
+BUILDIFY_CLIENT_ID=cursor-local \
+CURSOR_API_KEY=<cursor-api-key> \
+buildify-cursor-agent start --logs
+```
+
+## CLI Commands
+
+```bash
+buildify-cursor-agent start [options]
 buildify-cursor-agent stop
+buildify-cursor-agent status
+buildify-cursor-agent install-service
+buildify-cursor-agent uninstall-service
+buildify-cursor-agent install-cursor
+buildify-cursor-agent config init
+buildify-cursor-agent config show
+buildify-cursor-agent config set key=value [key=value ...]
 ```
 
-PID file: `~/.buildify/cursor-agent.pid`
+`start` options:
+
+| Option | Description |
+| --- | --- |
+| `--daemon` | Run in background |
+| `--foreground` | Run in foreground |
+| `--server <url>` | Override Broker URL |
+| `--token <token>` | Override Broker token |
+| `--client-id <id>` | Override client ID |
+| `--logs` | Enable local logs |
+| `--request-timeout-ms <ms>` | HTTP request timeout |
+
+## Use In Buildify
+
+Use `AgentCursorSubmitTaskNode` to submit Cursor tasks.
+
+Required fields:
+
+- Broker instance
+- Client ID matching the running `buildify-cursor-agent`
+- Cursor model
+- Cursor API key
+- Prompt
+- Working directory (`cwd`)
+
+Important: `cwd` is a path on the machine where this agent runs. It is not the Buildify server path. If the directory may not exist, enable “create working directory if missing”.
+
+## Cursor Task Fields
+
+The runner supports these task values from Buildify:
 
-### macOS launchd service (like Docker Desktop auto-start)
+- `prompt`: user instruction sent to Cursor
+- `cwd`: local working directory on the agent machine
+- `model`: Cursor model, for example `composer-2.5`
+- `cursorApiKey`: Cursor API key used by the task
+- `conversationId`: optional ACP session ID to resume
+- `mcpServers`: optional MCP server definitions passed to Cursor ACP
+- `createCwdIfMissing`: whether the agent may create `cwd`
 
-Install a user LaunchAgent that starts on login and restarts on failure:
+Each task starts a fresh Cursor ACP subprocess:
+
+```bash
+agent --api-key <cursor-api-key> --model <model> acp
+```
+
+## Usage Reporting
+
+Cursor ACP may not always report token usage directly. When `usageProbe=true`, this agent performs a best-effort usage probe after the task finishes.
+
+Reported usage can include:
+
+- input tokens
+- output tokens
+- reasoning tokens
+- cache read/write tokens
+- source metadata such as `acp`, `print-probe`, or `estimated`
+
+If usage cannot be read from Cursor, the runner falls back to an estimate so Broker still receives a useful usage payload.
+
+## Debugging
+
+Enable normal logs:
+
+```bash
+buildify-cursor-agent start --logs
+```
+
+Check daemon/service status:
 
 ```bash
-buildify-cursor-agent install-service
 buildify-cursor-agent status
 ```
 
-Logs:
+Install or verify the Cursor CLI:
 
-- `~/.buildify/cursor-agent.log`
-- `~/.buildify/cursor-agent.log.err`
+```bash
+buildify-cursor-agent install-cursor
+```
 
-Uninstall:
+For local ACP investigation, use the debug script:
 
 ```bash
-buildify-cursor-agent uninstall-service
+node debug-acp.mjs \
+  --model composer-2.5 \
+  --api-key <cursor-api-key> \
+  --prompt "say hello"
 ```
 
-## Protocol
+## Common Errors
+
+### `Task is missing cursorApiKey`
+
+The task did not include a Cursor API key. Set the key in Buildify `ModelSelect` or pass `cursorApiKey` in the task payload.
 
-Implements the client side of the Cursor Broker HTTP API:
+### `Cursor API key is invalid`
 
-| Method | Path | Purpose |
-|--------|------|---------|
-| `POST` | `/connect` | Register client, get `sessionId` |
-| `GET` | `/events` | SSE stream (`newTask` and `cancelled` events) |
-| `GET` | `/tasks/next` | Pull next queued task |
-| `POST` | `/tasks/{taskId}/events` | Report received / progress / completed / failed / cancelled |
-| `POST` | `/heartbeat` | Keep-alive with `runningCount` |
-| `DELETE` | `/disconnect` | Clean shutdown |
+Check whether the API key is valid and not redacted. The task must pass the real key value, not a masked placeholder.
 
-Headers:
+### `Cursor usage limit reached`
 
-- `Agent-Client-Id` — agent identifier
-- `Agent-Session-Id` — session from `/connect`
+The selected Cursor account or model has reached its usage limit. Try another model or wait for quota reset.
 
-Model discovery:
+### `Working directory does not exist`
 
-- The runner sends its cached model list in `/connect` and `/heartbeat`.
-- The model cache is refreshed from Cursor with the task-scoped `cursorApiKey` when a task starts.
-- `CursorSubmitTaskNode.model` loads options from the selected `clientId`; if the agent has not reported models yet, it falls back to `composer-2.5`.
+The `cwd` path does not exist on the agent machine and `createCwdIfMissing` is disabled. Use a local path on the agent machine or enable directory creation.
 
-## Buildify workflow setup
+### `Cursor CLI not found`
 
-1. Add **Cursor Broker Trigger** node; note the listening port in node status.
-2. Enable auth if needed and configure **Cursor Broker Credential** (`serverKey`).
-3. Set `token` in client config to the same `serverKey`.
-4. Add **Submit Cursor Task** node with matching `clientId` and task-scoped `cursorApiKey`.
-5. Optionally add **Cancel Cursor Task** node and pass `taskId` to cancel queued or running tasks.
-6. Start this runner on the target machine.
+The `agent` binary is missing or not on `PATH`. Run:
+
+```bash
+buildify-cursor-agent install-cursor
+```
+
+Or configure:
+
+```bash
+buildify-cursor-agent config set cursorBin=/path/to/agent
+```
 
 ## Development
 
 ```bash
 npm install
-npm run dev -- config show
-npm run dev -- start
+npm run typecheck
 npm run build
+npm run build:dev
 ```
 
-## License
+Before publishing:
 
-MIT
+```bash
+npm run typecheck
+npm run build
+npm pack --dry-run
+```