@cursor/july 0.1.92 → 0.1.94

package/docs/storage.md

@@ -7,15 +7,10 @@ description: "Point the Agent SDK's durable storage at a backend you own with de
 
 The Agent SDK owns durable storage for sessions, continuation tokens,
 reminders, playground eval history, and live A/B samples. It chooses the
-keys (under `agentkit/v1/`), when to read and write, and how to restore
-after restart.
+keys, when to read and write, and how to restore after restart.
 
-Keys have bounded length: caller-controlled segments (channel ids,
-continuation tokens) are URI-encoded, and any segment past 256 encoded
-bytes is replaced by its `sha256:…` digest — deterministically, so writes
-and lookups always agree. Backends can rely on this instead of imposing
-their own key-length caps (which would silently drop writes, since a
-throwing `put` is at-most-once).
+The Agent SDK owns key encoding. Backends must accept the keys they are
+given. Do not fail `put` to enforce a shorter cap.
 
 By default that storage lives under `--state-root` on local disk. Fine
 for one machine; it does not survive replacing the host.
@@ -23,8 +18,7 @@ for one machine; it does not survive replacing the host.
 To keep the same framework storage across hosts, plug in a key-value
 backend with `agent/storage.ts`. You provide `put` / `get` / `delete` /
 `list`. The optional `cas` group adds conditional writes (see
-[Conditional writes](#conditional-writes-the-cas-group)). The Agent SDK
-does the rest.
+[Conditional writes](#conditional-writes-the-cas-group)).
 
 ```ts
 // agent/storage.ts
@@ -44,15 +38,10 @@ export default defineStorage({
 });
 ```
 
-> [!NOTE]
-> Import paths here use `@cursor/july/storage`. On projects still
-> using `@anysphere/agent-serve`, swap the import. See
-> [Run the CLI](/#run-the-cli) for the full rename table.
-
 ## Which fields to provide
 
-Implement the small KV core — `put`/`get`/`delete`/`list` plus the `cas`
-group — and you get **full functionality**: eval-run and A/B history are
+Implement the small KV core (`put`/`get`/`delete`/`list` plus the `cas`
+group) and you get **full functionality**: eval-run and A/B history are
 derived over the core automatically. The dedicated `evals` / `abs` groups
 are backend-native optimizations, not required-or-lose-history hooks.
 
@@ -60,13 +49,13 @@ are backend-native optimizations, not required-or-lose-history hooks.
 | --- | --- | --- |
 | `put` | Yes | Write or update a value |
 | `cas` | Optional | Conditional writes; see [Conditional writes](#conditional-writes-the-cas-group) |
-| `get` | For restore | Look up one key (also: derived A/B snapshot backfill) |
-| `list` | For restore | Return entries under a prefix, in key order (also: derived eval-runs hydrate) |
-| `delete` | For cleanup | Remove a key (also: derived eval-runs pruning) |
+| `get` | For restore | Look up one key |
+| `list` | For restore | Return entries under a prefix, in key order |
+| `delete` | For cleanup | Remove a key |
 | `name` | No | Label surfaced on `GET /v1/info` diagnostics |
 | `policy` | No | Timing knobs; see [Policy](#policy) |
-| `evals` | No | Backend-native eval-runs table; derived over the core when omitted — see [Eval and A/B tables](#eval-and-a-b-tables) |
-| `abs` | No | Backend-native A/B metrics table; derived over the core when omitted — see [Eval and A/B tables](#eval-and-a-b-tables) |
+| `evals` | No | Backend-native eval-runs table; derived over the core when omitted. See [Eval and A/B tables](#eval-and-a-b-tables) |
+| `abs` | No | Backend-native A/B metrics table; derived over the core when omitted. See [Eval and A/B tables](#eval-and-a-b-tables) |
 
 A throwing `put` is logged and dropped. It never fails a turn. When
 resolving a missing continuation token, a throwing `get` fails the
@@ -80,30 +69,20 @@ values. Both are **optional optimizations**: when a group is not
 authored, `defineStorage` derives it over the KV core, so a backend that
 implements only the core loses nothing. Author a group only when the
 backend has a better native shape (a real database table, an analytics
-pipeline) — the built-in `fileKv` and `cursorHostedStorage` both do.
+pipeline). The built-in `fileKv` and `cursorHostedStorage` both do.
 
 `evals` keeps playground eval batches across restarts (`put`, `delete`,
-`list` over run snapshots keyed by `runId`). The Agent SDK upserts a
-snapshot as a batch starts, progresses, and finishes, prunes runs past
-the playground history window, and lists everything back at serve start.
-**Derived form**: one key per run under
-`agentkit/v1/{agent}/eval-runs/{runId}` — needs core `put` + `delete` +
-`list`. Only a core missing `delete` or `list` leaves eval history in
-process memory (cleared on restart). See
-[Evals](./evals.md#configure-eval-runs).
+`list` over run snapshots keyed by `runId`). A core missing `delete` or
+`list` leaves eval history in memory until restart.
+See [Evals](./evals.md#configure-eval-runs).
 
 `abs` exports live A/B metrics: `putSample` appends one cumulative
 metric sample per enrolled experiment on each completed or failed turn;
 optional `putSnapshot` / `getSnapshot` store and serve back the latest
-aggregate so a replacement host with no local sessions can still serve
-the A/Bs surface. **Derived form**: each sample lands as its own key
-(`agentkit/v1/{agent}/ab-samples/{experiment}/{sessionId}/{at}` — a
-blind append-only put, never a read-modify-write of one growing array)
-and the snapshot lives at the fixed `agentkit/v1/{agent}/ab-snapshot`
-key (last-write-wins is correct for "latest aggregate"). `putSample` and
-`putSnapshot` need only core `put`; `getSnapshot` needs core `get`.
-Session event logs remain the assignment source of truth either way. See
-[Live A/B metrics](./ab.md).
+aggregate so a replacement host can still serve the A/Bs surface.
+`putSample` and `putSnapshot` need only core `put`; `getSnapshot` needs
+core `get`. Session event logs remain the assignment source of truth
+either way. See [Live A/B metrics](./ab.md).
 
 ## Policy
 
@@ -137,8 +116,6 @@ follow-up arrives instead of at startup.
 With `get` and `list`, serve can rebuild local state from your store:
 
 - At startup, the Agent SDK loads recent sessions up to the restore caps.
-  Local disk wins when both sides have the same session. Reminders
-  hydrate the same way into `--state-root/reminders`.
 - On demand, a missing continuation token resolves through the store
   and resumes that session.
 - Playground eval history and A/B aggregates can load from the same
@@ -157,19 +134,16 @@ await ctx.host.kv.put("alert-memory/abc", { updated: "…" });
 const prior = await ctx.host.kv.get("alert-memory/abc");
 ```
 
-The Agent SDK prefixes author keys as `agentkit/v1/{agent}/kv/{key}` (same
-bounded encoding as continuation tokens). Writes **await** the sink and
-propagate errors — unlike session mirrors, which are at-most-once.
+Writes **await** the sink and propagate errors, unlike session mirrors,
+which are at-most-once.
 
-Without `agent/storage.ts`, `host.kv` falls back to files under
-`--state-root/kv`. That is fine for local dogfood; it does **not**
-survive replacing the host. For Cursor-managed hosting, prefer
-`@cursor/july/storage/cursor-hosted` so sessions and author KV share the
-platform Bugbot tables through a control-plane HTTP proxy (authenticated
-as the deployment pod credential — engines never receive a database URL).
+Without `agent/storage.ts`, `host.kv` is local-only and does not
+survive replacing the host. Hosted agents should author
+`cursorHostedStorage()` so session and `host.kv` records survive
+replace.
 
 ```ts
-// agent/storage.ts — Cursor-managed hosting
+// agent/storage.ts: Cursor-managed hosting
 import { defineStorage } from "@cursor/july/storage";
 import { cursorHostedStorage } from "@cursor/july/storage/cursor-hosted";
 
@@ -182,32 +156,18 @@ Built-in helpers:
 
 | Import | Backend |
 | --- | --- |
-| `@cursor/july/storage/file-kv` | File-per-key under `.agent-serve/kv` |
-| `@cursor/july/storage/cursor-hosted` | Platform Bugbot `agent_serve_*` via control-plane proxy |
+| `@cursor/july/storage/file-kv` | File-per-key under the project state directory |
+| `@cursor/july/storage/cursor-hosted` | Cursor-managed hosting; records survive replace |
 
 ## Bring your own backend
 
-There is no built-in Postgres backend on purpose. Cursor's internal
-`agent_serve_*` tables are owned by the backend and reachable only
-through the hosted proxy, and this doc does not prescribe a schema —
-what you back the KV with is your call. Any durable store works:
-
-- **Local disk** — the built-in `fileKv` (single process only).
-- **Object storage (S3-class)** — one object per key; conditional
-  writes map directly onto the contract (`putIfAbsent` = put with
-  `If-None-Match: *`, `putIfVersion` = put with `If-Match: <etag>`,
-  the ETag is the version token, `listKeys` is a prefix listing).
-- **Redis, DynamoDB, a SQL table, …** — anything that can do an
-  atomic compare-and-set and a prefix listing.
-
-Implement the `StorageConfig` methods (and the optional `cas` group)
-against that store. The
-contract, defined at `@cursor/july/kv`: version tokens are opaque
-strings that change on every successful write — including plain
-`put`, so a stale token fences instead of clobbering; conditional
-writes are atomic; `listKeys` returns every key under the prefix.
-`@cursor/july/kv/memory` is a complete reference implementation to
-compare behavior against.
+Any durable store works if it can put, get, delete, list by prefix,
+and optionally compare-and-set. Implement the `StorageConfig` methods
+(and the optional `cas` group) against that store. The contract,
+defined at `@cursor/july/kv`: version tokens are opaque strings that
+change on every successful write, including plain `put`, so a stale
+token fences instead of clobbering; conditional writes are atomic;
+`listKeys` returns every key under the prefix.
 
 ## Conditional writes (the `cas` group)
 
@@ -215,10 +175,7 @@ The `cas` group is compare-and-swap over the same keyspace:
 `getWithVersion` / `putIfAbsent` / `putIfVersion` / `listKeys`, defined
 backend-agnostically at `@cursor/july/kv`. Plain storage works without
 it, so an existing backend keeps working across a platform upgrade.
-`defineStorage` rejects a partial group — implement all four methods or
+`defineStorage` rejects a partial group. Implement all four methods or
 none. Version tokens are opaque strings that must change on every write
 (a counter column, a row version, a content hash). The built-in backends
-both include it: `fileKv` uses content-hash tokens (single-process
-correctness) and `cursorHostedStorage` the control-plane proxy (a
-`version` counter on the server). `memoryCasTable()` is for test fixtures
-and inert sinks only.
+both include the group.

package/docs/templates/agentic-owners.md

@@ -32,7 +32,7 @@ agent-sdk login
 agent-sdk dev
 ```
 
-PR events stream through your Cursor account — no webhook or GitHub App
+PR events stream through your Cursor account. No webhook or GitHub App
 setup. Open a PR, or replay a real one deterministically (this also works
 with `repos` empty):
 
@@ -75,7 +75,7 @@ applies the deterministic decision:
 
 - **Approve** when the tier is low and no matched rule demands a human,
   bound to the head SHA.
-- **Request reviewers** otherwise — the policy owners (max 2, never the
+- **Request reviewers** otherwise: the policy owners (max 2, never the
   author), plus one status comment the agent keeps updated in place.
 
 The model never writes to GitHub. A broken policy file fails closed with

package/docs/templates/pr-autofixer.md

@@ -91,12 +91,9 @@ opted-in PR wakes the agent. A comment on a plain GitHub issue does
 not. The channel buffers about 3 seconds per PR. Payload details are
 dropped on purpose. The follow-up says something changed.
 
-Pending wakes snapshot to `host.kv` (`webhook-buffer`) before the
-webhook is ACKed, and restore on restart. Affinity is
-`affinity/{owner/repo#N}` → `bc-…` in the same store, written from
-`agent.bound`. `agent/storage.ts` uses `cursorHostedStorage`, so both
-survive host replace. Local serve without that plug-in falls back to
-`--state-root/kv`.
+Pending wakes and the PR-to-cloud-agent map persist in `host.kv` so
+they survive restart. `cursorHostedStorage` keeps both across replace.
+Without that plug-in, `host.kv` is local-only.
 
 Closing a PR cancels its merge-conflict reminder and drops buffered
 wakes.
@@ -106,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

@@ -12,8 +12,8 @@ Start with four checks, in order:
 3. What the playground or HTTP API shows
 4. The session event stream (trace)
 
-Match your symptom below. Keep the commands as `agent-sdk`; see
-[Run the CLI](/#run-the-cli) if you still need an alias.
+Match your symptom below. Keep the commands as `agent-sdk`. If it is
+not on `PATH`, use `npx @cursor/july`.
 
 ## What if serve or the playground looks wrong?
 
@@ -21,9 +21,9 @@ Match your symptom below. Keep the commands as `agent-sdk`; see
 | --- | --- |
 | `serve` won't start | Run `agent-sdk validate --dir .` and fix the reported errors. |
 | Playground is blank or says there are no agents | The UI needs a running `serve` process. Building the playground assets alone is not enough. |
-| Edits to the playground don't show up | Use `serve --dev` and open the printed playground HMR URL (often port `5273`), not only the static `:3000` URL. |
-| Sessions exist on disk but the playground list is empty | The list shows sessions for the authenticated caller. In `--dev` on loopback the list is wider. Otherwise open `/<slug>/playground?sessionId=ses_…` or inspect `sessions/` under your state root. |
-| Port 3000 or 5273 is already in use | For the default serve port, the CLI tries the next free port and prints a notice. Pass `--port` to pick one, or `--port 0` for any free port. Stop leftover Vite or webhook-forwarder processes if you need the original port. |
+| The playground UI looks stale | `serve --dev` prints a playground URL. Open that URL. Agent-file edits still need a restart (press Enter on the TTY). |
+| Sessions exist but the playground list is empty | The list shows sessions for the authenticated caller. In `--dev` on loopback the list is wider. Otherwise open `/<slug>/playground?sessionId=ses_…`. |
+| Port 3000 is already in use | For the default serve port, the CLI tries the next free port and prints a notice. Pass `--port` to pick one, or `--port 0` for any free port. Stop leftover playground or webhook-forwarder processes if you need the original port. |
 
 ## What if a model turn goes wrong?
 
@@ -31,8 +31,8 @@ Match your symptom below. Keep the commands as `agent-sdk`; see
 | --- | --- |
 | 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 `~/.cache/agent-serve/<dir>`. 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`. |
+| 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 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 @@ Match your symptom below. Keep the commands as `agent-sdk`; see
 | --- | --- |
 | `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.92",
+  "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": {
@@ -47,6 +47,13 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./internal/hosted-delivery-protocol": {
+      "anysphere-source": "./src/internal/hosted-delivery-protocol.ts",
+      "bun": "./dist/internal/hosted-delivery-protocol.js",
+      "types": "./dist/internal/hosted-delivery-protocol.d.ts",
+      "import": "./dist/internal/hosted-delivery-protocol.js",
+      "default": "./dist/internal/hosted-delivery-protocol.js"
+    },
     "./tools": {
       "anysphere-source": "./src/tools.ts",
       "types": "./dist/tools.d.ts",
@@ -113,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",
@@ -248,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