@cursor/july 0.1.112 → 0.1.114

package/docs/guides/hooks.md

@@ -0,0 +1,116 @@
+---
+title: "Hooks"
+description: "Observe session events for metrics, alerts, and other side effects without changing the turn."
+---
+
+# Hooks
+
+Hooks observe session events after they are recorded and run side effects such
+as updating metrics or sending alerts. They never change the turn, prompt, or
+reply. Author them under `agent/hooks/` with `defineHook` from
+`@cursor/july/hooks`.
+
+## Meter token usage
+
+With [OpenTelemetry](./opentelemetry.md) configured, this hook adds a live
+turn's reported input and output tokens to your counters. Eval runs stay quiet,
+so the dashboard reflects live traffic instead of the test suite.
+
+```ts
+// agent/hooks/usage.ts
+import { defineHook } from "@cursor/july/hooks";
+
+export default defineHook({
+  events: {
+    async "turn.completed"(event, ctx) {
+      if (ctx.session.purpose === "eval") {
+        return;
+      }
+      if (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);
+    },
+  },
+});
+```
+
+## Alert on failure
+
+Set `PAGER_WEBHOOK_URL` to your pager's webhook. When a live turn fails, this
+hook posts the agent, session, and failure message there. Eval runs and
+interrupted turns stay quiet, so tests and preemptions do not page anyone.
+
+```ts
+// agent/hooks/page-on-failure.ts
+import { defineHook } from "@cursor/july/hooks";
+
+export default defineHook({
+  events: {
+    async "turn.failed"(event, ctx) {
+      if (ctx.session.purpose === "eval") {
+        return;
+      }
+      if (event.data.message === "turn interrupted") {
+        return;
+      }
+
+      const pagerUrl = process.env.PAGER_WEBHOOK_URL;
+      if (pagerUrl === undefined) {
+        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),
+      });
+    },
+  },
+});
+```
+
+## Events / when hooks run
+
+Use event names from the
+[session event vocabulary](../reference/sessions.md#stream-events). A hook
+receives each matching event after it is recorded, and the model does not wait
+for the handler.
+
+Within one session, handlers run one at a time. A slow handler delays later
+handlers for that session, but it does not delay the model or handlers for
+other sessions. Hooks also fire for evals, so check
+`ctx.session.purpose === "eval"` before metering or paging. A restart does not
+replay recorded events into hooks.
+
+## When not to use a hook
+
+| Want | Use instead |
+| --- | --- |
+| Add context before the model | `instructions.md`, skills, or `workspaceFiles` |
+| Deliver to Slack or a PR | Channel [`events`](../reference/channels.md#events) or packs |
+| Block or approve a tool | [`needsApproval`](../reference/tools.md#gate-a-tool-on-human-approval) |
+| Gate final assistant text | `defineResult` |
+| Gate behavior | [Evals](../evals.md) |
+
+[Cursor Agent hooks](https://cursor.com/docs/agent/hooks) in
+`.cursor/hooks.json` are a different product. They can observe, block, or
+modify the local agent loop.
+
+## Related
+
+- [Hooks reference](../reference/hooks.md): payloads, context, and discovery
+- [Sessions: stream events](../reference/sessions.md#stream-events): event
+  vocabulary and payload sequence
+- [OpenTelemetry](./opentelemetry.md): export traces and custom metrics
+- [Channels: events](../reference/channels.md#events): deliver replies back to
+  Slack, source control, or another surface

package/docs/guides/jev.md

@@ -0,0 +1,296 @@
+---
+title: "Jev"
+description: "Use typed Jev decisions to filter findings, route pull requests, and gate review actions."
+---
+
+# Use Jev in review tools
+
+Use Jev when a review workflow needs a typed decision instead of prose.
+A review agent can filter speculative findings, classify pull request
+risk, choose a reviewer, or decide whether a merge needs a documentation
+follow-up. Jev returns a choice, score, or probability; your TypeScript
+decides what happens next.
+
+Set `TYPESAFE_API_KEY`. The default model is `jev-latest`.
+
+```ts
+// agent/extensions/jev.ts
+import jev from "@cursor/july/extensions/jev";
+
+export default jev();
+```
+
+## Start only the review turns you need
+
+Call Jev from a channel hook before a model turn starts. When a pull
+request opens or becomes ready for review, this hook sends its title,
+body, labels, and filenames to Jev to decide whether the change needs
+security review. A result that clears the threshold starts the review
+turn; otherwise, the hook returns `null`, so the agent doesn't run or
+post to GitHub.
+
+```ts
+// agent/channels/github.ts
+import {
+  defaultGitHubAuth,
+  githubChannel,
+} from "@cursor/july/channels/github";
+import { above, decide } from "@cursor/july/extensions/jev";
+
+export default githubChannel({
+  botName: "security-reviewer",
+  cursorAccount: { repos: ["acme/checkout"] },
+  onPullRequest: async (ctx, pr) => {
+    if (pr.action !== "opened" && pr.action !== "ready_for_review") {
+      return null;
+    }
+
+    const octokit = await ctx.github.getOctokit();
+    const [{ data }, files] = await Promise.all([
+      octokit.rest.pulls.get({
+        owner: ctx.repository.owner,
+        repo: ctx.repository.name,
+        pull_number: pr.number,
+      }),
+      octokit.paginate(octokit.rest.pulls.listFiles, {
+        owner: ctx.repository.owner,
+        repo: ctx.repository.name,
+        pull_number: pr.number,
+      }),
+    ]);
+    const answers = await decide({
+      state: {
+        title: data.title,
+        body: data.body,
+        labels: data.labels.map(label => label.name),
+        files: files.map(file => file.filename),
+      },
+      questions: {
+        review: {
+          type: "boolean",
+          instructions:
+            "Does this change need security review? Answer yes for auth, permissions, secrets, request parsing, or external inputs.",
+        },
+      },
+    });
+
+    if (!above(answers.review, 0.8)) {
+      return null;
+    }
+    // `auth` starts a model turn running as the pull request sender.
+    return { auth: defaultGitHubAuth(ctx) };
+  },
+});
+```
+
+Jev receives only the pull request metadata shown here, not the diff.
+
+## Filter findings before you post them
+
+Let the chat model draft a finding, then ask Jev whether the finding is
+a real bug in the new code. Below your threshold, the tool returns and
+the author never sees the draft. Above it, the finding becomes a review
+comment.
+
+```ts
+// agent/tools/post_finding.ts
+import { parseGitHubPrContinuationKey } from "@cursor/july/channels/github";
+import { above, decide } from "@cursor/july/extensions/jev";
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description:
+    "Post one security finding on this session's pull request. Call once. Hold when it is not a real bug.",
+  inputSchema: z.object({
+    title: z.string(),
+    summary: z.string().describe("What the pull request changes."),
+    draft: z.string().describe("The finding to post, one or two sentences."),
+  }),
+  async execute({ title, summary, draft }, ctx) {
+    if (ctx.session.purpose === "eval") {
+      return { posted: false, reason: "eval" };
+    }
+
+    const ref = parseGitHubPrContinuationKey(ctx.session.continuationKey ?? "");
+    if (ref === undefined) {
+      throw new Error("post_finding requires a GitHub pull request session");
+    }
+
+    const answers = await decide({
+      state: { title, summary, draft },
+      questions: {
+        real: {
+          type: "boolean",
+          instructions:
+            "Is the draft an exploitable bug in the new code, not a style note or a hypothetical?",
+        },
+      },
+    });
+
+    if (!above(answers.real, 0.85)) {
+      return { posted: false, reason: "clean" };
+    }
+
+    const octokit = await ctx.host.github.getOctokit();
+    await octokit.rest.pulls.createReview({
+      owner: ref.owner,
+      repo: ref.repo,
+      pull_number: ref.number,
+      event: "COMMENT",
+      body: draft,
+    });
+    return {
+      posted: true,
+      pr: `${ref.owner}/${ref.repo}#${ref.number}`,
+    };
+  },
+});
+```
+
+## Approve changes by risk tier
+
+You can use the same pattern for Agentic Owners. Ask Jev to put the
+pull request in a closed set of risk tiers. Approve only a confident
+`very-low` or `low`; send everything else to a person.
+
+```ts
+import { decide, needsHuman } from "@cursor/july/extensions/jev";
+
+const answers = await decide({
+  state: { title, summary },
+  questions: {
+    risk: {
+      type: "choice",
+      instructions: "What risk tier is this pull request?",
+      criteria: {
+        "very-low": "docs, formatting, or a mechanical rename",
+        low: "a local change with tests and no new trust boundary",
+        medium: "auth, billing, or a behavior change callers depend on",
+        high: "a likely exploit, data loss, or a broken public contract",
+      },
+    },
+  },
+});
+
+const tier = answers.risk.choice;
+if (needsHuman(answers.risk) || tier === "medium" || tier === "high") {
+  return { verdict: "hold", tier };
+}
+return { verdict: "approve", tier };
+```
+
+Your GitHub tool resolves the pull request from `ctx.session` and posts
+that verdict. The model does not choose the repository, pull request, or
+approval event.
+
+## Open documentation follow-ups selectively
+
+After a pull request merges, a code-wiki agent can ask whether the
+change introduced a durable fact that belongs in the docs. A low
+probability skips the follow-up, while a high probability opens a
+documentation pull request.
+
+```ts
+import { above, decide } from "@cursor/july/extensions/jev";
+import { openDocsPullRequest } from "../lib/wiki";
+
+const answers = await decide({
+  state: { title, summary },
+  questions: {
+    updateDocs: {
+      type: "boolean",
+      instructions:
+        "Does this merge change a durable contract that the project docs should explain?",
+    },
+  },
+});
+
+if (!above(answers.updateDocs, 0.8)) {
+  return { action: "skip" };
+}
+return openDocsPullRequest({ title, summary });
+```
+
+## Write tools with Jev
+
+Call `decide` from a channel hook, server tool, or router when you want
+the answer map directly. Use `evaluate` when you want `{ answers }`.
+
+Use a boolean for a yes-or-no gate, a choice for a closed set such as
+risk tiers or owners, and a score for an ordered rubric. `above` returns
+`true` when a boolean probability or score meets the threshold.
+`needsHuman` returns `true` when a boolean probability or the selected
+choice's probability falls below the confidence threshold.
+
+Keep the questions atomic and combine them in TypeScript. For example,
+ask separately whether a finding is real, whether its impact is
+user-visible, and whether the changed line is new. Your code owns the
+rule that decides whether all three are enough to post.
+
+## Let the agent ask Jev
+
+Mounting the extension adds a read-only harness tool named
+`<namespace>__evaluate`. With the `agent/extensions/jev.ts` mount shown
+earlier, the model sees `jev__evaluate`.
+
+The tool accepts one state and a list of boolean, choice, or score
+questions. It returns `{ answers }` and never posts, approves, or opens
+a pull request. Use it when the agent needs the result during the turn.
+Use `decide` inside a project tool when the answer and the write belong
+in one operation.
+
+## Skills included with the extension
+
+The extension adds two skills by default:
+
+- `jev__questions` teaches the model how to structure atomic questions,
+  choose a question type, and read the answers.
+
+- `jev__gated-write` teaches the model to put `decide` and the write in
+  one server tool, hold on low confidence, and skip writes during evals.
+
+The model sees each skill's description and loads the full procedure
+when it applies.
+
+## Choose what to mount
+
+Both contribution groups are on by default. Turn off the harness tool
+when Jev should only run inside tools you wrote. Turn off the skills
+when your agent already has its own Jev instructions.
+
+```ts
+// agent/extensions/jev.ts
+import jev from "@cursor/july/extensions/jev";
+
+export default jev({
+  harnessTools: false,
+  skills: true,
+});
+```
+
+`harnessTools: false` removes `jev__evaluate` from discovery.
+`skills: false` removes both Jev skills. These switches do not remove
+the exported helpers, so project tools can still import `decide`,
+`above`, and `needsHuman`.
+
+## Practices
+
+- Pass the pull request title, a short summary, and the draft finding.
+  Don't send the checkout.
+
+- Calibrate `above` and `needsHuman` on pull requests you have already
+  labeled. `needsHuman` defaults to `0.7`.
+
+## Related
+
+- [Agentic owners](../templates/agentic-owners.md): a risk tier, then
+  the host approves or asks for reviewers
+- [Security reviewer](../templates/security-reviewer.md): a finding, or
+  no comment
+- [Thermo review](../templates/thermo-review.md): bugs and breakage,
+  posted the same way
+- [Code wiki](../reference/cli.md#init): documentation
+  follow-ups after a merge
+- [Evals](../evals.md): checks on the full turn
+- [GitHub agents](./github.md): how the review gets onto the pull request

package/docs/reference/agent-config.md

@@ -3,11 +3,11 @@ title: "Agent config"
 description: "defineAgent at agent/agent.ts: the model, the local and cloud runtimes, and serving programmatically."
 ---
 
-# Agent config (`agent/agent.ts`)
+# Agent config
 
-`agent/agent.ts` default-exports `defineAgent(config)`: which model runs
-the agent, where turns execute, and runtime-specific defaults.
-Everything is optional on the root agent.
+`agent/agent.ts` default-exports `defineAgent(config)`, which sets the
+model, execution runtime, and runtime-specific defaults. Every root
+config field is optional.
 
 ```ts
 import { defineAgent } from "@cursor/july";
@@ -27,9 +27,7 @@ export default defineAgent({
 });
 ```
 
-## Fields on `defineAgent`
-
-`defineAgent` accepts these fields.
+## Agent fields
 
 | Field | Type | Meaning |
 | --- | --- | --- |
@@ -38,14 +36,14 @@ export default defineAgent({
 | `description` | string | What the agent is for. Required on subagents; the parent model reads it to decide when to delegate. Documentation-only on the root. |
 | `instructions` | string | Inline instructions. Prefer `instructions.md`; this exists for subagents and generated configs. |
 | `runtime` | `"local"` or `"cloud"` | Where turns execute. Default `"local"`. |
-| `cloud` | object | Cloud agent defaults: repos, env, envVars, forwarded to the Cursor SDK. Used when `runtime` is `"cloud"`, and as the base merged under per-session `cloud` send options. |
+| `cloud` | object | Cloud agent defaults: repos, env, envVars. Used when `runtime` is `"cloud"`, and as the base merged under per-session `cloud` send options. |
 | `local` | `{ cwd?, workspaceDir?, sandbox? }` | Local harness defaults; ignored for cloud turns. See [Local options](#local-options). |
-| `hosting` | `{ egressDomains?, secretNames? }` | Managed-hosting declarations read by `agent-sdk deploy`: the pod's egress allowlist and the secret names the agent expects. Ignored by local serving. |
-| `concurrency` | `{ maxRunningTurns? }` | Engine-wide turn admission limit. See [Concurrency](#concurrency). |
+| `hosting` | `{ egressDomains?, secretNames? }` | `agent-sdk deploy` declarations for allowed egress domains and expected secret names. Ignored by local serving. |
+| `concurrency` | `{ maxRunningTurns? }` | Agent-wide turn admission limit. See [Concurrency](#concurrency). |
 | `builtinTools` | `{ reminders? }` | Framework-provided model-facing tools, opted in per capability. See [Built-in tools](#built-in-tools). |
-| `tools` | `ToolName[]` | Allowlist of built-in harness tools offered to the model. Unset = the model's full standard toolset. See [Allowlist built-in harness tools](#allowlist-built-in-harness-tools). |
+| `tools` | `ToolName[]` | Allowlist of built-in harness tools offered to the model. Unset = the model's full standard toolset. See [Harness tools](#harness-tools). |
 
-## Choose a model
+## Model
 
 `model` is a Cursor model id string, or `{ id, params }`. Effort and
 speed are params, not id suffixes. The SDK rejects suffix-style ids
@@ -67,24 +65,17 @@ A plain string works when you don't need params:
 model: "composer-2.5",
 ```
 
-## Choose a runtime
+## Runtime
 
-`runtime: "local"` (the default) runs turns on the Cursor SDK harness on
-this machine. Server tools, skills, sandbox seeds, and tool approvals
-all apply.
+`runtime: "local"` (the default) runs turns on this machine. Server
+tools, skills, sandbox seeds, and tool approvals all apply.
 
-`runtime: "cloud"` runs turns on Cursor cloud agents (`bc-…` ids). Pass
-a `cloud` block with the repos the VM carries. Server tools stay
-reachable over authenticated HTTP MCP back to the serve host when
-`--public-url` or `--cloud-tools-url` is set (omitted with a warning
-otherwise), and instructions and agent-tool catalogs are prepended to
-the first prompt, because the local session workspace is not the cloud
-VM.
+`runtime: "cloud"` runs turns on Cursor cloud agents. Pass a `cloud`
+block with the repositories the VM needs. See [Tools](./tools.md) for
+server- and agent-tool behavior on cloud turns.
 
-`validate` warns when `runtime: "cloud"` is combined with agent tools
-(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
+`validate` warns when `runtime: "cloud"` is combined with agent tools,
+when skills or sandbox seeds are present, and when the `cloud` block is
 missing.
 
 ## Local options
@@ -93,18 +84,15 @@ missing.
 
 `local.workspaceDir` points every session at one shared harness cwd,
 for agents that work inside an existing checkout. It takes precedence
-over `cwd`, and a per-send `workspaceDir` still wins over both. The SDK
-keys its local executor (rules, skills, MCP, ignore mappings) on the
-harness cwd, so a shared directory resolves the workspace once per
-serve process instead of once per session. The trade: sessions share a
-working tree, so a file one turn writes is visible to the next.
+over `cwd`, and a per-send `workspaceDir` still wins over both.
+Sessions share a working tree, so a file one turn writes is visible to
+the next.
 
 `local.sandbox` runs the harness inside Cursor's local sandbox. It's
-off by default, matching the SDK: shell then auto-approves and inherits
-the serve process environment, including any credentials the host
-holds. Turn it on for agents whose turns read untrusted input (webhook
-payloads, PR diffs, inbound chat); it's a real tool boundary rather
-than a prompt-level one.
+off by default: shell then auto-approves and inherits the serve process
+environment, including any credentials the host holds. Turn it on for
+agents whose turns read untrusted input (webhook payloads, PR diffs,
+inbound chat); it's a tool boundary, not a prompt-level one.
 
 ### Local cwd
 
@@ -120,13 +108,12 @@ does not leak rules, skills, or MCP servers into the turn. A standalone git
 root keeps the in-project session workspace. Point `cwd` at a checkout only
 when the agent should inherit that tree.
 
-## Allowlist built-in harness tools
+## Harness tools
 
 Use `tools` to limit which built-in Cursor harness tools the model can
 call. Omit it to keep the standard toolset. When you set it, the model
 gets only the tools you list. An empty list disables all native
-built-in tools. Because this field is an allowlist, new platform tools
-stay disabled until you add them.
+built-in tools. New platform tools stay disabled until you add them.
 
 ```ts
 export default defineAgent({
@@ -137,12 +124,13 @@ export default defineAgent({
 });
 ```
 
-The Agent SDK always adds `"mcp"` to a configured allowlist. Authored
-server tools in `agent/tools/` use MCP to reach the model. MCP can also
-expose declared connections and servers from the harness directory's
-ambient `.cursor` config. To exclude a checkout's MCP servers, point
-`local.cwd` outside the checkout. See [Local cwd](#local-cwd).
-`local.sandbox` makes MCP tool calls fail closed.
+The Agent SDK always adds `"mcp"` to a configured allowlist, because
+authored server tools in `agent/tools/` reach the model over MCP. MCP
+can also expose declared connections and servers from the harness
+directory's ambient `.cursor` config. To exclude a checkout's MCP
+servers, point `local.cwd` outside the checkout. See
+[Local cwd](#local-cwd). `local.sandbox` makes MCP tool calls fail
+closed.
 
 Use the SDK's public tool names, including `"shell"`, `"read"`,
 `"edit"`, `"grep"`, `"glob"`, `"ls"`, and `"task"`. Unknown names
@@ -159,8 +147,7 @@ Two names have broader effects:
 Tool allowlists work only with the local runtime. A
 `runtime: "cloud"` agent that sets `tools` fails at serve startup.
 The Agent SDK also refuses per-send cloud sessions from a hybrid agent
-with an allowlist. It won't run those sessions with unrestricted tool
-access.
+with an allowlist.
 
 The allowlist controls which tools the model can call. It does not
 isolate the serve host. For agents that process untrusted input, also
@@ -168,10 +155,10 @@ set `local: { sandbox: true }`.
 
 ## Cloud options
 
-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 (the `cloud` option on
+The `cloud` block sets default repositories (each
+`{ url, startingRef? }`), environment selection, and `envVars`. A local
+agent uses the same block as the base config when a channel opens a
+cloud-attached session per send (the `cloud` option on
 [`send`](./channels.md#handler-arguments)).
 
 ## Concurrency
@@ -194,9 +181,8 @@ export default defineAgent({
 ## Built-in tools
 
 `builtinTools` opts into framework-provided model-facing tools. Each
-enabled capability materializes as ordinary server tools at discovery
-time, so turns, direct calls, `info`, and the playground treat them
-like authored tools. Authored tools with the same name win, with a
+enabled capability shows up as ordinary server tools, so turns, direct
+calls, `info`, and the playground treat them like authored tools. Authored tools with the same name win, with a
 warning, and like all server tools they run on the local runtime.
 
 `builtinTools: { reminders: true }` adds three tools bound to the
@@ -205,22 +191,6 @@ current conversation over `host.reminders`: `reminders_create`,
 continuation key can't arm reminders. See
 [Schedules and reminders](./schedules.md#reminders).
 
-## Generate instructions
-
-When the system prompt must be computed, author `agent/instructions.ts`
-instead of markdown:
-
-```ts
-import { defineInstructions } from "@cursor/july";
-
-export default defineInstructions({
-  markdown: `You are the on-call assistant for ${process.env.TEAM_NAME}.`,
-});
-```
-
-The directory form and the runtime mapping are in
-[Instructions](./instructions.md).
-
 ## Serve programmatically
 
 `serve(dirOrProject, options)` embeds the server in your own process:
@@ -230,7 +200,7 @@ import { serve } from "@cursor/july";
 
 const handle = await serve("./my-agent", {
   port: 3000,
-  apiKey: process.env.CURSOR_API_KEY, // optional; see credential order
+  apiKey: process.env.CURSOR_API_KEY,
 });
 console.log(`listening on ${handle.url}`);
 // handle.callTool(...), handle.dispatchSchedule("heartbeat"),
@@ -239,17 +209,14 @@ console.log(`listening on ${handle.url}`);
 
 Host settings match the documented [CLI](./cli.md) `serve` flags.
 `serve()` also accepts `discovery` (project-loading options) and
-`mode: "single" | "multi"`. The Cursor credential resolves in one order
-everywhere: explicit `apiKey`, then `CURSOR_API_KEY`, then
-`CURSOR_API_KEY_FILE` (hosted default `/run/cursor/secrets/CURSOR_API_KEY`
-when unset), then `CURSOR_SERVICE_ACCOUNT_KEY`, then the key stored by
-`agent-sdk login`. On a host that has both the service-account key and a
-bind file, the file principal wins.
-
-## What's next
+`mode: "single" | "multi"`. Pass `apiKey` or use the same Cursor
+credential as the CLI: `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`,
+`CURSOR_SERVICE_ACCOUNT_KEY`, or `agent-sdk login`.
 
-Continue with these pages:
+## Related
 
 - [Instructions](./instructions.md): the required half of a minimal
   agent
 - [CLI](./cli.md): the `serve` flags `serve()` accepts
+- [Sessions](./sessions.md): workspaces, identifiers, and turn admission
+- [Schedules](./schedules.md): reminder tools opted in here