@cursor/july 0.1.1

package/docs/building-with-agents.md

@@ -0,0 +1,129 @@
+---
+title: "Building agents with agents"
+description: "Use the built-in skills to have a coding agent create, verify, and improve your agent."
+---
+
+# Building agents with agents
+
+Give a coding agent the goal. The built-in skills guide it through
+scaffolding, channels, verification, evals, and measured improvement.
+
+## What can a coding agent build for me?
+
+A coding agent can take a agentkit project from an idea to a
+verified first version. It can:
+
+- Create the project and choose the smallest useful surface
+- Add tools, skills, channels, MCP connections, and approval gates
+- Run a real turn and inspect its trace
+- Add evals for the behavior you want to keep
+- Improve the agent against fixed inputs
+
+This works because the project surface lives in files. The CLI also
+returns structured JSON and records each run as an NDJSON trace. Your
+coding agent can inspect what the framework discovered, run the agent,
+and verify the result without reading terminal prose.
+
+## How do I create an agent with the built-in skill?
+
+Have the coding agent read
+[`skills/create-agent/SKILL.md`](../skills/create-agent/SKILL.md) (in the
+monorepo: `packages/agent-serve/skills/create-agent/SKILL.md`) and follow
+it.
+
+The skill asks about your agent's purpose, runtime, model, channels, MCP
+connections, and capabilities. It then shows you a plan, writes the
+project, and verifies the result.
+
+For example:
+
+> Use the agent-serve create-agent skill to build a PR triage agent
+> reachable through GitHub. It should summarize failed checks, require
+> approval before posting a review, and include one smoke eval.
+
+The skill starts with a small surface: short instructions, one or two
+tools, the channels you chose, and a smoke eval. You can add more after
+the first end-to-end turn works.
+
+## Which built-in skill should I use?
+
+The package ships task-specific guides under [`skills/`](../skills/):
+
+| What you want to do | Skill |
+| --- | --- |
+| Understand the project layout and runtimes | [`framework-map`](../skills/framework-map/SKILL.md) |
+| Create and verify a new agent | [`create-agent`](../skills/create-agent/SKILL.md) |
+| Write fixtures and regression checks | [`evals`](../skills/evals/SKILL.md) |
+| Live A/B metrics on traffic (`defineAB`) | [`ab`](../skills/ab/SKILL.md) |
+| Improve an agent against fixed inputs | [`hillclimb`](../skills/hillclimb/SKILL.md) |
+| Add GitHub webhooks and replay events | [`github`](../skills/github/SKILL.md) |
+| Connect an agent to Slack | [`setup-slack`](../skills/setup-slack/SKILL.md) |
+| Diagnose a local run | [`debug`](../skills/debug/SKILL.md) |
+
+Point your coding agent at the matching `SKILL.md`. The guide contains
+the workflow, commands, and common mistakes for that task.
+
+> [!NOTE]
+> The skill bodies use the current `agent-serve` CLI names. This guide
+> uses the upcoming `agentkit` names. See
+> [Run the CLI](./README.md#run-the-cli) for the full rename table.
+
+## How does a coding agent verify its work?
+
+The coding agent should discover the project, test each server tool,
+run a real turn, and finish with evals:
+
+```bash
+agentkit validate --dir .
+agentkit info --dir . --json
+
+agentkit call inspect_pr --dir . \
+  --input '{"prUrl":"https://github.com/acme/checkout/pull/42"}'
+
+agentkit run --dir . \
+  --message "Is https://github.com/acme/checkout/pull/42 ready to approve?"
+
+agentkit trajectory --events .agentkit/traces/<sessionId>.ndjson
+
+agentkit eval --dir . --list
+agentkit eval --dir . --json
+```
+
+`serve` boots without an API key, which is enough to check channel
+mounts and the playground shell. Model turns need a credential. When the
+environment lacks one, finish every key-free check, then hand the `run`
+and `eval` commands to the operator.
+
+Test server tools with `call` before tuning the prompt. It runs a tool
+in-process with schema validation and no model turn. If the tool returns
+the wrong data, a prompt change won't fix it.
+
+`validate` and `run` don't type-check the project because tsx strips
+types. Run the project's TypeScript check before shipping. Tool results
+must also be JSON-shaped. Use object literals or `type` aliases for
+`execute` return types instead of `interface` types.
+
+## How do I improve the agent after its first run?
+
+Scaffolding proves the agent runs. It says nothing about quality. Once a
+smoke turn passes, give the hillclimb skill:
+
+1. **Fixtures**: one to three fixed inputs, such as a PR URL, a
+   canonical question, or a saved webhook payload
+2. **Success criteria**: correct tool choice, fewer tool calls, lower
+   wall time, or better output
+3. **The freeze line**: the API contract, output shape, and existing
+   evals that must stay unchanged
+
+Have the coding agent read
+[`skills/hillclimb/SKILL.md`](../skills/hillclimb/SKILL.md). It measures
+the current run, proposes one change, remeasures the same fixtures, and
+adds an eval for each kept improvement.
+
+## Related
+
+- [Create your first agent](./quickstart.md)
+- [Scaffold an agent with Cursor](./scaffolding-agents.md)
+- [Evals](./evals.md)
+- [Hillclimbing](./hillclimbing.md)
+- [CLI reference](./reference/cli.md)

package/docs/concepts.md

@@ -0,0 +1,177 @@
+---
+title: "How agentkit works"
+description: "Understand projects, sessions, event streams, channels, and runtimes in plain language."
+---
+
+# How agentkit works
+
+An agent is a folder of instructions and capabilities. agentkit
+discovers those files, runs conversations, and records what happened.
+
+## What happens when someone sends a message?
+
+Follow one message through the system:
+
+1. A channel receives the message from HTTP, Slack, GitHub, or another
+   webhook.
+2. The channel starts a session or continues an existing one.
+3. The runtime gives the model its instructions, tools, and workspace.
+4. The model replies and can call tools along the way.
+5. agentkit appends every message and tool call to the session's
+   event stream.
+
+The channel is the front door. The runtime does the work. The event
+stream is the record you inspect later.
+
+## How do files become an agent?
+
+Each capability has a home in the project. The path tells
+agentkit what to load. The filename becomes the capability's
+name. For example, `agent/tools/get_weather.ts` creates a tool named
+`get_weather`.
+
+| Path | What it is |
+| --- | --- |
+| `agent/agent.ts` | Model and runtime settings |
+| `agent/instructions.md` | The always-on system prompt |
+| `agent/tools/<name>.ts` | Typed actions the model can call |
+| `agent/skills/*` | Procedures loaded when needed |
+| `agent/mcp-connections/<name>.ts` | Tools from external MCP servers |
+| `agent/channels/*.ts` | HTTP, Slack, and GitHub entry points |
+| `agent/ab.ts` or `agent/ab/*.ts` | Sticky variants and live performance metrics |
+| `evals/**/*.eval.ts` | Repeatable checks at the project root |
+
+Other folders add subagents, hooks, schedules, and workspace files. You
+don't register them elsewhere. Run `agentkit validate` to catch
+invalid files before serving the project.
+
+See [Project layout](./reference/project-layout.md) for every supported
+path.
+
+## How does agentkit identify a conversation?
+
+A session is one durable conversation. It has two identifiers:
+
+- **`continuationToken`** tells a channel which conversation to resume.
+  A Slack channel can use its thread ID. A GitHub channel can use the
+  pull request. The built-in HTTP API returns an opaque token and
+  rotates it after each accepted follow-up.
+- **`sessionId`** identifies the stored session. Use it to stream
+  events, inspect the session, resolve approvals, or bind a tool call to
+  the session.
+
+Use the continuation token to keep talking. Use the session ID to
+observe or manage the conversation.
+
+## How do I see what an agent did?
+
+Each session writes an append-only NDJSON file:
+`sessions/<id>/events.ndjson`. It includes:
+
+- Messages and streamed text
+- Requested tool calls and their results
+- Approval requests and decisions
+- Turn completion and token usage
+
+Sessions and their event streams survive server restarts. The
+playground renders the stream. Evals assert against it. The
+`agentkit trajectory` command turns a saved stream into a short
+summary.
+
+When a run surprises you, inspect its event stream first. See
+[Sessions and streaming](./reference/sessions.md) for every event.
+
+## What does a channel control?
+
+A channel connects the agent to a surface such as HTTP, Slack, GitHub,
+or a custom webhook. It controls:
+
+- Routes and input schemas
+- Authentication
+- Conversation identity
+- How replies return to the user
+
+The built-in HTTP session API is always available. Custom routes accept
+loopback callers by default. Add an auth policy before sharing them over
+a network.
+
+Channels should also prepare deterministic input for the model. For
+example, a GitHub channel can fetch the pull request, collect the diff,
+and seed the workspace before the turn starts. The model can then focus
+on the review instead of gathering files.
+
+See [Channels](./reference/channels.md) for route and authentication
+details.
+
+## Where does a turn run?
+
+Choose a runtime in `agent/agent.ts`:
+
+| | Local (default) | Cloud |
+| --- | --- | --- |
+| Turn runs on | The server host | A Cursor cloud agent |
+| Server tools and approvals | Supported | Not supported |
+| Agent tool scripts | Supported | Supported |
+| Skills and seeded files | Added to the session workspace | Must exist in the cloud repository |
+| Repository | You provide it | The cloud agent checks it out |
+
+Use the local runtime when the host has the tools and files the agent
+needs. Use the cloud runtime when each turn needs an isolated repository
+checkout. `agentkit validate` warns when a cloud agent uses a
+local-only capability.
+
+See [Cloud runtime](./guides/cloud-runtime.md) for setup and trade-offs.
+
+## What files can a local session access?
+
+Each local session gets its own workspace. agentkit writes the
+instructions as `AGENTS.md`, installs authored skills, copies sandbox
+files, and adds agent tool scripts.
+
+The workspace is a real Cursor project. It can inherit `AGENTS.md` and
+`.cursor` settings from parent directories. If your agent lives inside
+a large monorepo, set `defineAgent({ local: { cwd } })` to a clean
+directory or pass a separate `--state-root`. The `run` and `eval`
+commands already use temporary state.
+
+Durable local state uses this shape:
+
+```text
+<project>/.agentkit/
+  sessions/<id>/events.ndjson
+  sessions/<id>/workspace/
+  traces/<sessionId>.ndjson
+```
+
+## How can one agent call another?
+
+Every mounted agent also serves MCP at `/<slug>/v1/mcp`. Another agent
+or MCP client can use `ask`, `check`, and `call_tool` to delegate work.
+A peer MCP connection such as
+`defineConnection({ agent: "weather-agent" })` adds those tools to the
+calling agent.
+
+See [Agent-to-agent](./guides/agent-to-agent.md) for a complete example.
+
+## Which rules prevent common setup problems?
+
+- Use Node 22.13 or newer. Bun isn't supported.
+- Put evals under the project-root `evals/` directory, not
+  `agent/evals/`.
+- Run a TypeScript check before shipping. `validate` and `run` execute
+  TypeScript but don't type-check it.
+- Return JSON-shaped values from tool `execute` functions.
+- Keep local session workspaces away from parent rules you don't want
+  the agent to inherit.
+- Sign in or set `CURSOR_API_KEY` before starting a model turn.
+  Discovery, validation, direct tool calls, and server startup work
+  without a credential.
+
+## Related
+
+- [Quickstart](./quickstart.md)
+- [Project layout](./reference/project-layout.md)
+- [Sessions and streaming](./reference/sessions.md)
+- [Channels](./reference/channels.md)
+- [Live A/B metrics](./ab.md)
+- [Cloud runtime](./guides/cloud-runtime.md)

package/docs/deployment.md

@@ -0,0 +1,218 @@
+---
+title: "Deployment"
+description: "Run agentkit on a real host: the auth model, credentials, durable state, single-box and Docker setups, and the production flags."
+---
+
+# Deployment
+
+agentkit is a plain Node HTTP server. It runs anywhere Node
+22.13+ runs: a VM, a container platform, ECS. This page covers the parts
+that matter beyond local development: who can reach the server, where
+credentials and state live, and the flags that change meaning in
+production.
+
+## The security model in one minute
+
+Everything defaults to loopback-only. Until you change something, no
+route is reachable from another machine. `serve` binds `127.0.0.1`
+unless you pass `--host`. Every route runs an auth-policy chain whose
+default, `localDevStrict()`, admits direct loopback callers only, rejects
+requests carrying proxy-forwarding headers (`X-Forwarded-For`,
+`X-Real-IP`, `Forwarded`, `X-Forwarded-Host`), and requires a loopback
+`Host` header. A same-host reverse proxy, a tunnel, or a DNS-rebinding
+page can't silently re-expose the API.
+
+Three ways to open it up, in order of preference:
+
+1. **`--bearer-token <secret>`** replaces the default with
+   `bearerAuth(secret)` on every channel that doesn't author its own
+   auth. Clients send `Authorization: Bearer <secret>`; the playground
+   has a token field. Use this for anything shared.
+2. **Authored auth.** Channels declare their own `auth` chains:
+   `bearerAuth`, signature verification, custom policies. Authored
+   chains always win over serve-level flags. The GitHub channel is the
+   model: `allowAll()` at the route plus HMAC verification in the
+   channel.
+3. **`--allow-anonymous`** replaces the default with `allowAll()`, and
+   every caller shares one `anonymous` principal. Only behind a trusted
+   network boundary. The server refuses to start when
+   `--allow-anonymous` is combined with Cursor account MCP connections,
+   because any admitted caller could drive the signed-in account's
+   connectors. Mutually exclusive with `--bearer-token`.
+
+Session routes also bind to the principal that created the session
+(other principals get `403`). A single static bearer token maps every
+holder to one shared principal. So it isolates the host, not the users
+on it. For per-user isolation, pass a verifier function to `bearerAuth`
+that returns a distinct principal per presented token.
+
+## Credentials
+
+A host reads at most five kinds of credentials.
+
+| Credential | Used for | Provide it as |
+| --- | --- | --- |
+| Cursor API key | model turns, cloud runtime, Cursor account MCP connections | `agentkit login` (stores a revocable key), `CURSOR_API_KEY`, or `--api-key` / `serve({ apiKey })` |
+| Slack tokens | Slack channels | `<PREFIX>_SLACK_BOT_TOKEN` + `<PREFIX>_SLACK_APP_TOKEN` per agent |
+| GitHub webhook secret | delivery signature verification | `GITHUB_WEBHOOK_SECRET`, same value on server and signer |
+| GitHub API | outbound API calls | a GitHub App (`GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY` + installation id) or `GITHUB_TOKEN` / `gh auth login` |
+| MCP connection tokens | authored MCP connections | whatever env vars your `mcp-connections/*.ts` read |
+
+The Cursor credential resolves in one order everywhere: an explicit
+`apiKey` option or `--api-key`, then `CURSOR_API_KEY`, then the key
+stored by `agentkit login`. `agentkit whoami` shows which
+one is active and why. `logout` removes the stored key, and revoking it
+in the Cursor dashboard invalidates it immediately. Mint a dedicated key
+per host. `login` names it after the hostname, so you can revoke each one
+independently.
+
+## State
+
+Durable state lives under `--state-root` (default
+`<project>/.agentkit`): sessions, event streams, session
+workspaces, the SDK conversation store, channel buffers, cursor-events
+offsets.
+
+Put it on a persistent volume. Sessions survive restarts and streams
+replay only if the directory does. Put it outside any repository, to keep
+ambient `AGENTS.md` or `.cursor` rules out of session workspaces.
+`/var/lib/agentkit` is a good home. Back it up like the
+conversation history it is. Deleting a session directory removes that
+session from the server. The SDK conversation store under `runner/` keeps
+its own copy until you delete it too.
+
+## A single box
+
+The minimum production host is two processes and a private network:
+
+```bash
+# the server: all agents under one port
+CURSOR_API_KEY=… GITHUB_WEBHOOK_SECRET=… \
+  agentkit serve --dir /srv/agents --port 3000 --host 127.0.0.1 \
+  --state-root /var/lib/agentkit --bearer-token "$CURSOR_AGENT_KIT_TOKEN"
+
+# GitHub agents only: ONE forwarder relaying live deliveries to loopback
+GITHUB_TOKEN= GH_TOKEN= GITHUB_WEBHOOK_SECRET=… \
+  agentkit github forward --dir /srv/agents --repo owner/repo
+```
+
+Run both under a supervisor. systemd is the durable choice. tmux
+survives SSH disconnects but not reboots. On a TTY, `serve` restarts on
+Enter (it reloads agent code). Under a supervisor, restart the process.
+Sessions and streams are durable either way.
+
+Inbound network requirements are small. Slack needs none at all: Socket
+Mode dials out. Prefer GitHub via `--cursor-events` so the host pulls
+events with no inbound network (see
+[Pull events from Cursor](./guides/github.md#pull-events-from-cursor)).
+A public HTTPS webhook endpoint with the secret on both ends, or the
+forwarder above, is the fallback when you terminate GitHub deliveries
+yourself. Humans reach the playground through your private network or a
+tunnel.
+Keep `--bearer-token` on, because tunneled requests arrive from loopback
+and IP-based policies can't tell them apart.
+
+Health checks: `GET /v1/health` at the host level (made for ALB and ECS
+checks), and each agent also serves `/<slug>/v1/health`.
+
+## Docker
+
+The repository includes a [`Dockerfile`](../Dockerfile) used for an
+internal deployment. It builds the workspace deps and the playground
+bundle and runs multi-agent serve as a non-root user. But its `CMD`
+passes `--allow-anonymous`, because that deployment sits behind an
+authenticating proxy. Don't copy that flag without one. That image also
+enables `--cursor-events` to pull GitHub events (see the
+[GitHub guide](./guides/github.md#pull-events-from-cursor)).
+
+Until the package rename ships, the real image paths are still
+`dist/bin/agent-serve.js` and `/var/lib/agent-serve` (see the
+[rename table](./README.md#run-the-cli)). The baseline shape to copy,
+shown with post-rename names:
+
+```dockerfile
+# build: pnpm install + pnpm --filter @cursor/july run build
+# run (today: agent-serve.js and /var/lib/agent-serve):
+CMD ["node", "--import", "tsx", "dist/bin/agentkit.js", "serve", \
+     "--dir", "examples", "--mode", "multi", \
+     "--host", "0.0.0.0", "--port", "3000", \
+     "--state-root", "/var/lib/agentkit"]
+```
+
+Inside a container, `--host 0.0.0.0` is required. Pair it with real auth
+(`--bearer-token`, or authored auth per channel), or keep the container
+on a private network. Mount the state root as a volume, install `git` and
+`gh` in the image when channels do host-side GitHub work (the shipped
+Dockerfile does), and inject secrets as env vars at start. Nothing secret
+belongs in the image.
+
+## Serve many agents from one process
+
+Point `serve` at a folder of agent projects and every child mounts under
+its directory name on one port. One process, one state root, one
+credential:
+
+```bash
+agentkit serve --dir /srv/agents
+# index at /, each agent at /<slug>/v1/*, /<slug>/playground
+```
+
+`GET /` is a web index of every agent and `GET /v1/agents` is the JSON
+equivalent. Sessions are isolated per agent under `<stateRoot>/<slug>/`.
+Each agent needs its own Slack app and token pair. Agents without tokens
+mount with their Slack channel idle.
+
+Only mount what you mean to run. Every mounted agent's channels are live,
+and webhook-driven agents spend model budget on every wake. `--mode
+single` serves exactly one agent at the unslugged `/v1/*` when that agent
+is the whole host.
+
+## The production flags
+
+These flags change meaning between a laptop and production.
+
+| Flag | In production |
+| --- | --- |
+| `--dev` | Off. Dev mode admits unsigned loopback GitHub deliveries, widens playground session listing on loopback, and never auto-fires schedules. |
+| `--bearer-token` | On for anything shared. Rotate it like any secret. |
+| `--allow-anonymous` | Only behind a trusted network boundary (e.g. an SSO-authenticating load balancer). Also widens playground session listing/streaming so Slack and webhook sessions appear. Never with account-level connectors. |
+| `--state-root` | A persistent volume, outside any repo. |
+| `--public-url` | Set when cloud-runtime turns must call back into peers on this host. |
+| `--no-playground` | Optional hardening when no human needs the UI. Also removes the `/` and `/v1/agents` index routes. |
+| `--no-docs` | Removes the documentation site at `/docs`. |
+| `--no-schedules` | Disable cron firing on secondary hosts so schedules run exactly once. |
+
+Schedules fire on their cron cadence (UTC) in production mode. They have
+no cross-host coordination, so enable them on exactly one serving process
+per project.
+
+## Restarts and upgrades
+
+Restarts are safe by design: sessions, event streams, and the SDK
+conversation store are durable under the state root. Two caveats. Parked
+tool approvals don't survive a restart. They resolve as interrupted, and
+you re-run the turn. And reminders created with in-memory `run` handlers
+are disarmed after a restart (`handler_lost_on_restart`). Re-arm them
+from the code path that created them, or use prompt-form reminders.
+
+## Observability
+
+`GET /v1/logs` (per agent) exposes recent server log lines: the same ring
+buffer the playground's Logs tab polls. For structured export, author a
+[hook](./reference/hooks.md). Subscribe to `turn.completed`,
+`turn.failed`, and `action.result`, then forward to your metrics system.
+Hook errors are logged, never fatal. For any incident, the session
+streams under the state root are the source of truth:
+`agentkit trajectory --events <file>` summarizes one, and the
+playground renders it.
+
+## What's next
+
+Continue with these pages:
+
+- [Channels](./reference/channels.md#auth-policies): the auth policies
+  in detail
+- [GitHub guide](./guides/github.md): delivery paths that don't need a
+  public URL
+- [Troubleshooting](./troubleshooting.md): the symptom table for when a
+  deploy misbehaves