@cursor/july 0.1.2 → 0.1.4

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,22 +1,22 @@
 ---
-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
@@ -81,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
@@ -96,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:
@@ -121,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.

package/skills/setup-slack/SKILL.md

@@ -1,14 +1,14 @@
 ---
-name: agent-serve-setup-slack
+name: agentkit-setup-slack
 description: >-
-  Set up a Slack channel for an agent-serve project — Socket Mode,
+  Set up a Slack channel for an agentkit project — Socket Mode,
   manifests, doctor, smoke test, and opt-in Slack tool approvals (HITL).
-  Read this skill when wiring Slack for an agent-serve project.
+  Read this skill when wiring Slack for an agentkit project.
 ---
 
-# Setup Slack for agent-serve
+# Setup Slack for agentkit
 
-Use this skill when a human asks to wire Slack to an agent-serve agent.
+Use this skill when a human asks to wire Slack to an agentkit agent.
 
 ## Goal
 
@@ -63,7 +63,7 @@ MY_AGENT_SLACK_APP_TOKEN=xapp-…
 ```
 
 ```bash
-agent-serve slack doctor --prefix MY_AGENT
+agentkit slack doctor --prefix MY_AGENT
 ```
 
 Stop when `app_token`, `connections_open`, `bot_token`, and `auth_test` are green.
@@ -71,10 +71,10 @@ Stop when `app_token`, `connections_open`, `bot_token`, and `auth_test` are gree
 ### Phase 4 — Serve + smoke (agent + human)
 
 ```bash
-agent-serve serve --dir . --dev
+agentkit dev .
 ```
 
-Confirm log: `[agent-serve/slack] Socket Mode connected`.
+Confirm log: `[agentkit/slack] Socket Mode connected`.
 
 When tokens are missing the channel logs
 `channel idle reason=missing credentials need=…` and `serve` continues — useful
@@ -171,10 +171,10 @@ Requirements and caveats:
 ## CLI reference
 
 ```bash
-agent-serve slack setup
-agent-serve slack init --dir . --name "My Agent"
-agent-serve slack init --dir . --no-prefix
-agent-serve slack init --dir . --channel-posts   # + message.channels/groups events
-agent-serve slack manifest --env both
-agent-serve slack doctor --prefix MY_AGENT
+agentkit slack setup
+agentkit slack init --dir . --name "My Agent"
+agentkit slack init --dir . --no-prefix
+agentkit slack init --dir . --channel-posts   # + message.channels/groups events
+agentkit slack manifest --env both
+agentkit slack doctor --prefix MY_AGENT
 ```