@cursor/july 0.1.92 → 0.1.94

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

package/docs/reference/channels.md

@@ -11,7 +11,7 @@ under `/v1/channels/<id>`. The Slack and GitHub packs are prebuilt
 channels with platform transports. This page is the authoring reference;
 for the walkthrough, see the [Webhooks guide](../guides/webhooks.md).
 
-## The built-in HTTP channel
+## Built-in HTTP channel
 
 It's always mounted, under `/<slug>` in the default multi-agent layout:
 session create, follow-up, stream, stop, the sessions list, approvals,
@@ -132,11 +132,9 @@ Handlers receive the Fetch `Request` and an args object:
 `"coalesce"` enqueues behind the running turn, the
 [Slack policy](./sessions.md#what-happens-when-i-send-a-follow-up)),
 `workspaceFiles`, `workspaceDir`, `cloud` (attach cloud repos for this
-session), `auth` (defaults to the request principal), `sdkAgentId`
-(resume a specific SDK agent), `state` (starting channel state for new
-sessions), `title` (session display title), `purpose` (`"eval"` skips
-sticky A/B enrollment), and `coalesceSourceTs` (dedupe key for coalesce
-queue items already delivered mid-turn).
+session), `auth` (defaults to the request principal), `state` (starting
+channel state for new sessions), `title` (session display title), and
+`purpose` (`"eval"` skips sticky A/B enrollment).
 
 ## Events
 
@@ -151,14 +149,12 @@ services. This is where a channel delivers replies back to its surface.
 
 `state` declares the starting per-session adapter state (JSON), persisted
 on the session record. Routes and event handlers read and mutate it
-through `channel.state`. `onStart(args)` runs when the channel mounts;
-the Slack pack opens its Socket Mode connection here. `onStop()` runs
-when the server drains.
+through `channel.state`. `onStart(args)` runs when the channel mounts.
+`onStop()` runs when the server stops.
 
 `onStart` receives the route helpers (`send`, `getSession`, `receive`,
-`callTool`, `host`, `waitUntil`, `artifacts`, and a `logger` that
-respects the server's log sink) plus a set that exists for long-lived
-transports:
+`callTool`, `host`, `waitUntil`, `artifacts`, `logger`) plus helpers
+for long-lived transports:
 
 - `emitAssistantMessage(sessionId, text)` appends an assistant message
   without a model turn, for host tasks that already produced the final
@@ -166,8 +162,6 @@ transports:
 - `hasContinuationSession(token)` and `isContinuationBusy(token)`
   report whether a continuation token has a live session and whether a
   turn is in flight on it.
-- `getContinuationLastBotMessageTs(token)` reads the Slack warm-delta
-  watermark from channel state.
 - `interruptContinuation(token)` stops the in-flight turn and clears
   coalesced follow-ups queued behind it.
 - `resolveApproval(sessionId, callId, decision, auth, options?)`
@@ -221,22 +215,17 @@ replay and live forwarding. Author `agent/channels/github.ts` with
 converge a merge-box check and sticky PR comment from default stream
 events. Guide: [GitHub](../guides/github.md).
 
-**Deployments** (`@cursor/july/channels/deployments`): pull transport
-over `/v0/deployment-events`. Subscribe per deploy source with
-`deploySourceUris`, narrow with `environments` / `events`, and handle
-each event in `onEvent`. `deploySourceUris` must match
-`Deployment.deploy_source_uri` as your deployment writer records it; the
-field has no format, and matching is case-insensitive but otherwise
-literal. Each event carries `deploySourceUri` and `deployVersion`.
-Author `agent/channels/deployments.ts` with `deploymentsChannel()`. The
-serve host discovers every mounted deployments channel, runs one relay
-for the process against the union of their deploy sources, and routes
-each event to the channels that asked for it; the Slack and SCM relays
-use the same ownership. It authenticates with the host credential and
-keeps a durable offset, so a restart resumes rather than dropping
-events. An empty `deploySourceUris` list mounts the channel but starts
-no relay for it, so an env-configured agent stays inert until its
-deploy sources are set.
+**Deployments** (`@cursor/july/channels/deployments`): pull deploy
+events. Subscribe per deploy source with `deploySourceUris`, narrow
+with `environments` / `events`, and handle each event in `onEvent`.
+`deploySourceUris` must match `Deployment.deploy_source_uri` as your
+deployment writer records it; matching is case-insensitive but
+otherwise literal. Each event carries `deploySourceUri` and
+`deployVersion`. Author `agent/channels/deployments.ts` with
+`deploymentsChannel()`. It uses the host credential. A restart resumes
+rather than dropping events. An empty `deploySourceUris` list mounts
+the channel but starts no pull, so an env-configured agent stays inert
+until its deploy sources are set.
 
 For other platforms like Discord or Teams, use the authored
 `defineChannel` webhook form.
@@ -255,6 +244,6 @@ session; one active continuation per session; the HTTP channel returns
 Continue with these pages:
 
 - [Webhooks guide](../guides/webhooks.md): the same API, walked through
-- [HTTP API](./http-api.md): the built-in routes precisely
+- [HTTP API](./http-api.md): session, discovery, and channel routes
 - [Sessions and streaming](./sessions.md): the events channels
   subscribe to

package/docs/reference/cli.md

@@ -5,14 +5,10 @@ description: "Commands and common flags for local development, running servers,
 
 # CLI reference
 
-`@cursor/july` installs `july` (so `npx @cursor/july docs` works),
-`agent-sdk`, and the legacy `agent-serve` alias. The examples on this
-page use `agent-sdk`. Run the CLI with Node 22.13 or newer. Don't run it
-with Bun; Bun corrupts tool-result streams from the Cursor SDK.
-
-The current release still uses `.agent-serve` for on-disk state. See the
-[rename table](/#run-the-cli) for identifiers still moving to
-agent-sdk names.
+`@cursor/july` installs `july` (so `npx @cursor/july docs` works) and
+`agent-sdk`. The examples on this page use `agent-sdk`. Run the CLI with
+Node 22.13 or newer. Don't run it with Bun; Bun corrupts tool-result
+streams from the Cursor SDK.
 
 `agent-sdk help` prints the built-in summary. The Slack and GitHub packs
 also provide `agent-sdk slack help` and `agent-sdk github help`.
@@ -32,7 +28,7 @@ also provide `agent-sdk slack help` and `agent-sdk github help`.
 | [`run`](#run)                                           | Run one or more turns locally, remotely, or on a hosted agent  |
 | [`call`](#call)                                         | Call a server tool without a model turn                        |
 | [`eval`](#eval)                                         | Run filesystem evals                                           |
-| [`trajectory`](#trajectory)                             | Summarize a saved `events.ndjson` file                         |
+| [`trajectory`](#trajectory)                             | Summarize a saved event stream                                 |
 | [`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)                     | Refresh coding-agent skills (`npm install` already copies them) |
@@ -97,7 +93,6 @@ agent-sdk serve [--dir <path>] [--port 3000] [--host 127.0.0.1] [--dev]
                   [--allow-anonymous-cursor-github]
                   [--allow-anonymous-cursor-account-mcp]
                   [--public-url <url>] [--cloud-tools-url <url>]
-                  [--cursor-github-proxy] [--no-control-plane]
                   [--no-schedules] [--no-playground]
                   [--no-docs] [--cursor-events --repo owner/name]...
 ```
@@ -106,15 +101,14 @@ If `--dir` is an agent project, it mounts under its directory name. If
 it contains agent projects, each child mounts separately. The index
 lives at `/`. Each agent is available at `/<slug>/v1/*` and
 `/<slug>/playground`. On a TTY, press Enter to restart.
-Unless `--state-root` is set, each mount uses
-`<agent-project>/.agent-serve`; slugged mounts use
-`<agent-project>/.agent-serve/<slug>`.
+Unless `--state-root` is set, each mount uses a state directory under
+the agent project. Slugged mounts get a subdirectory named for the slug.
 
 | Flag | Meaning |
 | --- | --- |
 | `--port` | Listen on this port. `0` selects an available port. The default is `3000`. When the default is taken, serve tries the next free port and prints a notice; an explicit `--port` fails with a next-port hint instead. |
 | `--host` | Bind this host. The default is loopback-only `127.0.0.1`. |
-| `--dev` | Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, widen playground session access on loopback, and start Vite HMR when available. |
+| `--dev` | Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, and widen playground session access on loopback. |
 | `--mode` | Use `multi` for slugged routes and an index, or `single` for one agent at the unslugged `/v1/*`. The default is `multi`. |
 | `--api-key` | Use this Cursor API key. The command falls back to `CURSOR_API_KEY`, then the stored login. |
 | `--state-root` | Store sessions, streams, workspaces, and channel state here. Keep durable production state outside the agent repository. |
@@ -124,12 +118,10 @@ Unless `--state-root` is set, each mount uses
 | `--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. |
-| `--cursor-events` | Pull SCM events from Cursor's `/v0/scm-events` in addition to authored webhook routes. Requires a signed-in host. Pass repeatable `--repo owner/name` values; repos declared by `githubChannel({ cursorAccount })` also enable the relay. State lives under `<state-root>/cursor-events/`. |
+| `--no-playground` | Skip the web playground. |
+| `--no-docs` | Skip the documentation site at `/docs`. |
+| `--cursor-events` | Pull SCM events from Cursor in addition to authored webhook routes. Requires a signed-in host. Pass repeatable `--repo owner/name` values; repos declared by `githubChannel({ cursorAccount })` also enable it. |
 
 Multi-agent slugs must start with a letter or digit, then contain only
 letters, digits, `_`, or `-`. The reserved slugs are `v1`, `playground`,
@@ -149,10 +141,9 @@ agent-sdk dev ./sdk-pr-reviewer --port 3000
 `dev` accepts the same flags as [`serve`](#serve). You can use `--dir`
 instead of the positional path.
 Dev mode is always on: schedules and reminders wait for manual dispatch,
-GitHub accepts unsigned loopback deliveries, and Vite HMR starts when
-the toolchain is present. Prefer this over `serve --dev` while
-iterating. Pass at most one positional path. Don't combine a positional
-path with a different `--dir`.
+and GitHub accepts unsigned loopback deliveries. Prefer this over
+`serve --dev` while iterating. Pass at most one positional path. Don't
+combine a positional path with a different `--dir`.
 
 ## chat
 
@@ -289,7 +280,7 @@ npx @cursor/july docs
 agent-sdk docs [--port <n>] [--host 127.0.0.1] [--print]
 ```
 
-The site is the same VitePress build mounted at `/docs` on a running
+The site is the same documentation mounted at `/docs` on a running
 `serve` host. `docs` starts a loopback-only static server (default port
 is an ephemeral port) and keeps it open until Ctrl-C. `--print` prints
 the URL without opening a browser.
@@ -325,7 +316,7 @@ after the turns finish.
 | `--slug <slug>` | Pick one agent when local discovery mounts several agents. With `--prod`, select the hosted deployment. |
 
 The default trace path is
-`<dir>/.agent-serve/traces/<sessionId>.ndjson`. JSON output contains
+`<state-root>/traces/<sessionId>.ndjson`. JSON output contains
 `ok`, `sessionId`, `continuationToken`, `trace`, `playgroundUrl`,
 `playgroundHint`, `visualize`, and `trajectory`. The command exits
 non-zero when the trajectory fails.
@@ -393,7 +384,7 @@ between 1 and 200. Timeout priority is the case's `timeoutMs`, the CLI's
 | `--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/`. |
+| `--artifacts <dir>` | Write run artifacts here. The default is a timestamped directory under `<state-root>/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>`). |
@@ -565,10 +556,9 @@ takes precedence over the stored login. `logout` removes the local
 credential file but doesn't revoke the API key. Revoke it in the Cursor
 dashboard when it should stop working.
 
-Non-production backends: login and account RPCs honor
-`CURSOR_API_BASE_URL` while the SDK harness honors `CURSOR_BACKEND_URL`.
-Set both to the same URL, or keys minted on one backend are rejected by
-the other.
+Login and account RPCs honor `CURSOR_API_BASE_URL`. The SDK harness
+honors `CURSOR_BACKEND_URL`. Set both to the same URL, or keys minted
+on one host are rejected by the other.
 
 ## update
 
@@ -648,7 +638,7 @@ state layout.
 agent-sdk deployments [--team <id>] [--json]
 ```
 
-Text output shows each slug, status, generation, deployment kind, and
+Text output shows each slug, status, deployment kind, and
 update time. `--json` prints `{ deployments }`.
 
 ## deployment
@@ -659,7 +649,7 @@ update time. `--json` prints `{ deployments }`.
 agent-sdk deployment <slug> [--team <id>] [--json]
 ```
 
-Text output includes status, generation, kind, alias, source, egress
+Text output includes status, kind, alias, source, egress
 domains, secret names, engine state, and the last error when present.
 `--json` returns the full API response. It can include short-lived
 `engineAccess.headers`, so handle JSON output as a credential.
@@ -748,8 +738,8 @@ as a credential.
 `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-auth.json` under the CLI config directory (override with
+`AGENT_SERVE_CONFIG_DIR`). Pass `--store` to upsert matching
 `MCP_OAUTH_<CONNECTION>_*` secrets on the hosted deployment.
 
 Cursor-account connections authorize the hosted deployment's service
@@ -761,7 +751,8 @@ command prints a note when you pass it anyway.
 agent-sdk mcp oauth <connection> [--dir .] [--store] [--slug <slug>] [--team <id>]
 ```
 
-`<connection>` is the `agent/mcp-connections/<connection>.ts` basename.
+`<connection>` is the basename under `agent/mcp-connections/` or
+`agent/host-connections/`.
 `--slug` defaults to the `--dir` basename. `--team` defaults to the
 signed-in account's team. You need `agent-sdk login` (or `--api-key`)
 before `--store`.
@@ -945,9 +936,9 @@ These environment variables affect the CLI and its channel packs.
 | Variable | Meaning |
 | --- | --- |
 | `CURSOR_API_KEY` | Cursor credential. It takes precedence over the stored login. |
-| `CURSOR_API_BASE_URL` | Backend used by login, account, deployment, and event-relay RPCs in non-production environments. |
-| `CURSOR_BACKEND_URL` | Backend used by the Cursor SDK harness in non-production environments. |
-| `AGENT_SERVE_CONFIG_DIR` | Directory for stored credentials and update-check state. The default is `~/.config/agent-serve`. |
+| `CURSOR_API_BASE_URL` | Backend used by login, account, deployment, and event-relay RPCs. |
+| `CURSOR_BACKEND_URL` | Backend used by the Cursor SDK harness. |
+| `AGENT_SERVE_CONFIG_DIR` | Directory for stored credentials and update-check state. Defaults to the CLI config directory under `~/.config`. |
 | `AGENT_SERVE_NO_UPDATE_CHECK` / `NO_UPDATE_NOTIFIER` | Disable the automatic published-version check when set to a non-empty value other than `0`. |
 | `CI` | Disable the automatic published-version check when set. |
 | `GITHUB_WEBHOOK_SECRET` | Default signing secret for GitHub forwarding and replay. |

package/docs/reference/connections.md

@@ -12,6 +12,11 @@ from `@cursor/july/connections`, and the transport comes in
 four shapes: remote HTTP, local stdio, the signed-in Cursor account's
 connectors, and peer agents on the same host.
 
+Put a server in `agent/host-connections/` when host tools should call it
+and the model should not. Same `defineConnection` shape. `agent-sdk mcp
+oauth` still works. The playground and the turn's MCP servers never see
+those files.
+
 ## Remote MCP server
 
 Point an MCP connection at a remote server with a URL.
@@ -30,7 +35,7 @@ Tokens come from env vars. Never hardcode them in the file.
 ## Host MCP OAuth
 
 For servers that speak OAuth, set `oauth: true` and authorize with the
-CLI. Tokens live in `~/.config/agent-serve/mcp-auth.json`. `--store`
+CLI. Tokens live in `mcp-auth.json` under the CLI config directory. `--store`
 copies them onto the hosted deployment as `MCP_OAUTH_<NAME>_*` secrets.
 
 ```ts
@@ -48,17 +53,15 @@ agent-sdk mcp oauth inventory --store   # also upsert deployment secrets
 Full walkthrough: [Host MCP OAuth](../guides/mcp-oauth.md). Companion
 skill: [`skills/mcp-auth/SKILL.md`](../../skills/mcp-auth/SKILL.md).
 
-Set `hostOnly: true` only when host tools should call the server and the
-model should not. Playground chat will not see those tools. Account MCP
-(`cursorAccount: true`) is the right choice for connectors already linked
-in the Cursor dashboard. Omit `servers` (or pass `"*"`) to forward every
-connected connector. If the model should call those tools by name on
-local turns, set `advertiseTools: true`.
+Account MCP (`cursorAccount: true`) is the right choice for connectors
+already linked in the Cursor dashboard. Omit `servers` (or pass `"*"`)
+to forward every connected connector. If the model should call those
+tools by name on local turns, set `advertiseTools: true`.
 
 ## Per-session auth (`auth`)
 
 For http/sse connections whose credential depends on **who the session is
-for** — a multi-tenant agent asserting the tenant it is acting for —
+for** (a multi-tenant agent asserting the tenant it is acting for),
 declare an `auth` callback instead of static headers. It runs host-side
 at turn-build time with the session's `SessionInfo` and returns headers
 merged over the static ones:
@@ -73,16 +76,16 @@ export default defineConnection({
 });
 ```
 
-The callback is evaluated on **every local turn** — reminder fires and
-post-restart follow-ups included — so the identity always comes from the
+The callback is evaluated on **every local turn**, including reminder
+fires and post-restart follow-ups, so the identity always comes from the
 session itself, never from state parked in memory. The model never sees a
 tenant parameter and can never choose the tenant. A callback that throws
 fails the turn: a turn never silently runs without the connection's
 identity. Local runtime only; cloud turns are refused. `host.mcp` calls
 from server tools keep the static headers only. Not combinable with
-`oauth: true` — the host OAuth provider owns the Authorization header.
+`oauth: true`; the host OAuth provider owns the Authorization header.
 
-Derive the identity from durable session facts — `session.auth`,
+Derive the identity from durable session facts: `session.auth`,
 `session.id`, or your channel's own session state. Do **not** key it off
 `session.continuationKey`: the HTTP channel rotates the continuation key
 after every accepted follow-up, so a tenant mapping keyed on it silently
@@ -93,14 +96,9 @@ design are the exception.)
 per-operation clients with the evaluated headers. Attached connections
 ride the turn's SDK `mcpServers`, passed on **every send** rather than
 pinned on the cached per-session agent handle, so a rotated credential is
-live on the very next turn. The cost: when any attached connection has
-`auth`, *all* of the agent's attached connections are configured per
-send — the harness opens fresh MCP clients for them on each turn, so a
-stdio (`command`) server respawns per turn and loses any in-process
-state; keep stateful stdio servers out of agents that attach an auth'd
-connection (or advertise the auth'd connection instead). Workspace
-prewarm has no session, so it omits auth'd connections rather than
-attaching them without an identity.
+live on the very next turn. A stateful stdio server cannot share a
+process with an attached `auth` connection. Advertise the auth
+connection instead.
 
 ## Advertise a connection's tools by name (`advertiseTools`) {#advertise-tools}
 
@@ -118,7 +116,7 @@ export default defineConnection({
 
 A listing failure, invalid tool name, or name collision fails the turn.
 Advertised tools follow the same runtime support as server tools. They cannot
-be combined with `hostOnly` or called through the direct tool API.
+be called through the direct tool API.
 
 In a dry-run session, MCP tools marked read-only run normally. Tools marked
 as writes are stubbed. Tools without effect annotations are unavailable.
@@ -226,13 +224,14 @@ Unknown slugs and self-references fail `serve` at startup. Resolution
 (loopback versus `--public-url`), loop caveats, and the delegation model
 are in the [Agent-to-agent guide](../guides/agent-to-agent.md).
 
-## Every MCP connection is available in three places
+## Every model-visible MCP connection is available in three places
 
-One authored MCP connection serves three consumers.
+A file under `agent/mcp-connections/` serves three consumers. Host
+connections skip the first one.
 
 1. **Cursor agent:** Attached connections ride SDK `mcpServers` behind
    harness MCP meta-tools. Set `advertiseTools: true` so local turns see
-   named tools. `hostOnly` keeps the connection off the model.
+   named tools.
 2. **Server tools:** Deterministic host code composes MCP calls
    through `ctx.host.mcp`:
 
@@ -267,7 +266,7 @@ lazily on first use.
 
 Continue with these pages:
 
-- [Host MCP OAuth](../guides/mcp-oauth.md): `mcp oauth`, `--store`, `hostOnly`
+- [Host MCP OAuth](../guides/mcp-oauth.md): `mcp oauth`, `--store`
 - [Agent-to-agent](../guides/agent-to-agent.md): peers in depth
 - [Tools](./tools.md): authored tools that wrap MCP connections
 - [Webhooks](../guides/webhooks.md): calling MCP connections from handlers

package/docs/reference/hooks.md

@@ -6,11 +6,11 @@ description: "Observe-only subscribers to the session event stream: audit logs,
 # Hooks
 
 A hook is an observe-only subscriber to the session event stream. Hooks
-run after each event is recorded and fanned out (file persistence flushes
-in the background). That makes them the home for audit logging, metrics,
-mirroring transcripts into your own store, and maintaining derived state.
-Handler errors are logged and never fatal. A hook can't modify events,
-inject context into the next turn, or block a turn.
+run after each event is recorded. They cannot change the event or the
+turn. That makes them the home for audit logging, metrics, mirroring
+transcripts into your own store, and maintaining derived state. Handler
+errors are logged and never fatal. A hook can't inject context into the
+next turn or block a turn.
 
 For deterministic context composition before the model runs, use the
 host path that already owns the wake: channel handlers (fetch, `callTool`,
@@ -38,7 +38,7 @@ export default defineHook({
 });
 ```
 
-Keys are event types (the full list is in the
+Keys are event types (see the
 [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`:
@@ -71,9 +71,8 @@ For GitHub merge-box checks and sticky PR banners, use
 `githubChannel({ progress: { commitStatus, banner } })` from
 `@cursor/july/channels/github`. That is the supported Autofix-style
 path. See [GitHub: Show PR progress](../guides/github.md#show-pr-progress).
-Override channel `events` only when the lifecycle is custom (for
-example [Approval Buddy](../example-agents/approval-buddy.md)'s
-never-red status from tool output). Do not use `defineHook` for those
+Override channel `events` only when the lifecycle is custom, such as
+never-red status from tool output. Do not use `defineHook` for those
 writes.
 
 ## Patterns
@@ -84,20 +83,16 @@ Usage metering: subscribe to `turn.completed` and forward
 Failure alerting: `turn.failed` carries the message, and
 `ctx.session.id` points at the trace.
 
-Derived state: `agent.bound` fires when the Cursor SDK agent id is known
-(`bc-…` on cloud). A PR agent can record PR → agent id from it in a
-hook with `ctx.host.kv`, so later webhook wakes resume the same cloud
-conversation. Prefer `ctx.host.kv` or `ctx.host.files` for ids that
-must survive hosted replace. `stateRoot` resets on replace.
+Derived state: persist ids that must survive hosted replace with
+`ctx.host.kv` or `ctx.host.files`. `stateRoot` resets on replace.
 
-Transcript export: subscribe to `"*"` and append to your own store. The
-NDJSON envelope is already ordered and replayable.
+Transcript export: subscribe to `"*"` and append to your own store.
 
 ## What's next
 
 Continue with these pages:
 
-- [Sessions and streaming](./sessions.md): every event a hook can see
+- [Sessions and streaming](./sessions.md): the event vocabulary hooks observe
 - [OpenTelemetry](../guides/opentelemetry.md): OTLP traces and metrics
   from the same event stream
 - [Deployment](../deployment.md#observability): runtime logs and export