@cursor/july 0.1.94 → 0.1.96

package/skills/framework-map/SKILL.md

@@ -1,165 +1,103 @@
 ---
 name: agentsdk-framework-map
 description: >-
-  Orientation for @cursor/july — folder structure, local vs cloud
-  runtimes, sessions, state layout, and invariants (Node not Bun, root
-  evals/, typecheck after tsx). Use when creating, editing, or running
-  Agent SDK projects with agent/agent.ts and agent/instructions.md.
+  Orient on Agent SDK layout, local vs cloud runtime, sessions, and
+  invariants (Node not Bun, root evals/, typecheck after tsx). Use
+  when creating, editing, or running a project with agent/agent.ts.
 ---
 
 # Agent SDK framework map
 
-`@cursor/july` serves agents defined as ordinary files: markdown
-for prose, TypeScript for typed behavior, under an `agent/` directory. The
-framework discovers the files, compiles a manifest, and serves the agent
-over HTTP/Slack/GitHub channels, with the Cursor SDK + harness as the
-execution engine. Ground truth is the package `README.md` (full reference)
-and `AGENTS.md` (coding-agent loop) — this skill is the map, not the spec.
-
-Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
-host serves the same index at `/docs/llms.txt`.
-
-Run the CLI as `agent-sdk <cmd>`. In the everysphere monorepo there is no
-installed bin — use:
-
-```bash
-cd packages/agent-serve
-pnpm exec tsx src/bin/agent-serve.ts <cmd> ...
-```
-
-## Hard invariants (violating these wastes hours)
-
-1. **Node 22+, never Bun.** Bun's HTTP/2 client corrupts harness
-   tool-result streams (`NGHTTP2_FRAME_SIZE_ERROR`): every built-in
-   read/grep the model makes fails and turns degrade into 8-minute retry
-   loops. All package mise tasks already use tsx.
-2. **Evals live at the project root `evals/`**, never `agent/evals/` (that
-   path is silently ignored).
-3. **tsx strips types without checking them.** `validate`/`run` passing
-   does not mean the code typechecks — run the repo's TypeScript check
-   (in everysphere: `dev check typecheck packages/agent-serve/... --timeout 120`)
-   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. **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`.
-5. **A model turn needs `CURSOR_API_KEY`.** Everything structural
-   (`validate`, `info`, `call`, `serve` bring-up) works without one.
+`@cursor/july` discovers files under `agent/` and serves the agent
+over HTTP, Slack, and GitHub. Markdown is prose. TypeScript is typed
+behavior. Ground truth: package `README.md` and `AGENTS.md`.
+
+CLI is `agent-sdk` (Node, never Bun).
+
+Public docs: `node_modules/@cursor/july/dist/docs/llms.txt` or
+`/docs/llms.txt` on a running host.
+
+## Invariants
+
+1. **Node 22.13+, never Bun.** Bun corrupts harness tool-result
+   streams (`NGHTTP2_FRAME_SIZE_ERROR`).
+2. **Evals live at project-root `evals/`.** `agent/evals/` is ignored.
+3. **tsx does not typecheck.** Tool `execute` must return JSON-shaped
+   values: object literals or `type` aliases, not `interface` types.
+4. **Nested git checkouts.** Discovery sets `local.cwd` to a
+   per-project cache directory under `~/.cache`. Point cwd at a
+   checkout only when the agent must inherit that tree.
+5. **Attached MCP is nameless** until `advertiseTools: true`.
+6. **Model turns need `CURSOR_API_KEY`.** `validate`, `info`, `call`,
+   and `serve` bring-up do not.
 
 ## Folder structure
 
-One file per concept; the path is the identity. Full details for each
-path live under README "Folder structure".
+Path is identity. Full list: README "Folder structure".
 
-| Path | What it is |
+| Path | Role |
 | --- | --- |
-| `agent/agent.ts` | `defineAgent({ model?, runtime?, cloud?, local? })`; model defaults to `grok-4.5` with `effort=high`, `fast=true` |
-| `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. `{ 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) |
-| `agent/ab.ts` or `agent/ab/*.ts` | Live A/B metrics (`defineAB`); sticky `split` + `onSample` |
-| `agent/ab.config.ts` | Optional A/B `maxPlaygroundSessions` / `persistSamples` / `persistSnapshots` |
-| `agent/otel.ts` | OpenTelemetry export (`defineOtel`); also `OTEL_EXPORTER_OTLP_*` env |
-| `agent/schedules/*` | Cron-driven runs (UTC, 5-field; never auto-fire under `--dev`) |
-| `agent/sandbox/workspace/` | Files seeded into each session workspace (local runtime only) |
-| `agent/lib/` | Import-only shared code, never discovered |
-| `evals/**/*.eval.ts` | Filesystem evals; case id = path under `evals/` |
-
-## Local vs cloud runtime
-
-`runtime: "local"` (default) runs turns on the Cursor SDK local harness on
-the serve host; `runtime: "cloud"` runs them on Cursor cloud agents
-(`bc-...` ids, needs `cloud: { repos: [...] }`).
+| `agent/agent.ts` | `defineAgent({ model?, runtime?, cloud?, local? })` |
+| `agent/instructions.md` | Always-on system prompt (required) |
+| `agent/tools/<name>.ts` | One tool. `execution: "server"` or `"agent"` |
+| `agent/skills/*` | On-demand procedures |
+| `agent/mcp-connections/<name>.ts` | MCP. Never name an account file `cursor.ts`. `advertiseTools: true` for named local tools |
+| `agent/host-connections/<name>.ts` | Privileged MCP for `ctx.host.mcp` / `mcp oauth` |
+| `agent/subagents/<id>/` | Child agent (`description` required) |
+| `agent/channels/*.ts` | Slack / GitHub / custom HTTP |
+| `agent/hooks/*.ts` | Observe-only |
+| `agent/ab.ts` or `agent/ab/*.ts` | Live A/B (`defineAB`) |
+| `agent/otel.ts` | OpenTelemetry (`defineOtel`) |
+| `agent/schedules/*` | Cron. Never auto-fire under `--dev` |
+| `agent/sandbox/workspace/` | Session seed files (local only) |
+| `agent/lib/` | Import-only. Never discovered |
+| `evals/**/*.eval.ts` | Case id is the path under `evals/` |
+
+## Local vs cloud
+
+`runtime: "local"` (default) runs on the serve host.
+`runtime: "cloud"` needs `cloud: { repos: [...] }`.
 
 | Capability | local | cloud |
 | --- | --- | --- |
-| Server tools (`execution: "server"`) | yes | yes on managed hosting; self-hosted needs `--public-url` |
+| Server tools | yes | yes on managed hosting; self-hosted needs `--public-url` |
 | Tool approvals | yes | no |
-| Agent tools (`execution: "agent"` scripts) | yes | yes |
-| Skills | yes | yes |
+| Agent tools / skills | yes | yes |
 | sandbox seeds | yes | no |
-| Instructions | `AGENTS.md` in session workspace | prepended to first prompt |
-| Checkout of a repo/PR | you arrange it | the VM carries it |
-
-Rule of thumb: per-PR worktrees on the serve host die at
-"hundreds of engineers issuing PRs" — when the job needs a repo checkout at
-scale, use cloud and keep the host to routing, briefs, and bookkeeping.
-`validate` warns when cloud is combined with local-only capabilities.
-
-## Sessions, tokens, streams
-
-Two handles, two owners:
-
-- **continuationToken:** credential for continuing a conversation. HTTP
-  follow-ups rotate it; stale tokens get `409`.
-- **sessionId** — runtime-owned handle for streaming/inspection
-  (`GET /v1/session/:id/stream?startIndex=N`, durable NDJSON replay).
-
-A follow-up to a busy HTTP/MCP session **interrupts the in-flight turn**
-and waits for it to settle before the new turn sends. Slack uses
-**coalesce** instead (enqueue + boundary drain; see
-`docs/reference/sessions.md`). `POST /v1/session/:id/stop` interrupts
-without sending. Session-bound deterministic tool calls are rejected with
-`409 session_busy` while a turn runs.
-
-Key built-in routes (each agent, under `/<slug>` in multi-agent mode):
-`POST /v1/session`, `POST /v1/session/:id`, `GET /v1/session/:id/stream`,
-`GET /v1/sessions`, `POST /v1/tools/:toolName` (deterministic call),
-`GET/POST /v1/session/:id/approvals[/:callId]`, `GET /v1/info`,
-`GET /v1/health`, and in dev `POST /v1/dev/schedules/:id`,
-`POST /v1/dev/reminders/:id`.
-
-## State layout
-
-```
-<project>/.agent-serve/            # or <stateRoot>/<slug>/ under serve
-  sessions/<id>/session.json       # metadata
-  sessions/<id>/events.ndjson      # durable stream (replayable)
-  sessions/<id>/workspace/         # the harness cwd for that session
-  traces/<sessionId>.ndjson        # written by `run`
-  runner/                          # SDK conversation store
-```
-
-Delete a session directory to forget a conversation.
+| Checkout | you arrange it | the VM carries it |
+
+Use cloud when the job needs a checkout at scale. `validate` warns
+when cloud is combined with local-only capabilities.
+
+## Sessions
+
+- **continuationToken** continues a conversation. HTTP follow-ups
+  rotate it. Stale tokens return `409`.
+- **sessionId** is the inspect handle
+  (`GET /v1/session/:id/stream?startIndex=N`).
+
+A follow-up to a busy HTTP/MCP session interrupts the in-flight
+turn. Slack coalesces. Routes: `docs/reference/http-api.md`.
+Session files live under the project state directory
+(`--state-root`).
 
 ## Where logic belongs
 
-The model is the engine; TypeScript is the boundary layer. Code earns its
-place on the deterministic path for side-effect gates and actuation,
-idempotency/dedupe of external writes, auth/secrets, evidence seeding, and
-hard caps at API boundaries. Formatting, summarizing, classification,
-wording, and composing human-facing output belong to the model, under an
-output contract in instructions/skills — prose lives in `.md` files, not TS
-string builders. When `agent/lib/` + `tools/` dwarf instructions + skills,
-you are usually looking at a service with a vestigial model turn, or at
-framework gaps patched agent-side that should be fixed upstream. The
-budget table and smells: `create-agent/SKILL.md` § "The deterministic-path
-budget".
-
-## The loop
-
-Edit → inspect → run → assert. Canonical commands and flags live in
-`AGENTS.md` (`validate` / `info` / `call` / `run` / `eval` / `serve`).
-Serve only your agent's directory during bring-up — mounting a parent
-folder mounts every sibling agent too.
-
-## Where to go next
-
-- Scaffolding → `packages/agent-serve/skills/create-agent/SKILL.md`
-- Evals → `packages/agent-serve/skills/evals/SKILL.md`
-- Live A/B metrics → `packages/agent-serve/skills/ab/SKILL.md`
-- OpenTelemetry → `packages/agent-serve/skills/otel/SKILL.md`
-- GitHub webhooks → `packages/agent-serve/skills/github/SKILL.md`
-- Slack → `packages/agent-serve/skills/setup-slack/SKILL.md`
-- Host MCP OAuth → `packages/agent-serve/skills/mcp-auth/SKILL.md`
-- Local triage → `packages/agent-serve/skills/debug/SKILL.md`
-- Measured improvement → `packages/agent-serve/skills/hillclimb/SKILL.md`
-- Dogfood / deploy → `packages/agent-serve/skills/operate/SKILL.md`
+Code: side-effect gates, write dedupe, auth, evidence seeding, hard
+API caps. Model: formatting, summarizing, classification, replies.
+Budget: `skills/create-agent/SKILL.md`.
+
+Loop: `validate` / `info` / `call` / `run` / `eval` / `serve`. Serve
+only this agent's directory.
+
+| Task | Skill |
+| --- | --- |
+| Scaffold | `skills/create-agent/SKILL.md` |
+| Evals | `skills/evals/SKILL.md` |
+| Live A/B | `skills/ab/SKILL.md` |
+| OpenTelemetry | `skills/otel/SKILL.md` |
+| GitHub | `skills/github/SKILL.md` |
+| Slack | `skills/setup-slack/SKILL.md` |
+| Host MCP OAuth | `skills/mcp-auth/SKILL.md` |
+| Local triage | `skills/debug/SKILL.md` |
+| Measured improvement | `skills/hillclimb/SKILL.md` |

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.