@cursor/july 0.1.1

package/docs/guides/webhooks.md

@@ -0,0 +1,201 @@
+---
+title: "Webhooks & custom channels"
+description: "Give the agent its own HTTP surface: validated routes, sessions keyed to your domain, and replies delivered back out."
+---
+
+# Webhooks and custom channels
+
+A custom channel gives the agent its own HTTP surface. You get routes
+with validated payloads, sessions keyed to something in your domain (a
+thread, a ticket, a PR), and replies delivered back to the caller. The
+[Slack](./slack.md) and [GitHub](./github.md) packs build on this
+mechanism. This page is the mechanism itself.
+
+## What you already have
+
+The built-in HTTP channel is always mounted (under `/<slug>` in the
+default multi-agent layout). `POST /v1/session` starts a conversation,
+`POST /v1/session/:id` follows up, and `GET /v1/session/:id/stream`
+streams NDJSON events, plus sessions, approvals, and tool routes. The
+full list is in the [HTTP API reference](../reference/http-api.md).
+
+Write a custom channel when that shape doesn't fit: a webhook with its
+own payload contract, a surface that keys sessions by a domain id, or a
+flow that does host-side work before (or instead of) a model turn.
+
+## Define a channel
+
+Author `agent/channels/<id>.ts` with `defineChannel`. The filename is
+the channel id, and routes mount under `/v1/channels/<id>`:
+
+```ts
+import { defineChannel, POST } from "@cursor/july/channels";
+import { z } from "zod";
+
+export default defineChannel({
+  routes: [
+    POST("/message", {
+      description: "Enqueue a chat turn on this channel",
+      bodySchema: z.object({
+        message: z.string(),
+        thread: z.string().optional(),
+      }),
+      handler: async (_req, { send, body }) => {
+        const session = await send(body.message, {
+          // stable key: same thread → same durable session
+          continuationToken: body.thread,
+        });
+        return Response.json({ sessionId: session.id });
+      },
+    }),
+  ],
+  events: {
+    "message.completed"(event, channel, ctx) {
+      // deliver the reply back to the surface that owns this channel:
+      // post to a webhook, reply in a thread, update a ticket, …
+    },
+  },
+});
+```
+
+```bash
+curl -X POST http://127.0.0.1:3000/<slug>/v1/channels/<id>/message \
+  -H 'content-type: application/json' \
+  -d '{"message":"hello","thread":"ticket-42"}'
+```
+
+## Schemas are Zod, and required
+
+`GET` routes require a Zod `querySchema`. `POST`, `PUT`, and `PATCH`
+require a Zod `bodySchema`. Compile-time checks enforce this, so plain
+JSON Schema objects won't type-check. Use `z.object({})` or
+`z.unknown()` when a surface is intentionally open. The host validates
+before your handler runs, handlers receive typed `args.body` and
+`args.query`, and empty POST bodies are coerced to `{}` first.
+
+Declared schemas also feed `GET /v1/info`, which adds two things to the
+playground: a **Try** button on every route, and matching **slash
+commands** in the composer (a channel `drive` route becomes `/drive …`).
+
+## What a handler receives
+
+Handlers get the Fetch `Request` plus an args object:
+
+| Helper | What it does |
+| --- | --- |
+| `send(message, options?)` | Run a model turn on this channel. `continuationToken` keys the durable session; options can seed `workspaceFiles`, attach `cloud` repos, or override `auth`. |
+| `getSession(sessionId)` | Look up an existing session |
+| `receive(channel, input)` | Hand off to another channel (schedules use this) |
+| `callTool(name, input, opts?)` | Run an authored server tool with no model turn ([Tools](../reference/tools.md#call-a-tool-without-a-model-turn)) |
+| `body`, `query`, `params` | Validated payloads and path params |
+| `auth` | The `AuthContext` the route's auth chain resolved |
+| `requestIp` | The TCP peer address |
+| `host` | Shared host services: `host.mcp`, `host.github`, `host.slack`, `host.reminders` |
+| `waitUntil(promise)` | Background work that outlives the response |
+
+Channel `state` declares the starting per-session adapter state. It
+persists across events, and event handlers receive it on
+`channel.state`.
+
+## Respond fast, work in the background
+
+Webhook senders time out quickly. GitHub gives you about ten seconds.
+For slow work, ACK immediately and continue in the background:
+
+```ts
+handler: async (_req, { send, waitUntil, body }) => {
+  waitUntil(
+    send(`Process incoming report: ${body.url}`, {
+      continuationToken: `report:${body.id}`,
+    })
+  );
+  return Response.json({ accepted: true }, { status: 202 });
+},
+```
+
+## Prepare on the host, then hand off
+
+The strongest channel pattern: do the deterministic setup in the
+handler, then hand the model prepared evidence. Fetch the PR with
+`callTool`, seed the files it needs, and make the prompt about judgment
+rather than about finding things:
+
+```ts
+handler: async (_req, { callTool, send, body }) => {
+  const prep = await callTool("prepare_pr", { pr: body.pr });
+  if (prep.isError) {
+    return Response.json({ ok: false, error: prep.result }, { status: 502 });
+  }
+  const session = await send("Review the prepared PR under pr/.", {
+    continuationToken: `pr:${body.pr}`,
+  });
+  return Response.json({ sessionId: session.id });
+},
+```
+
+This host-prep shape is the change with the largest effect on latency
+and quality. [Hillclimbing](../hillclimbing.md) lists it first.
+
+## Deliver replies back out
+
+The `events` map subscribes the channel to stream events for the
+sessions it owns. Typical wiring: `message.completed` posts the
+assistant text back to the caller's surface, and `turn.failed` posts an
+error notice. The full vocabulary is in
+[Sessions and streaming](../reference/sessions.md#the-event-vocabulary).
+
+## Auth: loopback by default, on purpose
+
+Every route runs an auth-policy chain (the channel's `auth` array). The
+default is `[localDevStrict()]`: direct loopback callers only. Requests
+carrying proxy-forwarding headers (`X-Forwarded-For`, `X-Real-IP`,
+`Forwarded`, `X-Forwarded-Host`) are rejected, and a loopback `Host`
+header is required. So a tunnel, a same-host reverse proxy, or a
+DNS-rebinding page can't silently re-expose the route.
+
+Before real traffic, author auth explicitly:
+
+```ts
+import { bearerAuth, defineChannel, localDevStrict } from "@cursor/july/channels";
+
+export default defineChannel({
+  auth: [localDevStrict(), bearerAuth(process.env.WEBHOOK_TOKEN ?? "")],
+  routes: [/* … */],
+});
+```
+
+The built-in policies are `localDevStrict()` (the default),
+`localDev()`, `loopbackOnly()`, `bearerAuth(tokenOrVerify)`, and
+`allowAll()`, and any `(request, info) => AuthContext | null` function
+composes with them. Signature-verified surfaces usually use `allowAll()`
+at the route and verify the HMAC in the channel; the GitHub channel with
+a webhook secret works this way. The details live in
+[Channels](../reference/channels.md#auth-policies).
+
+Server-level flags interact with channel auth. `--bearer-token <secret>`
+swaps the default for `bearerAuth` on every channel that doesn't author
+its own chain, and `--allow-anonymous` swaps it for `allowAll()`
+(trusted networks only). Authored `auth` arrays always win over both.
+
+## Test a channel
+
+Start with curl and saved payloads under `fixtures/`. The playground's
+**Try** modal covers manual probes. It remembers your last body per
+endpoint, has Copy curl, and opens the created session on a successful
+Try. For regression coverage, drive the same behavior through an eval,
+or keep channel logic deterministic in `agent/lib/` and unit-test it
+there. When something looks wrong, read the session's `events.ndjson`.
+The stream is the record of what happened.
+
+For GitHub specifically, don't hand-roll fixtures.
+`agentkit github replay` synthesizes real-shaped, signed payloads
+from any PR you can read. See the [GitHub guide](./github.md).
+
+## What's next
+
+Continue with these pages:
+
+- [Channels reference](../reference/channels.md): the full authoring API
+- [GitHub](./github.md) and [Slack](./slack.md): the packaged channels
+- [Sessions and streaming](../reference/sessions.md): events your
+  channel can subscribe to

package/docs/hillclimbing.md

@@ -0,0 +1,93 @@
+---
+title: "Hillclimbing"
+description: "Improve an agent one measured round at a time, with the hillclimb skill running the loop with you."
+---
+
+# Hillclimbing
+
+Make an agent better on fixed inputs: measure, change one lever, remeasure, and lock every kept win with an eval.
+
+## What is hillclimbing?
+
+Hillclimbing is a measured improvement loop. You pin a few fixtures, name the one dominant problem in the run, change one lever, and check the same fixtures again. Keep only what helps. Every kept change lands an [eval](./evals.md) so the win stays put.
+
+You don't have to run the loop alone. The package ships a coding-agent skill that drives it with you.
+
+```mermaid
+flowchart LR
+  measure[Measure] --> change[Change one lever]
+  change --> remeasure[Remeasure]
+  remeasure --> measure
+```
+
+## How do I hillclimb an agent with a coding agent?
+
+Have Cursor read [`skills/hillclimb/SKILL.md`](../skills/hillclimb/SKILL.md).
+
+Tell it:
+
+1. **Which agent** you're improving (path or slug)
+2. **One to three fixtures** you'll reuse every round: a PR URL, a saved webhook body, or a canonical chat prompt
+3. **What "better" means** this round: correct tool choice, fewer tools, lower latency, or output quality. Name the freeze line too: API shape, public output, and existing evals that must stay green
+
+The skill serves the agent, hits your fixtures, reads the session trajectory, proposes one change, remeasures, and checks with you before the next round.
+
+Other skills cover the edges:
+
+| When you need… | Skill |
+| --- | --- |
+| The measured improvement loop | [`skills/hillclimb/SKILL.md`](../skills/hillclimb/SKILL.md) |
+| An eval that locks a kept win | [`skills/evals/SKILL.md`](../skills/evals/SKILL.md) |
+| Repeatable GitHub webhook inputs | [`skills/github/SKILL.md`](../skills/github/SKILL.md) |
+| A run that misbehaves | [`skills/debug/SKILL.md`](../skills/debug/SKILL.md) |
+
+See [Building agents with agents](./building-with-agents.md) for every framework skill and a good first prompt.
+
+## What do I need before a hillclimb round?
+
+Agree on four things before you edit:
+
+1. **The target agent**: the project you're improving
+2. **Fixtures**: one to three fixed inputs you can compare across runs
+3. **Success criteria**: what better means this round
+4. **The freeze line**: what must not change
+
+Pin the input first. A moving fixture is noise. For GitHub agents, use `agentkit github replay` (see the [GitHub guide](./guides/github.md)). For a single tool without a model turn, use `agentkit call`. For a chat turn, use `agentkit run --dir . --message "…"`.
+
+## How do I run one hillclimb round?
+
+**Measure.** Hit the agent the way a user would: playground, channel HTTP, or Slack in `--dev`. Or ask the hillclimb skill to do it. `agentkit run` returns a JSON trajectory and writes a trace under `.agentkit/traces/`.
+
+**Reflect.** Score the trajectory, not impressions. Was the answer right? Did the model thrash (too many tools, fat evidence, grep loops)? Did it invent work the host should have prepared? Name the single dominant problem for this round in one sentence. Example: "Full-file dumps trigger grep loops."
+
+**Change one lever.** Prefer the smallest change that addresses that problem:
+
+1. Host prep: seed what the model needs so it doesn't hunt
+2. Evidence shape: trim or reorder artifacts
+3. Instructions and skills: tighten the procedure
+4. Tool surface: remove or gate tools that invite wandering
+5. Framework changes: only when the agent can't express the fix
+
+**Remeasure.** Same fixtures. Diff tools, wall time, and quality side by side. Keep the change only if the target metric improves and the freeze line holds.
+
+## How do I lock a hillclimb improvement with an eval?
+
+Every kept change needs an eval that would have failed before the change: a tool-choice gate, an `action.result` count bound, or an output-shape check. Run `agentkit eval --dir . --json` between rounds. Never weaken an existing gate to pass the round.
+
+Details live in [Evals](./evals.md). The evals skill will author the case with you.
+
+## What habits help hillclimbing stay reliable?
+
+- One problem per round. Don't bundle "trim evidence and rewrite instructions" unless you chose that on purpose.
+- Keep fixtures fixed until you deliberately need a harder case.
+- Separate host work from model tools when you blame latency. Moving deterministic prep onto the host is often the biggest win. In one PR reviewer, host-prepared evidence cut turns from about 8 minutes to about 1 minute.
+- Spot-check quality on at least one fixture against a known-good answer. Efficiency-only climbs quietly drop findings.
+- Treat `turn.failed` with `"turn interrupted"` as expected when a follow-up or stop preempted the turn.
+- Don't deploy, post to real surfaces, or weaken evals as part of a climb.
+
+## Related
+
+- [Evals](./evals.md)
+- [Building agents with agents](./building-with-agents.md)
+- [GitHub guide](./guides/github.md)
+- [Fix common agent problems](./troubleshooting.md)

package/docs/quickstart.md

@@ -0,0 +1,183 @@
+---
+title: "Build your first weather agent"
+description: "Create a weather agent, add a typed tool, run it from the terminal, and open it in the playground."
+---
+
+# Build your first weather agent
+
+Create an agent, give it a weather tool, run a complete turn, and chat
+with it in the browser.
+
+## Prerequisites
+
+You need:
+
+- Node 22.13 or newer. Bun isn't supported.
+- The `agentkit` CLI. See [Run the CLI](./README.md#run-the-cli)
+  for the current package and command names.
+- A Cursor credential for model turns. Sign in once:
+
+```bash
+agentkit login
+```
+
+You can also set `CURSOR_API_KEY` instead of signing in.
+
+## Scaffolding Agents
+
+Have Cursor read [`skills/create-agent/SKILL.md`](../skills/create-agent/SKILL.md)
+and describe what you want:
+
+> Build me a weather agent for the playground. Start with one weather
+> tool and guide me through the remaining decisions.
+
+Cursor asks for missing choices, shows you the plan, then builds and
+verifies the agent. Continue below to do the same by hand.
+
+See [Scaffold an agent with Cursor](./scaffolding-agents.md) for the
+full guided workflow.
+
+## Create your project
+
+Start with the built-in scaffold:
+
+```bash
+agentkit init ./weather-agent
+cd weather-agent
+```
+
+The scaffold creates the files agentkit discovers:
+
+```text
+weather-agent/
+├── agent/
+│   ├── agent.ts
+│   ├── instructions.md
+│   └── tools/
+│       └── echo.ts
+└── package.json
+```
+
+`agent.ts` holds the model and runtime settings. `instructions.md` is
+the always-on system prompt. Each file under `agent/tools/` becomes a
+tool.
+
+Check the project before you run it:
+
+```bash
+agentkit validate --dir .
+agentkit info --dir .
+```
+
+These commands inspect the project without starting a model turn.
+
+## Run your agent
+
+The scaffold already works. Run one turn from the terminal:
+
+```bash
+agentkit run --dir . \
+  --message "Introduce yourself in one sentence."
+```
+
+`run` starts the agent, sends the message, and waits for the final
+reply. It prints a JSON trajectory with the response, tool calls, and
+token usage. It also writes an NDJSON trace under
+`.agentkit/traces/`.
+
+## Add weather instructions
+
+Replace `agent/instructions.md`:
+
+```md
+# Weather agent
+
+You are a concise weather assistant.
+
+- Use `get_weather` before answering questions about current weather.
+- Tell the user the weather data is simulated.
+- Keep replies to two sentences or fewer.
+```
+
+Remove the demo echo tool:
+
+```bash
+rm agent/tools/echo.ts
+```
+
+## Add a weather tool
+
+Create `agent/tools/get_weather.ts`:
+
+```ts
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description: "Get simulated current weather for a city.",
+  inputSchema: z.object({
+    city: z.string().describe("City name, such as San Francisco"),
+  }),
+  async execute({ city }) {
+    const temperatureF = Math.round(Math.random() * (90 - 32) + 32);
+
+    return {
+      city,
+      temperatureF,
+      conditions: "sunny",
+    };
+  },
+});
+```
+
+The file adds one tool named `get_weather`:
+
+- `description` tells the model when to call it.
+- `inputSchema` defines and validates the arguments.
+- `execute` runs on the server and returns data to the model.
+
+This version uses simulated data so you can run it without another API
+key. Replace `execute` with a weather API when you're ready.
+
+## Try the weather tool
+
+Call the tool directly first:
+
+```bash
+agentkit call get_weather --dir . \
+  --input '{"city":"San Francisco"}'
+```
+
+`call` validates the input and runs `execute` without a model turn. If
+the result looks right, ask the agent:
+
+```bash
+agentkit run --dir . \
+  --message "What's the weather in San Francisco?"
+```
+
+The agent calls `get_weather`, receives the result, and uses it in the
+final reply. agentkit runs the tool loop for you.
+
+## Open the playground
+
+Start the development server:
+
+```bash
+agentkit serve --dir . --dev
+```
+
+Open the playground URL printed in the terminal. Ask the same weather
+question. The playground streams the reply and shows the tool arguments
+and result inline.
+
+## Where to go next
+
+- [Tools](./reference/tools.md): add more typed capabilities, like
+  replacing the simulated weather tool with live Open-Meteo data
+- [Evals](./evals.md): turn this weather question into a regression
+  check
+- [Channels](./reference/channels.md): expose the agent through HTTP,
+  Slack, or another webhook
+- [Building agents with agents](./building-with-agents.md): have a
+  coding agent extend the project for you

package/docs/reference/agent-config.md

@@ -0,0 +1,154 @@
+---
+title: "Agent config"
+description: "defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically."
+---
+
+# Agent config (`agent/agent.ts`)
+
+`agent/agent.ts` default-exports `defineAgent(config)`: which model runs
+the agent, where turns execute, and runtime-specific defaults.
+Everything is optional on the root agent.
+
+```ts
+import { defineAgent } from "@cursor/july";
+
+export default defineAgent({
+  model: {
+    id: "grok-4.5",
+    params: [
+      { id: "effort", value: "high" },
+      { id: "fast", value: "true" },
+    ],
+  }, // optional; this is the default
+  runtime: "local", // default, or "cloud"
+  // cloud: {
+  //   repos: [{ url: "https://github.com/org/repo", startingRef: "main" }],
+  // },
+  // local: { cwd: "../harness" },
+});
+```
+
+## Fields on `defineAgent`
+
+`defineAgent` accepts these fields.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `model` | string or `{ id, params }` | Cursor model for turns. Defaults to `grok-4.5` with `effort=high`, `fast=true` on the root agent. Subagents omit it to inherit. |
+| `name` | string | Display name override. Defaults to the package name or directory name. |
+| `description` | string | What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root. |
+| `instructions` | string | Inline instructions. Prefer `instructions.md`; this exists for subagents and generated configs. |
+| `runtime` | `"local"` or `"cloud"` | Where turns execute. Default `"local"`. |
+| `cloud` | object | Cloud agent defaults: repos, env, envVars, forwarded to the Cursor SDK. Used when `runtime` is `"cloud"`, and as the base merged under per-session `cloud` send options. |
+| `local` | `{ cwd? }` | Local harness defaults; ignored for cloud turns. |
+
+## Choose a model
+
+`model` is a Cursor model id string, or `{ id, params }`. Effort and
+speed are params, not id suffixes. The SDK rejects suffix-style ids
+like `grok-4.5-fast`:
+
+```ts
+model: {
+  id: "grok-4.5",
+  params: [
+    { id: "effort", value: "high" },
+    { id: "fast", value: "true" },
+  ],
+}
+```
+
+A plain string works when you don't need params:
+
+```ts
+model: "composer-2.5",
+```
+
+## Choose a runtime
+
+`runtime: "local"` (the default) runs turns on the Cursor SDK harness on
+this machine. The session id doubles as the SDK agent id, and server
+tools, skills, sandbox seeds, and tool approvals all apply.
+
+`runtime: "cloud"` runs turns on Cursor cloud agents (`bc-…` ids). Pass
+a `cloud` block with the repos the VM carries. In-process server
+tools are not available, and instructions and agent-tool catalogs are
+prepended to the first prompt, because the local session workspace is
+not the cloud VM.
+
+`validate` warns when `runtime: "cloud"` is combined with server tools,
+skills, or sandbox seeds that only apply locally. The full capability
+matrix and the patterns that hold up are in the
+[Cloud runtime guide](../guides/cloud-runtime.md).
+
+## Local cwd
+
+`local.cwd` sets the default parent directory for local harness
+workspaces. Each session uses `<cwd>/<sessionId>` (absolute, or relative
+to the project root) unless a per-send `workspaceDir` overrides it.
+
+This is your control over ambient context. Session workspaces are real
+Cursor project directories, so the harness loads `AGENTS.md` and
+`.cursor` config from ancestor directories. An agent inside a big
+monorepo that must not inherit the monorepo's rules points `cwd`
+outside it (or runs with `--state-root` under `/tmp`). An agent that
+*needs* a specific checkout's skills and rules points `cwd` inside that
+checkout.
+
+## The `cloud` block
+
+Cloud agent defaults forwarded to the Cursor SDK: `repos` (each
+`{ url, startingRef? }`), environment selection, `envVars`, and the
+rest. A local agent uses the same block as the base config when a
+channel opens a cloud-attached session per send. That hybrid pattern is
+covered in
+[Cloud runtime](../guides/cloud-runtime.md#hybrid-local-agent-cloud-sessions).
+
+## Generate instructions
+
+When the system prompt must be computed, author `agent/instructions.ts`
+instead of markdown:
+
+```ts
+import { defineInstructions } from "@cursor/july";
+
+export default defineInstructions({
+  markdown: `You are the on-call assistant for ${process.env.TEAM_NAME}.`,
+});
+```
+
+The directory form and the runtime mapping are in
+[Instructions](./instructions.md).
+
+## Serve programmatically
+
+`serve(dirOrProject, options)` embeds the server in your own process:
+
+```ts
+import { serve } from "@cursor/july";
+
+const handle = await serve("./my-agent", {
+  port: 3000,
+  apiKey: process.env.CURSOR_API_KEY, // optional; see credential order
+});
+console.log(`listening on ${handle.url}`);
+// handle.callTool(...), handle.dispatchSchedule("heartbeat"),
+// handle.createReminder(...), handle.project, await handle.close()
+```
+
+`ServeOptions` mirrors the CLI flags: `port`, `host`, `dev`,
+`stateRoot`, `apiKey`, `schedules`, `reminders`, `playground`,
+`authToken` (the `--bearer-token` equivalent), `allowAnonymous`,
+`publicUrl`, `cursorEvents`, and `mode: "single" | "multi"`. The Cursor
+credential resolves in one order everywhere: explicit `apiKey`, then
+`CURSOR_API_KEY`, then the key stored by `agentkit login`.
+
+## What's next
+
+Continue with these pages:
+
+- [Instructions](./instructions.md): the required half of a minimal
+  agent
+- [Cloud runtime](../guides/cloud-runtime.md): when and how to leave
+  the host
+- [CLI](./cli.md): the flags `ServeOptions` mirrors