@cursor/july 0.1.102 → 0.1.103

package/dist/docs/reference/hooks.md

@@ -1,55 +1,118 @@
 # 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](/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.
+
+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?
 
@@ -57,37 +120,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),
+      });
+    },
+  },
+});
+```
+
+### 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`](/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