@cursor/july 0.1.107 → 0.1.109

package/docs/guides/bitbucket.md

@@ -0,0 +1,89 @@
+---
+title: "Bitbucket"
+description: "Wake your agent from pull requests, comments, and pushes on Bitbucket Cloud or Bitbucket Data Center."
+---
+
+# Bitbucket agents
+
+Use `bitbucketChannel()` for Bitbucket Cloud and Bitbucket Data Center. The
+channel detects the source from each signed payload and normalizes Data Center
+events to the Bitbucket Cloud event vocabulary.
+
+## Define the channel
+
+Author `agent/channels/bitbucket.ts`:
+
+```ts
+import { bitbucketChannel } from "@cursor/july/channels/bitbucket";
+
+export default bitbucketChannel({});
+```
+
+Without `onPullRequest`, new pull requests start turns. Data Center updates
+also start turns when the source branch has new commits. Comments and pushes
+are opt-in through `onPullRequestComment` and `onPush`. Use `onEvent` for
+other event types. Set `webhookEvents` when managed event delivery must
+subscribe to an event that only `onEvent` handles.
+
+Filter comment hooks by author before starting a turn. This prevents comments
+posted by the agent from triggering another turn.
+
+`ctx.bitbucket.api` can read pull requests, post comments, and create build
+statuses. See the [Channels reference](../reference/channels.md) for hook
+return values and session behavior.
+
+## Connect Bitbucket
+
+Set a repository hook secret and API token:
+
+```bash
+BITBUCKET_WEBHOOK_SECRET=...
+BITBUCKET_TOKEN=...
+```
+
+Add a repository webhook for
+`https://<your-host>/<slug>/v1/channels/bitbucket`. Use the same secret on
+both sides. The channel verifies the `X-Hub-Signature` HMAC before it parses
+the payload.
+
+Bitbucket Cloud uses its 2.0 API by default. Data Center also needs its REST
+API base:
+
+```ts
+export default bitbucketChannel({
+  apiBaseUrl: "https://bitbucket.example.com/rest/api/1.0",
+  repos: ["PLATFORM/api"],
+});
+```
+
+You can set `BITBUCKET_API_BASE_URL` instead.
+
+## Test locally
+
+Start the agent, then replay a pull request you can read:
+
+```bash
+agent-sdk dev
+agent-sdk bitbucket replay \
+  https://bitbucket.example.com/projects/PLATFORM/repos/api/pull-requests/42
+```
+
+Replay supports Bitbucket Cloud and Data Center URLs. `BITBUCKET_TOKEN` needs
+pull request read access. The command reads the pull request, creates a payload
+in the matching dialect, and sends it through the same channel route. Use
+`--events '*'` to replay the supported events declared by the channel. Use
+`--dry-run --out fixtures/bitbucket` to save fixtures.
+
+```bash
+agent-sdk bitbucket events --dir .
+agent-sdk bitbucket forward --dir .
+```
+
+`forward` prints the repository-hook and HTTPS tunnel setup for live
+deliveries.
+
+## Related
+
+- [Channels reference](../reference/channels.md)
+- [Webhooks and custom channels](./webhooks.md)
+- [Evals](../evals.md)

package/docs/guides/cloud-agents.md

@@ -34,9 +34,10 @@ export default cursorCloudAgents({
 });
 ```
 
-Launches run under the host's signed-in account (`agent-sdk login` or
-`CURSOR_API_KEY`) and spend its cloud-agent budget. Name the
-repositories the agent may target, and keep approval on when you can't.
+Launches run under the host's signed-in account (`agent-sdk login`,
+`CURSOR_API_KEY`, or `CURSOR_SERVICE_ACCOUNT_KEY`) and spend its
+cloud-agent budget. Name the repositories the agent may target, and
+keep approval on when you can't.
 
 Mount it on an agent that runs on the local runtime; that is where
 launches park for approval. On the cloud runtime approvals don't

package/docs/guides/github.md

@@ -18,7 +18,8 @@ The companion skill for coding agents is
 Connect GitHub in Cursor for the repositories you care about (Settings or
 [cursor.com/dashboard](https://cursor.com/dashboard)). That gives your
 account access and lets Cursor receive the repo's webhooks. Sign the host
-in (`agent-sdk login` or `CURSOR_API_KEY`), then opt the channel into the
+in (`agent-sdk login`, `CURSOR_API_KEY`, or
+`CURSOR_SERVICE_ACCOUNT_KEY`), then opt the channel into the
 Cursor account connection:
 
 ```ts
@@ -78,6 +79,37 @@ snapshot in the wake.
 This is the preferred production path: no public URL, no repo admin
 webhook, and no inbound network for GitHub deliveries.
 
+## Connect GitHub Enterprise Server
+
+GitHub Enterprise Server uses the same `githubChannel()` hooks and normalized
+events. Connect it through the direct webhook route. Set the REST API base and
+credentials for your server:
+
+```ts
+export default githubChannel({
+  api: {
+    apiBaseUrl: "https://github.example.com/api/v3",
+  },
+  credentials: {
+    token: () => process.env.GITHUB_TOKEN,
+    webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET,
+  },
+  onPullRequest: (ctx, pr) =>
+    pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
+});
+```
+
+Add a repository webhook for
+`https://<your-host>/<slug>/v1/channels/github`. Use the same webhook secret
+on the server and in `GITHUB_WEBHOOK_SECRET`. The channel verifies
+`X-Hub-Signature-256` before it parses the payload.
+
+Cursor account event pull, `github replay`, and `github forward` target
+GitHub.com. Test Enterprise Server integrations by posting saved webhook
+fixtures to a local `--dev` server. Leave `GITHUB_WEBHOOK_SECRET` unset for
+this local test so the channel admits unsigned loopback deliveries. Use a real
+delivery from your server so the fixture matches its version.
+
 ## Define the channel
 
 Author `agent/channels/github.ts` with `githubChannel()` from

package/docs/guides/gitlab.md

@@ -0,0 +1,97 @@
+---
+title: "GitLab"
+description: "Wake your agent from GitLab merge requests, notes, pipelines, and pushes on GitLab.com or self-managed GitLab."
+---
+
+# GitLab agents
+
+Use `gitlabChannel()` for GitLab.com and self-managed GitLab. The channel
+verifies project hooks, normalizes their payloads, and gives each hook a
+project-bound `ctx.gitlab` API client.
+
+## Define the channel
+
+Author `agent/channels/gitlab.ts`:
+
+```ts
+import { gitlabChannel } from "@cursor/july/channels/gitlab";
+
+export default gitlabChannel({});
+```
+
+Without `onMergeRequest`, new and reopened merge requests start turns.
+Updates start turns only when they include new commits. Notes, pushes, and
+pipelines are opt-in through `onNote`, `onPush`, and `onPipeline`.
+Use `onEvent` for other GitLab event types. Set `webhookEvents` when managed
+event delivery must subscribe to an event that only `onEvent` handles.
+
+Filter note hooks by author before starting a turn. This prevents comments
+posted by the agent from triggering another turn.
+
+`ctx.gitlab` can call the project REST API and create commit statuses. See the
+[Channels reference](../reference/channels.md) for hook return values and
+session behavior.
+
+## Connect GitLab
+
+On Cursor-managed hosting, use the signed-in Cursor account:
+
+```ts
+export default gitlabChannel({
+  cursorAccount: {
+    projects: ["acme/platform"],
+  },
+});
+```
+
+For direct webhooks, set a project hook secret and API token:
+
+```bash
+GITLAB_WEBHOOK_SECRET=...
+GITLAB_TOKEN=...
+```
+
+Add a project webhook for
+`https://<your-host>/<slug>/v1/channels/gitlab`. Use the same value for the
+GitLab secret token and `GITLAB_WEBHOOK_SECRET`. The channel checks
+`X-Gitlab-Token` before it parses the payload.
+
+Self-managed GitLab also needs its REST API base:
+
+```ts
+export default gitlabChannel({
+  apiBaseUrl: "https://gitlab.example.com/api/v4",
+  projects: ["acme/platform"],
+});
+```
+
+You can set `GITLAB_API_BASE_URL` instead.
+
+## Test locally
+
+Start the agent, then replay a merge request you can read:
+
+```bash
+agent-sdk dev
+agent-sdk gitlab replay \
+  https://gitlab.example.com/acme/platform/-/merge_requests/42
+```
+
+`GITLAB_TOKEN` needs API read access. Replay reads the merge request,
+creates GitLab-shaped payloads, and sends them through the same channel route.
+Use `--events '*'` to replay the supported events declared by the channel.
+Use `--dry-run --out fixtures/gitlab` to save fixtures.
+
+```bash
+agent-sdk gitlab events --dir .
+agent-sdk gitlab forward --dir .
+```
+
+GitLab has no local webhook relay. `forward` prints the project-hook and HTTPS
+tunnel setup for live deliveries.
+
+## Related
+
+- [Channels reference](../reference/channels.md)
+- [Webhooks and custom channels](./webhooks.md)
+- [Evals](../evals.md)

package/docs/guides/grokbot-agents.md

@@ -32,8 +32,8 @@ export default cursorGrokBotAgents({
 
 `agents` is the allowlist. List every Grok Bot the model may talk to;
 a name outside the list is refused. Calls run under the host's
-signed-in account (`agent-sdk login` or `CURSOR_API_KEY`). Keep
-approval on when you can't.
+signed-in account (`agent-sdk login`, `CURSOR_API_KEY`, or
+`CURSOR_SERVICE_ACCOUNT_KEY`). Keep approval on when you can't.
 
 Start from the [Grok Bot agents template](../templates/grokbot-agents.md)
 when you want a project that already mounts this.

package/docs/guides/improve.md

@@ -0,0 +1,96 @@
+---
+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."
+---
+
+# 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 tree the agent runs from is never edited; nothing changed there
+survives a deploy. The pull request is the only path.
+
+## 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`.
+
+```ts
+// agent/extensions/cloud.ts
+import cursorCloudAgents from "@cursor/july/extensions/cursor-cloud-agents";
+
+export default cursorCloudAgents({
+  cloud: {
+    repos: [{ url: "https://github.com/acme/agents", startingRef: "main" }],
+  },
+});
+```
+
+```ts
+// agent/extensions/improve.ts
+import improve from "@cursor/july/extensions/improve";
+
+export default improve({
+  repo: "https://github.com/acme/agents",
+  path: "agents/concierge",
+});
+```
+
+`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.
+
+## 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." |
+
+## What's next
+
+Continue with these pages:
+
+- [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

package/docs/guides/slack.md

@@ -148,7 +148,8 @@ agent-sdk slack create --dir .
 agent-sdk slack create --dir . --prod
 ```
 
-Sign in first (`agent-sdk login` or `CURSOR_API_KEY`). Finish **Add
+Sign in first (`agent-sdk login` or `CURSOR_API_KEY`). A team
+service-account key cannot create Slack apps. Finish **Add
 Slack to this agent** as the same Cursor account. Then run
 `agent-sdk slack doctor --prefix MY_AGENT` and serve:
 

package/docs/guides/webhooks.md

@@ -9,7 +9,8 @@ A custom channel gives the agent its own HTTP surface. You get routes
 with validated payloads, sessions keyed to something in your domain (a
 thread, a ticket, a PR), and replies delivered back to the caller. The
 [Slack](./slack.md) and [GitHub](./github.md) packs build on this
-mechanism. This page is the mechanism itself.
+mechanism. The [GitLab](./gitlab.md) and [Bitbucket](./bitbucket.md) packs
+use it too. This page is the mechanism itself.
 
 ## What you already have
 
@@ -463,6 +464,7 @@ from any PR you can read. See the [GitHub guide](./github.md).
 Continue with these pages:
 
 - [Channels reference](../reference/channels.md): the full authoring API
-- [GitHub](./github.md) and [Slack](./slack.md): the packaged channels
+- [GitHub](./github.md), [GitLab](./gitlab.md),
+  [Bitbucket](./bitbucket.md), and [Slack](./slack.md): the packaged channels
 - [Sessions and streaming](../reference/sessions.md): events your
   channel can subscribe to

package/docs/hillclimbing.md

@@ -72,9 +72,9 @@ Pin the input first. A moving fixture is noise. For GitHub agents, use `agent-sd
 
 ## How do I lock a hillclimb improvement with an eval?
 
-Every kept change needs an eval that would have failed before the change: a tool-choice gate, an `action.result` count bound, or an output-shape check. Run `agent-sdk eval --dir . --json` between rounds. Never weaken an existing gate to pass the round.
+Every kept change needs an eval that would have failed before the change: a tool-choice gate, a `maxToolCalls` bound, or an output-shape check. Run `agent-sdk eval --dir . --json` between rounds. Never weaken an existing gate to pass the round.
 
-Details live in [Evals](./evals.md). The evals skill will author the case with you.
+Details live in [Keep improvements with regression evals](./evals.md#keep-improvements-with-regression-evals). The evals skill will author the case with you.
 
 ## What habits help hillclimbing stay reliable?
 

package/docs/reference/agent-config.md

@@ -240,8 +240,11 @@ console.log(`listening on ${handle.url}`);
 Host settings match the documented [CLI](./cli.md) `serve` flags.
 `serve()` also accepts `discovery` (project-loading options) and
 `mode: "single" | "multi"`. The Cursor credential resolves in one order
-everywhere: explicit `apiKey`, then `CURSOR_API_KEY`, then the key
-stored by `agent-sdk login`.
+everywhere: explicit `apiKey`, then `CURSOR_API_KEY`, then
+`CURSOR_API_KEY_FILE` (hosted default `/run/cursor/secrets/CURSOR_API_KEY`
+when unset), then `CURSOR_SERVICE_ACCOUNT_KEY`, then the key stored by
+`agent-sdk login`. On a host that has both the service-account key and a
+bind file, the file principal wins.
 
 ## What's next
 

package/docs/reference/channels.md

@@ -8,7 +8,8 @@ description: "The authoring reference for defineChannel, the built-in HTTP chann
 A channel is the surface an agent lives on. The built-in HTTP session
 channel is always mounted. Custom channels declare their own routes
 under `/v1/channels/<id>`. The Slack and GitHub packs are prebuilt
-channels with platform transports. This page is the authoring reference;
+channels with platform transports. GitLab and Bitbucket packs cover their
+hosted and self-managed products. This page is the authoring reference;
 for the walkthrough, see the [Webhooks guide](../guides/webhooks.md).
 
 ## Built-in HTTP channel
@@ -134,7 +135,7 @@ Handlers receive the Fetch `Request` and an args object:
 `workspaceFiles`, `workspaceDir`, `cloud` (attach cloud repos for this
 session), `auth` (defaults to the request principal), `state` (starting
 channel state for new sessions), `title` (session display title), and
-`purpose` (`"eval"` skips sticky A/B enrollment).
+`purpose` (`"eval"` marks the session as regression traffic).
 
 ## Events
 
@@ -215,7 +216,19 @@ model turn), `{ task }` (host work), or `null`, and CLI tooling for
 replay and live forwarding. Author `agent/channels/github.ts` with
 `githubChannel()`. Opt-in `progress.commitStatus` and `progress.banner`
 converge a merge-box check and sticky PR comment from default stream
-events. Guide: [GitHub](../guides/github.md).
+events. Supports GitHub.com and GitHub Enterprise Server. Guide:
+[GitHub](../guides/github.md).
+
+**GitLab** (`@cursor/july/channels/gitlab`): verified project hooks for
+merge requests, notes, pipelines, pushes, and custom event types. Supports
+GitLab.com and self-managed GitLab. Author `agent/channels/gitlab.ts` with
+`gitlabChannel()`. Guide: [GitLab](../guides/gitlab.md).
+
+**Bitbucket** (`@cursor/july/channels/bitbucket`): verified repository hooks
+for pull requests, comments, pushes, and custom event types. Supports
+Bitbucket Cloud and Bitbucket Data Center through one normalized hook API.
+Author `agent/channels/bitbucket.ts` with `bitbucketChannel()`. Guide:
+[Bitbucket](../guides/bitbucket.md).
 
 **Deployments** (`@cursor/july/channels/deployments`): pull deploy
 events. Declare `events` and handle each one in `onEvent`. Each event

package/docs/reference/cli.md

@@ -109,7 +109,7 @@ the agent project. Slugged mounts get a subdirectory named for the slug.
 | `--host` | Bind this host. The default is loopback-only `127.0.0.1`. |
 | `--dev` | Disable automatic schedule and reminder firing, admit unsigned loopback GitHub deliveries, and widen playground session access on loopback. |
 | `--mode` | Use `multi` for slugged routes and an index, or `single` for one agent at the unslugged `/v1/*`. The default is `multi`. |
-| `--api-key` | Use this Cursor API key. The command falls back to `CURSOR_API_KEY`, then the stored login. |
+| `--api-key` | Use this Cursor API key. Otherwise the command uses `CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE` (hosted default `/run/cursor/secrets/CURSOR_API_KEY` when unset), then `CURSOR_SERVICE_ACCOUNT_KEY`, then the stored login. |
 | `--state-root` | Store sessions, streams, workspaces, and channel state here. Keep durable production state outside the agent repository. |
 | `--bearer-token` | Require this bearer token on routes without authored auth. Mutually exclusive with `--allow-anonymous`. |
 | `--allow-anonymous` | Admit every caller as one `anonymous` principal. Use only behind a trusted network boundary. |
@@ -366,8 +366,10 @@ agent-sdk eval status <evalId> --prod --slug pr-approver
 agent-sdk eval cancel <evalId> --prod --slug pr-approver
 ```
 
-`eval` runs `evals/**/*.eval.{ts,js}` on an ephemeral server or against
-`--url`. Select one or more exact case IDs, file ID prefixes, or tags.
+`eval` runs `evals/**/*.eval.{ts,js}` on an ephemeral server. With
+`--prod` or `--url`, the target server runs its own evals as a
+server-side batch. Select one or more exact case IDs, file ID prefixes,
+or tags.
 Omit selectors to run all cases. Repeated `--tag` flags use OR matching.
 
 An eval run requires `evals/evals.config.{ts,js}` with `maxConcurrency`
@@ -378,13 +380,13 @@ between 1 and 200. Timeout priority is the case's `timeoutMs`, the CLI's
 | --- | --- |
 | `--list` | Print discovered cases without running. `--list --json` prints them as an array. |
 | `--tag <tag>` | Run cases with this tag. Repeated flags use OR matching. |
-| `--json` | Print `{ ok, passed, failed, results }`. |
+| `--json` | Print `{ ok, passed, failed, scored, skipped, strict, results }`; see [Run evals in CI](../evals.md#run-evals-in-ci) for the result shape. |
 | `--verbose` | Stream `t.log` lines and reply snippets. |
 | `--no-stream` | Hide live progress on stderr. |
 | `--strict` | Exit `1` when a scored case misses a soft threshold. |
 | `--max-concurrency <n>` | Override `maxConcurrency` from `evals.config.ts`. |
 | `--junit <path>` | Write JUnit XML for CI annotations. |
-| `--artifacts <dir>` | Write run artifacts here. The default is a timestamped directory under `<state-root>/evals/`. |
+| `--artifacts <dir>` | Write run artifacts here. The default is a timestamped directory under `evals/` in the project state directory (not affected by `--state-root`). |
 | `--no-artifacts` | Skip run artifacts. |
 | `--skip-report` | Ignore reporters from `evals.config.ts` and eval files. |
 | `--out <path>` | Also write the full results JSON to this path (also for `eval status <evalId>`). |
@@ -557,10 +559,14 @@ runtime, and Cursor account MCP connections. `--key-name` changes the
 name of a browser-minted key. `login --api-key` validates and stores a
 key you already created.
 
-`whoami` shows which credential is active and why. `CURSOR_API_KEY`
-takes precedence over the stored login. `logout` removes the local
-credential file but doesn't revoke the API key. Revoke it in the Cursor
-dashboard when it should stop working.
+`whoami` shows which credential is active and why. An explicit key
+wins, then `CURSOR_API_KEY`, then `CURSOR_API_KEY_FILE` (hosted default
+`/run/cursor/secrets/CURSOR_API_KEY` when unset), then
+`CURSOR_SERVICE_ACCOUNT_KEY`, then the stored login. A host that has
+both the service-account key and a bind file authenticates as the file
+principal. `logout` removes the local credential file but doesn't
+revoke the API key. Revoke it in the Cursor dashboard when it should
+stop working.
 
 Login and account RPCs honor `CURSOR_API_BASE_URL`. The SDK harness
 honors `CURSOR_BACKEND_URL`. Set both to the same URL, or keys minted
@@ -598,9 +604,9 @@ agent-sdk deploy [--dir <path>] [--slug <slug> | --all] [--team <id>]
                 [--no-wait] [--json]
 ```
 
-Managed hosting requires team-admin permission and the team's
-cloud-agent entitlement. `--team` defaults to the signed-in account's
-team.
+Managed hosting requires team membership and the team's cloud-agent
+entitlement. A team service-account API key with agent access can
+deploy. `--team` defaults to the signed-in account's team.
 
 For a single project, the slug defaults to a normalized version of the
 directory name. Deployment slugs contain lowercase letters, digits, `_`,
@@ -843,8 +849,9 @@ checklist. It doesn't change files.
 `slack create` opens the signed-in Cursor dashboard wizard. Finish Slack
 consent and the bot name there. The CLI writes the token pair into
 `<dir>/.env.local` and runs `doctor`. It requires a signed-in host
-(`agent-sdk login` or `CURSOR_API_KEY`). `--prod` provisions the
-production app; the default is the development app. `--name` / `--icon`
+(`agent-sdk login` or `CURSOR_API_KEY`). A team service-account key
+cannot create Slack apps. `--prod` provisions the production app; the
+default is the development app. `--name` / `--icon`
 / `--channel-posts` prefill the wizard. A second create for the same
 slug and env overwrites the live Slack app. If Slack needs a workspace
 admin's approval, the wizard waits; keep the CLI running, open Slack's
@@ -957,7 +964,9 @@ These environment variables affect the CLI and its channel packs.
 
 | Variable | Meaning |
 | --- | --- |
-| `CURSOR_API_KEY` | Cursor credential. It takes precedence over the stored login. |
+| `CURSOR_API_KEY` | Cursor credential. It takes precedence over `CURSOR_API_KEY_FILE`, `CURSOR_SERVICE_ACCOUNT_KEY`, and the stored login. |
+| `CURSOR_API_KEY_FILE` | Path to a Cursor credential file. Used when `CURSOR_API_KEY` is unset. When this variable is unset, the hosted default `/run/cursor/secrets/CURSOR_API_KEY` is tried. A present file takes precedence over `CURSOR_SERVICE_ACCOUNT_KEY` and the stored login. |
+| `CURSOR_SERVICE_ACCOUNT_KEY` | Team service-account credential. Used when `CURSOR_API_KEY` and `CURSOR_API_KEY_FILE` (including the hosted default path) are unset. It takes precedence over the stored login. |
 | `CURSOR_API_BASE_URL` | Backend used by login, account, deployment, and event-relay RPCs. |
 | `CURSOR_BACKEND_URL` | Backend used by the Cursor SDK harness. |
 | `AGENT_SERVE_CONFIG_DIR` | Directory for stored credentials and update-check state. Defaults to the CLI config directory under `~/.config`. |

package/docs/reference/connections.md

@@ -224,7 +224,8 @@ Name the file `account.ts`. `cursor.ts` collides with the IDE `cursor`
 MCP namespace. `advertiseTools: true` puts connector tools on local
 turns by name. Without it they sit behind harness meta-tools.
 
-The host must be signed in (`agent-sdk login` or `CURSOR_API_KEY`).
+The host must be signed in (`agent-sdk login`, `CURSOR_API_KEY`, or
+`CURSOR_SERVICE_ACCOUNT_KEY`).
 `serve` fails fast at startup otherwise, and logs each connector's live
 status (`connected`, `needsAuth`, `error`) as it starts.
 

package/docs/reference/extensions.md

@@ -59,7 +59,6 @@ namespace:
 | `subagents/<id>/` | subagent `<ns>__<id>` |
 | `instructions.md` / `.ts` / dir | appended to the agent's system prompt |
 | `sandbox/workspace/**` | seeded into each local session workspace |
-| `ab.ts` / `ab/<name>.ts` | A/B experiment `<ns>__<name>` |
 | `artifacts.ts` | artifact kinds `<ns>__<kind>` |
 
 The root agent still needs its own `instructions.md`. Extension
@@ -76,7 +75,6 @@ or is outside discovery:
 | `agent.ts` | One `defineAgent` runtime per agent |
 | `storage.ts` | One `host.kv` / `host.files` backend |
 | `otel.ts` | One OTLP exporter |
-| `ab.config.ts` | One experiment-platform config; `ab.ts` / `ab/` still merge |
 | `playground/` | Custom chips are a Vite glob of the agent tree, not a discovery walk |
 | `extensions/` | Nested mounts are not loaded |
 | `sandbox.ts` | Custom sandbox backends stay on the agent |
@@ -117,7 +115,6 @@ it alive.
 | `schedules/<name>.ts` | `disableSchedule()` |
 | `subagents/<id>.ts` | `disableSubagent()` |
 | `instructions.ts` | `disableInstructions()` |
-| `ab.ts` / `ab/<name>.ts` | `disableAB()` |
 | `artifacts.ts` | `disableArtifacts()` |
 
 `disable()` is the same brand as the slot helpers above and works in
@@ -265,6 +262,8 @@ Continue with these pages:
   lets an agent launch and steer cloud agents
 - [Cursor Grok Bot agents](../guides/grokbot-agents.md): the extension
   that lets an agent talk to Grok Bot agents
+- [Self-improvement](../guides/improve.md): the extension that lets an
+  agent change its own source through a cloud agent and a pull request
 - [Tools](./tools.md): the tool contract extensions contribute to
 - [Skills](./skills.md): the skill forms an extension can carry
 - [Project layout](./project-layout.md): where `agent/extensions/` sits

package/docs/reference/hooks.md

@@ -88,7 +88,7 @@ exported from `@cursor/july`.
 
 | Member | What it is |
 | --- | --- |
-| `ctx.session` | Read-only session info: `id`, `channelId`, `mode` (`chat` or `task`), `purpose` (`live` or `eval`), `auth`, plus `title`, `sdkAgentId`, and `abs` when set |
+| `ctx.session` | Read-only session info: `id`, `channelId`, `mode` (`chat` or `task`), `purpose` (`live` or `eval`), `auth`, plus `title` and `sdkAgentId` when set |
 | `ctx.agent` | `{ name }` of the agent the event belongs to |
 | `ctx.channel` | `{ id, continuationToken }`. The token is `null` when the session can't take follow-ups |
 | `ctx.host.kv` | Durable JSON, shared by every session of the agent; the [storage backend](../storage.md#author-kv-ctx-host-kv) decides whether it survives a hosted replace. Prefix keys with `ctx.session.id` for per-session state |
@@ -119,17 +119,17 @@ Each event reaches a hook at most once. A restart doesn't replay the log
 into hooks, so a mirror needs no dedupe, and the event log rather than
 the hook's copy is the source of truth.
 
-## Hooks, channel events, evals, or A/B?
+## Hooks, channel events, or evals?
 
 All of them consume the same stream, for different jobs:
 
-| | Hooks | Channel `events` | Evals | A/B (`defineAB`) |
-| --- | --- | --- | --- | --- |
-| Scope | every session of the agent | sessions the channel owns | one test turn | every live session; enrollment at creation, metrics on each turn |
-| Job | observe: audit, metrics, mirrors, derived state | deliver: replies back to the channel's surface | assert: gates over the trajectory | compare: sticky arms, then fold the stream into `onSample` metrics |
-| Context | `ctx.host`, `ctx.artifacts`, session info | `channel.state`, `setContinuationToken`, `ctx.host`, session info | the `t` assertion helpers | per-session samples in `onSample` |
-| Can affect the run | no | yes, it owns the surface | n/a | yes through arm instructions or `session.abs`; collection is observe-only |
-| Authored at | `agent/hooks/*.ts` | channel config | `evals/**/*.eval.ts` | [`agent/ab.ts` or `agent/ab/*.ts`](../ab.md) |
+| | Hooks | Channel `events` | Evals |
+| --- | --- | --- | --- |
+| Scope | every session of the agent | sessions the channel owns | one test turn |
+| Job | observe: audit, metrics, mirrors, derived state | deliver: replies back to the channel's surface | assert: gates over the trajectory |
+| Context | `ctx.host`, `ctx.artifacts`, session info | `channel.state`, `setContinuationToken`, `ctx.host`, session info | the `t` assertion helpers |
+| Can affect the run | no | yes, it owns the surface | n/a |
+| Authored at | `agent/hooks/*.ts` | channel config | `evals/**/*.eval.ts` |
 
 ## When not to use a hook
 
@@ -141,7 +141,6 @@ All of them consume the same stream, for different jobs:
 | Block, approve, or rewrite a tool call | [`needsApproval`](./tools.md#gate-a-tool-on-human-approval) on the tool |
 | Act on the final assistant text, or fail a bad turn | [`defineResult`](./result.md) |
 | Gate a change on behavior | [Evals](../evals.md) |
-| Compare two prompts on live traffic | [`defineAB`](../ab.md) |
 
 ## Patterns
 
@@ -267,5 +266,3 @@ Continue with these pages:
 - [Deployment](../deployment.md#observability): runtime logs and export
   paths
 - [Channels](./channels.md#events): the delivery-side counterpart
-- [Live A/B metrics](../ab.md): sticky variants over the same event
-  stream