@cursor/july 0.1.95 → 0.1.97

package/skills/create-agent/SKILL.md

@@ -1,142 +1,99 @@
 ---
 name: agentsdk-create-agent
 description: >-
-  Scaffold a new Agent SDK agent through a guided AskQuestion interview —
-  purpose, name, runtime, model, channels, MCP connections, capabilities —
-  then verify it serves and hand off to hillclimbing. Read this skill when
-  creating a new agent.
-paths:
-  - packages/agent-serve/**/*
+  Scaffold a new Agent SDK agent: short AskQuestion interview, then
+  verify a turn and hand off to hillclimb. Use when creating a new
+  agent. Ask only what the invoking message left open.
 ---
 
 # Create an Agent SDK agent
 
-Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
-host serves the same index at `/docs/llms.txt`.
+1. **Interview.** Two `AskQuestion` rounds, then a plan gate.
+2. **Scaffold.** `agent-sdk init`, then shape the files.
+3. **Verify.** `validate` / `info` / `call`, then a model turn.
+4. **Channels.** Slack, GitHub, webhook, or schedule as chosen.
+5. **Hillclimb.** `skills/hillclimb/SKILL.md`.
 
-Stand up one new agent project via a short interview, scaffold it, get
-channels working
-with the user, prove a turn runs end-to-end, and set up the improvement loop.
-Sibling skills: `framework-map` for orientation, `setup-slack` for Slack
-wiring, `mcp-auth` for host MCP OAuth, `github` for webhook-driven
-agents, `evals` for the eval API, `ab` for live A/B metrics, `otel` for
-OpenTelemetry export, `hillclimb` for iteration once the agent runs.
-
-Read `framework-map/SKILL.md` first if you haven't; treat the package
-`AGENTS.md` and `README.md` as ground truth for
-framework behavior. Run the CLI with Node, never Bun (Bun corrupts harness
-tool-result streams): use the installed `agent-sdk` bin, or from a source
-checkout `pnpm exec tsx src/bin/agent-serve.ts <command> …` — written as
-`agent-sdk …` below.
+Read `skills/framework-map/SKILL.md` if you have not. CLI is
+`agent-sdk`. Public docs:
+`node_modules/@cursor/july/dist/docs/llms.txt` or `/docs/llms.txt`
+on a running host.
 
 ## Interview
 
-Walk the user through the decisions with the `AskQuestion` tool: batched
-questions, concrete options, the recommended option listed first and labeled
-`(recommended)` so one click accepts it. Rules:
-
-- **Mine the invoking message first.** Never ask a question it already
-  answers. Target: at most two rounds before files appear.
-- **Stage the rounds.** Round 1 fixes identity; round 2 fixes the surface and
-  is tailored by round 1 (no MCP question for a chat toy, no cloud-repos
-  question for local runtime).
-- Use multi-select (`allow_multiple: true`) for channels, MCP connections, and
-  capabilities; single-select elsewhere. Add an "Other" option wherever a
-  custom answer is plausible (name, model, MCP server) — its freeform text is
-  the answer.
-- **Ask about decisions, not implementation.** Instructions wording, tool
-  names, file layout, env prefix, and eval shape are your job — derive them
-  from the purpose and show the result instead of asking.
-- If `AskQuestion` is unavailable or the user says "just go", state the
-  defaults you are assuming in one short list and proceed.
-
-### Round 1 — identity
+`AskQuestion`: batched, recommended option first and labeled
+`(recommended)`.
+
+- Mine the invoking message. Target: two rounds, then files.
+- Round 1 is identity. Round 2 is the surface, tailored by round 1.
+- Multi-select for channels, MCP, capabilities. Other where a
+  custom answer is plausible.
+- Ask decisions, not how to build it. File layout, tool names,
+  env prefix, and eval shape are yours.
+- If `AskQuestion` is missing or the user skips, state defaults
+  in one list and proceed.
+
+### Round 1: identity
 
 | Question | Options |
 | --- | --- |
-| **Purpose** | chat assistant · PR / repo automation · domain assistant over APIs/tools · scheduled reporter · Other (describe) |
-| **Name** | 2–3 slug suggestions derived from the purpose + Other. Slug = directory name: `[A-Za-z0-9][A-Za-z0-9_-]*`, not `v1`/`playground`/`docs`; lowercase-hyphenated |
-| **Location** | `./<slug>` (default) · another directory (user names it) |
+| **Purpose** | chat assistant · PR / repo automation · domain assistant over APIs/tools · scheduled reporter · Other |
+| **Name** | 2–3 slugs from the purpose + Other. Directory: `[A-Za-z0-9][A-Za-z0-9_-]*`, not `v1`/`playground`/`docs` |
+| **Location** | `./<slug>` (default) · another directory |
 
-### Round 2 — surface
+### Round 2: surface
 
 | Question | Options | Guidance |
 | --- | --- | --- |
-| **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 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
-intend to create — and a final gate: "Scaffold it" / "Adjust something". Only
-write files after approval.
+| **Runtime** | `local` (default) · `cloud` | Cloud needs `cloud.repos`. Approvals and sandbox seeds are local only. Recommend local unless the job needs a cloud checkout. |
+| **Model** | `grok-4.5` + `effort=high`, `fast=true` · Other id | Params, not id suffixes: `{ id: "grok-4.5", params: [{ id: "effort", value: "high" }, { id: "fast", value: "true" }] }` |
+| **Channels** (multi) | playground + HTTP (always on) · Slack · GitHub · custom webhook · schedule | Slack: `skills/setup-slack/SKILL.md`. GitHub: `skills/github/SKILL.md`. No Discord/Teams pack; offer custom webhook. |
+| **MCP** (multi) | none · remote URL · local stdio · Cursor account connectors · Other | One file under `agent/mcp-connections/`. Account file is `account.ts`, never `cursor.ts`. Named local tools need `advertiseTools: true`. Privileged servers go in `agent/host-connections/`. |
+| **Capabilities** (multi) | server tools · agent tools · skills · subagents · hooks · sandbox seeds · approvals · evals (recommend) | Always recommend one smoke eval. |
 
-## Fill in the blanks
+Close with the plan and file tree, then "Scaffold it" / "Adjust
+something". Write files only after approval.
 
-Everything the interview did not fix is yours to decide. Derive it from the
-purpose, and reach for the proven shape instead of
-inventing:
+## Fill the blanks
 
-| Purpose looks like | Proven shape |
+| Purpose | Shape |
 | --- | --- |
-| 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 |
-| Wrap an existing pipeline/tool | GitHub `{ task }` hook driving a deterministic loop under `agent/lib/` |
-
-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
+| Slack chat | `slackChannel({ envPrefix })` + suggested prompts. `agent-sdk slack create` mints the bot. Prefix: `skills/setup-slack/SKILL.md` |
+| PR review with host prep | Channel `callTool` into a trimmed workspace `pr/` tree |
+| GitHub automation | `githubChannel()` hooks, replay fixtures |
+| Domain assistant | Server tools + one MCP connection + a skill |
+| Wrap an existing pipeline | GitHub `{ task }` over a thin `agent/lib/` loop |
+
+Defaults:
+
+- Instructions + 1–2 tools + chosen channels + one smoke eval.
+- `local.cwd` stays outside a monorepo checkout (default: a cache
+  directory under `~/.cache`) unless 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
-  `execution: "server"` with a zod `inputSchema`; use `execution: "agent"`
-  (script) only when the tool must run where the agent runs (or runtime is
-  cloud). Gate side-effecting tools with `needsApproval: true`. For long
-  tool descriptions, reminder prompts, channel `context`, and errors, use
-  `prompt\`…\`` / `prompt.lines\`…\`` from `@cursor/july` (dedents indented
-  multi-line strings).
-- **Env prefix** for Slack tokens = upper-snake slug (`my-agent` →
-  `MY_AGENT_SLACK_*`); `agent-sdk slack create` derives it for you.
-- **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
-  instructing the model to do it. Stop there: host code that formats,
-  summarizes, classifies, or composes replies is the model's job specified
-  badly, and it never comes off the books.
-
-### The deterministic-path budget
-
-TypeScript on the deterministic path is a permanent liability — every line
-brings types, tests, restarts, and drift against the framework; prose is
-cheap to change. Default every behavior to instructions/skills and promote
-it to code only when it earns a row on the left:
-
-| Code owns (earns its keep) | Model owns (keep out of code) |
+- `agent/instructions.md`: identity, when to use which tool,
+  output shape.
+- One tool per file. Prefer `execution: "server"` + zod
+  `inputSchema`. Gate side effects with `needsApproval: true`.
+- Long prompts: `prompt\`…\`` / `prompt.lines\`…\`` from
+  `@cursor/july`.
+- Host prep is for evidence (`callTool`, `workspaceFiles`), not
+  judgment, formatting, or replies.
+
+### Deterministic-path budget
+
+Default to instructions and skills. Promote to TypeScript only
+when it earns the left column:
+
+| Code owns | Model owns |
 | --- | --- |
-| Side-effect gates and actuation (approve, deploy, post) | Composing human-facing output — replies, reports, comments, tables — to a shape stated in instructions |
-| Idempotency / dedupe of external writes | Summarizing, classifying, wording, judgment calls |
-| Auth, secrets, signature verification | Deciding what to do next from ground truth |
-| Evidence seeding (`workspaceFiles`, channel `callTool` prep) | Interpreting soft failures and choosing retries |
-| Hard caps at API boundaries (chunk limits, truncation) | Formatting niceties (links, emphasis, ordering) under those caps |
-
-Two smells to check before scaffolding and again before hand-off:
-
-- **Prose in TS.** An `instructions.ts` / `prompt.ts` string builder is a
-  skill file wearing a trench coat — write `.md` and interpolate only what
-  is truly dynamic.
-- **Inverted ratio.** A first cut whose `agent/lib/` + `tools/` dwarf its
-  instructions + skills (~3:1 or worse) is either wrapping an existing
-  deterministic pipeline (fine — keep the wrapper thin and say so) or
-  building a service with a vestigial model turn. Move procedure back into
-  prompts, or question whether this should be an agent at all.
+| Side-effect gates (approve, deploy, post) | Human-facing output to a stated shape |
+| Dedupe of external writes | Summarizing, classifying, wording |
+| Auth and signature checks | What to do next from ground truth |
+| Evidence seeding | Soft-failure retries |
+| Hard API caps | Formatting under those caps |
+
+Smells: prose builders in `.ts` (write `.md`); `agent/lib/` +
+`tools/` dwarfing instructions + skills on a first cut.
 
 ## Scaffold
 
@@ -144,124 +101,68 @@ Two smells to check before scaffolding and again before hand-off:
 agent-sdk init ./<slug>
 ```
 
-`init` writes `package.json` (with `typescript` dev deps and a
-`check` script), `tsconfig.json`, `AGENTS.md`, `.gitignore`, `agent/agent.ts`,
-`agent/instructions.md`, a demo `agent/tools/echo.ts`, and
-`agent/hooks/memory.ts`. Existing files are left alone (`exist`). 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
-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({...})`. 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>/`
-   (needs `description`), `schedules/`, `hooks/`, `sandbox/workspace/`. For
-   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`).
-5. `evals/evals.config.ts` — `defineEvalConfig({ maxConcurrency: 20 })`
-   (playground runs are memory-only unless you add `persistRuns`)
-   (`maxConcurrency` is required; hard-capped at 200 due to model provider
-   request limits) plus eval cases under `evals/**/*.eval.ts` — prefer one
-   suite file with `cases: [{ id, test }, …]` for related datapoints, or a
-   single `test` for one smoke. Assert `t.succeeded()` + `t.calledTool(...)`
-   (case id = file path, or `<fileId>/<case.id>`). Full assertion API and
-   fixture strategy: `evals/SKILL.md` (sibling skill).
-
-Stick to deps the Agent SDK already
-ships (`zod`, `@modelcontextprotocol/sdk`, `tsx`); a new npm dep needs its own
-install story and is a smell for a first cut.
+`init` writes the project, runs `npm install`, and may wait on
+`login`. Then shape it:
+
+1. `defineAgent` with the chosen model/runtime. Add
+   `cloud: { repos: [...] }` for cloud.
+2. Real `instructions.md`. Replace `echo.ts`.
+3. Chosen `channels/`, `mcp-connections/`, `skills/`,
+   `subagents/<id>/` (needs `description`), `schedules/`, `hooks/`.
+   Slack: `agent-sdk slack create --dir ./<slug> --name "<Name>"`,
+   not a hand-written channel. Manual Slack app:
+   `agent-sdk slack init --manual` (Slack CLI, or paste at
+   api.slack.com).
+4. `evals/evals.config.ts` with `maxConcurrency: 20` (required;
+   cap 200) plus `evals/**/*.eval.ts`. Assert `t.succeeded()` +
+   `t.calledTool(...)`. API: `skills/evals/SKILL.md`.
+
+Stay on deps the Agent SDK already ships (`zod`,
+`@modelcontextprotocol/sdk`, `tsx`).
 
 ## Verify
 
-No API key needed for the structural half — run these first and fix every
-error diagnostic:
-
 ```bash
-agent-sdk validate --dir ./<slug>            # zero errors (warnings explain runtime mismatches)
-agent-sdk info --dir ./<slug> --json         # surface matches the plan
-agent-sdk call <tool> --dir ./<slug> --input '{…}'   # server tools, deterministic, no model
+agent-sdk validate --dir ./<slug>
+agent-sdk info --dir ./<slug> --json
+agent-sdk call <tool> --dir ./<slug> --input '{…}'
 agent-sdk eval --dir ./<slug> --list
-npx tsc --noEmit -p ./<slug>                   # or the project's own type-check task
+npx tsc --noEmit -p ./<slug>
 ```
 
-The typecheck matters: everything above runs through tsx, which strips types
-without checking them. The classic miss is a tool `execute` return that does
-not satisfy `ToolExecuteResult` — returns must be JSON-shaped
-(`ToolResultValue`), so use plain object literals or `type` aliases, not
-`interface` types (their lack of an index signature fails assignability).
+tsx does not typecheck. Tool `execute` must return JSON-shaped
+values: object literals or `type` aliases, not `interface` types.
 
-`serve` also boots without a key (good for checking channel mounts and the
-playground shell), but model turns need `CURSOR_API_KEY` — ask the user for
-one if the environment lacks it (minted in the Cursor dashboard). If no key
-is forthcoming, finish every key-free check, confirm `run` fails with only
-the clean API-key error, and hand these to the user as their next steps:
+Model turns need `CURSOR_API_KEY`. Without one, finish the
+key-free checks, confirm `run` fails with only the API-key error,
+and hand these over:
 
 ```bash
-agent-sdk run --dir ./<slug> --message "<fixture prompt>"   # JSON trajectory
-agent-sdk serve --dir ./<slug> --dev
-# playground: http://127.0.0.1:3000/<slug>/playground
+agent-sdk run --dir ./<slug> --message "<fixture prompt>"
+agent-sdk serve --dir ./<slug> --mode single --dev
+# http://127.0.0.1:3000/playground
 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). 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
-
-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: `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
-  `localDevStrict()` is loopback-only; add `bearerAuth(...)` before any
-  tunnel or shared host.
-- **Schedules** — never auto-fire under `--dev`; dispatch via
-  `POST /<slug>/v1/dev/schedules/<id>`.
-
-## Hand off to hillclimbing
-
-Scaffolding proves the agent runs; it says nothing about quality. Once the
-smoke turn passes, propose the improvement loop — one last `AskQuestion` if
-choices are open:
-
-1. **Fixtures** — 1–3 fixed inputs worth optimizing against (a real PR URL, a
-   canonical Slack question, a saved webhook payload).
-2. **Success criteria** — what "better" means first (correct tool choice,
-   fewer tool calls, faster wall time, output quality).
-3. **Freeze line** — what must not change (API contract, output shape).
-
-Those are exactly the preconditions in `skills/hillclimb/SKILL.md`; suggest
-the user (or you) follow that skill with the fixtures you agreed on. Seed
-the loop by pointing
-at the smoke run's session (`.agent-serve/<slug>/sessions/<id>/events.ndjson`
-or the trace under `.agent-serve/traces/`) as the baseline measurement — or,
-when no API key was available, name the user's first real turn as the
-baseline instead. For GitHub agents, snapshot replay fixtures now
-(`agent-sdk github replay ... --dry-run --out fixtures/github`) so the
-loop starts deterministic.
-
-## Working agreements
-
-- Interview → plan gate → scaffold → verify → channel setup → hillclimb
-  handoff. Do not skip verification because the files "look right".
-- Fill blanks yourself. Re-ask only when an answer contradicts the framework,
-  such as approval-gated tools on the cloud runtime.
-- Do not deploy, post to real Slack/GitHub surfaces beyond the smoke tests the
-  user asked for, or commit without being asked.
-- Keep the first cut reviewable: if the plan grows past ~10 files, cut scope
-  and say what you deferred. Re-check the deterministic-path budget at
-  hand-off — behavior that crept into `lib/` during bring-up (formatting,
-  reply shaping, classification) goes back into instructions before you call
-  it done.
+Serve only this agent's directory. Session files land in the
+project state directory (`--state-root`). That is not harness cwd.
+
+## Channel setup
+
+- **Slack.** `skills/setup-slack/SKILL.md`
+- **GitHub.** `skills/github/SKILL.md`
+- **Custom webhook.** `POST /v1/channels/<id>/<route>`.
+  Loopback-only until you add `bearerAuth(...)`.
+- **Schedules.** Never auto-fire under `--dev`.
+  `POST /v1/dev/schedules/<id>`.
+
+## Hillclimb handoff
+
+Once a smoke turn passes, agree fixtures, success criteria, and a
+freeze line, then follow `skills/hillclimb/SKILL.md`. Seed from
+the smoke session under the project state directory. GitHub:
+snapshot `agent-sdk github replay ... --dry-run --out fixtures/github`.
+
+Do not deploy or post to real Slack/GitHub beyond the smoke the
+user asked for. If the plan grows past ~10 files, cut scope.
+Re-check the budget at hand-off.

package/skills/debug/SKILL.md

@@ -1,78 +1,44 @@
 ---
 name: agentsdk-debug
 description: >-
-  Diagnose a misbehaving Agent SDK agent, server, or playground — blank
-  playground, sessions missing, HMR not reloading, failing reads/retry
-  loops, webhook 401s, 403/409 responses, approvals or reminders lost,
-  orphaned processes. Use when an Agent SDK project runs but behaves
-  wrong locally.
+  Diagnose a misbehaving local Agent SDK agent: blank playground,
+  missing sessions, failed reads, webhook 401s, 403/409, lost
+  approvals. Use when a project runs but behaves wrong locally.
 ---
 
 # Debugging the Agent SDK locally
 
-Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
-host serves the same index at `/docs/llms.txt`.
+Local `agent-sdk serve`. Hosted start or health failures:
+`docs/troubleshooting.md` and `docs/deployment.md`.
 
-This skill is **local** `agent-sdk serve` / playground. A **hosted**
-deployment that is stopped, slow to start, or failing `/v1/health` is
-`.cursor/skills/debugging/debug-agent-serve-deployment/SKILL.md`.
+1. **Validate.** `agent-sdk validate --dir <project>`
+2. **Info.** `curl -s http://127.0.0.1:3000/<slug>/v1/info | jq .`
+3. **Trace.** Session events under the project state directory.
+   Then match the table.
 
-Read `framework-map/SKILL.md` (sibling skill) first if you don't know the
-project structure or session model. Everything below assumes Node/tsx (`pnpm exec tsx
-src/bin/agent-serve.ts ...` in the everysphere monorepo).
-
-## Triage in order
-
-```bash
-# 1. Is discovery clean? serve refuses to start on error diagnostics.
-agent-sdk validate --dir <project>
-
-# 2. What is actually running, and where?
-lsof -iTCP:3000 -sTCP:LISTEN; lsof -iTCP:5273 -sTCP:LISTEN
-ps aux | rg -i 'agent-serve|vite' | rg -v rg
-
-# 3. What does the server think it serves?
-curl -s localhost:3000/v1/agents | jq .        # multi-agent index
-curl -s localhost:3000/<slug>/v1/info | jq .   # per-agent surface
-
-# 4. What did the session actually do? The stream never lies.
-curl -sN 'localhost:3000/<slug>/v1/session/<id>/stream?startIndex=0' | head -50
-# or read <stateRoot>/<slug>/sessions/<id>/events.ndjson directly
-```
-
-## Symptom → cause
-
-| Symptom | Cause / fix |
+| Symptom | Fix |
 | --- | --- |
-| Playground blank or "no agents" even though Vite assets are built | The SPA is static; it needs the Agent SDK backend on `:3000`. Start `serve` — building `dist/playground/` alone serves nothing. |
-| Edits under `playground/src` don't show up in the browser | You're on the **static** `dist/playground` bundle, not HMR. Only `serve --dev` / `dev` starts Vite HMR (`:5273`) and prints that as `playground` — open that URL, not `:3000`. In the monorepo, `mise //packages/agent-serve:start` = all examples + multi-agent HMR; pin one slug with `AGENT_SERVE_BASE=/<slug>`. |
-| Webhook / schedule sessions exist on disk but the playground session list is empty | The list shows the calling principal's sessions. `--dev` (loopback) or `--allow-anonymous` (trusted shared host) switches it to `includeAll`. Otherwise deep-link `/<slug>/playground?sessionId=ses_...` or read `sessions/` on disk. |
-| 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 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 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`). |
-| Reminder disarmed after restart with `handler_lost_on_restart` | `run`-handler reminders are in-memory; re-arm them from the code path that created them (enroll hook / policy), or use prompt-based reminders. |
-| `409` on a follow-up | Stale `continuationToken` (each accepted follow-up rotates it), busy session, or a task/schedule session (not followable). |
-| `409 session_busy` on `agent-sdk call --session` | Session-bound deterministic calls serialize with model turns; wait or use an ephemeral call (drop `--session`). |
-| `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. 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`). |
-
-## Reading a turn like an expert
-
-- `actions.requested` / `action.result` pairs are the tool trajectory;
-  count them by `toolName` before blaming latency, and split **host** work
-  (channel `callTool`, prep) from **model** tools.
-- `turn.failed` with `"turn interrupted"` means a follow-up or `/stop`
-  preempted it — that's the designed behavior, not a crash.
-- Escapes outside the session workspace in read/grep paths mean the
-  harness is fighting your evidence layout, not that the model is broken.
-- `agent-sdk trajectory --events <file>` renders any saved NDJSON.
+| Playground blank / "no agents" | Start `serve`. A built SPA with no backend serves nothing. |
+| Playground UI edits do not show | Open the URL `serve --dev` prints as `playground`, not `:3000`. |
+| Sessions on disk, empty playground list | List is the calling principal. `--dev` or `--allow-anonymous` shows all. Or `?sessionId=ses_...`. |
+| Built-in read/grep fail; retry loops | Bun. Rerun under Node. The tell is `NGHTTP2_FRAME_SIZE_ERROR`. |
+| `github forward` 401s; hook created | Blank `GITHUB_TOKEN`/`GH_TOKEN`. Relay uses `gh` login. |
+| `Hook already exists` | One forwarder per repo. `forward --dir <parent>`. |
+| Answers cite ancestor `AGENTS.md` | Nested checkout. Default `local.cwd` is a cache directory under `~/.cache`. |
+| Model lists IDE `cursor` tools, never MCP | `advertiseTools: true`. Check `GET /v1/info`. |
+| Port 3000 in use | `lsof -iTCP:3000 -sTCP:LISTEN` and kill that pid. |
+| Approval vanished after restart | Parked calls do not survive restart. Re-run. |
+| Schedule / reminder silent under `--dev` | Dev never auto-fires. `POST /<slug>/v1/dev/schedules/<id>`. |
+| `409` on follow-up | Stale `continuationToken`, busy session, or a task session. |
+| `409 session_busy` on `call --session` | Wait, or drop `--session`. |
+| `403` on stream | Wrong principal. Same auth as create; beyond loopback send `--bearer-token`. |
+| Works on loopback, blocked via tunnel | `localDevStrict()` rejects forwarded headers. Use `--bearer-token`. Never `--allow-anonymous` with account MCP. |
+| Slack `channel idle … missing credentials` | Expected. `slack doctor --prefix <PREFIX>`. |
+| Immediate API-key error | Model turns need `CURSOR_API_KEY`. |
+| Approvals or sandbox seeds missing | `runtime: "cloud"`. Those are local only. `validate` warns. |
+| `validate` clean, CI typecheck fails | tsx skipped types. JSON-shaped returns; `type` not `interface`. |
+
+Count `action.result` by `toolName` before blaming latency.
+`turn.failed` + `"turn interrupted"` is a follow-up or stop, not a
+crash. `agent-sdk trajectory --events <file>` renders a saved
+trace.