@cursor/july 0.1.111 → 0.1.112

package/docs/guides/webhooks.md

@@ -1,469 +1,238 @@
 ---
 title: "Webhooks & custom channels"
-description: "Give the agent its own HTTP surface: validated routes, sessions keyed to your domain, and replies delivered back out."
+description: "Receive provider events, keep one conversation per domain object, and deliver agent replies back out."
 ---
 
-# Webhooks and custom channels
+# Webhook agents
 
-A custom channel gives the agent its own HTTP surface. You get routes
-with validated payloads, sessions keyed to something in your domain (a
-thread, a ticket, a PR), and replies delivered back to the caller. The
-[Slack](./slack.md) and [GitHub](./github.md) packs build on this
-mechanism. The [GitLab](./gitlab.md) and [Bitbucket](./bitbucket.md) packs
-use it too. This page is the mechanism itself.
+A custom channel turns an event from another system into an agent
+conversation, then sends the result back to the system that started it.
+Use one when the built-in [HTTP API](../reference/http-api.md) does not
+match the provider's payload, conversation key, or reply path.
 
-## What you already have
+Author `agent/channels/<id>.ts`. Its routes mount under
+`/<slug>/v1/channels/<id>`.
 
-The built-in HTTP channel is always mounted (under `/<slug>` in the
-default multi-agent layout). `POST /v1/session` starts a conversation,
-`POST /v1/session/:id` follows up, and `GET /v1/session/:id/stream`
-streams NDJSON events, plus sessions, approvals, and tool routes. See
-the [HTTP API reference](../reference/http-api.md).
+## Receive a webhook and send the answer back
 
-Write a custom channel when that shape doesn't fit: a webhook with its
-own payload contract, a surface that keys sessions by a domain id, or a
-flow that does host-side work before (or instead of) a model turn.
-
-## Define a channel
-
-Author `agent/channels/<id>.ts` with `defineChannel`. The filename is
-the channel id, and routes mount under `/v1/channels/<id>`:
+When a ticket system sends a new message, this endpoint responds with
+`202 Accepted` right away. The agent keeps working after the HTTP
+request ends, and its completed answer appears as a comment on the
+ticket.
 
 ```ts
+// agent/channels/tickets.ts
 import { defineChannel, POST } from "@cursor/july/channels";
 import { z } from "zod";
+import { postTicketComment } from "../lib/tickets.js";
 
-export default defineChannel({
+type TicketState = {
+  ticketId: string;
+};
+
+export default defineChannel<TicketState>({
+  state: { ticketId: "" },
   routes: [
-    POST("/message", {
-      description: "Enqueue a chat turn on this channel",
+    POST("/ticket", {
+      description: "Answer a new ticket message",
       bodySchema: z.object({
+        ticketId: z.string(),
         message: z.string(),
-        thread: z.string().optional(),
       }),
-      handler: async (_req, { send, body }) => {
-        const session = await send(body.message, {
-          // stable key: same thread → same durable session
-          continuationToken: body.thread,
-        });
-        return Response.json({ sessionId: session.id });
+      handler: async (_request, { send, waitUntil, body }) => {
+        waitUntil(
+          send(body.message, {
+            state: { ticketId: body.ticketId },
+            title: `Ticket ${body.ticketId}`,
+          })
+        );
+        return Response.json({ accepted: true }, { status: 202 });
       },
     }),
   ],
   events: {
-    "message.completed"(event, channel, ctx) {
-      // deliver the reply back to the surface that owns this channel:
-      // post to a webhook, reply in a thread, update a ticket, …
+    async "message.completed"(event, channel) {
+      if (event.data.finishReason === "tool_call" || event.data.text === "") {
+        return;
+      }
+      await postTicketComment(channel.state.ticketId, event.data.text);
     },
   },
 });
 ```
 
-```bash
-curl -X POST http://127.0.0.1:3000/<slug>/v1/channels/<id>/message \
-  -H 'content-type: application/json' \
-  -d '{"message":"hello","thread":"ticket-42"}'
-```
-
-## Schemas are Zod, and required
+`postTicketComment` is a small wrapper around the ticket provider's
+SDK. Keeping that write in the event handler means the webhook request
+does not stay open while the model works.
 
-`GET` routes require a Zod `querySchema`. `POST`, `PUT`, and `PATCH`
-require a Zod `bodySchema`. Compile-time checks enforce this, so plain
-JSON Schema objects won't type-check. Use `z.object({})` or
-`z.unknown()` when a surface is intentionally open. The host validates
-before your handler runs, handlers receive typed `args.body` and
-`args.query`, and empty POST bodies are coerced to `{}` first.
+## Keep one conversation per ticket
 
-Declared schemas also feed `GET /v1/info`, which adds two things to the
-playground: a **Try** button on every route, and matching **slash
-commands** in the composer (a channel `drive` route becomes `/drive …`).
+Without a conversation key, every delivery creates a new session. Add
+the ticket ID as the `continuationToken` so the opening message and all
+later comments resume the same conversation, while a different ticket
+starts its own.
 
-## What a handler receives
-
-Handlers get the Fetch `Request` plus an args object:
-
-| Helper | What it does |
-| --- | --- |
-| `send(message, options?)` | Run a model turn on this channel. `continuationToken` keys the durable session; options can seed `workspaceFiles`, attach `cloud` repos, or override `auth`. |
-| `getSession(sessionId)` | Look up an existing session |
-| `receive(channel, input)` | Hand off to another channel (schedules use this) |
-| `callTool(name, input, opts?)` | Run an authored server tool with no model turn ([Tools](../reference/tools.md#call-a-tool-without-a-model-turn)) |
-| `body`, `query`, `params` | Validated payloads and path params |
-| `auth` | The `AuthContext` the route's auth chain resolved |
-| `requestIp` | The TCP peer address |
-| `host` | Shared host services: `host.mcp`, `host.github`, `host.slack`, `host.reminders` |
-| `waitUntil(promise)` | Background work that outlives the response |
+```ts
+waitUntil(
+  send(body.message, {
+    continuationToken: `ticket:${body.ticketId}`,
+    state: { ticketId: body.ticketId },
+    title: `Ticket ${body.ticketId}`,
+  })
+);
+```
 
-Channel `state` declares the starting per-session adapter state. It
-persists across events, and event handlers receive it on
-`channel.state`.
+The channel owns this key. Callers only need to send the domain ID they
+already know.
 
-## Respond fast, work in the background
+## Prepare evidence before the turn
 
-Webhook senders time out quickly. GitHub gives you about ten seconds.
-For slow work, ACK immediately and continue in the background:
+Webhook payloads often contain little more than an object ID. This
+handler fetches the full ticket through a deterministic tool and writes
+the result to `ticket.json`, so the model begins with a stable snapshot
+instead of spending the turn looking for context.
 
 ```ts
-handler: async (_req, { send, waitUntil, body }) => {
+handler: async (_request, { callTool, send, waitUntil, body }) => {
+  const prepared = await callTool("prepare_ticket", {
+    ticketId: body.ticketId,
+  });
+  if (prepared.isError) {
+    return Response.json(
+      { error: prepared.errorMessage ?? "Could not prepare ticket" },
+      { status: 502 }
+    );
+  }
+
   waitUntil(
-    send(`Process incoming report: ${body.url}`, {
-      continuationToken: `report:${body.id}`,
+    send("Read ticket.json, then draft the reply.", {
+      continuationToken: `ticket:${body.ticketId}`,
+      state: { ticketId: body.ticketId },
+      workspaceFiles: {
+        "ticket.json": JSON.stringify(prepared.result, null, 2) ?? "null",
+      },
     })
   );
   return Response.json({ accepted: true }, { status: 202 });
 },
 ```
 
-## Prepare on the host, then hand off
+The same `message.completed` handler from the first example delivers
+the answer back to the ticket.
 
-The strongest channel pattern: do the deterministic setup in the
-handler, then hand the model prepared evidence. Fetch the PR with
-`callTool`, seed the files it needs, and make the prompt about judgment
-rather than about finding things:
+## Routes receive, events deliver
 
-```ts
-handler: async (_req, { callTool, send, body }) => {
-  const prep = await callTool("prepare_pr", { pr: body.pr });
-  if (prep.isError) {
-    return Response.json({ ok: false, error: prep.result }, { status: 502 });
-  }
-  const session = await send("Review the prepared PR under pr/.", {
-    continuationToken: `pr:${body.pr}`,
-  });
-  return Response.json({ sessionId: session.id });
-},
-```
-
-This host-prep shape is the change with the largest effect on latency
-and quality. [Hillclimbing](../hillclimbing.md) lists it first.
-
-## Deliver replies back out
-
-The `events` map subscribes the channel to stream events for the
-sessions it owns. Typical wiring: `message.completed` posts the
-assistant text back to the caller's surface, and `turn.failed` posts an
-error notice. The full vocabulary is in
-[Sessions and streaming](../reference/sessions.md#which-events-can-i-stream).
-
-## Auth: loopback by default, on purpose
+Routes own inbound HTTP. A route validates the request, decides whether
+to start or resume a turn, and responds to the caller. The channel's
+`events` handlers receive session events later, which is where you
+deliver the model's answer or report a failure to the originating
+system.
 
-Every route runs an auth-policy chain (the channel's `auth` array). The
-default is `[localDevStrict()]`: direct loopback callers only. Requests
-carrying proxy-forwarding headers (`X-Forwarded-For`, `X-Real-IP`,
-`Forwarded`, `X-Forwarded-Host`) are rejected, and a loopback `Host`
-header is required. So a tunnel, a same-host reverse proxy, or a
-DNS-rebinding page can't silently re-expose the route.
-
-Before real traffic, author auth explicitly:
-
-```ts
-import { bearerAuth, defineChannel, localDevStrict } from "@cursor/july/channels";
-
-export default defineChannel({
-  auth: [localDevStrict(), bearerAuth(process.env.WEBHOOK_TOKEN ?? "")],
-  routes: [/* … */],
-});
-```
+## Validate payloads with Zod
 
-The built-in policies are `localDevStrict()` (the default),
-`localDev()`, `loopbackOnly()`, `bearerAuth(tokenOrVerify)`, and
-`allowAll()`, and `publicEndpoint()`. Any
-`(request, info) => AuthContext | null` function composes with them.
+`POST`, `PUT`, and `PATCH` routes require a Zod `bodySchema`; `GET`
+requires a `querySchema`. Validation runs before the handler, and the
+parsed value arrives as typed `body` or `query`. Use `z.unknown()` when
+the provider controls a variable payload and your own parser will
+narrow it.
 
-The details live in
-[Channels](../reference/channels.md#auth-policies).
+The route description and schema also appear in `GET /v1/info`. The
+playground uses them to add a **Try** action and a matching slash
+command, so you can exercise the same handler without building a
+separate test UI.
 
-Server-level flags interact with channel auth. `--bearer-token <secret>`
-swaps the default for `bearerAuth` on every channel that doesn't author
-its own chain, and `--allow-anonymous` swaps it for `allowAll()`
-(trusted networks only). Authored `auth` arrays always win over both.
+## Use handler context
 
-## Receive signed webhooks on managed hosting
+The handler context keeps deterministic setup and model work in one
+route:
 
-Cursor-managed deployments expose a stable alias URL. External callers
-normally send `X-Agent-Alias-Token` on every request. Webhook providers
-often cannot set it.
+- `send` starts or resumes the agent conversation.
 
-Add `publicEndpoint()` to a custom channel that verifies its own provider
-signature. Only that channel path skips the alias token. Session and tool
-routes stay private. See [Deployment](../deployment.md#use-the-hosted-agent).
+- `callTool` runs an authored server tool without starting a model
+  turn.
 
-## Example: Linear as the control plane
+- `waitUntil` keeps background work alive after the HTTP response. Await
+  `send` when the caller needs the session handle, then call
+  `session.waitForCompletion()` if it also needs the turn outcome.
 
-Everything above composes into a working ticket-driven agent. This
-example wires Linear to the agent: new issues and comments start or
-resume sessions, and replies land back on the issue as comments. The
-same shape works for any tracker with signed webhooks.
+- `host` provides authenticated services for API calls made by channel
+  code.
 
-Create the webhook in Linear under Settings → API → "New webhook",
-pointed at `https://<your-host>/<slug>/v1/channels/linear`, and copy
-the signing secret. Linear requires a public HTTPS URL, so use a
-tunnel during local development or test with signed fixtures (below).
-Set three environment variables:
+The full handler API lives in the
+[Channels reference](../reference/channels.md#handler-arguments).
 
-```bash
-LINEAR_WEBHOOK_SECRET=lin_wh_...   # the webhook's signing secret
-LINEAR_API_KEY=lin_api_...         # posts replies as comments
-LINEAR_AGENT_USER_ID=...           # the API key's user: query { viewer { id } }
-```
+## Protect public webhooks
 
-`LINEAR_AGENT_USER_ID` matters: replies posted with the API key
-trigger the Comment webhook again, so the channel must recognize and
-skip its own comments. Without the guard, every reply starts another
-turn.
+Custom routes accept direct loopback requests by default. They reject
+forwarded requests, so a tunnel or reverse proxy does not silently turn
+a local development endpoint into a public one.
 
-Author `agent/channels/linear.ts`:
+Before accepting remote traffic, choose an explicit boundary.
+`bearerAuth()` works when the sender can attach an authorization header.
+On managed hosting, webhook providers often cannot attach the agent
+alias token, so `publicEndpoint()` lets that custom channel bypass it.
+That opens the route to every caller; verify the provider signature
+before starting a turn or calling a tool.
 
 ```ts
-import { Buffer } from "node:buffer";
-import { createHmac, timingSafeEqual } from "node:crypto";
 import { defineChannel, POST, publicEndpoint } from "@cursor/july/channels";
 import { z } from "zod";
-
-const secret = process.env.LINEAR_WEBHOOK_SECRET ?? "";
-const apiKey = process.env.LINEAR_API_KEY ?? "";
-const agentUserId = process.env.LINEAR_AGENT_USER_ID ?? "";
-
-interface LinearWebhook {
-  action: string;
-  type: string;
-  url?: string;
-  webhookTimestamp: number;
-  data: {
-    id: string;
-    title?: string;
-    description?: string;
-    body?: string;
-    issueId?: string;
-    userId?: string;
-  };
-}
-
-// Linear signs the raw body: hex HMAC-SHA256 in `Linear-Signature`.
-function verified(rawBody: string, header: string | null): boolean {
-  if (secret === "" || header === null) {
-    return false;
-  }
-  const expected = createHmac("sha256", secret).update(rawBody).digest();
-  const received = Buffer.from(header, "hex");
-  return (
-    received.length === expected.length && timingSafeEqual(received, expected)
-  );
-}
-
-async function postComment(issueId: string, body: string): Promise<void> {
-  const response = await fetch("https://api.linear.app/graphql", {
-    method: "POST",
-    headers: { "content-type": "application/json", authorization: apiKey },
-    body: JSON.stringify({
-      query:
-        "mutation($input: CommentCreateInput!) { commentCreate(input: $input) { success } }",
-      variables: { input: { issueId, body } },
-    }),
-  });
-  if (!response.ok) {
-    throw new Error(`commentCreate failed: ${response.status}`);
-  }
-}
-
-function issueIdFromToken(token: string | null): string | null {
-  if (token === null || !token.startsWith("linear:")) {
-    return null;
-  }
-  return token.slice("linear:".length);
-}
+import { verifyProviderSignature } from "../lib/tickets.js";
 
 export default defineChannel({
   auth: [publicEndpoint()],
   routes: [
     POST("/", {
-      description: "Linear webhook ingress",
-      // The payload shape varies by `Linear-Event`; parse after verifying.
+      description: "Signed ticket webhook",
       bodySchema: z.unknown(),
-      handler: async (request, { send, waitUntil }) => {
+      handler: async request => {
         const rawBody = await request.text();
-        if (!verified(rawBody, request.headers.get("linear-signature"))) {
-          return Response.json({ ok: false }, { status: 401 });
-        }
-        const event = JSON.parse(rawBody) as LinearWebhook;
-        // Reject stale deliveries to guard against replay.
-        if (Math.abs(Date.now() - event.webhookTimestamp) > 60_000) {
+        const signature = request.headers.get("x-provider-signature");
+        if (!verifyProviderSignature(rawBody, signature)) {
           return Response.json({ ok: false }, { status: 401 });
         }
-        // Skip the agent's own comments so replies don't re-trigger it.
-        if (event.type === "Comment" && event.data.userId === agentUserId) {
-          return Response.json({ ok: true });
-        }
-
-        // New issue → new session. New comment → follow-up on the same
-        // session, keyed by issue id through the continuation token.
-        let issueId: string | undefined;
-        let message: string | undefined;
-        if (event.type === "Issue" && event.action === "create") {
-          issueId = event.data.id;
-          message = `New Linear issue: ${event.data.title}\n\n${
-            event.data.description ?? ""
-          }\n${event.url ?? ""}`;
-        } else if (event.type === "Comment" && event.action === "create") {
-          issueId = event.data.issueId;
-          message = event.data.body;
-        }
-        if (issueId === undefined || message === undefined) {
-          return Response.json({ ok: true });
-        }
 
-        // Linear retries on any non-200 and times out after five
-        // seconds: ACK now, run the turn in the background.
-        waitUntil(send(message, { continuationToken: `linear:${issueId}` }));
+        // Parse and dispatch only after the signature passes.
         return Response.json({ ok: true });
       },
     }),
   ],
-  events: {
-    async "message.completed"(event, channel) {
-      if (event.data.finishReason === "tool_call" || event.data.text === "") {
-        return;
-      }
-      const issueId = issueIdFromToken(channel.continuationToken);
-      if (issueId !== null) {
-        await postComment(issueId, event.data.text);
-      }
-    },
-    async "turn.failed"(event, channel) {
-      const issueId = issueIdFromToken(channel.continuationToken);
-      if (issueId !== null) {
-        await postComment(issueId, `Turn failed: ${event.data.message}`);
-      }
-    },
-  },
 });
 ```
 
-The channel handles ingress and reply delivery deterministically. To
-let the model read and update Linear during the turn (search related
-issues, change state, assign), add the Linear MCP connection alongside
-it:
-
-```ts
-// agent/mcp-connections/linear.ts
-import { defineConnection } from "@cursor/july/connections";
-
-// Uses the signed-in Cursor account's Linear connector.
-export default defineConnection({ cursorAccount: true, servers: ["Linear"] });
-```
-
-See [MCP connections](../reference/connections.md) for the direct
-`https://mcp.linear.app/mcp` form when the host isn't signed in to
-Cursor.
-
-### Production Linear agents: expiring OAuth tokens
+`publicEndpoint()` only opens this channel's routes. The built-in
+session and tool APIs stay private. See
+[Auth policies](../reference/channels.md#auth-policies) for bearer
+tokens and the complete policy reference.
 
-A plain API key fits a personal integration. A production Linear agent
-is an OAuth application: installing it in a workspace mints an access
-token with an expiry plus a refresh token. The serve host can be
-replaced at any time, so the pair can't live in process memory.
-Persist it in `host.kv` instead.
-Route handlers receive `host` in their args, and event handlers get the
-same services on `ctx`.
+## Test locally
 
-Two prerequisites:
-
-- Keep the OAuth client id and client secret in
-  [deployment secrets](../deployment.md). They're static, so
-  deploy-time env vars fit them.
-- Back kv with durable storage. On Cursor-managed hosting, use
-  `cursorHostedStorage` in `agent/storage.ts`. Without it, kv falls back
-  to local disk and a host replacement drops the tokens.
-
-Save the pair when the install flow completes, then refresh on demand:
-
-```ts
-import type { HostKvApi } from "@cursor/july/kv";
-
-interface LinearTokens {
-  accessToken: string;
-  refreshToken: string;
-  expiresAtMs: number;
-}
-
-const TOKENS_KEY = "linear/oauth-tokens";
-
-export async function linearAccessToken(kv: HostKvApi): Promise<string> {
-  const tokens = (await kv.get(TOKENS_KEY)) as LinearTokens | undefined;
-  if (tokens === undefined) {
-    throw new Error("No Linear tokens stored. Complete the install flow first.");
-  }
-  if (Date.now() < tokens.expiresAtMs - 60_000) {
-    return tokens.accessToken;
-  }
-  const response = await fetch("https://api.linear.app/oauth/token", {
-    method: "POST",
-    headers: { "content-type": "application/x-www-form-urlencoded" },
-    body: new URLSearchParams({
-      grant_type: "refresh_token",
-      refresh_token: tokens.refreshToken,
-      client_id: process.env.LINEAR_CLIENT_ID ?? "",
-      client_secret: process.env.LINEAR_CLIENT_SECRET ?? "",
-    }),
-  });
-  if (!response.ok) {
-    throw new Error(`Linear token refresh failed: ${response.status}`);
-  }
-  const next = (await response.json()) as {
-    access_token: string;
-    refresh_token?: string;
-    expires_in: number;
-  };
-  const rotated: LinearTokens = {
-    accessToken: next.access_token,
-    refreshToken: next.refresh_token ?? tokens.refreshToken,
-    expiresAtMs: Date.now() + next.expires_in * 1000,
-  };
-  await kv.put(TOKENS_KEY, rotated);
-  return rotated.accessToken;
-}
-```
-
-Then authorize GraphQL calls with `Bearer ${await
-linearAccessToken(host.kv)}` in place of the static `apiKey` above.
-Writes to `host.kv` await the durable sink and propagate errors, so a
-failed save surfaces instead of silently losing the rotated refresh
-token.
-
-To test without a public URL, save a payload from the webhook's
-delivery log (or the sample in
-[Linear's webhook docs](https://linear.app/developers/webhooks)) under
-`fixtures/`, refresh its `webhookTimestamp`, and sign it yourself:
+Run the agent in development mode, then replay the same payload the
+provider will send. The response should return immediately, and the
+resulting session should appear in the playground while the reply is
+delivered.
 
 ```bash
-SIG=$(node -e 'const {createHmac}=require("node:crypto");const fs=require("node:fs");
-process.stdout.write(createHmac("sha256",process.env.LINEAR_WEBHOOK_SECRET)
-  .update(fs.readFileSync("fixtures/issue-create.json")).digest("hex"))')
-curl -X POST http://127.0.0.1:3000/<slug>/v1/channels/linear/ \
-  -H 'content-type: application/json' -H "linear-signature: $SIG" \
-  --data-binary @fixtures/issue-create.json
-```
-
-## Test a channel
+agent-sdk serve --dir . --dev
 
-Start with curl and saved payloads under `fixtures/`. The playground's
-**Try** modal covers manual probes. It remembers your last body per
-endpoint, has Copy curl, and opens the created session on a successful
-Try. For regression coverage, drive the same behavior through an eval,
-or keep channel logic deterministic in `agent/lib/` and unit-test it
-there. When something looks wrong, inspect the session event stream.
-The stream is the record of what happened.
-
-For GitHub specifically, don't hand-roll fixtures.
-`agent-sdk github replay` synthesizes real-shaped, signed payloads
-from any PR you can read. See the [GitHub guide](./github.md).
-
-## What's next
-
-Continue with these pages:
+curl -sS -X POST \
+  http://127.0.0.1:3000/<slug>/v1/channels/tickets/ticket \
+  -H 'content-type: application/json' \
+  -d '{"ticketId":"ENG-142","message":"CSV export returns 500"}'
+```
 
-- [Channels reference](../reference/channels.md): the full authoring API
-- [GitHub](./github.md), [GitLab](./gitlab.md),
-  [Bitbucket](./bitbucket.md), and [Slack](./slack.md): the packaged channels
-- [Sessions and streaming](../reference/sessions.md): events your
-  channel can subscribe to
+Keep representative payloads under `fixtures/` and pass them with
+`--data-binary @fixtures/<event>.json`. You can also open the route's
+**Try** action in the playground for manual probes.
+
+## Related
+
+- [Channels reference](../reference/channels.md): route methods,
+  handler arguments, events, state, and auth policies
+- [Triage Linear or Jira issues](../templates/triage.md): a complete
+  signed tracker webhook with reply delivery
+- [HTTP API](../reference/http-api.md): built-in session, follow-up,
+  stream, and tool routes
+- [Deployment](../deployment.md#use-the-hosted-agent): stable hosted
+  URLs and alias-token behavior
+- [Evals](../evals.md): turn saved payloads into regression fixtures