Add v1.1.0 with progress streaming, timeouts, and git validation.

Surface Cursor run progress to stderr and response payloads, enforce CURSOR_TIMEOUT_SECONDS, validate git repos before delegate, and fix resume session cwd persistence. Includes docs, tests, and packaging. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-19 08:08:14 +03:00
commit 1d71b3f822
17 changed files with 1096 additions and 0 deletions
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -0,0 +1,104 @@
+# Configuration
+
+Environment variables use the `CURSOR_` prefix (via `pydantic-settings`).
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CURSOR_API_KEY` | *(empty)* | Cursor user API key. Prefer `~/.hermes/.env` when using Hermes launcher. |
+| `CURSOR_DEFAULT_MODEL` | `composer-2.5` | Default Cursor model for delegations. |
+| `CURSOR_DEFAULT_CWD` | `~/Projects` | Default project root when `cwd` is omitted. |
+| `CURSOR_TIMEOUT_SECONDS` | `1800` | Max seconds per delegation/resume run before cancel + error. |
+| `CURSOR_REQUIRE_GIT_REPO` | `true` | When true, `cwd` must be inside a git work tree before delegate. |
+| `CURSOR_SESSIONS_PATH` | `~/.local/share/cursor-mcp/sessions.json` | Persisted session index for resume. |
+| `CURSOR_AUDIT_LOG_PATH` | `~/.local/share/cursor-mcp/audit.jsonl` | JSONL audit trail. |
+
+## Hermes registration
+
+Recommended launcher (loads `CURSOR_*` from `~/.hermes/.env`):
+
+```yaml
+mcp_servers:
+  cursor:
+    command: /Users/nearxos/.hermes/mcp_servers/cursor-mcp-env.sh
+    enabled: true
+    timeout: 1900
+    env:
+      CURSOR_DEFAULT_CWD: /Users/nearxos/Projects
+      CURSOR_DEFAULT_MODEL: composer-2.5
+      CURSOR_TIMEOUT_SECONDS: 1800
+      CURSOR_REQUIRE_GIT_REPO: true
+```
+
+Set Hermes MCP `timeout` slightly above `CURSOR_TIMEOUT_SECONDS` so the server can return a structured timeout error.
+
+## Progress streaming
+
+During long runs, cursor-mcp writes human-readable lines to **stderr**:
+
+```text
+[cursor-mcp] status: running
+[cursor-mcp] delta: started read_file
+[cursor-mcp] step: tool call: edit_file
+```
+
+Hermes captures these in `~/.hermes/logs/mcp-stderr.log`.
+
+The tool response JSON also includes:
+
+```json
+{
+  "status": "finished",
+  "progress": [
+    {"ts": "...", "kind": "status", "message": "running"},
+    {"ts": "...", "kind": "delta", "message": "started read_file", "tool": "read_file"}
+  ]
+}
+```
+
+## Git validation
+
+When `CURSOR_REQUIRE_GIT_REPO=true` (default), delegate tools fail fast if `cwd` is not a git repo:
+
+```text
+Working directory is not a git repository: /path. Initialize git or set CURSOR_REQUIRE_GIT_REPO=false
+```
+
+Successful validation adds repo metadata to the response `git` field (`root`, `branch`, `commit`, `dirty`).
+
+For scratch prototypes:
+
+```bash
+export CURSOR_REQUIRE_GIT_REPO=false
+```
+
+## Timeouts
+
+On timeout the server attempts `run.cancel()` and returns:
+
+```text
+Cursor run timed out after 1800s (run_id=...)
+```
+
+Tune per environment:
+
+- Fast patches: `CURSOR_TIMEOUT_SECONDS=600`
+- Large refactors: `CURSOR_TIMEOUT_SECONDS=3600`
+
+## Session resume
+
+`cursor_delegate_session` and `cursor_resume` store sessions in `CURSOR_SESSIONS_PATH`.
+
+Each entry includes `agent_id`, `cwd`, `task_summary`, and `updated_at`.
+
+`cursor_resume` uses the stored `cwd` when updating session history (fixed in 1.1.0).
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `CURSOR_API_KEY is not set` | Add to `~/.hermes/.env`, restart Hermes desktop |
+| `not a git repository` | `git init` in project or disable `CURSOR_REQUIRE_GIT_REPO` |
+| Timeout errors | Increase `CURSOR_TIMEOUT_SECONDS` or narrow task scope |
+| No progress in logs | Ensure stderr is captured; check `mcp-stderr.log` |
+
+See also the Hermes skill `autonomous-ai-agents/cursor-delegation`.