@cursor/july 0.1.102 → 0.1.103

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)
 
 ---
 
@@ -1100,8 +1098,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 +2697,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 +3006,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 +3447,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 +3473,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 +3528,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
 
 ---
 
@@ -4106,7 +3981,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 +4298,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 +4307,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 +4379,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 +4397,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 +4424,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 +4440,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 +5467,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 +5493,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 +5972,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 +6061,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 +6139,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 +6401,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,13 +6477,21 @@ 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.
@@ -6619,10 +6523,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 +7800,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 +7836,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 +7889,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 +7981,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 +7994,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 +8047,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 +8069,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).
+
+`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.
 
-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.
+## 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 +8189,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:
 
-Failure alerting: `turn.failed` carries the message, and
-`ctx.session.id` points at the trace.
+### Alert on failure
 
-Derived state: persist ids that must survive hosted replace with
-`ctx.host.kv` or `ctx.host.files`. `stateRoot` resets on replace.
+`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.
 
-Transcript export: subscribe to `"*"` and append to your own store.
+```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),
+      });
+    },
+  },
+});
+```
+
+### Mirror the transcript
+
+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.
+
+```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 +8708,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 +8762,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 +8822,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 +8909,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 +9315,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 +9574,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 +10442,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 +10800,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 +10822,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 +11666,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