@cursor/july 0.1.93 → 0.1.94

package/dist/docs/llms-full.txt

@@ -500,6 +500,7 @@ name. For example, `agent/tools/get_weather.ts` creates a tool named
 | `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/host-connections/<name>.ts` | Privileged MCP servers for host tools only |
 | `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 |
@@ -863,26 +864,7 @@ See the [GitHub guide](/docs/guides/github.md).
 
 ### Connect Slack
 
-Hosted Slack supports the team's Cursor Slack app or a dedicated Socket
-Mode app.
-
-Use the Cursor Slack app when mentions and direct messages are enough:
-
-```ts
-import { slackChannel } from "@cursor/july/channels/slack";
-
-export default slackChannel({
-  cursorAccount: true,
-  agentName: "PrApprover",
-});
-```
-
-The team must have the Cursor Slack app installed and Slack event relay
-access enabled. This mode needs no Slack token secrets. It doesn't
-support channel-post watches, tool approvals, or interactivity.
-
-Use a dedicated Socket Mode app for those features or a separate bot
-identity:
+Hosted Slack uses a dedicated Socket Mode app:
 
 ```ts
 import { slackChannel } from "@cursor/july/channels/slack";
@@ -1105,6 +1087,417 @@ Continue with these pages:
 
 ---
 
+Source: /docs/design/agsh.md
+
+# agsh: a shell for deployed agents
+
+## What this is
+
+`agsh` (agent shell) is a standalone CLI that connects to one agent-sdk
+deployment and turns the agent's live tool surface into commands. Every tool
+the deployment can execute (authored server tools and tools provided by the
+agent's MCP connections) becomes a subcommand with a synopsis derived from its
+input schema, a man-page style `--help`, and a place in an interactive shell.
+
+It is a separate binary and a separate package from `agent-sdk`. The
+`agent-sdk` CLI stays what it is today: the developer workflow tool for
+authoring, validating, deploying, and debugging agent projects. `agsh` is the
+operator's tool for working *inside* one deployed agent. The split also keeps
+heavy presentation dependencies (markdown rendering, syntax highlighting, the
+shell interpreter) out of `@cursor/july`, which ships to every agent project.
+
+## The experience
+
+```
+$ agsh help                        # list of commands, man-page style
+$ agsh read --help                 # man-page style: NAME, SYNOPSIS, DESCRIPTION, OPTIONS
+$ agsh read /repo/README.md
+$ agsh datadog_list_monitors --query "service:api"
+$ agsh                             # bare: interactive shell on a TTY, script from stdin otherwise
+❯ ls /repo | grep -i readme
+❯ read /repo/config.json | jq .version
+```
+
+Every invocation binds to the deployment's latest session by default, with
+`--session` and `--continuation-token` overrides, and prints the session
+identifier as a final stderr line.
+
+## Configuration
+
+`agsh` is a client only; it never boots an agent. Every invocation needs a
+target deployment, given by flags or by environment variables. Flags always
+win over the environment.
+
+Global command line options, accepted on every command and on the bare shell
+launch:
+
+| Option | Environment default | Meaning |
+| --- | --- | --- |
+| `--target <url \| name>` | `AGENT_SHELL_TARGET` | The deployment to talk to: a URL is a local deployment (`http://127.0.0.1:39400/executor`), a name a production one (`change-monitor-executor`). |
+| `--team <team>` | `AGENT_SHELL_TEAM` | Team override for production resolution, when the login spans several. |
+| `--bearer-token <token>` | `AGENT_SHELL_BEARER_TOKEN` | Explicit bearer auth for a deployment that is not behind the Cursor login. |
+| `--session <id>` | | Bind to a specific session instead of the latest. |
+| `--continuation-token <token>` | | Bind by continuation token instead of session id. |
+| `--output <text\|json>` | | Result rendering: human-friendly views (default) or raw JSON. |
+| `-h`, `--help` | | Per-command help. |
+
+One parameter carries the whole target selection, and the value's shape
+encodes the mode: a URL (`http://` or `https://`) targets a local
+deployment, anything else names a production one. Two options with a
+precedence rule would invite exactly the confusion a target selector must
+not have; with one parameter the only rule is that the flag beats the
+environment. A URL is self-contained down to the agent because one local
+agent-sdk serve process hosts every agent of the project (change-monitor's
+dev stack mounts `/executor` and `/planner` from a single port); a
+production deployment is a single agent, so its name is the complete
+address (`--team` narrows resolution when the login spans several).
+Authentication defaults to the stored Cursor login (the same engine-access
+credential agent-sdk uses); `--bearer-token` is the escape hatch for direct
+deployments. Session flags are per invocation and have no environment
+default: a session is state, not configuration. Color output follows the
+`NO_COLOR` convention and TTY detection; there is no agsh-specific color
+setting. No configuration file: one environment variable pins a working
+target for a terminal session
+(`AGENT_SHELL_TARGET=change-monitor-executor`, or a URL for a local stack),
+which is the whole persistent-configuration need.
+
+With no target from flags or environment, every command fails with a message
+naming both ways to provide one.
+
+## Architecture
+
+### A new package
+
+A new workspace package (working name `packages/agsh`, bin `agsh`) that
+depends on `@cursor/july` for target resolution, stored Cursor login, and the
+HTTP client plumbing. It owns the presentation stack: `marked` for terminal
+markdown (moved out of `@cursor/july`), with syntax highlighting (`shiki`)
+arriving in the phase that renders code; the shell interpreter is
+purpose-built (see Rationale).
+No new abstraction seam between the two packages; `agsh` imports what it
+needs until a second consumer justifies extracting a thin client.
+
+### The tool catalog
+
+At startup `agsh` fetches one live catalog of everything invocable on the
+deployment. This is the piece the current `/v1/info` cannot provide: `/v1/info`
+projects the authored manifest, and connection tools only exist at runtime,
+resolved per session under the connection's auth. A new endpoint provides the
+live view (see Backend changes).
+
+Catalog entries carry exactly one identifier each: the tool name exactly as
+the agent sees it. Authored server tools keep their authored name (`read`).
+Connection tools appear under their model-facing advertised name (the
+sanitized passthrough name from `advertise-tools.ts`, e.g.
+`datadog_list_monitors`). The CLI never invents a different naming format:
+a tool name copied from a session transcript is a valid `agsh` command, and
+vice versa. Where a tool came from — the upstream connector name when the
+tool declares one, the connection name otherwise — is a field on the
+catalog entry, not part of the identifier.
+
+### Two command tiers
+
+Each catalog entry becomes a command, through one of two shapes:
+
+**Curated commands for builtin tools.** The well-known tool names (`ls`,
+`read`, `grep`, `glob`, `diff`, ...) get hand-designed, POSIX-flavored
+command shapes, hardcoded in `agsh` next to their titles. These tools are
+what an operator types all day; their shapes should feel like the unix
+commands they mirror, not like generated bindings. A curated shape decides
+which schema fields are positional operands and which are flags, and every
+input has exactly one spelling: an operand is only an operand, never also a
+flag.
+
+```
+$ agsh read /repo/package.json --limit 2
+{
+  "name": "change-monitor",
+→ ses_a99d1b69c329eb75a2ec8603
+
+$ agsh grep -i -A 2 toolEffect /repo/src
+src/tool-policy.ts:12:export type ToolEffect = "read" | "write";
+...
+→ ses_a99d1b69c329eb75a2ec8603
+
+$ agsh ls /repo --ignore-globs '*.test.ts' --ignore-globs 'node_modules/**'
+```
+
+`read` takes its path as an operand mapped to the schema's `path` field, with
+`--offset` and `--limit` as integer flags. `grep` follows POSIX grep:
+`grep [options] <pattern> [path]`, with the rg-style options (`-i`, `-A`,
+`-B`, `-C`, `--output-mode`, `--head-limit`) mapping onto the schema fields
+of the same names (kebab-cased). `ls` shows array input: an array field's flag repeats once
+per element. A curated shape binds to the deployment's live schema at
+startup; when a deployment's tool lacks the expected field, the command
+degrades to the generic shape below rather than guessing.
+
+A curated shape may also reformat the tool's text result toward the unix
+command's own output conventions: the VFS ls tool returns the model-facing
+tree (`  - name/` rows under a header), and `agsh ls` prints it as standard
+ls does, one name per line with the trailing slash kept on directories. The
+tool's result string itself stays what the model sees; when a result does
+not match the expected shape it prints verbatim.
+
+**Generated commands for MCP tools.** Connection tools are dynamically
+discovered, so no special treatment is possible; they get a uniform
+schema-derived mapping:
+
+- Every schema property is accepted as one flag, spelled as the
+  kebab-cased property name (`org_slug` → `--org-slug`) — the unix
+  convention; kebab collisions gain a numeric suffix. Properties already
+  shaped like flags (grep's `-i`) stay literal. No positionals, no other
+  aliases.
+- Object-typed properties flatten recursively into one flag per leaf,
+  dash-joined (`--telemetry-context` for `telemetry.context`), so every
+  option reads as a plain value; a free-form object with no declared
+  properties stays one JSON-valued flag. A leaf is required only when its
+  whole ancestor chain is.
+- Values are coerced by schema type: booleans are valueless flags, numbers
+  and integers are parsed, arrays accept the flag repeated once per element,
+  enums are validated before the call.
+
+```
+$ agsh datadog_list_monitors --query "service:api" --limit 10
+```
+
+In both tiers `-h`/`--help` and the global target and session flags are
+reserved and injected, a flag that names no schema property fails before any
+request (listing the tool's actual properties), and the bound session prints
+as a final stderr line.
+
+### Result rendering
+
+Raw JSON on a terminal is not an experience for people, so `--output=text`
+(the default) renders structured results through a small set of views,
+selected automatically by the shape of the value each call actually returned;
+tool metadata plays no part, since most tools advertise no output schema, and
+many return structured data as JSON text. A string result that parses as a
+JSON object or array counts as structured. An array of objects renders as a
+table (columns are the union of keys, missing cells stay blank, the table
+clamps to the terminal width); a single object renders as a property view
+(aligned keys, scalar lists as bullets, nested structures indented); an
+object that is nothing but an error wrapper renders as an `Error:` line;
+plain text prints verbatim. `--output=json` renders the structured value as
+raw JSON. The rendering never depends on the TTY: piped and interactive
+output carry the same content, only color follows TTY detection.
+
+### Help rendering
+
+`--help` on a tool renders a man-page layout: NAME (the tool name, with the
+tool's `title` beside it when the catalog carries one; titles are curated
+data, never derived from the description), SYNOPSIS (operands from the
+curated shape; options never enumerate — they summarize as `[options...]`,
+man-page style, so the line stays bounded), DESCRIPTION (the tool
+description rendered as terminal markdown), OPERANDS (positional arguments,
+curated commands only), and OPTIONS. Descriptions of operands and options
+come from the schema's property descriptions. Effect and approval metadata
+render as notes when declared. Everything except the curated shape derives
+from `GET /v1/tools/:name`; nothing else is hand-written per tool.
+
+```
+$ agsh read --help
+NAME
+    read - Read a file
+
+SYNOPSIS
+    read [options...] <path>
+
+DESCRIPTION
+    Reads a file from the local filesystem. This tool can also read image
+    files when called with the appropriate path. Formats supported:
+    jpeg/jpg, png, gif, webp.
+
+OPERANDS
+    <path>
+        The absolute path of the file to read.
+
+OPTIONS
+    --offset <integer>
+        The line number to start reading from. Positive values are 1-indexed
+        from the start of the file. Negative values count backwards from the
+        end. Only provide if the file is too large to read at once.
+
+    --limit <integer>
+        The number of lines to read. Only provide if the file is too large
+        to read at once.
+
+NOTES
+    Effect: read (performs no writes).
+```
+
+`agsh help` lists the available command names grouped by source, authored
+tools first, then one group per upstream connector (its name is the group
+header — one aggregating connection can host tools from several connectors,
+and the connector name is what an operator recognizes). Each row is the
+name, with the title beside it when the tool declares one; everything else
+lives behind the command's `--help`:
+
+The agent's description renders as a DESCRIPTION section when the deployment
+declares one (`/v1/info` carries both name and description).
+
+```
+$ agsh help
+NAME
+    change-monitor-executor
+
+DESCRIPTION
+    Executes monitoring plans against changed code.
+
+COMMANDS
+    diff                     Show workspace changes
+    glob                     Find files by pattern
+    grep                     Search file contents
+    ls                       List a directory
+    read                     Read a file
+    report_change_issue
+    report_change_succeeded
+
+DATADOG
+    datadog_list_monitors    List monitors
+    ...
+
+Run any command with --help for its synopsis and options.
+```
+
+### Shell mode
+
+Invoked bare, `agsh` starts a shell. On a TTY this is a REPL; on a pipe it
+reads a script from stdin, so `echo 'ls /' | agsh` and here-docs work.
+
+The interpreter is purpose-built and minimal: tokenizing (quotes, escapes),
+pipelines, and `;` / `&&` / `||`. The command namespace is exactly the
+deployment's tool catalog plus a small curated set of local pipe filters
+(`head`, `tail`, `wc`, stdin-filtering `grep`), so a tool name can never be
+shadowed. There is no local filesystem, no variables, no control flow: agsh
+has nothing local to operate on, and every command is a single traced
+`POST /v1/tools/:name` call.
+
+The shell binds one session identity at launch (latest by default) and keeps
+it for the whole run, so a sequence of tool calls observes one consistent
+session context.
+
+## Backend changes on the agent-sdk runtime
+
+Two read endpoints, mirroring the invocation path:
+
+**`GET /v1/tools`: the live tool listing.** Returns the session's tool
+namespace exactly as a turn would assemble it: authored server tools plus the
+advertised passthrough tools synthesized from connections, under their
+model-facing names. Entries are light (name, source, and `title` when one is
+known); everything else lives behind the detail endpoint. Titles have two
+sources and no new authoring surface: connection tools inherit the upstream
+server's MCP title, which the host already propagates length-capped off
+listings; tools that do not come from MCP get theirs from a hardcoded
+name-to-title table in the runtime's endpoint implementation, covering the
+well-known tool names. A tool in neither place has no title. Accepts the same
+optional session binding as invocation (`session` or `continuationToken`)
+because advertised inventories can be tenant-scoped and resolved per session.
+Implementation reuses the existing plumbing: the discovered manifest for
+authored tools and the advertise-tools synthesis (`McpHost.listTools`, or the
+`oneOff` path when per-session auth substitution applies) for connection
+tools. This is not a duplicate of `/v1/info`: the info document stays the
+static authored manifest; the listing is the runtime view that only the
+running deployment can answer.
+
+**`GET /v1/tools/:name`: one tool's full description.** Description, input
+schema, output schema when declared, effect when declared, approval
+requirement, and source connection. Same path as invocation
+(`POST /v1/tools/:name`), different method: GET describes what POST executes,
+for the same identifier.
+
+Invocation needs no new naming scheme. Advertised connection tools are
+synthesized as ordinary server tools in the session's namespace, so
+`POST /v1/tools/:name` addresses them by their model-facing name like any
+authored tool, with the same session binding, policy checks, and per-call
+tracing. (The direct-call path did need the synthesis step added: it now
+resolves the advertised listing for the call's session identity when the
+authored lookup misses.)
+
+Phase 1 ships the minimal runtime surface agsh calls: the `effect`
+projection in `/v1/info` (rendered in per-tool help), the scratch-workspace
+fallback on direct calls, and `continuationToken` binding on
+`POST /v1/tools/:toolName`. The detail endpoint in phase 2 also closes the
+output-schema gap; `/v1/info` stays as it is.
+
+## Local development loop
+
+`factory/change-monitor` is the test bed. Its `pnpm start` already serves the
+planner and executor locally through the agent-sdk dev runtime
+(`agent-sdk serve --dir . --dev`). The loop:
+
+1. `cd factory/change-monitor && pnpm start` (local stack, both agents).
+2. `agsh --target http://127.0.0.1:<port>/<agent>` against it, via a dev shim
+   analogous to `agent-sdk-dev` so the CLI runs from the worktree.
+3. Iterate end to end: VFS verbs (`ls`, `read`, `grep`, `glob`, `diff`) for the
+   authored-tool path, and the planner's tenant connectors for the
+   connection-tool path once `GET /v1/tools` exists.
+
+## Removing the inspector surface from agent-sdk
+
+The inspector CLI is still on development branches, so nothing migrates: the
+CLI-side code is removed from `agent-sdk` and `agsh` is built in its place.
+
+- The verb commands (`ls`, `read`, `grep`, `glob`, `diff`) become the
+  curated tier: their hand-designed shapes, schema-binding logic (including
+  the candidate-field fallback), and session binding carry over. The
+  schema-to-argv flag mapping seeds the generated tier for MCP tools.
+- The `tools` and `skills` commands disappear entirely. `agsh help` and
+  per-tool `--help` are the discovery surface.
+- `marked` and `shiki` leave `@cursor/july`; agsh's help rendering takes
+  `marked`, and `shiki` returns when agsh ships syntax highlighting.
+  `agent-sdk` keeps its developer workflow commands unchanged.
+
+## Plan
+
+1. **Package and core invocation.** Create the package, port target
+   resolution, the schema-to-argv mapping, and help rendering from the
+   inspector code. Authored tools only, against the existing endpoints.
+   Verified end to end on the local change-monitor stack.
+2. **Live catalog.** Add `GET /v1/tools` and `GET /v1/tools/:name` to
+   the agent-sdk runtime, with the hardcoded title table for non-MCP tools, and verify
+   direct invocation resolves advertised connection tools by their
+   model-facing names. Connection tools appear as commands. Verified against
+   the planner's connectors.
+3. **Shell mode.** The purpose-built mini-shell: REPL on TTY, script on
+   stdin, tools as the command namespace, one session per shell run.
+4. **Cleanup.** Remove the inspector CLI surface and presentation
+   dependencies from `@cursor/july`.
+
+## Rationale and rejected alternatives
+
+**Why not extend `agent-sdk`.** The audiences differ: `agent-sdk` is for the
+person building and deploying an agent; this tool is for the person operating
+inside one. Bundling also forces every agent project to carry markdown
+rendering, syntax highlighting, and a bash interpreter it never uses.
+
+**Name.** `agsh` reads as "agent shell", is four characters, collides with
+nothing common, and works as a shell prompt name. Considered: `august`
+(pairs with `july` but says nothing about purpose), `toolsh` (awkward to
+pronounce), `cursor-shell` (too broad; this is scoped to one agent).
+
+**Why a REST catalog instead of the MCP endpoint.** The deployment already
+speaks MCP at `/v1/mcp/tools`, including a per-connection bridge, but the
+bridge is bound to an active turn and speaks JSON-RPC. The CLI wants a plain
+authenticated GET with session binding that returns the assembled tool
+namespace under the names the model sees. Wrapping that in MCP framing buys
+nothing for a first-party client.
+
+**Why a purpose-built interpreter instead of just-bash.** just-bash was the
+original plan (a full bash emulation with a custom-command extension point),
+and a prototype disproved it: custom commands replace its coreutils but can
+never shadow its shell builtins, and `read`, `test`, `type`, and `help` are
+builtins — so the flagship `read` tool is unreachable, and the precedence is
+not ours to control (vercel-labs owns the package). No other embeddable JS
+shell interpreter has a workable custom-command story (mvdan-sh's JS build
+does not expose one; bash-parser is a parser only). agsh also needs almost
+none of bash: no local filesystem, no variables, no control flow — just
+tokenizing, pipelines, and a command namespace it fully owns. A TypeScript
+REPL with tools as async functions (the shape of change-monitor's `script`
+tool) was considered and kept as a possible later addition; it trades away
+the unix muscle memory the curated commands exist for.
+
+---
+
 Source: /docs/evals.md
 
 # Evals
@@ -1294,2749 +1687,279 @@ Assert with the gates:
 | `t.eventOrder(matchers)` | matching event groups occur in this relative order |
 | `t.eventsSatisfy(label, predicate)` | your predicate over the typed event stream |
 | `t.check(value, expectation)` | any value, against a builder |
-| `t.score(name, value)` | records a 0–1 score you computed; soft until you add a bar |
-| `t.requireToolCall(name, matcher?)` | gates on a matching call and returns it, so later code can read its input and output |
-| `t.requireInputRequest(filter?)` | gates on exactly one pending approval request and returns it |
-
-Every gate returns a handle: `.soft()` demotes it to tracked-only,
-`.atLeast(0.7)` adds a soft score bar, and `.gate(0.8)` promotes a
-scored assertion into a hard gate.
-
-With no matcher, `calledTool` is request-based: a requested call counts
-even when its result has not arrived. Pass
-`t.calledTool("inspect_pr", { status: "completed" })` to require the
-call to return. `input`, `output`, and `count` matcher fields accept a
-literal, a `RegExp`, or a predicate.
-
-The expectation builders are `includes(string | RegExp)`,
-`equals(value)`, `matches(schema)`, `similarity(expected)`, and
-`satisfies(predicate, label)`. `includes` stringifies its input,
-`equals` compares values deeply, `matches` validates against a Standard
-Schema (or anything with `safeParse`, like Zod), `similarity` scores
-normalized text similarity, and `satisfies` runs your predicate. The
-plain function `normalizedSimilarity(actual, expected)` returns the
-same 0–1 score for use with `t.score`.
-
-A few more context members shape a case: `t.require(value, expectation)`
-records a gate and stops the test body when it fails, without a
-duplicate execution error. `t.skip(reason)` ends the case as skipped
-(reported separately, never changes the exit code; call it before
-sending messages). `t.metric(name, value)` records a structured score
-for the playground case card. `t.log(message)` records a debug line for
-the CLI and playground result.
-
-Three `t.send` options apply on session create (first `t.send` only):
-
-- `workspaceFiles`: `{ path: contents }`, seeded into the local session
-  workspace. Prefer this over machine-local paths.
-- `workspaceDir`: absolute harness cwd (local runtime).
-- `cloud`: per-session cloud options merged over the agent's static
-  `cloud` config (repos / env / …). Use a pinned `repos` override to
-  attach a fixture repo for cloud evals without putting it on the
-  agent's default `cloud.repos`. Cloud ignores `workspaceFiles` seeds.
-
-```ts
-const toolResults = t.events.filter((e) => e.type === "action.result");
-t.check(
-  toolResults.length,
-  satisfies((n) => (n as number) <= 4, "at most 4 tool calls")
-);
-```
-
-A case with no explicit gates falls back to whether at least one turn
-completed successfully. Add `t.succeeded()` and behavior-specific gates
-anyway. They make the contract visible during review.
-
-### Judge free-form output
-
-When wording matters and no regex captures it, `t.judge` grades the
-reply with an LLM. The built-in graders are `factuality(expected)`,
-`summarizes(expected)`, `closedQA(criteria)`, and `sql(expected)`. Each
-scores `t.reply` by default; pass `{ on }` to grade another value.
-
-```ts
-t.judge.factuality("It is 54°F in NYC right now.").atLeast(0.7);
-```
-
-Judge assertions are soft by default, so a judge never fails a build
-until you give it a bar with `.atLeast(0.7)` or promote it with
-`.gate(0.8)`. The judge model comes from `defineEvalConfig({ judge })`,
-`defineEval({ judge })`, a case-level `judge`, or a per-call
-`{ model }` override; the nearest one wins. For a domain-specific judge
-whose verdict is not a single score, `t.judge.model(prompt)` sends a
-raw prompt to the same model and returns the reply. You then record the
-parsed result with `t.score` or `t.check`.
-
-## Run evals from the CLI
-
-The `eval` command discovers, filters, and runs cases.
-
-Run the CLI under Node 22.13 or newer. Do not use Bun. Its HTTP/2 client
-breaks tool-result streams and causes eval turns to fail.
-
-```bash
-agent-sdk eval --dir . --list                         # discover only
-agent-sdk eval --dir .                                # run all
-agent-sdk eval --dir . builds/checkout                # one datapoint
-agent-sdk eval --dir . builds search                  # several ids or prefixes
-agent-sdk eval --dir . --tag smoke --tag pull-request # any matching tag
-agent-sdk eval --dir . --json --no-stream             # machine-readable results
-agent-sdk eval --dir . --verbose                      # logs + reply snippets
-```
-
-Id filters use OR semantics. Each filter selects an exact id and its
-descendants. For example, `builds` selects `builds`,
-`builds/checkout`, and every other case below that path. Repeated tags
-also use OR semantics. When you provide both ids and tags, a case must
-match both groups.
-
-`eval` boots an ephemeral server on port 0 with a temp state root
-outside the project, so cases don't inherit ambient monorepo rules and
-don't write into the project state directory. Point `--url` at a running server to eval
-a live agent instead:
-
-```bash
-agent-sdk eval --dir . \
-  --url http://127.0.0.1:3000/weather-agent \
-  --bearer-token "$AGENT_TOKEN"
-```
-
-The eval definitions still come from `--dir`; `--url` only changes the
-agent that receives the turns. For a locally mounted multi-agent
-directory, `--slug weather-agent` chooses the target. Use
-`--state-root` to keep ephemeral session state at a chosen path,
-`--timeout-ms` to override the project timeout, and `--no-stream` to
-keep live progress off stderr. A TTY streams turn progress by default.
-`--verbose` still writes `t.log` lines to stderr and adds reply snippets
-to text results.
-
-Model turns need a Cursor credential from `agent-sdk login` or
-`CURSOR_API_KEY`.
-
-See [CLI: eval](/docs/reference/cli.md#eval) for flags and exit codes.
-
-### JSON results
-
-Use `--json --no-stream` in scripts and CI. The top-level result carries
-the totals and one result per case:
-
-```json
-{
-  "ok": true,
-  "passed": 1,
-  "failed": 0,
-  "results": [
-    {
-      "id": "readiness",
-      "ok": true,
-      "assertions": [{ "name": "succeeded", "passed": true }],
-      "sessionId": "ses_123",
-      "inputs": ["Is checkout pull request 42 ready to approve?"],
-      "toolCalls": [{ "toolName": "inspect_pr", "isError": false }],
-      "logs": [],
-      "durationMs": 12340
-    }
-  ]
-}
-```
-
-Each case result can also include `description`, `finalText`, `tools`,
-`error`, and tool arguments or output. This shape lets CI report the
-failed assertion without parsing terminal text.
-
-## Run evals in the playground
-
-Start the server, open the playground, and choose **Evals**. You can run
-every case or one case, watch progress, and open the resulting session
-trace. The Evals tab works on a normal `serve`.
-
-```bash
-agent-sdk serve --dir .
-```
-
-Playground runs target the live server instead of an ephemeral one.
-Their sessions appear in the session list. One eval batch can run at a
-time. Persistence follows the rule under
-[Configure eval runs](#configure-eval-runs). See
-[Playground eval routes](/docs/reference/http-api.md#playground-eval-routes).
-The start request returns `202` while cases run in the background.
-Poll until the snapshot status becomes `completed`, `failed`, or `cancelled`.
-Configuration errors appear on a failed snapshot.
-
-On `--prod` / `--url`, the CLI prints the Eval ID as soon as the batch is
-accepted (and a Playground deep link with `?view=evals&evalRunId=…`):
-
-```bash
-agent-sdk eval --prod --slug vulnerability-scanner --tag deepsec
-# Eval ID: evalrun_…
-# Cancel:  agent-sdk eval cancel evalrun_… --prod --slug vulnerability-scanner
-# Playground: https://…/playground?view=evals&evalRunId=evalrun_…
-
-agent-sdk eval cancel evalrun_… --prod --slug vulnerability-scanner
-agent-sdk eval status evalrun_… --prod --slug vulnerability-scanner
-```
-
-## What good cases assert
-
-Gate decisions and shape, not prose. Model wording varies run to run.
-Tool choice, tool avoidance, and output structure are the stable
-contract.
-
-1. `t.succeeded()`: always, first.
-2. The tool decision: `calledTool` for the intended path,
-   `notCalledTool` for the likely wrong alternative. The pair is
-   stronger than either alone.
-3. Output shape: a regex for the contract (`/ready|blocked/i`, a JSON
-   marker, a findings-block fence), never exact sentences.
-4. For structured output, parse `t.reply` and check fields with
-   `satisfies` instead of substring-matching JSON.
-
-The common failure modes: asserting exact phrasing, packing more than
-about five gates into one case (split it), and cases that depend on live
-external state that drifts (pin the input; see fixtures).
-
-## Pick fixtures by agent type
-
-The right fixture depends on the surface under test.
-
-| Agent surface | Fixture |
-| --- | --- |
-| Chat / domain assistant | A canonical prompt string, chosen once and frozen |
-| Tool-heavy | Run `agent-sdk call <tool>` first to pin what the tool returns, then freeze the prompt that triggers it |
-| GitHub webhook | `agent-sdk github replay <pr> --events '*' --dry-run --out fixtures/github` snapshots real payloads for offline replay ([GitHub guide](/docs/guides/github.md)) |
-| PR reviewer with host preparation | Diff, metadata, and gold labels pinned to commit SHAs; keep any live PR matrix small |
-| Workspace-dependent | `workspaceFiles` in `t.send` options, never developer-machine paths |
-
-Tag the fast, reliably passing core `smoke` and run `--tag smoke` in the
-inner loop. Leave slow or flaky-prone cases untagged for explicit runs.
-
-### Materialize API-backed fixtures
-
-An input that only points at external data, such as a pull request URL,
-snapshot id, or pair of commit SHAs, is not self-contained. Fetch it
-once and commit the rendered fixture before you expand the suite.
-
-1. Save the diff, metadata, and labels under `fixtures/` at pinned
-   revisions.
-2. Seed those files with `workspaceFiles`, or read them from the fixture
-   directory.
-3. Assert decisions and output shape against the saved evidence.
-4. Keep a small `smoke` subset for any remaining live pipeline checks.
-
-Read committed fixtures with `@cursor/july/evals/loaders`: `loadJson`,
-`loadJsonl`, and `loadYaml` resolve relative paths against the project
-root the runner discovered, not the cwd the CLI was invoked from
-(`resolveFixturePath` and `evalFixtureRoot` expose the same
-resolution for other file formats).
-
-`maxConcurrency` limits parallel datapoints. It does not limit model or
-API fan-out inside one datapoint. Materialized fixtures prevent a large
-suite from exhausting provider and GitHub rate limits. The
-[evals skill](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/evals/SKILL.md) has the full fixture workflow.
-
-## Keep improvements with regression evals
-
-Every [hillclimb](/docs/hillclimbing.md) round that keeps a change must land
-an eval that would have failed before the change. If you can't express
-the improvement as a gate (a `calledTool` shift, a bounded
-`action.result` count, an output-shape regex), the improvement is
-unverified, and it'll regress silently.
-
-The rule cuts the other way too: never weaken an existing gate to make a
-round pass. That's the freeze line moving, and it turns your regression
-suite into a list of checks that no longer protect anything.
-
-## Compare variants on live traffic
-
-Use `defineAB` to compare variant metrics on live sessions. It is not a
-test runner and has no `agent-sdk ab` command. Keep `defineEval` as the
-regression ratchet. Eval sessions do not enroll or change live metrics.
-See [Live A/B metrics](/docs/ab.md) for assignment, behavior, collection,
-and inspection.
-
-## What's next
-
-Continue with these pages:
-
-- [Live A/B metrics](/docs/ab.md): sticky variants and cumulative metrics
-  on live sessions
-- [Hillclimbing](/docs/hillclimbing.md): the loop evals make trustworthy
-- [Building agents with agents](/docs/building-with-agents.md): have a
-  coding agent write the first suite
-- [GitHub guide](/docs/guides/github.md): deterministic webhook fixtures
-  with `github replay`
-- [Sessions and streaming](/docs/reference/sessions.md): the events
-  `t.events` contains
-
----
-
-Source: /docs/example-agents/approval-buddy.md
-
-# Keep PR approval policy deterministic with Approval Buddy
-
-Approval Buddy approves eligible pull requests from a fixed roster and
-declines every other request. GitHub still blocks self-approval when the stamp
-identity authored the PR. Code decides eligibility. The model prepares
-evidence, runs two specialist reviews, and passes their findings to the
-approval tool without changing the policy decision.
-
-Use this example when an agent can make a judgment inside a workflow, but
-authorization and the final side effect must stay in deterministic code.
-
-[Browse the Approval Buddy source.](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/approval-buddy/)
-
-## Keep approval policy in code
-
-Approval Buddy draws three hard boundaries:
-
-- `prepare_review` and `approve_pr` re-read the live PR and apply the same
-  eligibility rules.
-- Two subagents inspect prepared evidence, but their findings never grant or
-  block approval.
-- Only `approve_pr` posts the GitHub review.
-
-A spoofed webhook, Slack message, or model claim can't add someone to the
-buddy roster. The mutating tool checks the source of truth immediately before it
-acts.
-
-## Follow the intended stamp flow
-
-The root instructions ask the model to run this sequence for a qualifying PR:
-
-1. A non-draft `pull_request` event arrives with action `opened`, `reopened`,
-   or `ready_for_review`.
-2. The GitHub channel checks its repository allowlist and starts a session.
-3. `turn.started` posts a pending commit status.
-4. The model calls `prepare_review`.
-5. Host code fetches the live PR. It checks the author, open state, merged
-   state, and draft state.
-6. A qualifying PR gets `pr/MANIFEST.md`, `pr/meta.json`, and
-   `pr/diff.patch` in the session workspace. Diffs above 2,000,000
-   characters are truncated and marked in metadata.
-7. The model calls both review subagents through the built-in `task` tool.
-8. It concatenates their contracted replies and calls `approve_pr`.
-9. `approve_pr` re-runs eligibility, posts an `APPROVE` review, and returns
-   the outcome.
-10. The channel posts a final commit status. A self-approval block also gets
-    a short timeline comment because no approval review can appear.
-
-Ineligible PRs skip evidence and subagents. The model still calls
-`approve_pr` so the deterministic tool returns the formal decline reason.
-
-Steps 4 through 9 are prompt-driven. The channel doesn't enforce tool order
-or prove both subagents ran, and `approve_pr` accepts missing findings. A
-failed turn clears the pending status with a green non-blocking result without
-approving the PR.
-
-## Map the framework features
-
-| Capability | Source | Role |
-| --- | --- | --- |
-| Root agent and policy prompt | [`agent/agent.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/approval-buddy/agent/agent.ts), [`agent/instructions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/approval-buddy/agent/instructions.md) | Configure the local agent and describe orchestration order. |
-| GitHub channel | [`agent/channels/github.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/approval-buddy/agent/channels/github.ts) | Filter wakes, lease GitHub access, and publish status events. |
-| Slack channel | [`agent/channels/slack.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/approval-buddy/agent/channels/slack.ts) | Accept approval-bot stamp and qualification requests. |
-| Server tools | [`agent/tools/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/approval-buddy/agent/tools/) | Prepare evidence, approve, list buddies, and search GIFs. |
-| Deterministic policy | [`agent/lib/approve.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/approval-buddy/agent/lib/approve.ts), [`agent/lib/buddies.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/approval-buddy/agent/lib/buddies.ts) | Own the roster and live eligibility checks. |
-| Review subagents | [`agent/subagents/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/approval-buddy/agent/subagents/) | Run deep audit and code-quality passes over the same evidence. |
-| Storage | [`agent/storage.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/approval-buddy/agent/storage.ts) | Persist sessions and events with `cursorHostedStorage`. See [Storage](/docs/storage.md). |
-| Live A/B experiment | [`agent/ab.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/approval-buddy/agent/ab.ts) | Compare baseline responses with a concise, presentation-only treatment (`concise-results`). |
-| Evals and unit tests | [`evals/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/approval-buddy/evals/), [`agent/lib/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/approval-buddy/agent/lib/) | Protect routing, output contracts, policy, and GitHub behavior. |
-
-There are no authored skills, MCP connections, schedules, reminders, hooks,
-sandbox seeds, or tool approvals.
-
-## Prepare credentials
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential.
-- GitHub access to read PRs, post reviews, create commit statuses, and
-  post the self-approval visibility comment.
-
-Optional GIF selection uses:
-
-- `GIPHY_API_KEY` or `APPROVAL_BUDDY_GIPHY_API_KEY`,
-- `APPROVAL_BUDDY_STAMP_GIF`, or
-- severity-specific `APPROVAL_BUDDY_STAMP_GIF_<LEVEL>` variables.
-
-If you enable Giphy in a hosted copy, declare its secret and
-`api.giphy.com` egress.
-
-## Validate without approving a PR
-
-```bash
-agent-sdk validate --dir examples/approval-buddy
-agent-sdk info --dir examples/approval-buddy --json
-```
-
-List the deterministic roster:
-
-```bash
-agent-sdk call list_buddies \
-  --dir examples/approval-buddy \
-  --input '{}'
-```
-
-Set a known merged PR, then run the read-only precheck:
-
-```bash
-MERGED_PR_URL=https://github.com/your-org/your-repo/pull/123
-agent-sdk call prepare_review \
-  --dir examples/approval-buddy \
-  --input "{\"prUrl\":\"$MERGED_PR_URL\"}"
-```
-
-The result should decline because the PR is no longer open. `prepare_review`
-never posts an approval.
-
-> [!CAUTION]
-> Don't use `agent-sdk call approve_pr` as a smoke test. The tool has no
-> `needsApproval` gate and posts a real GitHub review when the PR qualifies.
-
-## See why preparation is separate
-
-`prepare_review` is read-only. It checks policy before fetching a large diff,
-so declined requests don't spend review-agent work.
-
-Direct calls return the evidence file map because their scratch workspace is
-deleted after the call. In-session calls write the tree to
-`ctx.workspaceDir`, where both subagents can read it.
-
-`approve_pr` repeats the live check instead of trusting preparation. A PR can
-close, merge, become a draft, or change author-related context between the two
-steps. Revalidation keeps the final write bound to current state.
-
-This is a reusable two-tool pattern:
-
-- a read-only tool prepares and explains the decision,
-- a mutating tool repeats policy at the side-effect boundary.
-
-## Fan out two review contracts
-
-The two discovered subagents have different contracts:
-
-- The security reviewer reports bugs, breaking changes, and security findings
-  with `High`, `Medium`, or `Low` tags.
-- The code-quality reviewer reports maintainability and structure concerns
-  with `Blocker`, `Major`, or `Minor` tags.
-
-The parent calls both through the harness `task` tool. They inherit the root
-agent's execution surface and read the same `pr/` workspace. The prompt asks
-the parent not to rewrite either reply. The review body trims the combined
-text and caps it at 16,000 characters.
-
-Findings are informational. A high-severity finding doesn't veto the stamp.
-That policy is explicit in the root instructions and approval code.
-
-## Trace GitHub channel behavior
-
-The channel uses `githubChannel` with:
-
-- a configured repository allowlist on the account-linked GitHub transport,
-- a second optional `APPROVAL_BUDDY_REPOS` wake filter,
-- `deliverReplies: false`,
-- progress reactions disabled, and
-- event handlers for turn start, `approve_pr` results, and failed turns.
-
-The source requests `contents-write`, even though the documented workflow
-posts reviews, statuses, and comments. When adapting the example, start with
-`pr-write` and opt up only if a tool must push code.
-
-Every terminal status is green by design. Declines and crashed turns are
-informational, not merge-blocking. This is a product decision in the example,
-not an Agent SDK default.
-
-A successful turn that never calls `approve_pr` leaves the pending status in
-place. The channel clears it on `approve_pr` results and `turn.failed`, but
-has no `turn.completed` fallback.
-
-`github replay` reaches the same channel and can post a real approval, status,
-or comment. Use replay only against a repository and PR created for this
-test.
-
-## Use Slack for explicit requests
-
-Start the dev server:
-
-```bash
-agent-sdk dev examples/approval-buddy
-```
-
-Then ask through the signed-in account-linked Slack connection:
-
-> Would this PR qualify for a stamp?
-
-The instructions route qualification questions to `prepare_review` only. A
-stamp request runs the complete flow and may approve the PR.
-
-This channel uses the account-linked transport instead of a dedicated Socket
-Mode app.
-
-## See how durable storage fits
-
-`defineStorage` replaces the default local session store with a shared,
-durable key-value adapter. Approval Buddy chooses:
-
-- a 15-second write debounce,
-- startup restoration for up to 200 sessions, and
-- a 14-day restore window.
-
-That policy fits long-lived Slack threads and a small webhook fleet. The
-security reviewer uses the same adapter with lazy restore, which fits its
-shorter sessions.
-
-## Run the regression suite
-
-List the four eval cases:
-
-```bash
-agent-sdk eval --dir examples/approval-buddy --list
-```
-
-The suite covers:
-
-- buddy-list routing,
-- declining a merged PR,
-- using only `prepare_review` for a qualification question, and
-- the combined findings headings and severity format over seeded evidence.
-
-Run the safe qualification case:
-
-```bash
-agent-sdk eval \
-  --dir examples/approval-buddy \
-  qualify/merged-pr-question \
-  --json
-```
-
-The qualification case reads a live merged PR. The seeded format case shown
-by `--list` uses a planted auth-bypass diff
-and checks for a `task` call, both headings, and severity tags. It doesn't
-prove both named subagents ran or whether their output reached `approve_pr`.
-Unit tests under `agent/lib/` cover policy, self-approval handling, evidence
-limits, status mapping, GIF selection, and severity parsing.
-
-## Reuse the policy boundary
-
-Keep these properties when you replace the buddy policy:
-
-1. Put authorization in typed code.
-2. Fetch the source of truth inside both prepare and mutate steps.
-3. Give the model evidence only after the request qualifies.
-4. Treat specialist findings as data, not authority.
-5. Keep the core domain mutation in one named tool. Treat channel status and
-   visibility writes as separate, audited effects.
-6. Add a human approval gate if your policy still needs operator consent.
-7. Test read-only routing separately from mutation.
-
-## Where to go next
-
-- [GitHub](/docs/guides/github.md)
-- [Tools](/docs/reference/tools.md)
-- [Subagents](/docs/reference/subagents.md)
-- [Storage](/docs/storage.md)
-- [Slack](/docs/guides/slack.md)
-- [Evals](/docs/evals.md)
-
----
-
-Source: /docs/example-agents/benny.md
-
-# Route Slack work through repository playbooks
-
-This agent is a Slack teammate for a product team. Mentions and direct
-messages reach it through an account-linked transport. New top-level posts in
-an allowlisted issue channel reach it through a dedicated Slack app, even
-without a mention. The agent then selects a repository playbook for triage,
-reproduction, fixes, reviews, on-call work, or design critique.
-
-Use this example when Slack is the intake surface and your durable procedures
-already live as repository skills.
-
-[Browse the current playbook-router source.](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/benny/)
-
-## Combine two Slack transports with repo skills
-
-The playbook router uniquely combines three decisions:
-
-- Two Slack transports serve different engagement modes.
-- `local.cwd` keeps session workspaces inside the monorepo.
-- Instructions route work to inherited repository playbooks
-  instead of authored `agent/skills/`.
-
-The result is a thin agent project over a mature procedure library.
-
-## Follow an issue report
-
-1. A teammate creates a top-level post in the allowlisted issue channel.
-2. The dedicated Socket Mode channel accepts the allowlisted channel.
-3. A 15-second debounce lets edits settle. Deleting the post during that
-   window cancels the dispatch.
-4. The Agent SDK creates a thread-scoped session and sends the report to the
-   playbook router.
-5. The instructions select the matching triage playbook.
-6. The harness finds the repository root, opens the inherited playbook, and
-   follows its procedure.
-7. The agent posts only in the source thread and reports the evidence it
-   gathered.
-
-Mentions and direct messages follow the same agent instructions. They don't
-need the watched-channel path.
-
-## Map the playbook router files
-
-| File | Purpose |
-| --- | --- |
-| [`agent/agent.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/benny/agent/agent.ts) | Names the agent, selects its model, and points the harness at a project-local cwd so inherited playbooks load. |
-| [`agent/instructions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/benny/agent/instructions.md) | Defines engagement rules, evidence policy, and the playbook routing map. |
-| [`agent/channels/slack.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/benny/agent/channels/slack.ts) | Handles account-linked mentions and direct messages. |
-| [`agent/channels/slack-app.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/benny/agent/channels/slack-app.ts) | Runs the dedicated app and watches one allowlisted channel. |
-| [`agent/storage.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/benny/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
-| [`evals/evals.config.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/benny/evals/evals.config.ts) | Caps eval run concurrency. |
-| [`evals/smoke.eval.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/benny/evals/smoke.eval.ts) | Checks the agent identity and expected triage route. |
-
-The playbook router authors no tools, MCP connections, subagents, schedules, hooks, A/B
-experiments, or sandbox seeds.
-
-## See why `local.cwd` matters
-
-The Agent SDK normally keeps an ephemeral `run` or `eval` workspace outside a
-large monorepo. This prevents ancestor instruction and repository-rule files
-from leaking into an unrelated agent.
-
-The playbook router needs the opposite. Its procedures live at the repository
-root, so `agent.ts` points `local.cwd` at a harness directory under the
-project. Each harness workspace is a child of that directory. Walking up
-reaches the host repository and its inherited playbook directory.
-
-Those playbooks are inherited context. `agent-sdk info` reports zero authored
-skills for the agent. Copying this project into another repository removes
-its main procedures unless you copy or replace the skill library too.
-
-## Connect both Slack paths
-
-The account-linked path needs an agent-runtime login and a connected Slack
-account:
-
-```bash
-agent-sdk login
-agent-sdk whoami
-```
-
-It routes explicit mentions without a dedicated Slack token on the host.
-
-For the watched-channel path, configure a dedicated Socket Mode app with:
-
-- subscribe to `message.channels` and `message.groups`,
-- have an App-Level Token with `connections:write`, and
-- be a member of the watched channel.
-
-Run `agent-sdk slack create --dir examples/benny --channel-posts` for a
-dedicated Socket Mode app, then `agent-sdk slack doctor`.
-
-Missing dedicated-app tokens leave that channel idle. They don't stop the
-account-linked channel.
-
-## Validate and start the server
-
-```bash
-agent-sdk validate --dir examples/benny
-agent-sdk info --dir examples/benny --json
-agent-sdk dev examples/benny
-```
-
-The info output should show two Slack channels and no authored skill. That
-combination confirms the example is using inherited playbooks.
-
-## Exercise each engagement mode
-
-Test the explicit account-linked path by asking:
-
-> Which playbook would you use to triage a product UI bug?
-
-Test the dedicated app:
-
-1. Create a top-level post in the allowlisted issue channel.
-2. Don't mention the bot.
-3. Wait for the debounce window.
-4. Confirm the agent replies in the post's thread.
-
-Thread replies don't trigger the proactive watch. Mentions still use Slack's
-normal mention path. Bot-authored posts are ignored to prevent loops.
-
-The channel uses the default handler after filtering. It doesn't apply a
-second code-level classifier, so every accepted top-level post spends a model
-turn and reaches the prompt.
-
-## Inspect thread continuity
-
-The Agent SDK keys Slack sessions by channel and thread timestamp. A follow-up in
-the same thread resumes the conversation and workspace. A new top-level issue
-gets a new session.
-
-This lets a playbook gather evidence over several turns without mixing two
-reports. The playground shows both the account-linked and dedicated-app
-sessions while the dev server runs.
-
-## Run the smoke eval
-
-```bash
-agent-sdk eval --dir examples/benny --list
-agent-sdk eval --dir examples/benny smoke --json
-```
-
-The case asks for the agent identity and the playbook used for issue triage.
-It checks the configured identity and route label.
-
-This is a lexical smoke test. It doesn't prove Slack delivery, skill
-selection, skill loading, procedure execution, or thread-only behavior. Add
-fixture-backed evals around the playbooks when you reuse this design.
-
-## Build a playbook-routed teammate
-
-Use this structure when your organization already has tested skills:
-
-1. Put the playbooks under a stable repository path.
-2. Set `local.cwd` so harness workspaces can inherit that path.
-3. Write a short routing table in `instructions.md`.
-4. Use account-linked Slack for explicit requests.
-5. Add a dedicated app only for allowlisted proactive intake.
-6. Keep the channel allowlist narrow and debounce edited posts.
-7. Add an eval for every important request-to-playbook route.
-
-If the procedures should ship with the agent, put them under
-`agent/skills/` instead. Authored skills appear in the manifest and travel
-with the project.
-
-## Where to go next
-
-- [Slack](/docs/guides/slack.md)
-- [Agent config](/docs/reference/agent-config.md)
-- [Skills](/docs/reference/skills.md)
-- [Sessions and streaming](/docs/reference/sessions.md)
-- [Evals](/docs/evals.md)
-
----
-
-Source: /docs/example-agents/bugbot.md
-
-# Review prepared pull-request evidence
-
-This GitHub-read-only reviewer uses host code to fetch the PR
-with `gh` and `git`, builds a trimmed `pr/` evidence tree, then hands that tree
-to the model. The model reads the diff, loads a review skill, and returns at
-most three high-confidence findings.
-
-Use this example when the host should control evidence collection and the
-model shouldn't browse or mutate the source repository.
-
-[Browse the current reviewer source.](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/bugbot/)
-
-## Separate evidence preparation from review
-
-The reviewer separates preparation from judgment:
-
-- Host code owns GitHub and Git access.
-- A server tool turns untrusted PR input into bounded workspace files.
-- A custom channel seeds those files before the model starts.
-- An on-demand skill defines the review procedure and output contract.
-- The model returns chat text. No path posts a GitHub review.
-
-This architecture gives the model a purpose-built evidence package instead of
-a checkout.
-
-## Follow a review
-
-The custom HTTP path runs this sequence:
-
-1. `POST /v1/channels/review/` receives a PR reference.
-2. The handler calls `prepare_pr` without a model turn.
-3. Host code reads PR metadata and the unified diff.
-4. It reuses a matching checkout, force-fetching the PR ref there when the
-   commit is missing. Without a matching checkout, it uses a temporary bare
-   cache.
-5. It creates `pr/MANIFEST.md`, `pr/meta.json`, `pr/diff.patch`, and selected
-   small files and rules.
-6. `send({ workspaceFiles })` creates the model session with that evidence.
-7. The model reads the manifest and diff, then loads `pr-review`.
-8. The channel returns session and playground URLs while the review streams.
-
-If a normal chat starts without evidence, the model can call `prepare_pr`
-mid-turn. That form writes the same files into the active session workspace.
-
-## Map the evidence-review files
-
-| File | Purpose |
-| --- | --- |
-| [`agent/agent.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/bugbot/agent/agent.ts) | Selects the local runtime and model. |
-| [`agent/instructions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/bugbot/agent/instructions.md) | Requires diff-first review and confines model work to `pr/`. |
-| [`agent/tools/prepare_pr.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/bugbot/agent/tools/prepare_pr.ts) | Exposes host preparation as a typed server tool. |
-| [`agent/lib/prepare-pr.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/bugbot/agent/lib/prepare-pr.ts) | Parses PR references, runs `gh` and `git`, and builds the evidence map. |
-| [`agent/channels/review.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/bugbot/agent/channels/review.ts) | Provides the loopback-only prepare-and-send HTTP route. |
-| [`agent/channels/slack.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/bugbot/agent/channels/slack.ts) | Extracts PR references and prepares evidence for mentions and direct messages. |
-| [`agent/skills/pr-review.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/bugbot/agent/skills/pr-review.md) | Sets finding limits, severities, and the machine-readable review format. |
-| [`agent/lib/log.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/bugbot/agent/lib/log.ts) | Writes timing logs for the host tools to stderr. |
-| [`agent/storage.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/bugbot/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
-| [`evals/evals.config.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/bugbot/evals/evals.config.ts) | Caps eval run concurrency. |
-| [`evals/review/smoke.eval.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/bugbot/evals/review/smoke.eval.ts) | Seeds fake evidence and checks the review path without GitHub. |
-
-There is no authored GitHub channel, MCP connection, subagent, schedule,
-hook, A/B experiment, approval, or custom storage.
-
-## Prepare the host
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential for model turns and account-linked Slack.
-- `gh` and `git` on `PATH`.
-- `gh` access to the target PR.
-- Network access to GitHub and a writable temporary directory.
-
-The preparer can prefer a configured local checkout. Its `origin` must match
-the target repository. Otherwise the reviewer uses its bare cache. It never
-checks out the PR into the serve host's working tree.
-
-## Validate the surface
-
-```bash
-agent-sdk validate --dir examples/bugbot
-agent-sdk info --dir examples/bugbot --json
-```
-
-The manifest should show one server tool, one skill, and two authored
-channels.
-
-## Inspect evidence without a model turn
-
-Call the preparation tool directly:
-
-```bash
-agent-sdk call prepare_pr \
-  --dir examples/bugbot \
-  --input '{"pr":"https://github.com/owner/repo/pull/123"}'
-```
-
-Direct tool calls use a scratch workspace removed after the call.
-`prepare_pr` detects this path and returns the complete file map in its
-result. In a model session, it writes the files and returns a smaller summary.
-
-The evidence builder applies explicit limits:
-
-| Evidence | Limit |
-| --- | --- |
-| Post-change file | 12,000 characters |
-| One rule file | 8,000 characters |
-| Combined rules | 12,000 characters |
-| PR body in metadata | 2,000 characters |
-
-Large files remain visible in `diff.patch`. The manifest records which full
-files or rules were omitted.
-
-The per-file limits aren't an aggregate context cap. Every changed file below
-12,000 characters can be included. The diff command has a 12 MiB output
-buffer; a larger diff fails preparation instead of being truncated.
-
-## Run the HTTP review path
-
-Start the server:
-
-```bash
-agent-sdk dev examples/bugbot
-```
-
-From another terminal:
-
-```bash
-curl -s -X POST \
-  http://127.0.0.1:3000/bugbot/v1/channels/review/ \
-  -H 'content-type: application/json' \
-  -d '{"pr":"https://github.com/owner/repo/pull/123"}'
-```
-
-The route returns `status: "started"`, a continuation token, and session and
-playground URLs. Open the session URL to watch the model read the evidence and
-produce findings.
-
-The channel declares `localDevStrict()`. Direct loopback callers can use it.
-Proxy-forwarding headers and non-loopback hosts are rejected.
-
-Send a follow-up by passing the returned key:
-
-```bash
-curl -s -X POST \
-  http://127.0.0.1:3000/bugbot/v1/channels/review/ \
-  -H 'content-type: application/json' \
-  -d '{"pr":"owner/repo#123","key":"<continuation-token>"}'
-```
-
-The follow-up resumes the session without fetching a new evidence tree.
-
-## Run the Slack path
-
-The account-linked Slack channel handles review-bot mentions and direct
-messages:
-
-> Review https://github.com/owner/repo/pull/123
-
-Slack handlers don't receive the channel `callTool` helper. This example calls
-the shared `preparePrReview` host function, then returns `workspaceFiles` in
-the Slack message preparation result. The model sees the same evidence and
-prompt as the HTTP path.
-
-If a message contains no PR reference, the handler asks for one. Thread
-follow-ups keep the same session.
-
-## See how the skill constrains review
-
-`pr-review.md` tells the model to:
-
-- read the manifest and unified diff first,
-- open at most one supporting file or rules file when a hunk is ambiguous,
-- avoid shell, network, `gh`, and `git`,
-- report no more than three findings,
-- keep each description under 120 words, and
-- emit the machine-readable review contract.
-
-The root instructions set the evidence boundary. The skill holds the reusable
-review procedure. Keeping those roles separate lets another agent reuse the
-same skill with different intake channels.
-
-## Run the fixture-backed eval
-
-```bash
-agent-sdk eval --dir examples/bugbot --list
-agent-sdk eval --dir examples/bugbot review/smoke --json
-```
-
-The eval constructs a `PreparedPrReview`, seeds its file map through
-`workspaceFiles`, and checks for at least one read call with no shell call. It
-doesn't assert which evidence file was read or whether the skill loaded. It
-accepts either a formatted review or a clean result.
-
-This case tests review behavior without GitHub credentials or network data.
-Add fixtures with reachable bugs when you need stricter location and severity
-checks.
-
-## Keep the side-effect boundary clear
-
-The reviewer makes no remote GitHub writes. It doesn't author a GitHub channel and
-doesn't call a review API. Host preparation does write session evidence and
-force-update `refs/pull/<N>/head` in either its bare cache or a matching local
-checkout when the commit is missing. Every result ends with a note saying no
-GitHub review was posted.
-
-If you add publishing later, keep it in a separate tool. This preserves a
-read-only preparation and review path safe to run in evals.
-
-## Reuse the evidence handoff
-
-Use host-prepared workspaces when:
-
-- external APIs should stay off the model's tool surface,
-- context needs hard size limits,
-- the model should inspect a snapshot instead of a live checkout, or
-- several channels need the same preparation.
-
-Return `workspaceFiles` from direct host preparation, write into
-`ctx.workspaceDir` for mid-turn recovery, and encode the reading order in both
-the manifest and a skill.
-
-## Where to go next
-
-- [Webhooks and custom channels](/docs/guides/webhooks.md)
-- [Tools](/docs/reference/tools.md)
-- [Skills](/docs/reference/skills.md)
-- [Slack](/docs/guides/slack.md)
-- [Evals](/docs/evals.md)
-
----
-
-Source: /docs/example-agents/codebase-wiki.md
-
-# Build a feature wiki from merged pull requests
-
-Codebase wiki keeps a living, feature-organized wiki of a repository.
-The GitHub channel acknowledges every closed pull request instantly,
-fetches a compact digest on the host, and spends a model turn only on
-merged PRs. The turn maps the change onto feature pages; a daily
-schedule writes a digest of what changed and rebuilds the index. Chat
-sessions answer codebase questions from the wiki with page citations.
-
-Use this project when documentation should accumulate from merges
-instead of being regenerated from scratch. Use
-[Knowledge base](/docs/example-agents/knowledge-base.md) when people should curate
-organizational context through conversation.
-
-[Browse the codebase wiki source.](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/codebase-wiki/)
-
-## Treat PRs as evidence and features as pages
-
-The wiki refuses to become a merge log:
-
-- The page tree is rigid: `index`, `features/<slug>`, and
-  `digests/<yyyy-mm-dd>`. The store rejects anything else, so the wiki
-  can't sprawl.
-- The `feature-mapping` skill requires a `wiki_search` before every
-  write. A PR updates the page that owns its feature; a new page needs
-  a genuinely new feature; chores change nothing.
-- Every touched page gets a dated changelog entry citing the PR
-  number, so each fact traces back to a merge.
-
-The wiki itself is markdown on the serve host, in a wiki directory by
-default with a `CODEBASE_WIKI_DIR` override. Sessions are disposable;
-the wiki is the durable state.
-
-## Follow a merged PR
-
-1. GitHub delivers `pull_request` with action `closed`. The channel
-   returns a task acknowledgement immediately.
-2. The task fetches the digest with the host `gh` CLI: title, body,
-   labels, changed files, and a bounded diff excerpt. No checkout.
-3. The webhook payload can't say whether the PR merged, so the host
-   checks `mergedAt` and skips abandoned PRs without a model turn.
-4. For merged PRs, the task starts the turn with `pr/DIGEST.md` seeded
-   through `workspaceFiles` and a `pr:<owner/repo#N>` continuation
-   token, so redeliveries resume instead of double-ingesting.
-5. The model follows `feature-mapping`: search, update or create
-   feature pages, add changelog entries, and refresh `index` when pages
-   were added.
-
-In chat, "ingest PR #123" runs the same flow through the `ingest_pr`
-tool, which writes the digest into the active session workspace.
-
-## Map the wiki files
-
-| File | Purpose |
-| --- | --- |
-| [`agent/agent.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codebase-wiki/agent/agent.ts) | Selects the local runtime and model. |
-| [`agent/instructions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codebase-wiki/agent/instructions.md) | Splits the job into merge ingestion and wiki-cited Q&A. |
-| [`agent/lib/wiki-store.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codebase-wiki/agent/lib/wiki-store.ts) | Enforces the rigid page tree and owns reads, writes, and search. |
-| [`agent/lib/pr-digest.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codebase-wiki/agent/lib/pr-digest.ts) | Fetches PR metadata and diff, and formats `pr/DIGEST.md`. |
-| [`agent/tools/ingest_pr.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codebase-wiki/agent/tools/ingest_pr.ts) | Exposes host digest preparation for chat-driven backfills. |
-| [`agent/tools/wiki_read.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codebase-wiki/agent/tools/wiki_read.ts), [`wiki_search.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codebase-wiki/agent/tools/wiki_search.ts), [`wiki_write.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codebase-wiki/agent/tools/wiki_write.ts) | Read, search, and rewrite wiki pages. |
-| [`agent/skills/feature-mapping.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codebase-wiki/agent/skills/feature-mapping.md) | Maps changes onto features and fixes the page and changelog shape. |
-| [`agent/schedules/daily-digest.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codebase-wiki/agent/schedules/daily-digest.md) | Writes `digests/<date>`, rebuilds the index, and flags stale pages. |
-| [`agent/channels/github.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codebase-wiki/agent/channels/github.ts) | Acknowledges closed PRs and starts merged-only ingest turns. |
-| [`agent/storage.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codebase-wiki/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
-| [`evals/evals.config.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codebase-wiki/evals/evals.config.ts) | Caps eval run concurrency. |
-| [`evals/ingest.eval.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codebase-wiki/evals/ingest.eval.ts) | Gates ingest decisions against the wiki filesystem. |
-
-There is no MCP connection, subagent, hook, or A/B experiment.
-
-## Prepare credentials and services
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential for model turns.
-- `gh` on `PATH` with read access to the PRs you ingest.
-
-The channel verifies webhook signatures when `GITHUB_WEBHOOK_SECRET` is
-set and narrows repositories with
-`CODEBASE_WIKI_REPOS=owner/repo,owner/other`. The agent never writes to
-GitHub. Its only side effects are wiki files on the serve host.
-
-## Validate the surface
-
-```bash
-agent-sdk validate --dir examples/codebase-wiki
-agent-sdk info --dir examples/codebase-wiki --json
-```
-
-The manifest should report four server tools, one skill, one schedule,
-and the authored GitHub channel.
-
-## Ingest without webhook plumbing
-
-Replay a real merged PR as a closed delivery:
-
-```bash
-agent-sdk dev examples/codebase-wiki
-
-agent-sdk github replay https://github.com/owner/repo/pull/123 \
-  --dir examples/codebase-wiki --action closed
-```
-
-The reply is a 202 acknowledgement; the ingest continues in the task.
-Watch the session in the playground, then open the wiki directory on
-the serve host. Feature pages land under `features/`.
-
-Each ingested feature page carries an overview, a "How it works"
-section, and a changelog line citing the PR. Deterministic digest
-preparation works without a model turn:
-
-```bash
-agent-sdk call ingest_pr \
-  --dir examples/codebase-wiki \
-  --input '{"pr":"https://github.com/owner/repo/pull/123"}'
-```
-
-A PR closed without merging returns `merged: false` and a note telling
-the model to change nothing.
-
-## Run the daily digest
-
-The schedule fires at 07:00 UTC. Under `agent-sdk dev`, trigger it by
-hand:
-
-```bash
-curl -s -X POST http://127.0.0.1:3000/codebase-wiki/v1/dev/schedules/daily-digest
-```
-
-The turn reads every feature changelog, writes
-`digests/<today>` grouped by feature with PR citations, rebuilds
-`index`, and reports one line per page it wrote. Entries dated today
-always count; a digest only claims a quiet day when no entry qualifies.
-
-## Run the evals
-
-```bash
-agent-sdk eval --dir examples/codebase-wiki --list
-agent-sdk eval --dir examples/codebase-wiki ingest/update-existing
-```
-
-The cases seed a temp wiki through `CODEBASE_WIKI_DIR` and build
-digests with the same formatter the channel uses, so they run without
-GitHub or network access. The gates check the filesystem, not prose:
-a new feature page lands on a new slug, a related PR updates the
-existing page instead of duplicating it, an unmerged PR changes
-nothing, and the daily pass writes a digest naming both seeded
-features.
-
-## Reuse the merge-ingestion pattern
-
-Copy this shape when events should accumulate into curated state:
-
-- Acknowledge webhooks with a task and decide host-side whether a
-  model turn is worth spending.
-- Seed evidence through `workspaceFiles` so the model never fetches.
-- Constrain the durable store's shape in code and its content in a
-  skill.
-- Add a consolidation schedule so incremental writes stay coherent.
-
-## Where to go next
-
-- [GitHub webhooks](/docs/guides/github.md)
-- [Schedules](/docs/reference/schedules.md)
-- [Tools](/docs/reference/tools.md)
-- [Evals](/docs/evals.md)
-
----
-
-Source: /docs/example-agents/codeowners-review.md
-
-# Route PR reviews by code ownership
-
-Codeowners review gives each part of a codebase its own review. A
-CODEOWNERS-style table maps changed paths to review areas; each area
-has a markdown playbook with the team's rules for that domain; and one
-`area-reviewer` subagent runs per routed area, in parallel. A billing
-change gets the billing review, a migration gets the migration review,
-and an author's personal style rides along as advisory notes. The lead
-aggregates: approve only when every area approves.
-
-Use this project when review quality depends on domain-specific values
-instead of one generic checklist.
-
-[Browse the codeowners review source.](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/codeowners-review/)
-
-## Keep routing in code and judgment in playbooks
-
-The pipeline separates three concerns:
-
-- `reviews/REVIEWERS` routes. Host code matches every changed path
-  against the table; every matching rule applies, and unmatched paths
-  fall back to the `general` playbook. Routing is glob code with unit
-  tests, not model judgment.
-- `reviews/<area>.md` judges. Each playbook is a severity-ordered rule
-  list the team owns: billing mandates integer cents and idempotent
-  webhooks, migrations forbid destructive DDL beside code changes,
-  background jobs demand idempotency and dead-letter paths.
-- Subagents review. The lead reads nothing but the manifest and
-  routes; each `area-reviewer` reads one playbook plus its files' diff
-  hunks and returns a mechanical verdict: request changes on any High
-  finding or two Mediums.
-
-Personal styles extend the same mechanism. `reviews/people/<login>.md`
-attaches automatically, as advisory notes, whenever that person authors
-the PR. Adding an area or a style is a markdown file plus at most one
-routing line.
-
-## Follow a review
-
-1. A PR arrives: a GitHub `pull_request` event, a chat message, or a
-   bundled fixture reference.
-2. `prepare_review` fetches metadata and the diff with the host `gh`
-   CLI, routes every changed file, and writes the `pr/` evidence tree:
-   `MANIFEST.md`, `ROUTES.md`, `diff.patch`, and a copy of each matched
-   playbook.
-3. The lead follows the `review-process` skill and issues one
-   `area-reviewer` delegation per routed area, plus one per personal
-   style, all in one step so they run in parallel.
-4. Each reviewer reads its playbook, reviews only its files, and
-   returns a verdict line with at most three findings.
-5. The lead aggregates per-area sections and the overall verdict:
-   APPROVE only when every non-advisory area approved.
-
-Nothing posts to GitHub. Verdicts live in the session; the
-[Approval Buddy guide](/docs/example-agents/approval-buddy.md) shows how to wire a real
-APPROVE and commit statuses on top of the same shape.
-
-## Map the review files
-
-| File | Purpose |
-| --- | --- |
-| [`reviews/REVIEWERS`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codeowners-review/reviews/REVIEWERS) | Routes path patterns to review areas. |
-| [`reviews/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/codeowners-review/reviews/) | Holds the area playbooks and `people/<login>.md` styles. |
-| [`agent/lib/routing.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codeowners-review/agent/lib/routing.ts) | Parses the table, matches globs, and unions areas per file. |
-| [`agent/lib/prepare-review.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codeowners-review/agent/lib/prepare-review.ts) | Fetches PRs or fixtures and builds the evidence tree. |
-| [`agent/tools/prepare_review.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codeowners-review/agent/tools/prepare_review.ts) | Exposes host preparation as a typed server tool. |
-| [`agent/tools/list_review_areas.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codeowners-review/agent/tools/list_review_areas.ts) | Answers routing questions deterministically. |
-| [`agent/skills/review-process.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codeowners-review/agent/skills/review-process.md) | Fixes the fan-out procedure and the verdict rule. |
-| [`agent/subagents/area-reviewer/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/codeowners-review/agent/subagents/area-reviewer/) | Defines the one-area, one-playbook reviewer contract. |
-| [`agent/channels/github.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codeowners-review/agent/channels/github.ts) | Reviews opened, reopened, synchronized, and undrafted PRs. |
-| [`fixtures/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/codeowners-review/fixtures/) | Ships two reviewable PRs with known planted findings. |
-| [`agent/storage.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codeowners-review/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
-| [`evals/evals.config.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codeowners-review/evals/evals.config.ts) | Caps eval run concurrency. |
-| [`evals/review.eval.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/codeowners-review/evals/review.eval.ts) | Gates routing, fan-out, planted bugs, and verdicts. |
-
-There is no MCP connection, schedule, hook, A/B experiment, or custom
-storage.
-
-## Prepare credentials and services
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential for model turns.
-- `gh` on `PATH` with read access to real PRs you review. The bundled
-  fixtures need no network at all.
-
-The channel verifies webhook signatures when `GITHUB_WEBHOOK_SECRET` is
-set and narrows repositories with
-`CODEOWNERS_REVIEW_REPOS=owner/repo,owner/other`. Pushes re-review in
-the same session through the `pr:<label>` continuation token.
-
-## Validate the surface
-
-```bash
-agent-sdk validate --dir examples/codeowners-review
-agent-sdk info --dir examples/codeowners-review --json
-```
-
-The manifest should report two server tools, one skill, one subagent,
-and the authored GitHub channel.
-
-## Inspect routing without a model turn
-
-```bash
-agent-sdk call list_review_areas --dir examples/codeowners-review --input '{}'
-
-agent-sdk call prepare_review \
-  --dir examples/codeowners-review \
-  --input '{"pr":"fixture:multi-area"}'
-```
-
-The fixture routes to `billing`, `database-migrations`, and `frontend`,
-attaches `people/alice` because alice authored it, and returns the full
-evidence map. Point the same tool at a real PR URL and the routing runs
-against the live file list. The example table maps a hypothetical
-`src/` layout, so most real repositories route to `general` until you
-adapt `reviews/REVIEWERS`.
-
-## Review the planted fixture
-
-```bash
-agent-sdk dev examples/codeowners-review
-```
-
-In the playground:
-
-> Review fixture:multi-area
-
-The fixture plants one violation per area: float dollar math in
-`src/billing/invoice.ts`, a `DROP COLUMN` plus a non-concurrent index
-in the migration, and a clickable `div` without loading states in the
-UI. The trace shows `prepare_review`, the evidence reads, four parallel
-`area-reviewer` cards, and an aggregated CHANGES REQUESTED verdict with
-each planted bug filed under its own area. The second fixture,
-`fixture:jobs-clean`, routes to `background-jobs` alone and ends in
-APPROVE.
-
-Review a real PR the same way:
-
-> Review https://github.com/owner/repo/pull/123
-
-Or replay one as a webhook delivery:
-
-```bash
-agent-sdk github replay https://github.com/owner/repo/pull/123 \
-  --dir examples/codeowners-review --action opened
-```
-
-## See how the verdict stays mechanical
-
-The reviewer contract computes verdicts from findings instead of
-letting the model pick a mood: findings first, then
-`request-changes` if any High exists or two Mediums do, otherwise
-`approve`. Pre-existing issues visible in context are scoped out, at
-most one advisory Low. The lead applies one rule on top: the PR is
-APPROVE only when every non-advisory area approved.
-
-## Run the evals
-
-```bash
-agent-sdk eval --dir examples/codeowners-review --list
-agent-sdk eval --dir examples/codeowners-review review/multi-area
-```
-
-`review/multi-area` gates the whole pipeline: `prepare_review` runs, at
-least three subagent delegations happen, the reply carries every area
-section plus alice's advisory notes, the planted billing and migration
-bugs surface, and the verdict requests changes. `review/clean-approve`
-proves the approval path on the clean fixture, and
-`review/routing-question` gates that routing answers come from
-`list_review_areas`.
-
-## Reuse the ownership-routing pattern
-
-Copy this shape when different code deserves different judgment:
-
-- Route with data and code, not prompt instructions. Tables and globs
-  are testable.
-- Write one playbook per domain and keep each reviewer blind to the
-  others.
-- Make verdicts mechanical so aggregation is arithmetic, not
-  negotiation.
-- Ship fixtures with planted findings so the review quality itself is
-  testable offline.
-
-## Where to go next
-
-- [Approval Buddy](/docs/example-agents/approval-buddy.md) for posting real approvals
-- [Subagents](/docs/reference/subagents.md)
-- [GitHub webhooks](/docs/guides/github.md)
-- [Evals](/docs/evals.md)
-
----
-
-Source: /docs/example-agents/concierge.md
-
-# Compose agents with a concierge
-
-Concierge answers general questions itself and sends every weather question
-to the weather agent. The connection is one file. The Agent SDK turns the target
-agent's MCP endpoint into tools the concierge can call.
-
-Use this example when two agents are useful on their own and one should
-delegate a narrow class of work to the other.
-
-[Browse the Concierge source.](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/concierge/)
-
-## Delegate through a peer MCP connection
-
-Concierge has no domain tool of its own. Its capability comes from a peer MCP
-connection:
-
-```ts
-export default defineConnection({
-  agent: "weather-agent",
-  description:
-    "The weather-agent peer: delegate weather questions with ask; it runs its own tools (live Open-Meteo data) in its own context.",
-});
-```
-
-The filename
-[`weather.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/concierge/agent/mcp-connections/weather.ts)
-makes the MCP server name `weather`. The `agent` field points to the sibling
-project's mount slug.
-
-This differs from a subagent. A peer keeps its own:
-
-- root instructions,
-- tools and MCP connections,
-- durable sessions,
-- playground, and
-- public MCP endpoint.
-
-An SDK subagent inherits the parent's execution surface and only its parent
-can invoke it. See [Agent-to-agent](/docs/guides/agent-to-agent.md) for the full
-comparison.
-
-## Follow a delegated request
-
-1. A user asks Concierge what to pack for Paris.
-2. [`instructions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/concierge/agent/instructions.md)
-   classifies packing advice as weather-related.
-3. The model calls `weather.ask` with the city, timeframe, units, and the
-   complete question.
-4. The Agent SDK creates an MCP-channel session inside `weather-agent`.
-5. Weather agent calls its own Open-Meteo tools and returns a reply.
-6. If the turn exceeds the bounded MCP wait, `ask` returns
-   `status: "running"`. Concierge calls `weather.check` with the returned
-   `sessionId`.
-7. Concierge relays the result and may add one sentence of travel advice.
-
-The weather session appears in the weather agent's playground. It doesn't
-share Concierge's conversation history.
-
-## Map the delegation files
-
-| File | Purpose |
-| --- | --- |
-| [`agent/agent.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/concierge/agent/agent.ts) | Describes the root agent and selects the local runtime. |
-| [`agent/instructions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/concierge/agent/instructions.md) | Draws a strict weather-only delegation boundary. |
-| [`agent/mcp-connections/weather.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/concierge/agent/mcp-connections/weather.ts) | Resolves the peer by its `weather-agent` slug. |
-| [`agent/storage.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/concierge/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
-
-Concierge doesn't author channels, tools, skills, subagents, schedules,
-hooks, A/B experiments, or evals. The built-in HTTP and MCP surfaces still
-exist.
-
-Its own MCP endpoint exposes `ask` and `check`. It doesn't expose
-`call_tool` because Concierge has no server tools. The target weather agent
-does expose `call_tool`, so that tool also appears under Concierge's
-`weather` connection.
-
-## Mount both agents
-
-A peer can only resolve within a multi-agent serve host. Validating Concierge
-alone checks its files, but serving it alone fails because `weather-agent`
-isn't mounted.
-
-From this package, validate both projects:
-
-```bash
-agent-sdk validate --dir examples/concierge
-agent-sdk validate --dir examples/weather-agent
-```
-
-Don't serve the repository's whole `examples/` directory for this proof.
-Several advanced examples subscribe to live GitHub events. Create an ignored
-two-project mount instead. Copy only the authored files needed for this proof,
-leaving Weather's Slack channels out:
-
-```bash
-PAIR_DIR=$(mktemp -d "${TMPDIR:-/tmp}/concierge-weather.XXXXXX")
-mkdir -p "$PAIR_DIR/concierge" "$PAIR_DIR/weather-agent/agent"
-cp -R examples/concierge/agent "$PAIR_DIR/concierge/"
-cp examples/concierge/package.json "$PAIR_DIR/concierge/"
-cp examples/weather-agent/agent/{agent.ts,instructions.md,ab.ts,ab.config.ts} \
-  "$PAIR_DIR/weather-agent/agent/"
-cp -R examples/weather-agent/agent/{tools,skills,mcp-connections,subagents,schedules,hooks,lib} \
-  "$PAIR_DIR/weather-agent/agent/"
-cp -R examples/weather-agent/mcp "$PAIR_DIR/weather-agent/"
-cp examples/weather-agent/package.json "$PAIR_DIR/weather-agent/"
-agent-sdk dev "$PAIR_DIR"
-```
-
-The host resolves the peer after it knows every mount. The local peer URL is
-`http://127.0.0.1:3000/weather-agent/v1/mcp`. You still need an agent-runtime
-credential for both model turns.
-
-## Exercise delegation
-
-Send a weather request to the running Concierge:
-
-```bash
-agent-sdk chat \
-  --url http://127.0.0.1:3000/concierge \
-  --message "What should I pack for Paris tomorrow?"
-```
-
-Open both playgrounds:
-
-- `http://127.0.0.1:3000/concierge/playground`
-- `http://127.0.0.1:3000/weather-agent/playground`
-
-The Concierge transcript shows the MCP call. The weather playground shows a
-separate session on the `mcp` channel with live weather tool calls.
-
-Now send a general request:
-
-```bash
-agent-sdk chat \
-  --url http://127.0.0.1:3000/concierge \
-  --message "Give me three ideas for a quiet weekend."
-```
-
-The instructions tell Concierge to answer without delegating. This contrast is
-the proof loop: weather goes to the peer, unrelated work stays local.
-
-## Preserve peer context
-
-`weather.ask` returns a peer `sessionId`. Passing it back to a later `ask`
-continues the same weather conversation. Concierge's instructions require
-this for follow-ups dependent on an earlier answer.
-
-Use a fresh call when the tasks are independent. Reuse the peer session when
-the second question needs facts or choices from the first.
-
-## Keep delegation bounded
-
-The Agent SDK rejects unknown peer slugs and self-references during startup. It
-doesn't stop a cycle across several valid peers. If agent A delegates all work
-to B and B delegates all work to A, they can recurse.
-
-The prompt provides the guardrail here:
-
-- delegate every weather request,
-- include complete context, and
-- never delegate unrelated work.
-
-Write similarly narrow routing rules for each peer. A tool description helps
-the model choose the connection, but the always-on instructions own the
-policy.
-
-## Use peers from cloud turns
-
-Local turns reach peers over loopback. A cloud VM can't reach the serve
-host's loopback address. Set a public URL when a cloud agent needs the peer:
-
-```bash
-agent-sdk serve --dir "$PAIR_DIR" \
-  --public-url https://agents.example.com \
-  --bearer-token "$AGENT_TOKEN"
-```
-
-The Agent SDK attaches the bearer token to peer calls. Without `--public-url`,
-cloud turns omit peer connections and the server logs a warning.
-
-## Compose your own pair
-
-To compose your own agents:
-
-1. Give each project a stable directory slug.
-2. Add `agent/mcp-connections/<name>.ts` to the caller.
-3. Set `agent` to the target slug.
-4. Describe the exact work the peer owns.
-5. Mount both projects from their parent directory.
-6. Add evals for delegated and non-delegated requests.
-
-Keep the peer independently useful. If the specialist only makes sense inside
-one parent and needs no independent sessions, use a subagent instead.
-
-## Where to go next
-
-- [Agent-to-agent](/docs/guides/agent-to-agent.md)
-- [MCP connections](/docs/reference/connections.md)
-- [Subagents](/docs/reference/subagents.md)
-- [Sessions and streaming](/docs/reference/sessions.md)
-
----
-
-Source: /docs/example-agents/index.md
-
-# Choose the right Agent SDK example
-
-The examples progress from one-channel assistants to durable, event-driven
-workflows. Start with the smallest agent for your use case. Each guide
-explains its request flow, framework features, verification path, and reusable
-design.
-
-The source projects live under
-[`examples/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/). Run the commands below from
-this package. See [Run the CLI](/docs/index.md#run-the-cli) if the
-`agent-sdk` command isn't installed.
-
-## Compare the examples
-
-| Agent | Runtime | Intake | Framework focus | What sets it apart |
-| --- | --- | --- | --- | --- |
-| [Weather agent](/docs/example-agents/weather-agent.md) | Cloud | HTTP and two Slack transports | Tools, stdio MCP, skill, subagent, schedule, hooks, A/B, and evals | It demonstrates the broad cloud-runtime surface in one domain. |
-| [Slack agent](/docs/example-agents/slack-agent.md) | Local | Account-linked Slack | Channel identity, threads, and suggested prompts | It reaches Slack without authored tools. |
-| [Concierge](/docs/example-agents/concierge.md) | Local | Built-in HTTP | Peer MCP and multi-agent serving | It delegates to a separate agent with its own tools, sessions, and context. |
-| [Playbook router](/docs/example-agents/benny.md) | Local with repo context | Two Slack transports | Channel watching, inherited skills, custom cwd, and an eval | An allowlisted Slack channel becomes an intake queue for repo playbooks. |
-| [Alert investigator](/docs/example-agents/oncall.md) | Local | Watched Slack alerts channel | Bot-post channel watching, per-thread debounce, reminder tools, and host Slack calls | Every alert gets a thread-pinned investigation that schedules its own re-checks. |
-| [PR evidence reviewer](/docs/example-agents/bugbot.md) | Local | Custom HTTP and Slack | Host tool, skill, seeded workspaces, and an eval | The model receives a prepared diff-first evidence tree instead of a checkout. |
-| [Approval Buddy](/docs/example-agents/approval-buddy.md) | Local | GitHub and Slack | Policy tools, two subagents, durable storage, and evals | Code decides whether a PR may be approved. Reviews stay informational. |
-| [Security Reviewer](/docs/example-agents/security-reviewer.md) | Local host pipeline | GitHub and chat | Staged tools, parallel SDK agents, progress UI, durable storage, A/B, and evals | Reviewers and triage overlap while the playground shows every stage. |
-| [Knowledge base](/docs/example-agents/knowledge-base.md) | Local | Built-in HTTP chat | Durable host-side state, a conventions skill, a schedule, unit tests, and evals | People curate shared facts in chat, and fresh sessions retrieve them from markdown. |
-| [Codebase wiki](/docs/example-agents/codebase-wiki.md) | Local | GitHub and chat | Task-dispatch webhooks, seeded digests, a mapping skill, a schedule, and evals | Merged PRs accumulate into per-feature wiki pages with a daily digest. |
-| [Codeowners review](/docs/example-agents/codeowners-review.md) | Local | GitHub, chat, and fixtures | Ownership routing in code, playbook data files, parallel subagents, and evals | Each product area reviews with its own playbook, and verdicts aggregate mechanically. |
-
-## Pick a learning path
-
-Use this order when you want to learn the Agent SDK one capability at a time:
-
-1. Start with [Weather agent](/docs/example-agents/weather-agent.md) to explore the filesystem
-   conventions and cloud runtime.
-2. Strip the project back to [Slack agent](/docs/example-agents/slack-agent.md) to see the
-   minimum channel surface.
-3. Read [Playbook router](/docs/example-agents/benny.md) when Slack should route requests into repo
-   playbooks.
-4. Continue to [Alert investigator](/docs/example-agents/oncall.md) when the intake is bot
-   posts and the agent must pace its own engagement and re-checks.
-5. Add composition with [Concierge](/docs/example-agents/concierge.md).
-6. Study [PR evidence reviewer](/docs/example-agents/bugbot.md) before giving a model repository
-   evidence.
-7. Move policy into code with [Approval Buddy](/docs/example-agents/approval-buddy.md).
-8. Study [Security Reviewer](/docs/example-agents/security-reviewer.md) for host-side PR
-   work.
-9. See parallel subagent delegation carry team judgment in
-   [Codeowners review](/docs/example-agents/codeowners-review.md).
-10. Curate team context through conversation with
-    [Knowledge base](/docs/example-agents/knowledge-base.md), then let GitHub events maintain
-    product documentation in [Codebase wiki](/docs/example-agents/codebase-wiki.md).
-
-## Common prerequisites
-
-All examples require:
-
-- Node 22.13 or newer. Don't run the Agent SDK under Bun.
-- Workspace dependencies installed.
-- An agent-runtime credential for model turns.
-
-Several examples need more:
-
-- Account-linked Slack channels require a connected host account.
-- Alert investigator needs a dedicated Socket Mode app with channel-post
-  events and membership in the watched alerts channel.
-- GitHub examples require access to the target repository. Codebase wiki and
-  Codeowners review call the host `gh` CLI for PR data; the codeowners
-  fixtures run without network.
-- Example agents use `cursorHostedStorage` in `agent/storage.ts` for hosted session storage. See [Storage](/docs/storage.md).
-
-Each guide lists its own credentials, services, and side effects.
-
-## Validate any example
-
-Discovery commands don't start a model turn:
-
-```bash
-agent-sdk validate --dir examples/weather-agent
-agent-sdk info --dir examples/weather-agent --json
-```
-
-Start one development server with `agent-sdk dev examples/<name>`.
-Concierge depends on Weather agent, so its guide creates an isolated
-two-project mount. Don't mount the whole examples directory to test one
-agent; several advanced examples subscribe to live GitHub events.
-
-## Read by framework feature
-
-- [Concepts](/docs/concepts.md) explains filesystem discovery and runtime
-  boundaries.
-- [Project layout](/docs/reference/project-layout.md) lists every authored
-  folder.
-- [Tools](/docs/reference/tools.md), [channels](/docs/reference/channels.md), and
-  [MCP connections](/docs/reference/connections.md) cover the core extension
-  points.
-- [Evals](/docs/evals.md) and [live A/B metrics](/docs/ab.md) cover measured
-  iteration.
-- [Deployment](/docs/deployment.md) covers credentials, auth, storage, and
-  hosting.
-
----
-
-Source: /docs/example-agents/knowledge-base.md
-
-# Build a team knowledge base through conversation
-
-Knowledge base turns conversations into shared team context. Teach the agent
-about people, systems, decisions, and standing preferences. Three server
-tools read, search, and write human-readable markdown pages; a conventions
-skill shapes each write; and a daily schedule merges duplicates and rebuilds
-the index. A fresh session retrieves what an earlier conversation captured.
-
-Use this project when people should curate organizational knowledge through
-chat. Use [Codebase wiki](/docs/example-agents/codebase-wiki.md) when merged PRs should maintain
-feature documentation instead.
-
-[Browse the knowledge base source.](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/knowledge-base/)
-
-## Keep shared knowledge on the filesystem
-
-The knowledge base lives outside any session workspace, in a wiki
-directory on the serve host by default. `KNOWLEDGE_BASE_DIR` overrides the location,
-and the tools resolve it on every call, so tests and evals can point the same
-code at a temp directory.
-
-The store enforces its own safety:
-
-- Page ids are one to three lowercase kebab-case segments, so a page id
-  can't escape the wiki directory.
-- Pages cap at 64 KiB. Oversized writes fail with instructions to split
-  the page.
-- `wiki_write` replaces whole pages. The instructions require reading a
-  page before updating it, so rewrites carry existing facts forward.
-
-Every page is plain markdown. You can open the wiki in an editor,
-review it in a PR, or grep it.
-
-## Follow a fact through the agent
-
-1. You tell the agent something durable: a system, an owner, a standing
-   preference.
-2. The instructions require a `wiki_search` before claiming knowledge
-   and a `wiki_write` after learning something worth keeping.
-3. The `wiki-conventions` skill picks the page id (`staging-database`,
-   `people/jane-doe`), the page shape, and the dated fact format.
-4. The tool writes the page under the durable wiki root and returns
-   whether it created or updated the page.
-5. A later session, on any channel, finds the fact with `wiki_search`
-   and cites the knowledge-base page in its answer.
-
-Ephemeral chatter stays out. The instructions tell the model to skip
-one-off questions and to ask before saving anything borderline.
-
-## Map the knowledge-base files
-
-| File | Purpose |
-| --- | --- |
-| [`agent/agent.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/knowledge-base/agent/agent.ts) | Selects the local runtime and model. |
-| [`agent/instructions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/knowledge-base/agent/instructions.md) | Sets the read-before-answer and save-after-learning policy. |
-| [`agent/lib/wiki-store.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/knowledge-base/agent/lib/wiki-store.ts) | Validates page ids, lists, reads, writes, and searches the knowledge base. |
-| [`agent/tools/wiki_read.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/knowledge-base/agent/tools/wiki_read.ts) | Reads one page or lists every page with titles and timestamps. |
-| [`agent/tools/wiki_search.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/knowledge-base/agent/tools/wiki_search.ts) | Searches titles and bodies with per-page match lines. |
-| [`agent/tools/wiki_write.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/knowledge-base/agent/tools/wiki_write.ts) | Creates or replaces a page and reports created versus updated. |
-| [`agent/skills/wiki-conventions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/knowledge-base/agent/skills/wiki-conventions.md) | Names pages, shapes them, and dates every fact. |
-| [`agent/schedules/gardener.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/knowledge-base/agent/schedules/gardener.md) | Merges duplicates, rebuilds the index, and flags stale facts daily. |
-| [`agent/lib/wiki-store.test.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/knowledge-base/agent/lib/wiki-store.test.ts) | Unit-tests slug safety and store round-trips. |
-| [`agent/storage.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/knowledge-base/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
-| [`evals/evals.config.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/knowledge-base/evals/evals.config.ts) | Caps eval run concurrency. |
-| [`evals/knowledge.eval.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/knowledge-base/evals/knowledge.eval.ts) | Seeds a temp knowledge base and gates recall, save, and no-write decisions. |
-
-There is no authored channel, MCP connection, subagent, hook, or A/B
-experiment. The wiki directory is the durable knowledge store.
-
-## Prepare the example
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential for model turns.
-
-Nothing else. The wiki is created on first write.
-
-## Validate the surface
-
-```bash
-agent-sdk validate --dir examples/knowledge-base
-agent-sdk info --dir examples/knowledge-base --json
-```
-
-The manifest should report three server tools, one skill, and one
-schedule.
-
-## Exercise the store without a model turn
-
-```bash
-agent-sdk call wiki_write \
-  --dir examples/knowledge-base \
-  --input '{"page":"staging-database","content":"# Staging database\n\n- Port: 6432 (recorded 2026-07-19)\n"}'
-
-agent-sdk call wiki_search \
-  --dir examples/knowledge-base \
-  --input '{"query":"6432"}'
-
-agent-sdk call wiki_read --dir examples/knowledge-base --input '{}'
-```
-
-Invalid page ids fail fast. Try `{"page":"../escape"}` and the tool
-returns the validation error instead of touching the filesystem.
-
-## Prove recall across sessions
-
-```bash
-agent-sdk dev examples/knowledge-base
-```
-
-Teach it something in the playground:
-
-> Remember: our staging database is Postgres at
-> staging-db.internal.example.com, port 6432 via PgBouncer. Jane Doe
-> owns it.
-
-The trace shows the conventions skill load, then `wiki_write` calls
-for `staging-database`, `people/jane-doe`, and `index`. Start a new
-session and ask:
-
-> What port does our staging database use, and who owns it?
-
-The fresh session finds the answer with `wiki_search` and `wiki_read`
-and cites the pages. The conversation history is empty; the wiki is the
-source of truth.
-
-## Run the gardener
-
-The `gardener` schedule fires at 06:00 UTC and rewrites the wiki for
-consistency: merge near-duplicate pages, rebuild `index`, and flag
-facts older than 90 days. Under `agent-sdk dev`, timers don't auto-fire.
-Trigger it by hand:
-
-```bash
-curl -s -X POST http://127.0.0.1:3000/knowledge-base/v1/dev/schedules/gardener
-```
-
-## Run the evals
-
-```bash
-agent-sdk eval --dir examples/knowledge-base --list
-agent-sdk eval --dir examples/knowledge-base knowledge/recall
-```
-
-The eval file seeds a temp directory through `KNOWLEDGE_BASE_DIR`
-inside the cases, so the durable knowledge base never sees test data.
-`knowledge/recall` proves the fact comes from disk, not the conversation.
-`knowledge/save`
-gates the write decision, and `knowledge/no-write-on-ephemera` proves small
-talk stays out of the knowledge base.
-
-## Reuse the knowledge-base pattern
-
-Copy this shape when an agent needs durable, inspectable team knowledge:
-
-- Resolve the storage root lazily behind an environment override.
-- Validate identifiers in the store, not in the prompt.
-- Put naming and structure conventions in a skill so writes stay
-  consistent.
-- Add a consolidation schedule instead of letting pages rot.
-
-## Where to go next
-
-- [Tools](/docs/reference/tools.md)
-- [Skills](/docs/reference/skills.md)
-- [Schedules](/docs/reference/schedules.md)
-- [Evals](/docs/evals.md)
-
----
-
-Source: /docs/example-agents/oncall.md
-
-# Investigate every alert in its own Slack thread
-
-This agent is an on-call teammate. Alert feeds post into an alerts channel
-as bots. Each new alert dispatches an investigation session pinned to that
-post's thread: the agent reacts 👀 the moment it locks in, investigates
-immediately, and posts brief findings backed by evidence it observed.
-Replies in the thread reach it only after the thread has been quiet for
-about a minute, and reminder tools let it wake itself later to re-check a
-baseline or confirm an alert cleared.
-
-Use this example when alerts land in Slack and you want one thread-scoped
-investigation per alert, with an agent that paces its own engagement
-instead of answering every message.
-
-[Browse the current alert-investigator source.](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/oncall/)
-
-## Follow an alert
-
-1. An alert feed (Alertmanager, PagerDuty, Datadog) posts a new top-level
-   message in the watched alerts channel.
-2. The channel watch accepts it. `includeBotPosts` lets bot authors
-   through; the agent's own posts always stay dropped.
-3. The handler reacts 👀 on the alert post and sets "Investigating…"
-   typing. The reaction is the lock-in signal: this alert has an owner.
-4. The Agent SDK creates a session keyed to the alert's thread and dispatches
-   immediately. New alerts get no debounce.
-5. The agent reads the alert, gathers evidence, and posts findings to the
-   thread once it has a hypothesis.
-6. People discuss in the thread. Replies buffer per thread and dispatch as
-   one coalesced follow-up after roughly a minute of quiet.
-7. The agent arms reminders for anything that needs time and posts interim
-   updates when new evidence changes the picture.
-
-Mentions and DMs skip the watch entirely and behave like ordinary chat.
-
-## Map the files
-
-| File | Purpose |
-| --- | --- |
-| [`agent/agent.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/oncall/agent/agent.ts) | Names the agent and keeps harness workspaces outside any monorepo checkout. |
-| [`agent/instructions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/oncall/agent/instructions.md) | Engagement rules, the investigation loop, and the message discipline. |
-| [`agent/channels/slack-app.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/oncall/agent/channels/slack-app.ts) | Dedicated Socket Mode app: watch configuration and handler wiring. |
-| [`agent/lib/alert-watch.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/oncall/agent/lib/alert-watch.ts) | The engagement policy: lock in on new alerts, coalesce replies. |
-| [`agent/lib/thread-debounce.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/oncall/agent/lib/thread-debounce.ts) | Per-thread quiet window. |
-| [`agent/lib/alerts.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/oncall/agent/lib/alerts.ts) | Dispatch classification, prompt building, and thread addressing. |
-| [`agent/lib/slack-api.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/oncall/agent/lib/slack-api.ts) | Reactions and thread posts on this agent's own token pair. |
-| [`agent/tools/reminders_create.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/oncall/agent/tools/reminders_create.ts) | Self-scheduled wakes bound to the thread (plus `reminders_list` and `reminders_cancel`). |
-| [`agent/tools/post_thread_update.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/oncall/agent/tools/post_thread_update.ts) | Interim updates to the thread mid-turn. |
-| [`agent/storage.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/oncall/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
-| [`evals/evals.config.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/oncall/evals/evals.config.ts) | Caps eval run concurrency. |
-| [`evals/smoke.eval.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/oncall/evals/smoke.eval.ts) | Checks identity and the reminder-tool route. |
-
-## Let bot posts through the watch
-
-Channel watching drops bot-authored posts by default so two agents can
-never feed each other. Alert channels invert the assumption: the posts
-worth watching come from bots. `channelPosts.includeBotPosts` opts in per
-channel:
-
-```ts
-engagement: {
-  channelPosts: {
-    allow: ["#alerts"],
-    posts: "all",
-    includeBotPosts: true,
-  },
-},
-```
-
-Loop safety survives the opt-in. The pack matches the watching app's own
-posts by the `bot_id` and bot user id from `auth.test` and drops them, so
-the agent's findings never re-dispatch it. Posts that mention the bot stay
-on the mention path.
-
-`posts: "all"` also delivers thread replies. The handler, not the pack,
-decides their pace.
-
-## Pace the engagement
-
-The example runs two rhythms:
-
-- A new alert dispatches immediately.
-- Thread replies produce one engagement per lull.
-
-The pack's `debounceMs` is per message; it exists to let edits settle. This
-agent needs a per-thread window instead, so the handler owns it
-([`lib/thread-debounce.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/oncall/agent/lib/thread-debounce.ts)).
-Every reply restarts a 60-second timer keyed by thread. Superseded waiters
-resolve `null` and the handler returns `null` for them. When the thread
-goes quiet, the newest waiter receives the whole batch and dispatches one
-follow-up that lists every message with mentionable attribution.
-
-Two details make the window matter. A follow-up that arrives while a turn
-runs preempts that turn (latest message wins), so engaging per message
-would keep cancelling the investigation. And @mentions bypass the window
-through Slack's mention path, so a person who needs the agent now still
-gets it now.
-
-## Schedule your own re-checks
-
-Investigations rarely finish in one pass. A baseline comparison needs 20
-minutes of data. An alert that cleared may re-fire. The example hands the
-model three tools over `host.reminders`:
-
-- `reminders_create` arms a one-shot (`delay: "20m"`) or recurring
-  (`every: "30m"` with a plain-language stop condition) wake bound to the
-  thread's conversation.
-- `reminders_list` shows the thread's standing watches.
-- `reminders_cancel` disarms one, and refuses ids that belong to another
-  thread's conversation.
-
-When a reminder fires, its prompt returns to the same session as a
-follow-up turn, and the reply lands in the alert thread. The instructions
-keep wake prompts generic (re-read live state instead of replaying stale
-numbers) and wake replies to one line, for example "re-checked p99 on
-api-gateway: 120ms, back at baseline, cancelling the watch."
-
-Keep these tool filenames if you copy the design: the framework's reminder
-fire prompt tells the model to call `reminders_cancel` by name when a stop
-condition is set.
-
-## Alert people mid-investigation
-
-The final reply of each turn posts to the thread on its own.
-`post_thread_update` covers evidence that shouldn't wait for the turn to
-finish: it posts a one-or-two-sentence update through the agent's token,
-with `<@USERID>` mentions for the people who need to act. The instructions
-restrict it to changes in hypothesis, severity, or blast radius. Progress
-narration doesn't qualify.
-
-## Connect the Slack app
-
-Channel watching is Socket Mode only, so this example uses a dedicated
-app:
-
-```bash
-agent-sdk slack create --dir examples/oncall --name "Oncall" --channel-posts
-agent-sdk slack doctor --prefix ONCALL
-```
-
-`--channel-posts` prefills channel-watch events (`message.channels` /
-`message.groups`). Invite the bot to each watched channel after the
-wizard finishes.
-
-`ONCALL_ALERTS_CHANNELS` sets the watch list as comma-separated ids or
-`#names`. It defaults to `#alerts`.
-
-Wire observability MCP servers under `agent/mcp-connections/` so evidence
-gathering reaches your logs, metrics, and dashboards. The example ships
-none; without them the agent works from the alert text, its links, and the
-thread.
-
-## Validate and start the server
-
-```bash
-agent-sdk validate --dir examples/oncall
-agent-sdk info --dir examples/oncall --json
-agent-sdk dev examples/oncall
-```
-
-The info output lists four server tools and the watched channel on the
-`slack-app` channel. Missing tokens leave that channel idle without
-stopping the server.
-
-In dev mode, reminder timers don't auto-fire. List and fire them by hand
-through the dev routes described in
-[Schedules and reminders](/docs/reference/schedules.md#dispatch-and-dev-mode).
-
-## Test the policy without Slack
-
-The engagement policy is plain code with unit tests:
-
-```bash
-pnpm exec vitest run examples/oncall
-```
-
-The integration test drives a synthetic Events API delivery through the
-real parse, watch, and dispatch plumbing. It asserts a bot alert
-dispatches pinned to its thread after the lock-in reaction, the agent's
-own posts never loop, and replies coalesce behind the quiet window.
-
-The smoke eval spends a model turn:
-
-```bash
-agent-sdk eval --dir examples/oncall smoke --json
-```
-
-It checks identity and the reminder-tool route lexically. It doesn't prove
-Slack delivery or reaction behavior; the unit tests cover the dispatch
-side, and a live check needs the dedicated app connected.
-
-## Build an alert investigator
-
-Use this structure when a bot feed should drive thread-scoped work:
-
-1. Watch the feed channel with `includeBotPosts: true` and a narrow
-   allowlist.
-2. Acknowledge on the triggering post before dispatching, so people see
-   ownership without opening the thread.
-3. Dispatch new items immediately; coalesce thread chatter behind a
-   per-thread quiet window.
-4. Give the agent reminder tools for anything that needs time, and make
-   cancel discipline part of the instructions.
-5. Keep every posted message brief and tied to evidence the agent saw.
-
-## Where to go next
-
-- [Slack](/docs/guides/slack.md)
-- [Schedules and reminders](/docs/reference/schedules.md)
-- [Tools](/docs/reference/tools.md)
-- [Playbook router](/docs/example-agents/benny.md) for the human-post variant of channel
-  watching
-
----
-
-Source: /docs/example-agents/security-reviewer.md
-
-# Run staged security reviews from GitHub events
-
-Security Reviewer turns a pull request into a staged host-side review. One
-tool prepares the diff and selects modules. A second fans out specialized
-reviewers and triages candidates as they arrive. A third deduplicates the
-confirmed findings, writes artifacts, and may publish a GitHub review.
-
-Use this example when the workflow needs several model workers, but the host
-must own orchestration, progress, artifacts, and the final write.
-
-Source lives under [`factory/security-reviewer/`](https://github.com/cursor/cursor/tree/main/factory/security-reviewer/) (factory agent, not under `examples/`).
-
-Want one model turn and one comment? Scaffold the
-[security-reviewer template](/docs/templates/security-reviewer.md).
-
-[Browse the Security Reviewer source.](https://github.com/cursor/cursor/tree/main/factory/security-reviewer/)
-
-## Run a three-stage host pipeline
-
-Security Reviewer is a pipeline, not one long agent turn:
-
-| Stage | Tool | Result |
-| --- | --- | --- |
-| Prepare | `prepare_review` | Fetch metadata and diff, create a `runId`, and select security modules. |
-| Review and triage | `run_reviewers` | Run module reviewers in parallel and start triage as each candidate arrives. |
-| Finalize | `finalize_review` | Apply thresholds, deduplicate findings, write artifacts, and optionally post a review. |
-
-`run_triage` remains available as a compatibility stage. In the normal flow,
-triage has already completed inside `run_reviewers`, so it reports existing
-results. If candidates exist without triage output, it starts triage workers
-and writes their state.
-
-The configured root agent chooses and sequences tools in chat. The review
-workers use a model selected by the host pipeline. They are
-created programmatically with the agent SDK, not discovered from
-`agent/subagents/`.
-
-## Follow a GitHub review
-
-1. A pull request event starts a review and opens a playground session.
-2. The playground shows reviewer and triage progress.
-3. Confirmed findings appear in the PR review.
-4. A GitHub Check reports completion or a processing failure.
-
-## Map the framework features
-
-| Capability | Source | Role |
-| --- | --- | --- |
-| Root agent | [`agent/agent.ts`](https://github.com/cursor/cursor/blob/main/factory/security-reviewer/agent/agent.ts), [`agent/instructions.md`](https://github.com/cursor/cursor/blob/main/factory/security-reviewer/agent/instructions.md) | Configure local chat and explain the three-stage contract. |
-| Server tools | [`agent/tools/`](https://github.com/cursor/cursor/tree/main/factory/security-reviewer/agent/tools/) | Expose each review stage to chat and host orchestration. |
-| GitHub channel | [`agent/channels/github.ts`](https://github.com/cursor/cursor/blob/main/factory/security-reviewer/agent/channels/github.ts) | Filter wakes, run background tasks, and publish status. |
-| Progress channel | [`agent/channels/asr-progress.ts`](https://github.com/cursor/cursor/blob/main/factory/security-reviewer/agent/channels/asr-progress.ts) | Serve live reviewer and triage state by `runId`. |
-| Playground renderer | [`agent/playground/tools/run_reviewers.tsx`](https://github.com/cursor/cursor/blob/main/factory/security-reviewer/agent/playground/tools/run_reviewers.tsx) | Replace the generic tool chip with live module rows. |
-| SDK review pipeline | [`review-stages.ts`](https://github.com/cursor/cursor/blob/main/factory/security-reviewer/agent/lib/review-stages.ts), [`@anysphere/security-review-lib`](https://github.com/cursor/cursor/blob/main/packages/security-review-lib/src/index.ts) | Select modules, call model workers, triage, deduplicate, and write artifacts. |
-| Storage | [`agent/storage.ts`](https://github.com/cursor/cursor/blob/main/factory/security-reviewer/agent/storage.ts) | Persist framework sessions with `cursorHostedStorage` (lazy restore). |
-| A/B | [`agent/ab.ts`](https://github.com/cursor/cursor/blob/main/factory/security-reviewer/agent/ab.ts) | Compare all-severity versus high-only GitHub comments. |
-| Eval | [`evals/`](https://github.com/cursor/cursor/tree/main/factory/security-reviewer/evals/) | Check stage-tool presence against a pinned sample. |
-
-There is no Slack channel, authored skill, discovered subagent, MCP
-connection, schedule, reminder, hook, tool approval, or cloud runtime.
-
-## Prepare the host
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential for the root turn and review workers.
-- GitHub read access for preparation.
-- GitHub write access for webhook-driven reviews and Checks.
-
-The pipeline exposes settings for:
-
-- the worker model,
-- reviewer and triage parallelism,
-- reviewer, triage, duplicate-gate, and final-dedupe timeouts, and
-- prior-comment loading.
-
-The active names live beside the orchestration in
-[`review-stages.ts`](https://github.com/cursor/cursor/blob/main/factory/security-reviewer/agent/lib/review-stages.ts).
-
-## Validate the discovered agent
-
-```bash
-agent-sdk validate --dir ../../factory/security-reviewer
-agent-sdk info --dir ../../factory/security-reviewer --json
-agent-sdk eval --dir ../../factory/security-reviewer --list
-```
-
-`validate` should pass. `info` and `eval --list` should match the capabilities
-mapped above.
-
-## Know the chat path's write boundary
-
-In chat, the root instructions ask the model to use this order:
-
-```text
-prepare_review -> run_reviewers -> finalize_review
-```
-
-They also ask the model to set `postComment: true` only on request. This is
-prompt policy, not a deterministic safety gate. The model chooses tool
-arguments, and `finalize_review` has no human approval. Use the direct stage
-calls below when a no-post proof must be enforced.
-
-## Call stages directly without publishing
-
-Call each stage and pass `postComment: false` yourself:
-
-```bash
-agent-sdk call prepare_review \
-  --dir ../../factory/security-reviewer \
-  --input '{"prUrl":"https://github.com/owner/repo/pull/123"}'
-
-agent-sdk call run_reviewers \
-  --dir ../../factory/security-reviewer \
-  --input '{"runId":"<run-id>"}'
-
-agent-sdk call finalize_review \
-  --dir ../../factory/security-reviewer \
-  --input '{"runId":"<run-id>","postComment":false}'
-```
-
-Review state lives under the project's run-artifact directory, so later
-stages can open the prepared `runId`.
-
-> [!CAUTION]
-> `finalize_review` with `postComment: true` writes to GitHub. The webhook
-> path always requests that write. Chat instructions alone don't prevent it.
-
-## Watch parallel work in the playground
-
-Run the dev server:
-
-```bash
-agent-sdk dev ../../factory/security-reviewer
-```
-
-Open the printed playground and start a review. The custom
-`run_reviewers` renderer polls the progress channel's `GET /:runId` route.
-
-It refreshes every 500 ms while the stage runs. Each row shows a reviewer
-module's state, candidates, reviewed areas, and failure. A second section
-shows triage jobs and confirmed or rejected counts.
-
-This is an authored playground extension. The Agent SDK discovers it by the tool
-name, so the generic `run_reviewers` chip becomes a domain-specific view
-without changing the framework playground.
-
-## Fan out reviewers while triage starts
-
-Module selection uses repository and path rules. The current module set
-covers:
-
-- agent tooling trust boundaries,
-- privileged service RPCs,
-- product-specific security risks,
-- dependency and supply-chain changes,
-- deployment and infrastructure code,
-- filesystem and workspace boundaries,
-- privacy, and
-- general security review.
-
-Selected modules may run more than once. Candidates pass through a duplicate
-gate, then bounded triage. Reviewer or triage failures can produce partial
-results. A final dedupe failure stops finalization.
-
-The pipeline writes JSONL journals as work completes. Final artifacts include
-the review bundle, patch, reviewer outputs, candidates, triage decisions,
-findings, accounting, and audit events.
-
-## Separate session storage from review artifacts
-
-`cursorHostedStorage` keeps Agent SDK session and event records on
-Cursor-managed hosting. Security Reviewer sets `restore: "off"` so startup
-doesn't load old review sessions in bulk. A continuation lookup can still
-fetch a needed session. See [Storage](/docs/storage.md).
-
-The staged review files are separate from session storage. Session-store
-durability doesn't preserve those files. All stages for one `runId` must see
-the same filesystem.
-
-This split is useful when conversation history needs shared durability but
-large review artifacts belong on attached storage or an object store.
-
-## Compare live comment variants
-
-The comment-severity experiment uses sticky session assignment with a 5%
-holdout:
-
-- `control` posts every finding.
-- `treatment` posts only high and critical findings.
-
-Finalization enforces the comment filter. The treatment also adds an
-instruction overlay asking chat and playground summaries to lead with high
-and critical findings. Full artifacts, `finalResponse`, and finding counts
-still include every finding. Stage-tool counters appear in the
-playground A/B view. Local sample and snapshot files persist under
-the project state directory.
-
-When a treatment session has only low or medium findings, the filtered review
-body currently says no vulnerabilities were found even though artifacts and
-status retain findings. Account for that mismatch before using this
-experiment as a publishing policy.
-
-Eval sessions skip A/B enrollment.
-
-## Test the GitHub channel carefully
-
-The channel uses the host's Cursor account repository scope. It wakes on
-`opened` and `synchronize`, skips drafts, and posts its own GitHub Check.
-
-Inspect its event surface:
-
-```bash
-agent-sdk github events \
-  --dir ../../factory/security-reviewer \
-  --json
-```
-
-Replay reaches the full publishing path:
-
-```bash
-TEST_PR_URL=https://github.com/your-org/allowlisted-test-repo/pull/123
-agent-sdk github replay \
-  "$TEST_PR_URL" \
-  --dir ../../factory/security-reviewer \
-  --action opened
-```
-
-Set `TEST_PR_URL` to a PR in the channel's configured repository allowlist.
-Run the command only against a PR intended for test reviews. It posts a
-GitHub Check and may post findings.
-
-## Inspect the eval before running it
-
-```bash
-agent-sdk eval --dir ../../factory/security-reviewer --list
-```
-
-The case gates the review flow and prevents comment posting. It still fetches
-the live PR, so it needs GitHub access.
-
-## Build another staged pipeline
-
-Use staged host orchestration when:
-
-- each phase needs its own timeout and artifact,
-- model workers should run in bounded parallel,
-- later work can start as soon as partial results arrive,
-- a webhook must acknowledge before the work finishes, or
-- operators need live progress beyond one tool spinner.
-
-Keep external writes in finalization. Pass a `runId` between stages, journal
-progress before publishing, and make partial-worker failures visible in the
-result.
-
-## Where to go next
-
-- [GitHub](/docs/guides/github.md)
-- [Tools](/docs/reference/tools.md)
-- [Channels](/docs/reference/channels.md)
-- [Playground](/docs/reference/playground.md)
-- [Storage](/docs/storage.md)
-- [Live A/B metrics](/docs/ab.md)
-- [Evals](/docs/evals.md)
-
----
-
-Source: /docs/example-agents/slack-agent.md
-
-# Put a minimal agent in Slack
-
-Slack agent is the smallest channel example. It has one runtime config, one
-instruction file, and one authored channel. A teammate mentions the agent,
-the local runtime harness runs a turn, and the answer
-returns to the same Slack thread.
-
-Use it to learn the minimum needed for a Slack agent before adding tools,
-workflows, or a dedicated app.
-
-[Browse the Slack agent source.](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/slack-agent/)
-
-## Keep the Slack channel small
-
-Slack agent delegates transport details to the host connection. The authored
-file selects the account-linked transport, gives the agent a single-token
-router name and icon, and supplies suggested prompts.
-
-The complete channel lives in
-[`agent/channels/slack.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/slack-agent/agent/channels/slack.ts).
-The framework supplies message intake, thread-scoped sessions, delivery,
-status updates, and suggested prompts.
-
-## Follow a Slack message
-
-1. A user mentions the agent or sends the host app a direct message naming
-   it.
-2. The Slack relay selects this channel by its single-token `agentName`.
-3. The Agent SDK maps the Slack channel and thread timestamp to a continuation
-   key.
-4. The local harness runs with
-   [`instructions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/slack-agent/agent/instructions.md).
-5. The response returns to the triggering thread.
-6. A later message in the same thread resumes the durable session.
-
-The prompt asks for concise threaded replies. It doesn't define domain policy
-or tool routing.
-
-## Map the Slack agent files
-
-| File | Purpose |
-| --- | --- |
-| [`package.json`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/slack-agent/package.json) | Declares the example package and Agent SDK dependency. |
-| [`agent/agent.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/slack-agent/agent/agent.ts) | Names the agent and selects the model. The omitted `runtime` defaults to local. |
-| [`agent/instructions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/slack-agent/agent/instructions.md) | Sets the always-on response style. |
-| [`agent/channels/slack.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/slack-agent/agent/channels/slack.ts) | Connects the signed-in host account to Slack. |
-| [`agent/storage.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/slack-agent/agent/storage.ts) | Persists sessions and events with `cursorHostedStorage`. |
-
-There are no authored tools, skills, MCP connections, subagents, schedules,
-hooks, A/B experiments, or evals. This small surface is the lesson.
-
-## Connect the host
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential.
-- Slack connected through the selected channel transport.
-
-Sign in and confirm the active account:
-
-```bash
-agent-sdk login
-agent-sdk whoami
-```
-
-The selected transport owns Slack credential setup. See the
-[Slack guide](/docs/guides/slack.md) for account-linked and dedicated-app
-options.
-
-## Validate and start the server
-
-```bash
-agent-sdk validate --dir examples/slack-agent
-agent-sdk info --dir examples/slack-agent --json
-agent-sdk dev examples/slack-agent
-```
-
-The dev command prints the playground URL. It also mounts the Slack channel
-and waits for relayed messages.
-
-In Slack, address the configured host app and router name, then send:
-
-> `<host-app mention> <router name>` Explain the Agent SDK in three bullets.
-
-Reply in the generated thread:
-
-> Make the second bullet simpler.
-
-The second message reaches the same session. You can open that session in the
-playground to inspect the received message, model events, final reply, and
-usage.
-
-## Test without Slack
-
-Every project gets the built-in HTTP channel even when no HTTP file exists.
-Run a one-shot turn through it:
-
-```bash
-agent-sdk run --dir examples/slack-agent \
-  --message "Explain the Agent SDK simply."
-```
-
-The same project also exposes an MCP endpoint. Since this agent has no server
-tools, its MCP surface contains `ask` and `check`, but not `call_tool`.
-
-These automatic surfaces let you test the prompt from the CLI and let another
-agent delegate to it later. The authored Slack channel only changes how work
-arrives and where replies go.
-
-## Know when to add a dedicated app
-
-An account-linked Slack transport is a fit for mentions, direct messages, thread
-continuity, and agent-branded replies. Move to a dedicated Socket Mode channel
-when you need:
-
-- top-level channel watching,
-- interactive approval buttons,
-- a separate bot identity, or
-- Slack app events unsupported by the account-linked relay.
-
-Compare this example with [Playbook router](/docs/example-agents/benny.md), which adds allowlisted channel
-watching, and [Weather agent](/docs/example-agents/weather-agent.md), which adds approval buttons
-through a second Slack channel.
-
-## Turn the channel into your own Slack agent
-
-Copy the three authored files, then change:
-
-- `name` in `agent.ts` for the harness identity,
-- `agentName` in `slack.ts` for the single-token router name,
-- the instructions for your domain, and
-- suggested prompts for the tasks teammates should try.
-
-Keep `agentName` free of whitespace. Use PascalCase for multiword names.
-
-## Where to go next
-
-- [Slack](/docs/guides/slack.md)
-- [Channels](/docs/reference/channels.md)
-- [Sessions and streaming](/docs/reference/sessions.md)
-- [Playground](/docs/reference/playground.md)
-
----
-
-Source: /docs/example-agents/weather-agent.md
-
-# Explore the full Agent SDK surface with a weather agent
-
-The weather agent is the broadest small example in the repository. It fetches
-live conditions and forecasts, converts units through MCP, writes notes in a
-session workspace, and runs from HTTP, Slack, a schedule, and the MCP endpoint.
-
-Use this project when you want to see how the Agent SDK's filesystem pieces fit
-together before you design a larger agent.
-
-[Browse the weather agent source.](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/weather-agent/)
-
-## See the runtime features together
-
-Most examples focus on one feature. Weather agent puts the major runtime
-features side by side:
-
-| Capability | Source | Role |
-| --- | --- | --- |
-| Root config and instructions | [`agent/agent.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/weather-agent/agent/agent.ts), [`agent/instructions.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/weather-agent/agent/instructions.md) | Select the cloud runtime and route each request. |
-| Server tools | [`agent/tools/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/weather-agent/agent/tools/) | Fetch Open-Meteo data and call MCP from the serve host. |
-| Agent tool | [`save_weather_note.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/weather-agent/agent/tools/save_weather_note.ts) | Run a Python script inside the session workspace. |
-| Stdio MCP | [`units.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/weather-agent/agent/mcp-connections/units.ts), [`probe.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/weather-agent/agent/mcp-connections/probe.ts) | Expose conversion tools to the model, host tools, and channel handlers. Author VM-side probe tools as TypeScript `execute` functions. |
-| Custom HTTP | [`webhook.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/weather-agent/agent/channels/webhook.ts) | Start a turn or call MCP without a model turn. |
-| Slack | [`slack.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/weather-agent/agent/channels/slack.ts), [`slack-app.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/weather-agent/agent/channels/slack-app.ts) | Compare account-linked chat with a dedicated app. |
-| Skill and subagent | [`forecast.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/weather-agent/agent/skills/forecast.md), [`researcher/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/weather-agent/agent/subagents/researcher/) | Load a procedure on demand or delegate broad research. |
-| Schedule and hooks | [`heartbeat.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/weather-agent/agent/schedules/heartbeat.md), [`audit.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/weather-agent/agent/hooks/audit.ts), [`journal.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/weather-agent/agent/hooks/journal.ts) | Start recurring tasks, log usage, and save turn summaries. |
-| A/B and evals | [`agent/ab.ts`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/examples/weather-agent/agent/ab.ts), [`evals/`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/weather-agent/evals/) | Compare a sticky variant and protect tool routing with regression cases. |
-
-## Follow one request
-
-A current-weather question takes this path:
-
-1. The built-in HTTP channel, Slack, or the custom `/report` route creates a
-   durable session.
-2. `instructions.md` tells the model to call `get_weather` instead of
-   guessing.
-3. The server tool geocodes the city, fetches Open-Meteo, validates the
-   response, and returns normalized fields.
-4. The agent writes a short answer. The Agent SDK records every event in the
-   session stream.
-5. The audit hook observes `turn.completed`. If the session joined the A/B
-   experiment, the collector updates its metrics too.
-
-Forecasts route to `get_forecast`. Unit conversions route to
-`convert_temperature`, which calls the `units` MCP server through
-`ctx.host.mcp`. Climate history and broad comparisons route to the
-`researcher` subagent.
-
-## Prepare the example
-
-You need:
-
-- Node 22.13 or newer.
-- An agent-runtime credential.
-- Network access to Open-Meteo.
-- Python 3 for `save_weather_note`.
-
-The project mounts an account-linked Slack channel. The Agent SDK checks the
-connection at startup, so sign in even when you plan to call a deterministic
-tool.
-
-The optional dedicated Slack app also needs a token pair.
-`agent-sdk slack create --dir examples/weather-agent` provisions the
-app and writes the tokens for you (see the
-[Slack guide](/docs/guides/slack.md#set-it-up)); with hand-minted tokens,
-export them instead:
-
-```bash
-export WEATHER_AGENT_SLACK_BOT_TOKEN=xoxb-...
-export WEATHER_AGENT_SLACK_APP_TOKEN=xapp-...
-agent-sdk slack doctor --prefix WEATHER_AGENT
-```
+| `t.score(name, value)` | records a 0–1 score you computed; soft until you add a bar |
+| `t.requireToolCall(name, matcher?)` | gates on a matching call and returns it, so later code can read its input and output |
+| `t.requireInputRequest(filter?)` | gates on exactly one pending approval request and returns it |
 
-Without those two tokens, the dedicated channel stays idle. The
-account-linked channel still works.
+Every gate returns a handle: `.soft()` demotes it to tracked-only,
+`.atLeast(0.7)` adds a soft score bar, and `.gate(0.8)` promotes a
+scored assertion into a hard gate.
 
-## Inspect before running
+With no matcher, `calledTool` is request-based: a requested call counts
+even when its result has not arrived. Pass
+`t.calledTool("inspect_pr", { status: "completed" })` to require the
+call to return. `input`, `output`, and `count` matcher fields accept a
+literal, a `RegExp`, or a predicate.
 
-```bash
-agent-sdk validate --dir examples/weather-agent
-agent-sdk info --dir examples/weather-agent --json
-agent-sdk eval --dir examples/weather-agent --list
-```
+The expectation builders are `includes(string | RegExp)`,
+`equals(value)`, `matches(schema)`, `similarity(expected)`, and
+`satisfies(predicate, label)`. `includes` stringifies its input,
+`equals` compares values deeply, `matches` validates against a Standard
+Schema (or anything with `safeParse`, like Zod), `similarity` scores
+normalized text similarity, and `satisfies` runs your predicate. The
+plain function `normalizedSimilarity(actual, expected)` returns the
+same 0–1 score for use with `t.score`.
 
-`validate` should pass. `info` and `eval --list` should match the capabilities
-described above.
+A few more context members shape a case: `t.require(value, expectation)`
+records a gate and stops the test body when it fails, without a
+duplicate execution error. `t.skip(reason)` ends the case as skipped
+(reported separately, never changes the exit code; call it before
+sending messages). `t.metric(name, value)` records a structured score
+for the playground case card. `t.log(message)` records a debug line for
+the CLI and playground result.
 
-## Call the typed tools
+Three `t.send` options apply on session create (first `t.send` only):
 
-Start with the current-weather server tool:
+- `workspaceFiles`: `{ path: contents }`, seeded into the local session
+  workspace. Prefer this over machine-local paths.
+- `workspaceDir`: absolute harness cwd (local runtime).
+- `cloud`: per-session cloud options merged over the agent's static
+  `cloud` config (repos / env / …). Use a pinned `repos` override to
+  attach a fixture repo for cloud evals without putting it on the
+  agent's default `cloud.repos`. Cloud ignores `workspaceFiles` seeds.
 
-```bash
-agent-sdk call get_weather \
-  --dir examples/weather-agent \
-  --input '{"city":"New York City"}'
+```ts
+const toolResults = t.events.filter((e) => e.type === "action.result");
+t.check(
+  toolResults.length,
+  satisfies((n) => (n as number) <= 4, "at most 4 tool calls")
+);
 ```
 
-`defineTool` gives the input a Zod schema. The Agent SDK validates the JSON before
-`execute` runs. The result includes the matched place, condition,
-temperature, humidity, wind, gusts, and precipitation.
+A case with no explicit gates falls back to whether at least one turn
+completed successfully. Add `t.succeeded()` and behavior-specific gates
+anyway. They make the contract visible during review.
 
-Try the forecast:
+### Judge free-form output
 
-```bash
-agent-sdk call get_forecast \
-  --dir examples/weather-agent \
-  --input '{"city":"Lisbon","days":5}'
+When wording matters and no regex captures it, `t.judge` grades the
+reply with an LLM. The built-in graders are `factuality(expected)`,
+`summarizes(expected)`, `closedQA(criteria)`, and `sql(expected)`. Each
+scores `t.reply` by default; pass `{ on }` to grade another value.
+
+```ts
+t.judge.factuality("It is 54°F in NYC right now.").atLeast(0.7);
 ```
 
-The tool accepts one to seven days. Shared Open-Meteo code lives under
-`agent/lib/`, so the Agent SDK imports it without discovering another tool.
+Judge assertions are soft by default, so a judge never fails a build
+until you give it a bar with `.atLeast(0.7)` or promote it with
+`.gate(0.8)`. The judge model comes from `defineEvalConfig({ judge })`,
+`defineEval({ judge })`, a case-level `judge`, or a per-call
+`{ model }` override; the nearest one wins. For a domain-specific judge
+whose verdict is not a single score, `t.judge.model(prompt)` sends a
+raw prompt to the same model and returns the reply. You then record the
+parsed result with `t.score` or `t.check`.
 
-## Compare server and agent execution
+## Run evals from the CLI
 
-Most weather tools use the default `execution: "server"`. Their TypeScript
-runs inside the serve host and can reach `ctx.host` services.
+The `eval` command discovers, filters, and runs cases.
 
-`save_weather_note` uses `execution: "agent"` instead. The Agent SDK materializes
-its script into the agent environment. The script reads JSON from stdin and
-appends to `weather-notes.md` in that session's workspace:
+Run the CLI under Node 22.13 or newer. Do not use Bun. Its HTTP/2 client
+breaks tool-result streams and causes eval turns to fail.
 
 ```bash
-agent-sdk run --dir examples/weather-agent \
-  --message "Save a note that Boston is cold and windy."
+agent-sdk eval --dir . --list                         # discover only
+agent-sdk eval --dir .                                # run all
+agent-sdk eval --dir . builds/checkout                # one datapoint
+agent-sdk eval --dir . builds search                  # several ids or prefixes
+agent-sdk eval --dir . --tag smoke --tag pull-request # any matching tag
+agent-sdk eval --dir . --json --no-stream             # machine-readable results
+agent-sdk eval --dir . --verbose                      # logs + reply snippets
 ```
 
-Each session gets its own workspace. Saving a note doesn't edit the authored
-example.
-
-This split matters on cloud. Server tools stay on the Agent SDK host.
-Agent tools run inside the cloud workspace.
-
-## Verify tool execution on the agent VM
-
-Ask the agent to call `probe_cloud_tool` on the `probe` MCP server.
-`agent/mcp-connections/probe.ts` authors that tool as TypeScript. The Agent
-SDK packages it as stdio MCP so a cloud VM with no checkout of this example
-can still run it. The model lists the server and calls the tool; it does
-not write a `.sh`.
-
-A real call writes `vm-tool-observations/<id>.json` in the agent cwd and
-returns hostname, cwd, and pid. Stream events show `probe:probe_cloud_tool`,
-not `shell`.
+Id filters use OR semantics. Each filter selects an exact id and its
+descendants. For example, `builds` selects `builds`,
+`builds/checkout`, and every other case below that path. Repeated tags
+also use OR semantics. When you provide both ids and tags, a case must
+match both groups.
 
-A local tool script or a marker under `probes/` means the model
-invented a substitute.
+`eval` boots an ephemeral server on port 0 with a temp state root
+outside the project, so cases don't inherit ambient monorepo rules and
+don't write into the project state directory. Point `--url` at a running server to eval
+a live agent instead:
 
 ```bash
-agent-sdk run --dir examples/weather-agent \
-  --message "Test custom tool execution from this cloud agent. Call probe_cloud_tool."
+agent-sdk eval --dir . \
+  --url http://127.0.0.1:3000/weather-agent \
+  --bearer-token "$AGENT_TOKEN"
 ```
 
-## Use MCP connections in three places
+The eval definitions still come from `--dir`; `--url` only changes the
+agent that receives the turns. For a locally mounted multi-agent
+directory, `--slug weather-agent` chooses the target. Use
+`--state-root` to keep ephemeral session state at a chosen path,
+`--timeout-ms` to override the project timeout, and `--no-stream` to
+keep live progress off stderr. A TTY streams turn progress by default.
+`--verbose` still writes `t.log` lines to stderr and adds reply snippets
+to text results.
 
-`agent/mcp-connections/units.ts` starts a local stdio server. The filename
-makes its server name `units`. The Agent SDK exposes it to:
+Model turns need a Cursor credential from `agent-sdk login` or
+`CURSOR_API_KEY`.
 
-- the model as MCP tools,
-- server tools through `ctx.host.mcp`, and
-- channel handlers through `host.mcp`.
+See [CLI: eval](/docs/reference/cli.md#eval) for flags and exit codes.
 
-`probe` is a second stdio connection. Its tools are TypeScript `execute`
-functions; the Agent SDK packages them so a cloud VM can spawn the server
-without this checkout. The model calls `probe_cloud_tool` directly; no host
-tool wraps it.
+### JSON results
 
-`convert_temperature` demonstrates the server-tool path:
+Use `--json --no-stream` in scripts and CI. The top-level result carries
+the totals and one result per case:
 
-```bash
-agent-sdk call convert_temperature \
-  --dir examples/weather-agent \
-  --input '{"value":72,"from":"F"}'
+```json
+{
+  "ok": true,
+  "passed": 1,
+  "failed": 0,
+  "results": [
+    {
+      "id": "readiness",
+      "ok": true,
+      "assertions": [{ "name": "succeeded", "passed": true }],
+      "sessionId": "ses_123",
+      "inputs": ["Is checkout pull request 42 ready to approve?"],
+      "toolCalls": [{ "toolName": "inspect_pr", "isError": false }],
+      "logs": [],
+      "durationMs": 12340
+    }
+  ]
+}
 ```
 
-The custom channel demonstrates the handler path. Start the dev server:
+Each case result can also include `description`, `finalText`, `tools`,
+`error`, and tool arguments or output. This shape lets CI report the
+failed assertion without parsing terminal text.
 
-```bash
-agent-sdk dev examples/weather-agent
-```
+## Run evals in the playground
 
-Then call MCP deterministically through `/convert`:
+Start the server, open the playground, and choose **Evals**. You can run
+every case or one case, watch progress, and open the resulting session
+trace. The Evals tab works on a normal `serve`.
 
 ```bash
-curl -s -X POST \
-  http://127.0.0.1:3000/weather-agent/v1/channels/webhook/convert \
-  -H 'content-type: application/json' \
-  -d '{"value":20,"from":"C"}'
+agent-sdk serve --dir .
 ```
 
-No model chooses a tool in this route. The handler calls the MCP server and
-returns its result.
-
-## Keep conversation state in a custom channel
+Playground runs target the live server instead of an ephemeral one.
+Their sessions appear in the session list. One eval batch can run at a
+time. Persistence follows the rule under
+[Configure eval runs](#configure-eval-runs). See
+[Playground eval routes](/docs/reference/http-api.md#playground-eval-routes).
+The start request returns `202` while cases run in the background.
+Poll until the snapshot status becomes `completed`, `failed`, or `cancelled`.
+Configuration errors appear on a failed snapshot.
 
-`POST /report` starts a model turn and waits for it:
+On `--prod` / `--url`, the CLI prints the Eval ID as soon as the batch is
+accepted (and a Playground deep link with `?view=evals&evalRunId=…`):
 
 ```bash
-curl -s -X POST \
-  http://127.0.0.1:3000/weather-agent/v1/channels/webhook/report \
-  -H 'content-type: application/json' \
-  -d '{"message":"What is the weather in Paris?"}'
-```
-
-The response includes a `key`. Send it back on the next request to continue
-the same session:
+agent-sdk eval --prod --slug vulnerability-scanner --tag deepsec
+# Eval ID: evalrun_…
+# Cancel:  agent-sdk eval cancel evalrun_… --prod --slug vulnerability-scanner
+# Playground: https://…/playground?view=evals&evalRunId=evalrun_…
 
-```bash
-curl -s -X POST \
-  http://127.0.0.1:3000/weather-agent/v1/channels/webhook/report \
-  -H 'content-type: application/json' \
-  -d '{"message":"How about tomorrow?","key":"<key>"}'
+agent-sdk eval cancel evalrun_… --prod --slug vulnerability-scanner
+agent-sdk eval status evalrun_… --prod --slug vulnerability-scanner
 ```
 
-This is the custom-channel version of a continuation token. See
-[webhooks and custom channels](/docs/guides/webhooks.md) for route schemas,
-authentication, and asynchronous handlers.
-
-## Load procedures and delegate research
+## What good cases assert
 
-The forecast skill gives the root agent an on-demand procedure. The Agent SDK
-advertises the skill's description, then the harness loads its content when
-the request matches.
+Gate decisions and shape, not prose. Model wording varies run to run.
+Tool choice, tool avoidance, and output structure are the stable
+contract.
 
-The `researcher` directory is an SDK subagent. Its description tells the
-parent when to delegate. It inherits the parent's execution surface, but
-gets its own instructions:
+1. `t.succeeded()`: always, first.
+2. The tool decision: `calledTool` for the intended path,
+   `notCalledTool` for the likely wrong alternative. The pair is
+   stronger than either alone.
+3. Output shape: a regex for the contract (`/ready|blocked/i`, a JSON
+   marker, a findings-block fence), never exact sentences.
+4. For structured output, parse `t.reply` and check fields with
+   `satisfies` instead of substring-matching JSON.
 
-```bash
-agent-sdk run --dir examples/weather-agent \
-  --message "Compare record summer temperatures across Paris, London, and Rome."
-```
+The common failure modes: asserting exact phrasing, packing more than
+about five gates into one case (split it), and cases that depend on live
+external state that drifts (pin the input; see fixtures).
 
-Use a skill when the same agent needs a procedure. Use a subagent when the
-parent should hand a bounded task to a specialist. The
-[subagents reference](/docs/reference/subagents.md) explains the current
-inheritance limits.
+## Pick fixtures by agent type
 
-## Trigger the schedule and inspect the hook
+The right fixture depends on the surface under test.
 
-The heartbeat schedule runs at 09:00 UTC on weekdays. Automatic schedule
-timers stay off under `--dev`, so dispatch it manually:
+| Agent surface | Fixture |
+| --- | --- |
+| Chat / domain assistant | A canonical prompt string, chosen once and frozen |
+| Tool-heavy | Run `agent-sdk call <tool>` first to pin what the tool returns, then freeze the prompt that triggers it |
+| GitHub webhook | `agent-sdk github replay <pr> --events '*' --dry-run --out fixtures/github` snapshots real payloads for offline replay ([GitHub guide](/docs/guides/github.md)) |
+| PR reviewer with host preparation | Diff, metadata, and gold labels pinned to commit SHAs; keep any live PR matrix small |
+| Workspace-dependent | `workspaceFiles` in `t.send` options, never developer-machine paths |
 
-```bash
-curl -s -X POST \
-  http://127.0.0.1:3000/weather-agent/v1/dev/schedules/heartbeat
-```
+Tag the fast, reliably passing core `smoke` and run `--tag smoke` in the
+inner loop. Leave slow or flaky-prone cases untagged for explicit runs.
 
-It creates a task session to check San Francisco, New York, and London.
-The audit hook logs usage after each completed turn. Hooks observe recorded
-events; their failures don't fail the turn.
+### Materialize API-backed fixtures
 
-## Measure variants and regressions
+An input that only points at external data, such as a pull request URL,
+snapshot id, or pair of commit SHAs, is not self-contained. Fetch it
+once and commit the rendered fixture before you expand the suite.
 
-The `weather-tool-efficiency` A/B experiment assigns sessions by a sticky
-hash:
+1. Save the diff, metadata, and labels under `fixtures/` at pinned
+   revisions.
+2. Seed those files with `workspaceFiles`, or read them from the fixture
+   directory.
+3. Assert decisions and output shape against the saved evidence.
+4. Keep a small `smoke` subset for any remaining live pipeline checks.
 
-- `control` returns current conditions in Fahrenheit.
-- `treatment` adds a brief Celsius instruction and changes `get_weather` to
-  return Celsius fields.
+Read committed fixtures with `@cursor/july/evals/loaders`: `loadJson`,
+`loadJsonl`, and `loadYaml` resolve relative paths against the project
+root the runner discovered, not the cwd the CLI was invoked from
+(`resolveFixturePath` and `evalFixtureRoot` expose the same
+resolution for other file formats).
 
-Samples and aggregate snapshots persist under the project state
-directory. The treatment
-only changes current conditions; `get_forecast` still returns Fahrenheit.
-Treat the branch as an example of `ctx.session.abs`, not a complete unit
-policy.
+`maxConcurrency` limits parallel datapoints. It does not limit model or
+API fan-out inside one datapoint. Materialized fixtures prevent a large
+suite from exhausting provider and GitHub rate limits. The
+[evals skill](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/evals/SKILL.md) has the full fixture workflow.
 
-List and run the evals:
+## Keep improvements with regression evals
 
-```bash
-agent-sdk eval --dir examples/weather-agent --list
-agent-sdk eval --dir examples/weather-agent --json
-```
+Every [hillclimb](/docs/hillclimbing.md) round that keeps a change must land
+an eval that would have failed before the change. If you can't express
+the improvement as a gate (a `calledTool` shift, a bounded
+`action.result` count, an output-shape regex), the improvement is
+unverified, and it'll regress silently.
 
-The suite covers weather and forecast routing, the local converter, workspace
-notes, and the VM-side probe.
+The rule cuts the other way too: never weaken an existing gate to make a
+round pass. That's the freeze line moving, and it turns your regression
+suite into a list of checks that no longer protect anything.
 
-## Turn the weather tour into your own agent
+## Compare variants on live traffic
 
-Keep the shape and replace the domain:
+Use `defineAB` to compare variant metrics on live sessions. It is not a
+test runner and has no `agent-sdk ab` command. Keep `defineEval` as the
+regression ratchet. Eval sessions do not enroll or change live metrics.
+See [Live A/B metrics](/docs/ab.md) for assignment, behavior, collection,
+and inspection.
 
-- Swap Open-Meteo tools for your typed service clients.
-- Keep deterministic transforms behind direct server tools or MCP.
-- Use an agent tool only when code must run in the agent workspace.
-- Put reusable procedures in skills and narrow specialist work into
-  subagents.
-- Add a channel only when the external surface needs its own identity,
-  continuation key, or delivery behavior.
+## What's next
 
-## Where to go next
+Continue with these pages:
 
-- [Tools](/docs/reference/tools.md)
-- [MCP connections](/docs/reference/connections.md)
-- [Human-in-the-loop approvals](/docs/guides/human-in-the-loop.md)
-- [Slack](/docs/guides/slack.md)
-- [Schedules and reminders](/docs/reference/schedules.md)
-- [Evals](/docs/evals.md)
-- [Live A/B metrics](/docs/ab.md)
+- [Live A/B metrics](/docs/ab.md): sticky variants and cumulative metrics
+  on live sessions
+- [Hillclimbing](/docs/hillclimbing.md): the loop evals make trustworthy
+- [Building agents with agents](/docs/building-with-agents.md): have a
+  coding agent write the first suite
+- [GitHub guide](/docs/guides/github.md): deterministic webhook fixtures
+  with `github replay`
+- [Sessions and streaming](/docs/reference/sessions.md): the events
+  `t.events` contains
 
 ---
 
@@ -4143,8 +2066,8 @@ Peer MCP connections are ordinary MCP connections, so deterministic host code
 can use them too. A channel handler or server tool can call
 `host.mcp.callTool("weather", "ask", { message: "…" })` without any
 model turn deciding to. See
-[MCP connections](/docs/reference/connections.md#every-mcp-connection-is-available-in-three-places)
-for the three places every MCP connection is available.
+[MCP connections](/docs/reference/connections.md#every-model-visible-mcp-connection-is-available-in-three-places)
+for the three places every model-visible MCP connection is available.
 
 ## What's next
 
@@ -4223,6 +2146,7 @@ mapping shifts:
 | Agent tools (`execution: "agent"`) | scripts in the session workspace | catalog + script bodies on the first prompt |
 | `skills/*` | `.cursor/skills/` in the workspace | native discovery after the first turn, from the hosted store or the signed-in account |
 | `mcp-connections/*.ts` | SDK `mcpServers` | SDK `mcpServers` (peers need `--public-url`) |
+| `host-connections/*.ts` | `ctx.host.mcp` only | `ctx.host.mcp` only |
 | `sandbox/workspace/**` | seeded into the session workspace | ignored |
 | Tool approvals (`needsApproval`) | supported | not supported; keep approval-gated tools on local turns |
 
@@ -4354,7 +2278,7 @@ or run lifecycle scripts from an existing `package.json`.
 | Prompt model | Pins the model on `defineAgent` in `agent/agent.ts`. `git_config` and `agent_options` remain comments. |
 | Cron trigger | Creates `agent/schedules/<slug>.ts` with `defineSchedule` in UTC. |
 | GitHub trigger | Creates `agent/channels/github.ts`. It converts pull-request action, push branch, issue action, and user allowlist filters. |
-| Slack trigger | Creates `agent/channels/slack.ts`. Mention-only uses `cursorAccount`; watches, reactions, and channel-created triggers use Socket Mode. Watches add `engagement.channelPosts`. |
+| Slack trigger | Creates `agent/channels/slack.ts` as Socket Mode with `envPrefix` from the automation name (same names `slack create` writes). Watches add `engagement.channelPosts`. Run `agent-sdk slack create` for the bot. |
 | Linear, PagerDuty, Sentry, Teams, or generic webhook | Creates a boilerplate `agent/channels/<slug>.ts`. |
 | HTTP or SSE MCP server | Creates a name-based Cursor-account connection under `agent/mcp-connections/`. The project contains no server URL or credentials. |
 | Stdio MCP server | Writes `agent/mcp-connections/<slug>.todo.md`. |
@@ -4716,10 +2640,10 @@ A comment-only first wake has no head SHA, so the check waits for a
 PR or CI event. The banner still posts. A later turn on the same SHA
 creates a new check run; GitHub cannot reopen a completed run.
 
-Override `events` when the mapping is custom. [Approval Buddy](/docs/example-agents/approval-buddy.md)
-posts commit status from `turn.started` / `action.result` / `turn.failed`
-and stays never-red; that pattern still wins when you replace a default
-handler key. Handlers you author replace the matching defaults (same as
+Override `events` when the mapping is custom. A handler can post commit
+status from `turn.started` / `action.result` / `turn.failed` and stay
+never-red; that pattern still wins when you replace a default handler
+key. Handlers you author replace the matching defaults (same as
 `progress.reactions` composition today).
 
 ## Related
@@ -4885,10 +2809,8 @@ The companion skill is
   to that connection's resource URL
 - Upsert deployment secrets with `--store` so hosted engines seed the
   same tokens from env
-- Keep privileged servers off the model with `hostOnly: true` while
-  tools still call them through `ctx.host.mcp`. Do not set `hostOnly` on
-  connectors the playground or local chat should call. Use
-  `advertiseTools: true` for those.
+- Use `advertiseTools: true` when local turns should call the server by
+  name. Host tools can still call it through `ctx.host.mcp`.
 
 Prefer a Cursor account MCP connection when the connector already lives
 in the signed-in account dashboard:
@@ -4903,7 +2825,8 @@ and the host must hold tokens.
 
 ## How do I declare a host-OAuth connection?
 
-Add one file under `agent/mcp-connections/`. The filename is the
+Add one file under `agent/mcp-connections/` (model + host) or
+`agent/host-connections/` (host + `mcp oauth` only). The filename is the
 connection name you pass to the CLI and to `host.mcp`.
 
 ```ts
@@ -4913,17 +2836,14 @@ import { defineConnection } from "@cursor/july/connections";
 export default defineConnection({
   url: "https://mcp.example.com/inventory",
   oauth: true,
-  hostOnly: true,
-  description:
-    "Inventory MCP (privileged). Call only from host tools, not the model.",
+  description: "Inventory MCP.",
 });
 ```
 
 Rules of the road:
 
 - `oauth: true` is required for `agent-sdk mcp oauth`
-- `hostOnly: true` hides the server from the model; `ctx.host.mcp` and
-  channel handlers still see it
+- A file under `mcp-connections/` is visible to the model and to `ctx.host.mcp`. A file under `host-connections/` stays on the host.
 - Declare expected secret names on the agent when you plan to `--store`:
 
 ```ts
@@ -4956,8 +2876,7 @@ agent-sdk mcp oauth inventory
 
 What happens:
 
-1. The Agent SDK loads `agent/mcp-connections/inventory.ts` and checks
-   `oauth: true`
+1. The Agent SDK loads the connection file and checks `oauth: true`
 2. It opens the authorization URL in your browser
 3. The callback lands on `http://localhost:8787/callback`
 4. Tokens land in `mcp-auth.json` under the CLI config directory
@@ -4996,8 +2915,6 @@ on the pod.
 
 ## How do host tools call the server?
 
-Keep privileged calls on the host:
-
 ```ts
 const result = await ctx.host.mcp.callTool(
   "inventory",
@@ -5006,9 +2923,8 @@ const result = await ctx.host.mcp.callTool(
 );
 ```
 
-The model never sees `hostOnly` tools in its MCP namespace list. If the
-agent asks to "check IDE MCP" or run `mcp_auth`, point it at your host
-tool instead.
+The model can call the same server. Use a host tool when the write needs
+an allowlist or other deterministic gate.
 
 ## What if authorization fails?
 
@@ -5021,7 +2937,7 @@ tool instead.
 
 ## What's next
 
-- [MCP connections](/docs/reference/connections.md): transports, `hostOnly`, account MCP
+- [MCP connections](/docs/reference/connections.md): transports, account MCP
 - [CLI](/docs/reference/cli.md#mcp-oauth): full flag list for `mcp oauth`
 - [Deployment](/docs/deployment.md): secrets, egress, and hosted engines
 - [Fix common agent problems](/docs/troubleshooting.md): more symptom → fix tables
@@ -5246,10 +3162,10 @@ Source: /docs/guides/slack.md
 
 # Slack agents
 
-The Slack channel puts your agent in Slack. Two products: the Cursor-hosted
-connection (`cursorAccount: true`), or a dedicated Socket Mode app created
-in the dashboard wizard (`agent-sdk slack create`). To own the Slack app
-yourself, run `agent-sdk slack init --manual` and paste the manifests at
+The Slack channel puts your agent in Slack as its own Socket Mode bot.
+`agent-sdk slack create` opens the dashboard wizard and writes tokens
+to `.env.local`. To own the Slack app yourself, run
+`agent-sdk slack init --manual` and paste the manifests at
 [api.slack.com](https://api.slack.com/apps). Socket Mode has no
 public Request URL. Replies stream in threads, with tool "thinking" steps,
 suggested prompts, and opt-in approval buttons.
@@ -5288,41 +3204,12 @@ Missing tokens leave the channel idle (`channel idle … missing
 credentials`) rather than failing `serve`. That's useful when you mount
 many agents and only some have Slack apps.
 
-## Use the Cursor Slack connection
-
-If the Cursor Slack app is already installed in your workspace and linked
-to your Cursor account, skip the dedicated Slack app:
-
-```ts
-import { slackChannel } from "@cursor/july/channels/slack";
-
-export default slackChannel({
-  cursorAccount: true,
-  agentName: "Weatherbot", // single token — no spaces; defaults from mount slug (PascalCase)
-  agentIcon: { emoji: ":robot_face:" },
-});
-```
-
-Sign the host in (`agent-sdk login` or `CURSOR_API_KEY`), then mention the
-agent in Slack as `@Cursor Weatherbot …`. Thread replies and DMs keep going to
-the same agent. Messages appear as the Cursor app under that agent's name
-and icon. Slack shows its working status, then posts one final reply.
-
-Use a dedicated Socket Mode Slack app when you need your own bot user,
-channel watching (`engagement.channelPosts`), or approval buttons. On
-`cursorAccount`, agents must be explicitly addressed (@mention, DM, or
-claimed-thread reply). Channel watching and `toolApprovals` /
-`interactivity` are Socket Mode only; the Cursor connection does not relay
-Block Kit clicks. Agent names must be unique on the host; an unmatched
-`@Cursor <name>` stays on Cursor's normal Slack agent.
-
 ## Control who can message the agent
 
 External senders are blocked by default. Slack Connect users, guests, and
 people whose home workspace is not the install team never reach the
-handler. That applies to Socket Mode and `cursorAccount: true`. Set
-`blockExternals: false` only when the agent should serve people outside
-your org:
+handler. Set `blockExternals: false` only when the agent should serve
+people outside your org:
 
 ```ts
 export default slackChannel({
@@ -5485,8 +3372,7 @@ export default slackChannel({
 ```
 
 Channel watching needs the `message.channels` / `message.groups` events
-on the Slack app (Socket Mode only; not available with
-`cursorAccount: true`). Pass `--channel-posts` on `slack create` or
+on the Slack app. Pass `--channel-posts` on `slack create` or
 `slack init --manual`. The bot must also be a member of each watched
 channel.
 
@@ -5496,9 +3382,7 @@ Set `includeBotPosts: true` when the posts worth watching come from bots:
 alert feeds, webhook integrations, or other agents posting notes. The
 watching app's own posts stay dropped either way, matched by the `bot_id`
 and bot user id from `auth.test`, so an agent can never dispatch on its
-own replies. The
-[alert investigator example](/docs/example-agents/oncall.md) watches a
-bot-fed alerts channel this way.
+own replies. Use this for a bot-fed alerts channel.
 
 ## Prepare work on the host
 
@@ -5527,11 +3411,6 @@ Approval cards need interactivity on the Slack app. Recreate with
 `buildToolApprovalEvents({ credentials })` into `events` and set
 `interactivity: true` on the channel so Socket Mode routes the clicks.
 
-Approval buttons need Socket Mode. `slackChannel({ cursorAccount: true })`
-rejects `toolApprovals` and `interactivity` at construction, since the
-Cursor Slack connection does not relay Block Kit clicks. Use a dedicated
-Slack app to run approvals for a cursor-account agent.
-
 Cards show redacted, truncated arguments (Block Kit size limits);
 execution still uses the full validated input, so review sensitive tools
 in the playground when the arguments may exceed the card. Approvals
@@ -5563,7 +3442,7 @@ Two habits matter most.
 The `slack` subcommands cover setup end to end.
 
 ```bash
-agent-sdk slack setup                     # two-product chooser plus manual phases
+agent-sdk slack setup                     # printed setup guide
 agent-sdk slack create --dir .            # dashboard wizard (dev app)
 agent-sdk slack create --dir . --prod     # prod app
 agent-sdk slack destroy --dir .           # delete the provisioned app
@@ -6178,7 +4057,6 @@ npx @cursor/july docs
 | New to the Agent SDK | [Quickstart](/docs/quickstart.md) (PR reviewer), then [Concepts](/docs/concepts.md) |
 | Building a new agent with Cursor | [Scaffold an agent with Cursor](/docs/scaffolding-agents.md) |
 | Turning a Cursor Automation into a project | [Convert a Cursor Automation](/docs/guides/convert-automation.md) |
-| Learning from working agents | [Example agents](/docs/example-agents/index.md) |
 | Wiring an agent to Slack | [Slack guide](/docs/guides/slack.md) |
 | Starting from a packaged template | [Demo](/docs/templates/demo.md), [Security reviewer](/docs/templates/security-reviewer.md), [Triage](/docs/templates/triage.md), or [Agentic Owners](/docs/templates/agentic-owners.md) |
 | Wiring an agent to GitHub webhooks | [GitHub guide](/docs/guides/github.md) |
@@ -6246,33 +4124,6 @@ npx @cursor/july docs
 - [OpenTelemetry](/docs/guides/opentelemetry.md): push session, turn, and
   tool traces to an OTLP collector you run.
 
-**Example agents**
-
-- [Choose the right example](/docs/example-agents/index.md): compare the
-  example agents by runtime, channels, tools, and state.
-- [Weather agent](/docs/example-agents/weather-agent.md): explore tools, MCP,
-  approvals, skills, subagents, schedules, hooks, A/B metrics, and evals.
-- [Slack agent](/docs/example-agents/slack-agent.md): put a minimal agent in
-  Slack through an account-linked transport.
-- [Concierge](/docs/example-agents/concierge.md): delegate work to a peer agent
-  with its own context and sessions.
-- [Playbook router](/docs/example-agents/benny.md): route Slack intake through inherited
-  repository playbooks.
-- [Alert investigator](/docs/example-agents/oncall.md): watch a Slack alerts
-  channel and pin a self-rechecking investigation to every alert thread.
-- [PR evidence reviewer](/docs/example-agents/bugbot.md): review a host-prepared,
-  diff-first pull-request evidence tree.
-- [Approval Buddy](/docs/example-agents/approval-buddy.md): keep approval policy
-  in code while subagents supply review findings.
-- [Security Reviewer](/docs/example-agents/security-reviewer.md): run a staged,
-  parallel security pipeline with live playground progress.
-- [Knowledge base](/docs/example-agents/knowledge-base.md): turn conversations
-  about people, systems, decisions, and preferences into shared markdown.
-- [Codebase wiki](/docs/example-agents/codebase-wiki.md): ingest merged PRs into
-  per-feature pages with a daily digest schedule.
-- [Codeowners review](/docs/example-agents/codeowners-review.md): route PR
-  reviews by ownership to per-area playbooks and aggregate verdicts.
-
 **Operating**
 
 - [Deployment](/docs/deployment.md): Cursor-managed hosting, self-hosting,
@@ -6676,9 +4527,8 @@ See [GitHub](/docs/guides/github.md) for local event delivery and
 
 ## Where to go next
 
-- [`examples/approval-buddy`](https://github.com/cursor/cursor/tree/main/packages/agent-serve/examples/approval-buddy/): an example
-  with commit statuses, review subagents, and a deterministic stamp
-  policy
+- [PR autofixer template](/docs/templates/pr-autofixer.md): drive a PR on a
+  Cursor cloud VM
 - [Evals](/docs/evals.md): freeze these two PRs as regression checks so
   prompt changes can't flip a verdict
 - [Tools](/docs/reference/tools.md): more on typed tools, approvals, and
@@ -8062,7 +5912,8 @@ command prints a note when you pass it anyway.
 agent-sdk mcp oauth <connection> [--dir .] [--store] [--slug <slug>] [--team <id>]
 ```
 
-`<connection>` is the `agent/mcp-connections/<connection>.ts` basename.
+`<connection>` is the basename under `agent/mcp-connections/` or
+`agent/host-connections/`.
 `--slug` defaults to the `--dir` basename. `--team` defaults to the
 signed-in account's team. You need `agent-sdk login` (or `--api-key`)
 before `--store`.
@@ -8275,6 +6126,11 @@ from `@cursor/july/connections`, and the transport comes in
 four shapes: remote HTTP, local stdio, the signed-in Cursor account's
 connectors, and peer agents on the same host.
 
+Put a server in `agent/host-connections/` when host tools should call it
+and the model should not. Same `defineConnection` shape. `agent-sdk mcp
+oauth` still works. The playground and the turn's MCP servers never see
+those files.
+
 ## Remote MCP server
 
 Point an MCP connection at a remote server with a URL.
@@ -8311,12 +6167,10 @@ agent-sdk mcp oauth inventory --store   # also upsert deployment secrets
 Full walkthrough: [Host MCP OAuth](/docs/guides/mcp-oauth.md). Companion
 skill: [`skills/mcp-auth/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md).
 
-Set `hostOnly: true` only when host tools should call the server and the
-model should not. Playground chat will not see those tools. Account MCP
-(`cursorAccount: true`) is the right choice for connectors already linked
-in the Cursor dashboard. Omit `servers` (or pass `"*"`) to forward every
-connected connector. If the model should call those tools by name on
-local turns, set `advertiseTools: true`.
+Account MCP (`cursorAccount: true`) is the right choice for connectors
+already linked in the Cursor dashboard. Omit `servers` (or pass `"*"`)
+to forward every connected connector. If the model should call those
+tools by name on local turns, set `advertiseTools: true`.
 
 ## Per-session auth (`auth`)
 
@@ -8376,7 +6230,7 @@ export default defineConnection({
 
 A listing failure, invalid tool name, or name collision fails the turn.
 Advertised tools follow the same runtime support as server tools. They cannot
-be combined with `hostOnly` or called through the direct tool API.
+be called through the direct tool API.
 
 In a dry-run session, MCP tools marked read-only run normally. Tools marked
 as writes are stubbed. Tools without effect annotations are unavailable.
@@ -8484,13 +6338,14 @@ Unknown slugs and self-references fail `serve` at startup. Resolution
 (loopback versus `--public-url`), loop caveats, and the delegation model
 are in the [Agent-to-agent guide](/docs/guides/agent-to-agent.md).
 
-## Every MCP connection is available in three places
+## Every model-visible MCP connection is available in three places
 
-One authored MCP connection serves three consumers.
+A file under `agent/mcp-connections/` serves three consumers. Host
+connections skip the first one.
 
 1. **Cursor agent:** Attached connections ride SDK `mcpServers` behind
    harness MCP meta-tools. Set `advertiseTools: true` so local turns see
-   named tools. `hostOnly` keeps the connection off the model.
+   named tools.
 2. **Server tools:** Deterministic host code composes MCP calls
    through `ctx.host.mcp`:
 
@@ -8525,7 +6380,7 @@ lazily on first use.
 
 Continue with these pages:
 
-- [Host MCP OAuth](/docs/guides/mcp-oauth.md): `mcp oauth`, `--store`, `hostOnly`
+- [Host MCP OAuth](/docs/guides/mcp-oauth.md): `mcp oauth`, `--store`
 - [Agent-to-agent](/docs/guides/agent-to-agent.md): peers in depth
 - [Tools](/docs/reference/tools.md): authored tools that wrap MCP connections
 - [Webhooks](/docs/guides/webhooks.md): calling MCP connections from handlers
@@ -8602,9 +6457,8 @@ For GitHub merge-box checks and sticky PR banners, use
 `githubChannel({ progress: { commitStatus, banner } })` from
 `@cursor/july/channels/github`. That is the supported Autofix-style
 path. See [GitHub: Show PR progress](/docs/guides/github.md#show-pr-progress).
-Override channel `events` only when the lifecycle is custom (for
-example [Approval Buddy](/docs/example-agents/approval-buddy.md)'s
-never-red status from tool output). Do not use `defineHook` for those
+Override channel `events` only when the lifecycle is custom, such as
+never-red status from tool output. Do not use `defineHook` for those
 writes.
 
 ## Patterns
@@ -8772,6 +6626,12 @@ while a turn runs). Agent-execution tools are rejected with `400`, and
 unknown tools with `404` and the list of available names. For the
 semantics, see [Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn).
 
+An optional `"continuationToken"` (`<channelId>:<key>`, as
+`/v1/sessions` lists it; mutually exclusive with `sessionId`) addresses
+the session by continuation token instead; malformed tokens are
+rejected with `400 invalid_continuation_token`. For the semantics, see
+[Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn).
+
 ## Discovery
 
 These read-only routes describe the running agent.
@@ -8779,6 +6639,8 @@ These read-only routes describe the running agent.
 | Route                  | What it does                                                                                                                                                                             |
 | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `GET /v1/info`         | The discovered surface: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, A/B experiments, diagnostics |
+| `GET /v1/tools`        | The live tool catalog: authored server tools plus advertised MCP passthroughs under model-facing names, as light `{ name, title?, source? }` entries. `session` / `continuationToken` query parameters bind the listing to a session identity (advertised inventories can be tenant-scoped); a connection whose listing fails is skipped and reported in `connectionErrors` |
+| `GET /v1/tools/:name`  | One catalog tool's full description: description, execution, `needsApproval`, `effect`, input and output schemas, source connection. Same session binding as the listing; unknown names get `404` with the available names |
 | `GET /v1/health`       | Per-agent liveness, no auth                                                                                                                                                              |
 | `GET /v1/logs?after=N` | Recent server log lines, with a polling cursor                                                                                                                                           |
 | `GET /v1/abs`          | [Live A/B metrics](/docs/ab.md): per-session assignments and aggregate arm totals                                                                                                           |
@@ -9044,7 +6906,8 @@ experiments can override their file-derived name.
 | Path | Resolves to |
 | --- | --- |
 | `agent/tools/approve_pr.ts` | tool `approve_pr` |
-| `agent/mcp-connections/linear.ts` | MCP connection `linear` |
+| `agent/mcp-connections/linear.ts` | MCP connection `linear` (model + host) |
+| `agent/host-connections/anytool.ts` | Host MCP connection `anytool` (host + `mcp oauth` only) |
 | `agent/skills/pr-review.md` | skill `pr-review` |
 | `agent/subagents/reviewer/` | subagent `reviewer` |
 | `agent/channels/drive.ts` | channel `drive`, routes under `/v1/channels/drive` |
@@ -9072,6 +6935,8 @@ my-agent/
 │   │   └── pr-review.md       # on-demand procedures (SKILL.md convention)
 │   ├── mcp-connections/
 │   │   └── linear.ts          # tools from external MCP servers
+│   ├── host-connections/
+│   │   └── anytool.ts         # privileged MCP, host tools only
 │   └── channels/
 │       └── github.ts          # messages and external events
 └── evals/
@@ -9093,6 +6958,7 @@ Each path maps to a capability and a reference page.
 | `agent/tools/<name>.ts` | One typed tool; filename = tool name. `execution: "server"` (in-process, default) or `"agent"` (a script that runs where the agent runs) | [Tools](/docs/reference/tools.md) |
 | `agent/skills/*` | SKILL.md-convention procedures, loaded on demand | [Skills](/docs/reference/skills.md) |
 | `agent/mcp-connections/<name>.ts` | MCP servers, available to the model, to server tools (`ctx.host.mcp`), and to channel/schedule handlers (`args.host.mcp`) | [MCP connections](/docs/reference/connections.md) |
+| `agent/host-connections/<name>.ts` | Privileged MCP servers for `ctx.host.mcp` and `mcp oauth`. The model never sees them. | [MCP connections](/docs/reference/connections.md) |
 | `agent/subagents/<id>/` | Child agent directory; `description` required | [Subagents](/docs/reference/subagents.md) |
 | `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` and `github.ts` use the platform packs | [Channels](/docs/reference/channels.md) |
 | `agent/hooks/*.ts` | Observe-only event subscribers, never fatal | [Hooks](/docs/reference/hooks.md) |
@@ -9698,8 +7564,8 @@ different one.
 Subagents inherit the parent's execution surface. Every per-subagent
 capability directory is reported as a warning and ignored: `tools/`,
 `skills/`, `mcp-connections/` (and the legacy `connections/` alias),
-`channels/`, `schedules/`, `hooks/`, `sandbox/`, and nested
-`subagents/`.
+`host-connections/`, `channels/`, `schedules/`, `hooks/`, `sandbox/`,
+and nested `subagents/`.
 
 Delegation needs both halves: the description makes it possible, and the
 parent's [instructions](/docs/reference/instructions.md) make it happen. "When a
@@ -9920,8 +7786,9 @@ passthrough server tools from the connection's live `listTools` on every
 local turn. See
 [MCP Connections](/docs/reference/connections.md#advertise-tools).
 Advertised tools ride the same execution path as authored server tools,
-but cannot be invoked via
-[direct tool calls](#call-a-tool-without-a-model-turn).
+and [direct tool calls](#call-a-tool-without-a-model-turn) address them
+by the same model-facing names: the call's session identity resolves the
+advertised listing when the authored lookup misses.
 
 ## Gate a tool on human approval
 
@@ -9995,7 +7862,22 @@ when the call returns. Pass a `sessionId` (a body field over
 HTTP, `--session` on the CLI, `options.sessionId` programmatically) to
 run inside an existing session instead: the tool sees that session's
 workspace, and the call is recorded on the session's event stream.
-Session-bound calls return `409 session_busy` while a turn runs.
+Session-bound calls return `409 session_busy` while a turn runs. When the
+session's harness cwd cannot be materialized, a read-effect call runs
+in a scratch workspace instead and the outcome carries
+`scratchWorkspace: true`; a write-effect call fails with
+`workspace_unavailable`.
+
+A session can also be addressed by its continuation token: an optional
+`continuationToken` (`<channelId>:<key>`, as `/v1/sessions` lists it;
+mutually exclusive with `sessionId`). A token that maps to a live
+session behaves exactly like passing that session's id — same ownership
+check, same `409 session_busy`, same event recording. A token with no
+session behind it runs the call scratch-bound with the token's channel
+id and continuation key as the call's session identity, so a deployment
+whose tools resolve state from the continuation key can serve it with
+no live session. Malformed tokens are rejected with
+`400 invalid_continuation_token`.
 
 The error semantics match the model path. Unknown tools are rejected
 with the available names, agent-execution tools cannot be called on the
@@ -10630,9 +8512,10 @@ fixture replay.
 
 ## Slack
 
-`agent/channels/slack.ts` uses your signed-in Cursor account. Mention
-the agent or DM it with a PR URL. Same `drive_pr` path as the
-playground. See [Slack](/docs/guides/slack.md).
+`agent/channels/slack.ts` is a dedicated Socket Mode bot
+(`PR_AUTOFIXER_SLACK_*`). Mint it with `agent-sdk slack create`, then
+mention the bot or DM it with a PR URL.
+Same `drive_pr` path as the playground. See [Slack](/docs/guides/slack.md).
 
 ## Evals
 
@@ -10669,9 +8552,8 @@ This agent reads a pull request diff and posts one review comment. It
 reports exploitable bugs: injection, authz bypass, secret leaks, SSRF,
 RCE. Style nits stay out.
 
-The factory [Security Reviewer](/docs/example-agents/security-reviewer.md)
-runs a staged pipeline with parallel workers. This template is one
-model turn.
+The in-repo factory Security Reviewer runs a staged pipeline with
+parallel workers. This template is one model turn.
 
 ## Scaffold
 
@@ -10884,7 +8766,7 @@ not on `PATH`, use `npx @cursor/july`.
 | Built-in file reads and greps fail; the turn retries for a long time | Run under Node 22.13+ (or `tsx`), never Bun. Look for `NGHTTP2_FRAME_SIZE_ERROR` in logs. |
 | The turn fails immediately with an API-key error | Sign in with `agent-sdk login`, or set `CURSOR_API_KEY`. Discovery, `info`, `call`, and serve bring-up work without a key; model turns need one. |
 | Replies quote rules or `AGENTS.md` from outside your agent project | The session workspace inherited parent-folder config. Nested git checkouts default `local.cwd` to a per-project cache directory under `~/.cache`. Point `defineAgent({ local: { cwd } })` at a checkout only when the agent should inherit that tree, or set `--state-root` to a clean directory (for example under `/tmp`). |
-| Yellow box shows Datadog/Linear tools, but the model lists `GetDynamicTools` / IDE `cursor` tools and never calls them | Attached MCP sits behind harness meta-tools, or `hostOnly` hid the connection, or the harness cwd is still inside another checkout. Set `advertiseTools: true` for named tools on local turns. Check `GET /v1/info` `local.cwd` and `connections[].advertiseTools`. |
+| Yellow box shows Datadog/Linear tools, but the model lists `GetDynamicTools` / IDE `cursor` tools and never calls them | Attached MCP sits behind harness meta-tools, or the harness cwd is still inside another checkout. Set `advertiseTools: true` for named tools on local turns. Check `GET /v1/info` `local.cwd` and `connections[].advertiseTools`. |
 | Server tools, skills, or workspace seed files never appear | Server tools and sandbox seeds apply on the local runtime (cloud server tools need `--public-url` / `--cloud-tools-url`). Skills reach cloud through the Agent Store when hosting or a personal `CURSOR_API_KEY` is available; otherwise only skills already in the cloud repo. `validate` warns when this combination is present. |
 | `validate` and `run` succeed, but typecheck fails in CI | The CLI runs TypeScript with type-stripping only. Keep tool `execute` return types as object literals or `type` aliases, not `interface` types. |
 | Login works, but turns are rejected when using custom API hosts | Point login and model traffic at the same host (`CURSOR_API_BASE_URL` and `CURSOR_BACKEND_URL`). A key from one host is rejected by the other. |
@@ -10923,7 +8805,7 @@ not on `PATH`, use `npx @cursor/july`.
 | --- | --- |
 | `must be defineConnection({ url, oauth: true })` | The connection file needs `oauth: true`, or you passed the wrong connection name to `agent-sdk mcp oauth`. |
 | Local auth works; hosted calls unauthorized | Run `agent-sdk mcp oauth <name> --store`, confirm names with `agent-sdk secrets list <slug>`, then redeploy. |
-| Model asks for `mcp_auth` or IDE MCP for a privileged server | That connection is `hostOnly`. Call it from a host tool via `ctx.host.mcp`, and update instructions. |
+| Model asks for `mcp_auth` or IDE MCP for a connector it already has | Attached MCP is behind meta-tools. Set `advertiseTools: true` for named tools on local turns, or call it from a host tool via `ctx.host.mcp`. |
 
 See [Host MCP OAuth](/docs/guides/mcp-oauth.md) and
 [`skills/mcp-auth/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md).