@cursor/july 0.1.111 → 0.1.113

package/docs/guides/improve.md

@@ -1,25 +1,24 @@
 ---
 title: "Self-improvement"
-description: "Mount improve so an agent can change its own instructions, skills, and tools through a pull request a one-off cloud agent opens."
+description: "Let an agent propose a change to its own source through a branch and pull request, with review and deployment kept separate."
 ---
 
 # Self-improvement
 
-The `improve` extension lets an agent change how it behaves by changing
-its own source. Someone asks it to answer more briefly, to stop reaching
-for a tool, or to learn a procedure. The agent writes a brief, a one-off
-Cursor cloud agent makes the change on a branch and opens a pull
-request, and the agent reports that pull request. Nothing changes until
-a person reviews it and deploys.
+The `improve` extension teaches an agent how to turn "change how you
+work" into a source change. The agent prepares a brief, a Cursor cloud
+agent edits a checkout and opens a pull request, and the running agent
+reports the verified PR for human review.
 
-The tree the agent runs from is never edited; nothing changed there
-survives a deploy. The pull request is the only path.
+Durable behavior does not change until that source is merged and
+deployed. A cloud-runtime turn may edit its ephemeral checkout, but it
+does not rewrite the source of a running deployment.
 
 ## Mount it
 
-The extension ships with `@cursor/july`. It relies on a
-[`cursor-cloud-agents`](./cloud-agents.md) mount beside it, with the
-agent's own repository among its `cloud.repos`.
+On the local runtime, mount Cloud agents with the agent's own repository
+allowlisted, keep launch approval explicit, then mount `improve` with
+the source directory.
 
 ```ts
 // agent/extensions/cloud.ts
@@ -27,8 +26,15 @@ import cursorCloudAgents from "@cursor/july/extensions/cursor-cloud-agents";
 
 export default cursorCloudAgents({
   cloud: {
-    repos: [{ url: "https://github.com/acme/agents", startingRef: "main" }],
+    repos: [
+      {
+        url: "https://github.com/acme/agents",
+        startingRef: "main",
+      },
+    ],
+    autoCreatePR: true,
   },
+  needsApproval: true,
 });
 ```
 
@@ -39,58 +45,105 @@ import improve from "@cursor/july/extensions/improve";
 export default improve({
   repo: "https://github.com/acme/agents",
   path: "agents/concierge",
+  ref: "main",
 });
 ```
 
-`repo` is the repository that holds the agent's source and `path` is
-the agent's directory in it, the same values `agent-sdk deploy --repo`
-and `--path` take. Mount it as `improve`: the skill then reads
-`improve__yourself`, which is what a person asks for.
-
-An agent on the
-[cloud runtime](../reference/agent-config.md#choose-a-runtime) already
-runs each turn on a VM with the repository checked out. It mounts
-`improve` alone, and the skill has it branch in that checkout instead of
-launching a second agent.
-
-## What the agent does
-
-With the extension mounted, "change how you work" becomes a procedure:
-
-- **Locate the change.** The skill maps the ask onto the Agent SDK tree:
-  instructions for the always-on prompt, a skill for a procedure, a tool
-  for behavior that must be right every time, `agent.ts` for the model.
-- **Brief a cloud agent.** The agent writes a self-contained brief: who
-  is asking and why, the repository, ref, and path, the files it expects
-  to change, your notes about the tree, and the rules. Follow the
-  repository's conventions, keep the diff to the change, run the
-  repository's checks, open a pull request against the deployed ref,
-  never merge.
-- **Follow up and report.** It gives the person the cloud agent's URL,
-  checks on the run, reads the pull request before repeating its claims,
-  and reports the pull request, not the delegation. It says the change
-  takes effect at the next deploy, never that it has changed already.
-
-Ask it directly. "Improve yourself: stop opening with a summary" is
-enough.
+Mounted as `improve`, the extension contributes the
+`improve__yourself` skill. It does not contribute a tool that can bypass
+the normal repository workflow.
+
+## Ask for one behavioral change
+
+State the change, how to tell it worked, and what behavior must stay
+fixed. The agent maps the request to instructions, a skill, a tool,
+channel configuration, or the model setting before preparing the coding
+brief.
+
+> Improve yourself: stop opening incident replies with a summary.
+> Start with the decision, keep the existing evidence bullets, and
+> preserve every current eval.
+
+The success criterion and freeze line keep the cloud agent from turning
+a narrow behavior request into an unrelated refactor.
+
+## Follow the source change
+
+On local runtime, the agent requests approval and launches one cloud
+agent on the configured repository and ref. It reports the complete
+cloud-agent ID and URL immediately, then checks the same run instead of
+launching another agent for follow-up work.
+
+When the cloud agent opens a pull request, the running agent reads the
+result and the PR before reporting what changed and which checks passed.
+The pull request, not the delegation transcript, is the durable
+deliverable.
+
+Use the [Cloud agents guide](./cloud-agents.md) for launch, status,
+transcript, steering, and cancellation behavior.
+
+## Review, merge, then deploy
+
+The workflow stops at a pull request. A human reviews the diff and
+decides whether to merge it; a separate deployment action decides when
+the new behavior becomes live.
+
+This separation gives each boundary a real control:
+
+- Repository permissions limit who can push the branch.
+- Branch protection and review policy govern the merge.
+- Deployment authorization governs the running agent.
+
+After deployment, repeat the original request or regression eval to
+confirm the behavior changed without crossing the freeze line.
+
+## Use it from a cloud-runtime agent
+
+When the agent's own turn already runs on a cloud VM with the source
+repository checked out, mount `improve` without the Cloud agents
+extension. The skill branches and edits that ephemeral checkout, then
+opens the same reviewable pull request.
+
+Cloud-runtime tool approvals are unavailable. Repository permissions,
+branch protection, human review, and separate deployment remain the
+hard controls.
 
 ## Configure it
 
-| Option | What it controls |
-| --- | --- |
-| `repo` | The repository holding the agent's source. One of the cloud mount's `cloud.repos`. |
-| `path` | The agent's directory in the repository, as `agent-sdk deploy --path` names it. |
-| `ref` | The ref the deployment tracks. Branches start there and pull requests target it. Defaults to `main`. |
-| `notes` | What a coding agent must know about this tree beyond the standard layout: a house skill format, a manifest that forces a reinstall, a pull request convention. Copied into every brief. |
-| `deploy` | Who deploys a merged change and when it is live. Defaults to "It takes effect at the next deploy." |
+- `repo` is the source repository URL.
+- `path` is the agent's repository-relative directory.
+- `ref` is the deployed branch or ref that new branches and pull
+  requests target; it defaults to `main`.
+- `notes` adds tree-specific guidance to every coding brief, such as a
+  required test command or PR convention.
+- `deploy` tells the skill who deploys a merged change and when it
+  becomes live.
 
-## What's next
+`notes` and `deploy` insert prose into the contributed skill. They do
+not run checks, merge a branch, or trigger a deployment.
 
-Continue with these pages:
+Validation checks the URL and path shape. It does not prove the source
+exists, matches the current deployment, or appears in the Cloud agents
+repository allowlist, so keep those values aligned yourself.
+
+## What the extension enforces
+
+`improve__yourself` is model guidance for locating the change, writing a
+brief, following repository rules, opening a PR, and reporting it. Rules
+such as "never merge" are instructions, not framework-enforced
+permissions.
+
+Use repository and deployment controls for hard enforcement. The
+extension provides a repeatable path through those controls; it does not
+replace them.
+
+## What's next
 
-- [Cursor cloud agents](./cloud-agents.md): the mount that does the
-  coding, and how to gate its launches
-- [Extensions](../reference/extensions.md): how mounts, namespaces, and
-  overrides work
-- [Deployment](../deployment.md): how a merged change reaches the
-  running agent
+- [Cloud agents](./cloud-agents.md): delegation and steering on local
+  runtime
+- [Build with a coding agent](../building-with-agents.md): have an
+  external coding agent edit the project directly
+- [Extensions](../reference/extensions.md): namespaces and overlays
+- [Deployment](../deployment.md): make a merged source change live
+- [Evals](../evals.md): protect the requested behavior before and after
+  the change

package/docs/guides/jev.md

@@ -0,0 +1,353 @@
+---
+title: "Jev"
+description: "Use typed Jev decisions to filter review findings, route pull requests, and gate software-factory writes."
+---
+
+# 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.
+
+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
+
+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.
+
+```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) };
+  },
+});
+```
+
+Only pull request metadata goes to Jev here. The review turn still reads
+the diff itself.
+
+## 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 means no follow-up. A high probability opens a documentation
+pull request instead of turning every merge into churn.
+
+```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
+
+`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 }`.
+
+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.
+
+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 default `jev` filename, 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`.
+
+## 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.
+  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