@cursor/july 0.1.102 → 0.1.104

package/dist/docs/llms-full.txt

@@ -506,6 +506,7 @@ name. For example, `agent/tools/get_weather.ts` creates a tool named
 | `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 |
+| `agent/result.ts` | Optional host `commit` on the final assistant text |
 | `evals/**/*.eval.ts` | Repeatable checks at the project root |
 
 Other folders add subagents, extensions, hooks, schedules, and workspace
@@ -581,7 +582,7 @@ Choose a runtime in `agent/agent.ts`:
 | Approvals (`needsApproval`) | Supported | Not supported (local runtime only) |
 | Agent tool scripts | Supported | Supported |
 | Skills | Added to the session workspace | Available automatically |
-| Seeded files | Added to the session workspace | Ignored |
+| Seeded files | Added to the session workspace | Available in a shared directory the first prompt names |
 | Repository | You provide it | The cloud agent checks it out |
 
 Use the local runtime when the host has the tools and files the agent
@@ -589,8 +590,6 @@ needs. Use the cloud runtime when each turn needs an isolated repository
 checkout. `agent-sdk validate` warns when a cloud agent uses a
 local-only capability.
 
-See [Cloud runtime](/docs/guides/cloud-runtime.md) for setup and trade-offs.
-
 ## What files can a local session access?
 
 Each local session gets its own workspace. The Agent SDK writes the
@@ -638,7 +637,6 @@ See [Agent-to-agent](/docs/guides/agent-to-agent.md) for a complete example.
 - [Sessions and streaming](/docs/reference/sessions.md)
 - [Channels](/docs/reference/channels.md)
 - [Live A/B metrics](/docs/ab.md)
-- [Cloud runtime](/docs/guides/cloud-runtime.md)
 
 ---
 
@@ -1091,6 +1089,387 @@ Continue with these pages:
 
 ---
 
+Source: /docs/design/filesystem.md
+
+# One FileSystem for every Agent SDK agent
+
+> **Status:** first implementation, this PR. `@cursor/july` only.
+> No Cursor SDK change.
+> **Audience:** Agent SDK maintainers.
+
+Every local turn binds a **FileSystem** and synthesizes native file
+tools from it. There is no "is there an override?" branch on the
+tool path. Authors pick the tree with `root`. Omit `root` and the
+tree is the host disk, through internal `localFileSystem`.
+
+```ts
+// Host disk. Relative paths resolve against the harness cwd.
+export default defineAgent({
+  name: "reviewer",
+});
+
+// Override. The model sees only this tree. Paths are posix `/`.
+export default defineAgent({
+  name: "notes",
+  root: tempFs({ "/notes.md": "hello" }),
+});
+```
+
+---
+
+## Names
+
+| Name | Kind | Meaning |
+| --- | --- | --- |
+| `FileSystem` | Type on `@cursor/july` | Path verbs. Authors provide this. |
+| `root` | Field on `defineAgent` | The FileSystem the agent runs on. Omit it and the root is the host disk. |
+
+No `root()` method and no public `Workspace` type.
+`local.workspaceDir` stays the harness cwd. `workspaceFiles` stays
+per-send seed files. Those names are not the path namespace.
+
+Do not pass `local.root` into `Agent.create`. The published SDK
+does not have that field.
+
+---
+
+## FileSystem
+
+```ts
+interface FileSystem {
+  list(prefix?: string): AsyncIterable<DirEntry>;
+  stat(path: string): Promise<FileInfo>;
+  glob(pattern: string, dir?: string): AsyncIterable<DirEntry>;
+  read(path: string): Promise<string | Uint8Array>;
+  grep(query: GrepQuery): AsyncIterable<GrepResult>;
+  write(path: string, contents: string): Promise<void>;
+  delete(path: string): Promise<void>;
+  search(query: SearchQuery): AsyncIterable<SearchResult>;
+}
+```
+
+Every method is required. A tree without an index yields nothing
+from `search`. Methods do not fall back to the host tree.
+Diagnostics are not a FileSystem verb.
+
+Path verbs take a path (and contents for `write`). Bags with two
+or more independent options (`grep`, `search`) take a
+named query object.
+
+`read` returns text as a string, or image bytes as a
+`Uint8Array` (`jpeg` / `png` / `gif` / `webp`). Native Read
+applies `offset` / `limit` and numbers lines on text. Images
+become a base64 image content part, the same shape the Cursor
+harness sends the model.
+
+FileSystem methods throw; they do not return a status envelope.
+`@cursor/july` does not export `FileSystemResult`.
+
+### Paths
+
+Authored `root` (`tempFs`, `unionFs`, `overlayFs`, `hostFs`, a custom tree) is one posix
+namespace rooted at `/`. Query paths and yielded paths are
+absolute (`/src/a.ts`). No trailing slash except `/`. `""`, `"/"`,
+and an omitted optional scope mean the root. Prefix tests are
+path-segment: `/agent` matches `/agent/skills`, not
+`/agent-tools`. `normalizeFsPath` resolves `..`. `/tmp` is
+reserved for turn-local scratch. See `/tmp` scratch.
+
+Host-default `localFileSystem` follows Cursor SDK natives:
+relative paths resolve against the harness cwd; absolute paths
+are used as-is. Yielded paths are host paths, not rewritten to
+`/`. `search` is empty (no host index).
+
+### Iterators
+
+Async iterators are already sorted. `unionFs` k-way merges them
+and does not re-sort a source.
+
+- `list` / `glob`: lexicographic by `path`. Paths are unique.
+- `grep`: by `path`, then `lineNumber` ascending. Keep every hit.
+- `search`: by `score` descending, then `path` ascending.
+
+A file is not under itself, so listing a file path is empty.
+Empty `list` is not "missing"; `stat` answers that.
+
+`glob(pattern, dir?)` matches relative to `dir`, not
+basename-anywhere (`*.ts` under `/src` is `/src/a.ts`, not
+`/src/nested/c.ts`).
+
+`grep` has no `output_mode` or `offset`. A slash-free `glob`
+(`*.ts`) matches the basename at any depth under `path`.
+`grep` / `search` take optional `maxResults` as predicate
+pushdown; implementations should stop after that many hits.
+Composers push the same cap to children and apply it again
+after the merge.
+
+Native-tool pagination (`head_limit`, `offset`, `output_mode`,
+`numResults`) stays on synthesized tools. Native `LS` is built
+from `list` + `stat`; there is no `ls` method.
+
+### Errors
+
+FileSystem methods throw `PathError`. `path` is the absolute
+posix path the error is about. Messages stay these contract
+strings so synthesized tools can show them as-is.
+
+- `list` / `stat` / `glob` must not throw for a missing path.
+  Missing is an empty iterator or `{ kind: "missing" }`.
+- `read` / `delete` missing file: `FileNotFoundError`
+  (`not found: ${path}`).
+- `write` has no `not found`. I/O uses the OS message or
+  `WriteFailedError` (`write failed: ${path}`). A read-only
+  mount uses `ReadOnlyMountError` (`read-only mount: ${path}`).
+- Synthesized StrReplace is `read` + exact replace + `write`.
+  Uniqueness failures throw `EditError` (`oldText is empty`,
+  `oldText and newText are exactly the same`, `The string to
+  replace was not found in the file`, and `The string to replace
+  was found multiple times in the file. Use replace_all to replace
+  all occurrences, or include more context to only edit one
+  occurrence.`). Write-back failures are `WriteFailedError`.
+- `grep` throws `InvalidGrepPatternError`
+  (`invalid grep pattern: ${pattern}`). A missing host search
+  root throws. A missing virtual path yields nothing.
+- `search` without an index is empty success.
+- `unionFs` with no mount throws `NoMountError`
+  (`no mount for path: ${path}`) on `read` / `write` /
+  `delete`. Walk verbs stay empty or missing.
+- `unionFs` catches `PathError` from a child and rethrows
+  `error.withPath(mountPrefix + childPath)`. Untyped `Error` still
+  gets a best-effort message rewrite.
+
+Invoke wraps FileSystem throws into the executor success / error
+envelope.
+
+### Write and StrReplace
+
+`write(path, contents)` creates or overwrites a file. Success is
+empty. Native Write maps `fileText` onto `contents` and prints
+`Wrote contents to ${path}`.
+
+StrReplace is not a FileSystem verb. The synthesized tool reads
+the file, applies an exact non-overlapping replace, and writes
+the result. It fails when `oldText` is empty, equals `newText`,
+is missing, or occurs more than once without `replaceAll`.
+Success is `{ occurrencesModified }`. Splice is literal; do not
+use `String.prototype.replace`. Native aliases (`old_string`,
+`new_string`, `replace_all`) map onto those fields at invoke
+time.
+
+---
+
+## Helpers
+
+| Helper | Role |
+| --- | --- |
+| `emptyFs()` | No files. Overlay leaf or missing catalog. Reads miss; writes are read-only. |
+| `tempFs(files)` | In-memory snapshot. Tests and fixtures. |
+| `unionFs({ "/repo": a, "/plans": b })` | Longest-prefix compose, path-segment match. Children are FileSystems rooted at `/`; `unionFs` strips the mount prefix on the way in and re-prefixes yields. List and glob use `unique` so an earlier mount shadows a later one. Grep and search keep every hit. Grep and search at `/` fan out to every child. |
+| `overlayFs([upper, lower])` | Same-root overlay. Earlier layers win. Read-only. A downed layer costs its own files, not the overlay — `stat` / `grep` / `search` only fail when no layer served. |
+| `hostFs(files, scope)` | `HostFilesApi` as a FileSystem rooted at `/`. Mount with `unionFs({ "/host": hostFs(files, scope) })`. `search` is empty (no index). Write without a cached etag is unconditional; after a successful read or write, write is CAS on that etag. |
+
+`localFileSystem({ cwd })` is the host-default handle. It is not
+exported from `@cursor/july`. Name helpers and `mergeSorted`
+stay private. `emptyFs`, `tempFs`, `unionFs`, `overlayFs`, `hostFs`, and
+the `PathError` classes (`FileNotFoundError`,
+`ReadOnlyMountError`, `NoMountError`, `InvalidGrepPatternError`,
+`WriteFailedError`, `EditError`,
+`DeleteNotSupportedError`) are the public helpers.
+
+---
+
+## Tool synthesis
+
+Local turns synthesize these natives from the bound FileSystem:
+`Read`, `LS`, `Grep`, `Glob`, `Write`, `StrReplace`, `Delete`,
+`SemanticSearch`. `list` + `stat` synthesize `LS`. `search`
+synthesizes `SemanticSearch`. `StrReplace` is `read` + exact
+replace + `write`. Other execute bodies call the matching
+FileSystem method.
+
+Authored `tools` can filter that set. `tools: ["read", "shell"]`
+on a host-default agent synthesizes `Read` only.
+`tools: ["edit"]` synthesizes `Write` and `StrReplace`.
+`tools: ["semSearch"]` synthesizes `SemanticSearch`.
+`tools: []` synthesizes nothing.
+
+Host-default does not synthesize `SemanticSearch`. Native
+`semSearch` stays on so the host index can run;
+`localFileSystem.search` is empty. Authored `root` synthesizes
+`SemanticSearch` from `FileSystem.search` and does not advertise
+native `semSearch`. `search` is not an allowlist alias, so an
+authored `search` tool is not treated as SemanticSearch.
+`ReadLints` is not a FileSystem verb. Authored
+`tools: ["readLints"]` fails closed so the host language service
+cannot run.
+
+Do not also ship `agent/tools/Read.ts` (and the other synthesized
+names). Discovery fails closed on that clash for host-default and
+authored `root`.
+
+A factory root re-resolves the handle before a turn. The session
+cache is the handle, not a tree snapshot. Unscoped `callTool`
+uses the invocation id and does not cache, so factories cannot
+share one tree across callers. A static `root` is the authored
+object on every session — Write / StrReplace / Delete /
+`workspaceFiles` are shared. Return a new handle from
+`(ctx) => …` when a session should have its own tree. A factory
+that returns the same object still shares.
+
+Per-send `workspaceFiles` write through the FileSystem.
+`memory/` is reserved (same as the host-default workspace
+symlink into durable agent memory) and is refused after
+normalize, including `./memory/x` and `foo/../memory/x`.
+Host-default `list` / `glob` / `grep` do not follow directory
+symlinks, including `memory/` — same as native LS/Glob/Grep.
+Exact-path `read` / `stat` still follow.
+
+Authored `root` skips session-directory materialize, git init,
+and host-cwd checks. First turns prepend `buildAgentsMdContent`
+and print `Workspace Path: /`. Host-default agents keep today's
+materialize path.
+
+---
+
+## Allowlist
+
+| `root` | `tools` | Model-facing harness |
+| --- | --- | --- |
+| omitted | omitted | The seven host-disk file tools (no synthesized `SemanticSearch`). Host shell / webSearch / sandbox / native `semSearch` stay. Host file natives are hidden with `disallowedTools: ["read","ls","grep","glob","edit","delete"]`. |
+| omitted | `["read", "shell"]` | Synthesized `Read` + SDK `shell` + `mcp`. |
+| omitted | `[]` | No synthesized file tools. |
+| set | omitted | All eight synthesized file tools (including `SemanticSearch`) + webSearch + webFetch + updateTodos + readTodos + `mcp`. Bind `/tmp` scratch. Not the host-default full catalog (no shell / sandbox / task / native semSearch). |
+| set | `["updateTodos"]` | All eight synthesized file tools + `updateTodos` + `mcp`. |
+| set | `["semSearch"]` | Synthesized `SemanticSearch` + `mcp`. Native host index stays off. |
+| set | `[]` | No synthesized file tools. Legal and empty. |
+| set | `["shell"]` / `["task"]` / `["readLints"]` | Fail closed. |
+| set | `["webSearch"]` / `["webFetch"]` | All eight synthesized file tools + the listed web tool + `mcp`. Bind `/tmp` scratch. |
+
+`mcp` is granted when any tools ride that path. File-family
+allowlist names are omitted from the SDK allowlist; the
+synthesized tools replace them.
+
+`local.sandbox` is Cursor's process sandbox around child
+processes on the host-default path. It is not a FileSystem.
+
+---
+
+## Fail closed
+
+| Combination | Result |
+| --- | --- |
+| `root` + `local.cwd` / `workspaceDir` / `sandbox` | Fail closed |
+| `root` + `runtime: "cloud"` or `"grokbot"` | Fail closed |
+| `root` + `tools` containing `"shell"` | Fail closed |
+| `root` + `tools` containing `"task"` | Fail closed. A child keeps the host toolset. Sharing `root` needs a Cursor SDK inherit, not an overridden Task. |
+| `root` + `tools` containing `"readLints"` | Fail closed. Diagnostics are not a FileSystem verb. |
+| `agent/tools/Read.ts` (etc.) | Fail closed on host-default and authored `root`. |
+
+---
+
+## `/tmp` scratch for webSearch and webFetch
+
+Native `WebSearch` and `WebFetch` stay native. They still scratch
+large output to `{harnessCwd}/agent-tools/{uuid}.txt` on the host
+disk. Under `root`, the turn composes
+`unionFs({ "/": authored, "/tmp": tempFs() })`, copies only the file
+the native tool wrote this turn, and drops that composed root at
+end of turn.
+
+### Why `/tmp`
+
+The FileSystem is the model's disk. Host `{cwd}/agent-tools/` is a
+harness path. Under `root`, the model never sees it.
+
+`/tmp` is the reserved scratch prefix. An authored `/tmp` is
+shadowed. Do not put durable files there. `{cwd}/agent-tools/` and
+`/tmp` are different namespaces.
+
+`/agent-tools` is not reserved. Prefix `/agent` does not cover
+`/agent-tools`. Those notes are path-prefix tests, not a mount.
+
+Process or VM death also loses `/tmp`. Same as POSIX `/tmp`. That
+is acceptable. Do not persist scratch across turns or process
+restarts.
+
+### Overlay
+
+| Piece | Rule |
+| --- | --- |
+| Native tool | Still searches and fetches. |
+| Bind | Per turn: `unionFs({ "/": authored, "/tmp": tempFs() })`. `/tmp` is a mount, not a FileSystem type. |
+| Session cache | Authored handle may stay cached. The composed root does not. |
+| Drop | End of turn. Next turn gets a new empty `/tmp`. |
+| Small results | Stay inline. No disk, no rewrite. |
+| Copy | Only a file the native tool wrote this turn under `{cwd}/agent-tools/`. |
+| Dest | `/tmp/{uuid}.txt`. Same uuid as the host file. |
+| Host file | Delete after copy. |
+| Other paths | Ignore. Do not copy from the result text at large. |
+
+Do not put that composed root on the session handle. A later turn
+must not read another turn's `/tmp`.
+
+### Result rewrite
+
+Keep the native tool descriptions. They do not mention spill.
+
+This package does not change the Cursor SDK. Native WebSearch /
+WebFetch results land in the AgentService conversation inside
+the local executor. That transcript is not rewritten here.
+
+What this package rewrites:
+
+| Surface | Overlay (`root` set) |
+| --- | --- |
+| `webSearch` / `webFetch` result | Host path and follow-up, in strings or structured fields (`output_location`). Other tools are untouched. |
+| Synthesized Read / Grep input | `{cwd}/agent-tools/{uuid}.txt` → `/tmp/{uuid}.txt` |
+
+| Field | Host path (`root` unset) | Overlay (`root` set) |
+| --- | --- | --- |
+| Path | `{cwd}/agent-tools/{uuid}.txt` | `/tmp/{uuid}.txt` |
+| Follow-up | Native text (today: shell / grep / `read_file`) | Read / Grep |
+
+Two modes, two paths. Do not invent a third.
+
+WebFetch proto has `output_location`. WebSearch only embeds the
+path in the chunk string. Rewrite whichever form the native tool
+used.
+
+The model follow path is Read / Grep on `/tmp/{uuid}.txt`,
+including when the model still holds the host path.
+
+### Out of scope here
+
+MCP `spillLargeMcpTextOutput` uses the same host `agent-tools`
+directory. The same overlay can cover it later. This section is
+webSearch and webFetch only.
+
+---
+
+## Live `root`
+
+When the tree depends on the conversation, pass a factory. The
+factory returns a handle. Agent SDK may reuse the object for the
+session. Reuse is not a snapshot of mount contents.
+
+```ts
+export default defineAgent({
+  name: "notes",
+  root: (ctx) => notesForSession(ctx.sessionId),
+});
+```
+
+```ts
+interface RootContext {
+  sessionId: string;
+  agentName?: string;
+  continuationKey?: string;
+  host?: { files: HostFilesApi; reminders?: ReminderHostApi };
+}
+```
+
+---
+
 Source: /docs/design/runtime-abstraction.md
 
 # Replacing `runtime: "local" | "cloud"` with a code interface
@@ -1100,8 +1479,8 @@ Source: /docs/design/runtime-abstraction.md
 > until this document has been reviewed.
 > **Audience:** Agent SDK and cursor-sdk maintainers; change-monitor as the
 > first consumer that is already faking a third runtime.
-> **Companions:** [cloud-runtime.md](/docs/guides/cloud-runtime.md) (today's
-> user-facing contract),
+> **Companions:** [agent-config.md](/docs/reference/agent-config.md#choose-a-runtime)
+> (today's user-facing contract),
 > [factory/change-monitor/docs/tools.md](https://github.com/cursor/cursor/blob/main/factory/change-monitor/docs/tools.md)
 > (why change-monitor is pinned to local),
 > [factory/change-monitor/docs/computer-use.md](https://github.com/cursor/cursor/blob/main/factory/change-monitor/docs/computer-use.md)
@@ -2699,7 +3078,6 @@ sandbox })`, next to `cloudRuntime({ repos })`. Sibling
 | Page | Change |
 |---|---|
 | [reference/agent-config.md](/docs/reference/agent-config.md) | `runtime` type becomes constructors **or** the deprecated string. Table + "Choose a runtime" show `localRuntime(opts)` / `cloudRuntime(opts)` / `virtualRuntime(fs)` first. Move cwd / sandbox / workspaceDir onto the `localRuntime` section. Mark sibling `local` / `cloud` and string `runtime` deprecated. |
-| [guides/cloud-runtime.md](/docs/guides/cloud-runtime.md) | Open with `cloudRuntime({ repos })`. Keep `runtime: "cloud"` as the still-supported form. Cloud is a turn host, not a filesystem. Hybrid is `send({ runtime: cloudRuntime(opts) })`; local overlay is `send({ runtime: localRuntime(opts) })`. `send({ cloud })` / `send({ workspaceDir })` deprecated. |
 | [concepts.md](/docs/concepts.md) | Local vs cloud table: same facts, constructor names. Add one line that `virtualRuntime` is local-with-your-files, not a third host. |
 
 **New page**
@@ -3009,17 +3387,19 @@ Drive the agent with `t.send(message, options?)`. It runs one turn and
 waits for the session to park or fail. Multiple sends in one case share
 the session, which is how you write multi-turn evals.
 
-Each `t.send` resolves to a turn result with `message`, `sessionId`,
-`events`, `toolCalls`, `ok`, and `index`. The turn carries the same
-assertion vocabulary as `t`, scoped to that turn, so you can grade an
-intermediate turn before the next send overwrites `t.reply`.
-`turn.expectOk()` throws when the turn failed, for later steps that
-depend on it.
+Each `t.send` resolves to a turn result with `message`,
+`sessionId`, `events`, `toolCalls`, `ok`, and `index`. The turn carries
+the same assertion vocabulary as `t`, scoped to that turn, so you can
+grade an intermediate turn before the next send overwrites `t.reply`.
+`turn.expectOk()` throws when the turn failed, for later
+steps that depend on it.
 
 Read the full case state with `t.reply` (the last assistant text),
 `t.events` (session events captured so far), `t.turns` (settled
 turns, oldest first), and `t.sessionId`. `t.signal` aborts when the
-case hits its timeout; pass it to your own async work.
+case hits its timeout; pass it to your own async work. A thrown
+[turn result](/docs/reference/result.md) `commit` fails the turn, so
+`t.succeeded()` fails too.
 
 Assert with the gates:
 
@@ -3448,7 +3828,8 @@ questions in the meantime. A Slack triage agent turns a bug report into
 a PR, a planner fans a refactor out across repositories, a reviewer asks
 a cloud agent to address its own comments.
 
-This is different from the [cloud runtime](/docs/guides/cloud-runtime.md). The
+This is different from
+[`runtime: "cloud"`](/docs/reference/agent-config.md#choose-a-runtime). The
 runtime moves *this* agent's turns onto a cloud VM. The extension keeps
 the agent where it is and lets it start *other* cloud agents.
 
@@ -3473,9 +3854,8 @@ Launches run under the host's signed-in account (`agent-sdk login` or
 repositories the agent may target, and keep approval on when you can't.
 
 Mount it on an agent that runs on the local runtime; that is where
-launches park for approval. On the
-[cloud runtime](/docs/guides/cloud-runtime.md#what-changes-on-cloud) approvals
-don't resolve.
+launches park for approval. On the cloud runtime approvals don't
+resolve.
 
 ## What the agent can do
 
@@ -3529,130 +3909,6 @@ Continue with these pages:
   overrides work
 - [Human-in-the-loop approvals](/docs/guides/human-in-the-loop.md): where parked
   launches get approved
-- [Cloud runtime](/docs/guides/cloud-runtime.md): run the agent's own turns on
-  cloud agents instead
-
----
-
-Source: /docs/guides/cloud-runtime.md
-
-# Cloud runtime
-
-By default, turns execute on the Cursor SDK's local harness, on the same
-machine as the server. Set `runtime: "cloud"` and turns execute on
-Cursor cloud agents instead. They're ephemeral VMs that carry a repo
-checkout, run `gh`, `git`, and tests for real, and scale past what one
-host's disk and CPU can do. The serve host keeps handling routing, host
-preparation, sessions, and bookkeeping.
-
-A canonical use is a PR driver whose triage runs on cloud VMs. The
-patterns in this guide come from running one against real PR traffic.
-
-## When to switch
-
-A guideline from running PR agents at scale: per-PR worktrees on the serve host
-don't scale to hundreds of engineers opening PRs. When the job needs a
-repo checkout at scale, use cloud. The signals:
-
-- The agent must run repo commands (tests, builds, `git`) against many
-  different refs concurrently.
-- Turns are long and heavy, and you don't want them competing with the
-  server for resources.
-- The work product is a PR or branch the VM can push, not a local file.
-
-Stay local when the agent is conversational, tool-driven against APIs,
-or works over host-prepared evidence. Local turns are cheaper, start
-faster, and support the full authored surface.
-
-## Configure it
-
-Cloud runtime is two fields on the agent config.
-
-```ts
-import { defineAgent } from "@cursor/july";
-
-export default defineAgent({
-  runtime: "cloud",
-  cloud: {
-    repos: [{ url: "https://github.com/org/repo", startingRef: "main" }],
-    // env / envVars / … forwarded to the Cursor SDK
-  },
-});
-```
-
-The host must be signed in (`agent-sdk login` or `CURSOR_API_KEY`).
-
-> [!IMPORTANT]
-> Cloud agents run against the Cursor backend under the signed-in
-> account, and every wake spends real cloud-agent budget. Decide
-> explicitly what may trigger one.
-
-## What changes on cloud
-
-Cloud turns run on a VM without your authored files, so the runtime
-mapping shifts:
-
-| Folder or file | Local runtime | Cloud runtime |
-| --- | --- | --- |
-| `instructions.*` | `AGENTS.md` in the session workspace | prepended to the first prompt |
-| Server tools (`execution: "server"`) | in-process SDK custom tools | authenticated HTTP MCP back to the AgentSDK host, when `--public-url` or `--cloud-tools-url` is set |
-| 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 |
-
-Authored skills are discovered natively after the first cloud turn,
-using the hosted store or the signed-in account.
-
-Approvals are a local-runtime contract. On cloud, a `needsApproval` tool
-call rides one HTTP MCP request from the VM, and a parked call would
-hold that request open until it times out; there is no durable approval
-flow for cloud turns.
-
-Peer MCP connections need `--public-url` for cloud turns. Without one,
-peers are omitted and the server warns at startup.
-
-## Hybrid: local agent, cloud sessions
-
-A local-runtime agent can still open cloud-attached sessions per send.
-Channel handlers may pass a `cloud` block (repos pinned to a PR ref, say)
-in `send` options, and Slack handlers may return `cloud` from a mention
-hook. A PR driver works this way: chat stays local, and the `drive`
-flow attaches the PR to a cloud VM. The agent-level `cloud` config is the
-base that per-session options merge over.
-
-## Patterns that hold up
-
-These come from running a PR driver against real PR traffic:
-
-- One cloud session per unit of work, keyed with a stable continuation
-  token (`pr:owner/repo#N`) so every wake lands on the same conversation.
-- Keep the host deterministic: fetch briefs and metadata on the host,
-  send the VM a compact prompt, and let the VM re-read source of truth
-  with its own `gh` and `git` instead of trusting payload snapshots.
-- Limit exposure: add repository allowlists on webhook channels,
-  because every wake spends the account's budget.
-
-## Verify cloud agents
-
-`agent-sdk run` and `eval` work unchanged. The trajectory records the
-same event vocabulary plus `agent.bound` with the cloud URL, so you can
-open the cloud conversation for any session. Cloud turns take minutes.
-Pass generous `--timeout-ms` values, and keep curl timeouts long when
-driving channels directly.
-
-## What's next
-
-Continue with these pages:
-
-- [Agent config](/docs/reference/agent-config.md): the `runtime` and
-  `cloud` fields
-- [GitHub guide](/docs/guides/github.md): the webhook patterns that pair with
-  cloud triage
-- [Cursor cloud agents](/docs/guides/cloud-agents.md): keep the agent local and
-  let it launch cloud agents instead
 
 ---
 
@@ -4091,6 +4347,11 @@ behavior. Reactions still default on; set `reactions: false` when the
 eyes emoji is noise. Descriptions are optional; defaults derive from
 `botName` or the check `context`.
 
+To match dashboard automations, set `detailsUrl(sessionId)`,
+`summaryLinkText: "View agent"`, and `outputTitle: "context"` so the
+check title is the check name, the summary includes `[View agent](…)`,
+and Details opens the session.
+
 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.
@@ -4106,7 +4367,6 @@ key. Handlers you author replace the matching defaults (same as
 - [Webhooks and custom channels](/docs/guides/webhooks.md): the HTTP mechanism under
   this pack
 - [Evals](/docs/evals.md): turn replay snapshots into regression fixtures
-- [Cloud runtime](/docs/guides/cloud-runtime.md): attach PRs to cloud VMs
 - [Hooks](/docs/reference/hooks.md): observe-only; use channel `progress` for
   GitHub surfaces
 
@@ -4424,7 +4684,7 @@ Source: /docs/guides/opentelemetry.md
 Agent SDK can push traces, metrics, and logs from the serve process to
 an OTLP collector you run. Point the process at the collector with
 standard `OTEL_EXPORTER_OTLP_*` env, or author `agent/otel.ts`. Traces
-cover the inbound request, the session, each turn, and every tool call.
+cover the inbound request, each turn, and every tool call.
 
 Export is opt-in. Nothing leaves the process until you set an endpoint
 or a `defineOtel` config.
@@ -4433,7 +4693,7 @@ or a `defineOtel` config.
 
 | Signal | Default | What you get |
 | --- | --- | --- |
-| Traces | on | `agent_sdk.http` → `agent_sdk.session` → `agent_sdk.turn` → `agent_sdk.tool` / `agent_sdk.subagent` |
+| Traces | on | `agent_sdk.http` (per request) and `agent_sdk.turn` → `agent_sdk.tool` / `agent_sdk.subagent` |
 | Metrics | on | `cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`, plus `agent_sdk.*` session and turn counts |
 | Logs | off | Session events as log records. Prompt text, tool payloads, and failure messages stay off unless you opt in |
 
@@ -4505,7 +4765,17 @@ destination with `signals: ["traces"]`.
 
 You can also pass the same object to `serve(dir, { otel })`. Precedence
 is `serve({ otel })` over `agent/otel.ts` over env. An empty
-`defineOtel()` still enables export when `OTEL_EXPORTER_OTLP_*` is set.
+`defineOtel()` still records traces; export starts when
+`OTEL_EXPORTER_OTLP_*` or a factory-returned `exporters` list appears.
+
+Hosted v2 binds deployment secrets after bake, onto the already-listening
+process. Pass a factory so flush can re-read them. Spans record from
+bake; the hosted handler flush constructs the OTLP client and sends the
+queued batch.
+
+```ts
+export default defineOtel(() => resolveMyOtelConfig());
+```
 
 The companion skill is [`skills/otel/SKILL.md`](/docs/skills/otel.md).
 
@@ -4513,17 +4783,23 @@ The companion skill is [`skills/otel/SKILL.md`](/docs/skills/otel.md).
 
 ```text
 agent_sdk.http          inbound channel request (W3C traceparent)
-  └─ agent_sdk.session  cursor.conversation.id = session id
-       └─ agent_sdk.turn
-            ├─ agent_sdk.tool
-            └─ agent_sdk.subagent
-                 └─ agent_sdk.tool
+agent_sdk.turn          one root per turn (`agent_sdk.session_id` = session id)
+  ├─ agent_sdk.tool
+  └─ agent_sdk.subagent
+       └─ agent_sdk.tool
 ```
 
-Inbound HTTP extracts W3C `traceparent`, so a channel request parents
-the session span when the turn starts in that request. Turns that
-resume after restore, or a direct `callTool` with no `turn.started` in
-this process, open a synthetic turn span so tool calls still nest.
+Conversational sessions stay on `session.waiting` and can take more
+turns, so there is no `agent_sdk.session` span — it would never end
+and OTel only exports ended spans. Each turn is its own root. Inbound
+HTTP is a separate SERVER span (it extracts W3C `traceparent`) and
+does not parent the turn, so the turn tree can export when the turn
+ends. Hosted flush ends that SERVER span before the one-shot export so
+`agent_sdk.http` is in the same batch.
+
+Turns that resume after restore, or a direct `callTool` with no
+`turn.started` in this process, open a synthetic turn span so tool
+calls still nest.
 
 ## Which attributes land on the wire?
 
@@ -4534,6 +4810,12 @@ Every signal carries these resource attributes:
 - `cursor.surface=unspecified`
 - `agent_sdk.framework=@cursor/july`
 
+Span attributes (not process resource attributes — one serve process
+handles many sessions):
+
+- `agent_sdk.session_id` / `cursor.conversation.id`: the session id.
+  Search all turns for one conversation with `@agent_sdk.session_id`.
+
 Shared names (same keys as enterprise export):
 
 - `cursor.conversation.id`: the session id
@@ -4544,22 +4826,24 @@ Shared names (same keys as enterprise export):
   `cursor.tool.status`
 - `cursor.cost.usage` (USD)
 
-Agent SDK only (`agent_sdk.*`): agent name, turn id, channel, call id,
-subagent name, session mode, and HTTP duration (`agent_sdk.http.duration`).
+Agent SDK only (`agent_sdk.*`): session id, agent name, turn id, channel,
+call id, subagent name, session mode, and HTTP duration
+(`agent_sdk.http.duration`).
 
 ## How do I emit my own metrics?
 
 `ctx.host.otel` is always present on tools, hooks, and channel
 handlers. Counters and histograms no-op when no meter is running.
-`setAttributes` still tags the open session when a collector is
+`setAttributes` still tags open turn/tool spans when a collector is
 attached.
 
 Prefix metric names with your team or agent. First-party names
 (`cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`,
 `agent_sdk.session.count`, `agent_sdk.turn.count`,
 `agent_sdk.subagent.count`, `agent_sdk.http.duration`) and join keys
-(`cursor.conversation.id`, `agent_sdk.agent`, `agent_sdk.turn_id`,
-`agent_sdk.framework`) are reserved. Custom spans are not on this
+(`cursor.conversation.id`, `agent_sdk.session_id`, `agent_sdk.agent`,
+`agent_sdk.turn_id`, `agent_sdk.framework`) are reserved. Custom spans
+are not on this
 surface.
 
 ```ts
@@ -5569,8 +5853,6 @@ npx @cursor/july docs
   on hosted deployments (`--store`).
 - [Agent-to-agent](/docs/guides/agent-to-agent.md): every agent is an MCP
   server; agents can delegate to each other.
-- [Cloud runtime](/docs/guides/cloud-runtime.md): run turns on Cursor cloud
-  agents instead of the local harness.
 - [Cursor cloud agents](/docs/guides/cloud-agents.md): let the agent launch
   and steer cloud agents through the `cursor-cloud-agents` extension.
 - [OpenTelemetry](/docs/guides/opentelemetry.md): push session, turn, and
@@ -5597,6 +5879,8 @@ npx @cursor/july docs
 - [Channels](/docs/reference/channels.md) ·
   [Schedules and reminders](/docs/reference/schedules.md) ·
   [Hooks](/docs/reference/hooks.md) ·
+  [Artifacts](/docs/reference/artifacts.md) ·
+  [Turn result](/docs/reference/result.md) ·
   [Sessions and streaming](/docs/reference/sessions.md) ·
   [Playground](/docs/reference/playground.md)
 - [CLI](/docs/reference/cli.md) · [HTTP API](/docs/reference/http-api.md)
@@ -6074,11 +6358,10 @@ the first prompt, because the local session workspace is not the cloud
 VM.
 
 `validate` warns when `runtime: "cloud"` is combined with agent tools
-or sandbox seeds (they only materialize into local session workspaces),
-when skills are present (they sync onto an Agent Store for native
-discovery rather than the session workspace), and when the `cloud`
-block is missing. The full capability matrix and the patterns that hold
-up are in the [Cloud runtime guide](/docs/guides/cloud-runtime.md).
+(they are described on the first prompt instead of written to the VM),
+when skills or sandbox seeds are present (they sync onto an Agent Store
+rather than the session workspace), and when the `cloud` block is
+missing.
 
 ## Local options
 
@@ -6164,9 +6447,8 @@ set `local: { sandbox: true }`.
 Cloud agent defaults forwarded to the Cursor SDK: `repos` (each
 `{ url, startingRef? }`), environment selection, `envVars`, and the
 rest. A local agent uses the same block as the base config when a
-channel opens a cloud-attached session per send. That hybrid pattern is
-covered in
-[Cloud runtime](/docs/guides/cloud-runtime.md#hybrid-local-agent-cloud-sessions).
+channel opens a cloud-attached session per send (the `cloud` option on
+[`send`](/docs/reference/channels.md#handler-arguments)).
 
 ## Concurrency
 
@@ -6243,8 +6525,6 @@ Continue with these pages:
 
 - [Instructions](/docs/reference/instructions.md): the required half of a minimal
   agent
-- [Cloud runtime](/docs/guides/cloud-runtime.md): when and how to leave
-  the host
 - [CLI](/docs/reference/cli.md): the `serve` flags `serve()` accepts
 
 ---
@@ -6507,8 +6787,10 @@ The `events` map subscribes the channel to stream events for the
 sessions it owns. Keys are event types from the
 [event vocabulary](/docs/reference/sessions.md#which-events-can-i-stream), or `"*"`.
 Handlers receive `(event, channel, ctx)`, where `channel.state` is the
-per-session adapter state and `ctx` exposes session info and host
-services. This is where a channel delivers replies back to its surface.
+per-session adapter state, `ctx.session` is the session info, and
+`ctx.host` is the shared host services, bound to that session as in a
+[hook](/docs/reference/hooks.md#handler-context). This is where a channel delivers
+replies back to its surface.
 
 ## State and lifecycle
 
@@ -6581,17 +6863,45 @@ converge a merge-box check and sticky PR comment from default stream
 events. Guide: [GitHub](/docs/guides/github.md).
 
 **Deployments** (`@cursor/july/channels/deployments`): pull deploy
-events. Subscribe per deploy source with `deploySourceUris`, narrow
-with `environments` / `events`, and handle each event in `onEvent`.
-`deploySourceUris` must match `Deployment.deploy_source_uri` as your
+events. Declare `events` and handle each one in `onEvent`. Each event
+carries `deploySourceUri` and `deployVersion`. Author
+`agent/channels/deployments.ts` with `deploymentsChannel()`.
+
+Omit `deploySourceUris` on hosted v2. The control plane binds
+`deploy_source` edges from the deploy's watched `repositories` and the
+channel admits what it is sent, which is what makes it multi-tenant
+safe.
+
+Name sources to narrow below that scope, or to drive the self-hosted
+pull relay, which has no deploy scope to inherit. There, subscribe per
+deploy source with `deploySourceUris` and narrow with `environments` /
+`events`. Each entry must match `Deployment.deploy_source_uri` as your
 deployment writer records it; matching is case-insensitive but
-otherwise literal. Each event carries `deploySourceUri` and
-`deployVersion`. Author `agent/channels/deployments.ts` with
-`deploymentsChannel()`. It uses the host credential. A restart resumes
+otherwise literal. It uses the host credential. A restart resumes
 rather than dropping events. An empty `deploySourceUris` list mounts
 the channel but starts no pull, so an env-configured agent stays inert
 until its deploy sources are set.
 
+**Change Monitors** (`@cursor/july/channels/change-monitors`): Change
+Monitor Checkpoint events. The channel publishes Factory
+`checkpoint.created` for every Checkpoint create. The agent filters the
+result (for example to the `issues` arm). The payload contains the
+full Checkpoint resource. This channel is scoped to Change Monitors,
+not generic Factory Checkpoints. There is no repository filter or
+resource filter. Author `agent/channels/change-monitors.ts` with
+`changeMonitorsChannel()`. It uses the host credential. The v1 omitted
+continuation is `none/v1`. A v2 agent defaults to
+`change_monitors.checkpoint/v2`, which keys the session as
+`cont:change_monitors:{checkpointName}`.
+
+**Issues** (`@cursor/july/channels/issues`): Factory issue events.
+The channel publishes `issue.created` for every Issue create. The
+agent filters if it needs a subset. The payload contains the full
+Issue resource. There is no repository filter or resource filter.
+Author `agent/channels/issues.ts` with `issuesChannel()`. It uses the
+host credential. The v1 omitted continuation is `none/v1`. A v2 agent
+defaults to `issues.issue/v2`, which keys the session by issue name.
+
 For other platforms like Discord or Teams, use the authored
 `defineChannel` webhook form.
 
@@ -6619,10 +6929,9 @@ Source: /docs/reference/cli.md
 
 # CLI reference
 
-`@cursor/july` installs `july` (so `npx @cursor/july docs` works) and
-`agent-sdk`. The examples on this page use `agent-sdk`. Run the CLI with
-Node 22.13 or newer. Don't run it with Bun; Bun corrupts tool-result
-streams from the Cursor SDK.
+`@cursor/july` installs one command, `agent-sdk`; `npx @cursor/july <cmd>`
+runs it. Run the CLI with Node 22.13 or newer. Don't run it with Bun; Bun
+corrupts tool-result streams from the Cursor SDK.
 
 `agent-sdk help` prints the built-in summary. The Slack and GitHub packs
 also provide `agent-sdk slack help` and `agent-sdk github help`.
@@ -7897,11 +8206,16 @@ Source: /docs/reference/extensions.md
 
 # Extensions
 
-An extension packages tools and skills an agent installs as one unit. You
-mount it with a single file under `agent/extensions/`, and its
-contributions join the agent under a namespace. The package updates
-like any other dependency; nothing is copied into your project. A Cursor
-plugin mounts the same way; see [Mount a Cursor plugin](#mount-a-cursor-plugin).
+An extension packages the same contributions an agent authors under
+`agent/` and installs them as one unit. You mount it with a single file
+under `agent/extensions/`, and its contributions join the agent under a
+namespace. The package updates like any other dependency; nothing is
+copied into your project. A Cursor plugin mounts the same way; see
+[Mount a Cursor plugin](#mount-a-cursor-plugin).
+
+Extensions are native to the Agent SDK. Slot files use the `@cursor/july`
+helpers, so a package built on another agent framework fails
+`agent-sdk validate` until you rewrite it onto `@cursor/july`.
 
 ## Mount an extension
 
@@ -7928,6 +8242,48 @@ Namespaces follow the tool-name rule, and `__` is reserved: an authored
 `agent/tools/ci__failed_jobs.ts` fails discovery, so nothing outside a
 mount can pose as one of its tools.
 
+## What an extension can contribute
+
+An extension tree uses the same slots as [`agent/`](/docs/reference/project-layout.md).
+Each shareable contribution lands on the agent under the mount's
+namespace:
+
+| Path | Becomes |
+| --- | --- |
+| `tools/<name>.ts` | tool `<ns>__<name>` |
+| `skills/<name>` | skill `<ns>__<name>` |
+| `mcp-connections/<name>.ts` | connection `<ns>__<name>` |
+| `host-connections/<name>.ts` | host connection `<ns>__<name>` |
+| `hooks/<name>.ts` | hook `<ns>__<name>` |
+| `channels/<name>.ts` | channel `<ns>__<name>` |
+| `schedules/<name>` | schedule `<ns>__<name>` |
+| `subagents/<id>/` | subagent `<ns>__<id>` |
+| `instructions.md` / `.ts` / dir | appended to the agent's system prompt |
+| `sandbox/workspace/**` | seeded into each local session workspace |
+| `ab.ts` / `ab/<name>.ts` | A/B experiment `<ns>__<name>` |
+| `artifacts.ts` | artifact kinds `<ns>__<kind>` |
+
+The root agent still needs its own `instructions.md`. Extension
+instructions are extra fragments, not a substitute.
+
+`httpChannel()` stays on the agent. An extension authors
+`defineChannel` only; a file named `http.ts` becomes `<ns>__http`.
+
+These stay on the agent that mounts the extension. Each is a singleton
+or is outside discovery:
+
+| Path | Why it stays on the agent |
+| --- | --- |
+| `agent.ts` | One `defineAgent` runtime per agent |
+| `storage.ts` | One `host.kv` / `host.files` backend |
+| `otel.ts` | One OTLP exporter |
+| `ab.config.ts` | One experiment-platform config; `ab.ts` / `ab/` still merge |
+| `playground/` | Custom chips are a Vite glob of the agent tree, not a discovery walk |
+| `extensions/` | Nested mounts are not loaded |
+| `sandbox.ts` | Custom sandbox backends stay on the agent |
+
+`agent-sdk validate` warns when a tree carries those paths.
+
 ## Adjust a mounted extension
 
 To replace or remove a contribution, mount the extension as a directory
@@ -7939,15 +8295,35 @@ agent/extensions/ci/
 ├── tools/
 │   ├── job_log.ts      # replaces ci__job_log with your own defineTool
 │   └── retry_job.ts    # export default disableTool() removes ci__retry_job
+├── hooks/
+│   └── audit.ts        # export default disableHook() removes ci__audit
 └── skills/
-    └── triage.md       # replaces ci__triage
+    └── triage.ts       # export default disableSkill() removes ci__triage
 ```
 
 Use the extension's own names inside the directory, without the
 namespace. A file with a name the extension doesn't contribute adds a
-new tool or skill under the namespace. `disableTool()` comes from
-`@cursor/july/extensions` and fails discovery when it names a tool the
-extension doesn't have, so a typo can't silently keep a tool alive.
+new contribution under the namespace. Each helper comes from
+`@cursor/july/extensions` and fails discovery when it names a
+contribution the extension doesn't have, so a typo can't silently keep
+it alive.
+
+| Slot | Helper |
+| --- | --- |
+| `tools/<name>.ts` | `disableTool()` |
+| `mcp-connections/<name>.ts` / `host-connections/<name>.ts` | `disableConnection()` |
+| `skills/<name>.ts` | `disableSkill()` |
+| `hooks/<name>.ts` | `disableHook()` |
+| `channels/<name>.ts` | `disableChannel()` |
+| `schedules/<name>.ts` | `disableSchedule()` |
+| `subagents/<id>.ts` | `disableSubagent()` |
+| `instructions.ts` | `disableInstructions()` |
+| `ab.ts` / `ab/<name>.ts` | `disableAB()` |
+| `artifacts.ts` | `disableArtifacts()` |
+
+`disable()` is the same brand as the slot helpers above and works in
+any of those files.
+
 A Cursor plugin mount overlays its MCP servers the same way; see below.
 
 ## Mount a Cursor plugin
@@ -8011,8 +8387,8 @@ discovery when it names a server the plugin doesn't declare.
 ## Build an extension
 
 An extension is a directory laid out like `agent/`. `extension.ts`
-declares it; `tools/` and `skills/` hold the contributions in the same
-authoring forms as [Tools](/docs/reference/tools.md) and [Skills](/docs/reference/skills.md).
+declares it; the slots in [What an extension can contribute](#what-an-extension-can-contribute)
+use the same authoring forms as the rest of this reference.
 
 ```text
 @acme/ci-triage/
@@ -8024,6 +8400,10 @@ authoring forms as [Tools](/docs/reference/tools.md) and [Skills](/docs/referenc
 │   └── retry_job.ts
 ├── skills/
 │   └── triage.md
+├── hooks/
+│   └── audit.ts
+├── mcp-connections/
+│   └── buildkite.ts
 └── lib/
     └── buildkite.ts    # shared code, never discovered
 ```
@@ -8073,17 +8453,10 @@ Because the consumer picks the namespace, have skills and tool
 descriptions refer to sibling tools by their short names and say they
 appear under the mount's namespace (`<namespace>__job_log`).
 
-Publish the built `extension.js` as the package entry point with
-`tools/` and `skills/` beside it. `root` is read from the built file, so
-copy `skills/*.md` into the build output or author skills as `.ts` with
-`defineSkill`.
-
-Only `tools/` and `skills/` are mounted from an extension tree.
-Instructions, connections, hooks, channels, and the runtime
-configuration belong to the agent that mounts the extension;
-`agent-sdk validate` warns when a tree carries agent slots such as
-`instructions.md`, `connections/`, `hooks/`, `channels/`, or
-`schedules/`.
+Publish the built `extension.js` as the package entry point with the
+slot directories beside it. `root` is read from the built file, so copy
+`skills/*.md` and `instructions.md` into the build output or author them
+as `.ts`.
 
 ## What's next
 
@@ -8102,56 +8475,119 @@ Source: /docs/reference/hooks.md
 
 # Hooks
 
-A hook is an observe-only subscriber to the session event stream. Hooks
-run after each event is recorded. They cannot change the event or the
-turn. That makes them the home for audit logging, metrics, mirroring
-transcripts into your own store, and maintaining derived state. Handler
-errors are logged and never fatal. A hook can't inject context into the
-next turn or block a turn.
+A hook subscribes to the session event stream and runs a side effect
+after each event is recorded: an audit line, a metric, a copy of the
+transcript in your own store, or derived state for later turns. Hooks
+run in the serving process for every session of the agent, on local and
+cloud runtime turns alike.
+
+Hooks observe. They can't change the turn, the prompt, or the reply, and
+a handler that throws is logged and skipped. Treat the event as
+read-only; later subscribers see the same object. That makes hooks safe
+to add to a production agent, and the wrong tool for anything that must
+happen before the model runs or must fail a turn; see
+[When not to use a hook](#when-not-to-use-a-hook).
 
-For deterministic context composition before the model runs, use the
-host path that already owns the wake: channel handlers (fetch, `callTool`,
-`workspaceFiles`, and the message you pass to `send`), plus
-`instructions.md`, skills, and `sandbox/workspace/` seed files. Hooks
-observe what happened; they do not assemble the prompt.
+`defineHook` is unrelated to
+[Cursor Agent hooks](https://cursor.com/docs/agent/hooks), the
+`.cursor/hooks.json` scripts that can observe, block, or modify the
+agent loop. Those still run inside a local session workspace.
+
+## Author a hook
 
 Author `agent/hooks/<name>.ts` with `defineHook` from
-`@cursor/july/hooks`:
+`@cursor/july/hooks`. This one meters tokens:
 
 ```ts
+// agent/hooks/usage.ts
 import { defineHook } from "@cursor/july/hooks";
 
 export default defineHook({
   events: {
     async "turn.completed"(event, ctx) {
-      const prior = await ctx.host.kv.get("last-result");
-      const notes = await ctx.host.files.read("notes.md");
-      console.log("turn done", ctx.session.id, event.data.usage, prior, notes);
+      if (ctx.session.purpose === "eval" || event.data.usage === undefined) {
+        return;
+      }
+      const { inputTokens, outputTokens } = event.data.usage;
+      ctx.host.otel.increment("acme.tokens.input", inputTokens);
+      ctx.host.otel.increment("acme.tokens.output", outputTokens);
     },
-    async "turn.failed"(event, ctx) {
-      // page, count, or record
+    async "turn.failed"(_event, ctx) {
+      ctx.host.otel.increment("acme.turn.failed", { channel: ctx.channel.id });
     },
   },
 });
 ```
 
-Keys are event types (see the
-[event vocabulary](/docs/reference/sessions.md#which-events-can-i-stream)), or `"*"`
-for everything. Handlers receive the event with its envelope (`index`,
-`sessionId`, `turnId?`, `at`) and a `HookContext`:
+Any module under `agent/hooks/`, subfolders included, is a hook named by
+its path without the extension: `agent/hooks/audit/usage.ts` is
+`audit/usage`. `*.test.ts` and `*.spec.ts` files are skipped. The
+default export must be `defineHook(...)`, names can't contain `__`, and
+an empty `events` map skips the hook with a warning; `agent-sdk validate`
+reports all three. An extension mounts its hooks as `<ns>__<name>`, and
+`disableHook()` removes one
+([Adjust a mounted extension](/docs/reference/extensions.md#adjust-a-mounted-extension)).
+
+`agent-sdk init` scaffolds `agent/hooks/memory.ts`, which exports
+`memoryHook()` from `@cursor/july/memory` and journals every turn for
+later sessions to read. Delete the file to opt out.
+
+## Events and payloads
+
+Keys are event types from the
+[event vocabulary](/docs/reference/sessions.md#which-events-can-i-stream), or `"*"`
+for every event. A typed key narrows `event.data`; a `"*"` handler
+receives the union, so switch on `event.type`. Every event carries the
+stream envelope `{ type, index, sessionId, turnId?, at, data }`, with
+`turnId` set on turn-scoped events.
+
+The payloads hooks read most often:
+
+| Event | `event.data` |
+| --- | --- |
+| `message.received` | `{ text }` |
+| `turn.completed` | `{ result?, usage?, cost? }`. `usage` has `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, and optional `reasoningTokens`. `cost` has `totalUsd` and the `model` it was priced against |
+| `turn.failed` | `{ message }` |
+| `actions.requested` | `{ calls: [{ callId, toolName, args? }] }`. A call with `parentCallId` belongs to a subagent |
+| `action.result` | `{ callId, toolName, output?, isError, stubbed? }`. `stubbed` means a dry-run session answered a write without running it |
+
+The types are `SessionEvent`, `SessionEventType`, and `HookContext`,
+exported from `@cursor/july`.
+
+## Handler context
 
 | Member | What it is |
 | --- | --- |
-| `ctx.session` | Read-only session info: id, channel, mode, auth |
+| `ctx.session` | Read-only session info: `id`, `channelId`, `mode` (`chat` or `task`), `purpose` (`live` or `eval`), `auth`, plus `title`, `sdkAgentId`, and `abs` when set |
 | `ctx.agent` | `{ name }` of the agent the event belongs to |
-| `ctx.channel` | `{ id, continuationToken }` for the owning channel |
-| `ctx.stateRoot` | The agent's durable state root. Prefer `ctx.host.kv` / `ctx.host.files` for derived state; this tree resets on hosted replace |
-| `ctx.host` | Shared host services; same as a tool's `ctx.host`. Pull JSON with `ctx.host.kv` and file-shaped state with `ctx.host.files` (session-bound by default; pass `{ scope: "deployment" }` for agent-wide files) |
-| `ctx.artifacts` | Session-bound [artifacts](/docs/reference/artifacts.md) facade: `tag` auto-fills the session |
+| `ctx.channel` | `{ id, continuationToken }`. The token is `null` when the session can't take follow-ups |
+| `ctx.host.kv` | Durable JSON, shared by every session of the agent; the [storage backend](/docs/storage.md#author-kv-ctx-host-kv) decides whether it survives a hosted replace. Prefix keys with `ctx.session.id` for per-session state |
+| `ctx.host.files` | Durable files, bound to this session. Pass `{ scope: "deployment" }` for agent-wide files |
+| `ctx.host.otel` | Counters, histograms, and tags, attributed to this session |
+| `ctx.host.mcp`, `ctx.host.github`, `ctx.host.slack` | The same shared clients tools get |
+| `ctx.host.reminders` | Per-session [reminders](/docs/reference/schedules.md), the same API tools get |
+| `ctx.artifacts` | Session-bound [artifacts](/docs/reference/artifacts.md) facade: `tag` fills in `sessionId` and `turnId` |
+| `ctx.stateRoot` | Absolute path of the local state root. It resets when a hosted deployment is replaced; keep derived state in `kv` or `files` |
+
+## When hooks run
+
+A hook runs after the event is durably recorded. It never delays the
+model turn and never sees an event that wasn't recorded.
 
-Hook context includes `ctx.host`, the same shared services a tool
-gets. Persist JSON with `ctx.host.kv` and file-shaped state with
-`ctx.host.files`. Hooks observe; they do not own delivery surfaces.
+Within one session, events dispatch in order, one at a time: the
+channel's `events` handlers first, then each hook in discovery order.
+Sessions don't wait on each other.
+
+Two consequences:
+
+- A slow handler holds up the next event's handlers for that session,
+  not the model. Keep handlers short and queue anything slow.
+- Hooks fire for eval sessions too. Check
+  `ctx.session.purpose === "eval"` before metering or paging.
+
+Each event reaches a hook at most once. A restart doesn't replay the log
+into hooks, so a mirror needs no dedupe, and the event log rather than
+the hook's copy is the source of truth.
 
 ## Hooks, channel events, evals, or A/B?
 
@@ -8159,37 +8595,143 @@ All of them consume the same stream, for different jobs:
 
 | | Hooks | Channel `events` | Evals | A/B (`defineAB`) |
 | --- | --- | --- | --- | --- |
-| Scope | every session on the agent | sessions the channel owns | one test turn | every live session; enrollment at creation, metrics on each turn |
-| Job | observe: audit, metrics, mirrors, derived state | deliver: replies back to the channel's surface | assert: gates over the trajectory | `ab.assigned` + fold stream → `onSample` |
+| Scope | every session of the agent | sessions the channel owns | one test turn | every live session; enrollment at creation, metrics on each turn |
+| Job | observe: audit, metrics, mirrors, derived state | deliver: replies back to the channel's surface | assert: gates over the trajectory | compare: sticky arms, then fold the stream into `onSample` metrics |
+| Context | `ctx.host`, `ctx.artifacts`, session info | `channel.state`, `setContinuationToken`, `ctx.host`, session info | the `t` assertion helpers | per-session samples in `onSample` |
 | Can affect the run | no | yes, it owns the surface | n/a | yes through arm instructions or `session.abs`; collection is observe-only |
 | Authored at | `agent/hooks/*.ts` | channel config | `evals/**/*.eval.ts` | [`agent/ab.ts` or `agent/ab/*.ts`](/docs/ab.md) |
 
-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, such as
-never-red status from tool output. Do not use `defineHook` for those
-writes.
+## When not to use a hook
+
+| You want to | Use instead |
+| --- | --- |
+| Add context before the model runs | The channel's `send` message and `workspaceFiles`, `instructions.md`, skills, or `sandbox/workspace/` seed files |
+| Reply on Slack, comment on a PR, or post any other delivery | The channel's `events` map, or the Slack and GitHub packs |
+| Show PR progress (merge-box check, sticky banner) | `githubChannel({ progress: { commitStatus, banner } })`; see [Show PR progress](/docs/guides/github.md#show-pr-progress) |
+| Block, approve, or rewrite a tool call | [`needsApproval`](/docs/reference/tools.md#gate-a-tool-on-human-approval) on the tool |
+| Act on the final assistant text, or fail a bad turn | [`defineResult`](/docs/reference/result.md) |
+| Gate a change on behavior | [Evals](/docs/evals.md) |
+| Compare two prompts on live traffic | [`defineAB`](/docs/ab.md) |
 
 ## Patterns
 
-Usage metering: subscribe to `turn.completed` and forward
-`event.data.usage` (token counts) to your metrics system.
+Usage metering is the [authoring example](#author-a-hook). Three more:
+
+### Alert on failure
+
+`turn.failed` carries the message, and `ctx.session.id` points at the
+trace. Skip interrupted turns; those are preemptions, not failures. Read
+secrets inside the handler: hosted deployments bind them after the
+process starts, so a module-scope read stays empty. Give the call a
+timeout, since a stalled request holds up later handlers on that
+session.
+
+```ts
+// agent/hooks/page-on-failure.ts
+import { defineHook } from "@cursor/july/hooks";
+
+export default defineHook({
+  events: {
+    async "turn.failed"(event, ctx) {
+      const pagerUrl = process.env.PAGER_WEBHOOK_URL;
+      if (
+        pagerUrl === undefined ||
+        ctx.session.purpose === "eval" ||
+        event.data.message === "turn interrupted"
+      ) {
+        return;
+      }
+      await fetch(pagerUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          agent: ctx.agent.name,
+          session: ctx.session.id,
+          channel: ctx.channel.id,
+          message: event.data.message,
+        }),
+        signal: AbortSignal.timeout(5_000),
+      });
+    },
+  },
+});
+```
 
-Failure alerting: `turn.failed` carries the message, and
-`ctx.session.id` points at the trace.
+### Mirror the transcript
 
-Derived state: persist ids that must survive hosted replace with
-`ctx.host.kv` or `ctx.host.files`. `stateRoot` resets on replace.
+Subscribe to `"*"` and write one file per event, skipping the
+`*.appended` deltas: they arrive per token, and `message.completed`
+carries the final text. Session scope keeps transcripts apart without a
+session id in the path. The mirror holds reasoning text and raw tool
+arguments and outputs, so pick the store accordingly, and write to your
+own store instead when you need cross-session queries.
 
-Transcript export: subscribe to `"*"` and append to your own store.
+```ts
+// agent/hooks/mirror.ts
+import { defineHook } from "@cursor/july/hooks";
+
+export default defineHook({
+  events: {
+    async "*"(event, ctx) {
+      if (event.type.endsWith(".appended")) {
+        return;
+      }
+      const name = String(event.index).padStart(6, "0");
+      await ctx.host.files.write(
+        `transcript/${name}.json`,
+        JSON.stringify(event)
+      );
+    },
+  },
+});
+```
+
+### Keep derived state across a replace
+
+Write it to `ctx.host.kv` under a session-prefixed key; a tool reads it
+back with `ctx.host.kv.get`.
+
+```ts
+// agent/hooks/last-result.ts
+import { defineHook } from "@cursor/july/hooks";
+
+export default defineHook({
+  events: {
+    async "turn.completed"(event, ctx) {
+      await ctx.host.kv.put(`last-result/${ctx.session.id}`, {
+        at: event.at,
+        result: event.data.result ?? null,
+      });
+    },
+  },
+});
+```
+
+## Test and debug a hook
+
+A hook definition is a plain object, so a unit test calls
+`hook.events["turn.completed"]` directly with an event and a stub
+`HookContext`. Discovery skips `*.test.ts`, so the test can live next to
+the hook.
+
+At runtime:
+
+- `agent-sdk validate --dir .` reports discovery errors and the
+  empty-handlers warning.
+- `agent-sdk info --dir . --json` lists the loaded hooks under
+  `agents[].hooks`.
+- Send a turn with `agent-sdk dev` or `agent-sdk run --dir . --message "…"`
+  and watch the serve log for
+  `hook "<name>" handler for <event> threw: …`. `run` prints that log on
+  stderr. On hosting, read it with [`agent-sdk logs`](/docs/reference/cli.md#logs).
 
 ## What's next
 
 Continue with these pages:
 
+- [Turn result](/docs/reference/result.md): fail a turn from `commit`, not from a hook
 - [Sessions and streaming](/docs/reference/sessions.md): the event vocabulary hooks observe
+- [Storage](/docs/storage.md): where `ctx.host.kv` and `ctx.host.files` live
 - [OpenTelemetry](/docs/guides/opentelemetry.md): OTLP traces and metrics
   from the same event stream
 - [Deployment](/docs/deployment.md#observability): runtime logs and export
@@ -8572,6 +9114,9 @@ Use the playground to chat, try channel routes, and inspect sessions.
   `/v1/dev/evals`). Schedule hand-dispatch still requires `--dev`.
 - **The surface**: inspect the discovered tools, skills, subagents, MCP
   connections, channels, and hooks.
+- **Custom tool chips**: drop `agent/playground/tools/<toolName>.tsx` to
+  change how that tool renders. Chips compile from the agent tree;
+  an [extension](/docs/reference/extensions.md) cannot contribute them.
 - **Raw events pane**: flip it on to inspect the event stream.
 - **Logs tab**: recent server log lines, polled from `GET /v1/logs`.
 - **A/Bs tab**: per-session and aggregate
@@ -8623,7 +9168,7 @@ experiments can override their file-derived name.
 | `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/extensions/ci.ts` | extension mount `ci`; its tools and skills become `ci__<name>` |
+| `agent/extensions/ci.ts` | extension mount `ci`; its contributions become `ci__<name>` |
 | `agent/extensions/notion.ts` | Cursor plugin mount `notion` (`cursorPlugin`); its skills, agents, and MCP servers become `notion__<name>` |
 | `agent/channels/drive.ts` | channel `drive`, routes under `/v1/channels/drive` |
 | `agent/ab.ts` | A/B experiment `ab` unless `name` overrides it |
@@ -8683,6 +9228,7 @@ Each path maps to a capability and a reference page.
 | `agent/ab.config.ts` | `defineABConfig` shared A/B settings | [Live A/B metrics](/docs/ab.md) |
 | `agent/storage.ts` | `defineStorage` backend for the durable `host.kv` / `host.files` APIs | [Storage](/docs/storage.md) |
 | `agent/artifacts.ts` | `defineArtifacts` kinds, the `tag_artifact` opt-in, and retention | [Artifacts](/docs/reference/artifacts.md) |
+| `agent/result.ts` | `defineResult` host `commit` on the final assistant text | [Turn result](/docs/reference/result.md) |
 | `agent/schedules/*` | Cron-driven runs (UTC, 5-field; never auto-fire under `--dev`) | [Schedules](/docs/reference/schedules.md) |
 | `agent/sandbox/workspace/**` | Seed files copied into each local session workspace | [Sessions](/docs/reference/sessions.md#what-goes-into-a-local-session-workspace) |
 | `agent/playground/` | Custom playground tool chips | [Playground](/docs/reference/playground.md) |
@@ -8769,6 +9315,100 @@ context: prompt.lines`
 
 ---
 
+Source: /docs/reference/result.md
+
+# Turn result
+
+Judgment agents need a place to act on the model's last message: parse
+it, then page, comment, or close a ticket. Author `agent/result.ts`
+with `defineResult` from `@cursor/july/result`. When that file exists,
+every finished turn runs `commit` on the serving host with the full
+assistant text.
+
+A thrown `commit` fails the turn. Empty assistant text fails it too.
+Hooks still observe only; they cannot fail a valid turn.
+
+Use this for an end-of-turn actuation. Mid-turn actions belong in
+[tools](/docs/reference/tools.md). Durable records that outlive a session belong in
+[artifacts](/docs/reference/artifacts.md).
+
+## Author `agent/result.ts`
+
+```ts
+import { defineResult } from "@cursor/july/result";
+import { applyDecision, parseDecision } from "./lib/actuate.js";
+
+export default defineResult({
+  async commit(ctx) {
+    if (ctx.session.purpose === "eval") {
+      return;
+    }
+    await applyDecision(parseDecision(ctx.text), ctx.host);
+  },
+});
+```
+
+`commit` is required. Parse `ctx.text` however the agent needs. Tell
+the model the document shape in `instructions.md`. The Agent SDK does
+not inject a schema.
+
+Put `result.ts` on the root agent only. A copy under a subagent is
+ignored with a warning.
+
+## Commit on the host
+
+`commit` runs in the serving process after the model finishes, before
+the turn completes. `ctx` is the same host surface a server tool gets,
+plus the turn text:
+
+| Member | What it is |
+| --- | --- |
+| `ctx.session` | The session that produced this turn, including `purpose` |
+| `ctx.host` | Shared host services (`kv`, `files`, `mcp`) |
+| `ctx.artifacts` | Session-bound [artifacts](/docs/reference/artifacts.md) facade |
+| `ctx.stateRoot` | The agent's durable state root |
+| `ctx.workspaceDir` | The session workspace |
+| `ctx.text` | The full assistant string |
+
+A dry-run session skips `commit` and still completes. Eval sessions do
+run `commit`; return early when `ctx.session.purpose === "eval"` if the
+handler must not actuate.
+
+On cloud runtime, the model still runs on the VM. `commit` runs on the
+serving host after the turn returns.
+
+`GET /v1/info` reports `result: true` when the file is authored.
+
+## Assert in evals
+
+`t.succeeded()` fails when `commit` throws or the turn produced no
+text, because those are turn failures. Read the document on `t.reply`.
+
+```ts
+import { defineEval, includes } from "@cursor/july/evals";
+
+export default defineEval({
+  async test(t) {
+    await t.send("Triage LIN-1842. It duplicates LIN-1801.");
+    t.succeeded();
+    t.check(t.reply, includes("duplicate"));
+  },
+});
+```
+
+## What's next
+
+Continue with these pages:
+
+- [Evals](/docs/evals.md): `t.succeeded` and `t.reply`
+- [Sessions and streaming](/docs/reference/sessions.md): `turn.completed` and
+  `turn.failed`
+- [Hooks](/docs/reference/hooks.md): observe the stream after the turn has already
+  settled
+- [Project layout](/docs/reference/project-layout.md): where `agent/result.ts` lives
+
+---
+
 Source: /docs/reference/schedules.md
 
 # Schedules and reminders
@@ -9081,7 +9721,9 @@ within one session. The `at` field is an ISO-8601 timestamp.
 
 Pair `actions.requested` with `action.result` to reconstruct the tool
 trajectory. Read `turn.completed.data.usage` for input, output, and
-cache token counts.
+cache token counts. When `agent/result.ts` is authored, a thrown
+`commit` or empty assistant text emits `turn.failed` instead of
+`turn.completed`. See [Turn result](/docs/reference/result.md).
 
 ## How do I stream or replay session events?
 
@@ -9338,8 +9980,7 @@ access to `process.env` and your `agent/lib/` code. Local turns call
 server tools as SDK custom tools. Cloud turns reach them over
 authenticated HTTP MCP back to the serve host when `--public-url` or
 `--cloud-tools-url` is set; without either, the server warns at startup
-and cloud turns omit them (see
-[Cloud runtime](/docs/guides/cloud-runtime.md#what-changes-on-cloud)).
+and cloud turns omit them.
 
 ```ts
 // agent/tools/inspect_pr.ts
@@ -10207,9 +10848,11 @@ Path is identity. Full list: README "Folder structure".
 | `agent/mcp-connections/<name>.ts` | MCP. Never name an account file `cursor.ts`. `advertiseTools: true` for named local tools |
 | `agent/host-connections/<name>.ts` | Privileged MCP for `ctx.host.mcp` / `mcp oauth` |
 | `agent/subagents/<id>/` | Child agent (`description` required) |
-| `agent/extensions/<ns>.ts` | Mounted extension or Cursor plugin (`cursorPlugin({ path })`); contributions are `<ns>__<name>` |
+| `agent/extensions/<ns>.ts` | Mounted extension or Cursor plugin (`cursorPlugin`); contributions are `<ns>__<name>` |
 | `agent/channels/*.ts` | Slack / GitHub / custom HTTP |
 | `agent/hooks/*.ts` | Observe-only |
+| `agent/artifacts.ts` | Durable tagged outputs (`defineArtifacts`) |
+| `agent/result.ts` | Host `commit` on the final assistant text (`defineResult`) |
 | `agent/ab.ts` or `agent/ab/*.ts` | Live A/B (`defineAB`) |
 | `agent/otel.ts` | OpenTelemetry (`defineOtel`) |
 | `agent/schedules/*` | Cron. Never auto-fire under `--dev` |
@@ -10563,9 +11206,13 @@ export default defineOtel({
 3. `serve(dir, { otel: { … } })`. `otel: false` disables env and
    authored config.
 
+Hosted v2 secrets arrive after bake. Use `defineOtel(() => …)` so flush
+re-resolves exporters. Authored `agent/otel.ts` records from process
+start even when the factory returns no exporters yet.
+
 | Signal | Default |
 | --- | --- |
-| Traces | on (`agent_sdk.http` → session → turn → tool / subagent) |
+| Traces | on (`agent_sdk.http`; `agent_sdk.turn` → tool / subagent) |
 | Metrics | on (`cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`) |
 | Logs | off (`logs: true` or `OTEL_LOGS_EXPORTER=otlp`) |
 
@@ -10581,8 +11228,9 @@ ctx.host.otel.record("abc.approval.duration_ms", 1420);
 ```
 
 Prefix names with team or agent. No custom spans. Join on
-`cursor.conversation.id` and `agent_sdk.agent`. Run `serve` as its
-own process when Agent SDK should own the destination.
+`agent_sdk.session_id` / `cursor.conversation.id` and
+`agent_sdk.agent`. Run `serve` as its own process when Agent SDK
+should own the destination.
 
 ---
 
@@ -11424,9 +12072,6 @@ Run it from the agent's git checkout. It infers repository, ref, path,
 and slug, builds on Cursor-managed hosting, and prints the URL.
 `agent-sdk deployments` shows status.
 
-See [Cloud runtime](/docs/guides/cloud-runtime.md) for what changes on
-the VM.
-
 ---
 
 Source: /docs/templates/security-help.md