@cursor/july 0.1.68 → 0.1.74

package/docs/scaffolding-agents.md

@@ -16,13 +16,21 @@ into a small working project. Have Cursor read that file and follow it.
 
 Where to find the file depends on how you got the package:
 
-- Reading these docs on a hosted site? Run `agent-sdk install-skills`
-  to copy every package skill into `~/.cursor/skills/agentkit/`, where
-  Cursor discovers them by name.
-- Installed `@cursor/july` as a dependency? The skill ships inside the
-  package at `node_modules/@cursor/july/skills/create-agent/SKILL.md`.
+- Installing `@cursor/july` (`npm install`, `npx @cursor/july`, a
+  version bump) copies every package skill into
+  `~/.cursor/skills/agentsdk/` with `alwaysApply: true`, so Cursor
+  injects the skill body into context instead of waiting for the
+  model to pick it from the catalog. The `/` menu lists them as
+  `/agentsdk-create-agent`, `/agentsdk-hillclimb`, and the rest. Re-installing overwrites those
+  copies with the package version. Set
+  `CURSOR_JULY_SKIP_SKILL_INSTALL=1` to skip the copy.
+- Installed `@cursor/july` as a dependency? The skill also ships inside
+  the package at `node_modules/@cursor/july/skills/create-agent/SKILL.md`.
 - Working in the monorepo? It's at
-  `packages/agent-serve/skills/create-agent/SKILL.md`.
+  `packages/agent-serve/skills/create-agent/SKILL.md`. Run
+  `agent-sdk install-skills` if you want the same copies in
+  `~/.cursor/skills/agentsdk/` (the package postinstall skips the
+  source checkout).
 
 Cursor will:
 

package/docs/troubleshooting.md

@@ -31,7 +31,8 @@ Match your symptom below. Keep the commands as `agent-sdk`; see
 | --- | --- |
 | Built-in file reads and greps fail; the turn retries for a long time | Run under Node 22.13+ (or `tsx`), never Bun. Look for `NGHTTP2_FRAME_SIZE_ERROR` in logs. |
 | The turn fails immediately with an API-key error | Sign in with `agent-sdk login`, or set `CURSOR_API_KEY`. Discovery, `info`, `call`, and serve bring-up work without a key; model turns need one. |
-| Replies quote rules or `AGENTS.md` from outside your agent project | The session workspace inherited parent-folder config. Point `defineAgent({ local: { cwd } })` outside that tree, or set `--state-root` to a clean directory (for example under `/tmp`). |
+| Replies quote rules or `AGENTS.md` from outside your agent project | The session workspace inherited parent-folder config. Nested git checkouts default `local.cwd` to `~/.cache/agent-serve/<dir>`. Point `defineAgent({ local: { cwd } })` at a checkout only when the agent should inherit that tree, or set `--state-root` to a clean directory (for example under `/tmp`). |
+| Yellow box shows Datadog/Linear tools, but the model lists `GetDynamicTools` / IDE `cursor` tools and never calls them | Attached MCP sits behind harness meta-tools, or `hostOnly` hid the connection, or the harness cwd is still inside another checkout. Set `advertiseTools: true` for named tools on local turns. Check `GET /v1/info` `local.cwd` and `connections[].advertiseTools`. |
 | Server tools, skills, or workspace seed files never appear | The agent runtime is `cloud`. Those features apply on the local runtime. `validate` warns when this combination is present. |
 | `validate` and `run` succeed, but typecheck fails in CI | The CLI runs TypeScript with type-stripping only. Keep tool `execute` return types as object literals or `type` aliases, not `interface` types. |
 | Login works, but turns are rejected when using custom API hosts | Point login and model traffic at the same host (`CURSOR_API_BASE_URL` and `CURSOR_BACKEND_URL`). A key from one host is rejected by the other. |
@@ -70,7 +71,7 @@ Match your symptom below. Keep the commands as `agent-sdk`; see
 | --- | --- |
 | `must be defineConnection({ url, oauth: true })` | The connection file needs `oauth: true`, or you passed the wrong connection name to `agent-sdk mcp oauth`. |
 | Local auth works; hosted calls unauthorized | Run `agent-sdk mcp oauth <name> --store`, confirm names with `agent-sdk secrets list <slug>`, then redeploy. |
-| Model asks for `mcp_auth` or IDE MCP for a privileged server | That connection is likely `hostOnly`. Call it from a host tool via `ctx.host.mcp`, and update instructions. |
+| Model asks for `mcp_auth` or IDE MCP for a privileged server | That connection is `hostOnly`. Call it from a host tool via `ctx.host.mcp`, and update instructions. |
 
 See [Host MCP OAuth](./guides/mcp-oauth.md) and
 [`skills/mcp-auth/SKILL.md`](../skills/mcp-auth/SKILL.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.68",
+  "version": "0.1.74",
   "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": {
@@ -34,6 +34,7 @@
     "templates/**/*",
     "docs/**/*.md",
     "!docs/.cursor/**",
+    "scripts/install-cursor-skills.mjs",
     "package.json",
     "LICENSE.md",
     "README.md",
@@ -150,18 +151,21 @@
     },
     "./kv": {
       "anysphere-source": "./src/kv.ts",
+      "bun": "./dist/kv.js",
       "types": "./dist/kv.d.ts",
       "import": "./dist/kv.js",
       "default": "./dist/kv.js"
     },
     "./kv/memory": {
       "anysphere-source": "./src/kv/memory-kv.ts",
+      "bun": "./dist/kv/memory-kv.js",
       "types": "./dist/kv/memory-kv.d.ts",
       "import": "./dist/kv/memory-kv.js",
       "default": "./dist/kv/memory-kv.js"
     },
     "./ledger": {
       "anysphere-source": "./src/ledger.ts",
+      "bun": "./dist/ledger.js",
       "types": "./dist/ledger.d.ts",
       "import": "./dist/ledger.js",
       "default": "./dist/ledger.js"
@@ -200,6 +204,7 @@
   },
   "scripts": {
     "build": "tsgo -p tsconfig.build.json && node scripts/bundle-publish-shims.mjs && pnpm run build:playground && pnpm run docs:build",
+    "postinstall": "node -e \"try{const p='./scripts/install-cursor-skills.mjs';if(require('fs').existsSync(p))require('child_process').execFileSync(process.execPath,[p],{stdio:'inherit'})}catch{}\"",
     "build:playground": "vite build --config playground/vite.config.ts",
     "build:playground:central": "vite build --mode central --config playground/vite.config.ts",
     "dev:playground": "vite --config playground/vite.config.ts",

package/scripts/install-cursor-skills.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * postinstall: copy Agent SDK coding-agent skills into ~/.cursor/skills/agentsdk
+ * so Cursor discovers them after `npm install` / `npx @cursor/july`.
+ *
+ * Never fails the package install. No-op in the monorepo source checkout
+ * (package root is not under node_modules) and when dist is missing.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const distEntry = join(
+  packageRoot,
+  "dist",
+  "internal",
+  "install-cursor-skills.js"
+);
+
+try {
+  if (!existsSync(distEntry)) {
+    process.exit(0);
+  }
+  // Windows: Node's ESM loader rejects bare drive-letter paths
+  // (`ERR_UNSUPPORTED_ESM_URL_SCHEME`). file:// is valid on every platform.
+  const { syncCursorSkillsOnPackageInstall } = await import(
+    pathToFileURL(distEntry).href
+  );
+  await syncCursorSkillsOnPackageInstall({ packageRoot });
+} catch {
+  // Swallow: a skill copy must not fail `npm install`.
+}
+
+process.exit(0);

package/skills/ab/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentkit-ab
+name: agentsdk-ab
 description: >-
   Author defineAB live A/B metrics plug-ins under agent/ab. Splits traffic into
   sticky variants and calls onSample with performance metrics as the agent runs

package/skills/create-agent/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentkit-create-agent
+name: agentsdk-create-agent
 description: >-
   Scaffold a new Agent SDK agent through a guided AskQuestion interview —
   purpose, name, runtime, model, channels, MCP connections, capabilities —
@@ -62,7 +62,7 @@ questions, concrete options, the recommended option listed first and labeled
 | **Runtime** | `local` (default) · `cloud` | Local = Cursor SDK harness on this machine; server tools, skills, sandbox seeds, and tool approvals all work. Cloud = Cursor cloud agents; needs `cloud.repos`, no server tools/skills/sandbox seeds (instructions are prepended to the first prompt). Recommend local unless the purpose needs a repo checkout on a cloud VM. |
 | **Model** | `grok-4.5` with `effort=high`, `fast=true` (default) · Other model id | Effort and fast are params, not id suffixes: `{ id: "grok-4.5", params: [{ id: "effort", value: "high" }, { id: "fast", value: "true" }] }` — the SDK rejects suffix-style ids. |
 | **Channels** (multi) | playground + HTTP API only (always mounted) · Slack · GitHub webhooks · custom webhook · schedule (cron) | Slack has two connections: the Cursor-hosted connection (`cursorAccount: true` — zero Slack admin, recommended default) and a dedicated Socket Mode app (own bot user + one app/token pair per agent; needed for channel watching or approval buttons). When Slack is picked, resolve the connection with the Step 0 gate in `setup-slack/SKILL.md` — either fold its AskQuestion into this round or ask it before channel setup; default to Cursor-hosted when you cannot ask. GitHub verifies `X-Hub-Signature-256` when a secret is set. Discord/Teams packs do not exist yet — offer custom webhook instead. |
-| **MCP connections** (multi) | none · remote server (URL + header auth) · local stdio server · Other | One file per server under `agent/mcp-connections/`; filename = server name; tokens via env vars, never hardcoded. MCP connections serve the model **and** host code (`ctx.host.mcp`, channel `host.mcp`). |
+| **MCP connections** (multi) | none · remote server (URL + header auth) · local stdio server · Cursor account connectors · Other | One file per server under `agent/mcp-connections/`; filename = server name. Do not name an account connection `cursor.ts` (collides with the IDE `cursor` namespace); use `account.ts`. Tokens via env vars, never hardcoded. Connections serve the model and host code (`ctx.host.mcp`). If the model should call them by name on local turns, set `advertiseTools: true`. Set `hostOnly: true` only when host tools call the server and the playground must not. |
 | **Capabilities** (multi) | server tools · agent tools (scripts) · skills · subagents · hooks · sandbox seed files · tool approvals (HITL) · evals (recommend) | Server tools, skills, sandbox seeds, approvals are local-runtime only. Agent tools (`execution: "agent"`) work on both runtimes. Always recommend at least one smoke eval. |
 
 Close the round with a one-screen plan — chosen options plus the file tree you
@@ -87,6 +87,10 @@ Defaults that make first cuts good:
 
 - **Minimal surface.** Instructions + 1–2 real tools + the chosen channels +
   one smoke eval. Unpicked capabilities are follow-ups, not scope.
+- **`local.cwd`.** Keep the harness outside a monorepo checkout
+  (`~/.cache/agent-serve/<slug>`). Discovery does this for nested git
+  projects. Point cwd at a checkout only when the agent must inherit that
+  tree.
 - **Instructions** (`agent/instructions.md`, required): a few lines — identity,
   when to use which tool, output shape. Not an essay.
 - **Tool per file**, filename = tool name the model sees. Prefer
@@ -139,9 +143,9 @@ agent-sdk init ./<slug>
 ```
 
 `init` writes `package.json` (with `typescript` dev deps and a
-`check` script), `tsconfig.json`, `agent/agent.ts`, `agent/instructions.md`,
-a demo `agent/tools/echo.ts`, and empty capability folders
-(`skills/`, `channels/`, `evals/`, …) each with a `.gitkeep`; existing
+`check` script), `tsconfig.json`, `AGENTS.md`, `.gitignore`, `agent/agent.ts`,
+`agent/instructions.md`, a demo `agent/tools/echo.ts`, and empty capability
+folders (`skills/`, `channels/`, `evals/`, …) each with a `.gitkeep`; existing
 files are left alone (`exist`) and missing ones are filled in. It then
 runs `npm install`, and when the host is unsigned runs `login` and waits
 before printing `cd` (when needed) and `agent-sdk dev`. Then shape it to the
@@ -149,8 +153,7 @@ plan:
 
 1. `tsconfig.json` — init writes a strict, `noEmit` config covering `agent/`
    and `evals/`; extend it only when the project needs more.
-2. `agent/agent.ts` — chosen model/runtime via `defineAgent({...})`; add the
-   `cloud: { repos: [...] }` block for cloud runtime.
+2. `agent/agent.ts` — chosen model/runtime via `defineAgent({...})`. Nested git checkouts get `local.cwd` under `~/.cache/agent-serve/<slug>` at discovery even if omitted. Add the `cloud: { repos: [...] }` block for cloud runtime.
 3. `agent/instructions.md` — real instructions; delete or replace `echo.ts`
    with the real tools.
 4. Add the chosen `channels/`, `mcp-connections/`, `skills/`, `subagents/<id>/`
@@ -210,9 +213,9 @@ agent-sdk eval --dir ./<slug>
 
 Serve only the new agent's directory during bring-up — pointing `serve` at a
 parent folder also mounts every sibling agent it contains.
-Runtime state lands in `<project>/.agent-serve/` (gitignored); keep durable
-`--state-root` outside the monorepo so sessions don't inherit ambient
-`AGENTS.md`.
+Runtime state lands in `<project>/.agent-serve/` (gitignored). Nested
+checkouts default `local.cwd` to `~/.cache/agent-serve/<slug>` at
+discovery. `--state-root` is for session files, not harness cwd.
 
 ## Channel setup with the user
 

package/skills/debug/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentkit-debug
+name: agentsdk-debug
 description: >-
   Diagnose a misbehaving Agent SDK agent, server, or playground — blank
   playground, sessions missing, HMR not reloading, failing reads/retry
@@ -47,7 +47,8 @@ curl -sN 'localhost:3000/<slug>/v1/session/<id>/stream?startIndex=0' | head -50
 | Every built-in read/grep the model makes fails; turns crawl through retry loops | You ran the CLI under **Bun**. Kill it, rerun under Node/tsx. (`NGHTTP2_FRAME_SIZE_ERROR` in SDK logs is the tell.) |
 | `gh webhook forward` / `agent-sdk github forward` deliveries all 401 — but hook creation succeeded | `GITHUB_TOKEN`/`GH_TOKEN` in the env. The relay authenticates with the gh CLI login and rejects env tokens. `GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward ...` |
 | `Hook already exists` starting a forwarder | GitHub allows one forwarder per repo. Use one `github forward --dir <parent>` (it fans out to every matching channel) instead of N processes; kill stale forwarders. |
-| Agent's answers reference monorepo rules / AGENTS.md it shouldn't know | Session workspace sits inside the monorepo, so the harness loaded ancestor config. `defineAgent({ local: { cwd } })` outside the repo, or `--state-root` under `/tmp`. |
+| Agent's answers reference monorepo rules / AGENTS.md it shouldn't know | Session workspace sits inside another git checkout, so the harness loaded ancestor config. Nested projects default `local.cwd` to `~/.cache/agent-serve/<dir>`. Point cwd at a checkout only when the agent should inherit that tree. |
+| Yellow box lists Datadog/Linear tools; model recites `GetDynamicTools` / IDE `cursor` tools and never calls MCP | Attached MCP is behind meta-tools, or `hostOnly` hid it, or cwd still leaked IDE MCP. Set `advertiseTools: true` for named tools on local turns. Confirm `GET /v1/info` `local.cwd` and `connections[].advertiseTools`. |
 | Port 3000/5273 in use; stray processes after crashes | `lsof -iTCP:3000 -sTCP:LISTEN`, kill the pids; also check companion processes (e.g. vite). |
 | Pending tool approval vanished after server restart | By design: parked SDK calls don't survive host restart; they resolve as interrupted. Re-run the turn. |
 | Schedule / reminder never fires under `--dev` | Dev never auto-fires. `POST /<slug>/v1/dev/schedules/<id>` or `POST /<slug>/v1/dev/reminders/<id>` (list at `GET /v1/dev/reminders`). |

package/skills/evals/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentkit-evals
+name: agentsdk-evals
 description: >-
   Author and run Agent SDK defineEval cases (single- or multi-datapoint).
   Use when writing, fixing, seeding, or hillclimbing evals; AskQuestion

package/skills/framework-map/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentkit-framework-map
+name: agentsdk-framework-map
 description: >-
   Orientation for @cursor/july — folder structure, local vs cloud
   runtimes, sessions, state layout, and invariants (Node not Bun, root
@@ -38,11 +38,11 @@ pnpm exec tsx src/bin/agent-serve.ts <cmd> ...
    before shipping. Classic miss: a tool `execute` return that fails
    `ToolExecuteResult` — returns must be JSON-shaped, so use object
    literals or `type` aliases, not `interface` types.
-4. **Keep session state out of big monorepos.** Session workspaces are real
-   Cursor project directories and inherit ambient `AGENTS.md`/`.cursor`
-   rules from **ancestors**. Set `defineAgent({ local: { cwd } })` outside
-   the monorepo or pass a temp `--state-root`. (`run`/`eval` already use a
-   temp state root.)
+4. **Harness cwd in a nested git repo.** Discovery defaults `local.cwd` to
+   `~/.cache/agent-serve/<dir>` so ancestor `AGENTS.md` / `.cursor` / IDE
+   MCP do not leak into playground turns. Set cwd at a checkout only when
+   the agent must inherit that tree. Attached MCP is invisible by name
+   until `advertiseTools: true`. `hostOnly` hides it from the model.
 5. **A model turn needs `CURSOR_API_KEY`.** Everything structural
    (`validate`, `info`, `call`, `serve` bring-up) works without one.
 
@@ -57,7 +57,7 @@ path live under README "Folder structure".
 | `agent/instructions.md` | Always-on system prompt (required; `.ts`/dir forms exist) |
 | `agent/tools/<name>.ts` | One typed tool; filename = tool name. `execution: "server"` (in-process, default) or `"agent"` (script that runs where the agent runs) |
 | `agent/skills/*` | SKILL.md-convention procedures, loaded on demand |
-| `agent/mcp-connections/<name>.ts` | MCP servers — available to the model, to server tools (`ctx.host.mcp`), and to channel/schedule handlers (`args.host.mcp`). `{ tools }` authors TypeScript the Agent SDK packages as stdio MCP for the agent environment. |
+| `agent/mcp-connections/<name>.ts` | MCP servers. Do not name an account connection `cursor.ts`. `advertiseTools: true` for named tools on local turns; `hostOnly` keeps them off the model. `{ tools }` authors TypeScript the Agent SDK packages as stdio MCP. |
 | `agent/subagents/<id>/` | Child agent dir (`description` required; per-subagent tools/skills/MCP connections ignored for now) |
 | `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` / `github.ts` use the platform packs |
 | `agent/hooks/*.ts` | Observe-only event subscribers (never fatal) |

package/skills/github/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentkit-github
+name: agentsdk-github
 description: >-
   Build and test GitHub-webhook-driven Agent SDK agents: githubChannel
   hooks (auth turn vs host task), signature modes, and testing tiers

package/skills/hillclimb/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentkit-hillclimb
+name: agentsdk-hillclimb
 description: >-
   Iterate on a specific Agent SDK agent by running the local server,
   sending real requests, measuring correctness/efficiency, and proposing

package/skills/mcp-auth/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: agentkit-mcp-auth
+name: agentsdk-mcp-auth
 description: >-
   Authorize host MCP OAuth for defineConnection({ url, oauth: true }):
   agent-sdk mcp oauth, local mcp-auth.json, --store deployment secrets,
-  hostOnly, and egress. Read when wiring or debugging MCP auth.
+  hostOnly, advertiseTools, and egress. Read when wiring or debugging MCP auth.
 ---
 
 # Host MCP OAuth (mcp auth)
@@ -26,13 +26,15 @@ Docs: `docs/guides/mcp-oauth.md`, `docs/reference/connections.md`,
 | Remote URL that speaks OAuth; host must hold tokens | `defineConnection({ url, oauth: true })` + this skill |
 | Static bearer / API key | `headers` / env on a plain `{ url }` connection |
 
-Prefer `hostOnly: true` when only host tools / channel handlers should
-call the server (admin APIs, privileged writes). The model will not see
-those tools.
+Set `hostOnly: true` only when host tools / channel handlers should call
+the server and the model should not (admin APIs, privileged writes).
+Playground chat will not see those tools. For connectors the model should
+call on local turns (Linear, Datadog, account MCP), omit `hostOnly` and
+set `advertiseTools: true`.
 
 ## Goal checklist
 
-- [ ] `agent/mcp-connections/<name>.ts` with `url` + `oauth: true` (+ `hostOnly` if privileged)
+- [ ] `agent/mcp-connections/<name>.ts` with `url` + `oauth: true` (`hostOnly` if privileged; `advertiseTools` if the model should call it)
 - [ ] `hosting.secretNames` lists `MCP_OAUTH_<NAME>_{ACCESS_TOKEN,REFRESH_TOKEN,CLIENT_ID}` when you will `--store`
 - [ ] Hosted engines that reach non-bootstrap hosts declare `hosting.egressDomains`
 - [ ] Local: `agent-sdk mcp oauth <name>` succeeds
@@ -127,7 +129,7 @@ redeploy completed, then exercise the same host tool once.
 | `Unknown MCP connection` | Filename under `agent/mcp-connections/` must match CLI arg |
 | Callback hang | Free port 8787; finish browser flow on this machine |
 | Hosted 401 / unauthorized | `secrets list`; re-run `--store`; redeploy |
-| Model invents `mcp_auth` / IDE MCP | Connection is `hostOnly`; fix instructions + use host tools |
+| Model invents `mcp_auth` / IDE MCP | `hostOnly` hid it, or attached MCP is behind meta-tools. Use host tools for privileged servers. Set `advertiseTools: true` for named tools on local turns. |
 | Tokens ignored after URL edit | Expected; run `mcp oauth` again for the new resource URL |
 
 ## Don't

package/skills/otel/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentkit-otel
+name: agentsdk-otel
 description: >-
   Wire OpenTelemetry export for an Agent SDK agent (defineOtel, OTLP env,
   traces/metrics/logs, ctx.host.otel). Use when adding observability,

package/skills/setup-slack/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: agentkit-setup-slack
+name: agentsdk-setup-slack
 description: >-
   Wire Slack to an Agent SDK agent. Gate Cursor-hosted vs a dedicated
   Socket Mode app, then finish that path: cursorAccount sign-in + smoke,

package/src/bin/agent-serve.ts

@@ -216,11 +216,13 @@ Commands:
               -> MCP). Review the project, then run \`validate\` / \`dev\`.
               Warnings never fail the command.
   install-skills
-              Install (or refresh) the Agent SDK skills for coding agents in
-              ~/.cursor/skills/agentkit and print where they landed. \`init\`
-              offers this once, interactively, and skips it when the prompt
-              goes unanswered; this command never asks. --print previews
-              without writing.
+              Refresh the Agent SDK skills for coding agents in
+              ~/.cursor/skills/agentsdk and print where they landed.
+              Installed copies set alwaysApply so Cursor injects them
+              into context. \`npm install\` / \`npx\` already copies them
+              (postinstall); this command overwrites with the package
+              version without asking. \`init\` also offers a TTY refresh.
+              --print previews without writing.
   mcp         Serve this agent's MCP endpoint over stdio for MCP clients
               that spawn local servers (e.g. Cursor). Proxies
               newline-delimited JSON-RPC to <target>/v1/mcp. --prod resolves
@@ -1260,7 +1262,8 @@ async function main(argv: string[]): Promise<number> {
           values["cursor-events"] === true
             ? { repos: values.repo ?? [] }
             : undefined,
-        // Soft boot logs (GitHub auth, etc.) stay secondary to the banner.
+        // Soft boot logs stay secondary to the banner. `dim` is a no-op on
+        // already-styled lines (the MCP warning box).
         logger: (line: string) => {
           process.stdout.write(`${style.dim(line)}\n`);
         },
@@ -1700,7 +1703,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.
+// command touches a project. In-repo CLI is `bin/agentsdk`.
 registerAuthoredModuleLoaders()
   .then(() => main(process.argv.slice(2)))
   .then(

package/src/channels/github/api.ts

@@ -535,7 +535,12 @@ function isOctokitRequestError(error: unknown): error is {
   );
 }
 
-function wrapOctokitError(error: unknown, method: string, path: string): Error {
+/** Normalize an Octokit request failure into {@link GitHubApiError}. */
+export function wrapOctokitError(
+  error: unknown,
+  method: string,
+  path: string
+): Error {
   if (isOctokitRequestError(error)) {
     return new GitHubApiError({
       body: error.response?.data,

package/src/channels/github/binding.ts

@@ -17,6 +17,11 @@ import {
   type GitHubPostedComment,
   type GitHubReactionContent,
 } from "./api.js";
+import {
+  createGitHubCheck,
+  type GitHubCheck,
+  type GitHubCheckCreateInput,
+} from "./checks.js";
 import type {
   GitHubChannelCredentials,
   GitHubConversationKind,
@@ -79,6 +84,14 @@ export interface GitHubHandle {
     description?: string;
     targetUrl?: string;
   }): Promise<GitHubApiResponse>;
+  /**
+   * Open a CI check run (Checks API) on `sha` and get a handle for updating
+   * and concluding it. Needs `checks:write` — with `cursorAccount`, declare
+   * `githubChannel({ checks: true })` to opt the lease up.
+   */
+  createCheck(
+    input: Omit<GitHubCheckCreateInput, "github" | "owner" | "repo">
+  ): Promise<GitHubCheck>;
 }
 
 /** Thread-scoped operations for the current conversation (`ctx.thread`). */
@@ -149,6 +162,14 @@ export function buildGitHubBinding(input: {
           : { targetUrl: status.targetUrl }),
       });
     },
+    createCheck(check) {
+      return createGitHubCheck({
+        ...check,
+        github: { getOctokit },
+        owner: state.owner,
+        repo: state.repo,
+      });
+    },
   };
 
   const thread: GitHubThread = {

package/src/channels/github/checks.ts

@@ -0,0 +1,179 @@
+/**
+ * Generic CI checks (GitHub Checks API) for agent authors.
+ *
+ * `createGitHubCheck` opens a merge-box check run on a commit and returns a
+ * handle for updating and concluding it, so an agent can report its own CI
+ * result (name, summary, and a "Details" link — e.g. the agent session run).
+ * Works with any client exposing `getOctokit()` (`ctx.github`,
+ * `ctx.host.github`), and is also reachable as `ctx.github.createCheck(...)`.
+ *
+ * Posting checks needs `checks:write`. With `cursorAccount`, declare
+ * `githubChannel({ checks: true })` so the hosted lease is minted on the
+ * `contents-write` tier; GitHub App / PAT credentials need the equivalent
+ * permission.
+ */
+
+import type { Octokit } from "@octokit/rest";
+import {
+  type GitHubCheckRunConclusion,
+  type GitHubCheckRunStatus,
+  wrapOctokitError,
+} from "./api.js";
+
+/** Any client that can hand out an authenticated Octokit. */
+export interface GitHubCheckClient {
+  getOctokit(): Promise<Octokit>;
+}
+
+/** Output shown on the check page (both fields required by GitHub). */
+export interface GitHubCheckOutput {
+  /** Heading on the check page. */
+  title: string;
+  /** Markdown body (supports links, e.g. `[View session](…)`). */
+  summary: string;
+}
+
+export interface GitHubCheckCreateInput {
+  /** Client used for every API call on the returned handle. */
+  github: GitHubCheckClient;
+  /** Repository owner login, e.g. `"acme"`. */
+  owner: string;
+  /** Repository name, e.g. `"widgets"`. */
+  repo: string;
+  /** Check name shown in the PR merge box, e.g. `"Cursor Security Review"`. */
+  name: string;
+  /** Commit the check attaches to (usually the PR head SHA). */
+  sha: string;
+  /** Initial status. Defaults to `"in_progress"`. */
+  status?: "queued" | "in_progress";
+  /** "Details" link on the check, e.g. the agent session run URL. */
+  detailsUrl?: string;
+  /** Title + markdown summary shown on the check page. */
+  output?: GitHubCheckOutput;
+}
+
+export interface GitHubCheckUpdateInput {
+  status?: GitHubCheckRunStatus;
+  conclusion?: GitHubCheckRunConclusion;
+  detailsUrl?: string;
+  output?: GitHubCheckOutput;
+}
+
+export interface GitHubCheckConcludeInput {
+  /** Final result shown in the merge box. */
+  conclusion: GitHubCheckRunConclusion;
+  detailsUrl?: string;
+  output?: GitHubCheckOutput;
+}
+
+/** A created check run. All methods throw `GitHubApiError` on API failure. */
+export interface GitHubCheck {
+  /** Check run id (for reuse across process restarts). */
+  readonly id: number;
+  /** GitHub web URL of the check run page, when returned by the API. */
+  readonly url: string | undefined;
+  /** Patch status / output / details link while the check is running. */
+  update(input: GitHubCheckUpdateInput): Promise<void>;
+  /** Complete the check with a conclusion (sets `completed_at`). */
+  conclude(input: GitHubCheckConcludeInput): Promise<void>;
+}
+
+/**
+ * Create a CI check run on a commit and return a handle for later updates.
+ *
+ * ```ts
+ * const check = await createGitHubCheck({
+ *   github: ctx.github,
+ *   owner: ctx.repository.owner,
+ *   repo: ctx.repository.name,
+ *   name: "Cursor Security Review",
+ *   sha: pr.headSha,
+ *   detailsUrl: sessionUrl,
+ *   output: { title: "Running…", summary: `[View session](${sessionUrl})` },
+ * });
+ * // …do the work…
+ * await check.conclude({ conclusion: "success", output: { … } });
+ * ```
+ */
+export async function createGitHubCheck(
+  input: GitHubCheckCreateInput
+): Promise<GitHubCheck> {
+  const octokit = await input.github.getOctokit();
+  let created: { id: number; html_url?: string | null };
+  try {
+    const response = await octokit.rest.checks.create({
+      owner: input.owner,
+      repo: input.repo,
+      name: input.name,
+      head_sha: input.sha,
+      status: input.status ?? "in_progress",
+      started_at: new Date().toISOString(),
+      details_url: input.detailsUrl,
+      output: input.output,
+    });
+    created = response.data;
+  } catch (error) {
+    throw wrapOctokitError(
+      error,
+      "POST",
+      `/repos/${input.owner}/${input.repo}/check-runs`
+    );
+  }
+  return resumeGitHubCheck({
+    github: input.github,
+    owner: input.owner,
+    repo: input.repo,
+    name: input.name,
+    checkRunId: created.id,
+    url: typeof created.html_url === "string" ? created.html_url : undefined,
+  });
+}
+
+/**
+ * Rebuild a {@link GitHubCheck} handle for an existing check run id (e.g.
+ * after a process restart). No API call is made until the first update.
+ */
+export function resumeGitHubCheck(input: {
+  github: GitHubCheckClient;
+  owner: string;
+  repo: string;
+  name: string;
+  checkRunId: number;
+  url?: string;
+}): GitHubCheck {
+  const patch = async (update: GitHubCheckUpdateInput): Promise<void> => {
+    const octokit = await input.github.getOctokit();
+    try {
+      await octokit.rest.checks.update({
+        owner: input.owner,
+        repo: input.repo,
+        check_run_id: input.checkRunId,
+        name: input.name,
+        status: update.status,
+        conclusion: update.conclusion,
+        completed_at:
+          update.status === "completed" ? new Date().toISOString() : undefined,
+        details_url: update.detailsUrl,
+        output: update.output,
+      });
+    } catch (error) {
+      throw wrapOctokitError(
+        error,
+        "PATCH",
+        `/repos/${input.owner}/${input.repo}/check-runs/${input.checkRunId}`
+      );
+    }
+  };
+  return {
+    id: input.checkRunId,
+    url: input.url,
+    update: patch,
+    conclude: (conclude) =>
+      patch({
+        status: "completed",
+        conclusion: conclude.conclusion,
+        detailsUrl: conclude.detailsUrl,
+        output: conclude.output,
+      }),
+  };
+}