@cursor/july 0.1.102 → 0.1.104

package/docs/reference/result.md

@@ -0,0 +1,94 @@
+---
+title: "Turn result"
+description: "Run host code on the final assistant text when a turn finishes. Throw to fail the turn."
+---
+
+# Turn result
+
+Judgment agents need a place to act on the model's last message: parse
+it, then page, comment, or close a ticket. Author `agent/result.ts`
+with `defineResult` from `@cursor/july/result`. When that file exists,
+every finished turn runs `commit` on the serving host with the full
+assistant text.
+
+A thrown `commit` fails the turn. Empty assistant text fails it too.
+Hooks still observe only; they cannot fail a valid turn.
+
+Use this for an end-of-turn actuation. Mid-turn actions belong in
+[tools](./tools.md). Durable records that outlive a session belong in
+[artifacts](./artifacts.md).
+
+## Author `agent/result.ts`
+
+```ts
+import { defineResult } from "@cursor/july/result";
+import { applyDecision, parseDecision } from "./lib/actuate.js";
+
+export default defineResult({
+  async commit(ctx) {
+    if (ctx.session.purpose === "eval") {
+      return;
+    }
+    await applyDecision(parseDecision(ctx.text), ctx.host);
+  },
+});
+```
+
+`commit` is required. Parse `ctx.text` however the agent needs. Tell
+the model the document shape in `instructions.md`. The Agent SDK does
+not inject a schema.
+
+Put `result.ts` on the root agent only. A copy under a subagent is
+ignored with a warning.
+
+## Commit on the host
+
+`commit` runs in the serving process after the model finishes, before
+the turn completes. `ctx` is the same host surface a server tool gets,
+plus the turn text:
+
+| Member | What it is |
+| --- | --- |
+| `ctx.session` | The session that produced this turn, including `purpose` |
+| `ctx.host` | Shared host services (`kv`, `files`, `mcp`) |
+| `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade |
+| `ctx.stateRoot` | The agent's durable state root |
+| `ctx.workspaceDir` | The session workspace |
+| `ctx.text` | The full assistant string |
+
+A dry-run session skips `commit` and still completes. Eval sessions do
+run `commit`; return early when `ctx.session.purpose === "eval"` if the
+handler must not actuate.
+
+On cloud runtime, the model still runs on the VM. `commit` runs on the
+serving host after the turn returns.
+
+`GET /v1/info` reports `result: true` when the file is authored.
+
+## Assert in evals
+
+`t.succeeded()` fails when `commit` throws or the turn produced no
+text, because those are turn failures. Read the document on `t.reply`.
+
+```ts
+import { defineEval, includes } from "@cursor/july/evals";
+
+export default defineEval({
+  async test(t) {
+    await t.send("Triage LIN-1842. It duplicates LIN-1801.");
+    t.succeeded();
+    t.check(t.reply, includes("duplicate"));
+  },
+});
+```
+
+## What's next
+
+Continue with these pages:
+
+- [Evals](../evals.md): `t.succeeded` and `t.reply`
+- [Sessions and streaming](./sessions.md): `turn.completed` and
+  `turn.failed`
+- [Hooks](./hooks.md): observe the stream after the turn has already
+  settled
+- [Project layout](./project-layout.md): where `agent/result.ts` lives

package/docs/reference/sessions.md

@@ -94,7 +94,9 @@ within one session. The `at` field is an ISO-8601 timestamp.
 
 Pair `actions.requested` with `action.result` to reconstruct the tool
 trajectory. Read `turn.completed.data.usage` for input, output, and
-cache token counts.
+cache token counts. When `agent/result.ts` is authored, a thrown
+`commit` or empty assistant text emits `turn.failed` instead of
+`turn.completed`. See [Turn result](./result.md).
 
 ## How do I stream or replay session events?
 

package/docs/reference/tools.md

@@ -19,8 +19,7 @@ access to `process.env` and your `agent/lib/` code. Local turns call
 server tools as SDK custom tools. Cloud turns reach them over
 authenticated HTTP MCP back to the serve host when `--public-url` or
 `--cloud-tools-url` is set; without either, the server warns at startup
-and cloud turns omit them (see
-[Cloud runtime](../guides/cloud-runtime.md#what-changes-on-cloud)).
+and cloud turns omit them.
 
 ```ts
 // agent/tools/inspect_pr.ts

package/docs/templates/pr-autofixer.md

@@ -123,6 +123,3 @@ agent-sdk deploy
 Run it from the agent's git checkout. It infers repository, ref, path,
 and slug, builds on Cursor-managed hosting, and prints the URL.
 `agent-sdk deployments` shows status.
-
-See [Cloud runtime](../guides/cloud-runtime.md) for what changes on
-the VM.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.102",
+  "version": "0.1.104",
   "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": {
@@ -13,11 +13,7 @@
   "module": "dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "july": "./dist/bin/agent-serve.js",
-    "agent-sdk": "./dist/bin/agent-serve.js",
-    "agentsdk": "./dist/bin/agent-serve.js",
-    "agentkit": "./dist/bin/agent-serve.js",
-    "agent-serve": "./dist/bin/agent-serve.js"
+    "agent-sdk": "./dist/bin/agent-serve.js"
   },
   "publishConfig": {
     "access": "public"
@@ -26,9 +22,17 @@
     "dist/**/*",
     "!dist/playground-central/**",
     "!dist/internal/tenant-mcp/**",
+    "!dist/internal/grokbot/**",
+    "!dist/internal/review-comments.*",
+    "!dist/internal/shallow-clone.*",
+    "!dist/internal/managed-delivery.*",
     "src/**/*",
     "!src/**/*.test.ts",
     "!src/internal/tenant-mcp/**",
+    "!src/internal/grokbot/**",
+    "!src/internal/review-comments.ts",
+    "!src/internal/shallow-clone.ts",
+    "!src/internal/managed-delivery.ts",
     "skills/**/*",
     "templates/**/*",
     "docs/**/*.md",
@@ -83,12 +87,36 @@
       "import": "./dist/channels/origin/index.js",
       "default": "./dist/channels/origin/index.js"
     },
+    "./channels/gitlab": {
+      "anysphere-source": "./src/channels/gitlab/index.ts",
+      "types": "./dist/channels/gitlab/index.d.ts",
+      "import": "./dist/channels/gitlab/index.js",
+      "default": "./dist/channels/gitlab/index.js"
+    },
+    "./channels/bitbucket": {
+      "anysphere-source": "./src/channels/bitbucket/index.ts",
+      "types": "./dist/channels/bitbucket/index.d.ts",
+      "import": "./dist/channels/bitbucket/index.js",
+      "default": "./dist/channels/bitbucket/index.js"
+    },
     "./channels/deployments": {
       "anysphere-source": "./src/channels/deployments/index.ts",
       "types": "./dist/channels/deployments/index.d.ts",
       "import": "./dist/channels/deployments/index.js",
       "default": "./dist/channels/deployments/index.js"
     },
+    "./channels/change-monitors": {
+      "anysphere-source": "./src/channels/change-monitors/index.ts",
+      "types": "./dist/channels/change-monitors/index.d.ts",
+      "import": "./dist/channels/change-monitors/index.js",
+      "default": "./dist/channels/change-monitors/index.js"
+    },
+    "./channels/issues": {
+      "anysphere-source": "./src/channels/issues/index.ts",
+      "types": "./dist/channels/issues/index.d.ts",
+      "import": "./dist/channels/issues/index.js",
+      "default": "./dist/channels/issues/index.js"
+    },
     "./skills": {
       "anysphere-source": "./src/skills.ts",
       "types": "./dist/skills.d.ts",
@@ -182,6 +210,13 @@
       "import": "./dist/artifacts.js",
       "default": "./dist/artifacts.js"
     },
+    "./result": {
+      "anysphere-source": "./src/result.ts",
+      "bun": "./dist/result.js",
+      "types": "./dist/result.d.ts",
+      "import": "./dist/result.js",
+      "default": "./dist/result.js"
+    },
     "./kv": {
       "anysphere-source": "./src/kv.ts",
       "bun": "./dist/kv.js",
@@ -279,6 +314,7 @@
     "esbuild": "^0.25.0",
     "javascript-time-ago": "^2.6.4",
     "js-yaml": "4.1.0",
+    "minimatch": "^10.2.5",
     "ms": "^2.1.3",
     "proper-lockfile": "^4.1.2",
     "slackify-markdown": "^5.0.0",
@@ -289,8 +325,6 @@
   "devDependencies": {
     "@anysphere/agent-store-sync": "workspace:*",
     "@anysphere/ui": "workspace:*",
-    "@base-ui/react": "1.6.0",
-    "@stylexjs/stylex": "0.18.3",
     "@stylexswc/rs-compiler": "^0.18.0",
     "@tanstack/react-virtual": "3.13.23",
     "@types/js-yaml": "4.0.9",
@@ -302,7 +336,6 @@
     "@types/react-dom": "^19.0.0",
     "@typescript/native-preview": "7.0.0-dev.20260701.1",
     "@vitejs/plugin-react": "^5.1.2",
-    "minimatch": "^10.2.5",
     "pg": "^8.18.0",
     "pretty-ms": "^9.2.0",
     "react": "^19.2.1",

package/skills/framework-map/SKILL.md

@@ -44,9 +44,11 @@ Path is identity. Full list: README "Folder structure".
 | `agent/mcp-connections/<name>.ts` | MCP. Never name an account file `cursor.ts`. `advertiseTools: true` for named local tools |
 | `agent/host-connections/<name>.ts` | Privileged MCP for `ctx.host.mcp` / `mcp oauth` |
 | `agent/subagents/<id>/` | Child agent (`description` required) |
-| `agent/extensions/<ns>.ts` | Mounted extension or Cursor plugin (`cursorPlugin({ path })`); contributions are `<ns>__<name>` |
+| `agent/extensions/<ns>.ts` | Mounted extension or Cursor plugin (`cursorPlugin`); contributions are `<ns>__<name>` |
 | `agent/channels/*.ts` | Slack / GitHub / custom HTTP |
 | `agent/hooks/*.ts` | Observe-only |
+| `agent/artifacts.ts` | Durable tagged outputs (`defineArtifacts`) |
+| `agent/result.ts` | Host `commit` on the final assistant text (`defineResult`) |
 | `agent/ab.ts` or `agent/ab/*.ts` | Live A/B (`defineAB`) |
 | `agent/otel.ts` | OpenTelemetry (`defineOtel`) |
 | `agent/schedules/*` | Cron. Never auto-fire under `--dev` |

package/skills/otel/SKILL.md

@@ -33,9 +33,13 @@ export default defineOtel({
 3. `serve(dir, { otel: { … } })`. `otel: false` disables env and
    authored config.
 
+Hosted v2 secrets arrive after bake. Use `defineOtel(() => …)` so flush
+re-resolves exporters. Authored `agent/otel.ts` records from process
+start even when the factory returns no exporters yet.
+
 | Signal | Default |
 | --- | --- |
-| Traces | on (`agent_sdk.http` → session → turn → tool / subagent) |
+| Traces | on (`agent_sdk.http`; `agent_sdk.turn` → tool / subagent) |
 | Metrics | on (`cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`) |
 | Logs | off (`logs: true` or `OTEL_LOGS_EXPORTER=otlp`) |
 
@@ -51,5 +55,6 @@ ctx.host.otel.record("abc.approval.duration_ms", 1420);
 ```
 
 Prefix names with team or agent. No custom spans. Join on
-`cursor.conversation.id` and `agent_sdk.agent`. Run `serve` as its
-own process when Agent SDK should own the destination.
+`agent_sdk.session_id` / `cursor.conversation.id` and
+`agent_sdk.agent`. Run `serve` as its own process when Agent SDK
+should own the destination.

package/src/ab.ts

@@ -6,7 +6,7 @@
  * `ab.assigned` events; arms are exposed on {@link SessionInfo.abs} for the
  * agent loop (tools / optional per-variant `instructions`). {@link ABCollector}
  * folds the event stream into metrics and calls {@link ABConfig.onSample}.
- * There is no `agent-serve ab` test runner.
+ * There is no `agent-sdk ab` test runner.
  *
  * Assignments and foldable metrics live in each session's `events.ndjson`
  * (survive serve restart). Optional project defaults in `agent/ab.config.ts`

package/src/bin/agent-serve.ts

@@ -2,18 +2,18 @@
 /**
  * agent-serve CLI.
  *
- *   agent-serve serve      [--dir .] [--port 3000] [--host 127.0.0.1] [--dev]
- *   agent-serve dev        [path] [--port 3000] [--host 127.0.0.1]
- *   agent-serve docs       [--port 0] [--host 127.0.0.1] [--print]
- *   agent-serve chat      [--url http://127.0.0.1:3000] [--message "..."] [--json]
- *   agent-serve resume    [sessionId] [--url | --prod] [--message "..."]
- *   agent-serve run       [--dir .] [--message "..."] [--json|--text]
- *   agent-serve trajectory --events <file.ndjson>
- *   agent-serve init      [dir] [--json]
- *   agent-serve convert-automation <url> [--dir <path>] [--json]
- *   agent-serve eval        [--dir .] [evalId...]
- *   agent-serve validate   [--dir .]
- *   agent-serve slack     <subcommand>
+ *   agent-sdk serve      [--dir .] [--port 3000] [--host 127.0.0.1] [--dev]
+ *   agent-sdk dev        [path] [--port 3000] [--host 127.0.0.1]
+ *   agent-sdk docs       [--port 0] [--host 127.0.0.1] [--print]
+ *   agent-sdk chat      [--url http://127.0.0.1:3000] [--message "..."] [--json]
+ *   agent-sdk resume    [sessionId] [--url | --prod] [--message "..."]
+ *   agent-sdk run       [--dir .] [--message "..."] [--json|--text]
+ *   agent-sdk trajectory --events <file.ndjson>
+ *   agent-sdk init      [dir] [--json]
+ *   agent-sdk convert-automation <url> [--dir <path>] [--json]
+ *   agent-sdk eval        [--dir .] [evalId...]
+ *   agent-sdk validate   [--dir .]
+ *   agent-sdk slack     <subcommand>
  */
 
 import { spawn } from "node:child_process";
@@ -286,6 +286,10 @@ Commands:
               doctor (see slack help).
   github      GitHub webhook pack: forward live deliveries, events, doctor
               (wraps \`gh webhook forward\`; see github help).
+  gitlab      GitLab webhook pack: replay a merge request, events, forward
+              recipe (see gitlab help).
+  bitbucket   Bitbucket webhook pack (Cloud + Data Center): replay a pull
+              request, events, forward recipe (see bitbucket help).
 
 Agent loop:
   ${CLI} validate --dir .
@@ -332,11 +336,14 @@ Options:
                      defineConnection({ cursorAccount: true }). Admitted callers
                      can drive the account's MCP connectors, so use only behind
                      a trusted boundary (e.g. an SSO proxy or hosted alias token).
+  --cursor-scm-proxy serve: route every SCM channel's cursorAccount API calls
+                     (githubChannel, gitlabChannel, bitbucketChannel) through
+                     the Cursor backend's per-forge forwarder instead of
+                     minting raw tokens into this process
+                     (AGENT_SERVE_<FORGE>_PROXY_URL overrides a base URL).
   --cursor-github-proxy
-                     serve: route githubChannel({ cursorAccount }) API calls
-                     through the Cursor backend's GitHub forwarder instead of
-                     minting raw installation tokens into this process
-                     (AGENT_SERVE_GITHUB_PROXY_URL overrides the base URL).
+                     serve: deprecated alias for --cursor-scm-proxy; removed
+                     one release after --cursor-scm-proxy ships.
   --public-url       serve: base URL where this host is reachable from outside
                      (e.g. https://agent-serve.example.com). Required for peer
                      connections (defineConnection({ agent })) on cloud-runtime
@@ -442,9 +449,10 @@ Options:
   --install          github: install the cli/gh-webhook extension if missing.
                      slack init --manual: require Slack CLI app install.
   --no-install       slack init --manual: skip Slack CLI app install.
-  --action           github replay: event action (e.g. opened, synchronize).
+  --action           github/gitlab replay: event action (e.g. opened, open).
   --conclusion       github replay: CI conclusion (check_run/suite/status).
-  --comment          github replay: comment body for comment events.
+                     gitlab replay: pipeline status (success, failed, …).
+  --comment          github/gitlab/bitbucket replay: comment / note body.
   --context          github replay: commit-status context.
   --dry-run          github replay: print synthesized payloads, don't POST.
   --out              eval / eval status <runId>: also write the full results
@@ -510,6 +518,7 @@ async function main(argv: string[]): Promise<number> {
       "allow-anonymous-cursor-github": { type: "boolean", default: false },
       "allow-anonymous-cursor-account-mcp": { type: "boolean", default: false },
       "allow-anonymous-grokbot": { type: "boolean", default: false },
+      "cursor-scm-proxy": { type: "boolean", default: false },
       "cursor-github-proxy": { type: "boolean", default: false },
       "no-schedules": { type: "boolean", default: false },
       "no-control-plane": { type: "boolean", default: false },
@@ -672,6 +681,66 @@ async function main(argv: string[]): Promise<number> {
         out: values.out,
       });
     }
+    case "gitlab": {
+      const port =
+        values.port === undefined
+          ? undefined
+          : Number.parseInt(values.port, 10);
+      if (
+        port !== undefined &&
+        (Number.isNaN(port) || port < 0 || port > 65535)
+      ) {
+        process.stderr.write(`invalid --port: ${values.port}\n`);
+        return 1;
+      }
+      const { cmdGitlab } = await import("../internal/cli-gitlab.js");
+      return cmdGitlab(positionals[0], {
+        dir,
+        slug: values.slug,
+        channel: values.channel?.at(-1),
+        host: values.host,
+        port,
+        url: values.url,
+        events: values.events,
+        secret: values.secret,
+        json: values.json,
+        mrUrl: positionals[1],
+        action: values.action,
+        conclusion: values.conclusion,
+        comment: values.comment,
+        dryRun: values["dry-run"],
+        out: values.out,
+      });
+    }
+    case "bitbucket": {
+      const port =
+        values.port === undefined
+          ? undefined
+          : Number.parseInt(values.port, 10);
+      if (
+        port !== undefined &&
+        (Number.isNaN(port) || port < 0 || port > 65535)
+      ) {
+        process.stderr.write(`invalid --port: ${values.port}\n`);
+        return 1;
+      }
+      const { cmdBitbucket } = await import("../internal/cli-bitbucket.js");
+      return cmdBitbucket(positionals[0], {
+        dir,
+        slug: values.slug,
+        channel: values.channel?.at(-1),
+        host: values.host,
+        port,
+        url: values.url,
+        events: values.events,
+        secret: values.secret,
+        json: values.json,
+        prUrl: positionals[1],
+        comment: values.comment,
+        dryRun: values["dry-run"],
+        out: values.out,
+      });
+    }
     case "init": {
       return cmdInit({
         dir,
@@ -1284,8 +1353,11 @@ async function main(argv: string[]): Promise<number> {
             : undefined,
         allowAnonymousGrokbot:
           values["allow-anonymous-grokbot"] === true ? true : undefined,
-        cursorGithubProxy:
-          values["cursor-github-proxy"] === true ? true : undefined,
+        cursorScmProxy:
+          values["cursor-scm-proxy"] === true ||
+          values["cursor-github-proxy"] === true
+            ? true
+            : undefined,
         schedules: values["no-schedules"] === true ? false : undefined,
         noControlPlane: values["no-control-plane"] === true ? true : undefined,
         playground: values["no-playground"] === true ? false : undefined,
@@ -1644,6 +1716,34 @@ function printServeBanner(
       )
     );
   }
+  if (
+    opts.dev &&
+    (process.env.GITLAB_WEBHOOK_SECRET === undefined ||
+      process.env.GITLAB_WEBHOOK_SECRET === "") &&
+    handle.agents.some((agent) =>
+      projectInfo(agent.project).channels.some((c) => c.kind === "gitlab")
+    )
+  ) {
+    process.stdout.write(
+      c.dim(
+        `  gitlab: dev accepts unsigned loopback deliveries (${CLI} gitlab replay works without a secret; set GITLAB_WEBHOOK_SECRET to verify X-Gitlab-Token)\n`
+      )
+    );
+  }
+  if (
+    opts.dev &&
+    (process.env.BITBUCKET_WEBHOOK_SECRET === undefined ||
+      process.env.BITBUCKET_WEBHOOK_SECRET === "") &&
+    handle.agents.some((agent) =>
+      projectInfo(agent.project).channels.some((c) => c.kind === "bitbucket")
+    )
+  ) {
+    process.stdout.write(
+      c.dim(
+        `  bitbucket: dev accepts unsigned loopback deliveries (${CLI} bitbucket replay works without a secret; set BITBUCKET_WEBHOOK_SECRET to verify X-Hub-Signature)\n`
+      )
+    );
+  }
 }
 
 /** Prefer the Vite playground URL in --dev; otherwise the static SPA path. */
@@ -1745,7 +1845,7 @@ installTransportErrorGuards();
 
 // Authored agent files are TypeScript imported at runtime; install the tsx
 // loader (and the framework import aliases on compiled runs) before any
-// command touches a project. In-repo CLI is `bin/agentsdk`.
+// command touches a project. In-repo CLI is `bin/agent-serve.ts`.
 registerAuthoredModuleLoaders()
   .then(() => main(process.argv.slice(2)))
   .then(