@cursor/july 0.1.1 → 0.1.3

package/docs/storage.md

@@ -0,0 +1,98 @@
+---
+title: "Storage"
+description: "Point agentkit's durable storage at a backend you own with defineStorage."
+---
+
+# Storage
+
+agentkit owns durable storage for sessions, continuation tokens,
+reminders, playground eval history, and live A/B samples. It chooses the
+keys (under `agentkit/v1/`), when to read and write, and how to restore
+after restart.
+
+Keys have bounded length: caller-controlled segments (channel ids,
+continuation tokens) are URI-encoded, and any segment past 256 encoded
+bytes is replaced by its `sha256:…` digest — deterministically, so writes
+and lookups always agree. Backends can rely on this instead of imposing
+their own key-length caps (which would silently drop writes, since a
+throwing `put` is at-most-once).
+
+By default that storage lives under `--state-root` on local disk. Fine
+for one machine; it does not survive replacing the host.
+
+To keep the same framework storage across hosts, plug in a key-value
+backend with `agent/storage.ts`. You provide `put` / `get` / `delete` /
+`list`. agentkit does the rest.
+
+```ts
+// agent/storage.ts
+import { defineStorage } from "@cursor/july/storage";
+
+export default defineStorage({
+  put: (key, value) => db.upsert(key, value),
+  get: (key) => db.get(key),
+  delete: (key) => db.delete(key),
+  list: (prefix) => db.listByPrefix(prefix), // [{ key, value }], key order
+});
+```
+
+> [!NOTE]
+> Import paths here use `@cursor/july/storage`. On projects still
+> using `@anysphere/agent-serve`, swap the import. See
+> [Run the CLI](./README.md#run-the-cli) for the full rename table.
+
+## Which methods to provide
+
+| Method | Required | Role |
+| --- | --- | --- |
+| `put` | Yes | Write or update a value |
+| `get` | For restore | Look up one key |
+| `list` | For restore | Return entries under a prefix, in key order |
+| `delete` | For cleanup | Remove a key |
+
+A throwing `put` is logged and dropped. It never fails a turn. When
+resolving a missing continuation token, a throwing `get` fails the
+follow-up so a store outage does not open a new session. Return
+`undefined` only for a real miss.
+
+## Policy
+
+Two knobs change behavior:
+
+```ts
+export default defineStorage({
+  policy: {
+    // Batch event writes while the session is busy (default: once per turn)
+    debounceMs: 30_000,
+    // Cap how much loads at serve start, or "off" to restore on demand
+    restore: { maxSessions: 500 },
+  },
+  // put / get / delete / list …
+});
+```
+
+| Knob | Default | Meaning |
+| --- | --- | --- |
+| `debounceMs` | unset (once per turn) | Wait this long after activity before writing event batches |
+| `restore` | caps below | How much to load at serve start |
+| `restore.maxSessions` | `1000` | Max sessions loaded at serve start |
+| `restore.maxAgeMs` | 30 days | Skip older sessions at serve start |
+| `restore.maxTotalBytes` | 1 GiB | Stop loading once this budget is reached |
+
+Set `restore: "off"` on high-traffic hosts. Sessions then load when a
+follow-up arrives instead of at startup.
+
+## Restore after restart
+
+With `get` and `list`, serve can rebuild local state from your store:
+
+- At startup, agentkit loads recent sessions up to the restore caps.
+  Local disk wins when both sides have the same session. Reminders
+  hydrate the same way into `--state-root/reminders`.
+- On demand, a missing continuation token resolves through the store
+  and resumes that session.
+- Playground eval history and A/B aggregates can load from the same
+  sink.
+
+A turn in flight at crash time is not replayed. The next follow-up
+resumes from the last flushed state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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": {
@@ -117,6 +117,13 @@
       "import": "./dist/ab.js",
       "default": "./dist/ab.js"
     },
+    "./storage": {
+      "anysphere-source": "./src/storage.ts",
+      "bun": "./src/storage.ts",
+      "types": "./dist/storage.d.ts",
+      "import": "./dist/storage.js",
+      "default": "./dist/storage.js"
+    },
     "./package.json": {
       "anysphere-source": "./package.json",
       "bun": "./package.json",
@@ -167,10 +174,12 @@
     "@tanstack/react-virtual": "3.13.23",
     "@types/ms": "^2.1.0",
     "@types/node": "catalog:",
+    "@types/pg": "^8.16.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@typescript/native-preview": "7.0.0-dev.20260701.1",
     "@vitejs/plugin-react": "^5.1.2",
+    "pg": "^8.18.0",
     "pretty-ms": "^9.2.0",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",

package/skills/ab/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agent-serve-ab
+name: agentkit-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
@@ -7,11 +7,11 @@ description: >-
   comparison; use defineEval for regression gates.
 ---
 
-# agent-serve A/B metrics (`defineAB`)
+# agentkit A/B metrics (`defineAB`)
 
 `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-serve ab`
+session event stream and calls `onSample`. There is **no** `agentkit ab`
 CLI and **no** assertion API.
 
 Human-facing reference: [`docs/ab.md`](../../docs/ab.md).
@@ -20,13 +20,13 @@ Human-facing reference: [`docs/ab.md`](../../docs/ab.md).
 | --- | --- | --- |
 | Job | Regression gates on frozen fixtures | Collect metrics on live runs |
 | Location | `evals/**/*.eval.ts` | `agent/ab.ts` or `agent/ab/<name>.ts` |
-| How it runs | `agent-serve eval` | Automatically under `serve` / `run` |
+| How it runs | `agentkit eval` | Automatically under `serve` / `run` |
 | Driver | `t.send` + gates | `split` → `ab.assigned` + `onSample` |
 
 ## Authoring
 
 ```ts
-import { defineAB, splitBySessionHash, splitIf } from "@anysphere/agent-serve/ab";
+import { defineAB, splitBySessionHash, splitIf } from "@cursor/july/ab";
 
 export default defineAB({
   name: "concise-instructions",
@@ -72,7 +72,7 @@ import {
   defineABConfig,
   persistABSamplesToDir,
   persistABSnapshotsToDir,
-} from "@anysphere/agent-serve/ab";
+} from "@cursor/july/ab";
 
 export default defineABConfig({
   // maxPlaygroundSessions: 200, // optional; default 200; A/Bs tab / GET /v1/abs only
@@ -101,9 +101,9 @@ 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-serve eval`). Those skip
+`purpose: "eval"` (playground Evals / `agentkit eval`). Those skip
 enrollment entirely — no `ab.assigned`, no `onSample`, omitted from
-`GET /v1/abs`. Ordinary chat / `agent-serve run` / Slack stay `"live"`.
+`GET /v1/abs`. Ordinary chat / `agentkit 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`)

package/skills/create-agent/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: agent-serve-create-agent
+name: agentkit-create-agent
 description: >-
-  Scaffold a new agent-serve agent through a guided AskQuestion interview —
+  Scaffold a new agentkit 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.
@@ -9,7 +9,7 @@ paths:
   - packages/agent-serve/**/*
 ---
 
-# Create an agent-serve agent
+# Create an agentkit agent
 
 Stand up one new agent project via a short interview, scaffold it, get
 channels working
@@ -21,9 +21,9 @@ wiring, `github` for webhook-driven agents, `evals` for the eval API,
 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-serve` bin, or from a source
+tool-result streams): use the installed `agentkit` bin, or from a source
 checkout `pnpm exec tsx src/bin/agent-serve.ts <command> …` — written as
-`agent-serve …` below.
+`agentkit …` below.
 
 ## Interview
 
@@ -93,7 +93,7 @@ Defaults that make first cuts good:
   (script) only when the tool must run where the agent runs (or runtime is
   cloud). Gate side-effecting tools with `needsApproval: true`.
 - **Env prefix** for Slack tokens = upper-snake slug (`my-agent` →
-  `MY_AGENT_SLACK_*`); `agent-serve slack init` derives it for you.
+  `MY_AGENT_SLACK_*`); `agentkit slack init` derives it for you.
 - **Host prep beats model wandering:** 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.
@@ -101,21 +101,27 @@ Defaults that make first cuts good:
 ## Scaffold
 
 ```bash
-agent-serve init ./<slug>
+agentkit init ./<slug>
 ```
 
-`init` writes `package.json`, `agent/agent.ts`, `agent/instructions.md`, and a
-demo `agent/tools/echo.ts`; it refuses to overwrite existing files. Then shape
-it to the plan:
-
-1. `tsconfig.json` — add one so the type-checker covers the project.
+`init` writes `package.json` (with `typescript` dev deps and a
+`check` script), `tsconfig.json`, `agent/agent.ts`, `agent/instructions.md`,
+a demo `agent/tools/echo.ts`, and empty capability folders
+(`skills/`, `channels/`, `evals/`, …) each with a `.gitkeep`; existing
+files are left alone (`exist`) and missing ones are filled in. It then
+runs `npm install`, and when the host is unsigned runs `login` and waits
+before printing `cd` (when needed) and bare `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({...})`; 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-serve slack init --dir
+   Slack, do not hand-write the channel: `agentkit slack init --dir
    ./<slug> --name "<Name>"` generates `agent/channels/slack.ts` (with
    the env prefix) plus manifests and `env.example`; customize the generated
    file (e.g. `suggestedPrompts`) afterwards.
@@ -128,7 +134,7 @@ it to the plan:
    (case id = file path, or `<fileId>/<case.id>`). Full assertion API and
    fixture strategy: `evals/SKILL.md` (sibling skill).
 
-Stick to deps agent-serve already
+Stick to deps agentkit already
 ships (`zod`, `@modelcontextprotocol/sdk`, `tsx`); a new npm dep needs its own
 install story and is a smell for a first cut.
 
@@ -138,10 +144,10 @@ No API key needed for the structural half — run these first and fix every
 error diagnostic:
 
 ```bash
-agent-serve validate --dir ./<slug>            # zero errors (warnings explain runtime mismatches)
-agent-serve info --dir ./<slug> --json         # surface matches the plan
-agent-serve call <tool> --dir ./<slug> --input '{…}'   # server tools, deterministic, no model
-agent-serve eval --dir ./<slug> --list
+agentkit validate --dir ./<slug>            # zero errors (warnings explain runtime mismatches)
+agentkit info --dir ./<slug> --json         # surface matches the plan
+agentkit call <tool> --dir ./<slug> --input '{…}'   # server tools, deterministic, no model
+agentkit eval --dir ./<slug> --list
 npx tsc --noEmit -p ./<slug>                   # or the project's own type-check task
 ```
 
@@ -158,10 +164,10 @@ 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:
 
 ```bash
-agent-serve run --dir ./<slug> --message "<fixture prompt>"   # JSON trajectory
-agent-serve serve --dir ./<slug> --dev
+agentkit run --dir ./<slug> --message "<fixture prompt>"   # JSON trajectory
+agentkit serve --dir ./<slug> --dev
 # playground: http://127.0.0.1:3000/<slug>/playground
-agent-serve eval --dir ./<slug>
+agentkit eval --dir ./<slug>
 ```
 
 Serve only the new agent's directory during bring-up — pointing `serve` at a
@@ -204,7 +210,7 @@ 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-serve github replay ... --dry-run --out fixtures/github`) so the
+(`agentkit github replay ... --dry-run --out fixtures/github`) so the
 loop starts deterministic.
 
 ## Working agreements

package/skills/debug/SKILL.md

@@ -1,14 +1,14 @@
 ---
-name: agent-serve-debug
+name: agentkit-debug
 description: >-
-  Diagnose a misbehaving agent-serve agent, server, or playground — blank
+  Diagnose a misbehaving agentkit 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-serve project runs but behaves
+  orphaned processes. Use when an agentkit project runs but behaves
   wrong locally.
 ---
 
-# Debugging agent-serve locally
+# Debugging agentkit locally
 
 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
@@ -18,7 +18,7 @@ src/bin/agent-serve.ts ...` in the everysphere monorepo).
 
 ```bash
 # 1. Is discovery clean? serve refuses to start on error diagnostics.
-agent-serve validate --dir <project>
+agentkit validate --dir <project>
 
 # 2. What is actually running, and where?
 lsof -iTCP:3000 -sTCP:LISTEN; lsof -iTCP:5273 -sTCP:LISTEN
@@ -37,11 +37,11 @@ curl -sN 'localhost:3000/<slug>/v1/session/<id>/stream?startIndex=0' | head -50
 
 | Symptom | Cause / fix |
 | --- | --- |
-| Playground blank or "no agents" even though Vite assets are built | The SPA is static; it needs the agent-serve 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` starts Vite HMR (`:5273`) and prints `playground (HMR): ...` — 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>`. |
+| Playground blank or "no agents" even though Vite assets are built | The SPA is static; it needs the agentkit 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-serve 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-serve github forward ...` |
+| `gh webhook forward` / `agentkit 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= agentkit 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 the monorepo, so the harness loaded ancestor config. `defineAgent({ local: { cwd } })` outside the repo, or `--state-root` under `/tmp`. |
 | Port 3000/5273 in use; stray processes after crashes | `lsof -iTCP:3000 -sTCP:LISTEN`, kill the pids; also check companion processes (e.g. vite). |
@@ -49,11 +49,11 @@ curl -sN 'localhost:3000/<slug>/v1/session/<id>/stream?startIndex=0' | head -50
 | 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-serve call --session` | Session-bound deterministic calls serialize with model turns; wait or use an ephemeral call (drop `--session`). |
+| `409 session_busy` on `agentkit 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-serve slack doctor --prefix <PREFIX>`. |
+| Slack channel prints `channel idle ... missing credentials` | Expected: tokens absent. Multi-agent needs `<PREFIX>_SLACK_BOT_TOKEN` + `<PREFIX>_SLACK_APP_TOKEN` per agent. `agentkit 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`). |
@@ -67,5 +67,5 @@ curl -sN 'localhost:3000/<slug>/v1/session/<id>/stream?startIndex=0' | head -50
   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-serve trajectory --events <file>` renders any saved NDJSON; the
+- `agentkit trajectory --events <file>` renders any saved NDJSON; the
   playground "Open trace" does the same visually.

package/skills/evals/SKILL.md

@@ -1,13 +1,13 @@
 ---
-name: agent-serve-evals
+name: agentkit-evals
 description: >-
-  Author and run agent-serve defineEval cases (single- or multi-datapoint).
+  Author and run agentkit defineEval cases (single- or multi-datapoint).
   Use when writing, fixing, seeding, or hillclimbing evals; AskQuestion
   whether to generate samples or upload data. Materialize API-backed
   fixtures first. Live A/B metrics: defineAB (skills/ab), not defineEval.
 ---
 
-# agent-serve evals
+# agentkit evals
 
 Evals are the ratchet that makes iteration trustworthy: a fixed input, a
 model turn, and gates over the recorded trajectory. They live at the
@@ -29,13 +29,13 @@ and does not replace `defineEval` gates.
   (`evals/weather.eval.ts` + `{ id: "nyc" }` → `weather/nyc`).
 
 ```bash
-agent-serve eval --dir . --list              # all datapoints
-agent-serve eval --dir . --json              # run all
-agent-serve eval --dir . weather/nyc         # one datapoint
-agent-serve eval --dir . weather             # every datapoint in that file
-agent-serve eval --dir . weather forecast    # several files
-agent-serve eval --dir . --tag smoke
-agent-serve eval --dir . --verbose
+agentkit eval --dir . --list              # all datapoints
+agentkit eval --dir . --json              # run all
+agentkit eval --dir . weather/nyc         # one datapoint
+agentkit eval --dir . weather             # every datapoint in that file
+agentkit eval --dir . weather forecast    # several files
+agentkit eval --dir . --tag smoke
+agentkit eval --dir . --verbose
 ```
 
 `eval` (like `run`) boots an ephemeral server on port 0 with a temp state
@@ -65,7 +65,7 @@ If `AskQuestion` is unavailable, ask the same fork in plain chat and wait.
 
 Tell the user the **shape** of the data (see “The API” below) and **how to
 upload it**. Do not invent cases until they provide files (or paste content
-to write). After they add data, run `agent-serve eval --dir <project>
+to write). After they add data, run `agentkit eval --dir <project>
 --list` to confirm discovery, then wire any missing gates.
 
 If the uploaded data is **API-backed** (PR URLs, pinned SHAs, gold labels,
@@ -79,7 +79,7 @@ fixtures first** — see “When eval data needs API calls to render” below.
 3. Optional fixtures beside the case or under `fixtures/`.
 4. Tell the agent once the files are in place — or paste case bodies in chat
    and ask the agent to write the file.
-5. Verify: `agent-serve eval --dir <project> --list` shows the new ids.
+5. Verify: `agentkit eval --dir <project> --list` shows the new ids.
 
 ### Step 2b — user chose agent-generated samples
 
@@ -95,7 +95,7 @@ fixtures first** — see “When eval data needs API calls to render” below.
 3. **Append** — prefer adding entries to an existing file’s `cases` array
    when the suite fits; otherwise create a new `evals/<suite>.eval.ts` with
    `cases`. Never overwrite or weaken an existing datapoint. Case ids must
-   not collide with `agent-serve eval --dir <project> --list`.
+   not collide with `agentkit eval --dir <project> --list`.
 4. Create `evals/evals.config.ts` if missing (`maxConcurrency: 20` is fine
    for now; hard limit 200 for model provider request limits).
 5. Re-list to confirm, then optionally run `--tag smoke` if you tagged any.
@@ -103,7 +103,7 @@ fixtures first** — see “When eval data needs API calls to render” below.
 ## The API
 
 ```ts
-import { defineEval, includes, equals, satisfies } from "@anysphere/agent-serve/evals";
+import { defineEval, includes, equals, satisfies } from "@cursor/july/evals";
 
 // Single datapoint (case id = file path under evals/)
 export default defineEval({
@@ -152,7 +152,7 @@ Project-wide defaults in `evals/evals.config.ts` (required once):
 import {
   defineEvalConfig,
   persistEvalRunsToDir,
-} from "@anysphere/agent-serve/evals";
+} from "@cursor/july/evals";
 
 export default defineEvalConfig({
   maxConcurrency: 20, // required; hard-capped at 200 (model provider limits)
@@ -193,7 +193,7 @@ input instead — see fixtures).
 | Agent surface | Fixture source |
 | --- | --- |
 | Chat / domain assistant | A canonical prompt string, chosen once and frozen |
-| Tool-heavy | `agent-serve call <tool> --dir . --input '{...}'` first, then the prompt that should trigger it |
+| Tool-heavy | `agentkit call <tool> --dir . --input '{...}'` first, then the prompt that should trigger it |
 | GitHub webhook | `github replay … --dry-run --out fixtures/github` (see `packages/agent-serve/skills/github/SKILL.md`) |
 | PR reviewer with host prep | A small fixed PR the team controls; assert on findings shape, not counts |
 | Workspace-dependent | `workspaceFiles` in `t.send` — never machine-local paths |

package/skills/framework-map/SKILL.md

@@ -1,22 +1,22 @@
 ---
-name: agent-serve-framework-map
+name: agentkit-framework-map
 description: >-
-  Orientation for @anysphere/agent-serve — folder structure, local vs cloud
+  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-serve projects with agent/agent.ts and agent/instructions.md.
+  agentkit projects with agent/agent.ts and agent/instructions.md.
 ---
 
-# agent-serve framework map
+# agentkit framework map
 
-`@anysphere/agent-serve` serves agents defined as ordinary files: markdown
+`@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.
 
-Run the CLI as `agent-serve <cmd>`. In the everysphere monorepo there is no
+Run the CLI as `agentkit <cmd>`. In the everysphere monorepo there is no
 installed bin — use:
 
 ```bash

package/skills/github/SKILL.md

@@ -1,26 +1,27 @@
 ---
-name: agent-serve-github
+name: agentkit-github
 description: >-
-  Build and test GitHub-webhook-driven agent-serve agents: githubChannel
+  Build and test GitHub-webhook-driven agentkit 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.
 ---
 
-# GitHub channels in agent-serve
+# GitHub channels in agentkit
 
 Author `agent/channels/github.ts` with `githubChannel()` from
-`@anysphere/agent-serve/channels/github`. It mounts
+`@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.
 
 ```ts
-import { defaultGitHubAuth, githubChannel } from "@anysphere/agent-serve/channels/github";
+import { defaultGitHubAuth, githubChannel } from "@cursor/july/channels/github";
 
 export default githubChannel({
   botName: "my-agent", // or GITHUB_APP_SLUG; used to ignore self-comments
-  credentials: { webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET },
+  cursorAccount: { repos: ["owner/repo"] }, // permissions?: "read" | "pr-write" | "contents-write"
+
   onPullRequest: (ctx, pr) =>
     pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
   onCheckSuite: (ctx, suite) =>
@@ -44,6 +45,13 @@ 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 (`agentkit 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
@@ -73,9 +81,9 @@ is fine here), synthesizes GitHub-shaped payloads, signs them when a secret
 is configured, and POSTs them at the channel. Fully deterministic.
 
 ```bash
-agent-serve github replay https://github.com/owner/repo/pull/123 --dir <project>
-agent-serve github replay owner/repo#123 --dir <project> --events '*' --conclusion failure
-agent-serve github replay owner/repo#123 --dir <project> --events '*' --dry-run --out fixtures/github
+agentkit github replay https://github.com/owner/repo/pull/123 --dir <project>
+agentkit github replay owner/repo#123 --dir <project> --events '*' --conclusion failure
+agentkit github replay owner/repo#123 --dir <project> --events '*' --dry-run --out fixtures/github
 ```
 
 `--events` defaults to `pull_request` (`'*'` = the channel's declared
@@ -88,9 +96,9 @@ Wraps `gh webhook forward`: registers a real webhook and relays deliveries
 to loopback. URL + events auto-derived; repo inferred from the git remote.
 
 ```bash
-agent-serve github doctor --install     # one-time: gh + cli/gh-webhook
-agent-serve github events --dir <parent> --json   # what would be forwarded
-GITHUB_TOKEN= GH_TOKEN= agent-serve github forward --dir <project>
+agentkit github doctor --install     # one-time: gh + cli/gh-webhook
+agentkit github events --dir <parent> --json   # what would be forwarded
+GITHUB_TOKEN= GH_TOKEN= agentkit github forward --dir <project>
 ```
 
 Traps, in order of hours lost:
@@ -113,11 +121,11 @@ Traps, in order of hours lost:
 ### 4. `serve --cursor-events` — pull from Cursor (`/v0/scm-events`)
 
 ```bash
-agent-serve serve --dir <project> --cursor-events --repo owner/repo
+agentkit serve --dir <project> --cursor-events --repo owner/repo
 ```
 
 Reads the stream as the host's Cursor user, so it **requires sign-in**
-(`agent-serve login` / `CURSOR_API_KEY`) — `serve` refuses to start signed
+(`agentkit 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

package/skills/hillclimb/SKILL.md

@@ -1,7 +1,7 @@
 ---
-name: agent-serve-hillclimb
+name: agentkit-hillclimb
 description: >-
-  Iterate on a specific agent-serve agent by running the local server,
+  Iterate on a specific agentkit 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.
@@ -9,9 +9,9 @@ paths:
   - packages/agent-serve/**/*
 ---
 
-# Agent-serve hillclimb
+# Agentkit hillclimb
 
-Optimize one agent-serve agent project
+Optimize one agentkit 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
@@ -36,15 +36,15 @@ If those are missing, ask before editing.
 A climb over a moving input is noise. Before round 1:
 
 - **GitHub agents** — replay, don't wait for live events:
-  `agent-serve github replay <pr> --dir <project>` synthesizes signed,
+  `agentkit 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-serve call <tool> --dir <project> --input '{...}'` (schema-validated,
+  `agentkit 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-serve run --dir <project> --message "<fixture>"`
+- **Chat agents** — `agentkit run --dir <project> --message "<fixture>"`
   gives a JSON trajectory plus an NDJSON trace under
-  `<project>/.agent-serve/traces/`; `agent-serve trajectory --events <file>`
+  `<project>/.agent-serve/traces/`; `agentkit 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
@@ -59,7 +59,7 @@ Repeat until the user stops or fixtures meet the criteria.
 - Serve with Node (never Bun):
 
   ```bash
-  agent-serve serve --dir <project> --dev
+  agentkit serve --dir <project> --dev
   ```
 
 - Hit the agent the way a user would (channel HTTP, playground, Slack in
@@ -119,7 +119,7 @@ State the hypothesis in one sentence: *“If we X, metric Y should move because
 - **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-serve eval --dir <project> --json` is the regression check
+  pass. `agentkit eval --dir <project> --json` is the regression check
   between rounds.
 
 Present a short round report to the user before starting the next climb.