@cursor/july 0.1.112 → 0.1.113

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

package/docs/reference/connections.md

@@ -256,7 +256,7 @@ export default defineConnection({
 ```
 
 Unknown slugs and self-references fail `serve` at startup. Walkthrough:
-[Agent-to-agent](../guides/agent-to-agent.md#how-do-i-wire-two-agents).
+[Peer agents](../guides/agent-to-agent.md#delegate-a-question-to-a-specialist).
 
 ## Every model-visible MCP connection is available in three places
 

package/docs/reference/extensions.md

@@ -192,6 +192,7 @@ namespace-neutral because the consumer chooses the final prefix.
 - [Cloud agents](../guides/cloud-agents.md): delegate repository work
   through an extension
 - [Grok Bot agents](../guides/grokbot-agents.md): consult named bots
+- [Jev](../guides/jev.md): typed answers, then gated writes
 - [Self-improvement](../guides/improve.md): propose source changes
   through pull requests
 - [Project layout](./project-layout.md): contribution slots

package/docs/reference/subagents.md

@@ -54,7 +54,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](../guides/agent-to-agent.md#peer-or-subagent).
+[Peer agents](../guides/agent-to-agent.md#peer-or-subagent).
 
 ## Patterns
 

package/docs/reference/tools.md

@@ -42,6 +42,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`](../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`](./prompt.md) so the string can sit indented with the surrounding
 TypeScript:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.112",
+  "version": "0.1.113",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -190,6 +190,13 @@
       "import": "./dist/extensions/improve/extension.js",
       "default": "./dist/extensions/improve/extension.js"
     },
+    "./extensions/jev": {
+      "anysphere-source": "./src/extensions/jev/extension.ts",
+      "bun": "./dist/extensions/jev/extension.js",
+      "types": "./dist/extensions/jev/extension.d.ts",
+      "import": "./dist/extensions/jev/extension.js",
+      "default": "./dist/extensions/jev/extension.js"
+    },
     "./extensions/slack-communication": {
       "anysphere-source": "./src/extensions/slack-communication/extension.ts",
       "bun": "./dist/extensions/slack-communication/extension.js",

package/src/bin/agent-serve.ts

@@ -290,9 +290,8 @@ Commands:
   cancel-runs Request cancellation for active Agent SDK v2 session runs
               and reminder clocks, and mark factory creating/active
               sessions failed. For a multi-tenant application this
-              cancels every install, not just the caller's, and requires
-              a team admin (service accounts cannot). Install-local
-              cancel is stop --cancel-runs.
+              cancels every install, not just the caller's.
+              Install-local cancel is stop --cancel-runs.
   event-repos Set the repositories a multi-tenant install receives events
               for. A deploy cannot carry these; pass every repository you
               want, since the list is replaced rather than merged.

package/src/channels/checks.ts

@@ -90,6 +90,14 @@ export interface CiCheckCreateInput {
   name: string;
   /** Commit the check attaches to (usually the PR head SHA). */
   sha: string;
+  /**
+   * Check suite the check files under, on forges that have one. Origin
+   * renders every check as `suite / check` and groups the checks tab by
+   * suite, so name it after the posting app (GitHub groups an app's checks
+   * under the app); without it the suite mirrors the check name. GitHub,
+   * GitLab and Bitbucket have no app-named suite and ignore it.
+   */
+  suite?: { name?: string };
   /** Initial status. Defaults to `"in_progress"`. */
   status?: "queued" | "in_progress";
   /** "Details" link on the check, e.g. the agent session run URL. */

package/src/channels/origin/checks.ts

@@ -88,8 +88,10 @@ export interface OriginCheckIdentityInput {
   externalId?: string;
 }
 
+// The identity input's `suite` also carries Origin's key and details URL, so
+// the forge-agnostic `suite` label is replaced rather than merged.
 export interface OriginCheckCreateInput
-  extends OriginCheckIdentityInput, CiCheckCreateInput {}
+  extends OriginCheckIdentityInput, Omit<CiCheckCreateInput, "suite"> {}
 
 /**
  * Origin rejects the whole upsert when `output.title` exceeds 255 characters

package/src/channels/slack/dispatch.ts

@@ -434,14 +434,15 @@ export async function dispatchInboundMessage(args: {
   });
 
   const handoff = args.platformHandoff?.slackPlaceholder;
-  const matchedHandoff =
-    args.placeholder !== undefined &&
+  const handoffInThread =
     kind !== "channel_post" &&
     handoff !== undefined &&
     handoff.channelId === message.channelId &&
     handoff.threadTs === message.threadTs
       ? handoff
       : undefined;
+  const matchedHandoff =
+    args.placeholder !== undefined ? handoffInThread : undefined;
   let adoptedPlaceholder = false;
   let handoffRetracted = false;
   const retractUnadoptedHandoff = async (): Promise<void> => {
@@ -674,8 +675,12 @@ export async function dispatchInboundMessage(args: {
     });
   }
 
+  // A control-plane placeholder is turn scaffolding, not thread history: the
+  // guest posts the reply over that exact ts, so hydrating it would feed the
+  // model its own "still working" line as an already-sent reply.
   const excludeThreadTimestamps = [
     message.ts,
+    ...(handoffInThread === undefined ? [] : [handoffInThread.messageTs]),
     ...(decision.excludeThreadTimestamps ?? []),
   ];
   const mergeMessages = [triggeringMergeMessage(message)];

package/src/extensions/jev/extension.ts

@@ -0,0 +1,95 @@
+/**
+ * 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 type { Extension } from "../../types.js";
+import { DEFAULT_EVALUATION_MODEL } from "./lib/evaluate.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;
+}
+
+const config: z.ZodType<JevConfig, z.ZodTypeDef, JevOptions | undefined> = 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 => ({
+    apiKey: options.apiKey,
+    model: options.model ?? DEFAULT_EVALUATION_MODEL,
+    harnessTools: options.harnessTools,
+    skills: options.skills,
+  }));
+
+const jev: Extension<JevConfig, JevOptions | undefined> = 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 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;