@cursor/july 0.1.93 → 0.1.94

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.
@@ -48,12 +53,10 @@ 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`)
 
@@ -113,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.
@@ -221,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`:
 
@@ -262,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

@@ -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

package/docs/reference/http-api.md

@@ -138,6 +138,12 @@ while a turn runs). Agent-execution tools are rejected with `400`, and
 unknown tools with `404` and the list of available names. For the
 semantics, see [Tools](./tools.md#call-a-tool-without-a-model-turn).
 
+An optional `"continuationToken"` (`<channelId>:<key>`, as
+`/v1/sessions` lists it; mutually exclusive with `sessionId`) addresses
+the session by continuation token instead; malformed tokens are
+rejected with `400 invalid_continuation_token`. For the semantics, see
+[Tools](./tools.md#call-a-tool-without-a-model-turn).
+
 ## Discovery
 
 These read-only routes describe the running agent.
@@ -145,6 +151,8 @@ These read-only routes describe the running agent.
 | Route                  | What it does                                                                                                                                                                             |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `GET /v1/info`         | The discovered surface: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, A/B experiments, diagnostics |
+| `GET /v1/tools`        | The live tool catalog: authored server tools plus advertised MCP passthroughs under model-facing names, as light `{ name, title?, source? }` entries. `session` / `continuationToken` query parameters bind the listing to a session identity (advertised inventories can be tenant-scoped); a connection whose listing fails is skipped and reported in `connectionErrors` |
+| `GET /v1/tools/:name`  | One catalog tool's full description: description, execution, `needsApproval`, `effect`, input and output schemas, source connection. Same session binding as the listing; unknown names get `404` with the available names |
 | `GET /v1/health`       | Per-agent liveness, no auth                                                                                                                                                              |
 | `GET /v1/logs?after=N` | Recent server log lines, with a polling cursor                                                                                                                                           |
 | `GET /v1/abs`          | [Live A/B metrics](../ab.md): per-session assignments and aggregate arm totals                                                                                                           |

package/docs/reference/project-layout.md

@@ -17,7 +17,8 @@ experiments can override their file-derived name.
 | Path | Resolves to |
 | --- | --- |
 | `agent/tools/approve_pr.ts` | tool `approve_pr` |
-| `agent/mcp-connections/linear.ts` | MCP connection `linear` |
+| `agent/mcp-connections/linear.ts` | MCP connection `linear` (model + host) |
+| `agent/host-connections/anytool.ts` | Host MCP connection `anytool` (host + `mcp oauth` only) |
 | `agent/skills/pr-review.md` | skill `pr-review` |
 | `agent/subagents/reviewer/` | subagent `reviewer` |
 | `agent/channels/drive.ts` | channel `drive`, routes under `/v1/channels/drive` |
@@ -45,6 +46,8 @@ my-agent/
 │   │   └── pr-review.md       # on-demand procedures (SKILL.md convention)
 │   ├── mcp-connections/
 │   │   └── linear.ts          # tools from external MCP servers
+│   ├── host-connections/
+│   │   └── anytool.ts         # privileged MCP, host tools only
 │   └── channels/
 │       └── github.ts          # messages and external events
 └── evals/
@@ -66,6 +69,7 @@ Each path maps to a capability and a reference page.
 | `agent/tools/<name>.ts` | One typed tool; filename = tool name. `execution: "server"` (in-process, default) or `"agent"` (a script that runs where the agent runs) | [Tools](./tools.md) |
 | `agent/skills/*` | SKILL.md-convention procedures, loaded on demand | [Skills](./skills.md) |
 | `agent/mcp-connections/<name>.ts` | MCP servers, available to the model, to server tools (`ctx.host.mcp`), and to channel/schedule handlers (`args.host.mcp`) | [MCP connections](./connections.md) |
+| `agent/host-connections/<name>.ts` | Privileged MCP servers for `ctx.host.mcp` and `mcp oauth`. The model never sees them. | [MCP connections](./connections.md) |
 | `agent/subagents/<id>/` | Child agent directory; `description` required | [Subagents](./subagents.md) |
 | `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) |

package/docs/reference/subagents.md

@@ -41,8 +41,8 @@ different one.
 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/`.
+`host-connections/`, `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

@@ -187,8 +187,9 @@ passthrough server tools from the connection's live `listTools` on every
 local turn. See
 [MCP Connections](connections.md#advertise-tools).
 Advertised tools ride the same execution path as authored server tools,
-but cannot be invoked via
-[direct tool calls](#call-a-tool-without-a-model-turn).
+and [direct tool calls](#call-a-tool-without-a-model-turn) address them
+by the same model-facing names: the call's session identity resolves the
+advertised listing when the authored lookup misses.
 
 ## Gate a tool on human approval
 
@@ -262,7 +263,22 @@ when the call returns. Pass a `sessionId` (a body field over
 HTTP, `--session` on the CLI, `options.sessionId` programmatically) to
 run inside an existing session instead: the tool sees that session's
 workspace, and the call is recorded on the session's event stream.
-Session-bound calls return `409 session_busy` while a turn runs.
+Session-bound calls return `409 session_busy` while a turn runs. When the
+session's harness cwd cannot be materialized, a read-effect call runs
+in a scratch workspace instead and the outcome carries
+`scratchWorkspace: true`; a write-effect call fails with
+`workspace_unavailable`.
+
+A session can also be addressed by its continuation token: an optional
+`continuationToken` (`<channelId>:<key>`, as `/v1/sessions` lists it;
+mutually exclusive with `sessionId`). A token that maps to a live
+session behaves exactly like passing that session's id — same ownership
+check, same `409 session_busy`, same event recording. A token with no
+session behind it runs the call scratch-bound with the token's channel
+id and continuation key as the call's session identity, so a deployment
+whose tools resolve state from the continuation key can serve it with
+no live session. Malformed tokens are rejected with
+`400 invalid_continuation_token`.
 
 The error semantics match the model path. Unknown tools are rejected
 with the available names, agent-execution tools cannot be called on the

package/docs/templates/pr-autofixer.md

@@ -103,9 +103,10 @@ fixture replay.
 
 ## Slack
 
-`agent/channels/slack.ts` uses your signed-in Cursor account. Mention
-the agent or DM it with a PR URL. Same `drive_pr` path as the
-playground. See [Slack](../guides/slack.md).
+`agent/channels/slack.ts` is a dedicated Socket Mode bot
+(`PR_AUTOFIXER_SLACK_*`). Mint it with `agent-sdk slack create`, then
+mention the bot or DM it with a PR URL.
+Same `drive_pr` path as the playground. See [Slack](../guides/slack.md).
 
 ## Evals
 

package/docs/templates/security-reviewer.md

@@ -9,9 +9,8 @@ This agent reads a pull request diff and posts one review comment. It
 reports exploitable bugs: injection, authz bypass, secret leaks, SSRF,
 RCE. Style nits stay out.
 
-The factory [Security Reviewer](../example-agents/security-reviewer.md)
-runs a staged pipeline with parallel workers. This template is one
-model turn.
+The in-repo factory Security Reviewer runs a staged pipeline with
+parallel workers. This template is one model turn.
 
 ## Scaffold
 

package/docs/troubleshooting.md

@@ -32,7 +32,7 @@ not on `PATH`, use `npx @cursor/july`.
 | Built-in file reads and greps fail; the turn retries for a long time | Run under Node 22.13+ (or `tsx`), never Bun. Look for `NGHTTP2_FRAME_SIZE_ERROR` in logs. |
 | The turn fails immediately with an API-key error | Sign in with `agent-sdk login`, or set `CURSOR_API_KEY`. Discovery, `info`, `call`, and serve bring-up work without a key; model turns need one. |
 | Replies quote rules or `AGENTS.md` from outside your agent project | The session workspace inherited parent-folder config. Nested git checkouts default `local.cwd` to a per-project cache directory under `~/.cache`. Point `defineAgent({ local: { cwd } })` at a checkout only when the agent should inherit that tree, or set `--state-root` to a clean directory (for example under `/tmp`). |
-| Yellow box shows Datadog/Linear tools, but the model lists `GetDynamicTools` / IDE `cursor` tools and never calls them | Attached MCP sits behind harness meta-tools, or `hostOnly` hid the connection, or the harness cwd is still inside another checkout. Set `advertiseTools: true` for named tools on local turns. Check `GET /v1/info` `local.cwd` and `connections[].advertiseTools`. |
+| Yellow box shows Datadog/Linear tools, but the model lists `GetDynamicTools` / IDE `cursor` tools and never calls them | Attached MCP sits behind harness meta-tools, or the harness cwd is still inside another checkout. Set `advertiseTools: true` for named tools on local turns. Check `GET /v1/info` `local.cwd` and `connections[].advertiseTools`. |
 | Server tools, skills, or workspace seed files never appear | Server tools and sandbox seeds apply on the local runtime (cloud server tools need `--public-url` / `--cloud-tools-url`). Skills reach cloud through the Agent Store when hosting or a personal `CURSOR_API_KEY` is available; otherwise only skills already in the cloud repo. `validate` warns when this combination is present. |
 | `validate` and `run` succeed, but typecheck fails in CI | The CLI runs TypeScript with type-stripping only. Keep tool `execute` return types as object literals or `type` aliases, not `interface` types. |
 | Login works, but turns are rejected when using custom API hosts | Point login and model traffic at the same host (`CURSOR_API_BASE_URL` and `CURSOR_BACKEND_URL`). A key from one host is rejected by the other. |
@@ -71,7 +71,7 @@ not on `PATH`, use `npx @cursor/july`.
 | --- | --- |
 | `must be defineConnection({ url, oauth: true })` | The connection file needs `oauth: true`, or you passed the wrong connection name to `agent-sdk mcp oauth`. |
 | Local auth works; hosted calls unauthorized | Run `agent-sdk mcp oauth <name> --store`, confirm names with `agent-sdk secrets list <slug>`, then redeploy. |
-| Model asks for `mcp_auth` or IDE MCP for a privileged server | That connection is `hostOnly`. Call it from a host tool via `ctx.host.mcp`, and update instructions. |
+| Model asks for `mcp_auth` or IDE MCP for a connector it already has | Attached MCP is behind meta-tools. Set `advertiseTools: true` for named tools on local turns, or call it from a host tool via `ctx.host.mcp`. |
 
 See [Host MCP OAuth](./guides/mcp-oauth.md) and
 [`skills/mcp-auth/SKILL.md`](../skills/mcp-auth/SKILL.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.93",
+  "version": "0.1.94",
   "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": {
@@ -120,6 +120,13 @@
       "import": "./dist/hooks.js",
       "default": "./dist/hooks.js"
     },
+    "./client": {
+      "anysphere-source": "./src/client.ts",
+      "bun": "./dist/client.js",
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js",
+      "default": "./dist/client.js"
+    },
     "./memory": {
       "anysphere-source": "./src/memory.ts",
       "types": "./dist/memory.d.ts",
@@ -255,13 +262,13 @@
     "@slack/socket-mode": "^2.0.7",
     "@slack/web-api": "^7.18.0",
     "croner": "^8.0.1",
+    "esbuild": "^0.25.0",
     "javascript-time-ago": "^2.6.4",
     "js-yaml": "4.1.0",
     "ms": "^2.1.3",
     "proper-lockfile": "^4.1.2",
     "slackify-markdown": "^5.0.0",
     "tsx": "^4.0.0",
-    "esbuild": "^0.25.0",
     "zod": "^3.25.0",
     "zod-to-json-schema": "^3.24.5"
   },

package/skills/create-agent/SKILL.md

@@ -64,8 +64,8 @@ questions, concrete options, the recommended option listed first and labeled
 | --- | --- | --- |
 | **Runtime** | `local` (default) · `cloud` | Local runs on this machine. Cloud runs on a Cursor cloud agent and needs `cloud.repos`. Server tools and skills work on both. Tool approvals and sandbox seeds are local only. Recommend local unless the purpose needs a cloud checkout. |
 | **Model** | `grok-4.5` with `effort=high`, `fast=true` (default) · Other model id | Effort and fast are params, not id suffixes: `{ id: "grok-4.5", params: [{ id: "effort", value: "high" }, { id: "fast", value: "true" }] }` — the SDK rejects suffix-style ids. |
-| **Channels** (multi) | playground + HTTP API only (always mounted) · Slack · GitHub webhooks · custom webhook · schedule (cron) | Slack has two connections: the Cursor-hosted connection (`cursorAccount: true` — zero Slack admin, recommended default) and a dedicated Socket Mode app (own bot user + one app/token pair per agent; needed for channel watching or approval buttons). When Slack is picked, resolve the connection with the Step 0 gate in `setup-slack/SKILL.md` — either fold its AskQuestion into this round or ask it before channel setup; default to Cursor-hosted when you cannot ask. GitHub verifies `X-Hub-Signature-256` when a secret is set. Discord/Teams packs do not exist yet — offer custom webhook instead. |
-| **MCP connections** (multi) | none · remote server (URL + header auth) · local stdio server · Cursor account connectors · Other | One file per server under `agent/mcp-connections/`; filename = server name. Do not name an account connection `cursor.ts` (collides with the IDE `cursor` namespace); use `account.ts`. Tokens via env vars, never hardcoded. Connections serve the model and host code (`ctx.host.mcp`). If the model should call them by name on local turns, set `advertiseTools: true`. Set `hostOnly: true` only when host tools call the server and the playground must not. |
+| **Channels** (multi) | playground + HTTP API only (always mounted) · Slack · GitHub webhooks · custom webhook · schedule (cron) | Slack is a dedicated Socket Mode app (`agent-sdk slack create` — own bot user + one app/token pair per agent). When Slack is picked, follow `setup-slack/SKILL.md`. GitHub verifies `X-Hub-Signature-256` when a secret is set. Discord/Teams packs do not exist yet — offer custom webhook instead. |
+| **MCP connections** (multi) | none · remote server (URL + header auth) · local stdio server · Cursor account connectors · Other | One file per server under `agent/mcp-connections/`; filename = server name. Do not name an account connection `cursor.ts` (collides with the IDE `cursor` namespace); use `account.ts`. Tokens via env vars, never hardcoded. Connections serve the model and host code (`ctx.host.mcp`). If the model should call them by name on local turns, set `advertiseTools: true`. Privileged servers the model must not see go in `agent/host-connections/` instead. |
 | **Capabilities** (multi) | server tools · agent tools (scripts) · skills · subagents · hooks · sandbox seed files · tool approvals (HITL) · evals (recommend) | Always recommend at least one smoke eval. |
 
 Close the round with a one-screen plan — chosen options plus the file tree you
@@ -80,7 +80,7 @@ inventing:
 
 | Purpose looks like | Proven shape |
 | --- | --- |
-| Slack chat assistant | minimal `slackChannel({ cursorAccount: true, agentName: "…" })` with suggested prompts; dedicated Socket Mode app only when the Step 0 gate picked it |
+| Slack chat assistant | `slackChannel()` with suggested prompts; run `agent-sdk slack create` for the bot and tokens |
 | PR review with host-prepared evidence | channel `callTool` prep into a trimmed workspace `pr/` tree |
 | GitHub-webhook automation | `githubChannel()` hooks, per-PR debounce, replay fixtures |
 | Domain assistant over live APIs / MCP | server + agent tools, a stdio MCP connection, a skill, a schedule |
@@ -105,7 +105,6 @@ Defaults that make first cuts good:
   multi-line strings).
 - **Env prefix** for Slack tokens = upper-snake slug (`my-agent` →
   `MY_AGENT_SLACK_*`); `agent-sdk slack create` derives it for you.
-  Dedicated-app path only — the Cursor-hosted connection has no tokens.
 - **Host prep beats model wandering — for evidence, not judgment.** When the
   purpose has a deterministic setup step (fetch a PR, seed files), do it in
   the channel handler via `callTool` / `workspaceFiles` rather than
@@ -160,11 +159,7 @@ plan:
    with the real tools.
 4. Add the chosen `channels/`, `mcp-connections/`, `skills/`, `subagents/<id>/`
    (needs `description`), `schedules/`, `hooks/`, `sandbox/workspace/`. For
-   Slack, follow the connection decided in the interview: Cursor-hosted is a
-   short hand-written `agent/channels/slack.ts`
-   (`slackChannel({ cursorAccount: true, agentName: "<Name>" })` — no
-   tokens, no manifests); for a dedicated Socket Mode app do not hand-write
-   the channel — `agent-sdk slack create --dir ./<slug> --name "<Name>"`
+   Slack, do not hand-write the channel — `agent-sdk slack create --dir ./<slug> --name "<Name>"`
    opens the dashboard wizard (env prefix from the directory name);
    for a Slack app they own at api.slack.com, `agent-sdk slack init --manual --dir ./<slug> --name "<Name>"`;
    customize `agent/channels/slack.ts` afterwards (e.g. `suggestedPrompts`).
@@ -225,10 +220,8 @@ Each surface beyond the playground has a human gate — drive the user through
 it, verify with doctor commands, and smoke-test before declaring victory.
 
 - **Slack** — follow `packages/agent-serve/skills/setup-slack/SKILL.md` end
-  to end, starting from its Step 0 connection gate. Cursor-hosted: sign in
-  (`agent-sdk login` / `CURSOR_API_KEY`) → serve → `@Cursor <AgentName>`
-  smoke. Dedicated app: init → human creates apps → doctor → `@mention`
-  smoke.
+  to end: `slack create` → doctor → `@mention` smoke. Manual path only
+  when they own the Slack app at api.slack.com.
 - **GitHub** — follow `packages/agent-serve/skills/github/SKILL.md`
   (fixtures / replay / forward / `--cursor-events`).
 - **Custom webhook** — `POST /<slug>/v1/channels/<id>/<route>`. Default

package/skills/debug/SKILL.md

@@ -51,7 +51,7 @@ curl -sN 'localhost:3000/<slug>/v1/session/<id>/stream?startIndex=0' | head -50
 | `gh webhook forward` / `agent-sdk github forward` deliveries all 401 — but hook creation succeeded | `GITHUB_TOKEN`/`GH_TOKEN` in the env. The relay authenticates with the gh CLI login and rejects env tokens. `GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward ...` |
 | `Hook already exists` starting a forwarder | GitHub allows one forwarder per repo. Use one `github forward --dir <parent>` (it fans out to every matching channel) instead of N processes; kill stale forwarders. |
 | Agent's answers reference monorepo rules / AGENTS.md it shouldn't know | Session workspace sits inside another git checkout, so the harness loaded ancestor config. Nested projects default `local.cwd` to `~/.cache/agent-serve/<dir>`. Point cwd at a checkout only when the agent should inherit that tree. |
-| Yellow box lists Datadog/Linear tools; model recites `GetDynamicTools` / IDE `cursor` tools and never calls MCP | Attached MCP is behind meta-tools, or `hostOnly` hid it, or cwd still leaked IDE MCP. Set `advertiseTools: true` for named tools on local turns. Confirm `GET /v1/info` `local.cwd` and `connections[].advertiseTools`. |
+| Yellow box lists Datadog/Linear tools; model recites `GetDynamicTools` / IDE `cursor` tools and never calls MCP | Attached MCP is behind meta-tools, or cwd still leaked IDE MCP. Set `advertiseTools: true` for named tools on local turns. Confirm `GET /v1/info` `local.cwd` and `connections[].advertiseTools`. |
 | Port 3000/5273 in use; stray processes after crashes | `lsof -iTCP:3000 -sTCP:LISTEN`, kill the pids; also check companion processes (e.g. vite). |
 | Pending tool approval vanished after server restart | By design: parked SDK calls don't survive host restart; they resolve as interrupted. Re-run the turn. |
 | Schedule / reminder never fires under `--dev` | Dev never auto-fires. `POST /<slug>/v1/dev/schedules/<id>` or `POST /<slug>/v1/dev/reminders/<id>` (list at `GET /v1/dev/reminders`). |
@@ -61,9 +61,7 @@ curl -sN 'localhost:3000/<slug>/v1/session/<id>/stream?startIndex=0' | head -50
 | `403` on stream/follow-up | Caller principal ≠ session owner. In dev, create and inspect with the same auth; beyond loopback pass `--bearer-token` and send it. |
 | Works on localhost, 401/blocked through a tunnel or LAN | Default `localDevStrict()` auth only admits direct loopback, **rejects proxy-forwarding headers** (`X-Forwarded-For`, ...), and requires a loopback `Host`. Use `--bearer-token <secret>` (or authored `bearerAuth`) — `--allow-anonymous` only for trusted-network demos (and never with Cursor account MCP connections). |
 | Channel route won't compile: body/query schema type error | `GET` requires a Zod `querySchema`, `POST`/`PUT`/`PATCH` a Zod `bodySchema` — plain JSON Schema objects don't type-check. Use `z.object({})` / `z.unknown()` for open surfaces. Empty POST bodies are coerced to `{}` before validation. |
-| Slack channel prints `channel idle ... missing credentials` | Expected: tokens absent (dedicated-app path). Multi-agent needs `<PREFIX>_SLACK_BOT_TOKEN` + `<PREFIX>_SLACK_APP_TOKEN` per agent. `agent-sdk slack doctor --prefix <PREFIX>`. |
-| `serve` fails: `Slack channels using the Cursor account connection ... not signed in to Cursor` | Cursor-hosted Slack (`cursorAccount: true`) needs a signed-in host: `agent-sdk login` or `CURSOR_API_KEY`. No Slack tokens exist on this path — `slack doctor` doesn't apply. |
-| `@Cursor <name>` in Slack gets Cursor's normal agent, not yours | Agent name mismatch or host not relaying. Names are single-token and matched case-insensitively; confirm the serve log `cursor-slack: relaying Slack for <AgentName>` and that the workspace's Cursor Slack integration is linked to the signed-in account. |
+| Slack channel prints `channel idle ... missing credentials` | Expected: tokens absent. Multi-agent needs `<PREFIX>_SLACK_BOT_TOKEN` + `<PREFIX>_SLACK_APP_TOKEN` per agent. `agent-sdk slack doctor --prefix <PREFIX>`. |
 | Turn fails immediately with an API-key error | Model turns need `CURSOR_API_KEY`; everything structural (validate/info/call/serve bring-up) doesn't. |
 | Server tools / skills / sandbox silently absent | Runtime is `cloud` — those are local-only. `validate` prints exactly this warning; read it. |
 | `validate` clean, `run` works, CI typecheck fails | tsx never typechecked it. See invariant 3 in `framework-map/SKILL.md` (JSON-shaped tool returns; `type` not `interface`). |

package/skills/evals/SKILL.md

@@ -181,7 +181,7 @@ export default defineEvalConfig({
 Drop `agent/playground/evals.tsx` exporting `agentName` (must match
 `defineAgent({ name })`) and
 `default: { RunSummary?, CaseMetrics?, CaseExtras? }`. The playground
-loads these via Vite glob (`examples/*` and `factory/*`). Without a
+loads these via Vite glob (`factory/*`). Without a
 module, cases still show default `t.metric` badges.
 
 ## What good cases assert

package/skills/framework-map/SKILL.md

@@ -45,7 +45,7 @@ pnpm exec tsx src/bin/agent-serve.ts <cmd> ...
    `~/.cache/agent-serve/<dir>` so ancestor `AGENTS.md` / `.cursor` / IDE
    MCP do not leak into playground turns. Set cwd at a checkout only when
    the agent must inherit that tree. Attached MCP is invisible by name
-   until `advertiseTools: true`. `hostOnly` hides it from the model.
+   until `advertiseTools: true`.
 5. **A model turn needs `CURSOR_API_KEY`.** Everything structural
    (`validate`, `info`, `call`, `serve` bring-up) works without one.
 
@@ -60,7 +60,8 @@ path live under README "Folder structure".
 | `agent/instructions.md` | Always-on system prompt (required; `.ts`/dir forms exist) |
 | `agent/tools/<name>.ts` | One typed tool; filename = tool name. `execution: "server"` (in-process, default) or `"agent"` (script that runs where the agent runs) |
 | `agent/skills/*` | SKILL.md-convention procedures, loaded on demand |
-| `agent/mcp-connections/<name>.ts` | MCP servers. Do not name an account connection `cursor.ts`. `advertiseTools: true` for named tools on local turns; `hostOnly` keeps them off the model. `{ tools }` authors TypeScript the Agent SDK packages as stdio MCP. |
+| `agent/mcp-connections/<name>.ts` | MCP servers. Do not name an account connection `cursor.ts`. `advertiseTools: true` for named tools on local turns. `{ tools }` authors TypeScript the Agent SDK packages as stdio MCP. |
+| `agent/host-connections/<name>.ts` | Privileged MCP for `ctx.host.mcp` and `mcp oauth`. The model never sees them. |
 | `agent/subagents/<id>/` | Child agent dir (`description` required; per-subagent tools/skills/MCP connections ignored for now) |
 | `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` / `github.ts` use the platform packs |
 | `agent/hooks/*.ts` | Observe-only event subscribers (never fatal) |

package/skills/mcp-auth/SKILL.md

@@ -3,7 +3,7 @@ name: agentsdk-mcp-auth
 description: >-
   Authorize host MCP OAuth for defineConnection({ url, oauth: true }):
   agent-sdk mcp oauth, local mcp-auth.json, --store deployment secrets,
-  hostOnly, advertiseTools, and egress. Read when wiring or debugging MCP auth.
+  advertiseTools, and egress. Read when wiring or debugging MCP auth.
 ---
 
 # Host MCP OAuth (mcp auth)
@@ -29,15 +29,13 @@ Docs: `docs/guides/mcp-oauth.md`, `docs/reference/connections.md`,
 | Remote URL that speaks OAuth; host must hold tokens | `defineConnection({ url, oauth: true })` + this skill |
 | Static bearer / API key | `headers` / env on a plain `{ url }` connection |
 
-Set `hostOnly: true` only when host tools / channel handlers should call
-the server and the model should not (admin APIs, privileged writes).
-Playground chat will not see those tools. For connectors the model should
-call on local turns (Linear, Datadog, account MCP), omit `hostOnly` and
-set `advertiseTools: true`.
+For connectors the model should call by name on local turns (Linear,
+Datadog, account MCP), set `advertiseTools: true`. Host tools can still
+call the same connection through `ctx.host.mcp`.
 
 ## Goal checklist
 
-- [ ] `agent/mcp-connections/<name>.ts` with `url` + `oauth: true` (`hostOnly` if privileged; `advertiseTools` if the model should call it)
+- [ ] `agent/mcp-connections/<name>.ts` with `url` + `oauth: true` (`advertiseTools` if the model should call it by name). Use `agent/host-connections/<name>.ts` when host tools should call it and the model should not.
 - [ ] `hosting.secretNames` lists `MCP_OAUTH_<NAME>_{ACCESS_TOKEN,REFRESH_TOKEN,CLIENT_ID}` when you will `--store`
 - [ ] Hosted engines that reach non-bootstrap hosts declare `hosting.egressDomains`
 - [ ] Local: `agent-sdk mcp oauth <name>` succeeds
@@ -52,8 +50,7 @@ import { defineConnection } from "@cursor/july/connections";
 export default defineConnection({
   url: "https://mcp.example.com/inventory",
   oauth: true,
-  hostOnly: true,
-  description: "Privileged inventory MCP; call via ctx.host.mcp only.",
+  description: "Inventory MCP.",
 });
 ```
 
@@ -81,8 +78,8 @@ await ctx.host.mcp.callTool("inventory", "list_warehouses", {
 });
 ```
 
-Update instructions so the model does not hunt IDE MCP namespaces or
-`mcp_auth` for `hostOnly` servers.
+Set `advertiseTools: true` when the model should call the server by name
+instead of through MCP meta-tools.
 
 ## Phase 1 — Local authorize (agent + human)
 
@@ -129,10 +126,10 @@ redeploy completed, then exercise the same host tool once.
 | Symptom | Fix |
 | --- | --- |
 | `must be defineConnection({ url, oauth: true })` | Wrong connection name, or missing `oauth: true` |
-| `Unknown MCP connection` | Filename under `agent/mcp-connections/` must match CLI arg |
+| `Unknown MCP connection` | Filename under `agent/mcp-connections/` or `agent/host-connections/` must match CLI arg |
 | Callback hang | Free port 8787; finish browser flow on this machine |
 | Hosted 401 / unauthorized | `secrets list`; re-run `--store`; redeploy |
-| Model invents `mcp_auth` / IDE MCP | `hostOnly` hid it, or attached MCP is behind meta-tools. Use host tools for privileged servers. Set `advertiseTools: true` for named tools on local turns. |
+| Model invents `mcp_auth` / IDE MCP | Attached MCP is behind meta-tools. Set `advertiseTools: true` for named tools on local turns. |
 | Tokens ignored after URL edit | Expected; run `mcp oauth` again for the new resource URL |
 
 ## Don't