@cursor/july 0.1.89 → 0.1.91

package/AGENTS.md

@@ -9,6 +9,14 @@ User-facing documentation lives in [`docs/`](./docs/README.md)
 troubleshooting, reference). This file is the terse loop reference;
 point humans at the docs.
 
+Before committing or reviewing any Agent SDK documentation change, read
+`docs/.cursor/skills/writing/SKILL.md` and
+`docs/.cursor/skills/docs-lint/SKILL.md`. Run `/docs-lint` on every change.
+
+Before writing or editing a template, read
+[`docs/.cursor/skills/template-lint/SKILL.md`](./docs/.cursor/skills/template-lint/SKILL.md).
+Run `/template-lint` before every commit or review that changes `templates/`.
+
 Run the CLI under **Node, never Bun** — use the installed `agent-serve`
 (or `agent-sdk`) bin; from a source checkout of this package,
 `pnpm exec tsx src/bin/agent-serve.ts <command> …` is equivalent. Bun's

package/README.md

@@ -15,7 +15,7 @@ as the execution engine.
 
 **User-facing documentation lives in [`docs/`](./docs/README.md)** —
 open it with `npx @cursor/july docs`, or at `/docs` on every running
-`agent-serve serve` host — getting started, concepts, guides (Slack,
+`agent-sdk serve` host. It covers getting started, concepts, guides (Slack,
 GitHub webhooks, approvals, agent-to-agent, cloud runtime), evals, live
 A/B metrics, hillclimbing, deployment, troubleshooting, and reference
 pages for each folder. This README is the compact package reference.
@@ -44,6 +44,10 @@ my-agent/
     │   └── webhook.ts       # HTTP surfaces beyond the built-in session API
     ├── hooks/
     │   └── audit.ts         # observe the runtime event stream
+    ├── storage.ts           # optional durable storage
+    ├── artifacts.ts         # optional artifact kinds and retention
+    ├── otel.ts              # optional OpenTelemetry export
+    ├── playground/          # optional custom playground tool chips
     ├── ab.ts                # optional live A/B experiment
     ├── ab/                  # optional: more experiments
     ├── schedules/
@@ -52,20 +56,21 @@ my-agent/
     └── lib/                 # shared code (import-only, never discovered)
 ```
 
-Scaffold a starter project with `agent-serve init ./my-agent` — a minimal
-agent (`package.json`, `tsconfig.json`, `agent/agent.ts`,
-`agent/instructions.md`, and a demo `agent/tools/echo.ts`) that serves
-immediately and type-checks with `npm run check`. From there, grow it folder
-by folder; the [docs](./docs/README.md) walk a weather agent from a single
+Scaffold a starter project with `agent-sdk init ./my-agent`. It writes
+`AGENTS.md`, `.gitignore`, `package.json`, `tsconfig.json`, `agent/agent.ts`,
+`agent/instructions.md`, `agent/tools/echo.ts`, and `agent/hooks/memory.ts`.
+The project serves immediately and type-checks with `npm run check`. From
+there, grow it folder by folder. The
+[docs](./docs/README.md) walk a weather agent from a single
 `get_weather` tool through skills, channels, evals, and deployment.
 
-Serve one project with `agent-serve serve --dir ./my-agent --dev`, or point
+Serve one project with `agent-sdk serve --dir ./my-agent --dev`, or point
 `serve` at a folder of agent projects to mount every child under its
 directory name.
 
 ## Node only — do not run under Bun
 
-Run agent-serve with **Node 22+** (from source: `pnpm exec tsx
+Run the Agent SDK with **Node 22.13+** (from source: `pnpm exec tsx
 src/bin/agent-serve.ts …`, or the built `dist/bin/agent-serve.js`). Do not
 run it under Bun: Bun's HTTP/2 client corrupts the Cursor SDK's local
 harness tool-result streams (`NGHTTP2_FRAME_SIZE_ERROR`), so every built-in
@@ -79,7 +84,7 @@ Point `serve` at a **folder of agent projects** and it hosts all of them on
 one port, each under its own slug (its directory name):
 
 ```bash
-agent-serve serve --dir ./agents --dev
+agent-sdk serve --dir ./agents --dev
 # 2 agents listening
 #   playground  http://127.0.0.1:5273
 ```
@@ -101,7 +106,7 @@ In multi-agent mode:
 - sessions are isolated per agent (`<stateRoot>/<slug>/`), and the playground
   gains a "← all agents" link back to the index.
 - point the terminal client at a slug:
-  `agent-serve chat --url http://127.0.0.1:3000/weather-agent`.
+  `agent-sdk chat --url http://127.0.0.1:3000/weather-agent`.
 
 Slugs come from directory names and must match `[A-Za-z0-9][A-Za-z0-9_-]*`
 and not collide with the reserved `v1` / `playground` / `docs` path
@@ -163,8 +168,8 @@ instructions narrowly (the concierge above delegates *weather questions* to
 `weather-agent`, not everything).
 
 ```bash
-agent-serve serve --dir ./agents --dev
-agent-serve chat --url http://127.0.0.1:3000/concierge \
+agent-sdk serve --dir ./agents --dev
+agent-sdk chat --url http://127.0.0.1:3000/concierge \
   --message "What's the weather in Paris right now?"
 # concierge → weather.ask → weather-agent's own session/tools → reply
 ```
@@ -198,9 +203,9 @@ Serve it (turns run on the Cursor harness, so the host needs a Cursor
 credential — sign in once, or export an API key):
 
 ```bash
-agent-serve login          # browser sign-in; mints + stores a revocable API key
+agent-sdk login          # browser sign-in; mints + stores a revocable API key
 # or: export CURSOR_API_KEY=key_...
-agent-serve serve --dir . --port 3000
+agent-sdk serve --dir . --port 3000
 # e.g. playground at http://127.0.0.1:3000/<dirname>/playground
 ```
 
@@ -233,28 +238,28 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/session/ses_... \
 Inspect the discovered surface at any time:
 
 ```bash
-agent-serve info --dir .        # or GET /<slug>/v1/info on a running server
-agent-serve validate --dir .    # exit non-zero on error diagnostics
+agent-sdk info --dir .        # or GET /<slug>/v1/info on a running server
+agent-sdk validate --dir .    # exit non-zero on error diagnostics
 ```
 
 ## Terminal client
 
-`agent-serve chat` talks to a running server over the same public API and
+`agent-sdk chat` talks to a running server over the same public API and
 renders the reply live — streamed text, tool calls, and a per-turn usage
 footer. Pass `--json` for a compact trajectory (same shape as `run`).
 
 ```bash
 # interactive REPL against a local server
-agent-serve chat --url http://127.0.0.1:3000
+agent-sdk chat --url http://127.0.0.1:3000
 
 # one-shot (good for piping / scripts)
-agent-serve chat --url http://127.0.0.1:3000 --message "Weather in Paris?"
+agent-sdk chat --url http://127.0.0.1:3000 --message "Weather in Paris?"
 
 # JSON trajectory (for coding agents / scripts)
-agent-serve chat --url http://127.0.0.1:3000 --message "hello" --json
+agent-sdk chat --url http://127.0.0.1:3000 --message "hello" --json
 
 # against an authed server
-agent-serve chat --url https://my-agent.example.com --bearer-token "$TOKEN"
+agent-sdk chat --url https://my-agent.example.com --bearer-token "$TOKEN"
 ```
 
 ## Agent loop
@@ -263,19 +268,19 @@ Coding agents should prefer the JSON-first commands: edit files → inspect
 → run a turn → assert with filesystem evals.
 
 ```bash
-agent-serve validate --dir .
-agent-serve info --dir . --json
+agent-sdk validate --dir .
+agent-sdk info --dir . --json
 
 # Ephemeral server + one (or more) turns; JSON trajectory on stdout
-agent-serve run --dir . --message "What's the temperature in NYC?"
+agent-sdk run --dir . --message "What's the temperature in NYC?"
 
 # Optional event log for later summarization
-agent-serve run --dir . --message "..." --events /tmp/run.ndjson
-agent-serve trajectory --events /tmp/run.ndjson
+agent-sdk run --dir . --message "..." --events /tmp/run.ndjson
+agent-sdk trajectory --events /tmp/run.ndjson
 
 # Scaffold (or print the setup guide with no directory)
-agent-serve init ./my-agent
-agent-serve init
+agent-sdk init ./my-agent
+agent-sdk init
 ```
 
 `run` / `eval` boot a temporary server on port `0` with a temp `stateRoot`
@@ -306,6 +311,9 @@ export default defineEval({
 Case id is the path under `evals/` for a single-`test` file, or
 `<fileId>/<case.id>` when using `cases` in one file.
 
+Use `t.judge` when wording needs an LLM grader. The built-in JUnit and
+Artifacts reporters write CI results and per-case evidence.
+
 Every project with evals needs `evals/evals.config.ts` with a required
 `maxConcurrency` (hard-capped at 200 due to model provider request limits).
 Playground batches are in-memory by default; declare an `evals` table in
@@ -324,12 +332,12 @@ export default defineEvalConfig({
 ```
 
 ```bash
-agent-serve eval --dir . --list
-agent-serve eval --dir . --json
-agent-serve eval --dir . weather/nyc         # one datapoint
-agent-serve eval --dir . weather             # whole file
-agent-serve eval --dir . weather forecast    # multiple files
-agent-serve eval --dir . --tag smoke
+agent-sdk eval --dir . --list
+agent-sdk eval --dir . --json
+agent-sdk eval --dir . weather/nyc         # one datapoint
+agent-sdk eval --dir . weather             # whole file
+agent-sdk eval --dir . weather forecast    # multiple files
+agent-sdk eval --dir . --tag smoke
 ```
 
 See [`docs/`](./docs/README.md) for the full documentation set,
@@ -339,10 +347,10 @@ evals, hillclimb, GitHub webhooks, Slack setup, debugging).
 
 ## Web playground
 
-Every served agent ships with a built-in playground at
-`http://127.0.0.1:3000/playground` — a Vite + React SPA (reusing
-Cursor's internal UI components) over the same public HTTP API, made for quick
-manual testing and demo recordings:
+Every served agent ships with a built-in playground. The default multi-agent
+mode serves it at `http://127.0.0.1:3000/<slug>/playground`.
+`--mode single` uses `http://127.0.0.1:3000/playground`. The Vite and React
+app uses the same public HTTP API for manual testing and demo recordings:
 
 - chat with the agent and watch text/reasoning stream live, rendered as
   markdown (headings, lists, tables, blockquotes, links) with syntax
@@ -361,7 +369,7 @@ manual testing and demo recordings:
   connections, channels, hooks),
 - flip on the raw NDJSON pane to see the exact wire events.
 
-The SPA is a static bundle. `agent-serve serve` auto-builds `dist/playground/`
+The SPA is a static bundle. `agent-sdk serve` auto-builds `dist/playground/`
 when it is missing and the local vite toolchain is present (`pnpm run build`
 also emits it for publish). The server serves the bundle and every call it
 makes runs the normal route auth chain (there's a bearer-token field for
@@ -461,7 +469,7 @@ export default defineAgent({
 ```
 
 `model` accepts a Cursor model id string or `{ id, params }`. When omitted
-on the root agent, agent-serve defaults to `grok-4.5` with `effort=high`
+on the root agent, the Agent SDK defaults to `grok-4.5` with `effort=high`
 and `fast=true`.
 
 `runtime` selects where turns execute:
@@ -469,9 +477,10 @@ and `fast=true`.
 | Value     | Behavior |
 | --------- | ------- |
 | `"local"` | Cursor SDK local harness on this machine. Session id doubles as the SDK agent id. Authored tools, skills, and sandbox seeds apply. |
-| `"cloud"` | Cursor cloud agents. Pass a `cloud` block (repos, env, envVars, …) forwarded to the SDK. In-process server tools are not available; instructions and agent-tool catalogs are prepended to the first prompt because the local session workspace is not the cloud VM. |
+| `"cloud"` | Cursor cloud agents. Pass a `cloud` block with the repositories and environment the agent needs. Server tools work on managed hosting. Self-hosted cloud turns need `--public-url`. |
 
-Discovery warns when `runtime: "cloud"` is combined with agent tools or sandbox seeds that only apply locally. Authored skills still warn: they sync onto an Agent Store for native discovery rather than the session workspace.
+Discovery warns when cloud turns ignore a local-only capability. Authored
+skills remain available automatically.
 
 ### Instructions
 
@@ -489,7 +498,7 @@ One file per tool; the filename is the tool name the model sees.
 
 | Value | Behavior |
 | ----- | -------- |
-| `"server"` (default) | In-process on the agent-serve host via Cursor SDK custom tools. Requires `execute`. Only available when the agent `runtime` is `"local"`. |
+| `"server"` (default) | Runs on the serve host. Available to local turns and managed cloud deployments. Self-hosted cloud turns need `--public-url`. Requires `execute`. |
 | `"agent"` | Materialized into the agent environment as a shell script. Requires `script` (JSON on stdin, result on stdout). Works with local and cloud agent runtimes. |
 
 Server tool (default):
@@ -603,10 +612,12 @@ printf '%s\\n' "$message"
 });
 ```
 
-`inputSchema` is a zod schema (validated and typed for server tools) or a
-plain JSON Schema object (forwarded as-is). For server tools, `ctx` carries
-`{ toolCallId, session, workspaceDir }`. Return a string, a JSON value, or
-`{ content: [...], isError? }` for rich results.
+`inputSchema` is a Zod schema (validated and typed for server tools) or a
+plain JSON Schema object (forwarded as-is). `outputSchema` advertises a
+structured result schema. The host doesn't validate results against it.
+Plain objects fill `structuredContent` automatically. Envelope results set
+it explicitly next to `content` and `isError`. For server tools, `ctx` carries
+`{ toolCallId, session, workspaceDir }`.
 
 #### Deterministic tool calls
 
@@ -629,8 +640,8 @@ From the CLI (boots an ephemeral server unless `--url` targets a running
 one):
 
 ```bash
-agent-serve call get_weather --dir . --input '{"city":"NYC"}'
-agent-serve call get_weather --url http://127.0.0.1:3000/<slug> --input '{"city":"NYC"}'
+agent-sdk call get_weather --dir . --input '{"city":"NYC"}'
+agent-sdk call get_weather --url http://127.0.0.1:3000/<slug> --input '{"city":"NYC"}'
 ```
 
 Programmatically, `callTool(toolName, input, options?)` is available on the
@@ -725,7 +736,7 @@ name.
 
 Requirements and behavior:
 
-- The host must be signed in (`agent-serve login` or `CURSOR_API_KEY`);
+- The host must be signed in (`agent-sdk login` or `CURSOR_API_KEY`);
   `serve` fails fast at startup otherwise, and logs each connector's live
   status (`connected` / `needsAuth` / `error`) as it starts.
 - Local turns and host-side calls go through a loopback bridge route guarded
@@ -743,7 +754,7 @@ Requirements and behavior:
 Every MCP connection is always available in three places:
 
 1. the Cursor agent (local or cloud), via SDK `mcpServers`
-2. the agent-serve host, for in-process tools via `ctx.host.mcp`
+2. the serve host, for in-process tools via `ctx.host.mcp`
 3. channel / schedule handlers, via `args.host.mcp` (deterministic — no agent loop)
 
 ```ts
@@ -788,7 +799,7 @@ default multi-agent layout; at the server root with `mode: "single"`):
   `sessionId` + `continuationToken`)
 - `POST /v1/session/:sessionId` — follow-up (`{"message", "continuationToken"}`;
   rotates the token; works for any chat session including custom channels like
-  `drive`; `409` on stale tokens, busy sessions, or task/schedule sessions;
+  `drive`; `409` on stale tokens or task sessions;
   `403` if the caller is not the session owner)
 - `GET /v1/session/:sessionId/stream?startIndex=N` — replay + live NDJSON
   (same owner check)
@@ -928,7 +939,7 @@ Watched posts dispatch with the same thread-scoped principal as mentions
 left to the `app_mention` path; bot-authored posts never dispatch; deleting
 a post inside the debounce window cancels its dispatch. The Slack app must
 subscribe to `message.channels` / `message.groups`
-(`agent-serve slack create --channel-posts`) and be a member of each watched channel. Watched channels surface in
+(`agent-sdk slack create --channel-posts`) and be a member of each watched channel. Watched channels surface in
 `info` via `meta.slackChannelPosts`.
 
 **HITL compose:** park/resume is independent (`needsApproval` on tools). Opt in
@@ -966,19 +977,19 @@ from the mention and run the same host path as their HTTP channels.
 agent-to-agent only (no Slack channel).
 
 For Socket Mode apps (channel watch / approvals), run
-`agent-serve slack create`. It opens the dashboard wizard, creates and
+`agent-sdk slack create`. It opens the dashboard wizard, creates and
 installs the app, and writes the token pair to `.env.local`. To own the
-Slack app yourself, run `agent-serve slack init --manual` and paste the
+Slack app yourself, run `agent-sdk slack init --manual` and paste the
 manifests at api.slack.com.
 
-CLI (`agent-serve slack …`; guided setup in `skills/setup-slack/SKILL.md`):
+CLI (`agent-sdk slack …`; guided setup in `skills/setup-slack/SKILL.md`):
 
 ```bash
-agent-serve slack create --dir ./my-agent           # dashboard wizard (dev app)
-agent-serve slack create --dir ./my-agent --prod    # prod app
-agent-serve slack init --manual --dir ./my-agent    # manifests for api.slack.com
-agent-serve slack setup
-agent-serve slack doctor --prefix MY_AGENT
+agent-sdk slack create --dir ./my-agent           # dashboard wizard (dev app)
+agent-sdk slack create --dir ./my-agent --prod    # prod app
+agent-sdk slack init --manual --dir ./my-agent    # manifests for api.slack.com
+agent-sdk slack setup
+agent-sdk slack doctor --prefix MY_AGENT
 ```
 
 **GitHub** (`@cursor/july/channels/github`): a webhook channel pack
@@ -1009,7 +1020,7 @@ under `serve --dev`, which admits unsigned loopback deliveries so
 `{ auth }` to start a model turn as the actor, `{ task }` for host-side work
 (202 ACK, runs past GitHub's ~10s timeout), or `null` to skip.
 
-**Testing GitHub agents locally.** `cursorAccount` reuses `agent-serve login`
+**Testing GitHub agents locally.** `cursorAccount` reuses `agent-sdk login`
 for both Cursor SCM events and a refreshing repo-scoped GitHub credential used
 by `ctx.github`, `ctx.host.github`, and child `gh` commands. Default
 `permissions: "pr-write"` covers comments without `contents:write`; opt up to
@@ -1020,27 +1031,27 @@ auth prefers GitHub App installation tokens when `GITHUB_APP_ID` /
 `GITHUB_APP_PRIVATE_KEY` (and an installation id) are set, then falls back to
 `GITHUB_TOKEN` / `GH_TOKEN` or `gh auth login`. The channel publishes the
 webhook events it dispatches on (derived from the declared hooks, or pinned
-via `webhookEvents`), so `agent-serve github …` can forward live
+via `webhookEvents`), so `agent-sdk github …` can forward live
 deliveries with zero hand-listing — it wraps [`gh webhook
 forward`](https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/using-the-github-cli-to-forward-webhooks-for-testing):
 
 ```bash
 # One-time: gh + the cli/gh-webhook extension
-agent-serve github doctor --install
+agent-sdk github doctor --install
 
 # Terminal A: serve the agent (dev accepts unsigned loopback deliveries)
-agent-serve serve --dir ./my-agent --dev
+agent-sdk serve --dir ./my-agent --dev
 
 # Terminal B: forward this repo's deliveries to the discovered github channel
 # (URL + events auto-derived; repo inferred from the git remote). No secret
 # needed against a --dev server; set GITHUB_WEBHOOK_SECRET to verify signatures.
-agent-serve github forward --dir ./my-agent
+agent-sdk github forward --dir ./my-agent
 
 # Inspect what would be forwarded (URL + events per agent)
-agent-serve github events --dir ./agents --json
+agent-sdk github events --dir ./agents --json
 
 # Forward to EVERY discovered github channel at once
-agent-serve github forward --dir ./agents
+agent-sdk github forward --dir ./agents
 ```
 
 When several channels match (e.g. a folder of agent projects with more than
@@ -1054,8 +1065,8 @@ URL, so N processes would collide with `Hook already exists`.
 it registers a real webhook — and authenticates its relay with the GitHub CLI's
 own login. If `GITHUB_TOKEN` / `GH_TOKEN` is set in your env, deliveries fail
 with **HTTP 401** (the relay rejects env tokens); blank it for the command
-(`GITHUB_TOKEN= GH_TOKEN= agent-serve github forward …`) or `unset` it.
-`agent-serve github doctor` / `forward` warn when they detect this.
+(`GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward …`) or `unset` it.
+`agent-sdk github doctor` / `forward` warn when they detect this.
 
 Pass `--repo owner/repo` / `--org ORG` to override the inferred target,
 `--events a,b,c` to narrow the set, `--url` for a custom endpoint (e.g. a
@@ -1067,19 +1078,19 @@ still works too — `POST` a saved payload with an `x-github-event` header (no
 signature needed in `--dev`).
 
 **No admin? Hillclimbing? Use `github replay`.** `gh webhook forward` needs repo
-admin and a live event. `agent-serve github replay <pr_url>` instead **reads**
+admin and a live event. `agent-sdk github replay <pr_url>` instead **reads**
 the PR (pull access is enough — no admin, no relay, and `GITHUB_TOKEN` is fine)
 and synthesizes GitHub-shaped payloads it POSTs straight at the channel:
 
 ```bash
 # Replay a pull_request delivery for a PR to the discovered channel
-agent-serve github replay https://github.com/owner/repo/pull/123 --dir ./my-agent
+agent-sdk github replay https://github.com/owner/repo/pull/123 --dir ./my-agent
 
 # Replay everything the channel listens for (its declared events), CI failing
-agent-serve github replay owner/repo#123 --dir ./my-agent --events '*' --conclusion failure
+agent-sdk github replay owner/repo#123 --dir ./my-agent --events '*' --conclusion failure
 
 # Inspect payloads without POSTing (and snapshot them as reusable fixtures)
-agent-serve github replay owner/repo#123 --dir ./my-agent --events '*' --dry-run --out fixtures/github
+agent-sdk github replay owner/repo#123 --dir ./my-agent --events '*' --dry-run --out fixtures/github
 ```
 
 `--events` defaults to `pull_request` (`*` = the channel's declared events);
@@ -1094,8 +1105,9 @@ Cursor GitHub App is on the repo, `serve --cursor-events --repo owner/repo`
 long-polls `/v0/scm-events` with the host's Cursor account (no public URL /
 repo admin). Offset + consumer id live under `<state-root>/cursor-events/`.
 The stream is read as your Cursor user, so the flag **requires a signed-in
-host** (`agent-serve login`, `CURSOR_API_KEY`, or `serve({ apiKey })`) — serve
-fails fast rather than starting with a relay that can never receive events.
+host** (`agent-sdk login`, `CURSOR_API_KEY`, or `serve({ apiKey })`).
+Serve fails fast rather than starting with a relay that can never receive
+events.
 
 ### Hooks (`agent/hooks/*.ts`)
 Observe-only subscribers that run after each event is recorded — audit
@@ -1135,7 +1147,7 @@ export default defineSchedule({
 ```
 
 Cron expressions are standard 5-field, evaluated in UTC with minute
-granularity. In production mode (`agent-serve serve`) schedules fire on
+granularity. In production mode (`agent-sdk serve`) schedules fire on
 cadence; in dev mode (`--dev`) they never fire automatically — dispatch one
 by hand, exactly once, through the same path production uses:
 
@@ -1215,7 +1227,7 @@ console.log(`listening on ${handle.url}`);
 
 The Cursor credential resolves in one order everywhere (SDK turns, cloud
 runtime, Cursor account MCP connections): explicit `apiKey` option / `--api-key`
-→ `CURSOR_API_KEY` → the key stored by `agent-serve login`. `whoami` shows
+→ `CURSOR_API_KEY` → the key stored by `agent-sdk login`. `whoami` shows
 which one is active; `logout` removes the stored key (revoke it in the
 Cursor dashboard to kill it outright).
 
@@ -1225,7 +1237,7 @@ non-production backend, set **both** to the same URL — a key minted on one
 backend is rejected by the other.
 
 `serve` refuses to start when discovery produced error diagnostics; run
-`agent-serve validate` (or read `project.diagnostics`) to see why.
+`agent-sdk validate` (or read `project.diagnostics`) to see why.
 
 State lives under `<project>/.agent-serve/` (override with `stateRoot` /
 `--state-root`): `sessions/<id>/{session.json,events.ndjson,workspace/}`
@@ -1240,20 +1252,10 @@ when the agent should inherit that tree.
 
 ## Not supported (yet)
 
-Deliberately out of scope for now, and reported as warnings where the
-corresponding folder exists: per-subagent tools/skills/mcp-connections, nested
-subagents, WebSocket channel routes, platform channel packs for Discord
-and Teams (Slack is supported via `@cursor/july/channels/slack`;
-other platforms still use the authored `defineChannel` webhook form),
-OAuth-brokered MCP connections beyond the Cursor account
-(`{ cursorAccount: true }` covers connectors the account already
-authorized in Cursor), custom sandbox backends (`sandbox.ts`),
-instrumentation modules, dynamic per-caller capabilities, structured
-output schemas, and file uploads. Human-in-the-loop tool approvals
-(`needsApproval` on `execution: "server"` tools) are supported; exact
-resume of a parked tool call after host restart is not. Filesystem
-evals (`defineEval` under `evals/`), live A/B metrics (`defineAB` under
-`agent/ab`), and the `run` / `trajectory` commands are supported;
-LLM-as-judge scoring and external reporters are not yet. Context
-compaction is handled by the Cursor harness rather than
-configured here.
+The Agent SDK does not load per-subagent tools, skills, or MCP connections.
+It also rejects nested subagents, WebSocket channel routes, and custom
+sandbox backends. Discord and Teams do not have channel packs. Use an
+authored `defineChannel` integration for those platforms.
+
+Parked approval calls do not resume after a host restart. Context compaction
+is owned by the Cursor harness.

package/dist/ab.d.ts

@@ -14,7 +14,7 @@
  * sample/snapshot export lives on the `defineStorage` `abs` table.
  *
  * ```ts
- * import { defineAB, splitBySessionHash } from "@anysphere/agent-serve/ab";
+ * import { defineAB, splitBySessionHash } from "@cursor/july/ab";
  *
  * export default defineAB({
  *   name: "concise-instructions",

package/dist/ab.js

@@ -14,7 +14,7 @@
  * sample/snapshot export lives on the `defineStorage` `abs` table.
  *
  * ```ts
- * import { defineAB, splitBySessionHash } from "@anysphere/agent-serve/ab";
+ * import { defineAB, splitBySessionHash } from "@cursor/july/ab";
  *
  * export default defineAB({
  *   name: "concise-instructions",

package/dist/artifacts.d.ts

@@ -10,7 +10,7 @@
  *
  * ```ts
  * import { z } from "zod";
- * import { defineArtifacts } from "@anysphere/agent-serve/artifacts";
+ * import { defineArtifacts } from "@cursor/july/artifacts";
  *
  * export default defineArtifacts({
  *   kinds: {

package/dist/artifacts.js

@@ -10,7 +10,7 @@
  *
  * ```ts
  * import { z } from "zod";
- * import { defineArtifacts } from "@anysphere/agent-serve/artifacts";
+ * import { defineArtifacts } from "@cursor/july/artifacts";
  *
  * export default defineArtifacts({
  *   kinds: {

package/dist/bin/agent-serve.js

@@ -34,7 +34,7 @@ import { cmdCall, cmdChat, cmdCost, cmdEval, cmdEvalCancel, cmdEvalStatus, cmdIn
 import { ensureCursorLogin } from "../internal/cli-cursor.js";
 import { cmdDelete, cmdDeploy, cmdDeploymentStatus, cmdDeployments, cmdRotatePodCredential, cmdRotateToken, cmdSecretsList, cmdSecretsSet, cmdSecretsUnset, cmdStop, } from "../internal/cli-deploy.js";
 import { cmdManifest } from "../internal/cli-manifest.js";
-import { CLI_COMMAND_NAME as CLI, PACKAGE_NAME, packageVersion, } from "../internal/distribution.js";
+import { CLI_COMMAND_NAME as CLI, formatCliVersion, PACKAGE_NAME, packageVersion, } from "../internal/distribution.js";
 import { loadAgentLocalEnv } from "../internal/local-env.js";
 import { ENTER_RESTART_EXIT_CODE, isServeRestartWorker, runEnterRestartSupervisor, } from "../internal/serve-restart.js";
 import { clearTerminal, stdoutPalette } from "../internal/terminal-style.js";
@@ -100,7 +100,7 @@ Usage:
   ${CLI} logout
   ${CLI} whoami      [--json]
   ${CLI} update
-  ${CLI} version
+  ${CLI} version     [--json]
   ${CLI} deploy      [--dir <path>] [--slug <slug> | --all] [--team <id>] [--json]
                           [--no-wait] [--repo <url>] [--ref <ref>]
                           [--path <agentPath>] [--cursor-events-repo <owner/name>]...
@@ -170,7 +170,7 @@ Commands:
               prompt. --json is machine-readable and never blocks on
               login. No directory: print the setup guide.
   convert-automation
-              Export a Cursor Automation into an agentkit project. <url> is
+              Export a Cursor Automation into an agentsdk project. <url> is
               the dashboard URL (…/automations/<uuid> or
               …/custom-agents/<uuid>) or a bare uuid. Fetches the definition
               with your Cursor credentials, writes the converted files into
@@ -223,7 +223,9 @@ Commands:
   whoami      Show which Cursor account powers this host (and why).
   update      Upgrade this install to the latest published version (detects
               global npm/pnpm/yarn/bun installs and project dependencies).
-  version     Print the installed ${CLI} version and exit (also --version / -V).
+  version     Print the ${PACKAGE_NAME} version this CLI will use and exit
+              (also --version / -V). Text is the version number; --json
+              prints { name, version, cli }.
   deploy      Deploy onto Cursor's managed agent-serve hosting, then wait for
               the engine to come up. --repo/--ref/--path stay available;
               inside an agent git checkout they are inferred when omitted
@@ -257,7 +259,7 @@ Agent loop:
   ${CLI} dev .
 
 Options:
-  --version, -V      Print the installed version and exit.
+  --version, -V      Print the version number and exit.
   --dir             Project root (defaults to the current directory).
   --port             Port to listen on (default 3000). When the default is
                      taken, serve tries the next free port and prints a notice.
@@ -365,7 +367,7 @@ Options:
   --skip-report      eval: ignore reporters from evals.config.ts / eval files.
   --no-stream        run/eval: silence live progress on stderr (JSON still prints).
   --json             JSON output (init/convert-automation/install-skills/
-                     info/chat/eval/logs/
+                     info/chat/eval/logs/version/
                      sessions/session/github; run defaults to JSON). logs:
                      NDJSON progress/log events. session: trajectory JSON
                      (not raw events).
@@ -438,7 +440,7 @@ function main(argv) {
             return command === undefined ? 1 : 0;
         }
         if (command === "version" || command === "--version" || command === "-V") {
-            yield writeStdout(`${CLI} ${packageVersion()}\n`);
+            yield writeStdout(formatCliVersion({ json: restIn.includes("--json") }));
             return 0;
         }
         // `session --events` means "dump raw events" (boolean). Rewrite so it does
@@ -535,9 +537,14 @@ function main(argv) {
                 "no-artifacts": { type: "boolean", default: false },
                 "skip-report": { type: "boolean", default: false },
                 "max-concurrency": { type: "string" },
+                version: { type: "boolean", short: "V", default: false },
             },
         });
         const dir = (_j = values.dir) !== null && _j !== void 0 ? _j : ".";
+        if (values.version === true) {
+            yield writeStdout(formatCliVersion({ json: values.json === true }));
+            return 0;
+        }
         // Best-effort, cached, and silent on failure. `update` does its own fresh
         // lookup, --json runs stay quiet for machine consumers, and `mcp` skips it
         // so MCP client spawns stay fast (stdout there is the protocol wire).
@@ -1090,8 +1097,14 @@ function main(argv) {
                     loadLocalEnv();
                     // Model turns need a Cursor credential. Prompt login before listen
                     // so the first playground turn does not fail with a late auth error.
+                    // `--allow-anonymous` is the hosted trust boundary (alias token /
+                    // freeze bake): skip the login gate so health can bind without a
+                    // key. v1 hosted injects CURSOR_API_KEY at exec; freeze bind drops
+                    // CURSOR_API_KEY / CURSOR_API_KEY_FILE onto the listening process.
+                    // Self-hosted omit the flag and still fail-fast unsigned on a TTY-less host.
                     const loginExit = yield ensureCursorLogin({
                         apiKey: values["api-key"],
+                        allowAnonymous: values["allow-anonymous"] === true,
                     });
                     if (loginExit !== 0) {
                         return { kind: "login-failed", exitCode: loginExit };

package/dist/channels/slack/channel-watch.d.ts

@@ -2,7 +2,7 @@
  * Opt-in channel watch: dispatch on posts in allowlisted channels.
  *
  * Filtering rules (the anti-slop guarantees):
- * - Only explicitly allowlisted channels are watched — no wildcard.
+ * - Only configured channels are watched; `"*"` opts into every channel.
  * - Top-level posts only by default; thread replies never dispatch unless
  *   `posts: "all"` is configured.
  * - Posts that @mention the bot are skipped here (the `app_mention` path

package/dist/channels/slack/channel-watch.js

@@ -2,7 +2,7 @@
  * Opt-in channel watch: dispatch on posts in allowlisted channels.
  *
  * Filtering rules (the anti-slop guarantees):
- * - Only explicitly allowlisted channels are watched — no wildcard.
+ * - Only configured channels are watched; `"*"` opts into every channel.
  * - Top-level posts only by default; thread replies never dispatch unless
  *   `posts: "all"` is configured.
  * - Posts that @mention the bot are skipped here (the `app_mention` path

package/dist/channels/slack/slack-channel.js

@@ -149,7 +149,7 @@ export function slackChannel(authored = {}) {
     if (channelPosts !== undefined) {
         const entries = channelPosts.allow.filter((entry) => entry.trim() !== "");
         if (entries.length === 0) {
-            throw new Error("slackChannel engagement.channelPosts.allow must list at least one channel (id or #name); there is no wildcard watch.");
+            throw new Error('slackChannel engagement.channelPosts.allow must list at least one channel (id, #name, or "*").');
         }
     }
     const botMentions = engagement.botMentions;