@cursor/july 0.1.111 → 0.1.113

package/docs/templates/thermo-review.md

@@ -0,0 +1,79 @@
+---
+title: "Review pull requests for bugs and breakage"
+description: "Scaffold the agent, deploy it, and open a PR."
+---
+
+# Review pull requests for bugs and breakage
+
+This agent reads a pull request diff and posts one review comment. It
+reports bugs, breaking side effects, devex breaks, and feature-gate
+leaks in added or modified code. Style nits stay out.
+
+This template is one model turn: read the diff, then post one comment.
+
+## Scaffold
+
+```bash
+npx @cursor/july init ./thermo-review --template thermo-review
+cd thermo-review
+```
+
+## Deploy
+
+Sign in once, then deploy from a pushed checkout:
+
+```bash
+agent-sdk login
+agent-sdk deploy --cursor-events-repo acme/api
+```
+
+Repeat `--cursor-events-repo` for each repo. Every repo must share one
+owner. The deployment watches those repos through your team's Cursor
+GitHub connection and reviews each opened PR. No webhook or local
+server.
+
+Change repos later without redeploying:
+
+```bash
+agent-sdk event-repos thermo-review --repo acme/api --repo acme/web
+```
+
+## Try it locally
+
+Skip the deploy while you iterate. Start the relay for one repo:
+
+```bash
+agent-sdk dev --cursor-events --repo acme/api
+```
+
+Open a PR, or replay a known one without pushing:
+
+```bash
+agent-sdk github replay https://github.com/acme/api/pull/12 --dir .
+```
+
+`replay` needs pull access. Draft PRs are ignored. The channel writes
+`pr/diff.patch`, then starts a model turn. The model calls
+`post_findings` once. Chat replies stay in the playground.
+`post_findings` writes the GitHub comment.
+
+Connect GitHub in Cursor first (Settings or
+[cursor.com/dashboard](https://cursor.com/dashboard)) so the relay and
+API calls use your account. See the [GitHub guide](../guides/github.md).
+
+## Evals
+
+Two smoke cases: one auth-bypass fixture and one docs-only change. They
+need no GitHub access.
+
+```bash
+agent-sdk eval
+```
+
+Eval sessions skip the GitHub write.
+
+## What to edit
+
+- `agent/instructions.md`: what counts as a finding and the comment
+  shape
+- `evals/review.eval.ts`: smoke cases

package/docs/troubleshooting.md

@@ -1,115 +1,146 @@
 ---
 title: "Fix common agent problems"
-description: "Match what you see to a cause, then read a session trace when you need more detail."
+description: "Match the symptom to one corrective action, then inspect the session trace when the first fix is not enough."
 ---
 
 # Fix common agent problems
 
-Start with four checks, in order:
+Start with three checks:
 
-1. Project discovery: `agent-sdk validate --dir .`
-2. Whether the serve process is running
-3. What the playground or HTTP API shows
-4. The session event stream (trace)
+1. Run `agent-sdk validate --dir .`.
+2. Confirm the expected agent and connections in
+   `agent-sdk info --dir . --json`.
+3. Reproduce once, then inspect the serve log or session trace.
 
-Match your symptom below. Keep the commands as `agent-sdk`. If it is
-not on `PATH`, use `npx @cursor/july`.
+Match the visible symptom below. If `agent-sdk` is not on `PATH`, use
+`npx @cursor/july`.
 
-## What if serve or the playground looks wrong?
+## Serve or the playground will not work
 
 | What you see | What to do |
 | --- | --- |
-| `serve` won't start | Run `agent-sdk validate --dir .` and fix the reported errors. |
-| Playground is blank or says there are no agents | The UI needs a running `serve` process. Building the playground assets alone is not enough. |
-| The playground UI looks stale | `serve --dev` prints a playground URL. Open that URL. Agent-file edits still need a restart (press Enter on the TTY). |
-| Sessions exist but the playground list is empty | The list shows sessions for the authenticated caller. In `--dev` on loopback the list is wider. Otherwise open `/<slug>/playground?sessionId=ses_…`. |
-| Port 3000 is already in use | For the default serve port, the CLI tries the next free port and prints a notice. Pass `--port` to pick one, or `--port 0` for any free port. Stop leftover playground or webhook-forwarder processes if you need the original port. |
+| `serve` exits before listening | Fix the errors from `agent-sdk validate --dir .`, then start it again. |
+| Playground is blank or says there are no agents | Start `agent-sdk serve`; built playground assets have no agent data without the server. |
+| Agent-file edits do not appear | Open the URL printed by `serve --dev`, then press Enter in its TTY to reload after file changes. |
+| Sessions exist but the list is empty | The list is scoped to the authenticated principal. Use the same identity that created the session; a `?sessionId=` deep link does not bypass authorization. |
+| The preferred port is busy | Use the next port printed by the CLI, pass `--port <number>`, or pass `--port 0` for any free port. |
 
-## What if a model turn goes wrong?
+## A model turn fails
 
 | What you see | What to do |
 | --- | --- |
-| 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` or `CURSOR_SERVICE_ACCOUNT_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. Nested git checkouts default `local.cwd` to a per-project cache directory under `~/.cache`. 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 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 | Server tools and sandbox seeds apply on the local runtime (cloud server tools need `--public-url` / `--cloud-tools-url`). Skills reach cloud through the Agent Store when hosting or a personal `CURSOR_API_KEY` is available; otherwise only skills already in the cloud repo. `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. |
+| File reads and greps fail repeatedly with `NGHTTP2_FRAME_SIZE_ERROR` | Run the agent under Node 22.13 or newer, never Bun. |
+| The turn immediately reports a missing API key | Set `CURSOR_API_KEY`, `CURSOR_API_KEY_FILE`, or `CURSOR_SERVICE_ACCOUNT_KEY`, or run `agent-sdk login`. |
+| Login succeeds but the model host rejects the key | Point login and model traffic at the same API host; check `CURSOR_API_BASE_URL` and `CURSOR_BACKEND_URL`. |
+| Cloud turns cannot reach local tools or skills | Give the cloud runtime a reachable `--public-url` and protected tool bridge, or move the required capability into the cloud checkout. See [agent runtime](./reference/agent-config.md#choose-a-runtime). |
 
-## What if the HTTP API returns an error?
+## A turn behaves unexpectedly
 
 | What you see | What to do |
 | --- | --- |
-| `409` on a follow-up message | Refresh the `continuationToken` or confirm the session is a chat session. Task sessions do not accept follow-ups. |
-| `409 session_busy` on `call --session` | The tool is a write (or declares no effect) and a model turn is running. Wait for the turn to finish, omit `--session` for a one-off call, or declare `effect: "read"` on a tool that only reads so it runs alongside turns. |
-| `403` on stream or follow-up | Use the same auth identity that created the session. Off localhost, pass `--bearer-token` and send it on every request. |
-| Works on localhost; blocked through a tunnel or LAN | Default auth allows only direct loopback callers. Share the host with `--bearer-token <secret>` (or authored `bearerAuth`). Use `--allow-anonymous` only on a trusted private network. |
-| A channel route fails to compile with a schema type error | `GET` routes need a Zod `querySchema`. `POST` / `PUT` / `PATCH` need a Zod `bodySchema`. Use `z.object({})` or `z.unknown()` for open shapes. |
+| Replies quote an ancestor `AGENTS.md` or unrelated repository rules | Inspect `local.cwd` in `/v1/info`. Set `defineAgent({ local: { cwd } })` or the session workspace explicitly instead of inheriting the parent checkout. |
+| The model lists IDE meta-tools but never calls named MCP tools | Set `advertiseTools: true` on the local model-visible connection and confirm it under `connections` in `/v1/info`. |
+| Server tools, skills, or seed files are absent | Check the selected local/cloud runtime and discovered project in `/v1/info`; follow the capability warning from `validate`. |
+| `validate` and `run` pass but CI type-checking fails | Run the project type check. Tool results must be JSON-shaped; prefer object literals or `type` aliases over `interface` return types. |
 
-## What if GitHub webhooks misbehave?
+## HTTP returns 401, 403, or 409
 
 | What you see | What to do |
 | --- | --- |
-| `github forward` returns 401 on every delivery, but the hook was created | Clear `GITHUB_TOKEN` and `GH_TOKEN` for that command. The forwarder uses your `gh` CLI login: `GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward …` |
-| `Hook already exists` when starting a forwarder | GitHub allows one forwarder per repo. Run a single `github forward --dir <parent>` and stop stale forwarders. |
-| Deliveries rejected outside `--dev` | Set `GITHUB_WEBHOOK_SECRET` on the server and on the signer. Without a secret, the channel stays loopback-only. |
-| You lack repo admin and can't forward | Use `agent-sdk github replay <pr-url>`. It needs pull access only and posts signed test payloads. |
+| `401` outside localhost | Send the configured bearer token, alias token, or channel credential. Default custom routes admit direct loopback only. |
+| `403` on a stream or follow-up | Use the same authenticated principal that created the session. |
+| A localhost route fails through a tunnel or LAN | Protect the shared host with `--bearer-token` or authored channel auth. Use `--allow-anonymous` only behind a proxy that authenticates every caller. |
+| `409` on a follow-up | Refresh the rotating `continuationToken` and confirm the target is a chat session; task sessions do not accept follow-ups. |
+| `409 session_busy` from `call --session` | Wait for the turn, omit `--session`, or mark a read-only tool with `effect: "read"` so it can run concurrently. |
+| A custom route fails schema type-checking | Add the required Zod `querySchema` for `GET`, or `bodySchema` for `POST`, `PUT`, and `PATCH`. See [Channels](./reference/channels.md). |
 
-## What if Slack stays quiet?
+## A hosted deployment fails or looks stale
 
 | What you see | What to do |
 | --- | --- |
-| Logs show `channel idle … missing credentials` | Expected when tokens are missing. Run `agent-sdk slack create --dir <agent>` to provision the app and write the tokens, or `agent-sdk slack init --manual --dir <agent>` and paste the manifests at api.slack.com. Then set `<PREFIX>_SLACK_BOT_TOKEN` and `<PREFIX>_SLACK_APP_TOKEN` per agent and run `agent-sdk slack doctor --prefix <PREFIX>`. |
-| `slack create` reports the app needs admin approval | Open Slack's **Request approval** page (the CLI prints the link; the same URL is **Send a reminder** after you submit). Managed install does not file the request. Keep the CLI running, then click **Retry** in the dashboard after an admin approves. |
-| The bot ignores ordinary channel posts | Default engagement is mentions and DMs only. Enable `engagement.channelPosts` with an allowlist, and subscribe the app to `message.channels` / `message.groups`. |
-| Approve / Deny buttons do nothing | Channels that post approval cards need `toolApprovals: true`. Recreate the app with `slack create` if interactivity is off. |
+| Local changes do not appear after deploy | `deploy` reads a pushed Git ref, not the working tree. Commit and push the intended ref, then deploy it again. |
+| The deployment never becomes running | Run `agent-sdk deployment <slug>` and `agent-sdk logs --prod --slug <slug>`, then act on the reported build or startup error. |
+| A secret or egress change has no effect | Confirm the name with `secrets list`, verify the `hosting` block exists on the pushed ref, and follow the CLI or dashboard prompt to redeploy. |
+| Cursor events stopped after redeploy | Redeploy replaces CLI-supplied event repositories. Pass every `--cursor-events-repo` value again. |
+| External HTTP rejects the alias token | Update the caller with the current token. If the token is lost or exposed, run `agent-sdk rotate-token <slug>` and replace it everywhere. |
 
-## What if host MCP OAuth fails?
+See [Deployment](./deployment.md) for source, credential, and
+redeployment boundaries.
+
+## GitHub deliveries fail
+
+| What you see | What to do |
+| --- | --- |
+| `github forward` returns 401 on every delivery after creating the hook | Clear `GITHUB_TOKEN` and `GH_TOKEN` for that command so the forwarder uses the `gh` CLI login: `GITHUB_TOKEN= GH_TOKEN= agent-sdk github forward ...`. |
+| `Hook already exists` | Run one forwarder for the repository and stop the stale process. |
+| Direct webhook deliveries are rejected outside `--dev` | Configure the same `GITHUB_WEBHOOK_SECRET` on the signer and server. Cursor event pull needs no public webhook or webhook secret. |
+| You cannot create a forwarder | Use `agent-sdk github replay <pr-url>`; it needs pull access instead of repository administration. |
+
+The [GitHub guide](./guides/github.md) covers event pull, replay, and
+direct webhooks.
+
+## Slack does not respond
 
 | What you see | What to do |
 | --- | --- |
-| `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 | Finish Connect on the hosted engine, or 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 connector it already has | Attached MCP is behind meta-tools. Set `advertiseTools: true` for named tools on local turns, or call it from a host tool via `ctx.host.mcp`. |
+| Logs say `channel idle ... missing credentials` | Run `agent-sdk slack create --dir <agent>`, then check the generated prefix with `agent-sdk slack doctor`. Use `slack init --manual` only for an app you own. |
+| `slack create` is waiting for workspace approval | Open the approval link printed by the CLI, keep the command running, and retry after an admin approves. |
+| The bot ignores ordinary channel posts | Configure `engagement.channelPosts`, create the app with `--channel-posts`, and invite it to every allowed channel. |
+| Approval buttons do nothing | Set `toolApprovals: true`, then recreate the app if its interactivity is not enabled. |
 
-See [Host MCP OAuth](./guides/mcp-oauth.md) and
-[`skills/mcp-auth/SKILL.md`](../skills/mcp-auth/SKILL.md).
+See the [Slack guide](./guides/slack.md) for app setup and engagement
+choices.
 
-## What if a secret showed up in a terminal transcript?
+## MCP authorization fails
 
 | What you see | What to do |
 | --- | --- |
-| `secrets set … NAME=VALUE` in an agent-captured terminal or shell history | Rotate the secret at the provider. Set it again with names only: `agent-sdk secrets set <slug> NAME` (hidden prompt) or pipe/redirect the value. `NAME=VALUE` requires `--from-argv` and still leaks into argv. |
-| Alias token printed during first deploy or `rotate-token` | Treat it as exposed if the transcript left your machine. Run `agent-sdk rotate-token <slug>`, store the new token outside agent transcripts, and update callers. |
-| Someone verified a secret with `echo` / `printenv` | Rotate it. Confirm presence with `agent-sdk secrets list <slug>` (names only), then redeploy and test the feature. |
+| `must be defineConnection({ url, oauth: true })` | Add `oauth: true` to the named URL connection or correct the connection filename passed to `mcp oauth`. |
+| Local auth works but hosted calls return unauthorized | Complete Connect for the running process, or run `mcp oauth <name> --store` and redeploy for future replacements. |
+| The model invents `mcp_auth` instead of calling the server | Set `advertiseTools: true` for named local tools, or expose a host-side wrapper through `ctx.host.mcp`. |
 
-## What if schedules, reminders, or approvals stall?
+See [Host MCP OAuth](./guides/mcp-oauth.md) for the credential lifecycle.
+
+## Schedules, reminders, or approvals stall
+
+| What you see | What to do |
+| --- | --- |
+| A schedule or reminder never fires under `--dev` | Trigger it through the matching `/v1/dev/schedules/<id>` or `/v1/dev/reminders/<id>` route; development mode does not auto-fire. |
+| A pending approval disappears after restart | Parked approvals do not survive restart. Run the turn again. |
+| A reminder is disarmed with `handler_lost_on_restart` | Recreate handler-form reminders after restart, or use a prompt-form reminder. |
+| The same schedule fires on several self-hosted processes | Enable schedules on one serving process per project and pass `--no-schedules` to the others. |
+
+## A credential was exposed
 
 | What you see | What to do |
 | --- | --- |
-| A schedule or reminder never fires under `--dev` | Dev mode does not auto-fire. Trigger with `POST /<slug>/v1/dev/schedules/<id>` or `POST /<slug>/v1/dev/reminders/<id>` (list reminders at `GET /v1/dev/reminders`). |
-| A pending tool approval disappeared after restart | Parked approvals do not survive host restart. They resolve as interrupted. Run the turn again. |
-| A reminder is disarmed after restart (`handler_lost_on_restart`) | Handler-form reminders live in memory. Re-arm them from the code that created them, or use prompt-form reminders. |
+| A secret value appears in a command, transcript, or shell history | Rotate it at the provider, set it again through hidden input or stdin, and test the feature. |
+| An alias token appears outside its secure destination | Run `agent-sdk rotate-token <slug>`, store the new value outside transcripts, and update every caller. |
+| Someone printed a secret to verify it | Rotate it. Confirm only the name with `agent-sdk secrets list <slug>`, then redeploy and exercise the feature. |
+
+## Read the session trace
 
-## How do I read a session trace?
+Start with `actions.requested` and `action.result`. Count calls by tool
+name, pair every request with its result, and separate host preparation
+from tools chosen by the model.
 
-Look at `actions.requested` / `action.result` pairs for the tool
-trajectory. Count calls by tool name before blaming latency. Separate
-host-side work (channel `callTool`, preparation) from tools the model
-chose.
+`turn.failed` with `turn interrupted` usually means a follow-up or stop
+ended the turn deliberately. Other failures should have an error event
+near the tool or model boundary that produced them.
 
-`turn.failed` with `"turn interrupted"` means a follow-up or stop ended
-the turn on purpose.
+Use the trace path printed by `agent-sdk run`:
 
-If the model reads outside the session workspace, the prepared files
-don't match what the instructions expect. Fix the layout. See
-[Hillclimbing](./hillclimbing.md).
+```bash
+agent-sdk trajectory --events <trace-path>
+```
 
-`agent-sdk trajectory --events <file>` summarizes any saved NDJSON
-stream. The playground **Open trace** control does the same visually.
+The playground's **Open trace** control renders the same trajectory.
+When the agent runs but makes poor decisions, move from diagnosis to a
+measured [hillclimb](./hillclimbing.md).
 
-## What's next
+## Related
 
-- [Hillclimbing](./hillclimbing.md): when the agent runs but underperforms
-- [Deployment](./deployment.md): auth and state on shared hosts
+- [Deployment](./deployment.md): hosted and self-hosted boundaries
+- [Sessions](./reference/sessions.md): session ownership and event
+  vocabulary
+- [CLI reference](./reference/cli.md): command flags and exit behavior

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.111",
+  "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/skills/github/SKILL.md

@@ -23,10 +23,18 @@ export default githubChannel({
   botName: "my-agent",
   cursorAccount: { repos: ["owner/repo"] }, // permissions?: "read" | "pr-write" | "contents-write"
 
-  onPullRequest: (ctx, pr) =>
-    pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
-  onCheckSuite: (ctx, suite) =>
-    suite.conclusion === "failure" ? { task: () => triage(ctx) } : null,
+  onPullRequest: (ctx, pr) => {
+    if (pr.action !== "opened") {
+      return null;
+    }
+    return { auth: defaultGitHubAuth(ctx) };
+  },
+  onCheckSuite: (ctx, suite) => {
+    if (suite.conclusion !== "failure") {
+      return null;
+    }
+    return { task: () => triage(ctx) };
+  },
 });
 ```
 
@@ -34,11 +42,11 @@ Hooks: `onPullRequest`, `onComment`, `onIssue`, `onCheckSuite`,
 `onCheckRun`, `onWorkflowRun`, `onStatus`, plus `onEvent` and
 `onStart`/`onStop`.
 
-| Return | Meaning |
-| --- | --- |
+| Return     | Meaning                                                                          |
+| ---------- | -------------------------------------------------------------------------------- |
 | `{ auth }` | Model turn. Session shows in the playground. `workspaceFiles` can be a function. |
-| `{ task }` | Host work. No chat session. Use when the work can outlive a webhook timeout. |
-| `null` | Skip |
+| `{ task }` | Host work. No chat session. Use when the work can outlive a webhook timeout.     |
+| `null`     | Skip                                                                             |
 
 To keep repo scope in deploy config, use `cursorAccount: true`
 and pass `--repo owner/name` at serve / `--cursor-events-repo`
@@ -46,11 +54,11 @@ at deploy. Repos must share one GitHub owner.
 
 ## Event sources
 
-| Source | When |
-| --- | --- |
-| `cursorAccount` + `serve --cursor-events` | Preferred. Signed-in host (`agent-sdk login`, `CURSOR_API_KEY`, or `CURSOR_SERVICE_ACCOUNT_KEY`). Repos from the channel and from repeatable `--repo owner/name`. Cap 20, one GitHub owner |
-| HTTP `POST /<slug>/v1/channels/github` with a webhook secret | `allowAll()` + `X-Hub-Signature-256` |
-| HTTP, no secret | Loopback only. `serve --dev` also admits unsigned loopback (fixtures / forward) |
+| Source                                                       | When                                                                                                                                                                                       |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `cursorAccount` + `serve --cursor-events`                    | Preferred. Signed-in host (`agent-sdk login`, `CURSOR_API_KEY`, or `CURSOR_SERVICE_ACCOUNT_KEY`). Repos from the channel and from repeatable `--repo owner/name`. Cap 20, one GitHub owner |
+| HTTP `POST /<slug>/v1/channels/github` with a webhook secret | `allowAll()` + `X-Hub-Signature-256`                                                                                                                                                       |
+| HTTP, no secret                                              | Loopback only. `serve --dev` also admits unsigned loopback (fixtures / forward)                                                                                                            |
 
 `permissions`: `"read"` inspect; `"pr-write"` (default) comments /
 PR writes; `"contents-write"` push or merge-box checks.

package/src/bin/agent-serve.ts

@@ -42,6 +42,7 @@ import {
   cmdRun,
   cmdSession,
   cmdSessions,
+  cmdSkill,
   cmdTrajectory,
 } from "../internal/cli-ax.js";
 import {
@@ -115,6 +116,8 @@ Usage:
   ${CLI} trajectory  --events <file.ndjson> [--text]
   ${CLI} call        <tool> [--input <json>] [--dir <path> | --url <baseUrl> | --prod]
                           [--session <id>] [--slug <slug>] [--team <id>]
+  ${CLI} skill       <name> [--dir <path> | --url <baseUrl> | --prod]
+                          [--slug <slug>] [--team <id>] [--text]
   ${CLI} init        [dir] [--template <name>] [--var id=value]... [--json]
   ${CLI} convert-automation <url> [--dir <path>] [--json]
   ${CLI} install-skills [--print] [--json]
@@ -211,6 +214,8 @@ Commands:
   call        Call an authored server tool deterministically (no model turn)
               via POST /v1/tools/:toolName. --session runs it inside an
               existing session and records it on that session's event stream.
+  skill       Read an authored skill deterministically (no model turn)
+              via GET /v1/skills/:skillName. --text prints SKILL.md.
   init        Scaffold a project (skipping existing files), npm install,
               run login when unsigned, then print next steps. Templates
               with init.json interview on a TTY; --var answers without a
@@ -285,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.
@@ -989,6 +993,23 @@ async function main(argv: string[]): Promise<number> {
       );
     }
 
+    case "skill": {
+      return cmdSkill(
+        positionals[0],
+        axFromOptions({
+          dir,
+          text: values.text,
+          url: values.url,
+          prod: values.prod,
+          team: values.team,
+          apiKey: values["api-key"],
+          slug: values.slug,
+          bearerToken: values["bearer-token"],
+          stateRoot: values["state-root"],
+        })
+      );
+    }
+
     case "trajectory": {
       if (values.events === undefined) {
         process.stderr.write("trajectory requires --events <file.ndjson>\n");

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/github/github-channel.ts

@@ -615,25 +615,35 @@ export function getGitHubChannelOptions(
  *   credentials: { webhookSecret: () => process.env.GITHUB_WEBHOOK_SECRET },
  *   // Replaces the @mention gate. Prefer typed Octokit via getOctokit().
  *   onComment: (ctx, comment) => ({ auth: defaultGitHubAuth(ctx) }),
- *   onPullRequest: (ctx, pr) =>
- *     pr.action === "opened" ? { auth: defaultGitHubAuth(ctx) } : null,
- *   onStatus: (ctx, status) =>
- *     status.state === "failure"
- *       ? {
- *           task: async () => {
- *             const octokit = await ctx.github.getOctokit();
- *             await octokit.rest.repos.createCommitStatus({
- *               owner: ctx.repository.owner,
- *               repo: ctx.repository.name,
- *               sha: status.sha,
- *               state: "pending",
- *               context: "agent/triage",
- *             });
- *           },
- *         }
- *       : null,
- *   onEvent: (ctx, event) =>
- *     event.eventName === "label" ? { auth: defaultGitHubAuth(ctx) } : null,
+ *   onPullRequest: (ctx, pr) => {
+ *     if (pr.action !== "opened") {
+ *       return null;
+ *     }
+ *     return { auth: defaultGitHubAuth(ctx) };
+ *   },
+ *   onStatus: (ctx, status) => {
+ *     if (status.state !== "failure") {
+ *       return null;
+ *     }
+ *     return {
+ *       task: async () => {
+ *         const octokit = await ctx.github.getOctokit();
+ *         await octokit.rest.repos.createCommitStatus({
+ *           owner: ctx.repository.owner,
+ *           repo: ctx.repository.name,
+ *           sha: status.sha,
+ *           state: "pending",
+ *           context: "agent/triage",
+ *         });
+ *       },
+ *     };
+ *   },
+ *   onEvent: (ctx, event) => {
+ *     if (event.eventName !== "label") {
+ *       return null;
+ *     }
+ *     return { auth: defaultGitHubAuth(ctx) };
+ *   },
  * });
  * ```
  */

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/agentic-delivery.ts

@@ -196,6 +196,7 @@ async function postNew(args: {
       outcome: "progress_update",
       deliverySurface: "slack",
     });
+    await setChip(args.channel, "", args.botToken, args.getLog);
     return;
   }
   try {
@@ -219,6 +220,7 @@ async function postNew(args: {
       outcome: "final_post",
       deliverySurface: "slack",
     });
+    await setChip(args.channel, "", args.botToken, args.getLog);
   } catch (error) {
     log.warn(
       `agentic reply failed: ${