@cursor/july 0.1.95 → 0.1.97

package/docs/templates/agents-md.md

@@ -0,0 +1,110 @@
+---
+title: "Keep AGENTS.md current from last week's work"
+description: "Scaffold the agent, pick a repo and Slack channels, dispatch the weekly job, and deploy."
+---
+
+# Keep AGENTS.md current from last week's work
+
+This agent runs every Monday at 09:00 UTC. It reads last week's merged
+pull requests and the Slack channels you list. When a durable rule
+showed up, `apply_agents` parks the write until a person approves it,
+then opens a draft follow-up pull request against the default branch.
+Chores and rules the file already states stay quiet.
+
+This template is one model turn: read the week, then call
+`apply_agents`.
+
+Init once per app. Pass a different repo and channel list each time.
+
+## Scaffold
+
+```bash
+npx @cursor/july init ./agents-md --template agents-md
+```
+
+`init` asks which GitHub repo to watch and which Slack channels to
+read. Pass `--var repos=acme/api --var slack=#eng-api,#api-private`
+to skip the prompt. Use `--var slack=none` when Slack is out of
+scope.
+
+The answers land in `agent/lib/config.ts`. Edit that file when the
+set changes.
+
+## Connect GitHub and Slack
+
+Connect GitHub in Cursor for that repository (Settings or
+[cursor.com/dashboard](https://cursor.com/dashboard)). Sign the host
+in:
+
+```bash
+cd agents-md
+agent-sdk login
+```
+
+`cursorAccount` mints a short-lived, repo-scoped credential with
+`contents-write` so the agent can open the follow-up PR. See the
+[GitHub guide](../guides/github.md).
+
+Create the Slack app and invite the bot to each listed channel,
+including private ones:
+
+```bash
+agent-sdk slack create --dir .
+```
+
+See the [Slack guide](../guides/slack.md).
+
+## First weekly run
+
+```bash
+agent-sdk dev
+```
+
+Schedules never fire under `dev`. Dispatch the same path production
+uses:
+
+```bash
+curl -X POST http://127.0.0.1:3000/v1/dev/schedules/weekly
+```
+
+The playground can run `/queue/run` too.
+
+The host writes `week/prs.md`, `week/slack.md`, `week/window.txt`,
+and `week/tree/**.txt` snapshots of the current `AGENTS.md` files,
+then starts a model turn. The
+model calls `apply_agents` once. A skip finishes. An update parks in
+the playground until someone approves; then a draft PR opens against
+the repository default branch. Later updates to the same base stack
+on `agents-md/<base>`. Pull requests from those branches are ignored
+so the follow-up cannot feed the next week.
+
+Chat replies stay in the playground. `apply_agents` records a skip,
+or parks the write. Approve there or with
+`POST /v1/session/:id/approvals/:callId`.
+
+## What to edit
+
+- `agent/lib/config.ts`: repo and Slack channels
+- `agent/instructions.md`: what counts as an update
+- `evals/agents.eval.ts`: smoke cases
+
+## Evals
+
+Four smoke cases: a lint-only week, a billing rule that parks the
+write, the same rule already in `AGENTS.md`, and an empty week.
+
+```bash
+agent-sdk eval
+```
+
+Eval sessions skip the GitHub write.
+
+## Deploy
+
+```bash
+agent-sdk deploy
+```
+
+Run it from the agent's git checkout. The command infers repository,
+ref, path, and slug. Production fires the Monday cron. The deployment
+uses the team's Cursor GitHub connection for the watched repo.

package/docs/templates/code-wiki.md

@@ -0,0 +1,96 @@
+---
+title: "Keep a code wiki current after merge"
+description: "Scaffold the agent, pick repos, replay a merged PR, and deploy."
+---
+
+# Keep a code wiki current after merge
+
+This agent wakes when a watched pull request merges. It reads the diff
+and the in-repo `wiki/` pages. When a durable fact changed, it opens a
+follow-up pull request with the page edits. Chores, cherry-picks, and
+wiki-only merges stay quiet.
+
+This template is one model turn: read the merge, then call `apply_wiki`.
+
+## Scaffold
+
+```bash
+npx @cursor/july init ./code-wiki --template code-wiki
+```
+
+`init` asks which GitHub repos to watch. Every repo must share one
+owner. Pass `--var repos=acme/api,acme/web` to skip the prompt.
+
+The list lands in `agent/lib/repos.ts`. The GitHub channel reads it for
+`cursorAccount` and for the wake filter. Edit that file when the set
+changes.
+
+Pages live in `wiki/` at the repository root. Keep them flat markdown.
+Add `wiki/_index.md` as the catalog.
+
+## Connect GitHub through Cursor
+
+Connect GitHub in Cursor for those repositories (Settings or
+[cursor.com/dashboard](https://cursor.com/dashboard)). Sign the host in:
+
+```bash
+cd code-wiki
+agent-sdk login
+```
+
+`cursorAccount` pulls SCM events from Cursor and mints a short-lived,
+repo-scoped credential with `contents-write` so the agent can open the
+follow-up PR. See the [GitHub guide](../guides/github.md).
+
+## First update
+
+```bash
+agent-sdk dev
+```
+
+`dev` starts the Cursor event relay for the watched repos. To drive a
+known merge without waiting on a live push:
+
+```bash
+agent-sdk github replay https://github.com/acme/api/pull/12 --dir . --action closed
+```
+
+`replay` needs pull access. The payload must be a merged PR (`closed`
+and `merged`). Repos outside `agent/lib/repos.ts`, wiki-only merges,
+and branches named `wiki/*` are ignored so the follow-up PR cannot
+wake the agent again.
+
+The channel writes `pr/base.ref`, `pr/files.txt`, `pr/diff.patch`, and
+the current `wiki/` pages, then starts a model turn. The model calls
+`apply_wiki` once. The follow-up PR targets that merge's base. Later
+updates to the same base stack on `wiki/<base>`.
+
+Chat replies stay in the playground. `apply_wiki` opens the GitHub
+pull request, or records a skip.
+
+## What to edit
+
+- `agent/lib/repos.ts`: watched repos
+- `agent/instructions.md`: what counts as an update
+- `evals/wiki.eval.ts`: smoke cases
+
+## Evals
+
+Four smoke cases drawn from a busy merge day: a lint fix, a new
+protobuf contract, a markdown-only change, and a cherry-pick.
+
+```bash
+agent-sdk eval
+```
+
+Eval sessions skip the GitHub write.
+
+## Deploy
+
+```bash
+agent-sdk deploy
+```
+
+Run it from the agent's git checkout. The command infers repository,
+ref, path, and slug. The deployment uses the team's Cursor GitHub
+connection for the same watched repos.

package/docs/troubleshooting.md

@@ -42,7 +42,7 @@ not on `PATH`, use `npx @cursor/july`.
 | What you see | What to do |
 | --- | --- |
 | `409` on a follow-up message | Refresh the `continuationToken` or confirm the session is a chat session. Task sessions do not accept follow-ups. |
-| `409 session_busy` on `call --session` | Wait for the model turn to finish, or omit `--session` for a one-off call. |
+| `409 session_busy` on `call --session` | The tool is a write (or declares no effect) and a model turn is running. Wait for the turn to finish, omit `--session` for a one-off call, or declare `effect: "read"` on a tool that only reads so it runs alongside turns. |
 | `403` on stream or follow-up | Use the same auth identity that created the session. Off localhost, pass `--bearer-token` and send it on every request. |
 | Works on localhost; blocked through a tunnel or LAN | Default auth allows only direct loopback callers. Share the host with `--bearer-token <secret>` (or authored `bearerAuth`). Use `--allow-anonymous` only on a trusted private network. |
 | A channel route fails to compile with a schema type error | `GET` routes need a Zod `querySchema`. `POST` / `PUT` / `PATCH` need a Zod `bodySchema`. Use `z.object({})` or `z.unknown()` for open shapes. |
@@ -70,7 +70,7 @@ not on `PATH`, use `npx @cursor/july`.
 | What you see | What to do |
 | --- | --- |
 | `must be defineConnection({ url, oauth: true })` | The connection file needs `oauth: true`, or you passed the wrong connection name to `agent-sdk mcp oauth`. |
-| Local auth works; hosted calls unauthorized | Run `agent-sdk mcp oauth <name> --store`, confirm names with `agent-sdk secrets list <slug>`, then redeploy. |
+| Local auth works; hosted calls unauthorized | Finish Connect on the hosted engine, or run `agent-sdk mcp oauth <name> --store`. Confirm names with `agent-sdk secrets list <slug>`, then redeploy. |
 | Model asks for `mcp_auth` or IDE MCP for a connector it already has | Attached MCP is behind meta-tools. Set `advertiseTools: true` for named tools on local turns, or call it from a host tool via `ctx.host.mcp`. |
 
 See [Host MCP OAuth](./guides/mcp-oauth.md) and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.95",
+  "version": "0.1.97",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -30,7 +30,6 @@
     "!src/**/*.test.ts",
     "!src/internal/tenant-mcp/**",
     "skills/**/*",
-    "!skills/operate/**",
     "templates/**/*",
     "docs/**/*.md",
     "!docs/.cursor/**",
@@ -217,6 +216,7 @@
   },
   "scripts": {
     "build": "tsgo -p tsconfig.build.json && node scripts/bundle-publish-shims.mjs && pnpm run build:playground && pnpm run docs:build",
+    "build:dist": "node scripts/build-hosted-dist.mjs",
     "postinstall": "node -e \"try{const p='./scripts/install-cursor-skills.mjs';if(require('fs').existsSync(p))require('child_process').execFileSync(process.execPath,[p],{stdio:'inherit'})}catch{}\"",
     "build:playground": "vite build --config playground/vite.config.ts",
     "build:playground:central": "vite build --mode central --config playground/vite.config.ts",

package/skills/ab/SKILL.md

@@ -1,35 +1,24 @@
 ---
 name: agentsdk-ab
 description: >-
-  Author defineAB live A/B metrics plug-ins under agent/ab. Splits traffic into
-  sticky variants and calls onSample with performance metrics as the agent runs
-  — not a test runner. Use when instrumenting production/dev traffic for variant
-  comparison; use defineEval for regression gates.
+  Author defineAB live A/B metrics under agent/ab. Sticky variants
+  and onSample on live runs. Not a test runner. Use when comparing
+  variants on traffic; use defineEval for regression gates.
 ---
 
 # Agent SDK A/B metrics (`defineAB`)
 
-Public docs index: `node_modules/@cursor/july/dist/docs/llms.txt`. A running
-host serves the same index at `/docs/llms.txt`.
-
-`defineAB` is a **live metrics plug-in**. At session creation the engine runs
-`split` and appends durable `ab.assigned` events; the collector folds the
-session event stream and calls `onSample`. There is **no** `agent-sdk ab`
-CLI and **no** assertion API.
-
-Human-facing reference: [`docs/ab.md`](../../docs/ab.md).
+Live metrics plug-in. No `agent-sdk ab` CLI. No assertion API.
+Reference: `docs/ab.md`.
 
 | | `defineEval` | `defineAB` |
 | --- | --- | --- |
-| Job | Regression gates on frozen fixtures | Collect metrics on live runs |
+| Job | Gates on frozen fixtures | Metrics on live runs |
 | Location | `evals/**/*.eval.ts` | `agent/ab.ts` or `agent/ab/<name>.ts` |
-| How it runs | `agent-sdk eval` | Automatically under `serve` / `run` |
-| Driver | `t.send` + gates | `split` → `ab.assigned` + `onSample` |
-
-## Authoring
+| How it runs | `agent-sdk eval` | Under `serve` / `run` |
 
 ```ts
-import { defineAB, splitBySessionHash, splitIf } from "@cursor/july/ab";
+import { defineAB, splitBySessionHash } from "@cursor/july/ab";
 
 export default defineAB({
   name: "concise-instructions",
@@ -37,13 +26,11 @@ export default defineAB({
     control: { label: "Baseline" },
     treatment: {
       label: "Shorter",
-      // Optional: appended to agent instructions for this arm.
       instructions: "Keep replies to one short paragraph.",
     },
   },
   split: splitBySessionHash({ holdout: 0.1 }),
   derive: {
-    // Keep sync + cheap — runs on every event, including message deltas.
     weatherCalls: (event) =>
       event.type === "action.result" && event.data.toolName === "get_weather"
         ? 1
@@ -55,8 +42,6 @@ export default defineAB({
 });
 ```
 
-In tools, read the arm from session context:
-
 ```ts
 async execute(input, ctx) {
   if (ctx.session.abs?.["concise-instructions"] === "treatment") {
@@ -65,78 +50,9 @@ async execute(input, ctx) {
 }
 ```
 
+Enrollment is at session creation. Eval sessions skip it. Do not
+use `splitIf` to filter evals. Split helpers and `onSample`
+fields: `docs/ab.md`.
 
-Discovery: `agent/ab.ts` and `agent/ab/*.ts`. Name defaults to file stem or `config.name`.
-
-Optional project defaults in `agent/ab.config.ts` (retention + persistence):
-
-```ts
-import {
-  defineABConfig,
-  persistABSamplesToDir,
-  persistABSnapshotsToDir,
-} from "@cursor/july/ab";
-
-export default defineABConfig({
-  // maxPlaygroundSessions: 200, // optional; default 200; A/Bs tab / GET /v1/abs only
-  persistSamples: persistABSamplesToDir(".agent-serve/ab-samples"),
-  persistSnapshots: persistABSnapshotsToDir(".agent-serve/ab-snapshots"),
-});
-```
-
-Session `events.ndjson` remains the assignment/metrics source of truth.
-`persistSamples` / `persistSnapshots` are author-controlled exports (like
-eval `persistRuns`).
-
-### Stream model
-
-Typical new-session prefix:
-
-1. `session.started`
-2. one `ab.assigned` per experiment (`variant` key or `null` skip)
-3. `message.received` / `turn.started` / …
-
-Enrollment is **at session creation** (before the first turn) so each arm can
-vary instructions and tool behavior from a known assignment. Failed/`null`
-splits persist as `ab.assigned` with `variant: null` (sticky skip). The
-collector is a pure fold over the log. `SessionRecord.abs` is a convenience
-mirror, not a metrics store. After park/restart it replays `events.ndjson` to
-rebuild counters without re-firing `onSample`.
-
-**Evals are separate:** the eval harness creates sessions with
-`purpose: "eval"` (playground Evals / `agent-sdk eval`). Those skip
-enrollment entirely — no `ab.assigned`, no `onSample`, omitted from
-`GET /v1/abs`. Ordinary chat / `agent-sdk run` / Slack stay `"live"`.
-Do not use `splitIf` to filter evals; the framework already does.
-
-After enrollment, arms are on `session.abs` (experiment → variant | `null`)
-for tools/hooks, and optional per-variant `instructions` are appended to the
-agent prompt for that session (a treatment arm can, say, switch `get_weather`
-to °C for its sessions).
-
-### Split helpers
-
-| Helper | Behavior |
-| --- | --- |
-| `splitBySessionHash({ weights?, holdout?, salt? })` | Sticky hash → arm |
-| `splitByRandom({ weights?, holdout? })` | Random once, then sticky |
-| `splitAlways("control")` | Pin all new sessions |
-| `splitNone()` | Skip everyone (pause in place) |
-| `splitIf(pred, inner)` | Skip unless `pred` |
-| `(ctx) => …` | Custom — variant key or `null` |
-
-### Built-in metrics
-
-`turns`, `turnFailures`, `toolCalls`, `toolErrors`, token fields, `wallTimeMs`,
-plus `custom.*` from `derive`. `onSample` fires on `turn.completed` / `turn.failed`.
-
-Playground **A/Bs** tab and `GET /v1/abs` fold the same durable streams into
-per-session assignments and aggregate arm totals (no separate metrics store).
-
-### `derive` cost
-
-`derive` extractors run on **every** session event (same cost model as hooks).
-Keep them synchronous and cheap — no network, no disk, no heavy parsing.
-
-Before wiring: pick experiment name + arm labels, a split helper (and who
-to leave out), and a real `onSample` sink — do not invent credentials.
+Pick a name, arm labels, a split, and a real `onSample` sink. Do
+not invent credentials.