@cursor/july 0.1.94 → 0.1.96

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.

package/skills/otel/SKILL.md

@@ -1,80 +1,48 @@
 ---
 name: agentsdk-otel
 description: >-
-  Wire OpenTelemetry export for an Agent SDK agent (defineOtel, OTLP env,
-  traces/metrics/logs, ctx.host.otel). Use when adding observability,
-  Datadog/Grafana/OTLP export, session/turn/tool tracing, or custom metrics.
+  Wire OpenTelemetry export (defineOtel, OTLP env, traces/metrics/logs,
+  ctx.host.otel). Use when adding collector export or custom metrics.
 ---
 
 # Agent SDK OpenTelemetry (`defineOtel`)
 
-Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
-host serves the same index at `/docs/llms.txt`.
+Push traces and metrics from the serve process to an OTLP
+collector. Logs are off until you opt in.
 
-Push session, turn, tool, and subagent traces, plus token and cost
-metrics, from the serve process to an OTLP collector. Logs are off
-until you opt in.
-
-Read [OpenTelemetry](../../docs/guides/opentelemetry.md) for the full
-guide, including how this joins Cursor enterprise export.
+Guide: `docs/guides/opentelemetry.md`.
 
 ## Enable
 
 Any one of:
 
-1. **Env.** Set `OTEL_EXPORTER_OTLP_ENDPOINT` (and optional
+1. `OTEL_EXPORTER_OTLP_ENDPOINT` (optional
    `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_HEADERS`,
-   `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf|http/json`).
-   Per-signal URLs work when the base URL is unset:
-   `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `_METRICS_ENDPOINT` /
-   `_LOGS_ENDPOINT`.
-2. **Authored.** `agent/otel.ts`:
+   `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf|http/json`)
+2. `agent/otel.ts`:
 
 ```ts
 import { defineOtel } from "@cursor/july/otel";
 
 export default defineOtel({
   serviceName: "cursor",
-  exporters: [
-    {
-      url: "https://otel.example.com",
-      protocol: "http/protobuf",
-      headers: { Authorization: "Bearer …" },
-    },
-  ],
+  exporters: [{ url: "https://otel.example.com", protocol: "http/protobuf" }],
 });
 ```
 
-3. **Programmatic.** `serve(dir, { otel: { … } })`. Pass `otel: false`
-   to disable even when env or `agent/otel.ts` are set.
-
-Multiple `exporters` fan out. Default protocol is `http/protobuf`.
-Use `http/json` only when the collector requires it. `grpc` is ignored.
-
-Precedence: `serve({ otel })` over `agent/otel.ts` over env.
-
-## Signals
-
-| Signal | Default | What |
-| --- | --- | --- |
-| Traces | on | `agent_sdk.http` → `agent_sdk.session` → `agent_sdk.turn` → `agent_sdk.tool` / `agent_sdk.subagent` |
-| Metrics | on | `cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`, plus `agent_sdk.*` counts and HTTP duration |
-| Logs | off | Opt in with `logs: true`, `OTEL_LOGS_EXPORTER=otlp`, or `OTEL_LOG_USER_PROMPTS=1` / `OTEL_LOG_TOOL_CONTENT=1` |
+3. `serve(dir, { otel: { … } })`. `otel: false` disables env and
+   authored config.
 
-Prompt text, tool payloads, and failure text stay off the wire unless
-those flags are set.
+| Signal | Default |
+| --- | --- |
+| Traces | on (`agent_sdk.http` → session → turn → tool / subagent) |
+| Metrics | on (`cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`) |
+| Logs | off (`logs: true` or `OTEL_LOGS_EXPORTER=otlp`) |
 
-## Custom metrics (`ctx.host.otel`)
+Prompt text and tool payloads stay off the wire unless you set
+`OTEL_LOG_USER_PROMPTS` / `OTEL_LOG_TOOL_CONTENT`.
 
-Always present. `increment` / `record` no-op without a meter.
-`setAttributes` still tags the open session when a collector is
-attached. Prefix names with team or agent. No custom spans. Reserved
-metric names: `cursor.token.usage`, `cursor.tool.calls`,
-`cursor.cost.usage`, `agent_sdk.session.count`,
-`agent_sdk.turn.count`, `agent_sdk.subagent.count`,
-`agent_sdk.http.duration`. Reserved attributes:
-`cursor.conversation.id`, `agent_sdk.agent`, `agent_sdk.turn_id`,
-`agent_sdk.framework`.
+## Custom metrics
 
 ```ts
 ctx.host.otel.setAttributes({ "abc.ticket_id": "INC-123" });
@@ -82,20 +50,6 @@ ctx.host.otel.increment("abc.ticket.resolved");
 ctx.host.otel.record("abc.approval.duration_ms", 1420);
 ```
 
-## Attributes worth joining on
-
-- `cursor.conversation.id` (session id)
-- `cursor.tool.name` / `cursor.tool.kind` / `cursor.tool.status`
-- `cursor.token.type`, `cursor.model.name`
-- `agent_sdk.agent`, `agent_sdk.turn_id`, `agent_sdk.call_id`, `agent_sdk.channel`
-
-Resource defaults: `service.name=cursor`, `cursor.entrypoint=sdk_ts`,
-`cursor.surface=unspecified`.
-
-Inbound HTTP extracts W3C `traceparent`, so a channel request parents
-the session span when the turn starts in that request.
-
-If another TracerProvider already owns the process (CLI / IDE), Agent
-SDK reuses it. Run `serve` as its own process when Agent SDK should
-own the destination. Conflicting `agent/otel.ts` files across mounts
-fail at serve start.
+Prefix names with team or agent. No custom spans. Join on
+`cursor.conversation.id` and `agent_sdk.agent`. Run `serve` as its
+own process when Agent SDK should own the destination.