@cursor/july 0.1.1

package/AGENTS.md

@@ -0,0 +1,290 @@
+# Agent experience (AX)
+
+Guide for coding agents working on or with `@cursor/july`.
+Loop: edit files → inspect surface → run a turn → assert with filesystem
+evals. Prefer the CLI over ad-hoc curl.
+
+User-facing documentation lives in [`docs/`](./docs/README.md)
+(quickstart, concepts, guides, evals/live A/B metrics/hillclimbing, deployment,
+troubleshooting, reference). This file is the terse loop reference;
+point humans at the docs.
+
+Run the CLI under **Node, never Bun** — use the installed `agent-serve`
+(or `agentkit`) bin; from a source checkout of this package,
+`pnpm exec tsx src/bin/agent-serve.ts <command> …` is equivalent. Bun's
+HTTP/2 client corrupts local harness
+tool-result streams (`NGHTTP2_FRAME_SIZE_ERROR`), which makes every
+built-in read/grep fail and sends models into retry loops.
+
+## Skills
+
+Before scaffolding, wiring channels, writing evals, or deploying, **read the
+matching skill under `skills/<task>/SKILL.md`** (paths
+below are relative to this package). These files are the single source of
+truth; they ship with `@cursor/july`. There are no
+`.cursor/skills/` stubs — open the package skill directly.
+
+| Skill | Read it when |
+| --- | --- |
+| `skills/framework-map/SKILL.md` | First contact: folder structure, runtimes, sessions, state, invariants |
+| `skills/create-agent/SKILL.md` | Scaffolding a new agent (interview → scaffold → verify) |
+| `skills/evals/SKILL.md` | Writing evals; fixture strategy; the regression ratchet |
+| `skills/ab/SKILL.md` | Live A/B metrics (`defineAB` under `agent/ab`); not a test runner |
+| `skills/hillclimb/SKILL.md` | Improving an existing agent measurably |
+| `skills/github/SKILL.md` | GitHub webhook agents; replay / forward / fixtures / cursor-events |
+| `skills/setup-slack/SKILL.md` | Slack wiring and Slack tool approvals |
+| `skills/debug/SKILL.md` | Something misbehaving locally (symptom → cause) |
+
+## Recommended loop
+
+```bash
+# 1. Discover / validate
+agent-serve validate --dir .
+agent-serve info --dir . --json
+
+# One-shot turn (ephemeral server, JSON trajectory + single NDJSON trace)
+agent-serve run --dir . --message "What's the temperature in NYC?"
+# → trace at <dir>/.agent-serve/traces/<sessionId>.ndjson
+# Visualize: agent-serve serve --dir .  then playground → Open trace
+
+# Against a running server (deep-linkable in the playground)
+agent-serve serve --dir . &
+agent-serve run --url http://127.0.0.1:3000 --message "..."
+# → JSON includes playgroundUrl?sessionId=...
+
+# Optional: custom path / offline summary
+agent-serve run --dir . --message "..." --events /tmp/run.ndjson
+agent-serve trajectory --events /tmp/run.ndjson
+
+# Deterministic tool call (no model turn, no API key needed)
+agent-serve call get_weather --dir . --input '{"city":"NYC"}'
+# → POST /v1/tools/get_weather; validates input, runs execute in-process
+
+# 3. Evals (defineEval under evals/)
+agent-serve eval --dir . --list
+agent-serve eval --dir . --json
+agent-serve eval --dir . weather/nyc
+
+# Live A/B metrics: author agent/ab.ts (defineAB) — runs under serve, no CLI
+```
+
+## Project layout
+
+```
+my-agent/
+  agent/
+    agent.ts
+    instructions.md
+    tools/*.ts
+    skills/*.md
+    channels/
+    ab.ts                    # optional live A/B metrics (defineAB)
+    ab.config.ts             # optional: maxPlaygroundSessions (default 200) / persist*
+    ...
+  evals/
+    smoke.eval.ts            # single datapoint → id: smoke
+    weather.eval.ts          # cases → weather/nyc, weather/paris, …
+    evals.config.ts          # required: maxConcurrency; optional maxPlaygroundRuns (default 20) / persistRuns
+```
+
+## Authoring evals
+
+```ts
+import { defineEval, includes } from "@cursor/july/evals";
+
+// One datapoint per file, or many via `cases` (ids = <fileId>/<case.id>)
+export default defineEval({
+  tags: ["smoke", "weather"],
+  cases: [
+    {
+      id: "nyc",
+      description: "Weather tool is used for temperature questions.",
+      async test(t) {
+        await t.send("What's the temperature in NYC?");
+        t.succeeded();
+        t.calledTool("get_weather");
+        t.check(t.reply, includes(/°|[FC]/));
+      },
+    },
+  ],
+});
+```
+
+Select with the CLI: one datapoint (`weather/nyc`), a whole file
+(`weather`), several ids, or omit for all.
+
+`evals/evals.config.ts` must set `maxConcurrency` (hard-capped at 200 due to
+model provider request limits; examples use `20`). Playground batches default
+to in-memory only (`maxPlaygroundRuns`, default 20); set `persistRuns` to survive
+serve restart:
+
+```ts
+import {
+  defineEvalConfig,
+  persistEvalRunsToDir,
+} from "@cursor/july/evals";
+
+export default defineEvalConfig({
+  maxConcurrency: 20,
+  // persistRuns: persistEvalRunsToDir(".agent-serve/eval-runs"),
+});
+```
+## CLI notes for agents
+
+- `run` defaults to **JSON** (use `--text` for a compact text dump).
+- `run` / `eval` start an ephemeral server on port 0 with a temp `stateRoot`
+  outside the monorepo so session workspaces do not inherit ambient `AGENTS.md`.
+- Point `--url` at an already-running agent to skip local host startup.
+- `call <tool> --input '{...}'` invokes a server tool deterministically
+  (schema-validated, in-process, no model). `--session <id>` runs it inside
+  an existing session and records it on that session's event stream.
+- `init` with no directory prints this setup guide (does not scaffold).
+- `chat --json --message "..."` talks to a running server and prints a trajectory.
+
+## Agent-to-agent (MCP endpoint + peer MCP connections)
+
+Every mounted agent is also an MCP server at `/<slug>/v1/mcp` (streamable
+HTTP, stateless, same auth chain as the session API). Tools: `ask`
+(delegate a message; returns `{ status, sessionId, reply }`, with bounded
+waits — `status: "running"` means keep waiting), `check` (wait/poll a
+running session), and `call_tool` (deterministic server-tool passthrough,
+only when the agent has server tools). Sessions created this way live on
+the `mcp` channel and are visible in the playground.
+
+Wire one agent to another with a **peer MCP connection**:
+
+```ts
+// agent/mcp-connections/weather.ts
+export default defineConnection({ agent: "weather-agent" });
+```
+
+Peers resolve at serve time to the target's MCP URL — loopback for local
+turns and host-side `ctx.host.mcp`, the serve `--public-url` for
+cloud-runtime turns (omitted + warned when unset; a cloud VM cannot reach
+loopback). `--bearer-token` is attached to peer calls automatically.
+Unknown slugs and self-references fail `serve` at startup; peers need the
+multi-agent layout. No cross-host loop protection: scope delegation in
+instructions so A→B→A recursion cannot happen (e.g. a parent agent that
+delegates *only* weather questions to a `weather-agent` peer).
+
+```bash
+agent-serve serve --dir ./agents --dev
+agent-serve chat --url http://127.0.0.1:3000/concierge --message "Weather in Paris?"
+```
+
+## Slack channel
+
+The Cursor Slack connection is the zero-setup default
+(`slackChannel({ cursorAccount: true, agentName: "…" })`). Sign the host
+in (`agent-serve login` / `CURSOR_API_KEY`), then `@Cursor <agentName> …`
+in Slack; thread replies stay with that agent. Import from
+`@cursor/july/channels/slack`.
+
+Dedicated Socket Mode apps (no public Request URL) live in a second
+channel file when you need channel watching, approval buttons, or a
+distinct bot handle:
+
+```bash
+agent-serve slack setup
+agent-serve slack init --dir ./my-agent --name "My Agent" --channel-posts
+# writes envPrefix from the directory name (MY_AGENT_SLACK_*)
+agent-serve slack doctor --prefix MY_AGENT
+agent-serve serve --dir ./my-agent --dev
+```
+
+Multi-agent Socket Mode needs **one Slack app (and token pair) per agent**:
+`<PREFIX>_SLACK_BOT_TOKEN` + `<PREFIX>_SLACK_APP_TOKEN`. Missing tokens leave
+that channel idle instead of failing `serve`. Single-agent setups can use the
+shared `SLACK_*` vars (`slackChannel()` / `init --no-prefix`).
+
+Channel watching (`engagement.channelPosts`) and tool approvals
+(`toolApprovals` / `interactivity`) are Socket Mode only — not supported on
+cursorAccount (the Cursor connection does not relay Block Kit clicks); use a
+dedicated Slack app for Approve/Deny.
+
+Defaults ON: chat streaming, thinking steps, suggested prompts (graceful
+fallback when APIs missing; streaming defaults off on cursorAccount). Guided
+skill: `skills/setup-slack/SKILL.md`.
+
+## Playground UI (Vite + React)
+
+The web playground is a Vite + React SPA under `playground/` (entry
+`playground/src/main.tsx`).
+
+`agent-serve serve` handles the Vite side for you:
+
+- If `dist/playground/` is missing and the local vite toolchain is present,
+  serve auto-runs `vite build` before listening.
+- `serve --dev` also starts Vite HMR (default `:5273`) and prints
+  `playground (HMR): …`. Single-agent proxies `/v1` to the serve URL;
+  multi-agent serves the agents index at `/` and each SPA at
+  `/<slug>/playground` (pin one slug with `AGENT_SERVE_BASE=/<slug>`).
+
+`pnpm run build` still emits the static bundle to `dist/playground/` (ships in
+`dist/**`). Pure logic (markdown render, trace model) lives in
+`playground/src/lib` with Vitest tests — prefer adding tests there.
+
+## GitHub channel
+
+Author `agent/channels/github.ts` with `githubChannel()` from
+`@cursor/july/channels/github`; it mounts `POST /v1/channels/github`
+and verifies `X-Hub-Signature-256` when a webhook secret is set. The channel
+publishes the webhook events it dispatches on (derived from the declared hooks,
+or pinned via `webhookEvents`) as `meta.githubWebhookEvents`. Auth default: with
+a secret → `allowAll()` + signature check; without one → `localDevStrict()`,
+except under `serve --dev` which admits unsigned loopback deliveries (so
+`gh webhook forward` and fixtures work with no secret). Outbound GitHub API
+calls prefer App installation tokens (`GITHUB_APP_ID` +
+`GITHUB_APP_PRIVATE_KEY` + webhook `installation.id` or
+`GITHUB_APP_INSTALLATION_ID`); serve warmup also exports that token as
+`GH_TOKEN` for tools that shell out to `gh`. For local testing, omit App
+creds and use `GITHUB_TOKEN` / `GH_TOKEN` or `gh auth login`.
+
+Test github agents against live deliveries with the CLI (wraps
+`gh webhook forward`; URL + events auto-derived, repo inferred from the git
+remote):
+
+```bash
+# one-time: gh + the cli/gh-webhook extension
+agent-serve github doctor --install
+
+# what would be forwarded, per agent (URL + events)
+agent-serve github events --dir ./agents --json
+
+# forward live deliveries to a served agent (no secret needed against --dev;
+# set GITHUB_WEBHOOK_SECRET to verify signatures)
+agent-serve serve --dir ./my-agent --dev &
+agent-serve github forward --dir ./my-agent
+```
+
+When several channels match (e.g. a folder of agent projects), one forwarder fans out to
+all of them via a local proxy that re-posts each raw (still-signed) delivery to
+the channels whose event set matches — `gh webhook forward` targets one URL and
+GitHub allows only one forwarder per repo. `--repo` / `--org` override the
+target, `--events` narrows the set, `--url` points at a tunnel, and `--slug` /
+`--channel` forward to just one of several agents.
+
+`gh webhook forward` requires **admin** on the repo (org owner for `--org`) and
+authenticates its relay with the GitHub CLI's own login — so a `GITHUB_TOKEN` /
+`GH_TOKEN` env override makes deliveries **401** (hook creation still succeeds,
+which is the confusing part). Blank it for the command (`GITHUB_TOKEN= GH_TOKEN=
+agent-serve github forward …`) or `unset` it; `github doctor` / `forward` warn
+when they detect an env token.
+
+When you lack repo admin, or want deterministic runs (hillclimbing), use
+`agent-serve github replay <pr_url>` instead: it **reads** the PR via `gh api`
+(pull access only, `GITHUB_TOKEN` is fine), synthesizes GitHub-shaped payloads,
+signs them (`--secret`/`GITHUB_WEBHOOK_SECRET`), and POSTs them at the channel —
+no admin, no relay. `--events` defaults to `pull_request` (`*` = the channel's
+declared events); `--action`/`--conclusion`/`--comment`/`--context` tune each;
+`--dry-run`/`--out DIR` print or snapshot payloads as fixtures.
+Fixtures still work for offline replay: `POST` a saved payload with an
+`x-github-event` header (no signature in `--dev`).
+
+## Do not
+
+- Put durable `--state-root` inside a large monorepo if you care about
+  ambient `AGENTS.md` / `.cursor` rules leaking into the agent workspace.
+  Prefer `defineAgent({ local: { cwd } })` pointing outside the monorepo
+  (session harnesses land at `<cwd>/<sessionId>`), or a temp `--state-root`.
+- Expect `agent/evals/` to be loaded — evals live at the **project root** `evals/`.

package/LICENSE.md

@@ -0,0 +1,3 @@
+# Cursor SDK License
+
+© Anysphere Inc. All rights reserved. Use is subject to Cursor's [Terms of Service](https://cursor.com/terms-of-service).