@cursor/july 0.1.35 → 0.1.37

package/docs/guides/webhooks.md

@@ -142,7 +142,7 @@ 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).
+[Sessions and streaming](../reference/sessions.md#which-events-can-i-stream).
 
 ## Auth: loopback by default, on purpose
 

package/docs/hillclimbing.md

@@ -56,7 +56,7 @@ Pin the input first. A moving fixture is noise. For GitHub agents, use `agent-sd
 
 ## 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. `agent-sdk run` returns a JSON trajectory and writes a trace under `.agent-sdk/traces/`.
+**Measure.** Hit the agent the way a user would: playground, channel HTTP, or Slack in `--dev`. Or ask the hillclimb skill to do it. `agent-sdk run` returns a JSON trajectory and writes a trace under `.agent-serve/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."
 

package/docs/quickstart.md

@@ -19,8 +19,12 @@ inspectable in the playground.
 You need:
 
 - Node 22.13 or newer. Bun isn't supported.
-- The `agent-sdk` CLI. See [Run the CLI](./README.md#run-the-cli)
-  for the current package and command names.
+- The `agent-sdk` CLI. `npx @cursor/july init ./pr-approver` bootstraps
+  it with no prior install: `init` scaffolds the project, runs
+  `npm install`, and offers a Cursor sign-in, after which `npx agent-sdk`
+  resolves from the project's own dependencies. See
+  [Run the CLI](./README.md#run-the-cli) for other setups, such as a
+  monorepo source checkout.
 - A Cursor credential for model turns. Sign in once:
 
 ```bash
@@ -34,6 +38,28 @@ You can also set `CURSOR_API_KEY` instead of signing in.
   automatically. Reading pull requests works on any public repo;
   posting reviews needs write access to the repo you review.
 
+## First run in 10 minutes
+
+Want a working agent before the full tutorial? Four commands get you
+there:
+
+```bash
+agent-sdk init ./pr-approver     # scaffold + npm install + sign-in offer
+cd pr-approver
+agent-sdk dev                    # serve, and print the playground URL
+```
+
+Open the playground URL and chat with the scaffold. Then, in a second
+terminal (`dev` keeps running), run one turn from the command line:
+
+```bash
+agent-sdk run --dir . --message "Introduce yourself in one sentence."
+```
+
+That's the whole loop: files become an agent, `dev` serves it, and
+`run` exercises it. The rest of this page turns that scaffold into a
+real PR approver.
+
 ## Scaffolding Agents
 
 Have Cursor read [`skills/create-agent/SKILL.md`](../skills/create-agent/SKILL.md)
@@ -74,6 +100,7 @@ pr-approver/
 │   ├── subagents/
 │   ├── channels/
 │   ├── hooks/
+│   │   └── memory.ts
 │   ├── ab/
 │   ├── schedules/
 │   ├── sandbox/workspace/
@@ -84,11 +111,16 @@ pr-approver/
 ```
 
 `agent.ts` holds the model and runtime settings. `instructions.md` is
-the always-on system prompt. Each file under `agent/tools/` becomes a
-tool. `tsconfig.json` type-checks the project (`npm run check`); the
-framework runs your TypeScript directly, so nothing compiles.
+the always-on system prompt, and the scaffold's version includes a
+memory section that tells the agent how to consult its journal. Each
+file under `agent/tools/` becomes a tool, and `agent/hooks/memory.ts`
+journals every turn so future sessions can recall past work (delete it
+to opt out). `tsconfig.json` type-checks the project (`npm run check`);
+the framework runs your TypeScript directly, so nothing compiles.
 
-Check the project before you run it:
+`agent-sdk dev` blocks until you stop it. Keep it running and open a
+second terminal for every other command on this page, starting with
+these checks:
 
 ```bash
 agent-sdk validate --dir .
@@ -109,7 +141,7 @@ agent-sdk run --dir . \
 `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
-`.agent-sdk/traces/`.
+`.agent-serve/traces/`.
 
 ## Teach it to review
 

package/docs/reference/agent-config.md

@@ -40,7 +40,10 @@ export default defineAgent({
 | `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. |
+| `local` | `{ cwd?, workspaceDir?, sandbox? }` | Local harness defaults; ignored for cloud turns. See [Local options](#local-options). |
+| `hosting` | `{ egressDomains?, secretNames? }` | Managed-hosting declarations read by `agent-sdk deploy`: the pod's egress allowlist and the secret names the agent expects. Ignored by local serving. |
+| `concurrency` | `{ maxRunningTurns? }` | Engine-wide turn admission limit. See [Concurrency](#concurrency). |
+| `builtinTools` | `{ reminders? }` | Framework-provided model-facing tools, opted in per capability. See [Built-in tools](#built-in-tools). |
 
 ## Choose a model
 
@@ -71,17 +74,39 @@ 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
+a `cloud` block with the repos the VM carries. Server tools stay
+reachable over authenticated HTTP MCP back to the serve host when
+`--public-url` or `--cloud-tools-url` is set (omitted with a warning
+otherwise), 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 agent tools,
+skills, or sandbox seeds, which only materialize into local session
+workspaces, and when the `cloud` block is missing. The full capability
 matrix and the patterns that hold up are in the
 [Cloud runtime guide](../guides/cloud-runtime.md).
 
-## Local cwd
+## Local options
+
+`local` sets local-harness defaults, all ignored for cloud turns.
+
+`local.workspaceDir` points every session at one shared harness cwd,
+for agents that work inside an existing checkout. It takes precedence
+over `cwd`, and a per-send `workspaceDir` still wins over both. The SDK
+keys its local executor (rules, skills, MCP, ignore mappings) on the
+harness cwd, so a shared directory resolves the workspace once per
+serve process instead of once per session. The trade: sessions share a
+working tree, so a file one turn writes is visible to the next.
+
+`local.sandbox` runs the harness inside Cursor's local sandbox. It's
+off by default, matching the SDK: shell then auto-approves and inherits
+the serve process environment, including any credentials the host
+holds. Turn it on for agents whose turns read untrusted input (webhook
+payloads, PR diffs, inbound chat); it's a real tool boundary rather
+than a prompt-level one.
+
+### Local cwd
 
 `local.cwd` sets the default parent directory for local harness
 workspaces. Each session uses `<cwd>/<sessionId>` (absolute, or relative
@@ -104,6 +129,37 @@ 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).
 
+## Concurrency
+
+`concurrency.maxRunningTurns` caps how many model turns run at once
+across all of the agent's sessions (positive integer, hard cap 200).
+When every slot is busy, newly admitted turns queue FIFO instead of
+failing: the stream records a durable `turn.queued` event with the
+queue position, `GET /v1/sessions` reports `queued: true`, and each
+queued turn starts as soon as a slot frees. A queued turn still counts
+as running for busy semantics: follow-ups preempt it, and direct tool
+calls get `409 session_busy`. Omit for unlimited.
+
+```ts
+export default defineAgent({
+  concurrency: { maxRunningTurns: 3 },
+});
+```
+
+## Built-in tools
+
+`builtinTools` opts into framework-provided model-facing tools. Each
+enabled capability materializes as ordinary server tools at discovery
+time, so turns, direct calls, `info`, and the playground treat them
+like authored tools. Authored tools with the same name win, with a
+warning, and like all server tools they run on the local runtime.
+
+`builtinTools: { reminders: true }` adds three tools bound to the
+current conversation over `host.reminders`: `reminders_create`,
+`reminders_list`, and `reminders_cancel`. Sessions without a
+continuation key can't arm reminders. See
+[Schedules and reminders](./schedules.md#reminders).
+
 ## Generate instructions
 
 When the system prompt must be computed, author `agent/instructions.ts`
@@ -137,11 +193,15 @@ console.log(`listening on ${handle.url}`);
 ```
 
 `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 `agent-sdk login`.
+`stateRoot`, `apiKey`, `schedules`, `reminders`, `noControlPlane`,
+`playground`, `docs`, `authToken` (the `--bearer-token` equivalent),
+`allowAnonymous`, `allowAnonymousCursorGithub`,
+`allowAnonymousCursorAccountMcp`, `cursorGithubProxy`, `publicUrl`,
+`cloudToolsUrl`, `cursorEvents`, and `logger`. `serve()` additionally
+accepts `discovery` (project-loading options) and
+`mode: "single" | "multi"`. The Cursor credential resolves in one order
+everywhere: explicit `apiKey`, then `CURSOR_API_KEY`, then the key
+stored by `agent-sdk login`.
 
 ## What's next
 

package/docs/reference/artifacts.md

@@ -0,0 +1,117 @@
+---
+title: "Artifacts"
+description: "Tag durable outputs (reviewed PRs, reports) so they persist across sessions, stream as events, and list over HTTP."
+---
+
+# Artifacts
+
+An artifact marks a durable output the agent produced: a reviewed PR
+URL, a generated report, a decision record. Sessions come and go;
+artifacts persist across them, capped and listable, so the people
+supervising an agent see what it shipped without replaying event
+streams.
+
+## Declare kinds
+
+Author `agent/artifacts.ts` with `defineArtifacts` from
+`@cursor/july/artifacts`:
+
+```ts
+import { z } from "zod";
+import { defineArtifacts } from "@cursor/july/artifacts";
+
+export default defineArtifacts({
+  kinds: {
+    "reviewed-pr": {
+      description: "A pull request this agent reviewed.",
+      schema: z.object({ url: z.string(), verdict: z.string() }),
+    },
+    report: { description: "A generated report." },
+  },
+  agentTool: true,
+});
+```
+
+`defineArtifacts` accepts three fields. `kinds` declares the artifact
+kinds: with kinds declared, `tag` accepts only these; with none, any
+kind string is accepted freeform. Each kind's `description` says what it
+holds and doubles as the model-facing prompt for `tag_artifact`. An
+optional Zod `schema` validates payloads before they persist (the parsed
+output is stored, so defaults and coercions apply). `agentTool` exposes
+the model-facing `tag_artifact` tool generated from the kinds registry;
+it requires at least one declared kind. `max` is the retention cap,
+default 1000: on insert past the cap, the oldest-updated artifact is
+evicted.
+
+## Tag from host code
+
+Every handler surface carries `ctx.artifacts` (or `args.artifacts`),
+an `ArtifactsApi` with `tag` and `list`: tools, hooks, channel route
+handlers and `onStart`, schedule `run` handlers, and reminder `run`
+handlers. Tool and hook facades are session-bound, so `tag` auto-fills
+the `sessionId` (and `turnId` when known). Channel, schedule, and
+reminder facades are unbound; pass `sessionId` in the tag input to
+attribute one.
+
+```ts
+await ctx.artifacts.tag({
+  kind: "reviewed-pr",
+  key: prUrl,
+  title: `Reviewed ${prUrl}`,
+  data: { url: prUrl, verdict: "approve" },
+});
+```
+
+`key` is the upsert handle: tagging the same key again replaces the
+record instead of creating a new one, so re-reviewing a PR updates one
+row. A `contents` payload (string or bytes, with an optional
+`contentType`) attaches a file or blob served at
+`GET /v1/artifacts/:id/content`; re-tagging a keyed artifact without
+`contents` keeps the existing payload.
+
+## Let the model tag
+
+With `agentTool: true`, the `tag_artifact` server tool materializes from
+the kinds registry. Its description tells the model to tag notable
+outputs and lists each kind with its description, and its input schema
+is a discriminated union over the declared kinds, so a schema'd kind is
+validated exactly like a host-side tag. An authored tool named
+`tag_artifact` shadows the built-in, with a warning.
+
+## Observe and list
+
+Tagging emits an `artifact.tagged` event on the attributed session's
+stream, carrying the record: `id`, `kind`, `key`, `title`, `data`, and
+`source` (`"host"` for host code, `"model"` for `tag_artifact`). Hooks,
+channel `events`, and evals see it like any other
+[stream event](./sessions.md#which-events-can-i-stream).
+
+Over HTTP:
+
+```bash
+curl 'http://127.0.0.1:3000/<slug>/v1/artifacts?kind=reviewed-pr&limit=20'
+curl 'http://127.0.0.1:3000/<slug>/v1/artifacts/<id>/content'
+```
+
+`GET /v1/artifacts` returns records newest-updated first, filterable by
+`kind` and `sessionId`. Session ownership applies, same as
+`/v1/sessions`. The playground renders tagged artifacts too.
+
+## Gate evals on tagging
+
+`t.taggedArtifact(kind?, predicate?)` gates an eval on at least one
+artifact tagged during the test turn, optionally of one kind and
+matching a predicate over the record:
+
+```ts
+t.taggedArtifact("reviewed-pr", (record) => record.source === "model");
+```
+
+## What's next
+
+Continue with these pages:
+
+- [Sessions and streaming](./sessions.md): the `artifact.tagged` event
+  in the full vocabulary
+- [Tools](./tools.md): the `ctx` that carries `artifacts`
+- [Evals](../evals.md): the assertions `taggedArtifact` sits beside

package/docs/reference/channels.md

@@ -115,22 +115,34 @@ Handlers receive the Fetch `Request` and an args object:
 
 | Member                              | What it is                                                                                                                                                                                                                                                                                  |
 | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `send(message, options?)`           | Run a model turn on this channel; returns the session handle. Options: `continuationToken` (the conversation key), `workspaceFiles`, `workspaceDir`, `cloud` (attach cloud repos for this session), `auth` (defaults to the request principal), `sdkAgentId` (resume a specific SDK agent). |
-| `getSession(sessionId)`             | Look up an existing session on this channel                                                                                                                                                                                                                                                 |
-| `receive(channelDefinition, input)` | Hand off to another channel (schedules use this)                                                                                                                                                                                                                                            |
-| `callTool(name, input, options?)`   | Deterministic server-tool call ([Tools](./tools.md#call-a-tool-without-a-model-turn))                                                                                                                                                                                                       |
-| `body`, `query`, `params`           | Validated payloads and `:param` path segments                                                                                                                                                                                                                                               |
-| `auth`                              | The `AuthContext` resolved by this route's auth chain                                                                                                                                                                                                                                       |
-| `requestIp`                         | The TCP peer address                                                                                                                                                                                                                                                                        |
-| `host`                              | Shared services: `host.mcp`, `host.github`, `host.slack`, `host.reminders`                                                                                                                                                                                                                  |
-| `waitUntil(promise)`                | Background work that outlives the response                                                                                                                                                                                                                                                  |
-| `sessionUrls(request, sessionId)`   | Absolute playground + trace URLs for a session on this mount                                                                                                                                                                                                                                |
+| `send(message, options?)`           | Run a model turn on this channel; returns the session handle (options below)                                                 |
+| `getSession(sessionId)`             | Look up an existing session on this channel                                                                                  |
+| `receive(channelDefinition, input)` | Hand off to another channel (schedules use this)                                                                             |
+| `callTool(name, input, options?)`   | Deterministic server-tool call ([Tools](./tools.md#call-a-tool-without-a-model-turn))                                        |
+| `body`, `query`, `params`           | Validated payloads and `:param` path segments                                                                                |
+| `auth`                              | The `AuthContext` resolved by this route's auth chain                                                                        |
+| `requestIp`                         | The TCP peer address                                                                                                         |
+| `host`                              | Shared services: `host.mcp`, `host.github`, `host.slack`, `host.kv`, `host.files`, `host.reminders`                          |
+| `waitUntil(promise)`                | Background work that outlives the response                                                                                   |
+| `sessionUrls(request, sessionId)`   | Absolute playground + trace URLs for a session on this mount                                                                 |
+| `artifacts`                         | Unbound [artifacts](./artifacts.md) facade; pass `sessionId` in `tag` input to attribute one                                 |
+
+`send` options: `continuationToken` (the conversation key),
+`admission` (`"preempt"` interrupts a busy session, the default;
+`"coalesce"` enqueues behind the running turn, the
+[Slack policy](./sessions.md#what-happens-when-i-send-a-follow-up)),
+`workspaceFiles`, `workspaceDir`, `cloud` (attach cloud repos for this
+session), `auth` (defaults to the request principal), `sdkAgentId`
+(resume a specific SDK agent), `state` (starting channel state for new
+sessions), `title` (session display title), `purpose` (`"eval"` skips
+sticky A/B enrollment), and `coalesceSourceTs` (dedupe key for coalesce
+queue items already delivered mid-turn).
 
 ## Events
 
 The `events` map subscribes the channel to stream events for the
 sessions it owns. Keys are event types from the
-[event vocabulary](./sessions.md#the-event-vocabulary), or `"*"`.
+[event vocabulary](./sessions.md#which-events-can-i-stream), or `"*"`.
 Handlers receive `(event, channel, ctx)`, where `channel.state` is the
 per-session adapter state and `ctx` exposes session info and host
 services. This is where a channel delivers replies back to its surface.
@@ -139,10 +151,28 @@ services. This is where a channel delivers replies back to its surface.
 
 `state` declares the starting per-session adapter state (JSON), persisted
 on the session record. Routes and event handlers read and mutate it
-through `channel.state`. `onStart(args)` runs when the channel mounts. It
-receives `send`, `receive`, `callTool`, `host`, and friends; the Slack
-pack opens its Socket Mode connection here. `onStop()` runs when the
-server drains.
+through `channel.state`. `onStart(args)` runs when the channel mounts;
+the Slack pack opens its Socket Mode connection here. `onStop()` runs
+when the server drains.
+
+`onStart` receives the route helpers (`send`, `getSession`, `receive`,
+`callTool`, `host`, `waitUntil`, `artifacts`, and a `logger` that
+respects the server's log sink) plus a set that exists for long-lived
+transports:
+
+- `emitAssistantMessage(sessionId, text)` appends an assistant message
+  without a model turn, for host tasks that already produced the final
+  text.
+- `hasContinuationSession(token)` and `isContinuationBusy(token)`
+  report whether a continuation token has a live session and whether a
+  turn is in flight on it.
+- `getContinuationLastBotMessageTs(token)` reads the Slack warm-delta
+  watermark from channel state.
+- `interruptContinuation(token)` stops the in-flight turn and clears
+  coalesced follow-ups queued behind it.
+- `resolveApproval(sessionId, callId, decision, auth, options?)`
+  approves or denies a parked tool call, how Slack Block Kit buttons
+  unblock a turn without the HTTP approvals route.
 
 ## Auth policies