@cursor/july 0.1.34 → 0.1.36

package/docs/reference/cli.md

@@ -26,6 +26,7 @@ also provide `agent-sdk slack help` and `agent-sdk github help`.
 | [`logs`](#logs)                                         | Follow local or hosted logs                                    |
 | [`sessions`](#sessions)                                 | List sessions on a running agent                               |
 | [`session`](#session)                                   | Inspect one session                                            |
+| [`cost`](#cost)                                         | Report per-session token usage and estimated cost              |
 | [`playground`](#playground)                             | Open the local or hosted playground                            |
 | [`docs`](#docs)                                         | Serve the shipped documentation site locally                   |
 | [`run`](#run)                                           | Run one or more turns locally, remotely, or on a hosted agent  |
@@ -33,9 +34,12 @@ also provide `agent-sdk slack help` and `agent-sdk github help`.
 | [`eval`](#eval)                                         | Run filesystem evals                                           |
 | [`trajectory`](#trajectory)                             | Summarize a saved `events.ndjson` file                         |
 | [`init`](#init)                                         | Scaffold a project, or print the setup guide                   |
+| [`convert-automation`](#convert-automation)             | Export a Cursor Automation into an agent project               |
+| [`install-skills`](#install-skills)                     | Install the coding-agent skills without running `init`         |
 | [`info`](#info)                                         | Print the discovered agent surface                             |
 | [`validate`](#validate)                                 | Check a project and fail on errors                             |
-| [`login` / `logout` / `whoami`](#login--logout--whoami) | Manage the host's Cursor credential                            |
+| [`login` / `logout` / `whoami`](#login-logout-whoami)   | Manage the host's Cursor credential                            |
+| `version`                                               | Print the installed version and exit (also `--version` / `-V`) |
 | [`update`](#update)                                     | Upgrade the installed CLI                                      |
 | [`deploy`](#deploy)                                     | Deploy one or more agents to Cursor managed hosting            |
 | [`deployments`](#deployments)                           | List hosted deployments                                        |
@@ -44,6 +48,7 @@ also provide `agent-sdk slack help` and `agent-sdk github help`.
 | [`rotate-token`](#rotate-token)                         | Replace a deployment's alias token                             |
 | [`rotate-pod-credential`](#rotate-pod-credential)       | Replace a deployment's pod credential                          |
 | [`secrets`](#secrets)                                   | Manage deployment secrets                                      |
+| [`mcp`](#mcp)                                           | Proxy the agent's MCP endpoint over stdio; `mcp install` writes `~/.cursor/mcp.json` |
 | [`mcp oauth`](#mcp-oauth)                               | Authorize host MCP OAuth; optional `--store` to deployment secrets |
 | [`slack ...`](#slack)                                   | Provision, set up, and check Slack channels                    |
 | [`github ...`](#github)                                 | Forward, replay, and inspect GitHub webhook channels           |
@@ -55,13 +60,14 @@ Request-sending commands support three target types.
 | Target | How to select it | Commands |
 | --- | --- | --- |
 | Ephemeral local server | Omit `--url` and `--prod` | `run`, `call`, `eval` |
-| Running server | Pass `--url <baseUrl>`, unless the command uses the localhost default described next | `chat`, `resume`, `logs`, `sessions`, `session`, `playground`, `run`, `call`, `eval` |
-| Cursor managed hosting | Pass `--prod` | `chat`, `resume`, `logs`, `sessions`, `session`, `playground`, `run`, `call`, `eval` |
+| Running server | Pass `--url <baseUrl>`, unless the command uses the localhost default described next | `chat`, `resume`, `logs`, `sessions`, `session`, `cost`, `playground`, `run`, `call`, `eval`, `mcp` |
+| Cursor managed hosting | Pass `--prod` | `chat`, `resume`, `logs`, `sessions`, `session`, `cost`, `playground`, `run`, `call`, `eval`, `mcp` |
 
-`chat`, `logs`, `sessions`, `session`, and `playground` default to
+`chat`, `logs`, `sessions`, `session`, `cost`, and `playground` default to
 `http://127.0.0.1:3000`. A `--url` must include the agent slug for a
 multi-agent server, such as `http://127.0.0.1:3000/pr-approver`.
-`--slug` doesn't change an explicit URL.
+`--slug` doesn't change an explicit URL. `mcp` has no default target;
+pass `--url` or `--prod`.
 
 With `--prod`, `--slug` selects the deployment and `--team` selects the
 Cursor team. The slug defaults to the `--dir` basename. The team
@@ -89,7 +95,9 @@ agent-sdk serve [--dir <path>] [--port 3000] [--host 127.0.0.1] [--dev]
                   [--state-root <path>] [--bearer-token <secret> | --allow-anonymous]
                   [--allow-anonymous-cursor-github]
                   [--allow-anonymous-cursor-account-mcp]
-                  [--public-url <url>] [--no-schedules] [--no-playground]
+                  [--public-url <url>] [--cloud-tools-url <url>]
+                  [--cursor-github-proxy] [--no-control-plane]
+                  [--no-schedules] [--no-playground]
                   [--no-docs] [--cursor-events --repo owner/name]...
 ```
 
@@ -114,6 +122,9 @@ Unless `--state-root` is set, each mount uses
 | `--allow-anonymous-cursor-github` | Allow anonymous callers to drive sessions holding a Cursor account's repo-scoped GitHub credential. Use only behind an authenticating proxy. |
 | `--allow-anonymous-cursor-account-mcp` | Allow anonymous callers to drive Cursor account MCP connectors (`defineConnection({ cursorAccount: true })`). Use only behind an authenticating proxy (hosted alias token counts). |
 | `--public-url` | Set the externally reachable host URL. Cloud-runtime peer connections need it to call back into this server. |
+| `--cloud-tools-url` | Authenticated HTTP MCP URL for this deployment's direct server-tool endpoint. Hosted deployments configure it automatically. |
+| `--cursor-github-proxy` | Route `githubChannel({ cursorAccount })` API calls through the Cursor backend's GitHub forwarder instead of minting raw installation tokens into this process. `AGENT_SERVE_GITHUB_PROXY_URL` overrides the base URL. |
+| `--no-control-plane` | Skip the bundled schedule and reminder clocks. Cursor hosting passes this so the platform fires timed work through internal routes instead. |
 | `--no-schedules` | Disable the cron runner outside dev mode. |
 | `--no-playground` | Skip the web playground and its build or HMR process. |
 | `--no-docs` | Skip the documentation site at `/docs` and its build. |
@@ -220,15 +231,35 @@ and update time. `--json` prints full session summaries in
 ```bash
 agent-sdk session <sessionId> [--url <baseUrl> | --prod]
                  [--slug <slug>] [--team <id>]
-                 [--json | --text | --events]
+                 [--json | --text | --events] [--out <file.ndjson>]
 ```
 
 By default, `session` prints a compact trajectory. `--text` selects the
 same format. `--json` prints the trajectory object. `--events` prints
 `{ sessionId, events }` with the raw event list. You can't combine
-`--events` and `--json`. Use
+`--events` and `--json`. `--out <file.ndjson>` writes the raw NDJSON
+trace to a file instead of printing. The file uses the same format as
+`run --events` and the playground download. Use
 [`resume`](#resume) to continue the conversation.
 
+## cost
+
+`cost` reports token usage and estimated cost.
+
+```bash
+agent-sdk cost [sessionId] [--url <baseUrl> | --prod]
+              [--slug <slug>] [--team <id>] [--json]
+```
+
+With a session ID, `cost` prints per-turn token usage and estimated
+cost for that session. Without one, it prints one row per session on
+the target plus a total. Costs are the engine's recorded estimates from
+`turn.completed` events; turns persisted before cost tracking count as
+unpriced. `--json` prints the underlying report, or `{ sessions }` when
+aggregating. Like `session`, the command supports `--dir`,
+`--bearer-token`, and the `--url`/`--prod` targets, and defaults to the
+local server.
+
 ## playground
 
 `playground` opens an agent's web playground.
@@ -349,13 +380,27 @@ Omit selectors to run all cases. Repeated `--tag` flags use OR matching.
 
 An eval run requires `evals/evals.config.{ts,js}` with `maxConcurrency`
 between 1 and 200. Timeout priority is the case's `timeoutMs`, the CLI's
-`--timeout-ms`, the config's `timeoutMs`, then 180 seconds. Use
-`--no-stream` to hide live progress or `--verbose` to include `t.log`
-lines and reply snippets.
+`--timeout-ms`, the config's `timeoutMs`, then 180 seconds.
 
-`--list --json` prints an array of discovered cases. A run with `--json`
-prints `{ ok, passed, failed, results }`. Failed cases exit `1`; no
-matching cases exit `2`. See [Evals](../evals.md).
+| Flag | Meaning |
+| --- | --- |
+| `--list` | Print discovered cases without running. `--list --json` prints them as an array. |
+| `--tag <tag>` | Run cases with this tag. Repeated flags use OR matching. |
+| `--json` | Print `{ ok, passed, failed, results }`. |
+| `--verbose` | Stream `t.log` lines and reply snippets. |
+| `--no-stream` | Hide live progress on stderr. |
+| `--strict` | Exit `1` when a scored case misses a soft threshold. |
+| `--max-concurrency <n>` | Override `maxConcurrency` from `evals.config.ts`. |
+| `--junit <path>` | Write JUnit XML for CI annotations. |
+| `--artifacts <dir>` | Write run artifacts here. The default is a timestamped directory under `<dir>/.agent-serve/evals/`. |
+| `--no-artifacts` | Skip run artifacts. |
+| `--skip-report` | Ignore reporters from `evals.config.ts` and eval files. |
+| `--out <path>` | Also write the full results JSON to this path (also for `eval status <evalId>`). |
+| `--no-wait` | Return with the Eval ID as soon as a `--prod` or `--url` batch is accepted. |
+| `--timeout-ms <n>` | Per-case timeout override. |
+
+Failed cases exit `1`; no matching cases exit `2`. See
+[Evals](../evals.md).
 
 ## trajectory
 
@@ -397,6 +442,44 @@ login or skill installation. It prints
 `{ ok, directory, created, skipped, installed, installError, next }`
 (with `login` in `next` when unsigned).
 
+## convert-automation
+
+`convert-automation` exports a Cursor Automation into an agent project.
+
+```bash
+agent-sdk convert-automation <url> [--dir <path>] [--json]
+```
+
+`<url>` is the dashboard URL (`…/automations/<uuid>` or
+`…/custom-agents/<uuid>`) or a bare UUID. The command fetches the
+automation's definition with your Cursor credentials, writes the
+converted files into `--dir` (default `./<automation-name>`), fills in
+the `init` scaffold around them, and installs npm dependencies.
+Existing files are kept.
+
+MCP servers convert to Cursor-account connections resolved at runtime.
+No URLs or credentials land in the project; manage authorization in the
+Cursor dashboard under MCP. Review the generated project, then run
+`validate` and `dev`. Warnings never fail the command; it exits
+non-zero only for bad arguments, auth or fetch failures, and filesystem
+write failures.
+
+## install-skills
+
+`install-skills` installs the package's coding-agent skills into
+`~/.cursor/skills/agentkit/`.
+
+```bash
+agent-sdk install-skills [--print] [--json]
+```
+
+Running the command is the confirmation: it never prompts, and it
+overwrites the installed skills with the version bundled in the
+package. `init` offers the same install once, interactively. `--print`
+previews the skills, the removals, and the install path without writing
+anything. `--json` prints
+`{ ok, dryRun, directory, firstInstall, skills, removed }`.
+
 ## info
 
 `info` prints the discovered agent surface.
@@ -576,18 +659,56 @@ engine pod.
 agent-sdk rotate-pod-credential <slug> [--team <id>] [--json]
 ```
 
-The command returns only the masked key and revokes the old credential
-immediately. Redeploy at once to inject the replacement; the current
-pod can't authenticate to Cursor in between.
+The command prints only the masked key (`--json` prints
+`{ podCredentialMaskedKey }`). The running pod keeps the old credential
+until the next deploy, so nothing breaks in between. Run
+`agent-sdk deploy --slug <slug>` to inject the replacement and retire
+the old credential.
+
+## mcp
+
+`mcp` proxies an agent's MCP endpoint over stdio for MCP clients that
+spawn local servers, such as Cursor.
+
+```bash
+agent-sdk mcp --prod [--slug <slug>] [--team <id>]
+agent-sdk mcp --url <baseUrl> [--bearer-token <token>]
+agent-sdk mcp install [--prod | --url <baseUrl>] [--name <serverName>]
+                     [--print] [--json] [--remote]
+```
+
+The bare command reads newline-delimited JSON-RPC on stdin and forwards
+one POST per message to `<target>/v1/mcp`. It requires `--prod` or
+`--url`. With `--prod`, it resolves the hosted deployment through the
+signed-in Cursor account and re-mints short-lived engine credentials as
+they expire, so no durable secret lands in a config file. stdout is
+reserved for the MCP wire; logging goes to stderr.
+
+`mcp install` writes the matching entry into `~/.cursor/mcp.json` so
+the agent shows up as an MCP server in Cursor. `--name` overrides the
+server name (the default is the slug, or a name derived from `--url`).
+`--print` prints the entry instead of writing the file, and `--json`
+prints a machine-readable result. `--remote` (with `--prod`) writes a
+remote HTTP entry pointing at the stable Cursor MCP gateway instead of
+the local stdio proxy, for MCP hosts that can't spawn stdio servers.
+The remote entry carries your API key in plain text, so treat the file
+as a credential.
 
 ## mcp oauth
 
-`mcp oauth` authorizes a `defineConnection({ url, oauth: true })`
-connection with a browser PKCE flow. Tokens are written to
+`mcp oauth` authorizes a `defineConnection({ url, oauth: true })` or
+`defineConnection({ cursorAccount: true })` connection.
+
+URL connections run a browser PKCE flow. Tokens are written to
 `mcp-auth.json` under the agent-serve config dir (default
 `~/.config/agent-serve`). Pass `--store` to upsert matching
 `MCP_OAUTH_<CONNECTION>_*` secrets on the hosted deployment.
 
+Cursor-account connections authorize the hosted deployment's service
+account through the Cursor backend's connector consent flow. Those
+tokens live on the Cursor backend, so `--store` isn't needed; the
+command prints a note when you pass it anyway.
+
 ```bash
 agent-sdk mcp oauth <connection> [--dir .] [--store] [--slug <slug>] [--team <id>]
 ```
@@ -651,7 +772,7 @@ agent-sdk slack init [--dir <path>] [--name <name>]
                     [--prefix <prefix> | --no-prefix] [--channel-posts]
 agent-sdk slack manifest [--dir <path>] [--name <name>]
                         [--env dev|prod|both] [--channel-posts] [--print]
-agent-sdk slack doctor [--prefix <prefix>] [--json]
+agent-sdk slack doctor [--dir <path>] [--prefix <prefix> | --no-prefix] [--json]
 ```
 
 `slack setup` prints a guided checklist and doesn't change files.

package/docs/reference/hooks.md

@@ -31,10 +31,17 @@ export default defineHook({
 ```
 
 Keys are event types (the full list is in the
-[event vocabulary](./sessions.md#the-event-vocabulary)), or `"*"` for
-everything. Handlers receive the event with its envelope (`index`,
-`sessionId`, `turnId?`, `at`) and a context carrying read-only
-`ctx.session` info.
+[event vocabulary](./sessions.md#which-events-can-i-stream)), or `"*"`
+for everything. Handlers receive the event with its envelope (`index`,
+`sessionId`, `turnId?`, `at`) and a `HookContext`:
+
+| Member | What it is |
+| --- | --- |
+| `ctx.session` | Read-only session info: id, channel, mode, auth |
+| `ctx.agent` | `{ name }` of the agent the event belongs to |
+| `ctx.channel` | `{ id, continuationToken }` for the owning channel |
+| `ctx.stateRoot` | The agent's durable state root; hooks maintaining derived state write here |
+| `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade: `tag` auto-fills the session |
 
 ## Hooks, channel events, evals, or A/B?
 

package/docs/reference/http-api.md

@@ -83,7 +83,7 @@ default is `0`: omitting the parameter replays the entire recorded
 stream before following. Pass the last index you've seen plus one to
 resume without duplicates. The stream is durable and reconnectable. For
 the vocabulary, see
-[Sessions](./sessions.md#the-event-vocabulary).
+[Sessions](./sessions.md#which-events-can-i-stream).
 
 `GET /v1/session/:sessionId/events` returns the same content as a
 one-shot dump with no live follow.
@@ -96,6 +96,14 @@ calling principal. Under `serve --dev` on loopback it includes all
 sessions, which is how webhook and schedule sessions show up in the
 playground.
 
+## Session cost
+
+`GET /v1/session/:sessionId/cost` returns the session's cost report:
+per-turn token usage and the engine's estimated cost, folded from
+`turn.completed` events. It runs the same owner check as the other
+session routes and returns `404` for an unknown session. The
+[`agent-sdk cost`](./cli.md#cost) command reports the same data.
+
 ## Approvals
 
 Two routes list and resolve parked tool calls.
@@ -132,12 +140,27 @@ Five read-only routes describe the running agent.
 
 | Route                  | What it does                                                                                                                                                                             |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GET /v1/info`         | The manifest snapshot: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, A/B experiments, diagnostics; the same shape as `agent-sdk info --json` |
+| `GET /v1/info`         | The manifest snapshot: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, A/B experiments, diagnostics. Always the bare project-info object; `agent-sdk info --json` wraps the same data per slug in `{ agents: [...] }` |
 | `GET /v1/health`       | Per-agent liveness, no auth                                                                                                                                                              |
 | `GET /v1/meta`         | SPA bootstrap: agent name, dev flag, base path (no auth)                                                                                                                                 |
 | `GET /v1/logs?after=N` | Recent server log lines from the ring buffer, with a polling cursor                                                                                                                      |
 | `GET /v1/abs`          | [Live A/B metrics](../ab.md): per-session assignments and aggregate arm totals folded from durable event streams (`config` reports `maxPlaygroundSessions` / `durableSamples` / `durableSnapshots` from `agent/ab.config.ts`) |
 
+## Artifacts
+
+Two routes read durable artifacts tagged by `ctx.artifacts` or
+`tag_artifact`. See [Artifacts](./artifacts.md).
+
+| Route                            | What it does                                                                                          |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `GET /v1/artifacts`              | List artifacts as `{ artifacts }`, newest-updated first. Filter with `?kind=`, `?sessionId=`, and `?limit=` (a positive integer) |
+| `GET /v1/artifacts/:id/content`  | Download one artifact's file or blob payload. Served as an attachment, never rendered inline; `404` when the artifact is unknown or carries no content |
+
+Session ownership applies the same way as `GET /v1/sessions`: under
+`serve --dev` on loopback (or `--allow-anonymous`) the list spans all
+principals, while bearer or custom channel auth keeps strict
+per-principal isolation.
+
 ## Custom channel routes
 
 Authored routes mount under `/v1/channels/<id>` with the methods, paths,
@@ -157,6 +180,17 @@ server-tool passthrough, present when the agent has server tools). The
 route runs the same auth chain as the session API. See
 [Agent-to-agent](../guides/agent-to-agent.md).
 
+`/v1/mcp/tools` is a second stateless MCP endpoint exposing only the
+agent's deterministic server tools. Hosted cloud turns call back into
+it through the URL configured by `serve --cloud-tools-url`. Unlike
+`/v1/mcp`, it runs the CLI-level auth chain (loopback, bearer, or
+anonymous), not any authored channel auth.
+
+`POST /v1/cursor-account/:connection/mcp` is the bridge for
+`defineConnection({ cursorAccount: true })` connections. The runtime
+calls it with a per-boot bearer secret; it never joins the public auth
+chain, and an unknown connection name returns `404`.
+
 ## Playground eval routes
 
 Always registered (including production / non-`--dev` serves). The playground
@@ -174,8 +208,9 @@ Eval runs are asynchronous. Poll the run route for case progress and
 the final `completed` or `failed` status. Batch errors appear on the
 snapshot returned by the poll. Entries within `filterIds` and `tags`
 use OR semantics. When both fields are present, a case must match one
-entry from each field. Without `persistRuns` in `evals.config.ts`,
-listed runs are process-memory only (capped by `maxPlaygroundRuns`).
+entry from each field. Without a storage `evals` table in
+`agent/storage.ts` (see [Storage](../storage.md)), listed runs are
+process-memory only (capped by `maxPlaygroundRuns`).
 
 ## Dev-mode routes
 
@@ -190,6 +225,17 @@ These routes exist only under `serve --dev`.
 Schedules and reminders never fire automatically in dev mode. These
 routes are the only way they run, which keeps iteration deterministic.
 
+## Platform timer routes
+
+`POST /v1/internal/schedules/:scheduleId/fire` and
+`POST /v1/internal/reminders/:reminderId/fire` exist only under
+`serve --no-control-plane`, where the host runs no schedule or reminder
+clocks of its own. Cursor hosting starts engines this way and fires
+timed work through them. They admit only requests carrying the
+platform's `x-agent-serve-timed-work` marker, which the alias proxy
+strips from external traffic, so webhook and playground callers can
+never reach them.
+
 ## Playground assets
 
 `GET /playground` and `GET /playground/assets/:file` serve the static

package/docs/reference/project-layout.md

@@ -84,8 +84,14 @@ Each path maps to a capability and a reference page.
 | `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` and `github.ts` use the platform packs | [Channels](./channels.md) |
 | `agent/hooks/*.ts` | Observe-only event subscribers, never fatal | [Hooks](./hooks.md) |
 | `agent/ab.ts`, `agent/ab/*.ts` | `defineAB` experiments with sticky variants and live metrics | [Live A/B metrics](../ab.md) |
+| `agent/ab.config.ts` | `defineABConfig` shared A/B settings | [Live A/B metrics](../ab.md) |
+| `agent/storage.ts` | `defineStorage` backend for the durable `host.kv` / `host.files` APIs | [Storage](../storage.md) |
+| `agent/artifacts.ts` | `defineArtifacts` kinds, the `tag_artifact` opt-in, and retention | [Artifacts](./artifacts.md) |
 | `agent/schedules/*` | Cron-driven runs (UTC, 5-field; never auto-fire under `--dev`) | [Schedules](./schedules.md) |
+| `agent/sandbox/workspace/**` | Seed files copied into each local session workspace | [Sessions](./sessions.md#what-goes-into-a-local-session-workspace) |
+| `agent/playground/` | Custom playground tool chips for the Vite dev playground | [Playground](./playground.md) |
 | `agent/lib/` | Import-only shared code, never discovered | None |
+| `evals/evals.config.ts` | Shared eval settings (e.g. `maxConcurrency`); required when evals exist | [Evals](../evals.md) |
 | `evals/**/*.eval.ts` | Filesystem evals; case id = path under `evals/` | [Evals](../evals.md) |
 
 `agent/lib/` is the only place for shared code. Everything else under

package/docs/reference/sessions.md

@@ -81,13 +81,14 @@ within one session. The `at` field is an ISO-8601 timestamp.
 | Session | `session.started`, [`ab.assigned`](../ab.md#assign-sticky-variants), `session.waiting`, `session.completed`, `session.failed` | Session creation, A/B enrollment, readiness, and task completion |
 | Agent | `agent.bound` | Cursor SDK agent ID and cloud conversation URL |
 | Input | `message.received` | A user message was accepted |
-| Turn | `turn.started`, `turn.completed`, `turn.failed` | Turn status, final result, and token usage |
+| Turn | `turn.queued`, `turn.started`, `turn.completed`, `turn.failed` | Queue position under a [`maxRunningTurns` cap](./agent-config.md#concurrency), then turn status, final result, and token usage |
 | Steps | `step.started`, `step.completed` | Model step boundaries and duration |
 | Reasoning | `reasoning.appended`, `reasoning.completed` | Streamed reasoning blocks |
 | Reply | `message.appended`, `message.completed` | Text deltas and finalized assistant messages |
 | Tools | `actions.requested`, `action.result` | Tool names, validated arguments, outputs, and errors |
 | Approvals | `action.approval_requested`, `action.approval_resolved` | A parked tool call and the human decision |
 | Subagents | `subagent.called`, `subagent.completed` | Delegated work |
+| Artifacts | `artifact.tagged` | A durable [artifact](./artifacts.md) was tagged for this session, by host code or `tag_artifact` |
 
 Pair `actions.requested` with `action.result` to reconstruct the tool
 trajectory. Read `turn.completed.data.usage` for input, output, and
@@ -117,7 +118,7 @@ The Agent SDK creates a workspace before the first local turn:
 | ---------------------------------- | ----------------------------------------------------------------------- |
 | `instructions.*`                   | `AGENTS.md`                                                             |
 | `skills/*`                         | `.cursor/skills/<name>/SKILL.md`                                        |
-| agent tools (`execution: "agent"`) | scripts under `.agent-sdk/tools/`, with a catalog in `AGENTS.md` |
+| agent tools (`execution: "agent"`) | scripts under `.agent-serve/tools/`, with a catalog in `AGENTS.md` |
 | `sandbox/workspace/**`             | copied in as seed files                                                 |
 | per-send `workspaceFiles`          | written before the turn                                                 |
 
@@ -135,7 +136,7 @@ inheritance rules.
 Local state uses one directory tree:
 
 ```text
-<project>/.agent-sdk/            # or <stateRoot>/<slug>/ under serve
+<project>/.agent-serve/           # or <stateRoot>/<slug>/ under serve
   sessions/<id>/session.json       # metadata: channel, mode, principal, tokens
   sessions/<id>/events.ndjson      # the durable stream
   sessions/<id>/workspace/         # the harness cwd
@@ -158,7 +159,7 @@ repositories whose parent rules shouldn't reach the agent. See
 Use `trajectory` with a trace or session event file:
 
 ```bash
-agent-sdk trajectory --events .agent-sdk/traces/<sessionId>.ndjson
+agent-sdk trajectory --events .agent-serve/traces/<sessionId>.ndjson
 agent-sdk trajectory --events <stateRoot>/<slug>/sessions/<id>/events.ndjson
 ```
 

package/docs/reference/subagents.md

@@ -38,9 +38,11 @@ when deciding whether to delegate, so write it as a routing rule
 inherit the parent's model, or set it to run the specialist on a
 different one.
 
-Subagents inherit the parent's execution surface. Per-subagent `tools/`,
-`skills/`, and `mcp-connections/` directories are reported as warnings and
-ignored. Nested subagents aren't supported.
+Subagents inherit the parent's execution surface. Every per-subagent
+capability directory is reported as a warning and ignored: `tools/`,
+`skills/`, `mcp-connections/` (and the legacy `connections/` alias),
+`channels/`, `schedules/`, `hooks/`, `sandbox/`, and nested
+`subagents/`.
 
 Delegation needs both halves: the description makes it possible, and the
 parent's [instructions](./instructions.md) make it happen. "When a

package/docs/reference/tools.md

@@ -15,8 +15,12 @@ also be called directly, with no model turn.
 ## Define a server tool
 
 By default, `execute` runs in-process on the serving host with full
-access to `process.env` and your `agent/lib/` code. Server tools require
-the `local` runtime.
+access to `process.env` and your `agent/lib/` code. Local turns call
+server tools as SDK custom tools. Cloud turns reach them over
+authenticated HTTP MCP back to the serve host when `--public-url` or
+`--cloud-tools-url` is set; without either, the server warns at startup
+and cloud turns omit them (see
+[Cloud runtime](../guides/cloud-runtime.md#what-changes-on-cloud)).
 
 ```ts
 // agent/tools/inspect_pr.ts
@@ -69,8 +73,19 @@ export default defineTool({
 | `ctx.toolCallId` | The call id, matching the `actions.requested` / `action.result` stream events |
 | `ctx.session` | Read-only session info: id, channel, mode, auth |
 | `ctx.workspaceDir` | The session's workspace directory |
-| `ctx.host.mcp` | Authored MCP connections: `names()`, `listTools(name)`, `callTool(name, tool, args)` |
-| `ctx.host.github` / `ctx.host.slack` | Shared host clients when those packs are configured |
+| `ctx.stateRoot` | The agent's durable state root, shared across every session |
+| `ctx.host` | Shared host services (see below) |
+| `ctx.send(channelId, message, options?)` | Start or resume a session on any channel: the cross-channel handoff primitive, e.g. a chat tool opening a `drive` cloud session for a PR. `auth` defaults to this call's session principal |
+| `ctx.getSession(channelId, sessionId)` | Look up a session on a channel, e.g. refresh `sdkAgentId` after a turn |
+| `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade: `tag` auto-fills the session |
+
+`ctx.host` carries the shared host services: `host.mcp` (authored MCP
+connections: `names()`, `listTools(name)`, `callTool(name, tool, args)`),
+`host.github` and `host.slack` (shared platform clients), `host.kv` and
+`host.files` (durable [storage](../storage.md)), `host.reminders`
+(per-session wakes, when attached), `host.evals` (playground eval
+batches, when attached), and `host.slackNudges` (Slack ask-dedupe
+helpers).
 
 ### Return values
 
@@ -89,8 +104,9 @@ Throwing inside `execute` reports an error result to the model
 Set `execution: "agent"` and the tool materializes as a shell script
 that runs where the Cursor agent runs: the local harness workspace or
 the cloud VM. The script receives JSON arguments on stdin and prints its
-result on stdout. This is the only tool flavor available to
-`runtime: "cloud"` agents.
+result on stdout. Use this flavor when the tool must run next to the
+checkout the agent works in; on cloud, server tools stay available too
+through the host's HTTP MCP endpoint.
 
 ```ts
 import { defineTool } from "@cursor/july/tools";
@@ -108,7 +124,7 @@ printf '%s\\n' "$message"
 });
 ```
 
-On the local runtime, scripts land under `.agent-sdk/tools/` in the
+On the local runtime, scripts land under `.agent-serve/tools/` in the
 session workspace with a catalog in `AGENTS.md`. On cloud, the catalog
 and script bodies travel on the first prompt.
 

package/docs/scaffolding-agents.md

@@ -12,8 +12,17 @@ decision.
 
 The bundled
 [`create-agent` skill](../skills/create-agent/SKILL.md) turns your goal
-into a small working project. Have Cursor read that file and follow it
-(monorepo path: `packages/agent-serve/skills/create-agent/SKILL.md`).
+into a small working project. Have Cursor read that file and follow it.
+
+Where to find the file depends on how you got the package:
+
+- Reading these docs on a hosted site? Run `agent-sdk install-skills`
+  to copy every package skill into `~/.cursor/skills/agentkit/`, where
+  Cursor discovers them by name.
+- Installed `@cursor/july` as a dependency? The skill ships inside the
+  package at `node_modules/@cursor/july/skills/create-agent/SKILL.md`.
+- Working in the monorepo? It's at
+  `packages/agent-serve/skills/create-agent/SKILL.md`.
 
 Cursor will:
 

package/docs/storage.md

@@ -41,20 +41,45 @@ export default defineStorage({
 > using `@anysphere/agent-serve`, swap the import. See
 > [Run the CLI](./README.md#run-the-cli) for the full rename table.
 
-## Which methods to provide
+## Which fields to provide
 
-| Method | Required | Role |
+| Field | Required | Role |
 | --- | --- | --- |
 | `put` | Yes | Write or update a value |
 | `get` | For restore | Look up one key |
 | `list` | For restore | Return entries under a prefix, in key order |
 | `delete` | For cleanup | Remove a key |
+| `name` | No | Label surfaced on `GET /v1/info` diagnostics |
+| `policy` | No | Timing knobs; see [Policy](#policy) |
+| `evals` | No | Dedicated eval-runs table; see [Eval and A/B tables](#eval-and-ab-tables) |
+| `abs` | No | Dedicated A/B metrics table; see [Eval and A/B tables](#eval-and-ab-tables) |
 
 A throwing `put` is logged and dropped. It never fails a turn. When
 resolving a missing continuation token, a throwing `get` fails the
 follow-up so a store outage does not open a new session. Return
 `undefined` only for a real miss.
 
+## Eval and A/B tables
+
+Two dedicated tables carry structured rows instead of opaque KV values.
+Both are optional and independent of `put` / `get` / `list`.
+
+`evals` keeps playground eval batches across restarts. Provide `put`,
+`delete`, and `list` over run snapshots keyed by `runId`. The Agent SDK
+upserts a snapshot as a batch starts, progresses, and finishes, prunes
+runs past the playground history window, and lists everything back at
+serve start. Without this table, eval history lives in process memory
+and a restart clears it. See [Evals](./evals.md#configure-eval-runs).
+
+`abs` exports live A/B metrics. Provide `putSample` to append one
+cumulative metric sample per enrolled experiment on each completed or
+failed turn. Optional `putSnapshot` and `getSnapshot` store and serve
+back the latest aggregate snapshot, so a replacement host with no local
+sessions can still serve the A/Bs surface. Without this table, samples
+only go where each experiment's `onSample` sends them; session event
+logs remain the assignment source of truth. See
+[Live A/B metrics](./ab.md).
+
 ## Policy
 
 Two knobs change behavior:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {

package/src/channels/github/github-channel.ts

@@ -388,7 +388,7 @@ function verifyWebhookSha256Signature(args: {
  * hooks:
  *
  * ```ts
- * import { defaultGitHubAuth, githubChannel } from "@anysphere/agent-serve/channels/github";
+ * import { defaultGitHubAuth, githubChannel } from "@cursor/july/channels/github";
  *
  * export default githubChannel({
  *   botName: "my-agent",

package/src/channels/github/index.ts

@@ -2,7 +2,7 @@
  * GitHub webhook channel pack for agent-serve (Eve-compatible dispatch).
  *
  * ```ts
- * import { defaultGitHubAuth, githubChannel } from "@anysphere/agent-serve/channels/github";
+ * import { defaultGitHubAuth, githubChannel } from "@cursor/july/channels/github";
  *
  * export default githubChannel({
  *   botName: "my-agent",

package/src/channels/slack/index.ts

@@ -2,7 +2,7 @@
  * Slack platform channel pack for agent-serve.
  *
  * ```ts
- * import { slackChannel } from "@anysphere/agent-serve/channels/slack";
+ * import { slackChannel } from "@cursor/july/channels/slack";
  *
  * // Single agent: SLACK_BOT_TOKEN + SLACK_APP_TOKEN
  * export default slackChannel();

package/src/channels/slack/init.ts

@@ -4,6 +4,7 @@
 
 import { mkdir, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
+import { PACKAGE_NAME } from "../../internal/distribution.js";
 import { envPrefixFromName, slackEnvKeys } from "./credentials.js";
 import { buildSlackManifestPair } from "./manifest.js";
 
@@ -59,7 +60,7 @@ export async function initSlackChannel(
 
   await write(
     "agent/channels/slack.ts",
-    `import { slackChannel } from "@anysphere/agent-serve/channels/slack";
+    `import { slackChannel } from "${PACKAGE_NAME}/channels/slack";
 
 /**
  * Slack channel (Socket Mode).