@cursor/july 0.1.102 → 0.1.103

package/docs/reference/extensions.md

@@ -1,15 +1,20 @@
 ---
 title: "Extensions"
-description: "Mount a package of tools and skills or a Cursor plugin under a namespace with one file, adjust what it contributes, and author your own as a directory laid out like agent/."
+description: "Mount a package of agent contributions or a Cursor plugin under a namespace with one file, adjust what it contributes, and author your own as a directory laid out like agent/."
 ---
 
 # 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
 
@@ -36,6 +41,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/`](./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
@@ -47,15 +94,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
@@ -119,8 +186,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](./tools.md) and [Skills](./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/
@@ -132,6 +199,10 @@ authoring forms as [Tools](./tools.md) and [Skills](./skills.md).
 │   └── retry_job.ts
 ├── skills/
 │   └── triage.md
+├── hooks/
+│   └── audit.ts
+├── mcp-connections/
+│   └── buildkite.ts
 └── lib/
     └── buildkite.ts    # shared code, never discovered
 ```
@@ -181,17 +252,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
 

package/docs/reference/hooks.md

@@ -5,56 +5,119 @@ description: "Observe-only subscribers to the session event stream: audit logs,
 
 # 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.
-
-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.
+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.
+
+## 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](./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](./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](./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](./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](../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](./schedules.md), the same API tools get |
+| `ctx.artifacts` | Session-bound [artifacts](./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.
+
+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.
 
-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.
+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?
 
@@ -62,37 +125,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`](../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](../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](../guides/github.md#show-pr-progress) |
+| Block, approve, or rewrite a tool call | [`needsApproval`](./tools.md#gate-a-tool-on-human-approval) on the tool |
+| Act on the final assistant text, or fail a bad turn | [`defineResult`](./result.md) |
+| Gate a change on behavior | [Evals](../evals.md) |
+| Compare two prompts on live traffic | [`defineAB`](../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),
+      });
+    },
+  },
+});
+```
+
+### 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
 
-Failure alerting: `turn.failed` carries the message, and
-`ctx.session.id` points at the trace.
+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.
 
-Derived state: persist ids that must survive hosted replace with
-`ctx.host.kv` or `ctx.host.files`. `stateRoot` resets on replace.
+At runtime:
 
-Transcript export: subscribe to `"*"` and append to your own store.
+- `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`](./cli.md#logs).
 
 ## What's next
 
 Continue with these pages:
 
+- [Turn result](./result.md): fail a turn from `commit`, not from a hook
 - [Sessions and streaming](./sessions.md): the event vocabulary hooks observe
+- [Storage](../storage.md): where `ctx.host.kv` and `ctx.host.files` live
 - [OpenTelemetry](../guides/opentelemetry.md): OTLP traces and metrics
   from the same event stream
 - [Deployment](../deployment.md#observability): runtime logs and export

package/docs/reference/playground.md

@@ -32,6 +32,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](./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

package/docs/reference/project-layout.md

@@ -21,7 +21,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 |
@@ -81,6 +81,7 @@ Each path maps to a capability and a reference page.
 | `agent/ab.config.ts` | `defineABConfig` shared A/B settings | [Live A/B metrics](../ab.md) |
 | `agent/storage.ts` | `defineStorage` backend for the durable `host.kv` / `host.files` APIs | [Storage](../storage.md) |
 | `agent/artifacts.ts` | `defineArtifacts` kinds, the `tag_artifact` opt-in, and retention | [Artifacts](./artifacts.md) |
+| `agent/result.ts` | `defineResult` host `commit` on the final assistant text | [Turn result](./result.md) |
 | `agent/schedules/*` | Cron-driven runs (UTC, 5-field; never auto-fire under `--dev`) | [Schedules](./schedules.md) |
 | `agent/sandbox/workspace/**` | Seed files copied into each local session workspace | [Sessions](./sessions.md#what-goes-into-a-local-session-workspace) |
 | `agent/playground/` | Custom playground tool chips | [Playground](./playground.md) |

package/docs/reference/result.md

@@ -0,0 +1,94 @@
+---
+title: "Turn result"
+description: "Run host code on the final assistant text when a turn finishes. Throw to fail the turn."
+---
+
+# 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](./tools.md). Durable records that outlive a session belong in
+[artifacts](./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](./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](../evals.md): `t.succeeded` and `t.reply`
+- [Sessions and streaming](./sessions.md): `turn.completed` and
+  `turn.failed`
+- [Hooks](./hooks.md): observe the stream after the turn has already
+  settled
+- [Project layout](./project-layout.md): where `agent/result.ts` lives

package/docs/reference/sessions.md

@@ -94,7 +94,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](./result.md).
 
 ## How do I stream or replay session events?
 

package/docs/reference/tools.md

@@ -19,8 +19,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](../guides/cloud-runtime.md#what-changes-on-cloud)).
+and cloud turns omit them.
 
 ```ts
 // agent/tools/inspect_pr.ts

package/docs/templates/pr-autofixer.md

@@ -123,6 +123,3 @@ agent-sdk deploy
 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](../guides/cloud-runtime.md) for what changes on
-the VM.