@cursor/july 0.1.42 → 0.1.45

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.42",
+  "version": "0.1.45",
   "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",
@@ -208,10 +215,25 @@
     "node": ">=22.13"
   },
   "dependencies": {
-    "@cursor/sdk": "1.0.26",
+    "@cursor/sdk": "1.0.27",
     "@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/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,98 @@
+---
+name: agentkit-otel
+description: >-
+  Wire OpenTelemetry export for an Agent SDK agent (defineOtel, OTLP env,
+  traces/metrics/logs, ctx.host.otel). Use when adding observability,
+  Datadog/Grafana/OTLP export, session/turn/tool tracing, or custom metrics.
+---
+
+# 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.
+
+## Custom metrics (`ctx.host.otel`)
+
+Always present. `increment` / `record` no-op without a meter.
+`setAttributes` still tags the open session when a collector is
+attached. Prefix names with team or agent. No custom spans. Reserved
+metric names: `cursor.token.usage`, `cursor.tool.calls`,
+`cursor.cost.usage`, `agent_sdk.session.count`,
+`agent_sdk.turn.count`, `agent_sdk.subagent.count`,
+`agent_sdk.http.duration`. Reserved attributes:
+`cursor.conversation.id`, `agent_sdk.agent`, `agent_sdk.turn_id`,
+`agent_sdk.framework`.
+
+```ts
+ctx.host.otel.setAttributes({ "abc.ticket_id": "INC-123" });
+ctx.host.otel.increment("abc.ticket.resolved");
+ctx.host.otel.record("abc.approval.duration_ms", 1420);
+```
+
+## 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

@@ -137,6 +137,12 @@ const githubPullRequestPayloadSchema: z.ZodType<GitHubPullRequestPayload> =
     }),
     sender: senderSchema,
     installation: installationSchema,
+    label: z
+      .object({
+        name: z.string().min(1),
+      })
+      .nullable()
+      .optional(),
   });
 
 /**
@@ -336,6 +342,9 @@ export function parseGitHubPullRequestEvent(args: {
     ...(payload.pull_request.user?.login === undefined
       ? {}
       : { authorLogin: payload.pull_request.user.login }),
+    ...(payload.label?.name === undefined
+      ? {}
+      : { label: { name: payload.label.name } }),
   };
   return { ctx, pullRequest };
 }
@@ -958,6 +967,9 @@ async function handleReviewComment(input: {
       binding,
       deliveryId: ctx.deliveryId,
       eventName: ctx.eventName,
+      headSha: parsed.headSha,
+      headRef: parsed.headRef,
+      baseRef: parsed.baseRef,
     }),
   });
 }
@@ -1459,6 +1471,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 +1626,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 +1636,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 +1707,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";