@cursor/july 0.1.91 → 0.1.93

package/docs/evals.md

@@ -16,12 +16,6 @@ targets) a real agent server, drives sessions over the public API, and
 grades what comes back. A passing eval means the agent started,
 accepted a message, and did what you asserted.
 
-> [!NOTE]
-> Import paths here use `@cursor/july/evals`. On projects still
-> using `@anysphere/agent-serve`, swap the import and run
-> `agent-serve eval`. See
-> [Run the CLI](/#run-the-cli) for the full rename table.
-
 ## Define evals with `defineEval`
 
 The Agent SDK discovers evals under the project-root `evals/` directory,
@@ -125,7 +119,7 @@ export default defineEvalConfig({
   // timeoutMs: 180_000, // optional project-wide default
   // judge: { model: "..." }, // default judge model for t.judge.*
   // reporters: [], // destinations that observe every case
-  // maxPlaygroundRuns: 50, // playground /v1/dev/evals history only (default 20)
+  // maxPlaygroundRuns: 50, // playground history only (default 20)
 });
 ```
 
@@ -139,7 +133,7 @@ The optional fields:
 | `timeoutMs` | `180_000` | Project-wide per-case timeout |
 | `judge` | unset | Default judge model for `t.judge.*`; see [Judge free-form output](#judge-free-form-output) |
 | `reporters` | unset | Destinations that observe every case; `--skip-report` suppresses them |
-| `maxPlaygroundRuns` | `20` | Max batches in the playground / `/v1/dev/evals*` history (not CLI `eval`) |
+| `maxPlaygroundRuns` | `20` | Max batches in the playground / `/v1/dev/evals*` history (not CLI `eval`). Hard-capped at 500. |
 
 Reporters come from `@cursor/july/evals/reporters`: `JUnit` writes a
 JUnit XML file for CI, `Artifacts` writes per-case files, and
@@ -151,7 +145,7 @@ Playground batches survive restarts whenever `agent/storage.ts` exists
 with an `evals` table or a KV core providing `delete` and `list` (the
 table is derived over the core); see
 [Storage](./storage.md#eval-and-a-b-tables). Without storage they live
-in process memory and disappear when `serve` exits — navigating away
+in process memory and disappear when `serve` exits. Navigating away
 and back still works while the process is up.
 
 ## Drive and assert with `t`
@@ -171,9 +165,9 @@ intermediate turn before the next send overwrites `t.reply`.
 depend on it.
 
 Read the full case state with `t.reply` (the last assistant text),
-`t.events` (every captured session event across turns), `t.turns`
-(settled turns, oldest first), and `t.sessionId`. `t.signal` aborts
-when the case hits its timeout; pass it to your own async work.
+`t.events` (session events captured so far), `t.turns` (settled
+turns, oldest first), and `t.sessionId`. `t.signal` aborts when the
+case hits its timeout; pass it to your own async work.
 
 Assert with the gates:
 
@@ -229,10 +223,10 @@ the CLI and playground result.
 
 Three `t.send` options apply on session create (first `t.send` only):
 
-- `workspaceFiles` — `{ path: contents }`, seeded into the local session
+- `workspaceFiles`: `{ path: contents }`, seeded into the local session
   workspace. Prefer this over machine-local paths.
-- `workspaceDir` — absolute harness cwd (local runtime).
-- `cloud` — per-session cloud options merged over the agent's static
+- `workspaceDir`: absolute harness cwd (local runtime).
+- `cloud`: per-session cloud options merged over the agent's static
   `cloud` config (repos / env / …). Use a pinned `repos` override to
   attach a fixture repo for cloud evals without putting it on the
   agent's default `cloud.repos`. Cloud ignores `workspaceFiles` seeds.
@@ -294,7 +288,7 @@ match both groups.
 
 `eval` boots an ephemeral server on port 0 with a temp state root
 outside the project, so cases don't inherit ambient monorepo rules and
-don't pollute `.agent-serve/`. Point `--url` at a running server to eval
+don't write into the project state directory. Point `--url` at a running server to eval
 a live agent instead:
 
 ```bash
@@ -348,29 +342,18 @@ failed assertion without parsing terminal text.
 
 ## Run evals in the playground
 
-Start the server with `--dev`, open the playground, and choose
-**Evals**. You can run every case or one case, watch progress, and open
-the resulting session trace.
+Start the server, open the playground, and choose **Evals**. You can run
+every case or one case, watch progress, and open the resulting session
+trace. The Evals tab works on a normal `serve`.
 
 ```bash
-agent-sdk serve --dir . --dev
+agent-sdk serve --dir .
 ```
 
 Playground runs target the live server instead of an ephemeral one.
 Their sessions appear in the session list. One eval batch can run at a
-time. Batches persist across restarts whenever `agent/storage.ts`
-provides an `evals` table or a KV core with `delete` and `list` (the
-table is derived over the core); without storage they are **in-memory
-only** (capped by `maxPlaygroundRuns`) — see
-[Storage](./storage.md#eval-and-a-b-tables).
-
-The UI uses the playground eval routes (available without `--dev`):
-`GET /v1/dev/evals` lists datapoints and config (includes `maxPlaygroundRuns` /
-`durableRuns`),
-`GET /v1/dev/evals/runs` rehydrates recent batches after navigation,
-`POST /v1/dev/evals/runs` starts a batch (returns an **Eval ID** / `runId`),
-`GET /v1/dev/evals/runs/:runId` polls it, and
-`POST /v1/dev/evals/runs/:runId/cancel` cancels a running batch. See
+time. Persistence follows the rule under
+[Configure eval runs](#configure-eval-runs). See
 [Playground eval routes](./reference/http-api.md#playground-eval-routes).
 The start request returns `202` while cases run in the background.
 Poll until the snapshot status becomes `completed`, `failed`, or `cancelled`.
@@ -389,10 +372,6 @@ agent-sdk eval cancel evalrun_… --prod --slug vulnerability-scanner
 agent-sdk eval status evalrun_… --prod --slug vulnerability-scanner
 ```
 
-The Evals tab prefers the server’s in-flight batch (`activeRunId`) over a
-stale tab-local remembered id, so CLI / Slack kicks show up without an
-incognito window.
-
 ## What good cases assert
 
 Gate decisions and shape, not prose. Model wording varies run to run.

package/docs/example-agents/approval-buddy.md

@@ -69,7 +69,7 @@ approving the PR.
 | Server tools | [`agent/tools/`](../../examples/approval-buddy/agent/tools/) | Prepare evidence, approve, list buddies, and search GIFs. |
 | Deterministic policy | [`agent/lib/approve.ts`](../../examples/approval-buddy/agent/lib/approve.ts), [`agent/lib/buddies.ts`](../../examples/approval-buddy/agent/lib/buddies.ts) | Own the roster and live eligibility checks. |
 | Review subagents | [`agent/subagents/`](../../examples/approval-buddy/agent/subagents/) | Run deep audit and code-quality passes over the same evidence. |
-| Storage | [`agent/storage.ts`](../../examples/approval-buddy/agent/storage.ts) | Persist sessions and events with `cursorHostedStorage` (Bugbot `agent_serve_*`). |
+| Storage | [`agent/storage.ts`](../../examples/approval-buddy/agent/storage.ts) | Persist sessions and events with `cursorHostedStorage`. See [Storage](../storage.md). |
 | Live A/B experiment | [`agent/ab.ts`](../../examples/approval-buddy/agent/ab.ts) | Compare baseline responses with a concise, presentation-only treatment (`concise-results`). |
 | Evals and unit tests | [`evals/`](../../examples/approval-buddy/evals/), [`agent/lib/`](../../examples/approval-buddy/agent/lib/) | Protect routing, output contracts, policy, and GitHub behavior. |
 

package/docs/example-agents/benny.md

@@ -48,7 +48,7 @@ need the watched-channel path.
 
 | File | Purpose |
 | --- | --- |
-| [`agent/agent.ts`](../../examples/benny/agent/agent.ts) | Names the agent, selects its model, and keeps the harness under `.agent-serve/harness`. |
+| [`agent/agent.ts`](../../examples/benny/agent/agent.ts) | Names the agent, selects its model, and points the harness at a project-local cwd so inherited playbooks load. |
 | [`agent/instructions.md`](../../examples/benny/agent/instructions.md) | Defines engagement rules, evidence policy, and the playbook routing map. |
 | [`agent/channels/slack.ts`](../../examples/benny/agent/channels/slack.ts) | Handles account-linked mentions and direct messages. |
 | [`agent/channels/slack-app.ts`](../../examples/benny/agent/channels/slack-app.ts) | Runs the dedicated app and watches one allowlisted channel. |
@@ -66,18 +66,9 @@ large monorepo. This prevents ancestor instruction and repository-rule files
 from leaking into an unrelated agent.
 
 The playbook router needs the opposite. Its procedures live at the repository
-root, so
-`agent.ts` sets:
-
-```ts
-local: {
-  cwd: ".agent-serve/harness",
-}
-```
-
-Each harness workspace lands under
-`examples/benny/.agent-serve/harness/<sessionId>`. Walking up the directory
-tree reaches the host repository and its inherited playbook directory.
+root, so `agent.ts` points `local.cwd` at a harness directory under the
+project. Each harness workspace is a child of that directory. Walking up
+reaches the host repository and its inherited playbook directory.
 
 Those playbooks are inherited context. `agent-sdk info` reports zero authored
 skills for the agent. Copying this project into another repository removes

package/docs/example-agents/codebase-wiki.md

@@ -32,9 +32,9 @@ The wiki refuses to become a merge log:
 - Every touched page gets a dated changelog entry citing the PR
   number, so each fact traces back to a merge.
 
-The wiki itself is markdown on the serve host, in `.agent-serve/wiki/`
-by default with a `CODEBASE_WIKI_DIR` override. Sessions are
-disposable; the wiki is the durable state.
+The wiki itself is markdown on the serve host, in a wiki directory by
+default with a `CODEBASE_WIKI_DIR` override. Sessions are disposable;
+the wiki is the durable state.
 
 ## Follow a merged PR
 
@@ -108,11 +108,8 @@ agent-sdk github replay https://github.com/owner/repo/pull/123 \
 ```
 
 The reply is a 202 acknowledgement; the ingest continues in the task.
-Watch the session in the playground, then read the result on disk:
-
-```bash
-ls examples/codebase-wiki/.agent-serve/wiki/features/
-```
+Watch the session in the playground, then open the wiki directory on
+the serve host. Feature pages land under `features/`.
 
 Each ingested feature page carries an overview, a "How it works"
 section, and a changelog line citing the PR. Deterministic digest

package/docs/example-agents/concierge.md

@@ -85,7 +85,7 @@ A peer can only resolve within a multi-agent serve host. Validating Concierge
 alone checks its files, but serving it alone fails because `weather-agent`
 isn't mounted.
 
-From `packages/agent-serve`, validate both projects:
+From this package, validate both projects:
 
 ```bash
 agent-sdk validate --dir examples/concierge
@@ -98,8 +98,7 @@ two-project mount instead. Copy only the authored files needed for this proof,
 leaving Weather's Slack channels out:
 
 ```bash
-mkdir -p "$PWD/.agent-serve"
-PAIR_DIR=$(mktemp -d "$PWD/.agent-serve/concierge-weather.XXXXXX")
+PAIR_DIR=$(mktemp -d "${TMPDIR:-/tmp}/concierge-weather.XXXXXX")
 mkdir -p "$PAIR_DIR/concierge" "$PAIR_DIR/weather-agent/agent"
 cp -R examples/concierge/agent "$PAIR_DIR/concierge/"
 cp examples/concierge/package.json "$PAIR_DIR/concierge/"

package/docs/example-agents/index.md

@@ -1,6 +1,6 @@
 ---
 title: "Choose the right Agent SDK example"
-description: "Compare all twelve example agents by runtime, channels, tools, state, and the framework pattern each one teaches."
+description: "Compare the example agents by runtime, channels, tools, state, and the framework pattern each one teaches."
 ---
 
 # Choose the right Agent SDK example
@@ -12,7 +12,7 @@ design.
 
 The source projects live under
 [`examples/`](../../examples/). Run the commands below from
-`packages/agent-serve`. See [Run the CLI](/#run-the-cli) if the
+this package. See [Run the CLI](/#run-the-cli) if the
 `agent-sdk` command isn't installed.
 
 ## Compare the examples
@@ -26,8 +26,7 @@ The source projects live under
 | [Alert investigator](./oncall.md) | Local | Watched Slack alerts channel | Bot-post channel watching, per-thread debounce, reminder tools, and host Slack calls | Every alert gets a thread-pinned investigation that schedules its own re-checks. |
 | [PR evidence reviewer](./bugbot.md) | Local | Custom HTTP and Slack | Host tool, skill, seeded workspaces, and an eval | The model receives a prepared diff-first evidence tree instead of a checkout. |
 | [Approval Buddy](./approval-buddy.md) | Local | GitHub and Slack | Policy tools, two subagents, durable storage, and evals | Code decides whether a PR may be approved. Reviews stay informational. |
-| [Security Reviewer](./security-reviewer.md) | Local host pipeline | GitHub and chat | Staged tools, parallel SDK agents, progress UI, durable storage, A/B, and evals | Lives in `factory/security-reviewer/`. Reviewers and triage overlap while the playground shows every stage. |
-| [Remote PR coordinator](./fsd.md) | Local coordinator and remote PR sessions | HTTP, GitHub, and Slack | Remote handoff, hooks, affinity, buffering, reminders, and workflow MCP | One remote conversation follows a PR across chat, webhooks, and timed wakes. |
+| [Security Reviewer](./security-reviewer.md) | Local host pipeline | GitHub and chat | Staged tools, parallel SDK agents, progress UI, durable storage, A/B, and evals | Reviewers and triage overlap while the playground shows every stage. |
 | [Knowledge base](./knowledge-base.md) | Local | Built-in HTTP chat | Durable host-side state, a conventions skill, a schedule, unit tests, and evals | People curate shared facts in chat, and fresh sessions retrieve them from markdown. |
 | [Codebase wiki](./codebase-wiki.md) | Local | GitHub and chat | Task-dispatch webhooks, seeded digests, a mapping skill, a schedule, and evals | Merged PRs accumulate into per-feature wiki pages with a daily digest. |
 | [Codeowners review](./codeowners-review.md) | Local | GitHub, chat, and fixtures | Ownership routing in code, playbook data files, parallel subagents, and evals | Each product area reviews with its own playbook, and verdicts aggregate mechanically. |
@@ -48,8 +47,8 @@ Use this order when you want to learn the Agent SDK one capability at a time:
 6. Study [PR evidence reviewer](./bugbot.md) before giving a model repository
    evidence.
 7. Move policy into code with [Approval Buddy](./approval-buddy.md).
-8. Compare [Security Reviewer](./security-reviewer.md) and
-   [Remote PR coordinator](./fsd.md) for host-side versus remote PR work.
+8. Study [Security Reviewer](./security-reviewer.md) for host-side PR
+   work.
 9. See parallel subagent delegation carry team judgment in
    [Codeowners review](./codeowners-review.md).
 10. Curate team context through conversation with
@@ -72,9 +71,7 @@ Several examples need more:
 - GitHub examples require access to the target repository. Codebase wiki and
   Codeowners review call the host `gh` CLI for PR data; the codeowners
   fixtures run without network.
-- Example agents use `cursorHostedStorage` (`agent/storage.ts`) for Cursor-hosted session storage (control-plane proxy).
-- Remote PR coordinator starts remote agent sessions and needs access to its
-  workflow backend.
+- Example agents use `cursorHostedStorage` in `agent/storage.ts` for hosted session storage. See [Storage](../storage.md).
 
 Each guide lists its own credentials, services, and side effects.
 

package/docs/example-agents/knowledge-base.md

@@ -19,8 +19,8 @@ feature documentation instead.
 
 ## Keep shared knowledge on the filesystem
 
-The knowledge base lives outside any session workspace, in
-`.agent-serve/wiki/` by default. `KNOWLEDGE_BASE_DIR` overrides the location,
+The knowledge base lives outside any session workspace, in a wiki
+directory on the serve host by default. `KNOWLEDGE_BASE_DIR` overrides the location,
 and the tools resolve it on every call, so tests and evals can point the same
 code at a temp directory.
 

package/docs/example-agents/security-reviewer.md

@@ -175,10 +175,10 @@ findings, accounting, and audit events.
 
 ## Separate session storage from review artifacts
 
-`defineStorage` + `cursorHostedStorage` sends Agent SDK session and event records
-to Cursor-hosted Bugbot storage through the control-plane proxy. Security
-Reviewer sets `restore: "off"` so startup doesn't load old review sessions in
-bulk. A continuation lookup can still fetch a needed session.
+`cursorHostedStorage` keeps Agent SDK session and event records on
+Cursor-managed hosting. Security Reviewer sets `restore: "off"` so startup
+doesn't load old review sessions in bulk. A continuation lookup can still
+fetch a needed session. See [Storage](../storage.md).
 
 The staged review files are separate from session storage. Session-store
 durability doesn't preserve those files. All stages for one `runId` must see
@@ -200,7 +200,7 @@ instruction overlay asking chat and playground summaries to lead with high
 and critical findings. Full artifacts, `finalResponse`, and finding counts
 still include every finding. Stage-tool counters appear in the
 playground A/B view. Local sample and snapshot files persist under
-`.agent-serve/`.
+the project state directory.
 
 When a treatment session has only low or medium findings, the filtered review
 body currently says no vulnerabilities were found even though artifacts and

package/docs/example-agents/weather-agent.md

@@ -147,8 +147,8 @@ A real call writes `vm-tool-observations/<id>.json` in the agent cwd and
 returns hostname, cwd, and pid. Stream events show `probe:probe_cloud_tool`,
 not `shell`.
 
-A local `.agent-serve/tools/probe_cloud_tool.sh` or a marker under `probes/`
-means the model invented a substitute.
+A local tool script or a marker under `probes/` means the model
+invented a substitute.
 
 ```bash
 agent-sdk run --dir examples/weather-agent \
@@ -263,7 +263,8 @@ hash:
 - `treatment` adds a brief Celsius instruction and changes `get_weather` to
   return Celsius fields.
 
-Samples and aggregate snapshots persist under `.agent-serve/`. The treatment
+Samples and aggregate snapshots persist under the project state
+directory. The treatment
 only changes current conditions; `get_forecast` still returns Fahrenheit.
 Treat the branch as an example of `ctx.session.abs`, not a complete unit
 policy.

package/docs/guides/agent-to-agent.md

@@ -14,7 +14,7 @@ same. A peer MCP connection makes the wiring one line.
 This guide wires a `concierge` agent that delegates weather questions
 to a `weather-agent` peer mounted on the same host.
 
-## The MCP endpoint
+## MCP endpoint
 
 Each agent serves the Model Context Protocol over streamable HTTP at
 `/<slug>/v1/mcp` (or `/v1/mcp` in single mode). The surface is stateless

package/docs/guides/cloud-runtime.md

@@ -64,34 +64,21 @@ mapping shifts:
 | `instructions.*` | `AGENTS.md` in the session workspace | prepended to the first prompt |
 | Server tools (`execution: "server"`) | in-process SDK custom tools | authenticated HTTP MCP back to the AgentSDK host, when `--public-url` or `--cloud-tools-url` is set |
 | Agent tools (`execution: "agent"`) | scripts in the session workspace | catalog + script bodies on the first prompt |
-| `skills/*` | `.cursor/skills/` in the workspace | native discovery from the Agent Store (`skills/` on hosted deployments; `agent-serve/<agent>/skills/` on the USER store for local serve/run) |
+| `skills/*` | `.cursor/skills/` in the workspace | native discovery after the first turn, from the hosted store or the signed-in account |
 | `mcp-connections/*.ts` | SDK `mcpServers` | SDK `mcpServers` (peers need `--public-url`) |
 | `sandbox/workspace/**` | seeded into the session workspace | ignored |
 | Tool approvals (`needsApproval`) | supported | not supported; keep approval-gated tools on local turns |
 
-Authored skills copy onto an Agent Store on the first cloud turn so the
-VM discovers them natively. Hosted deployments write the deployment
-store's `skills/` directory; local `serve`/`run` with a personal API
-key writes `agent-serve/<agent>/skills/` on the USER store.
-
-Hosted deployments configure the server-tool MCP URL automatically
-(`cloudToolsUrl`, authenticated with the resolved Cursor API key). A
-self-hosted public server needs `--public-url` (and `--bearer-token` when the
-host is not behind another trusted authentication boundary) so cloud turns
-can reach those tools. Without either, the server warns at startup and
-cloud turns omit the server tools.
+Authored skills are discovered natively after the first cloud turn,
+using the hosted store or the signed-in account.
 
 Approvals are a local-runtime contract. On cloud, a `needsApproval` tool
 call rides one HTTP MCP request from the VM, and a parked call would
 hold that request open until it times out; there is no durable approval
 flow for cloud turns.
 
-Two more behaviors are cloud-specific. Sessions persist a separate SDK
-agent id (`bc-…`), emitted on the stream as `agent.bound` with a URL to
-the cloud conversation. Cloud ids are minted during the first send. And
-peer MCP connections resolve to `--public-url` for cloud turns, because a VM
-cannot reach the host's loopback; without one, peers are omitted from
-cloud turns and the server warns at startup.
+Peer MCP connections need `--public-url` for cloud turns. Without one,
+peers are omitted and the server warns at startup.
 
 ## Hybrid: local agent, cloud sessions
 
@@ -106,12 +93,8 @@ base that per-session options merge over.
 
 These come from running a PR driver against real PR traffic:
 
-- One cloud agent per unit of work (per PR, say). Store the `bc-…` id
-  keyed by the work unit (an affinity store written from an
-  `agent.bound` hook) so webhook wakes resume the same conversation
-  instead of booting a fresh VM per event.
-- Stable continuation keys (`pr:owner/repo#N`) so every wake lands on
-  the same session within a channel.
+- One cloud session per unit of work, keyed with a stable continuation
+  token (`pr:owner/repo#N`) so every wake lands on the same conversation.
 - Keep the host deterministic: fetch briefs and metadata on the host,
   send the VM a compact prompt, and let the VM re-read source of truth
   with its own `gh` and `git` instead of trusting payload snapshots.
@@ -131,6 +114,6 @@ driving channels directly.
 Continue with these pages:
 
 - [Agent config](../reference/agent-config.md): the `runtime` and
-  `cloud` fields precisely
+  `cloud` fields
 - [GitHub guide](./github.md): the webhook patterns that pair with
   cloud triage

package/docs/guides/convert-automation.md

@@ -42,9 +42,9 @@ cd nightly-triage
 ```
 
 The command fetches the Automation before writing files. A 404 means it
-was not found, you do not have access, or the `agent_serve_mvp` feature
-gate is off for your team. A 422 means it is Cursor-managed. The command
-writes nothing after either error.
+was not found, you do not have access, or convert is not enabled for
+your team. A 422 means it is Cursor-managed. The command writes nothing
+after either error.
 
 The command runs `npm install` after writing the project. If the install
 fails, the files remain. Run `npm install` in the output directory

package/docs/guides/github.md

@@ -49,8 +49,9 @@ Choose `permissions` by what the agent needs:
 `contents-write` is an explicit opt-up. `progress.commitStatus` posts a
 GitHub check run (`checks:write`). Hosted `cursorAccount` mints that
 permission on `"contents-write"` tokens. Enabling `commitStatus` opts a
-`"pr-write"` channel up to that tier so github-proxy can post the check.
-`"pr-write"` without `commitStatus` is enough for comments and banners.
+`"pr-write"` channel up to that tier because it needs check-write
+permission. `"pr-write"` without `commitStatus` is enough for comments
+and banners.
 Prefer `"pr-write"` unless the agent must push or post a merge-box check.
 
 Set `checks: true` when channel code posts its own Checks API runs through
@@ -70,10 +71,9 @@ Repeat `--repo` for each repository. The stream and credential are
 resolved as the signed-in Cursor principal. `serve` refuses to start
 signed out.
 
-Offset and consumer id live under `<state-root>/cursor-events/`.
-`CURSOR_API_BASE_URL` overrides the backend. The stream carries event
-metadata, not full webhook bodies, so your agent should re-read the PR
-or checks from GitHub instead of trusting a snapshot in the wake.
+The stream carries event metadata, not full webhook bodies, so your
+agent should re-read the PR or checks from GitHub instead of trusting a
+snapshot in the wake.
 
 This is the preferred production path: no public URL, no repo admin
 webhook, and no inbound network for GitHub deliveries.
@@ -111,7 +111,7 @@ things:
 | `{ task }` | Host-side work. The delivery is 202-ACKed immediately and the task runs past GitHub's ~10-second timeout. No chat session. |
 | `null` | Skip this delivery. |
 
-`{ auth }` may also carry `workspaceFiles` — the same session seed Slack
+`{ auth }` may also carry `workspaceFiles`, the same session seed Slack
 and `send()` use. Pass a function to fetch after a 202 so I/O can miss
 GitHub's ~10s window.
 
@@ -198,9 +198,7 @@ These patterns come from running a PR agent against real traffic:
 - Persist the buffer in `host.kv` before you acknowledge a wake, and
   restore it on channel start. A restart must not drop buffered wakes.
 - Key sessions with a stable continuation token (`pr:owner/repo#N`) so
-  every wake resumes the PR's conversation. Cross-channel resume needs
-  an affinity store mapping PR → SDK agent id; write it from an
-  `agent.bound` hook with `ctx.host.kv`.
+  every wake resumes the PR's conversation.
 - Keep payload details out of wake prompts. Send a generic "re-check
   the PR" and let the agent re-read source of truth instead of trusting a
   stale snapshot.
@@ -262,19 +260,9 @@ behavior. Reactions still default on; set `reactions: false` when the
 eyes emoji is noise. Descriptions are optional; defaults derive from
 `botName` or the check `context`.
 
-The check run posts to `channel.state.headSha`. PR and CI wakes seed and
-refresh it (`refreshState` on continuation). A first wake that is only an
-`issue_comment` has no head SHA in the payload, so the check is skipped until
-a PR/CI wake stores one; the banner still posts. Review-comment wakes
-carry `pull_request.head.sha` when GitHub includes it.
-
-The sticky comment id and latest check-run id live on durable
-`GitHubChannelState` (session record). Each wake also passes `refreshState`
-so `headSha` / refs update on continuation without wiping those ids. A later
-turn on the same SHA creates a new check run — GitHub cannot reopen a
-completed run. Persist other derived state
-with `ctx.host.kv` or `ctx.host.files`. `stateRoot` resets on hosted
-replace.
+A comment-only first wake has no head SHA, so the check waits for a
+PR or CI event. The banner still posts. A later turn on the same SHA
+creates a new check run; GitHub cannot reopen a completed run.
 
 Override `events` when the mapping is custom. [Approval Buddy](../example-agents/approval-buddy.md)
 posts commit status from `turn.started` / `action.result` / `turn.failed`

package/docs/guides/mcp-oauth.md

@@ -18,8 +18,8 @@ The companion skill is
 
 - Authorize `defineConnection({ url, oauth: true })` with a browser PKCE
   flow (`agent-sdk mcp oauth <connection>`)
-- Keep tokens in `~/.config/agent-serve/mcp-auth.json`, bound to that
-  connection's resource URL
+- Keep tokens in `mcp-auth.json` under the CLI config directory, bound
+  to that connection's resource URL
 - Upsert deployment secrets with `--store` so hosted engines seed the
   same tokens from env
 - Keep privileged servers off the model with `hostOnly: true` while
@@ -97,8 +97,8 @@ What happens:
    `oauth: true`
 2. It opens the authorization URL in your browser
 3. The callback lands on `http://localhost:8787/callback`
-4. Tokens land in `~/.config/agent-serve/mcp-auth.json` (override the
-   config dir with `AGENT_SERVE_CONFIG_DIR`)
+4. Tokens land in `mcp-auth.json` under the CLI config directory
+  (override with `AGENT_SERVE_CONFIG_DIR`)
 
 If you're already authorized, the command prints that and exits. Re-run
 it after rotating tokens on the MCP server, or after you change the

package/docs/guides/slack.md

@@ -127,7 +127,7 @@ writes `<PREFIX>_SLACK_BOT_TOKEN` and `<PREFIX>_SLACK_APP_TOKEN` into
 [below](#wire-the-env-and-verify).
 
 If Slack needs a workspace admin to approve the app, keep the CLI
-running. Managed install does not file the request — open Slack's
+running. Managed install does not file the request. Open Slack's
 **Request approval** page (the CLI prints the link; the same URL is
 **Send a reminder** after you submit). After an admin approves, click
 **Retry** in the wizard.
@@ -190,9 +190,9 @@ option.
 agent-sdk slack init --manual --dir . --name "My Agent"
 ```
 
-That writes `agent/channels/slack.ts`, importable manifests at
-`.agent-serve/slack/manifest.{dev,prod}.json`, `env.example`, and
-`setup-status.json`. `--no-prefix` uses shared `SLACK_*` variables on
+That writes `agent/channels/slack.ts`, Slack manifests under the
+project state directory, `env.example`, and `setup-status.json`.
+`--no-prefix` uses shared `SLACK_*` variables on
 a single-agent host. `--prefix CUSTOM` overrides the directory-derived
 prefix. `--channel-posts` subscribes the manifests to channel-post
 events.

package/docs/guides/webhooks.md

@@ -16,8 +16,8 @@ mechanism. This page is the mechanism itself.
 The built-in HTTP channel is always mounted (under `/<slug>` in the
 default multi-agent layout). `POST /v1/session` starts a conversation,
 `POST /v1/session/:id` follows up, and `GET /v1/session/:id/stream`
-streams NDJSON events, plus sessions, approvals, and tool routes. The
-full list is in the [HTTP API reference](../reference/http-api.md).
+streams NDJSON events, plus sessions, approvals, and tool routes. See
+the [HTTP API reference](../reference/http-api.md).
 
 Write a custom channel when that shape doesn't fit: a webhook with its
 own payload contract, a surface that keys sessions by a domain id, or a
@@ -451,7 +451,7 @@ Start with curl and saved payloads under `fixtures/`. The playground's
 endpoint, has Copy curl, and opens the created session on a successful
 Try. For regression coverage, drive the same behavior through an eval,
 or keep channel logic deterministic in `agent/lib/` and unit-test it
-there. When something looks wrong, read the session's `events.ndjson`.
+there. When something looks wrong, inspect the session event stream.
 The stream is the record of what happened.
 
 For GitHub specifically, don't hand-roll fixtures.

package/docs/hillclimbing.md

@@ -56,7 +56,7 @@ Pin the input first. A moving fixture is noise. For GitHub agents, use `agent-sd
 
 ## How do I run one hillclimb round?
 
-**Measure.** Hit the agent the way a user would: playground, channel HTTP, or Slack in `--dev`. Or ask the hillclimb skill to do it. `agent-sdk run` returns a JSON trajectory and writes a trace under `.agent-serve/traces/`.
+**Measure.** Hit the agent the way a user would: playground, channel HTTP, or Slack in `--dev`. Or ask the hillclimb skill to do it. `agent-sdk run` returns a JSON trajectory and writes a trace under the project state directory.
 
 **Reflect.** Score the trajectory, not impressions. Was the answer right? Did the model thrash (too many tools, fat evidence, grep loops)? Did it invent work the host should have prepared? Name the single dominant problem for this round in one sentence. Example: "Full-file dumps trigger grep loops."
 

package/docs/quickstart.md

@@ -21,7 +21,7 @@ review. Add GitHub event handling so pull requests can trigger reviews.
 - Node 22.13 or newer. Bun isn't supported.
 - Run commands as `agent-sdk <command>`, or use
   `npx @cursor/july <command>` when the CLI isn't on `PATH`. See
-  [Run the CLI](/#run-the-cli) for monorepo checkouts and other setups.
+  [Run the CLI](/#run-the-cli) if `agent-sdk` is not on `PATH`.
 - A Cursor credential for model turns. Sign in once:
 
 ```bash

package/docs/reference/agent-config.md

@@ -70,8 +70,8 @@ model: "composer-2.5",
 ## Choose a runtime
 
 `runtime: "local"` (the default) runs turns on the Cursor SDK harness on
-this machine. The session id doubles as the SDK agent id, and server
-tools, skills, sandbox seeds, and tool approvals all apply.
+this machine. Server tools, skills, sandbox seeds, and tool approvals
+all apply.
 
 `runtime: "cloud"` runs turns on Cursor cloud agents (`bc-…` ids). Pass
 a `cloud` block with the repos the VM carries. Server tools stay
@@ -115,8 +115,8 @@ it.
 
 Session workspaces are real Cursor project directories. The harness loads
 `AGENTS.md` and `.cursor` config from ancestor directories. An agent nested
-in another git repo (a monorepo package) defaults to
-`~/.cache/agent-serve/<dir>` when you omit `cwd`, so the enclosing checkout
+in another git repo (a monorepo package) defaults to a per-project
+cache directory under `~/.cache` when you omit `cwd`, so the enclosing checkout
 does not leak rules, skills, or MCP servers into the turn. A standalone git
 root keeps the in-project session workspace. Point `cwd` at a checkout only
 when the agent should inherit that tree.
@@ -138,7 +138,7 @@ export default defineAgent({
 });
 ```
 
-Agent Serve always adds `"mcp"` to a configured allowlist. Authored
+The Agent SDK always adds `"mcp"` to a configured allowlist. Authored
 server tools in `agent/tools/` use MCP to reach the model. MCP can also
 expose declared connections and servers from the harness directory's
 ambient `.cursor` config. To exclude a checkout's MCP servers, point
@@ -159,7 +159,7 @@ Two names have broader effects:
 
 Tool allowlists work only with the local runtime. A
 `runtime: "cloud"` agent that sets `tools` fails at serve startup.
-Agent Serve also refuses per-send cloud sessions from a hybrid agent
+The Agent SDK also refuses per-send cloud sessions from a hybrid agent
 with an allowlist. It won't run those sessions with unrestricted tool
 access.
 
@@ -167,7 +167,7 @@ The allowlist controls which tools the model can call. It does not
 isolate the serve host. For agents that process untrusted input, also
 set `local: { sandbox: true }`.
 
-## The `cloud` block
+## Cloud options
 
 Cloud agent defaults forwarded to the Cursor SDK: `repos` (each
 `{ url, startingRef? }`), environment selection, `envVars`, and the
@@ -239,13 +239,8 @@ console.log(`listening on ${handle.url}`);
 // handle.createReminder(...), handle.project, await handle.close()
 ```
 
-`ServeOptions` mirrors the CLI flags: `port`, `host`, `dev`,
-`stateRoot`, `apiKey`, `schedules`, `reminders`, `noControlPlane`,
-`playground`, `docs`, `authToken` (the `--bearer-token` equivalent),
-`allowAnonymous`, `allowAnonymousCursorGithub`,
-`allowAnonymousCursorAccountMcp`, `cursorGithubProxy`, `publicUrl`,
-`cloudToolsUrl`, `cursorEvents`, and `logger`. `serve()` additionally
-accepts `discovery` (project-loading options) and
+Host settings match the documented [CLI](./cli.md) `serve` flags.
+`serve()` also accepts `discovery` (project-loading options) and
 `mode: "single" | "multi"`. The Cursor credential resolves in one order
 everywhere: explicit `apiKey`, then `CURSOR_API_KEY`, then the key
 stored by `agent-sdk login`.
@@ -258,4 +253,4 @@ Continue with these pages:
   agent
 - [Cloud runtime](../guides/cloud-runtime.md): when and how to leave
   the host
-- [CLI](./cli.md): the flags `ServeOptions` mirrors
+- [CLI](./cli.md): the `serve` flags `serve()` accepts