@cursor/july 0.1.95 → 0.1.96

package/skills/github/SKILL.md

@@ -1,28 +1,26 @@
 ---
 name: agentsdk-github
 description: >-
-  Build and test GitHub-webhook-driven Agent SDK agents: githubChannel
-  hooks (auth turn vs host task), signature modes, and testing tiers
-  (fixtures, github replay, github forward, serve --cursor-events). Use
-  when wiring GitHub events, replaying PR webhooks, or debugging delivery.
+  Build and test GitHub-driven Agent SDK agents: githubChannel hooks
+  (auth turn vs host task), cursorAccount / --cursor-events, and
+  local test tiers (fixtures, replay, forward). Use when wiring
+  GitHub events or debugging delivery.
 ---
 
 # GitHub channels in the Agent SDK
 
-Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
-host serves the same index at `/docs/llms.txt`.
+Author `agent/channels/github.ts`. Production wakes:
+`cursorAccount` + `serve --cursor-events`. No public webhook URL.
+Use the HTTP route for fixtures, replay, and hosts that already
+terminate GitHub webhooks.
 
-Author `agent/channels/github.ts` with `githubChannel()` from
-`@cursor/july/channels/github`. It mounts
-`POST /<slug>/v1/channels/github` and publishes the events it dispatches on
-(derived from declared hooks, or pinned via `webhookEvents`) so the CLI can
-auto-derive forwarding.
+Guide: `docs/guides/github.md`.
 
 ```ts
 import { defaultGitHubAuth, githubChannel } from "@cursor/july/channels/github";
 
 export default githubChannel({
-  botName: "my-agent", // or GITHUB_APP_SLUG; used to ignore self-comments
+  botName: "my-agent",
   cursorAccount: { repos: ["owner/repo"] }, // permissions?: "read" | "pr-write" | "contents-write"
 
   onPullRequest: (ctx, pr) =>
@@ -33,39 +31,44 @@ export default githubChannel({
 ```
 
 Hooks: `onPullRequest`, `onComment`, `onIssue`, `onCheckSuite`,
-`onCheckRun`, `onWorkflowRun`, `onStatus`, plus catch-all `onEvent` and
-lifecycle `onStart`/`onStop`. Each hook returns one of:
+`onCheckRun`, `onWorkflowRun`, `onStatus`, plus `onEvent` and
+`onStart`/`onStop`.
 
 | Return | Meaning |
 | --- | --- |
-| `{ auth }` | Start/continue a **model turn** as that actor (a chat session exists; shows in the playground) |
-| `{ task }` | **Host-side work**, 202-ACKed immediately so it can run past GitHub's ~10s delivery timeout (no chat session) |
-| `null` | Skip this delivery |
-
-Use `{ task }` for deterministic pipelines (a security reviewer can run its
-whole review loop this way and report via commit status); use `{ auth }` when
-the model should reason about the event.
-
-## Auth modes
-
-- **`cursorAccount`** → the signed-in Cursor principal supplies both the SCM
-  event stream and a short-lived, repo-scoped GitHub credential. It works in
-  local dev (`agent-sdk login`) and hosted deployments (`CURSOR_API_KEY`).
-  `ctx.github`, `ctx.host.github`, and child `gh` commands share the lease.
-  Use `{ repos: ["owner/repo"] }`, or `true` with `serve --cursor-events
-  --repo owner/repo`. One host credential covers up to 20 repositories under
-  one GitHub owner; it cannot span owners.
-- **Secret set** → route auth is `allowAll()` + `X-Hub-Signature-256`
-  verification before parsing; the HMAC becomes the request principal.
-- **No secret** → `localDevStrict()` (loopback only) — except under
-  `serve --dev`, which admits **unsigned loopback** deliveries so fixtures
-  and forwarding work with zero config.
-- Non-dev targets always need the secret; keep the same value on the
-  server and whatever signs deliveries.
-
-## Testing tiers — pick deliberately
-
-### 1. Saved fixtures (offline, free)
+| `{ auth }` | Model turn. Session shows in the playground. `workspaceFiles` can be a function. |
+| `{ task }` | Host work. No chat session. Use when the work can outlive a webhook timeout. |
+| `null` | Skip |
+
+To keep repo scope in deploy config, use `cursorAccount: true`
+and pass `--repo owner/name` at serve / `--cursor-events-repo`
+at deploy. Repos must share one GitHub owner.
+
+## Event sources
+
+| Source | When |
+| --- | --- |
+| `cursorAccount` + `serve --cursor-events` | Preferred. Signed-in host (`agent-sdk login` / `CURSOR_API_KEY`). Repos from the channel and from repeatable `--repo owner/name`. Cap 20, one GitHub owner |
+| HTTP `POST /<slug>/v1/channels/github` with a webhook secret | `allowAll()` + `X-Hub-Signature-256` |
+| HTTP, no secret | Loopback only. `serve --dev` also admits unsigned loopback (fixtures / forward) |
+
+`permissions`: `"read"` inspect; `"pr-write"` (default) comments /
+PR writes; `"contents-write"` push or merge-box checks.
+`progress.commitStatus` needs check-write; see the GitHub guide.
+Set `checks: true` when channel code posts its own Checks API
+runs through `ctx.github.createCheck`. The flag grants access.
+It does not post a check.
+
+Without `cursorAccount`, outbound calls prefer App installation
+tokens (`GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY`). Local tests
+can use `GITHUB_TOKEN` / `gh auth login`.
+
+The Cursor stream is metadata, not full webhook bodies. Re-read
+the PR from GitHub.
+
+## Test locally
+
+1. **Fixtures** (offline, `--dev`, no signature):
 
 ```bash
 curl -s -X POST http://127.0.0.1:3000/<slug>/v1/channels/github \
@@ -74,87 +77,26 @@ curl -s -X POST http://127.0.0.1:3000/<slug>/v1/channels/github \
   -d @fixtures/github/pull_request.synchronize.json
 ```
 
-No signature needed against `--dev`. Snapshot fixtures with replay's
-`--dry-run --out` (below) instead of hand-writing payloads.
-
-### 2. `github replay` — deterministic, read-only (the hillclimbing tier)
-
-Reads a real PR via `gh api` (**pull access is enough** — `GITHUB_TOKEN`
-is fine here), synthesizes GitHub-shaped payloads, signs them when a secret
-is configured, and POSTs them at the channel. Fully deterministic.
+2. **Replay** (hillclimb tier; pull access is enough):
 
 ```bash
-agent-sdk github replay https://github.com/owner/repo/pull/123 --dir <project>
-agent-sdk github replay owner/repo#123 --dir <project> --events '*' --conclusion failure
+agent-sdk github replay owner/repo#123 --dir <project>
 agent-sdk github replay owner/repo#123 --dir <project> --events '*' --dry-run --out fixtures/github
 ```
 
-`--events` defaults to `pull_request` (`'*'` = the channel's declared
-set); `--action` / `--conclusion` / `--comment` / `--context` shape each
-event; `--secret` or `GITHUB_WEBHOOK_SECRET` signs.
-
-### 3. `github forward` — live deliveries (needs repo admin)
-
-Wraps `gh webhook forward`: registers a real webhook and relays deliveries
-to loopback. URL + events auto-derived; repo inferred from the git remote.
+3. **Forward** (live; repo admin). One forwarder per repo. Blank
+   `GITHUB_TOKEN`/`GH_TOKEN` or every delivery 401s:
 
 ```bash
-agent-sdk github doctor --install     # one-time: gh + cli/gh-webhook
-agent-sdk github events --dir <parent> --json   # what would be forwarded
+agent-sdk github doctor --install
 GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward --dir <project>
 ```
 
-Traps, in order of hours lost:
-
-1. **`GITHUB_TOKEN`/`GH_TOKEN` in the env → every delivery 401s** while
-   hook creation still succeeds. The relay authenticates with the gh CLI
-   login and rejects env tokens. Blank them for the command. `doctor` and
-   `forward` warn about this.
-2. **One forwarder per repo** (GitHub limit). Point one
-   `forward --dir <parent>` at a folder of agents and it fans out each raw,
-   still-signed delivery to every channel whose event set matches; N
-   separate forwarders collide with `Hook already exists`.
-3. Requires **admin** on the repo (org owner for `--org`) — if you lack
-   it, use replay.
-4. Best-effort dev relay: deliveries while the process is down are lost.
-
-`--repo owner/repo` / `--org ORG` override the target, `--events` narrows,
-`--url` points at a tunnel, `--slug` / `--channel` target one agent.
-
-### 4. `serve --cursor-events` — pull from Cursor (`/v0/scm-events`)
+4. **Cursor pull** (same as production):
 
 ```bash
 agent-sdk serve --dir <project> --cursor-events --repo owner/repo
 ```
 
-Reads the stream as the host's Cursor user, so it **requires sign-in**
-(`agent-sdk login` / `CURSOR_API_KEY`) — `serve` refuses to start signed
-out instead of running a relay that can never receive events. No public URL
-or repo admin. Registers before consuming; offset + consumer id under
-`<state-root>/cursor-events/`. `CURSOR_API_BASE_URL` for a non-default
-backend. Each event includes the verified webhook payload when the API
-stored it.
-
-## Production-shaped channel patterns
-
-Steal these when an agent must survive real webhook volume — each one
-against its measured load signal, not as a starter kit. Debounce needs
-event bursts you have seen; persisted buffers need wakes you cannot afford
-to drop; affinity stores need cross-channel resume you actually do.
-Preinstalling all of them is how a channel file hits 400 lines before the
-first real delivery.
-
-- **Debounce per PR** (~3s, latest event wins) and re-buffer while CI
-  settles; skip a flush when a turn for that PR is already in flight.
-- **Persist the buffer before ACKing** the webhook in `host.kv`, then
-  restore it on channel start. A restart must not drop buffered wakes.
-- **Stable continuation key** `pr:owner/repo#N` so every wake resumes the
-  PR's session. Cross-channel resume needs an affinity store mapping PR →
-  SDK agent id (write it from an `agent.bound` hook with `ctx.host.kv`).
-- **Discard payload details in wake prompts** — send a generic "re-check
-  the PR" refresh; the agent re-reads ground truth instead of trusting a
-  stale payload.
-- **Cancel PR-scoped reminders on `pull_request.closed`.**
-- No repo allowlist means the channel wakes for whatever deliveries
-  reach it — decide explicitly what repos an agent may act on, and
-  remember each wake spends real model budget.
+Volume, debounce, and `progress.commitStatus` / `progress.banner`
+live in `docs/guides/github.md`. Do not preinstall them.

package/skills/hillclimb/SKILL.md

@@ -1,186 +1,63 @@
 ---
 name: agentsdk-hillclimb
 description: >-
-  Iterate on a specific Agent SDK agent by running the local server,
-  sending real requests, measuring correctness/efficiency, and proposing
-  the next harness or prompt change. Read this skill when improving an
-  existing agent.
-paths:
-  - packages/agent-serve/**/*
+  Improve one existing Agent SDK agent: pin fixtures, measure, change
+  one lever, remeasure, lock the win with an eval. Use when an agent
+  already runs and needs better results.
 ---
 
 # Agent SDK hillclimb
 
-Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
-host serves the same index at `/docs/llms.txt`.
+Measure → change one lever → remeasure. One failure mode per round.
 
-Optimize one Agent SDK agent project
-with a tight measure → change → remeasure loop. Do not redesign the
-whole framework; climb one concrete failure mode at a time. Sibling skills:
-`framework-map` (orientation), `evals` (the ratchet), `ab` (live variant
-metrics under serve), `github` (deterministic webhook replay), `debug`
-(when a run misbehaves rather than underperforms).
+Siblings: `skills/evals/SKILL.md`, `skills/github/SKILL.md`,
+`skills/debug/SKILL.md`.
 
 ## Preconditions
 
-Confirm with the user (or take from the invoking message):
+From the user or the invoking message:
 
-1. **Target agent** — path or slug, e.g. `./my-agent`
-2. **Fixture(s)** — fixed inputs to compare across runs (PR URL, webhook
-   payload, playground prompt, etc.)
-3. **Success criteria** — what “better” means this round (fewer tools, faster
-   wall time, higher finding quality, fewer wrong side-effects, …)
-4. **Freeze line** — what must not change (API contracts, public output shape)
+1. **Target.** Path or slug
+2. **Fixtures.** Fixed inputs
+3. **Success.** What better means this round
+4. **Freeze line.** What must not change
 
-If those are missing, ask before editing.
+Ask before editing if any are missing. A moving fixture is noise.
 
-## Make the fixture deterministic first
-
-A climb over a moving input is noise. Before round 1:
-
-- **GitHub agents** — replay, don't wait for live events:
-  `agent-sdk github replay <pr> --dir <project>` synthesizes signed,
-  GitHub-shaped payloads from read access only, identically every run;
-  `--dry-run --out fixtures/github` snapshots them for offline replay.
-- **Tool behavior** — isolate host tools from the model with
-  `agent-sdk call <tool> --dir <project> --input '{...}'` (schema-validated,
-  in-process, no turn). If the tool output is wrong, no prompt change fixes it.
-- **Chat agents** — `agent-sdk run --dir <project> --message "<fixture>"`
-  gives a JSON trajectory plus an NDJSON trace under
-  `<project>/.agent-serve/traces/`; `agent-sdk trajectory --events <file>`
-  re-summarizes any saved trace.
-- **Manual probes** — the playground Try modal on any channel route
-  remembers your last body per endpoint and has Copy curl; a successful Try
-  opens the created session.
-
-## Loop
-
-Repeat until the user stops or fixtures meet the criteria.
-
-### 1. Baseline
-
-- Serve with Node (never Bun):
-
-  ```bash
-  agent-sdk serve --dir <project> --dev
-  ```
-
-- Hit the agent the way a user would (channel HTTP, playground, Slack in
-  `--dev` if that is the surface under test).
-
-  Custom channels live at `http://127.0.0.1:3000/<slug>/v1/channels/<id>`.
-  Playground: `http://127.0.0.1:3000/<slug>/playground`.
-
-- Record for each fixture:
-  - HTTP/status and wall time
-  - `sessionId` + playground URL
-  - final result text / structured output
-  - tool trajectory from session `events.ndjson` (`actions.requested` /
-    `action.result`)
-  - workspace footprint (what the host seeded vs what the model opened)
-
-Sessions typically live under:
-
-`<project>/.agent-serve/<slug>/sessions/<sessionId>/`
-
-### 2. Reflect
-
-Score the run on three axes; cite evidence from the trajectory, not vibes.
-
-| Axis | Ask |
+| Surface | Pin it |
 | --- | --- |
-| **Correctness** | Right answer / findings? Misses? Hallucinated context? |
-| **Efficiency** | Tool-call count, redundant reads/greps, fat evidence, latency |
-| **Harness fit** | Did the model invent work the host should have done? Escape the intended workspace? Fight the instructions? |
-
-Name the **single dominant failure mode** for this round (e.g. “full-file dumps
-trigger grep loops”, “skill not on disk so model searches the monorepo”).
-
-### 3. Propose one change
-
-Prefer the smallest lever that addresses that failure mode — and check the
-subtractive lever first:
-
-0. **Deletion** — remove the code, cache, flag, or prompt that caused the
-   failure. A round that shrinks the agent while holding the metrics is a
-   win, not a wash.
-1. **Instructions / skills** — tighten procedure, state the output contract
-   (shape, sections, caps), forbid escape hatches that invite thrash. First
-   lever for quality, formatting, and wording failures.
-2. **Evidence shape** — trim, split, or order artifacts so the intended file
-   is primary
-3. **Host prep** — deterministic tools / channel handlers seed only what the
-   model needs (`workspaceFiles`, channel `callTool`, …). First lever for
-   tool-wandering and latency failures. Prep evidence and gate side effects;
-   do **not** move formatting, summarizing, or classification here — that is
-   the model's job specified badly, and host code is a permanent tax (types,
-   tests, restarts, drift).
-4. **Tool surface** — remove or gate tools that enable wandering
-5. **Framework changes** only if the agent cannot express the fix otherwise —
-   but when the gap is plumbing the framework should own (posting, chunking,
-   auth, retries), extend it or file the gap. A hand-rolled transport
-   workaround in `agent/lib/` outlives the gap and never flows back.
-
-State the hypothesis in one sentence: *“If we X, metric Y should move because Z.”*
-
-### 4. Apply and remeasure
+| GitHub | `agent-sdk github replay <pr> --dir <project>` (`--dry-run --out fixtures/github`) |
+| One tool | `agent-sdk call <tool> --dir <project> --input '{...}'` |
+| Chat | `agent-sdk run --dir <project> --message "<fixture>"` |
 
-- Implement the change.
-- Restart serve if needed (agent project code or package `src/`).
-- Re-run the **same** fixtures.
-- Diff metrics side-by-side (tools, bytes, time, quality notes).
-- Keep the change only if the target metric improves without regressing the
-  freeze line; otherwise revert or narrow.
-- **Ratchet every kept change**: land an eval that would have failed before
-  it (tool-choice gate, `action.result` count bound, output-shape regex —
-  see `evals/SKILL.md`), and never weaken an existing gate to make a round
-  pass. `agent-sdk eval --dir <project> --json` is the regression check
-  between rounds.
-
-Present a short round report to the user before starting the next climb.
-
-## Measurement tips
-
-- Prefer `action.result` counts by `toolName` over raw event volume.
-- Log paths the model actually read; escape outside the session workspace is a
-  harness smell.
-- Separate **host** work (channel `callTool`, prepare steps) from **model**
-  tools when blaming latency. The biggest wins this framework has seen came
-  from moving deterministic work to the host (one PR reviewer's host-prepared
-  reviews cut ~8-minute tool-wandering turns to ~1 minute), not from prompt
-  tuning.
-- The reverse also holds: every optimization on the deterministic path —
-  prefetch, fingerprint dedupe, write coalescing, TTL caches — is code, tests,
-  and flags forever. Add one only against measured pressure (wake volume,
-  rate-limit hits, model spend) recorded in the round report; when the data
-  says the cache would rarely hit, don't build it.
-- For quality, spot-check against a known-good review or oracle on at least
-  one fixture; efficiency-only climbs will silently drop findings.
-- `turn.failed` with `"turn interrupted"` in a trace means a follow-up or
-  stop preempted the turn — measurement artifact, not a regression.
-
-## Working agreements
-
-- One failure mode per round — no mixed “also rewrite instructions while
-  trimming evidence” bundles unless the user asks.
-- Climbs accrete; schedule the counter-move. Every few rounds propose a
-  **shrink round**: dead flags, caches that never hit (the disposition
-  metrics tell you), host renderers the model could own under an output
-  contract. The eval suite is exactly what makes deletion safe.
-- Keep fixtures fixed until a climb explicitly needs a harder case.
-- Use mise/Node workflows already documented for this package; do not introduce
-  Bun.
-- Do not deploy, post real GitHub reviews, or push unless the user asks.
-- Commit only when asked.
+## Loop
 
-## Round report template
+1. **Serve.** `agent-sdk serve --dir <project> --mode single --dev`
+   Playground: `http://127.0.0.1:3000/playground`.
+2. **Hit it.** Same path a user would. Record status, wall time,
+   `sessionId`, output, and `action.result` counts by `toolName`.
+3. **Name the failure.** Score correctness, efficiency, harness
+   fit. One dominant failure this round.
+4. **Change one lever.** Smallest first. Delete the code or prompt
+   that caused it. Then instructions / skills, evidence shape,
+   host prep (`workspaceFiles`, channel `callTool`) for wandering
+   and latency (not formatting or judgment), remove or gate
+   wandering tools, framework only if the agent cannot express
+   the fix. Hypothesis: *If we X, metric Y should move because Z.*
+5. **Remeasure.** Same fixtures. Keep only if the target metric
+   improves and the freeze line holds.
+6. **Lock.** A kept change gets an eval that would have failed
+   before it (`skills/evals/SKILL.md`). Never weaken a gate to
+   pass a round.
 
 ```markdown
-### Hillclimb round N — <slug>
+### Hillclimb round N. `<slug>`
 - Fixture(s): …
 - Hypothesis: …
-- Change: <files / one-liner>
-- Before → after: tools …; wall …; evidence …; quality …
+- Change: …
+- Before → after: tools …; wall …; quality …
 - Verdict: keep | revert | narrow
-- Next failure mode (if any): …
+- Next failure mode:
 ```
+
+Do not deploy or post real GitHub reviews unless asked.

package/skills/mcp-auth/SKILL.md

@@ -2,139 +2,80 @@
 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,
-  advertiseTools, and egress. Read when wiring or debugging MCP auth.
+  agent-sdk mcp oauth, local tokens, --store, advertiseTools, egress.
+  Use when wiring or debugging MCP auth.
 ---
 
-# Host MCP OAuth (mcp auth)
+# Host MCP OAuth
 
-Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
-host serves the same index at `/docs/llms.txt`.
-
-Use this skill when a human asks to authorize a remote MCP server on an
-Agent SDK host, store credentials for Cursor-managed hosting, or debug
-`host.mcp` auth failures for `oauth: true` connections.
-
-Sibling skills: `framework-map` for layout, `create-agent` when scaffolding,
-`debug` for unrelated local failures, `operate` for deploy/secrets ops.
-
-Docs: `docs/guides/mcp-oauth.md`, `docs/reference/connections.md`,
-`docs/reference/cli.md#mcp-oauth`.
-
-## When to use host OAuth vs account MCP
+Guide: `docs/guides/mcp-oauth.md`.
 
 | Need | Use |
 | --- | --- |
-| Connector already in Cursor dashboard (Linear, Notion, …) | `defineConnection({ cursorAccount: true })` or `servers: "*"` for every connected server; `servers: […]` to allowlist |
-| 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 |
-
-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` (`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
-- [ ] Hosted: `agent-sdk mcp oauth <name> --store` then redeploy; `secrets list` shows the names
-
-## Phase 0 — Author the connection (agent)
+| Connector already in the Cursor dashboard | `defineConnection({ cursorAccount: true })` or `servers: "*"` / `servers: […]` |
+| Remote URL that speaks OAuth; host holds tokens | `defineConnection({ url, oauth: true })` + this skill |
+| Static bearer / API key | `headers` / env on `{ url }` |
+
+`advertiseTools: true` puts named tools on local turns. Host tools
+can still call `ctx.host.mcp`.
+
+## Checklist
+
+1. **Declare the connection.** `agent/mcp-connections/<name>.ts`
+   with `url` + `oauth: true`. Use `agent/host-connections/` when
+   the model must not see it.
+2. **Name the secrets** if you will `--store`:
+   `hosting.secretNames` lists
+   `MCP_OAUTH_<NAME>_{ACCESS_TOKEN,REFRESH_TOKEN,CLIENT_ID}`.
+3. **Allow egress** on hosted non-bootstrap hosts:
+   `hosting.egressDomains`.
+4. **Authorize.** Local: `agent-sdk mcp oauth <name>`. Hosted:
+   `agent-sdk mcp oauth <name> --store` then `agent-sdk deploy`.
+   `secrets list` shows the names.
 
 ```ts
 // agent/mcp-connections/inventory.ts
-import { defineConnection } from "@cursor/july/connections";
-
 export default defineConnection({
   url: "https://mcp.example.com/inventory",
   oauth: true,
-  description: "Inventory MCP.",
 });
 ```
 
-In `agent/agent.ts`:
-
-```ts
-hosting: {
-  egressDomains: ["mcp.example.com"], // if hosted + non-bootstrap host
-  secretNames: [
-    "MCP_OAUTH_INVENTORY_ACCESS_TOKEN",
-    "MCP_OAUTH_INVENTORY_REFRESH_TOKEN",
-    "MCP_OAUTH_INVENTORY_CLIENT_ID",
-  ],
-},
-```
-
-Naming: connection file `inventory.ts` → env prefix `MCP_OAUTH_INVENTORY`.
-Do **not** put `CURSOR_*` or hosted-storage names in `secretNames`.
-
-Wire privileged calls through host tools:
-
 ```ts
-await ctx.host.mcp.callTool("inventory", "list_warehouses", {
-  region: input.region,
+// agent/agent.ts
+export default defineAgent({
+  hosting: {
+    secretNames: [
+      "MCP_OAUTH_INVENTORY_ACCESS_TOKEN",
+      "MCP_OAUTH_INVENTORY_REFRESH_TOKEN",
+      "MCP_OAUTH_INVENTORY_CLIENT_ID",
+    ],
+    egressDomains: ["mcp.example.com"],
+  },
 });
 ```
 
-Set `advertiseTools: true` when the model should call the server by name
-instead of through MCP meta-tools.
-
-## Phase 1 — Local authorize (agent + human)
+File `inventory.ts` → prefix `MCP_OAUTH_INVENTORY`. Do not put
+`CURSOR_*` names in `secretNames`.
 
 ```bash
-cd <agent-project>
 agent-sdk mcp oauth <connection>
-```
-
-Human completes the browser login. Callback:
-`http://localhost:8787/callback`. Tokens:
-`~/.config/agent-serve/mcp-auth.json` (or `$AGENT_SERVE_CONFIG_DIR`).
-
-Already authorized → command prints that and exits 0. URL change →
-re-run; resource URL binding drops the old entry.
-
-## Phase 2 — Store on the deployment (agent + human)
-
-Requires `agent-sdk login` (or `CURSOR_API_KEY`) and deploy rights.
-
-```bash
-agent-sdk mcp oauth <connection> --store [--slug <slug>] [--team <id>]
+agent-sdk mcp oauth <connection> --store [--slug <slug>]
 agent-sdk secrets list <slug>
-agent-sdk deploy   # or your usual deploy; secrets apply next deploy
+agent-sdk deploy
 ```
 
-`--store` upserts access (required), refresh (if present), and client id
-(if present). It does not remove unrelated secrets.
-
-## Phase 3 — Verify (agent)
-
-Local:
-
-```bash
-agent-sdk validate --dir .
-agent-sdk call <tool-that-uses-host.mcp> --dir .
-# or exercise the same path from the playground
-```
-
-Hosted: confirm egress allowlist includes the MCP host, secrets exist,
-redeploy completed, then exercise the same host tool once.
-
-## Failure table
+Browser callback: `http://127.0.0.1:8787/callback`. Tokens live in
+the CLI config directory (`mcp-auth.json` or
+`$AGENT_SERVE_CONFIG_DIR`). URL change drops the old entry; re-run.
+`--store` does not restart a running engine.
 
 | Symptom | Fix |
 | --- | --- |
-| `must be defineConnection({ url, oauth: true })` | Wrong connection name, or missing `oauth: true` |
-| `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 | 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
+| `must be defineConnection({ url, oauth: true })` | Wrong name or missing `oauth: true` |
+| `Unknown MCP connection` | Filename must match the CLI arg |
+| Callback hang | Free port 8787; finish the browser flow here |
+| Hosted 401 | `secrets list`; `--store`; redeploy |
+| Model invents `mcp_auth` / IDE MCP | `advertiseTools: true` on local turns |
 
-- Don't put raw OAuth tokens in git or in connection source files
-- Don't add `BUGBOTDB_URL` / `AGENT_SERVE_DEPLOYMENT_ID` to `secretNames`
-- Don't use Bun for the CLI (use Node / `tsx`)
-- Don't expect `--store` alone to restart a running engine; redeploy
+No raw tokens in git.