@cursor/july 0.1.90 → 0.1.92

package/dist/docs/reference/channels.md

@@ -0,0 +1,255 @@
+# Channels
+
+A channel is the surface an agent lives on. The built-in HTTP session
+channel is always mounted. Custom channels declare their own routes
+under `/v1/channels/<id>`. The Slack and GitHub packs are prebuilt
+channels with platform transports. This page is the authoring reference;
+for the walkthrough, see the [Webhooks guide](/docs/guides/webhooks.md).
+
+## The built-in HTTP channel
+
+It's always mounted, under `/<slug>` in the default multi-agent layout:
+session create, follow-up, stream, stop, the sessions list, approvals,
+deterministic tool calls, health, and info. For the route-by-route
+contract, see the [HTTP API reference](/docs/reference/http-api.md).
+
+Author `agent/channels/http.ts` only to override its defaults:
+
+```ts
+import {
+  bearerAuth,
+  httpChannel,
+  localDevStrict,
+} from "@cursor/july/channels";
+
+export default httpChannel({
+  auth: [localDevStrict(), bearerAuth(process.env.AGENT_TOKEN ?? "")],
+  onMessage: (message, { auth }) =>
+    `[caller ${auth?.principalId ?? "anonymous"}] ${message}`,
+});
+```
+
+## Define a custom channel
+
+Author `agent/channels/<id>.ts`. The filename is the channel id and the
+route prefix:
+
+```ts
+import { defineChannel, POST } from "@cursor/july/channels";
+import { z } from "zod";
+
+export default defineChannel({
+  routes: [
+    POST("/review", {
+      description: "Review a pull request on this channel",
+      bodySchema: z.object({
+        message: z.string(),
+        prUrl: z.string().url(),
+        thread: z.string().optional(),
+      }),
+      handler: async (_req, { callTool, send, body }) => {
+        const prepared = await callTool("inspect_pr", {
+          prUrl: body.prUrl,
+        });
+        if (prepared.isError) {
+          return Response.json(
+            { error: prepared.errorMessage ?? "Could not inspect pull request" },
+            { status: 502 }
+          );
+        }
+
+        const session = await send(
+          `${body.message}\n\nRead pr.json before answering.`,
+          {
+            continuationToken: body.thread ?? `pr:${body.prUrl}`,
+            workspaceFiles: {
+              "pr.json": JSON.stringify(prepared.result, null, 2) ?? "null",
+            },
+          }
+        );
+        return Response.json({ sessionId: session.id });
+      },
+    }),
+  ],
+  events: {
+    "message.completed"(event, channel, ctx) {
+      // deliver the reply to the surface that owns this channel
+    },
+  },
+  // auth: [...], state: {...}, onStart(...), onStop(...)
+});
+```
+
+This example assumes `agent/tools/inspect_pr.ts` exists. The handler
+calls it before the model turn, so every review starts with validated PR
+data. It also derives a stable conversation key from the PR URL and
+writes the tool result to `pr.json`. Instructions can ask the model to
+inspect a PR, but host code guarantees it.
+
+## Route verbs and schemas
+
+`GET`, `POST`, `PUT`, `PATCH`, and `DELETE` helpers build routes. Their
+schemas are Zod, enforced at compile time:
+
+| Verb                     | Required schema                       |
+| ------------------------ | ------------------------------------- |
+| `GET`                    | `querySchema`                         |
+| `POST` / `PUT` / `PATCH` | `bodySchema` (optional `querySchema`) |
+| `DELETE`                 | both optional                         |
+
+Plain JSON Schema objects won't type-check; use `z.object({})` or
+`z.unknown()` for intentionally open surfaces. The host validates before
+the handler runs. Handlers receive typed `args.body` and `args.query`,
+and empty POST bodies are coerced to `{}` first. Declared schemas are
+projected on `GET /v1/info`, which powers the playground's **Try**
+buttons and composer **slash commands**.
+
+## Handler arguments
+
+Handlers receive the Fetch `Request` and an args object:
+
+| Member                              | What it is                                                                                                                                                                                                                                                                                  |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `send(message, options?)`           | Run a model turn on this channel; returns the session handle (options below)                                                 |
+| `getSession(sessionId)`             | Look up an existing session on this channel                                                                                  |
+| `receive(channelDefinition, input)` | Hand off to another channel (schedules use this)                                                                             |
+| `callTool(name, input, options?)`   | Deterministic server-tool call ([Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn))                                        |
+| `body`, `query`, `params`           | Validated payloads and `:param` path segments                                                                                |
+| `auth`                              | The `AuthContext` resolved by this route's auth chain                                                                        |
+| `requestIp`                         | The TCP peer address                                                                                                         |
+| `host`                              | Shared services: `host.mcp`, `host.github`, `host.slack`, `host.kv`, `host.files`, `host.reminders`                          |
+| `waitUntil(promise)`                | Background work that outlives the response                                                                                   |
+| `sessionUrls(request, sessionId)`   | Absolute playground + trace URLs for a session on this mount                                                                 |
+| `artifacts`                         | Unbound [artifacts](/docs/reference/artifacts.md) facade; pass `sessionId` in `tag` input to attribute one                                 |
+
+`send` options: `continuationToken` (the conversation key),
+`admission` (`"preempt"` interrupts a busy session, the default;
+`"coalesce"` enqueues behind the running turn, the
+[Slack policy](/docs/reference/sessions.md#what-happens-when-i-send-a-follow-up)),
+`workspaceFiles`, `workspaceDir`, `cloud` (attach cloud repos for this
+session), `auth` (defaults to the request principal), `sdkAgentId`
+(resume a specific SDK agent), `state` (starting channel state for new
+sessions), `title` (session display title), `purpose` (`"eval"` skips
+sticky A/B enrollment), and `coalesceSourceTs` (dedupe key for coalesce
+queue items already delivered mid-turn).
+
+## Events
+
+The `events` map subscribes the channel to stream events for the
+sessions it owns. Keys are event types from the
+[event vocabulary](/docs/reference/sessions.md#which-events-can-i-stream), or `"*"`.
+Handlers receive `(event, channel, ctx)`, where `channel.state` is the
+per-session adapter state and `ctx` exposes session info and host
+services. This is where a channel delivers replies back to its surface.
+
+## State and lifecycle
+
+`state` declares the starting per-session adapter state (JSON), persisted
+on the session record. Routes and event handlers read and mutate it
+through `channel.state`. `onStart(args)` runs when the channel mounts;
+the Slack pack opens its Socket Mode connection here. `onStop()` runs
+when the server drains.
+
+`onStart` receives the route helpers (`send`, `getSession`, `receive`,
+`callTool`, `host`, `waitUntil`, `artifacts`, and a `logger` that
+respects the server's log sink) plus a set that exists for long-lived
+transports:
+
+- `emitAssistantMessage(sessionId, text)` appends an assistant message
+  without a model turn, for host tasks that already produced the final
+  text.
+- `hasContinuationSession(token)` and `isContinuationBusy(token)`
+  report whether a continuation token has a live session and whether a
+  turn is in flight on it.
+- `getContinuationLastBotMessageTs(token)` reads the Slack warm-delta
+  watermark from channel state.
+- `interruptContinuation(token)` stops the in-flight turn and clears
+  coalesced follow-ups queued behind it.
+- `resolveApproval(sessionId, callId, decision, auth, options?)`
+  approves or denies a parked tool call, how Slack Block Kit buttons
+  unblock a turn without the HTTP approvals route.
+
+## Auth policies
+
+Every route runs an auth-policy chain: the channel's `auth` array, or
+`[localDevStrict()]` when unset. A policy is a function
+`(request, info) => AuthContext | null` (async allowed); the first
+non-null wins, and a request no policy admits gets `401`.
+
+| Policy              | Admits                                                                                                                                                                                                                                                                                                                                                     |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `localDevStrict()`  | Direct loopback callers with no proxy-forwarding headers (`X-Forwarded-For`, `X-Real-IP`, `Forwarded`, and `X-Forwarded-Host` are all rejected, so tunnels and same-host reverse proxies don't silently re-expose the route), plus a loopback `Host` header, which rejects DNS-rebinding callers that reach 127.0.0.1 with a remote hostname. |
+| `localDev()`        | Like `localDevStrict()` but without the `Host` check. An explicit, weaker opt-in.                                                                                                                                                                                                                                                                          |
+| `loopbackOnly()`    | A loopback TCP peer, ignoring forwarding headers; for dev relays that legitimately carry them, like `gh webhook forward`.                                                                                                                                                                                                                                  |
+| `bearerAuth(token)` | `Authorization: Bearer <token>`, compared in constant time. Also accepts a verifier function mapping a presented token to an `AuthContext`.                                                                                                                                                                                                                |
+| `allowAll()`        | Everyone, as an `anonymous` principal. Only for surfaces protected upstream (an HMAC-verified webhook) or intentionally public.                                                                                                                                                                                                                            |
+| `publicEndpoint()`  | Everyone on this custom channel. Managed hosting also serves the channel without an alias token. Use it only when the handler verifies the provider signature.                                                                                                                                                                                             |
+
+`publicEndpoint()` applies only to custom channel routes. It does not open
+the built-in session or tool API.
+
+The resolved `AuthContext` (`{ authenticator, principalId,
+principalType, attributes? }`) becomes the request principal. Sessions
+bind to the principal that created them, and follow-up, stream, and list
+routes enforce ownership (`403` otherwise).
+
+Server flags interact with authored auth: `--bearer-token` swaps the
+default `localDevStrict()` for `bearerAuth(...)` on channels that don't
+author their own chain, and `--allow-anonymous` swaps it for
+`allowAll()`. Authored `auth` arrays always win over both. A channel that
+declares `[localDevStrict()]` stays loopback-only even on an
+`--allow-anonymous` host.
+
+## First class channels
+
+**Slack** (`@cursor/july/channels/slack`): Socket Mode
+transport, streaming replies, engagement rules, approval cards, and a
+default block on Slack Connect / guest / other-workspace senders. Author
+`agent/channels/slack.ts` with `slackChannel()`. Guide:
+[Slack](/docs/guides/slack.md).
+
+**GitHub** (`@cursor/july/channels/github`): webhook dispatch
+with signature verification, per-event hooks returning `{ auth }` (a
+model turn), `{ task }` (host work), or `null`, and CLI tooling for
+replay and live forwarding. Author `agent/channels/github.ts` with
+`githubChannel()`. Opt-in `progress.commitStatus` and `progress.banner`
+converge a merge-box check and sticky PR comment from default stream
+events. Guide: [GitHub](/docs/guides/github.md).
+
+**Deployments** (`@cursor/july/channels/deployments`): pull transport
+over `/v0/deployment-events`. Subscribe per deploy source with
+`deploySourceUris`, narrow with `environments` / `events`, and handle
+each event in `onEvent`. `deploySourceUris` must match
+`Deployment.deploy_source_uri` as your deployment writer records it; the
+field has no format, and matching is case-insensitive but otherwise
+literal. Each event carries `deploySourceUri` and `deployVersion`.
+Author `agent/channels/deployments.ts` with `deploymentsChannel()`. The
+serve host discovers every mounted deployments channel, runs one relay
+for the process against the union of their deploy sources, and routes
+each event to the channels that asked for it; the Slack and SCM relays
+use the same ownership. It authenticates with the host credential and
+keeps a durable offset, so a restart resumes rather than dropping
+events. An empty `deploySourceUris` list mounts the channel but starts
+no relay for it, so an env-configured agent stays inert until its
+deploy sources are set.
+
+For other platforms like Discord or Teams, use the authored
+`defineChannel` webhook form.
+
+## Continuation semantics
+
+Channels own their continuation-token format. The built-in HTTP channel
+mints opaque rotating tokens, Slack uses `channelId:threadTs`, and PR
+automations use keys like `pr:owner/repo#N`. Same token, same durable
+session; one active continuation per session; the HTTP channel returns
+`409` for stale tokens. For the full session model, see
+[Sessions](/docs/reference/sessions.md).
+
+## What's next
+
+Continue with these pages:
+
+- [Webhooks guide](/docs/guides/webhooks.md): the same API, walked through
+- [HTTP API](/docs/reference/http-api.md): the built-in routes precisely
+- [Sessions and streaming](/docs/reference/sessions.md): the events channels
+  subscribe to