@cursor/july 0.1.112 → 0.1.113

package/dist/docs/llms-full.txt

@@ -366,6 +366,9 @@ This smoke case asks for a PR verdict, requires the read-only inspection
 tool, and fails if the agent tries to approve. The CLI reports all three
 decisions together instead of stopping at the first miss.
 
+Use the [Jev extension](/docs/guides/jev.md) when host code needs a typed
+choice, score, or boolean before it writes.
+
 ```ts
 // evals/readiness.eval.ts
 import { defineEval, includes } from "@cursor/july/evals";
@@ -606,32 +609,21 @@ moves the freeze line instead of proving the change.
 
 Source: /docs/guides/agent-to-agent.md
 
-# Agent-to-agent
+# Peer agents
 
 A peer connection lets one agent ask another agent on the same host for
 help. The specialist keeps its own instructions, tools, and session,
 while the caller decides when to delegate and returns the answer to the
-user.
-
-## How do I wire two agents?
+user. Co-host both projects under one `agent-sdk` process.
 
-Put both projects under one directory, then point the concierge at the
-specialist's mount slug. When a user asks about weather, the concierge
-calls the peer's `ask` tool, the weather agent runs in its own context,
-and the concierge returns that answer.
+## Delegate a question to a specialist
 
-```text
-agents/
-  concierge/
-    agent/instructions.md
-    agent/mcp-connections/weather.ts
-  weather-agent/
-    agent/agent.ts
-    agent/instructions.md
-```
+Ask the concierge about the weather and it hands the question to the
+specialist. The weather agent answers in its own context, then the
+concierge returns that answer to you.
 
 ```ts
-// agents/concierge/agent/mcp-connections/weather.ts
+// agent/mcp-connections/weather.ts
 import { defineConnection } from "@cursor/july/connections";
 
 export default defineConnection({
@@ -644,7 +636,7 @@ Give the concierge a narrow routing rule:
 
 ```md
 When a request needs current weather, ask the `weather` peer. Return its
-answer without delegating the same request again.
+answer.
 ```
 
 ```bash
@@ -653,58 +645,69 @@ agent-sdk chat --url http://127.0.0.1:3000/concierge \
   --message "What's the weather in Paris right now?"
 ```
 
-The connection filename becomes the MCP server name. The `agent` value
-is the specialist's mount slug, normally its directory name.
+The connection filename is the MCP server name the concierge calls, and
+`agent` is the specialist's mount slug, normally its directory name.
 
-## Continue the specialist's conversation
+## Continue the specialist's session
 
-The first `ask` returns a peer `sessionId`. Pass that ID into the next
-`ask` when the specialist should remember its earlier work instead of
-starting with fresh context.
+Ask a follow-up about the same forecast and the specialist picks up
+where it left off, with its own instructions and tool history still in
+place. The first `ask` returns `{ status, sessionId, reply }` as text on
+the `callTool` result. Parse `sessionId` and pass it on the next `ask`
+so the peer remembers its earlier work instead of starting fresh.
 
-```json
-{
-  "message": "How does that compare with tomorrow?",
-  "sessionId": "<session-id>"
+```ts
+const first = await ctx.host.mcp.callTool("weather", "ask", {
+  message: "What's the weather in Paris right now?",
+});
+const firstText = first.content.find((part) => part.type === "text");
+if (firstText?.text === undefined) {
+  throw new Error("weather ask returned no text payload");
 }
-```
-
-The peer owns this session. Follow-ups resume its instructions and tool
-history without merging them into the concierge's conversation.
+const { sessionId } = JSON.parse(firstText.text) as { sessionId: string };
 
-## Wait for long-running specialist work
+await ctx.host.mcp.callTool("weather", "ask", {
+  message: "How does that compare with tomorrow?",
+  sessionId,
+});
+```
 
-`ask` waits for a bounded time. If the specialist is still working, it
-returns `status: "running"` with the session ID, allowing the caller to
-do other work and check again later.
+If the specialist is still working, `ask` returns `status: "running"`
+with the session ID, and you can do other work before calling `check`.
 
-```json
-{
-  "sessionId": "<session-id>",
-  "waitSeconds": 20
-}
+```ts
+await ctx.host.mcp.callTool("weather", "check", {
+  sessionId,
+  waitSeconds: 20,
+});
 ```
 
-Call the peer's `check` tool with that input. It returns the final reply
-when the turn settles, or another running status when more time is
-needed.
+The peer owns this session. Follow-ups stay on the specialist and leave
+the concierge's conversation unchanged.
 
 ## Call a deterministic peer tool
 
-When the specialist has a server tool and no second model turn should
-make a decision, call its `call_tool` endpoint through the peer
-connection. This example runs `get_forecast` in the weather agent's
-workspace and returns its structured result to the concierge tool.
+You need a forecast for Paris, and the weather agent already has
+`get_forecast`. Host code calls that tool in the specialist's workspace
+and the forecast comes back to the concierge, with no second model turn.
 
 ```ts
 const result = await ctx.host.mcp.callTool("weather", "call_tool", {
   toolName: "get_forecast",
   input: { city: "Paris" },
 });
+const part = result.content.find((item) => item.type === "text");
+if (part?.text === undefined) {
+  return { ok: false, forecast: null };
+}
+const payload = JSON.parse(part.text) as {
+  isError?: boolean;
+  result?: unknown;
+};
 
 return {
-  ok: result.isError !== true,
-  forecast: result.structuredContent ?? null,
+  ok: result.isError !== true && payload.isError !== true,
+  forecast: payload.result ?? null,
 };
 ```
 
@@ -723,26 +726,31 @@ complete agent you would also run, inspect, or expose on its own.
 | Tools and connections | Inherits the parent project | Owns its project surface |
 | Reachability | Parent only | Other co-hosted agents and MCP clients |
 
-## Peer sessions
+## 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.
 
-Calls through `ask` create sessions on the peer's `mcp` channel. They
-use the caller's authenticated principal and appear in the peer's
-playground, so the same authorization boundary applies to starts,
-follow-ups, and checks.
+## Practices
+
+- Give each caller a one-way routing rule so agent A cannot send work
+  to B and receive the same request back.
 
-There is no automatic recursion guard between peers. Give each caller a
-one-way routing rule so agent A cannot delegate the same work to B and
-receive it back from B.
+- Prefer `ask` when the specialist should reason. Use `call_tool` when
+  host code already knows which server tool to run.
 
-## Run peers on one host
+- Cursor-managed hosting deploys one agent per slug. Use
+  [subagents](/docs/reference/subagents.md) there instead of peer
+  connections.
 
-Peers require the default multi-agent layout and one shared `serve`
-process. Unknown slugs and self-references fail at startup.
-Cursor-managed hosting deploys one agent per slug, so use subagents
-there instead of peer connections.
+## Other hosts
 
-For a self-hosted cloud-runtime caller, expose the shared process with
-`--public-url` and protect it with `--bearer-token`. The
+Peers need the default multi-agent layout and one shared process;
+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](/docs/deployment.md) owns that hosting setup.
 
 ## Related
@@ -2307,6 +2315,359 @@ replace them.
 
 ---
 
+Source: /docs/guides/jev.md
+
+# 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](/docs/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](/docs/templates/agentic-owners.md): a risk tier, then
+  the host approves or asks for reviewers
+- [Security reviewer](/docs/templates/security-reviewer.md): a finding, or
+  no comment
+- [Thermo review](/docs/templates/thermo-review.md): bugs and breakage,
+  posted the same way
+- [Code wiki](/docs/reference/cli.md#init): documentation
+  follow-ups after a merge
+- [Evals](/docs/evals.md): checks on the full turn
+- [GitHub agents](/docs/guides/github.md): how the review gets onto the pull request
+
+---
+
 Source: /docs/guides/mcp-oauth.md
 
 # Connect a private MCP server with OAuth
@@ -5534,7 +5895,7 @@ export default defineConnection({
 ```
 
 Unknown slugs and self-references fail `serve` at startup. Walkthrough:
-[Agent-to-agent](/docs/guides/agent-to-agent.md#how-do-i-wire-two-agents).
+[Peer agents](/docs/guides/agent-to-agent.md#delegate-a-question-to-a-specialist).
 
 ## Every model-visible MCP connection is available in three places
 
@@ -6073,6 +6434,7 @@ namespace-neutral because the consumer chooses the final prefix.
 - [Cloud agents](/docs/guides/cloud-agents.md): delegate repository work
   through an extension
 - [Grok Bot agents](/docs/guides/grokbot-agents.md): consult named bots
+- [Jev](/docs/guides/jev.md): typed answers, then gated writes
 - [Self-improvement](/docs/guides/improve.md): propose source changes
   through pull requests
 - [Project layout](/docs/reference/project-layout.md): contribution slots
@@ -7436,7 +7798,7 @@ subagent."
 Subagents split one job into roles inside a single agent. When the
 specialist is independently useful, with its own tools, sessions, and
 playground, make it a full agent. See
-[Agent-to-agent](/docs/guides/agent-to-agent.md#peer-or-subagent).
+[Peer agents](/docs/guides/agent-to-agent.md#peer-or-subagent).
 
 ## Patterns
 
@@ -7498,6 +7860,10 @@ code that runs it. With a Zod `inputSchema`, the input is validated before
 `execute` runs and the input type is inferred. A plain JSON Schema
 object is forwarded as-is and the input arrives as raw JSON.
 
+A server tool can call `decide` from
+[`@cursor/july/extensions/jev`](/docs/guides/jev.md) for a risk tier or a
+finding gate without a second model turn.
+
 For multi-line descriptions, reminder prompts, and error messages, use
 [`prompt`](/docs/reference/prompt.md) so the string can sit indented with the surrounding
 TypeScript:

package/dist/docs/llms.txt

@@ -26,7 +26,7 @@
 
 ## Guides
 
-- [Agent-to-agent](/docs/guides/agent-to-agent.md): Let one Agent SDK agent consult an independent specialist, continue its session, or call its deterministic tools.
+- [Peer agents](/docs/guides/agent-to-agent.md): Let one Agent SDK agent consult an independent specialist, continue its session, or call its deterministic tools.
 - [Bitbucket](/docs/guides/bitbucket.md): Review pull requests, answer comments, and triage pushes on Bitbucket Cloud or Data Center.
 - [Cursor cloud agents](/docs/guides/cloud-agents.md): Mount an extension that lets your agent delegate repository work, inspect the result, and steer or stop the cloud agent.
 - [Convert a Cursor Automation](/docs/guides/convert-automation.md): Turn a dashboard Automation into an Agent SDK project, then reconnect its actions and triggers.
@@ -34,6 +34,7 @@
 - [GitLab](/docs/guides/gitlab.md): Review merge requests, answer notes, and triage failed pipelines on GitLab.com or self-managed GitLab.
 - [Cursor Grok Bot agents](/docs/guides/grokbot-agents.md): Mount an extension that lets your agent consult named Grok Bot agents, wait for long replies, and interrupt work.
 - [Self-improvement](/docs/guides/improve.md): Let an agent propose a change to its own source through a branch and pull request, with review and deployment kept separate.
+- [Jev](/docs/guides/jev.md): Use typed Jev decisions to filter review findings, route pull requests, and gate software-factory writes.
 - [Host MCP OAuth](/docs/guides/mcp-oauth.md): Authorize a private MCP server locally, constrain its tools, and carry its credentials onto a hosted agent.
 - [OpenTelemetry](/docs/guides/opentelemetry.md): Send agent traces and metrics to an OTLP collector, follow one conversation, and add domain telemetry.
 - [Slack](/docs/guides/slack.md): Wake your agent from mentions, DMs, and watched posts, then reply in the thread.