@cursor/july 0.1.41 → 0.1.43

package/docs/reference/hooks.md

@@ -27,7 +27,9 @@ import { defineHook } from "@cursor/july/hooks";
 export default defineHook({
   events: {
     async "turn.completed"(event, ctx) {
-      console.log("turn done", ctx.session.id, event.data.usage);
+      const prior = await ctx.host.kv.get("last-result");
+      const notes = await ctx.host.files.read("notes.md");
+      console.log("turn done", ctx.session.id, event.data.usage, prior, notes);
     },
     async "turn.failed"(event, ctx) {
       // page, count, or record
@@ -46,9 +48,14 @@ for everything. Handlers receive the event with its envelope (`index`,
 | `ctx.session` | Read-only session info: id, channel, mode, auth |
 | `ctx.agent` | `{ name }` of the agent the event belongs to |
 | `ctx.channel` | `{ id, continuationToken }` for the owning channel |
-| `ctx.stateRoot` | The agent's durable state root; hooks maintaining derived state write here |
+| `ctx.stateRoot` | The agent's durable state root. Prefer `ctx.host.kv` / `ctx.host.files` for derived state; this tree resets on hosted replace |
+| `ctx.host` | Shared host services; same as a tool's `ctx.host`. Pull JSON with `ctx.host.kv` and file-shaped state with `ctx.host.files` (session-bound by default; pass `{ scope: "deployment" }` for agent-wide files) |
 | `ctx.artifacts` | Session-bound [artifacts](./artifacts.md) facade: `tag` auto-fills the session |
 
+Hook context includes `ctx.host`, the same shared services a tool
+gets. Persist JSON with `ctx.host.kv` and file-shaped state with
+`ctx.host.files`. Hooks observe; they do not own delivery surfaces.
+
 ## Hooks, channel events, evals, or A/B?
 
 All of them consume the same stream, for different jobs:
@@ -60,6 +67,15 @@ All of them consume the same stream, for different jobs:
 | 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) |
 
+For GitHub commit status and sticky PR banners, use
+`githubChannel({ progress: { commitStatus, banner } })` from
+`@cursor/july/channels/github`. That is the supported Autofix-style
+path. See [GitHub: Show PR progress](../guides/github.md#show-pr-progress).
+Override channel `events` only when the lifecycle is custom (for
+example [Approval Buddy](../example-agents/approval-buddy.md)'s
+never-red status from tool output). Do not use `defineHook` for those
+writes.
+
 ## Patterns
 
 Usage metering: subscribe to `turn.completed` and forward
@@ -70,7 +86,9 @@ Failure alerting: `turn.failed` carries the message, and
 
 Derived state: `agent.bound` fires when the Cursor SDK agent id is known
 (`bc-…` on cloud). A PR agent can record PR → agent id from it in a
-hook, so later webhook wakes resume the same cloud conversation.
+hook with `ctx.host.kv`, so later webhook wakes resume the same cloud
+conversation. Prefer `ctx.host.kv` or `ctx.host.files` for ids that
+must survive hosted replace. `stateRoot` resets on replace.
 
 Transcript export: subscribe to `"*"` and append to your own store. The
 NDJSON envelope is already ordered and replayable.
@@ -80,8 +98,10 @@ NDJSON envelope is already ordered and replayable.
 Continue with these pages:
 
 - [Sessions and streaming](./sessions.md): every event a hook can see
-- [Deployment](../deployment.md#observability): hooks as the metrics
-  export path
+- [OpenTelemetry](../guides/opentelemetry.md): OTLP traces and metrics
+  from the same event stream
+- [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

package/docs/reference/project-layout.md

@@ -53,6 +53,7 @@ my-agent/
 │   │   └── github.ts          # the GitHub webhook channel pack
 │   ├── hooks/
 │   │   └── audit.ts           # observe the runtime event stream
+│   ├── otel.ts                # optional OpenTelemetry export
 │   ├── ab.ts                  # optional live A/B experiment
 │   ├── ab/
 │   │   └── concise.ts         # optional: more experiments
@@ -83,6 +84,7 @@ Each path maps to a capability and a reference page.
 | `agent/subagents/<id>/` | Child agent directory; `description` required | [Subagents](./subagents.md) |
 | `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` and `github.ts` use the platform packs | [Channels](./channels.md) |
 | `agent/hooks/*.ts` | Observe-only event subscribers, never fatal | [Hooks](./hooks.md) |
+| `agent/otel.ts` | `defineOtel` OTLP export (traces, metrics, optional logs) | [OpenTelemetry](../guides/opentelemetry.md) |
 | `agent/ab.ts`, `agent/ab/*.ts` | `defineAB` experiments with sticky variants and live metrics | [Live A/B metrics](../ab.md) |
 | `agent/ab.config.ts` | `defineABConfig` shared A/B settings | [Live A/B metrics](../ab.md) |
 | `agent/storage.ts` | `defineStorage` backend for the durable `host.kv` / `host.files` APIs | [Storage](../storage.md) |

package/docs/templates/triage.md

@@ -0,0 +1,147 @@
+---
+title: "Ship a triage agent from the template"
+description: "Scaffold the triage template, make its rubric yours, prove it with evals, and deploy it to Cursor-managed hosting."
+---
+
+# Ship a triage agent from the template
+
+The triage template is a working agent you own from the first command.
+It reads a report, classifies it as a bug, a question, or feedback,
+judges severity against a rubric, records a structured verdict, and
+replies with the next step. This page walks the whole arc: scaffold,
+first verdict, customize, prove, wire Slack, deploy.
+
+Every file the template ships is yours to edit. The only dependency is
+`@cursor/july` itself, pinned to the version the template was tested
+against. Nothing phones home to a template registry.
+
+## Scaffold it
+
+```bash
+npx @cursor/july init ./triage-agent --template triage
+```
+
+One command with no prior install. It writes twelve files, runs
+`npm install`, puts `agent-sdk` on your PATH, and offers a browser
+sign-in when the machine has no Cursor credential. Model turns need
+that credential, so sign in now rather than mid-flow:
+
+```bash
+agent-sdk login
+```
+
+The scaffold is a plain directory. Commit it to your own repo.
+
+## Get the first verdict
+
+```bash
+cd triage-agent
+agent-sdk dev
+```
+
+Open the playground URL it prints and type a real report:
+
+> Export to CSV has returned 500s since this morning. Request id 41ac.
+> Retrying does not help.
+
+Watch the turn. The agent reads the `triage-rubric` skill, calls
+`record_triage` with a structured verdict, and replies in six lines or
+fewer. The tool call renders inline, so you see the exact kind,
+severity, and next step it recorded.
+
+Integrations use the same door your playground does. The `intake`
+channel accepts reports over HTTP:
+
+```bash
+curl -X POST http://127.0.0.1:3000/triage-agent/v1/channels/intake/report \
+  -H 'content-type: application/json' \
+  -d '{"message":"How do I rotate staging API keys?","reporter":"dana"}'
+```
+
+The composer also autocompletes `/report`, which drives this route.
+
+## Make the rubric yours
+
+`agent/skills/triage-rubric.md` holds the judgment: what counts as a
+bug, the tie-breakers, and the severity ladder. Edit it first. Your
+team's definition of `urgent` belongs there, in plain markdown, and the
+next turn uses it without a restart step.
+
+`agent/instructions.md` owns the flow around the rubric: when to ask a
+clarifying question, the one-call `record_triage` rule, and the reply
+shape.
+
+## Prove it with evals
+
+The template ships three smoke cases, one per kind. Run them after
+every rubric edit:
+
+```bash
+agent-sdk eval
+```
+
+Each case sends a realistic report and asserts a verdict was recorded
+with the expected kind. When you tighten the rubric, add a case for the
+report style you tightened it for. The eval suite is the regression
+net for prompt changes, so grow it with the rubric.
+
+## File verdicts into your tracker
+
+`agent/tools/record_triage.ts` defines the verdict shape with a zod
+schema and returns it. Point its `execute` at Linear, GitHub Issues, or
+a webhook to file real tickets. Test the tool without a model turn:
+
+```bash
+agent-sdk call record_triage --dir . --input '{
+  "kind": "bug",
+  "severity": "high",
+  "title": "CSV export 500s",
+  "summary": "Export returns 500 since this morning.",
+  "nextStep": "Check export service logs."
+}'
+```
+
+The call validates against the schema and runs your `execute` body
+in-process, so tracker wiring gets a fast loop.
+
+## Wire it to Slack
+
+The `slack` channel idles until its tokens exist, so local work never
+blocks on Slack. When you want it live:
+
+```bash
+agent-sdk slack setup
+```
+
+The guided flow creates the Slack app and writes the token pair to
+`.env.local`. Restart `agent-sdk dev`, invite the bot to a channel, and
+@mention it with a report. The [Slack guide](../guides/slack.md) covers
+channel watching and approvals when you outgrow mentions.
+
+## Deploy it
+
+```bash
+agent-sdk deploy
+```
+
+From your git checkout, `deploy` infers the repo, ref, and slug, builds
+the ref on Cursor-managed hosting, and prints the hosted URL plus a
+one-time alias token. Store the token. Production Slack tokens go in as
+deployment secrets:
+
+```bash
+agent-sdk secrets set SLACK_BOT_TOKEN SLACK_APP_TOKEN --slug triage-agent
+agent-sdk deploy
+```
+
+Check on it with `agent-sdk deployments`. The
+[deployment guide](../deployment.md) covers self-hosting, storage, and
+auth when you need them.
+
+## Where to go next
+
+- Add a GitHub intake with the [GitHub guide](../guides/github.md), so
+  issue comments triage themselves.
+- Persist verdicts across restarts with [storage](../storage.md).
+- Measure rubric changes on live traffic with
+  [A/B metrics](../ab.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "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": {
@@ -31,6 +31,7 @@
     "!src/internal/tenant-mcp/**",
     "skills/**/*",
     "!skills/operate/**",
+    "templates/**/*",
     "docs/**/*.md",
     "!docs/.cursor/**",
     "package.json",
@@ -177,6 +178,12 @@
       "import": "./dist/storage-backends/cursor-hosted.js",
       "default": "./dist/storage-backends/cursor-hosted.js"
     },
+    "./otel": {
+      "anysphere-source": "./src/otel.ts",
+      "types": "./dist/otel.d.ts",
+      "import": "./dist/otel.js",
+      "default": "./dist/otel.js"
+    },
     "./package.json": {
       "anysphere-source": "./package.json",
       "bun": "./package.json",
@@ -212,6 +219,21 @@
     "@modelcontextprotocol/sdk": "1.25.1",
     "@octokit/auth-app": "^7.2.0",
     "@octokit/rest": "^21.1.1",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.208.0",
+    "@opentelemetry/core": "^2.6.1",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.208.0",
+    "@opentelemetry/exporter-logs-otlp-proto": "^0.208.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.208.0",
+    "@opentelemetry/exporter-metrics-otlp-proto": "^0.208.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.208.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.208.0",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-logs": "^0.208.0",
+    "@opentelemetry/sdk-metrics": "^2.2.0",
+    "@opentelemetry/sdk-trace-base": "^2.6.1",
+    "@opentelemetry/sdk-trace-node": "^2.6.1",
+    "@opentelemetry/semantic-conventions": "^1.27.0",
     "@slack/socket-mode": "^2.0.7",
     "@slack/web-api": "^7.18.0",
     "croner": "^8.0.1",

package/skills/create-agent/SKILL.md

@@ -16,8 +16,8 @@ channels working
 with the user, prove a turn runs end-to-end, and set up the improvement loop.
 Sibling skills: `framework-map` for orientation, `setup-slack` for Slack
 wiring, `mcp-auth` for host MCP OAuth, `github` for webhook-driven
-agents, `evals` for the eval API, `ab` for live A/B metrics, `hillclimb`
-for iteration once the agent runs.
+agents, `evals` for the eval API, `ab` for live A/B metrics, `otel` for
+OpenTelemetry export, `hillclimb` for iteration once the agent runs.
 
 Read `framework-map/SKILL.md` first if you haven't; treat the package
 `AGENTS.md` and `README.md` as ground truth for

package/skills/debug/SKILL.md

@@ -10,6 +10,10 @@ description: >-
 
 # Debugging the Agent SDK locally
 
+This skill is **local** `agent-sdk serve` / playground. A **hosted**
+deployment that is stopped, slow to start, or failing `/v1/health` is
+`.cursor/skills/debugging/debug-agent-serve-deployment/SKILL.md`.
+
 Read `framework-map/SKILL.md` (sibling skill) first if you don't know the
 project structure or session model. Everything below assumes Node/tsx (`pnpm exec tsx
 src/bin/agent-serve.ts ...` in the everysphere monorepo).

package/skills/framework-map/SKILL.md

@@ -63,6 +63,7 @@ path live under README "Folder structure".
 | `agent/hooks/*.ts` | Observe-only event subscribers (never fatal) |
 | `agent/ab.ts` or `agent/ab/*.ts` | Live A/B metrics (`defineAB`); sticky `split` + `onSample` |
 | `agent/ab.config.ts` | Optional A/B `maxPlaygroundSessions` / `persistSamples` / `persistSnapshots` |
+| `agent/otel.ts` | OpenTelemetry export (`defineOtel`); also `OTEL_EXPORTER_OTLP_*` env |
 | `agent/schedules/*` | Cron-driven runs (UTC, 5-field; never auto-fire under `--dev`) |
 | `agent/sandbox/workspace/` | Files seeded into each session workspace (local runtime only) |
 | `agent/lib/` | Import-only shared code, never discovered |
@@ -151,6 +152,7 @@ folder mounts every sibling agent too.
 - Scaffolding → `packages/agent-serve/skills/create-agent/SKILL.md`
 - Evals → `packages/agent-serve/skills/evals/SKILL.md`
 - Live A/B metrics → `packages/agent-serve/skills/ab/SKILL.md`
+- OpenTelemetry → `packages/agent-serve/skills/otel/SKILL.md`
 - GitHub webhooks → `packages/agent-serve/skills/github/SKILL.md`
 - Slack → `packages/agent-serve/skills/setup-slack/SKILL.md`
 - Host MCP OAuth → `packages/agent-serve/skills/mcp-auth/SKILL.md`

package/skills/otel/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: agentkit-otel
+description: >-
+  Wire OpenTelemetry export for an Agent SDK agent (defineOtel, OTLP env,
+  traces/metrics/logs). Use when adding observability, Datadog/Grafana/OTLP
+  export, or session/turn/tool tracing.
+---
+
+# Agent SDK OpenTelemetry (`defineOtel`)
+
+Push session, turn, tool, and subagent traces, plus token and cost
+metrics, from the serve process to an OTLP collector. Logs are off
+until you opt in.
+
+Read [OpenTelemetry](../../docs/guides/opentelemetry.md) for the full
+guide, including how this joins Cursor enterprise export.
+
+## Enable
+
+Any one of:
+
+1. **Env.** Set `OTEL_EXPORTER_OTLP_ENDPOINT` (and optional
+   `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_HEADERS`,
+   `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf|http/json`).
+   Per-signal URLs work when the base URL is unset:
+   `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `_METRICS_ENDPOINT` /
+   `_LOGS_ENDPOINT`.
+2. **Authored.** `agent/otel.ts`:
+
+```ts
+import { defineOtel } from "@cursor/july/otel";
+
+export default defineOtel({
+  serviceName: "cursor",
+  exporters: [
+    {
+      url: "https://otel.example.com",
+      protocol: "http/protobuf",
+      headers: { Authorization: "Bearer …" },
+    },
+  ],
+});
+```
+
+3. **Programmatic.** `serve(dir, { otel: { … } })`. Pass `otel: false`
+   to disable even when env or `agent/otel.ts` are set.
+
+Multiple `exporters` fan out. Default protocol is `http/protobuf`.
+Use `http/json` only when the collector requires it. `grpc` is ignored.
+
+Precedence: `serve({ otel })` over `agent/otel.ts` over env.
+
+## Signals
+
+| Signal | Default | What |
+| --- | --- | --- |
+| Traces | on | `agent_sdk.http` → `agent_sdk.session` → `agent_sdk.turn` → `agent_sdk.tool` / `agent_sdk.subagent` |
+| Metrics | on | `cursor.token.usage`, `cursor.tool.calls`, `cursor.cost.usage`, plus `agent_sdk.*` counts and HTTP duration |
+| Logs | off | Opt in with `logs: true`, `OTEL_LOGS_EXPORTER=otlp`, or `OTEL_LOG_USER_PROMPTS=1` / `OTEL_LOG_TOOL_CONTENT=1` |
+
+Prompt text, tool payloads, and failure text stay off the wire unless
+those flags are set.
+
+## Attributes worth joining on
+
+- `cursor.conversation.id` (session id)
+- `cursor.tool.name` / `cursor.tool.kind` / `cursor.tool.status`
+- `cursor.token.type`, `cursor.model.name`
+- `agent_sdk.agent`, `agent_sdk.turn_id`, `agent_sdk.call_id`, `agent_sdk.channel`
+
+Resource defaults: `service.name=cursor`, `cursor.entrypoint=sdk_ts`,
+`cursor.surface=unspecified`.
+
+Inbound HTTP extracts W3C `traceparent`, so a channel request parents
+the session span when the turn starts in that request.
+
+If another TracerProvider already owns the process (CLI / IDE), Agent
+SDK reuses it. Run `serve` as its own process when Agent SDK should
+own the destination. Conflicting `agent/otel.ts` files across mounts
+fail at serve start.

package/src/bin/agent-serve.ts

@@ -100,7 +100,7 @@ Usage:
   ${CLI} trajectory  --events <file.ndjson> [--text]
   ${CLI} call        <tool> [--input <json>] [--dir <path> | --url <baseUrl> | --prod]
                           [--session <id>] [--slug <slug>] [--team <id>]
-  ${CLI} init        [dir] [--json]
+  ${CLI} init        [dir] [--template <name>] [--json]
   ${CLI} convert-automation <url> [--dir <path>] [--json]
   ${CLI} install-skills [--print] [--json]
   ${CLI} mcp         --prod [--slug <slug>] [--team <id>] [--dir <path>]
@@ -467,6 +467,7 @@ async function main(argv: string[]): Promise<number> {
     allowPositionals: true,
     options: {
       dir: { type: "string", default: "." },
+      template: { type: "string" },
       port: { type: "string" },
       host: { type: "string" },
       mode: { type: "string" },
@@ -624,6 +625,7 @@ async function main(argv: string[]): Promise<number> {
       return cmdInit({
         dir,
         initTarget: positionals[0],
+        template: values.template,
         json: values.json,
       });
     }

package/src/channels/github/api.ts

@@ -258,6 +258,28 @@ export async function createGitHubIssueComment(
   }
 }
 
+/** Update an issue or PR timeline comment by id. */
+export async function updateGitHubIssueComment(
+  input: GitHubResourceInput & { body: string; commentId: number }
+): Promise<GitHubPostedComment> {
+  const octokit = await createGitHubOctokit(input);
+  try {
+    const response = await octokit.rest.issues.updateComment({
+      owner: input.owner,
+      repo: input.repo,
+      comment_id: input.commentId,
+      body: input.body,
+    });
+    return toPostedComment(response.data);
+  } catch (error) {
+    throw wrapOctokitError(
+      error,
+      "PATCH",
+      `/repos/${input.owner}/${input.repo}/issues/comments/${input.commentId}`
+    );
+  }
+}
+
 /** Reply to an inline pull-request review comment thread. */
 export async function createGitHubReviewCommentReply(
   input: GitHubResourceInput & {

package/src/channels/github/defaults.ts

@@ -5,14 +5,11 @@
 import type { ChannelEventHandlers } from "../../types.js";
 import type { GitHubBindingConfig } from "./binding.js";
 import { buildGitHubBinding, formatGitHubOutboundComment } from "./binding.js";
+import { applyGitHubProgress, type GitHubProgressConfig } from "./progress.js";
 import type { GitHubChannelState } from "./state.js";
 
-export interface GitHubProgressConfig {
-  /** When false, skip the eyes reaction on turn.started. Defaults to true. */
-  reactions?: boolean;
-}
-
 export interface BuildDefaultGitHubEventsOptions extends GitHubBindingConfig {
+  botName?: string;
   progress?: GitHubProgressConfig;
   /**
    * When false, skip posting completed assistant messages back to GitHub.
@@ -22,7 +19,8 @@ export interface BuildDefaultGitHubEventsOptions extends GitHubBindingConfig {
 }
 
 /**
- * Built-in delivery: eyes reaction on turn start, post assistant text on
+ * Built-in delivery: eyes reaction on turn start, optional commit status /
+ * sticky banner via {@link GitHubProgressConfig}, post assistant text on
  * `message.completed`, and a short error comment on turn/session failure.
  */
 export function buildDefaultGitHubEvents(
@@ -32,6 +30,11 @@ export function buildDefaultGitHubEvents(
 
   return {
     async "turn.started"(_event, channel) {
+      await applyGitHubProgress({
+        phase: "pending",
+        channel,
+        options,
+      });
       if (options.progress?.reactions === false) {
         return;
       }
@@ -49,6 +52,14 @@ export function buildDefaultGitHubEvents(
       }
     },
 
+    async "turn.completed"(_event, channel) {
+      await applyGitHubProgress({
+        phase: "success",
+        channel,
+        options,
+      });
+    },
+
     async "message.completed"(event, channel) {
       if (!deliverReplies) {
         return;
@@ -71,10 +82,20 @@ export function buildDefaultGitHubEvents(
     },
 
     async "turn.failed"(event, channel) {
+      await applyGitHubProgress({
+        phase: "failure",
+        channel,
+        options,
+      });
       await postFailure(channel, options, event.data.message);
     },
 
     async "session.failed"(event, channel) {
+      await applyGitHubProgress({
+        phase: "failure",
+        channel,
+        options,
+      });
       await postFailure(channel, options, event.data.message);
     },
   };

package/src/channels/github/github-channel.ts

@@ -958,6 +958,9 @@ async function handleReviewComment(input: {
       binding,
       deliveryId: ctx.deliveryId,
       eventName: ctx.eventName,
+      headSha: parsed.headSha,
+      headRef: parsed.headRef,
+      baseRef: parsed.baseRef,
     }),
   });
 }
@@ -1459,6 +1462,8 @@ async function startTurn(input: {
     title: input.dispatch.title ?? defaultGitHubTitle(input.ctx),
     ...(input.cloud === undefined ? {} : { cloud: input.cloud }),
     state: input.state as unknown as JsonValue,
+    // Resume must refresh headSha / refs without wiping sticky banner id.
+    refreshState: input.state as unknown as JsonValue,
   });
   return Response.json({
     ok: true,
@@ -1612,6 +1617,9 @@ function parseReviewCommentEvent(args: {
   action: string;
   ctx: GitHubParsedContext;
   comment: GitHubComment;
+  headSha?: string;
+  headRef?: string;
+  baseRef?: string;
 } | null {
   const schema = z.object({
     action: z.string().min(1),
@@ -1619,6 +1627,17 @@ function parseReviewCommentEvent(args: {
     pull_request: z.object({
       number: z.number().int().positive(),
       html_url: z.string().url(),
+      head: z
+        .object({
+          sha: z.string().min(1).optional(),
+          ref: z.string().min(1).optional(),
+        })
+        .optional(),
+      base: z
+        .object({
+          ref: z.string().min(1).optional(),
+        })
+        .optional(),
     }),
     comment: z.object({
       id: z.number(),
@@ -1679,7 +1698,14 @@ function parseReviewCommentEvent(args: {
       ? {}
       : { inReplyToId: payload.comment.in_reply_to_id }),
   };
-  return { action: payload.action, ctx, comment };
+  return {
+    action: payload.action,
+    ctx,
+    comment,
+    headSha: payload.pull_request.head?.sha,
+    headRef: payload.pull_request.head?.ref,
+    baseRef: payload.pull_request.base?.ref,
+  };
 }
 
 function parseIssueEvent(args: {

package/src/channels/github/index.ts

@@ -47,6 +47,7 @@ export * from "./defaults.js";
 export * from "./events.js";
 export * from "./forward.js";
 export * from "./github-channel.js";
+export * from "./progress.js";
 export * from "./replay.js";
 export * from "./state.js";
 export * from "./types.js";