@cursor/july 0.1.62 → 0.1.73

package/docs/reference/connections.md

@@ -37,7 +37,6 @@ copies them onto the hosted deployment as `MCP_OAUTH_<NAME>_*` secrets.
 export default defineConnection({
   url: "https://mcp.example.com/inventory",
   oauth: true,
-  hostOnly: true, // model cannot call; host.mcp still can
 });
 ```
 
@@ -49,10 +48,96 @@ 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).
 
-Use `hostOnly: true` when only deterministic host tools should call the
-server (deploys, admin APIs). Account MCP (`cursorAccount: true`) stays
-the right choice for connectors already linked in the Cursor dashboard;
-omit `servers` (or pass `"*"`) to forward every connected connector.
+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`.
+
+## 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 —
+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:
+
+```ts
+export default defineConnection({
+  url: "https://api.cursor.com/v1/mcp/plugins",
+  auth: async (session) => ({
+    headers: { Authorization: `Bearer ${await grantFor(session)}` },
+  }),
+  advertiseTools: true, // optional — named tools instead of meta-tools
+});
+```
+
+The callback is evaluated on **every local turn** — reminder fires and
+post-restart follow-ups included — 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.
+
+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
+breaks mid-conversation. (Channels that mint stable, parseable tokens by
+design are the exception.)
+
+`auth` works attached or advertised. Advertised connections open
+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.
+
+## Advertise a connection's tools by name (`advertiseTools`) {#advertise-tools}
+
+Attached MCP servers sit behind the harness MCP meta-tools. The model does
+not see names like `Datadog-search_datadog_dashboards` until you set
+`advertiseTools: true`. Use that flag when playground or local chat should
+call the tools by name.
+
+The engine lists the connection at turn-build time and synthesizes a named
+1:1 passthrough server tool per entry, using the server's names,
+descriptions, and live schemas. Those merge into the authored
+`agent/tools/` catalog. The raw connection is then not attached to the
+model (it stays available on `host.mcp`), so each tool appears exactly
+once.
+
+```ts
+export default defineConnection({
+  url: "https://api.cursor.com/v1/mcp/plugins",
+  auth: async (session) => ({ headers: await tenantHeaders(session) }),
+  advertiseTools: true,
+});
+```
+
+Fail-closed, by design: a `listTools` failure, an invalid tool name, or a
+name collision (with an authored tool or another advertised connection)
+fails the turn. A turn never silently runs with a shrunken toolset.
+Listing runs once per turn, so point this at endpoints that answer
+`tools/list` cheaply. Connections with `auth` are listed and called
+through one-off clients carrying that session's headers. Auth-less ones
+(including Cursor account connections) go through the shared host
+registry. Local runtime only, like all server tools, and not combinable
+with `hostOnly`. Advertising puts the tools in the model's toolset.
+`hostOnly` keeps them off the model. `GET /v1/info` reports
+`advertiseTools` on the connection. The per-tool list is built per turn,
+not on the static catalog, the peer-agent MCP server, or cloud
+`agentsdk-tools`, and those advertised tools cannot be invoked via direct
+tool calls.
 
 ## Local stdio MCP server
 
@@ -100,17 +185,29 @@ behavior in an explicit form. Pass a name list when you want a smaller
 set.
 
 ```ts
-// agent/mcp-connections/cursor.ts: every connected connector
-export default defineConnection({ cursorAccount: true });
+// agent/mcp-connections/account.ts: every connected connector
+export default defineConnection({
+  cursorAccount: true,
+  advertiseTools: true,
+});
 // same, spelled out:
-export default defineConnection({ cursorAccount: true, servers: "*" });
+export default defineConnection({
+  cursorAccount: true,
+  servers: "*",
+  advertiseTools: true,
+});
 // only Linear:
 export default defineConnection({
   cursorAccount: true,
   servers: ["Linear"],
+  advertiseTools: true,
 });
 ```
 
+Name the file `account.ts`. `cursor.ts` collides with the IDE `cursor`
+MCP namespace. `advertiseTools: true` puts connector tools on local
+turns by name. Without it they sit behind harness meta-tools.
+
 The host must be signed in (`agent-sdk login` or `CURSOR_API_KEY`).
 `serve` fails fast at startup otherwise, and logs each connector's live
 status (`connected`, `needsAuth`, `error`) as it starts.
@@ -152,8 +249,9 @@ are in the [Agent-to-agent guide](../guides/agent-to-agent.md).
 
 One authored MCP connection serves three consumers.
 
-1. **Cursor agent:** Local or cloud turns see the MCP connection
-   through SDK `mcpServers`, and the model calls its tools directly.
+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.
 2. **Server tools:** Deterministic host code composes MCP calls
    through `ctx.host.mcp`:
 

package/docs/reference/sessions.md

@@ -150,8 +150,8 @@ disappears from listings and can no longer be streamed or continued.
 The `runner/` store keeps its own conversation copy until you remove it.
 Cloud conversations remain on the Cursor backend.
 
-Change the root with `--state-root` or `stateRoot`. Keep it outside
-repositories whose parent rules shouldn't reach the agent. See
+Change the root with `--state-root` or `stateRoot`. Nested git checkouts
+already default `local.cwd` outside the enclosing repo. See
 [local session workspaces](../concepts.md#what-files-can-a-local-session-access).
 
 ## How do I inspect a saved event stream?

package/docs/reference/tools.md

@@ -129,6 +129,20 @@ On the local runtime, scripts land under `.agent-serve/tools/` in the
 session workspace with a catalog in `AGENTS.md`. On cloud, the catalog
 and script bodies travel on the first prompt.
 
+## Tools from an MCP connection, advertised by name
+
+Authored `agent/tools/` files are one catalog for every session. When
+the tools should come from an MCP server — including per-tenant toolsets
+resolved at runtime — declare the connection with
+`advertiseTools: true` (plus per-session `auth` when the credential
+depends on who the session is for) and the engine synthesizes named 1:1
+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).
+
 ## Gate a tool on human approval
 
 A server tool can require a person to sign off before it runs. Set

package/docs/troubleshooting.md

@@ -31,7 +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. Point `defineAgent({ local: { cwd } })` outside that tree, or set `--state-root` to a clean directory (for example under `/tmp`). |
+| 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`. |
 | Server tools, skills, or workspace seed files never appear | The agent runtime is `cloud`. Those features apply on the local runtime. `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. |
@@ -70,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 likely `hostOnly`. Call it from a host tool via `ctx.host.mcp`, and update instructions. |
+| 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. |
 
 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.62",
+  "version": "0.1.73",
   "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": {
@@ -150,18 +150,21 @@
     },
     "./kv": {
       "anysphere-source": "./src/kv.ts",
+      "bun": "./dist/kv.js",
       "types": "./dist/kv.d.ts",
       "import": "./dist/kv.js",
       "default": "./dist/kv.js"
     },
     "./kv/memory": {
       "anysphere-source": "./src/kv/memory-kv.ts",
+      "bun": "./dist/kv/memory-kv.js",
       "types": "./dist/kv/memory-kv.d.ts",
       "import": "./dist/kv/memory-kv.js",
       "default": "./dist/kv/memory-kv.js"
     },
     "./ledger": {
       "anysphere-source": "./src/ledger.ts",
+      "bun": "./dist/ledger.js",
       "types": "./dist/ledger.d.ts",
       "import": "./dist/ledger.js",
       "default": "./dist/ledger.js"
@@ -221,7 +224,7 @@
     "node": ">=22.13"
   },
   "dependencies": {
-    "@cursor/sdk": "1.0.27",
+    "@cursor/sdk": "1.0.28",
     "@modelcontextprotocol/sdk": "1.25.1",
     "@octokit/auth-app": "^7.2.0",
     "@octokit/rest": "^21.1.1",
@@ -246,6 +249,7 @@
     "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",
@@ -263,6 +267,7 @@
     "@types/ms": "^2.1.0",
     "@types/node": "catalog:",
     "@types/pg": "^8.16.0",
+    "@types/proper-lockfile": "^4.1.4",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@typescript/native-preview": "7.0.0-dev.20260701.1",

package/skills/create-agent/SKILL.md

@@ -62,7 +62,7 @@ questions, concrete options, the recommended option listed first and labeled
 | **Runtime** | `local` (default) · `cloud` | Local = Cursor SDK harness on this machine; server tools, skills, sandbox seeds, and tool approvals all work. Cloud = Cursor cloud agents; needs `cloud.repos`, no server tools/skills/sandbox seeds (instructions are prepended to the first prompt). Recommend local unless the purpose needs a repo checkout on a cloud VM. |
 | **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 · Other | One file per server under `agent/mcp-connections/`; filename = server name; tokens via env vars, never hardcoded. MCP connections serve the model **and** host code (`ctx.host.mcp`, channel `host.mcp`). |
+| **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. |
 | **Capabilities** (multi) | server tools · agent tools (scripts) · skills · subagents · hooks · sandbox seed files · tool approvals (HITL) · evals (recommend) | Server tools, skills, sandbox seeds, approvals are local-runtime only. Agent tools (`execution: "agent"`) work on both runtimes. Always recommend at least one smoke eval. |
 
 Close the round with a one-screen plan — chosen options plus the file tree you
@@ -87,6 +87,10 @@ Defaults that make first cuts good:
 
 - **Minimal surface.** Instructions + 1–2 real tools + the chosen channels +
   one smoke eval. Unpicked capabilities are follow-ups, not scope.
+- **`local.cwd`.** Keep the harness outside a monorepo checkout
+  (`~/.cache/agent-serve/<slug>`). Discovery does this for nested git
+  projects. Point cwd at a checkout only when the agent must inherit that
+  tree.
 - **Instructions** (`agent/instructions.md`, required): a few lines — identity,
   when to use which tool, output shape. Not an essay.
 - **Tool per file**, filename = tool name the model sees. Prefer
@@ -139,9 +143,9 @@ agent-sdk init ./<slug>
 ```
 
 `init` writes `package.json` (with `typescript` dev deps and a
-`check` script), `tsconfig.json`, `agent/agent.ts`, `agent/instructions.md`,
-a demo `agent/tools/echo.ts`, and empty capability folders
-(`skills/`, `channels/`, `evals/`, …) each with a `.gitkeep`; existing
+`check` script), `tsconfig.json`, `AGENTS.md`, `.gitignore`, `agent/agent.ts`,
+`agent/instructions.md`, a demo `agent/tools/echo.ts`, and empty capability
+folders (`skills/`, `channels/`, `evals/`, …) each with a `.gitkeep`; existing
 files are left alone (`exist`) and missing ones are filled in. It then
 runs `npm install`, and when the host is unsigned runs `login` and waits
 before printing `cd` (when needed) and `agent-sdk dev`. Then shape it to the
@@ -149,8 +153,7 @@ plan:
 
 1. `tsconfig.json` — init writes a strict, `noEmit` config covering `agent/`
    and `evals/`; extend it only when the project needs more.
-2. `agent/agent.ts` — chosen model/runtime via `defineAgent({...})`; add the
-   `cloud: { repos: [...] }` block for cloud runtime.
+2. `agent/agent.ts` — chosen model/runtime via `defineAgent({...})`. Nested git checkouts get `local.cwd` under `~/.cache/agent-serve/<slug>` at discovery even if omitted. Add the `cloud: { repos: [...] }` block for cloud runtime.
 3. `agent/instructions.md` — real instructions; delete or replace `echo.ts`
    with the real tools.
 4. Add the chosen `channels/`, `mcp-connections/`, `skills/`, `subagents/<id>/`
@@ -210,9 +213,9 @@ agent-sdk eval --dir ./<slug>
 
 Serve only the new agent's directory during bring-up — pointing `serve` at a
 parent folder also mounts every sibling agent it contains.
-Runtime state lands in `<project>/.agent-serve/` (gitignored); keep durable
-`--state-root` outside the monorepo so sessions don't inherit ambient
-`AGENTS.md`.
+Runtime state lands in `<project>/.agent-serve/` (gitignored). Nested
+checkouts default `local.cwd` to `~/.cache/agent-serve/<slug>` at
+discovery. `--state-root` is for session files, not harness cwd.
 
 ## Channel setup with the user
 

package/skills/debug/SKILL.md

@@ -47,7 +47,8 @@ curl -sN 'localhost:3000/<slug>/v1/session/<id>/stream?startIndex=0' | head -50
 | Every built-in read/grep the model makes fails; turns crawl through retry loops | You ran the CLI under **Bun**. Kill it, rerun under Node/tsx. (`NGHTTP2_FRAME_SIZE_ERROR` in SDK logs is the tell.) |
 | `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 the monorepo, so the harness loaded ancestor config. `defineAgent({ local: { cwd } })` outside the repo, or `--state-root` under `/tmp`. |
+| 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`. |
 | 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`). |

package/skills/framework-map/SKILL.md

@@ -38,11 +38,11 @@ pnpm exec tsx src/bin/agent-serve.ts <cmd> ...
    before shipping. Classic miss: a tool `execute` return that fails
    `ToolExecuteResult` — returns must be JSON-shaped, so use object
    literals or `type` aliases, not `interface` types.
-4. **Keep session state out of big monorepos.** Session workspaces are real
-   Cursor project directories and inherit ambient `AGENTS.md`/`.cursor`
-   rules from **ancestors**. Set `defineAgent({ local: { cwd } })` outside
-   the monorepo or pass a temp `--state-root`. (`run`/`eval` already use a
-   temp state root.)
+4. **Harness cwd in a nested git repo.** Discovery defaults `local.cwd` to
+   `~/.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.
 5. **A model turn needs `CURSOR_API_KEY`.** Everything structural
    (`validate`, `info`, `call`, `serve` bring-up) works without one.
 
@@ -57,7 +57,7 @@ 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 — available to the model, to server tools (`ctx.host.mcp`), and to channel/schedule handlers (`args.host.mcp`). `{ tools }` authors TypeScript the Agent SDK packages as stdio MCP for the agent environment. |
+| `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/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: agentkit-mcp-auth
 description: >-
   Authorize host MCP OAuth for defineConnection({ url, oauth: true }):
   agent-sdk mcp oauth, local mcp-auth.json, --store deployment secrets,
-  hostOnly, and egress. Read when wiring or debugging MCP auth.
+  hostOnly, advertiseTools, and egress. Read when wiring or debugging MCP auth.
 ---
 
 # Host MCP OAuth (mcp auth)
@@ -26,13 +26,15 @@ 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 |
 
-Prefer `hostOnly: true` when only host tools / channel handlers should
-call the server (admin APIs, privileged writes). The model will not see
-those tools.
+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`.
 
 ## Goal checklist
 
-- [ ] `agent/mcp-connections/<name>.ts` with `url` + `oauth: true` (+ `hostOnly` if privileged)
+- [ ] `agent/mcp-connections/<name>.ts` with `url` + `oauth: true` (`hostOnly` if privileged; `advertiseTools` if the model should call it)
 - [ ] `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
@@ -127,7 +129,7 @@ redeploy completed, then exercise the same host tool once.
 | `Unknown MCP connection` | Filename under `agent/mcp-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 | Connection is `hostOnly`; fix instructions + use host tools |
+| 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. |
 | Tokens ignored after URL edit | Expected; run `mcp oauth` again for the new resource URL |
 
 ## Don't

package/src/bin/agent-serve.ts

@@ -58,6 +58,7 @@ import {
   cmdStop,
   type DeployCliOptions,
 } from "../internal/cli-deploy.js";
+import { cmdManifest } from "../internal/cli-manifest.js";
 import {
   CLI_COMMAND_NAME as CLI,
   PACKAGE_NAME,
@@ -139,6 +140,7 @@ Usage:
                           [--no-wait] [--repo <url>] [--ref <ref>]
                           [--path <agentPath>] [--cursor-events-repo <owner/name>]...
                           [--allow-domain <domain>]...
+  ${CLI} manifest    [--dir <path>] [--json]
   ${CLI} deployments [--team <id>] [--json]
   ${CLI} deployment  <slug> [--team <id>] [--json]
   ${CLI} stop        <slug> [--team <id>] [--json] [--no-wait]
@@ -742,6 +744,13 @@ async function main(argv: string[]): Promise<number> {
       });
     }
 
+    case "manifest": {
+      // Offline extraction of deploy metadata (events, egress, routes,
+      // /v1/info payload) — no VM, no network. Wd-1 of the event-ingress
+      // plan; `deploy` attaches this to the request from Wd-2 on.
+      return cmdManifest({ dir, json: values.json === true });
+    }
+
     case "deployments": {
       return cmdDeployments(deployOptionsFromValues(values));
     }
@@ -1251,7 +1260,8 @@ async function main(argv: string[]): Promise<number> {
           values["cursor-events"] === true
             ? { repos: values.repo ?? [] }
             : undefined,
-        // Soft boot logs (GitHub auth, etc.) stay secondary to the banner.
+        // Soft boot logs stay secondary to the banner. `dim` is a no-op on
+        // already-styled lines (the MCP warning box).
         logger: (line: string) => {
           process.stdout.write(`${style.dim(line)}\n`);
         },
@@ -1691,7 +1701,7 @@ installTransportErrorGuards();
 
 // Authored agent files are TypeScript imported at runtime; install the tsx
 // loader (and the framework import aliases on compiled runs) before any
-// command touches a project.
+// command touches a project. In-repo CLI is `bin/agentsdk`.
 registerAuthoredModuleLoaders()
   .then(() => main(process.argv.slice(2)))
   .then(

package/src/channels/github/api.ts

@@ -535,7 +535,12 @@ function isOctokitRequestError(error: unknown): error is {
   );
 }
 
-function wrapOctokitError(error: unknown, method: string, path: string): Error {
+/** Normalize an Octokit request failure into {@link GitHubApiError}. */
+export function wrapOctokitError(
+  error: unknown,
+  method: string,
+  path: string
+): Error {
   if (isOctokitRequestError(error)) {
     return new GitHubApiError({
       body: error.response?.data,

package/src/channels/github/binding.ts

@@ -17,6 +17,11 @@ import {
   type GitHubPostedComment,
   type GitHubReactionContent,
 } from "./api.js";
+import {
+  createGitHubCheck,
+  type GitHubCheck,
+  type GitHubCheckCreateInput,
+} from "./checks.js";
 import type {
   GitHubChannelCredentials,
   GitHubConversationKind,
@@ -79,6 +84,14 @@ export interface GitHubHandle {
     description?: string;
     targetUrl?: string;
   }): Promise<GitHubApiResponse>;
+  /**
+   * Open a CI check run (Checks API) on `sha` and get a handle for updating
+   * and concluding it. Needs `checks:write` — with `cursorAccount`, declare
+   * `githubChannel({ checks: true })` to opt the lease up.
+   */
+  createCheck(
+    input: Omit<GitHubCheckCreateInput, "github" | "owner" | "repo">
+  ): Promise<GitHubCheck>;
 }
 
 /** Thread-scoped operations for the current conversation (`ctx.thread`). */
@@ -149,6 +162,14 @@ export function buildGitHubBinding(input: {
           : { targetUrl: status.targetUrl }),
       });
     },
+    createCheck(check) {
+      return createGitHubCheck({
+        ...check,
+        github: { getOctokit },
+        owner: state.owner,
+        repo: state.repo,
+      });
+    },
   };
 
   const thread: GitHubThread = {