npm - @cursor/july - Versions diffs - 0.1.113 → 0.1.114 - Mend

@cursor/july 0.1.113 → 0.1.114

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (229) hide show

package/dist/playground/index.html CHANGED Viewed

@@ -8,8 +8,8 @@
     />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>agent-serve playground</title>
-    <script type="module" crossorigin src="./assets/index-De_lpFxE.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-DSMAewbx.css">
+    <script type="module" crossorigin src="./assets/index-CrMWlgUU.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-C61EWMBK.css">
   </head>
   <body>
     <div id="root"></div>

package/docs/deployment.md CHANGED Viewed

@@ -191,7 +191,7 @@ per-caller and channel-specific auth.
 Use `agent-sdk logs --prod` for runtime output,
 [OpenTelemetry](./guides/opentelemetry.md) for traces and metrics, and
-[session traces](./reference/sessions.md#how-do-i-inspect-a-saved-event-stream)
+[session traces](./reference/sessions.md#inspect-a-saved-event-stream)
 for one conversation.
 ## Related

package/docs/guides/agent-to-agent.md CHANGED Viewed

@@ -76,8 +76,8 @@ await ctx.host.mcp.callTool("weather", "check", {
 });
 ```
-The peer owns this session. Follow-ups stay on the specialist and leave
-the concierge's conversation unchanged.
+The peer owns this session, so follow-ups continue the specialist's
+context.
 ## Call a deterministic peer tool
@@ -122,14 +122,13 @@ complete agent you would also run, inspect, or expose on its own.
 ## Affinity
-Follow-up `ask` and `check` calls resume the same specialist session
-and run as the caller. Those turns show up in the peer's playground;
-only that caller can continue or check the session.
+Those turns show up in the peer's playground. Only the session owner
+can continue or check them.
 ## Practices
-- Give each caller a one-way routing rule so agent A cannot send work
-  to B and receive the same request back.
+- Give each caller a one-way routing rule, and don't configure reciprocal
+  routes for the same request.
 - Prefer `ask` when the specialist should reason. Use `call_tool` when
   host code already knows which server tool to run.
@@ -140,12 +139,12 @@ only that caller can continue or check the session.
 ## Other hosts
-Peers need the default multi-agent layout and one shared process;
-unknown slugs and self-references fail at startup.
+Peers require the default multi-agent layout; unknown slugs and
+self-references fail at startup.
-For a self-hosted caller, expose the shared process with `--public-url`
-and protect it with `--bearer-token`. The
-[Deployment guide](../deployment.md) owns that hosting setup.
+If a cloud-runtime turn needs a self-hosted peer, set `--public-url` to
+the shared host's reachable URL and protect it with `--bearer-token`.
+The [Deployment guide](../deployment.md) owns that hosting setup.
 ## Related

package/docs/guides/cloud-agents.md CHANGED Viewed

@@ -11,7 +11,7 @@ agent, keep talking while it works, inspect the result, and steer or
 stop the same branch.
 This is different from choosing
-[`runtime: "cloud"`](../reference/agent-config.md#choose-a-runtime).
+[`runtime: "cloud"`](../reference/agent-config.md#runtime).
 That setting moves this agent's turns to a cloud VM; this extension lets
 the agent delegate separate coding tasks.

package/docs/guides/grokbot-agents.md CHANGED Viewed

@@ -142,5 +142,5 @@ directory and disable that tool. See
   overlays
 - [Tool approvals](../reference/tools.md#gate-a-tool-on-human-approval):
   approve asks
-- [Agent config](../reference/agent-config.md#choose-a-runtime): local
+- [Agent config](../reference/agent-config.md#runtime): local
   and hosted runtimes

package/docs/guides/hooks.md ADDED Viewed

@@ -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 CHANGED Viewed

@@ -1,19 +1,15 @@
 ---
 title: "Jev"
-description: "Use typed Jev decisions to filter review findings, route pull requests, and gate software-factory writes."
+description: "Use typed Jev decisions to filter findings, route pull requests, and gate review actions."
 ---
 # Use Jev in review tools
-Use Jev for narrow decisions where your software factory needs a typed
-answer, not another paragraph. 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.
-Ask one question per judgment. If an approval depends on risk, test
-coverage, and the size of the change, ask three questions in one call
-and combine the answers in code.
+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`.
@@ -26,11 +22,12 @@ export default jev();
 ## Start only the review turns you need
-You can call Jev from a channel hook before a model turn starts. When a
-pull request opens, this hook reads its title, labels, and filenames,
-then asks whether the change needs security review. A high probability
-starts the review. Otherwise the hook returns `null`, so the agent does
-not run and nothing is posted to GitHub.
+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
@@ -86,8 +83,7 @@ export default githubChannel({
 });
 ```
-Only pull request metadata goes to Jev here. The review turn still reads
-the diff itself.
+Jev receives only the pull request metadata shown here, not the diff.
 ## Filter findings before you post them
@@ -192,8 +188,8 @@ approval event.
 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 means no follow-up. A high probability opens a documentation
-pull request instead of turning every merge into churn.
+probability skips the follow-up, while a high probability opens a
+documentation pull request.
 ```ts
 import { above, decide } from "@cursor/july/extensions/jev";
@@ -218,14 +214,14 @@ return openDocsPullRequest({ title, summary });
 ## Write tools with Jev
-`decide` is a regular async host function. Call it from a channel hook,
-server tool, or router. It returns the answer map directly. `evaluate`
-makes the same request and returns `{ answers }`.
+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` checks
-a boolean probability or score. `needsHuman` checks whether a boolean
-or the selected choice clears your confidence bar.
+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
@@ -235,8 +231,8 @@ 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 default `jev` filename, the model sees
-`jev__evaluate`.
+`<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
@@ -278,59 +274,6 @@ export default jev({
 the exported helpers, so project tools can still import `decide`,
 `above`, and `needsHuman`.
-## Jev and trajectory evals
-An eval checks a whole turn: the agent called the read, and it stayed
-off approve. `decide` is the one call inside the tool, before GitHub.
-Use the [Evals guide](../evals.md) when you want the turn to keep
-behaving. Use `decide` when the tool itself needs a tier or a yes.
-## Test without the live API
-Pass `fetch` and `apiKey` and the same `decide` path runs in a test.
-```ts
-import { decide } from "@cursor/july/extensions/jev";
-const answers = await decide({
-  state: {
-    title: "Skip the refund auth check",
-    summary: "acme/checkout#42 drops the session check on POST /refunds.",
-  },
-  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",
-      },
-    },
-  },
-  apiKey: "sk-test",
-  fetch: async () =>
-    new Response(
-      JSON.stringify({
-        answers: {
-          risk: {
-            type: "choice",
-            choice: "high",
-            probabilities: {
-              "very-low": 0.02,
-              low: 0.05,
-              medium: 0.18,
-              high: 0.75,
-            },
-          },
-        },
-      }),
-      { status: 200 }
-    ),
-});
-```
 ## Practices
 - Pass the pull request title, a short summary, and the draft finding.

package/docs/reference/agent-config.md CHANGED Viewed

@@ -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