@cursor/july 0.1.111 → 0.1.113

package/dist/docs/troubleshooting.md

@@ -1,110 +1,141 @@
 # Fix common agent problems
 
-Start with four checks, in order:
+Start with three checks:
 
-1. Project discovery: `agent-sdk validate --dir .`
-2. Whether the serve process is running
-3. What the playground or HTTP API shows
-4. The session event stream (trace)
+1. Run `agent-sdk validate --dir .`.
+2. Confirm the expected agent and connections in
+   `agent-sdk info --dir . --json`.
+3. Reproduce once, then inspect the serve log or session trace.
 
-Match your symptom below. Keep the commands as `agent-sdk`. If it is
-not on `PATH`, use `npx @cursor/july`.
+Match the visible symptom below. If `agent-sdk` is not on `PATH`, use
+`npx @cursor/july`.
 
-## What if serve or the playground looks wrong?
+## Serve or the playground will not work
 
 | What you see | What to do |
 | --- | --- |
-| `serve` won't start | Run `agent-sdk validate --dir .` and fix the reported errors. |
-| Playground is blank or says there are no agents | The UI needs a running `serve` process. Building the playground assets alone is not enough. |
-| The playground UI looks stale | `serve --dev` prints a playground URL. Open that URL. Agent-file edits still need a restart (press Enter on the TTY). |
-| Sessions exist but the playground list is empty | The list shows sessions for the authenticated caller. In `--dev` on loopback the list is wider. Otherwise open `/<slug>/playground?sessionId=ses_…`. |
-| Port 3000 is already in use | For the default serve port, the CLI tries the next free port and prints a notice. Pass `--port` to pick one, or `--port 0` for any free port. Stop leftover playground or webhook-forwarder processes if you need the original port. |
+| `serve` exits before listening | Fix the errors from `agent-sdk validate --dir .`, then start it again. |
+| Playground is blank or says there are no agents | Start `agent-sdk serve`; built playground assets have no agent data without the server. |
+| Agent-file edits do not appear | Open the URL printed by `serve --dev`, then press Enter in its TTY to reload after file changes. |
+| Sessions exist but the list is empty | The list is scoped to the authenticated principal. Use the same identity that created the session; a `?sessionId=` deep link does not bypass authorization. |
+| The preferred port is busy | Use the next port printed by the CLI, pass `--port <number>`, or pass `--port 0` for any free port. |
 
-## What if a model turn goes wrong?
+## A model turn fails
 
 | What you see | What to do |
 | --- | --- |
-| Built-in file reads and greps fail; the turn retries for a long time | Run under Node 22.13+ (or `tsx`), never Bun. Look for `NGHTTP2_FRAME_SIZE_ERROR` in logs. |
-| The turn fails immediately with an API-key error | Sign in with `agent-sdk login`, or set `CURSOR_API_KEY` or `CURSOR_SERVICE_ACCOUNT_KEY`. Discovery, `info`, `call`, and serve bring-up work without a key; model turns need one. |
-| Replies quote rules or `AGENTS.md` from outside your agent project | The session workspace inherited parent-folder config. Nested git checkouts default `local.cwd` to a per-project cache directory under `~/.cache`. Point `defineAgent({ local: { cwd } })` at a checkout only when the agent should inherit that tree, or set `--state-root` to a clean directory (for example under `/tmp`). |
-| Yellow box shows Datadog/Linear tools, but the model lists `GetDynamicTools` / IDE `cursor` tools and never calls them | Attached MCP sits behind harness meta-tools, or the harness cwd is still inside another checkout. Set `advertiseTools: true` for named tools on local turns. Check `GET /v1/info` `local.cwd` and `connections[].advertiseTools`. |
-| Server tools, skills, or workspace seed files never appear | Server tools and sandbox seeds apply on the local runtime (cloud server tools need `--public-url` / `--cloud-tools-url`). Skills reach cloud through the Agent Store when hosting or a personal `CURSOR_API_KEY` is available; otherwise only skills already in the cloud repo. `validate` warns when this combination is present. |
-| `validate` and `run` succeed, but typecheck fails in CI | The CLI runs TypeScript with type-stripping only. Keep tool `execute` return types as object literals or `type` aliases, not `interface` types. |
-| Login works, but turns are rejected when using custom API hosts | Point login and model traffic at the same host (`CURSOR_API_BASE_URL` and `CURSOR_BACKEND_URL`). A key from one host is rejected by the other. |
+| File reads and greps fail repeatedly with `NGHTTP2_FRAME_SIZE_ERROR` | Run the agent under Node 22.13 or newer, never Bun. |
+| The turn immediately reports a missing API key | Set `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`, or `CURSOR_SERVICE_ACCOUNT_KEY`, or run `agent-sdk login`. |
+| Login succeeds but the model host rejects the key | Point login and model traffic at the same API host; check `CURSOR_API_BASE_URL` and `CURSOR_BACKEND_URL`. |
+| Cloud turns cannot reach local tools or skills | Give the cloud runtime a reachable `--public-url` and protected tool bridge, or move the required capability into the cloud checkout. See [agent runtime](/docs/reference/agent-config.md#choose-a-runtime). |
 
-## What if the HTTP API returns an error?
+## A turn behaves unexpectedly
 
 | What you see | What to do |
 | --- | --- |
-| `409` on a follow-up message | Refresh the `continuationToken` or confirm the session is a chat session. Task sessions do not accept follow-ups. |
-| `409 session_busy` on `call --session` | The tool is a write (or declares no effect) and a model turn is running. Wait for the turn to finish, omit `--session` for a one-off call, or declare `effect: "read"` on a tool that only reads so it runs alongside turns. |
-| `403` on stream or follow-up | Use the same auth identity that created the session. Off localhost, pass `--bearer-token` and send it on every request. |
-| Works on localhost; blocked through a tunnel or LAN | Default auth allows only direct loopback callers. Share the host with `--bearer-token <secret>` (or authored `bearerAuth`). Use `--allow-anonymous` only on a trusted private network. |
-| A channel route fails to compile with a schema type error | `GET` routes need a Zod `querySchema`. `POST` / `PUT` / `PATCH` need a Zod `bodySchema`. Use `z.object({})` or `z.unknown()` for open shapes. |
+| Replies quote an ancestor `AGENTS.md` or unrelated repository rules | Inspect `local.cwd` in `/v1/info`. Set `defineAgent({ local: { cwd } })` or the session workspace explicitly instead of inheriting the parent checkout. |
+| The model lists IDE meta-tools but never calls named MCP tools | Set `advertiseTools: true` on the local model-visible connection and confirm it under `connections` in `/v1/info`. |
+| Server tools, skills, or seed files are absent | Check the selected local/cloud runtime and discovered project in `/v1/info`; follow the capability warning from `validate`. |
+| `validate` and `run` pass but CI type-checking fails | Run the project type check. Tool results must be JSON-shaped; prefer object literals or `type` aliases over `interface` return types. |
 
-## What if GitHub webhooks misbehave?
+## HTTP returns 401, 403, or 409
 
 | What you see | What to do |
 | --- | --- |
-| `github forward` returns 401 on every delivery, but the hook was created | Clear `GITHUB_TOKEN` and `GH_TOKEN` for that command. The forwarder uses your `gh` CLI login: `GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward …` |
-| `Hook already exists` when starting a forwarder | GitHub allows one forwarder per repo. Run a single `github forward --dir <parent>` and stop stale forwarders. |
-| Deliveries rejected outside `--dev` | Set `GITHUB_WEBHOOK_SECRET` on the server and on the signer. Without a secret, the channel stays loopback-only. |
-| You lack repo admin and can't forward | Use `agent-sdk github replay <pr-url>`. It needs pull access only and posts signed test payloads. |
+| `401` outside localhost | Send the configured bearer token, alias token, or channel credential. Default custom routes admit direct loopback only. |
+| `403` on a stream or follow-up | Use the same authenticated principal that created the session. |
+| A localhost route fails through a tunnel or LAN | Protect the shared host with `--bearer-token` or authored channel auth. Use `--allow-anonymous` only behind a proxy that authenticates every caller. |
+| `409` on a follow-up | Refresh the rotating `continuationToken` and confirm the target is a chat session; task sessions do not accept follow-ups. |
+| `409 session_busy` from `call --session` | Wait for the turn, omit `--session`, or mark a read-only tool with `effect: "read"` so it can run concurrently. |
+| A custom route fails schema type-checking | Add the required Zod `querySchema` for `GET`, or `bodySchema` for `POST`, `PUT`, and `PATCH`. See [Channels](/docs/reference/channels.md). |
 
-## What if Slack stays quiet?
+## A hosted deployment fails or looks stale
 
 | What you see | What to do |
 | --- | --- |
-| Logs show `channel idle … missing credentials` | Expected when tokens are missing. Run `agent-sdk slack create --dir <agent>` to provision the app and write the tokens, or `agent-sdk slack init --manual --dir <agent>` and paste the manifests at api.slack.com. Then set `<PREFIX>_SLACK_BOT_TOKEN` and `<PREFIX>_SLACK_APP_TOKEN` per agent and run `agent-sdk slack doctor --prefix <PREFIX>`. |
-| `slack create` reports the app needs admin approval | Open Slack's **Request approval** page (the CLI prints the link; the same URL is **Send a reminder** after you submit). Managed install does not file the request. Keep the CLI running, then click **Retry** in the dashboard after an admin approves. |
-| The bot ignores ordinary channel posts | Default engagement is mentions and DMs only. Enable `engagement.channelPosts` with an allowlist, and subscribe the app to `message.channels` / `message.groups`. |
-| Approve / Deny buttons do nothing | Channels that post approval cards need `toolApprovals: true`. Recreate the app with `slack create` if interactivity is off. |
+| Local changes do not appear after deploy | `deploy` reads a pushed Git ref, not the working tree. Commit and push the intended ref, then deploy it again. |
+| The deployment never becomes running | Run `agent-sdk deployment <slug>` and `agent-sdk logs --prod --slug <slug>`, then act on the reported build or startup error. |
+| A secret or egress change has no effect | Confirm the name with `secrets list`, verify the `hosting` block exists on the pushed ref, and follow the CLI or dashboard prompt to redeploy. |
+| Cursor events stopped after redeploy | Redeploy replaces CLI-supplied event repositories. Pass every `--cursor-events-repo` value again. |
+| External HTTP rejects the alias token | Update the caller with the current token. If the token is lost or exposed, run `agent-sdk rotate-token <slug>` and replace it everywhere. |
 
-## What if host MCP OAuth fails?
+See [Deployment](/docs/deployment.md) for source, credential, and
+redeployment boundaries.
+
+## GitHub deliveries fail
+
+| What you see | What to do |
+| --- | --- |
+| `github forward` returns 401 on every delivery after creating the hook | Clear `GITHUB_TOKEN` and `GH_TOKEN` for that command so the forwarder uses the `gh` CLI login: `GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward ...`. |
+| `Hook already exists` | Run one forwarder for the repository and stop the stale process. |
+| Direct webhook deliveries are rejected outside `--dev` | Configure the same `GITHUB_WEBHOOK_SECRET` on the signer and server. Cursor event pull needs no public webhook or webhook secret. |
+| You cannot create a forwarder | Use `agent-sdk github replay <pr-url>`; it needs pull access instead of repository administration. |
+
+The [GitHub guide](/docs/guides/github.md) covers event pull, replay, and
+direct webhooks.
+
+## Slack does not respond
 
 | What you see | What to do |
 | --- | --- |
-| `must be defineConnection({ url, oauth: true })` | The connection file needs `oauth: true`, or you passed the wrong connection name to `agent-sdk mcp oauth`. |
-| Local auth works; hosted calls unauthorized | Finish Connect on the hosted engine, or run `agent-sdk mcp oauth <name> --store`. Confirm names with `agent-sdk secrets list <slug>`, then redeploy. |
-| Model asks for `mcp_auth` or IDE MCP for a connector it already has | Attached MCP is behind meta-tools. Set `advertiseTools: true` for named tools on local turns, or call it from a host tool via `ctx.host.mcp`. |
+| Logs say `channel idle ... missing credentials` | Run `agent-sdk slack create --dir <agent>`, then check the generated prefix with `agent-sdk slack doctor`. Use `slack init --manual` only for an app you own. |
+| `slack create` is waiting for workspace approval | Open the approval link printed by the CLI, keep the command running, and retry after an admin approves. |
+| The bot ignores ordinary channel posts | Configure `engagement.channelPosts`, create the app with `--channel-posts`, and invite it to every allowed channel. |
+| Approval buttons do nothing | Set `toolApprovals: true`, then recreate the app if its interactivity is not enabled. |
 
-See [Host MCP OAuth](/docs/guides/mcp-oauth.md) and
-[`skills/mcp-auth/SKILL.md`](https://github.com/cursor/cursor/blob/main/packages/agent-serve/skills/mcp-auth/SKILL.md).
+See the [Slack guide](/docs/guides/slack.md) for app setup and engagement
+choices.
 
-## What if a secret showed up in a terminal transcript?
+## MCP authorization fails
 
 | What you see | What to do |
 | --- | --- |
-| `secrets set … NAME=VALUE` in an agent-captured terminal or shell history | Rotate the secret at the provider. Set it again with names only: `agent-sdk secrets set <slug> NAME` (hidden prompt) or pipe/redirect the value. `NAME=VALUE` requires `--from-argv` and still leaks into argv. |
-| Alias token printed during first deploy or `rotate-token` | Treat it as exposed if the transcript left your machine. Run `agent-sdk rotate-token <slug>`, store the new token outside agent transcripts, and update callers. |
-| Someone verified a secret with `echo` / `printenv` | Rotate it. Confirm presence with `agent-sdk secrets list <slug>` (names only), then redeploy and test the feature. |
+| `must be defineConnection({ url, oauth: true })` | Add `oauth: true` to the named URL connection or correct the connection filename passed to `mcp oauth`. |
+| Local auth works but hosted calls return unauthorized | Complete Connect for the running process, or run `mcp oauth <name> --store` and redeploy for future replacements. |
+| The model invents `mcp_auth` instead of calling the server | Set `advertiseTools: true` for named local tools, or expose a host-side wrapper through `ctx.host.mcp`. |
 
-## What if schedules, reminders, or approvals stall?
+See [Host MCP OAuth](/docs/guides/mcp-oauth.md) for the credential lifecycle.
+
+## Schedules, reminders, or approvals stall
+
+| What you see | What to do |
+| --- | --- |
+| A schedule or reminder never fires under `--dev` | Trigger it through the matching `/v1/dev/schedules/<id>` or `/v1/dev/reminders/<id>` route; development mode does not auto-fire. |
+| A pending approval disappears after restart | Parked approvals do not survive restart. Run the turn again. |
+| A reminder is disarmed with `handler_lost_on_restart` | Recreate handler-form reminders after restart, or use a prompt-form reminder. |
+| The same schedule fires on several self-hosted processes | Enable schedules on one serving process per project and pass `--no-schedules` to the others. |
+
+## A credential was exposed
 
 | What you see | What to do |
 | --- | --- |
-| A schedule or reminder never fires under `--dev` | Dev mode does not auto-fire. Trigger with `POST /<slug>/v1/dev/schedules/<id>` or `POST /<slug>/v1/dev/reminders/<id>` (list reminders at `GET /v1/dev/reminders`). |
-| A pending tool approval disappeared after restart | Parked approvals do not survive host restart. They resolve as interrupted. Run the turn again. |
-| A reminder is disarmed after restart (`handler_lost_on_restart`) | Handler-form reminders live in memory. Re-arm them from the code that created them, or use prompt-form reminders. |
+| A secret value appears in a command, transcript, or shell history | Rotate it at the provider, set it again through hidden input or stdin, and test the feature. |
+| An alias token appears outside its secure destination | Run `agent-sdk rotate-token <slug>`, store the new value outside transcripts, and update every caller. |
+| Someone printed a secret to verify it | Rotate it. Confirm only the name with `agent-sdk secrets list <slug>`, then redeploy and exercise the feature. |
+
+## Read the session trace
 
-## How do I read a session trace?
+Start with `actions.requested` and `action.result`. Count calls by tool
+name, pair every request with its result, and separate host preparation
+from tools chosen by the model.
 
-Look at `actions.requested` / `action.result` pairs for the tool
-trajectory. Count calls by tool name before blaming latency. Separate
-host-side work (channel `callTool`, preparation) from tools the model
-chose.
+`turn.failed` with `turn interrupted` usually means a follow-up or stop
+ended the turn deliberately. Other failures should have an error event
+near the tool or model boundary that produced them.
 
-`turn.failed` with `"turn interrupted"` means a follow-up or stop ended
-the turn on purpose.
+Use the trace path printed by `agent-sdk run`:
 
-If the model reads outside the session workspace, the prepared files
-don't match what the instructions expect. Fix the layout. See
-[Hillclimbing](/docs/hillclimbing.md).
+```bash
+agent-sdk trajectory --events <trace-path>
+```
 
-`agent-sdk trajectory --events <file>` summarizes any saved NDJSON
-stream. The playground **Open trace** control does the same visually.
+The playground's **Open trace** control renders the same trajectory.
+When the agent runs but makes poor decisions, move from diagnosis to a
+measured [hillclimb](/docs/hillclimbing.md).
 
-## What's next
+## Related
 
-- [Hillclimbing](/docs/hillclimbing.md): when the agent runs but underperforms
-- [Deployment](/docs/deployment.md): auth and state on shared hosts
+- [Deployment](/docs/deployment.md): hosted and self-hosted boundaries
+- [Sessions](/docs/reference/sessions.md): session ownership and event
+  vocabulary
+- [CLI reference](/docs/reference/cli.md): command flags and exit behavior

package/dist/extensions/cursor-cloud-agents/skills/handoff.md

@@ -16,17 +16,13 @@ The result carries `agentId` (`bc-...`) and a `url`. Report both in full. Never
 
 ## Look an agent up by id
 
-Call `get` with the `agent_id`. It returns the agent's `status` (`creating`, `running`, `finished`, `error`, or `expired`), its `branch` and pull request `prUrl` once pushed, the `changes` it made so far (files and lines), a `summary` when one exists, and an `error` when it failed. A run takes minutes: check when asked or when you need the result, not in a tight loop. The final report itself comes from `dump`.
+Call `get` with the `agent_id`. It returns the agent's `status` (`creating`, `running`, `finished`, `error`, `expired`, or `unknown`), its `branch` and pull request `prUrl` once pushed, change counts, a `summary` when one exists, and an `error` when it failed. A run takes minutes: check when asked or when you need the result, not in a tight loop. The final report itself comes from `dump`.
 
 ## Read what it did
 
-To read the report or understand what was done, call `dump` with the `agent_id`. It writes the agent's whole conversation, every run, to `cloud-agent-transcripts/<agent_id>.jsonl` in your workspace and returns the absolute `path` plus the `finalMessage`. Each line is one JSON message with `role` (`user` or `assistant`) and, for assistant lines, `text`, `thinking`, and `toolCalls` (tool `name`, `args`, `content`, `error`). Read it with your file and shell tools, using the returned path:
+To read the report or understand what was done, call `dump` with the `agent_id`. Once a transcript exists, it writes the agent's whole conversation to `cloud-agent-transcripts/<agent_id>.jsonl` in your workspace and returns the absolute `path` plus `finalMessage`. Before any transcript exists, either value may be absent; wait for output instead of inventing a report.
 
-- `tail -n 1 <path>` gives the final report.
-- `grep '"toolCalls"' <path>` shows the commands and edits it made.
-- `grep '"role":"user"' <path>` shows every prompt it received, including replies.
-
-Use `dump` before summarizing an agent's work for a person, and to understand a failure before replying with a fix.
+Use `finalMessage` as the agent's report. Read the returned transcript path when you need its prompts, reasoning, or tool calls, then inspect the resulting branch or pull request before claiming exact code changes. The transcript is evidence of what the agent did, not a canonical diff.
 
 ## Reply
 

package/dist/extensions/improve/extension.d.ts

@@ -3,7 +3,9 @@
  * repository, so changing how it behaves is a change to that source: a
  * one-off Cursor cloud agent does the coding on a branch and opens a pull
  * request, the agent that mounted this writes the brief and reports the
- * pull request, and the tree it runs from is never edited.
+ * pull request. Durable behavior changes only after review, merge, and
+ * deployment. A cloud-runtime turn may edit its ephemeral checkout while
+ * preparing the pull request.
  *
  * ```ts
  * // agent/extensions/improve.ts

package/dist/extensions/improve/extension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../src/extensions/improve/extension.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,yGAAyG;IACzG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,oDAAoD;AACpD,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,QAAA,MAAM,OAAO,EAAE,SAAS,CAAC,aAAa,EAAE,cAAc,CAgBpD,CAAC;eAEY,OAAO"}
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../src/extensions/improve/extension.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,+FAA+F;IAC/F,IAAI,EAAE,MAAM,CAAC;IACb,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,yGAAyG;IACzG,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,oDAAoD;AACpD,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,QAAA,MAAM,OAAO,EAAE,SAAS,CAAC,aAAa,EAAE,cAAc,CAgBpD,CAAC;eAEY,OAAO"}

package/dist/extensions/improve/extension.js

@@ -3,7 +3,9 @@
  * repository, so changing how it behaves is a change to that source: a
  * one-off Cursor cloud agent does the coding on a branch and opens a pull
  * request, the agent that mounted this writes the brief and reports the
- * pull request, and the tree it runs from is never edited.
+ * pull request. Durable behavior changes only after review, merge, and
+ * deployment. A cloud-runtime turn may edit its ephemeral checkout while
+ * preparing the pull request.
  *
  * ```ts
  * // agent/extensions/improve.ts
@@ -27,7 +29,7 @@ import { defineExtension } from "../../extensions.js";
 const line = z.string().trim().min(1);
 const improve = defineExtension({
     root: import.meta.dirname,
-    description: "Change your own source through a one-off cloud agent and a pull request, never the running tree.",
+    description: "Propose changes to your own source through a branch and pull request; durable behavior changes after review and deployment.",
     config: z.object({
         repo: z.string().url(),
         path: z

package/dist/extensions/improve/skills/yourself.js

@@ -23,7 +23,7 @@ Under \`${path}/agent/\`:
 ${treeNotes}
 ## The change is made on a clean checkout
 
-Never edit the tree you run from: it is a deployed copy of \`${path}\`, and nothing changed there lasts. The change is made on a clean checkout of ${repo} at \`${ref}\`. When your own turn runs on a cloud VM with that repository checked out, that VM is the checkout: branch there. Otherwise hand the coding to a one-off Cursor cloud agent through the cloud agents extension, with \`launch\` under its mount namespace, \`repo\` set to ${repo}, and \`starting_ref\` to \`${ref}\`. One agent per change; steer it with \`reply\` rather than launching another.
+Durable source changes happen on a branch from a clean checkout of ${repo} at \`${ref}\`, never by mutating a deployed local-runtime copy. When your own turn runs on a cloud VM with that repository checked out, its ephemeral tree is the checkout: branch there. Otherwise hand the coding to a one-off Cursor cloud agent through the cloud agents extension, with \`launch\` under its mount namespace, \`repo\` set to ${repo}, and \`starting_ref\` to \`${ref}\`. One agent per change; steer it with \`reply\` instead of launching another.
 
 ## The brief
 

package/dist/extensions/jev/extension.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Jev decisions as an extension. Mount it and the agent can ask Jev for
+ * typed boolean, choice, and score answers, then call `decide` from your
+ * own channel hooks and tools before they start a turn or write.
+ *
+ * ```ts
+ * // agent/extensions/jev.ts
+ * import jev from "@cursor/july/extensions/jev";
+ *
+ * export default jev();
+ * ```
+ *
+ * Contributes `<namespace>__evaluate` plus the `questions` and
+ * `gated-write` skills (the namespace is the mount filename). Auth is
+ * `TYPESAFE_API_KEY`. The default model is `jev-latest`. Custom tools
+ * import `decide`, `above`, and `needsHuman` from this same module. Set
+ * `harnessTools` or `skills` to false when the agent should not see those
+ * contributions.
+ */
+import type { Extension } from "../../types.js";
+/** Mount options; every field is optional. */
+export interface JevOptions {
+    /** TypeSafe API key. Defaults to `TYPESAFE_API_KEY`. */
+    apiKey?: string;
+    /** TypeSafe model id. Defaults to `jev-latest`. */
+    model?: string;
+    /** Mount the namespaced `evaluate` harness tool. Defaults to true. */
+    harnessTools?: boolean;
+    /** Mount the `questions` and `gated-write` skills. Defaults to true. */
+    skills?: boolean;
+}
+/** {@link JevOptions} with defaults applied. */
+export interface JevConfig {
+    apiKey?: string;
+    model: string;
+    harnessTools: boolean;
+    skills: boolean;
+}
+declare const jev: Extension<JevConfig, JevOptions | undefined>;
+export type { AnswersFor, BooleanAnswer, BooleanQuestion, ChoiceAnswer, ChoiceQuestion, EvaluateArgs, EvaluateResult, EvaluationAnswer, EvaluationQuestion, EvaluationState, QuestionMap, ScoreAnswer, ScoreQuestion, } from "./lib/evaluate.js";
+export { above, DEFAULT_EVALUATION_MODEL, DEFAULT_HUMAN_THRESHOLD, decide, evaluate, needsHuman, } from "./lib/evaluate.js";
+export default jev;
+//# sourceMappingURL=extension.d.ts.map

package/dist/extensions/jev/extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../src/extensions/jev/extension.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,wEAAwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,gDAAgD;AAChD,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CACjB;AAiBD,QAAA,MAAM,GAAG,EAAE,SAAS,CAAC,SAAS,EAAE,UAAU,GAAG,SAAS,CAQpD,CAAC;AAEH,YAAY,EACV,UAAU,EACV,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,WAAW,EACX,aAAa,GACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,EACL,wBAAwB,EACxB,uBAAuB,EACvB,MAAM,EACN,QAAQ,EACR,UAAU,GACX,MAAM,mBAAmB,CAAC;eAEZ,GAAG"}

package/dist/extensions/jev/extension.js

@@ -0,0 +1,47 @@
+/**
+ * Jev decisions as an extension. Mount it and the agent can ask Jev for
+ * typed boolean, choice, and score answers, then call `decide` from your
+ * own channel hooks and tools before they start a turn or write.
+ *
+ * ```ts
+ * // agent/extensions/jev.ts
+ * import jev from "@cursor/july/extensions/jev";
+ *
+ * export default jev();
+ * ```
+ *
+ * Contributes `<namespace>__evaluate` plus the `questions` and
+ * `gated-write` skills (the namespace is the mount filename). Auth is
+ * `TYPESAFE_API_KEY`. The default model is `jev-latest`. Custom tools
+ * import `decide`, `above`, and `needsHuman` from this same module. Set
+ * `harnessTools` or `skills` to false when the agent should not see those
+ * contributions.
+ */
+import { z } from "zod";
+import { defineExtension } from "../../extensions.js";
+import { DEFAULT_EVALUATION_MODEL } from "./lib/evaluate.js";
+const config = z
+    .object({
+    apiKey: z.string().min(1).optional(),
+    model: z.string().min(1).optional(),
+    harnessTools: z.boolean().default(true),
+    skills: z.boolean().default(true),
+})
+    .default({})
+    .transform(options => { var _a; return ({
+    apiKey: options.apiKey,
+    model: (_a = options.model) !== null && _a !== void 0 ? _a : DEFAULT_EVALUATION_MODEL,
+    harnessTools: options.harnessTools,
+    skills: options.skills,
+}); });
+const jev = defineExtension({
+    root: import.meta.dirname,
+    description: "Ask Jev for typed choice, score, and boolean answers.",
+    config,
+    contributions: options => ({
+        tools: options.harnessTools,
+        skills: options.skills,
+    }),
+});
+export { above, DEFAULT_EVALUATION_MODEL, DEFAULT_HUMAN_THRESHOLD, decide, evaluate, needsHuman, } from "./lib/evaluate.js";
+export default jev;

package/dist/extensions/jev/lib/evaluate.d.ts

@@ -0,0 +1,101 @@
+/**
+ * System One decisions for Agent SDK host code.
+ *
+ * Chat models write. {@link evaluate} asks Jev for typed choice / score /
+ * boolean answers over shared state. Call it from a project tool, a
+ * router, or other host code after mounting `@cursor/july/extensions/jev`.
+ * Do not set Jev as the `defineAgent` turn model.
+ *
+ * ```ts
+ * import { evaluate, decide, above, needsHuman } from "@cursor/july/extensions/jev";
+ *
+ * const { answers } = await evaluate({
+ *   state: draft,
+ *   questions: {
+ *     route: {
+ *       type: "choice",
+ *       instructions: "Which queue should handle this?",
+ *       criteria: {
+ *         billing: "charges, invoices, refunds",
+ *         shipping: "delivery",
+ *         technical: "bugs and outages",
+ *       },
+ *     },
+ *     post: {
+ *       type: "boolean",
+ *       instructions: "Is this safe to post publicly?",
+ *     },
+ *   },
+ * });
+ *
+ * if (needsHuman(answers.route) || !above(answers.post, 0.85)) {
+ *   return { action: "review" };
+ * }
+ * ```
+ *
+ * Auth is `TYPESAFE_API_KEY`. `model` is a TypeSafe id (`jev-latest` by
+ * default).
+ */
+/** TypeSafe model used when {@link EvaluateArgs.model} is omitted. */
+export declare const DEFAULT_EVALUATION_MODEL = "jev-latest";
+/** Default bar for {@link needsHuman} when the caller does not pass one. */
+export declare const DEFAULT_HUMAN_THRESHOLD = 0.7;
+export type EvaluationState = string | Record<string, unknown> | readonly unknown[];
+export type BooleanQuestion = {
+    type: "boolean";
+    instructions: string;
+};
+export type ChoiceCriterion = string | readonly string[] | {
+    includes: readonly string[];
+} | null;
+export type ChoiceQuestion<C extends Record<string, ChoiceCriterion> = Record<string, ChoiceCriterion>> = {
+    type: "choice";
+    instructions: string;
+    criteria: C;
+};
+export type ScoreQuestion = {
+    type: "score";
+    instructions: string;
+    criteria: readonly string[];
+};
+export type EvaluationQuestion = BooleanQuestion | ChoiceQuestion | ScoreQuestion;
+export type QuestionMap = Record<string, EvaluationQuestion>;
+export type BooleanAnswer = {
+    type: "boolean";
+    probability: number;
+};
+export type ChoiceAnswer<C extends Record<string, unknown> = Record<string, unknown>> = {
+    type: "choice";
+    choice: keyof C & string;
+    probabilities: {
+        [K in keyof C]: number;
+    };
+};
+export type ScoreAnswer = {
+    type: "score";
+    score: number;
+    probabilities: Record<string, number>;
+};
+export type EvaluationAnswer = BooleanAnswer | ChoiceAnswer | ScoreAnswer;
+export type AnswerFor<Q> = Q extends BooleanQuestion ? BooleanAnswer : Q extends ChoiceQuestion<infer C> ? ChoiceAnswer<C> : Q extends ScoreQuestion ? ScoreAnswer : never;
+export type AnswersFor<Q extends QuestionMap> = {
+    [K in keyof Q]: AnswerFor<Q[K]>;
+};
+export type EvaluateResult<Q extends QuestionMap = QuestionMap> = {
+    answers: AnswersFor<Q>;
+};
+export type EvaluateArgs<Q extends QuestionMap = QuestionMap> = {
+    model?: string;
+    state: EvaluationState;
+    questions: Q;
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+};
+/** Ask Jev for typed answers over one state. */
+export declare function evaluate<const Q extends QuestionMap>(args: EvaluateArgs<Q>): Promise<EvaluateResult<Q>>;
+/** Same as {@link evaluate}, returning only `answers`. */
+export declare function decide<const Q extends QuestionMap>(args: EvaluateArgs<Q>): Promise<AnswersFor<Q>>;
+export declare function above(answer: BooleanAnswer | ScoreAnswer, threshold: number): boolean;
+export declare function needsHuman(answer: BooleanAnswer | ChoiceAnswer, threshold?: number): boolean;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/extensions/jev/lib/evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../../../src/extensions/jev/lib/evaluate.ts"],"names":[],"mappings":"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"}