/add-cursor

name: add-cursor
description: Use Cursor (local Agent SDK) as a full agent provider — planning, tool orchestration, MCP tools, session resume — alongside or instead of Claude. Cursor-account sign-in or API key, held by the credential gateway. Per-group via `ncl groups config update --provider cursor`. Distinct from using Cursor as a cloud agent (those run on Cursor VMs and are not this provider).
metadata:
  nanoclaw-provider: cursor
  nanoclaw-provider-label: Cursor
  nanoclaw-provider-hint: Cursor — account sign-in or API key
  nanoclaw-provider-offered: 'true'
  nanoclaw-provider-image: local-required

Cursor agent provider

> Shortcut: `pnpm exec tsx setup/index.ts --step provider-auth cursor` performs this whole install (payload files, barrels, SDK pin, image rebuild) plus auth in one command. The steps below are the same operations, for agent-driven or manual application.

NanoClaw selects each group's agent backend from `container_configs.provider` (default `claude`). This skill installs the Cursor provider: copy the payload from this skill's `payload/`, append one import to each of the five provider and contract barrels, pin `@cursor/sdk` in the agent-runner tree, rebuild, then run the auth walk-through.

The provider runs `@cursor/sdk` in-process inside the container (`Agent.create` / `resume` / `send`): native streaming, MCP tools, a local agent store (the continuation is a Cursor `agentId`). It integrates through the provider contracts only — a data-only host contract declares the composed `AGENTS.md`, the per-group `.cursor-shared` state volume at `~/.cursor`, the two Cursor-native skill directories and the Cursor model domains; the runtime contract declares the execution stance, model mapping, memory hooks, MCP mapping, and archives each exchange into `conversations/` through core's shared exchange archive.

Credentials stay in the credential gateway selected by `NANOCLAW_GATEWAY_PROVIDER`. The container only ever sees the placeholder `CURSOR_API_KEY=cursor_placeholder_nanoclaw`, which the SDK sends as a bearer header. Setup stores the key for two exact routes: `api2.cursor.sh/auth/exchange_user_api_key`, where the SDK swaps it for a short-lived runtime token, and `api.cursor.com/v1/models`, for model discovery. The runtime token stays in the SDK's memory and rides the same gateway proxy on the agent's Connect RPCs to `api2.cursor.sh`, which the gateway leaves untouched because the key is scoped to the exchange path. The payload ships `cursor.gateway-proxy.test.ts`, which proves every request of a real SDK run transits the proxy carrying nothing but the placeholder. Never put a key in chat.

The mechanical steps under **Install** carry `nc:` directive fences: an agent reads the prose and applies them, and a parser can apply them deterministically from the same document. Every directive is idempotent, so the whole skill is safe to re-run; anything a parser can't apply falls back to the prose beside it.

Install

Pre-flight

Install and refresh require host contract version 1, credential-connection seam version 2 or later (path-scoped credentials), and core's shared exchange archive (`container/agent-runner/src/provider-contracts/exchange-archive.ts`). The compatibility predicate below guards every later step, so an unsupported core receives no partial payload or dependency changes. If it prints `no`, stop and tell the operator to run `/update-nanoclaw` first.

node -e "const fs=require('fs'); const r=(f)=>fs.existsSync(f)?fs.readFileSync(f,'utf8'):''; if(/PROVIDER_HOST_CONTRACT_SEAM_VERSION = 1/.test(r('src/provider-contracts/registry.ts')) && /PROVIDER_CREDENTIAL_CONNECTION_SEAM_VERSION = ([2-9]|[1-9][0-9])/.test(r('setup/gateways/credential-store.ts')) && /export function archiveProviderExchange/.test(r('container/agent-runner/src/provider-contracts/exchange-archive.ts'))) console.log('yes'); else console.log('no')"

1. Copy the payload

Copy only the files listed below from this skill's `payload/` to the matching paths at the project root. These are skill-owned files; overwrite them together when refreshing the skill. The host files are the data-only host contract, the env adapter and their guards; the container files are the provider runtime (turn loop, event mapping, hooks.json writer), the runtime contract, the memory hook adapter, the host-side login helper, and their guards — including the conformance test the verifier requires and the gateway-proxy proof; the setup file is the picker entry and auth walk-through.

payload/src/providers/cursor.ts -> src/providers/cursor.ts
payload/src/providers/cursor-registration.test.ts -> src/providers/cursor-registration.test.ts
payload/src/providers/cursor-host-contribution.test.ts -> src/providers/cursor-host-contribution.test.ts
payload/src/provider-contracts/cursor.ts -> src/provider-contracts/cursor.ts
payload/container/agent-runner/src/providers/cursor.ts -> container/agent-runner/src/providers/cursor.ts
payload/container/agent-runner/src/providers/cursor-auth.ts -> container/agent-runner/src/providers/cursor-auth.ts
payload/container/agent-runner/src/providers/cursor-hook.ts -> container/agent-runner/src/providers/cursor-hook.ts
payload/container/agent-runner/src/providers/cursor-gateway-probe.ts -> container/agent-runner/src/providers/cursor-gateway-probe.ts
payload/container/agent-runner/src/providers/cursor-registration.test.ts -> container/agent-runner/src/providers/cursor-registration.test.ts
payload/container/agent-runner/src/providers/cursor.factory.test.ts -> container/agent-runner/src/providers/cursor.factory.test.ts
payload/container/agent-runner/src/providers/cursor-auth.test.ts -> container/agent-runner/src/providers/cursor-auth.test.ts
payload/container/agent-runner/src/providers/cursor-hook.test.ts -> container/agent-runner/src/providers/cursor-hook.test.ts
payload/container/agent-run