@cursor/july 0.1.113 → 0.2.0

package/docs/reference/channels.md

@@ -1,28 +1,25 @@
 ---
 title: "Channels"
-description: "The authoring reference for defineChannel, the built-in HTTP channel, route schemas, handler args, and the auth policies."
+description: "Define custom channel routes, schemas, state, events, and authentication."
 ---
 
 # 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. GitLab and Bitbucket packs cover their
-hosted and self-managed products. This page is the authoring reference;
-for the walkthrough, see the [Webhooks guide](../guides/webhooks.md).
+A channel connects an external surface to agent sessions. A file at
+`agent/channels/<id>.ts` defines channel `<id>` and mounts its routes
+under `/v1/channels/<id>`. The built-in HTTP session channel is always
+available alongside any custom or prebuilt channels.
 
 ## 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](./http-api.md).
+The built-in channel serves the session, approval, tool, discovery, and
+health routes. In a multi-agent host, each agent's routes sit under its
+slug. See the [HTTP API](./http-api.md) for request and response
+contracts.
 
 ## Define a custom channel
 
-Author `agent/channels/<id>.ts`. The filename is the channel id and the
-route prefix:
+Use `defineChannel` with one or more typed routes:
 
 ```ts
 import { defineChannel, POST } from "@cursor/july/channels";
@@ -35,234 +32,170 @@ export default defineChannel({
       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 }
-          );
-        }
-
+      handler: async (_request, { send, body }) => {
         const session = await send(
-          `${body.message}\n\nRead pr.json before answering.`,
+          `${body.message}\n\nPull request: ${body.prUrl}`,
           {
-            continuationToken: body.thread ?? `pr:${body.prUrl}`,
-            workspaceFiles: {
-              "pr.json": JSON.stringify(prepared.result, null, 2) ?? "null",
-            },
+            continuationToken: `pr:${body.prUrl}`,
           }
         );
         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.
+The route above is
+`POST /v1/channels/<id>/review`. Calls for the same pull request reuse
+one conversation because they pass the same continuation token.
 
 ## Route verbs and schemas
 
-`GET`, `POST`, `PUT`, `PATCH`, and `DELETE` helpers build routes. Their
-schemas are Zod, enforced at compile time:
+Route paths must begin with `/`. The method helper determines which Zod
+schemas the route accepts:
 
-| Verb                     | Required schema                       |
-| ------------------------ | ------------------------------------- |
-| `GET`                    | `querySchema`                         |
-| `POST` / `PUT` / `PATCH` | `bodySchema` (optional `querySchema`) |
-| `DELETE`                 | both optional                         |
+| Helper | Schema contract |
+| --- | --- |
+| `GET` | `querySchema` is required |
+| `POST`, `PUT`, `PATCH` | `bodySchema` is required; `querySchema` is optional |
+| `DELETE` | Both schemas are 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**.
+Plain JSON Schema objects don't type-check. Use `z.object({})` or
+`z.unknown()` for an open surface. The host validates the body and query
+before calling the handler, returning `400` on failure; an empty body is
+read as `{}`. Declared schemas also appear in `GET /v1/info` for
+playground requests and 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](./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](./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](./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), `state` (starting
-channel state for new sessions), `title` (session display title), and
-`purpose` (`"eval"` marks the session as regression traffic).
+Each handler receives the Fetch `Request` and a typed arguments object.
+
+| Member | Contract |
+| --- | --- |
+| `send(message, options?)` | Start or resume a session on this channel |
+| `getSession(sessionId)` | Return this channel's session, or `null` |
+| `receive(channel, input)` | Hand work to another channel |
+| `callTool(name, input, options?)` | [Call a server tool](./tools.md#call-a-tool-without-a-model-turn) without a model turn |
+| `body`, `query`, `params` | Validated inputs and `:param` path segments |
+| `auth` | The `AuthContext` returned by the route's auth chain |
+| `requestIp` | The TCP peer address, or `null` |
+| `host` | Shared MCP, provider, storage, telemetry, and reminder services |
+| `waitUntil(promise)` | Track work after the response returns |
+| `sessionUrls(request, sessionId)` | Build absolute playground and trace URLs for this mount |
+| `artifacts` | List or tag [artifacts](./artifacts.md); pass `sessionId` when attributing one |
+
+### `send` options
+
+| Option | Contract |
+| --- | --- |
+| `continuationToken` | Resume the session with this channel-local key, or create one when the key is new |
+| `admission` | `"preempt"` interrupts a busy turn; `"coalesce"` queues behind it. The default is `"preempt"` |
+| `workspaceFiles` | Add relative files for the next turn |
+| `workspaceDir` | Use an absolute local working directory |
+| `cloud` | Override cloud session options when creating a session |
+| `auth` | Set the session principal; defaults to the request principal |
+| `state` | Set starting channel state for a new session |
+| `title` | Set the display title for a new session |
+| `purpose` | Use `"eval"` to mark a new session as regression traffic |
+| `dryRun` | Run read tools and stub write tools for a new session |
+| `asOf` | Freeze a new session at an ISO-8601 instant with a timezone |
+
+`send` returns a `ChannelSession`. Its `id` identifies the session,
+`continuationToken` contains its current channel key, and `isNew` says
+whether this call created it. A coalesced call also returns
+`coalesced: true`.
 
 ## Events
 
 The `events` map subscribes the channel to stream events for the
 sessions it owns. Keys are event types from the
-[event vocabulary](./sessions.md#which-events-can-i-stream), or `"*"`.
-Handlers receive `(event, channel, ctx)`, where `channel.state` is the
-per-session adapter state, `ctx.session` is the session info, and
-`ctx.host` is the shared host services, bound to that session as in a
-[hook](./hooks.md#handler-context). 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.
-`onStop()` runs when the server stops.
-
-`onStart` receives the route helpers (`send`, `getSession`, `receive`,
-`callTool`, `host`, `waitUntil`, `artifacts`, `logger`) plus helpers
-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.
-- `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.
+[event vocabulary](./sessions.md#stream-events), or `"*"`. Each handler
+receives `(event, channel, ctx)`, including the session's
+`channel.state`, session info, and shared host services. Use these
+handlers to deliver progress and replies to the surface that owns the
+channel.
 
-## Auth policies
+## Session state
+
+`state` on the channel definition supplies starting JSON for each new
+session. A route can instead pass `state` to `send`; event handlers read
+and update the active value through `channel.state`.
 
-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`.
+## Start and stop a channel
 
-| 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.                                                                                                                                                                                             |
+`onStart(args)` runs when the channel mounts, and `onStop()` runs when
+the host stops. `onStart` receives the route helpers plus these
+transport controls:
 
-`publicEndpoint()` applies only to custom channel routes. It does not open
-the built-in session or tool API.
+| Helper | Contract |
+| --- | --- |
+| `emitAssistantMessage(sessionId, text)` | Append final assistant text without starting a model turn |
+| `hasContinuationSession(token)` | Check whether a token maps to a session |
+| `isContinuationBusy(token)` | Check whether a turn is active for a token |
+| `interruptContinuation(token)` | Stop the active turn and clear queued coalesced follow-ups |
+| `resolveApproval(...)` | Approve or deny a parked tool call |
+
+## Auth policies
+
+Every route runs the channel's `auth` array. The default is
+`[localDevStrict()]`. Policies may be asynchronous; the first one to
+return an `AuthContext` admits the request, and an all-null result
+returns `401`.
+
+| Policy | Admits |
+| --- | --- |
+| `localDevStrict()` | Direct loopback requests with a loopback hostname and no proxy-forwarding headers |
+| `localDev()` | Direct loopback requests with no proxy-forwarding headers, without checking the hostname |
+| `loopbackOnly()` | Any loopback TCP peer, including local relays that carry forwarding headers |
+| `bearerAuth(tokenOrVerify)` | A matching bearer token, or a token accepted by the verifier |
+| `sharedSecretAuth({ header, secret })` | A header matching the named environment or deployment secret |
+| `hmacSignatureAuth({ header, secret, prefix? })` | A hex HMAC-SHA256 signature over the raw body using the named secret |
+| `allowAll()` | Every caller as an anonymous principal |
+| `publicEndpoint()` | Every caller on this custom channel; managed hosting also exposes the route without an alias token |
+
+Use `allowAll()` only for an intentionally public surface or one
+protected upstream. With `publicEndpoint()`, the handler must verify the
+provider's signature. The policy applies only to custom channel routes;
+it doesn't 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).
+belong to the principal that created them, and other principals receive
+`403` on owned routes.
 
 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](../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. Supports GitHub.com and GitHub Enterprise Server. Guide:
-[GitHub](../guides/github.md).
-
-**GitLab** (`@cursor/july/channels/gitlab`): verified project hooks for
-merge requests, notes, pipelines, pushes, and custom event types. Supports
-GitLab.com and self-managed GitLab. Author `agent/channels/gitlab.ts` with
-`gitlabChannel()`. Guide: [GitLab](../guides/gitlab.md).
-
-**Bitbucket** (`@cursor/july/channels/bitbucket`): verified repository hooks
-for pull requests, comments, pushes, and custom event types. Supports
-Bitbucket Cloud and Bitbucket Data Center through one normalized hook API.
-Author `agent/channels/bitbucket.ts` with `bitbucketChannel()`. Guide:
-[Bitbucket](../guides/bitbucket.md).
-
-**Deployments** (`@cursor/july/channels/deployments`): pull deploy
-events. Declare `events` and handle each one in `onEvent`. Each event
-carries `deploySourceUri` and `deployVersion`. Author
-`agent/channels/deployments.ts` with `deploymentsChannel()`.
-
-On Cursor-managed hosting, omit `deploySourceUris`. The deployment's
-watched repositories bind the event scope automatically. Name sources
-to narrow the scope or to drive the self-hosted pull relay. Subscribe
-per deploy source with `deploySourceUris` and narrow with `environments`
-or `events`. Each entry must match `Deployment.deploy_source_uri` as
-your deployment writer records it. Matching is case-insensitive but
-otherwise literal. It uses the host credential. A restart resumes
-rather than dropping events. An empty `deploySourceUris` list mounts the
-channel but starts no pull, so an env-configured agent stays inert until
-its deploy sources are set.
-
-**Change Monitors** (`@cursor/july/channels/change-monitors`): Change
-Monitor Checkpoint events. The channel publishes Factory
-`checkpoint.created` for every Checkpoint create. The agent filters the
-result (for example to the `issues` arm). The payload contains the
-full Checkpoint resource. This channel is scoped to Change Monitors,
-not generic Factory Checkpoints. There is no repository filter or
-resource filter. Author `agent/channels/change-monitors.ts` with
-`changeMonitorsChannel()`. It uses the host credential.
-
-**Issues** (`@cursor/july/channels/issues`): Factory issue events.
-The channel publishes `issue.created` for every Issue create. The
-agent filters if it needs a subset. The payload contains the full
-Issue resource. There is no repository filter or resource filter.
-Author `agent/channels/issues.ts` with `issuesChannel()`. It uses the
-host credential.
+`allowAll()`. An authored `auth` array always takes precedence.
 
-For other platforms like Discord or Teams, use the authored
-`defineChannel` webhook form.
+## Prebuilt channels
 
-## Continuation semantics
+| Import | Factory | Surface |
+| --- | --- | --- |
+| `@cursor/july/channels/slack` | `slackChannel()` | Slack messages, threads, streaming replies, and approvals. See [Slack](../guides/slack.md) |
+| `@cursor/july/channels/github` | `githubChannel()` | GitHub and GitHub Enterprise webhooks. See [GitHub](../guides/github.md) |
+| `@cursor/july/channels/gitlab` | `gitlabChannel()` | GitLab.com and self-managed GitLab hooks. See [GitLab](../guides/gitlab.md) |
+| `@cursor/july/channels/bitbucket` | `bitbucketChannel()` | Bitbucket Cloud and Data Center hooks. See [Bitbucket](../guides/bitbucket.md) |
+| `@cursor/july/channels/deployments` | `deploymentsChannel()` | Deployment events filtered by source, environment, or event name |
+| `@cursor/july/channels/change-monitors` | `changeMonitorsChannel()` | Change Monitor `checkpoint.created` events |
+| `@cursor/july/channels/issues` | `issuesChannel()` | Factory `issue.created` events |
+
+For other platforms like Discord or Teams, use the authored
+`defineChannel` route form.
 
-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](./sessions.md).
+## Continuation tokens
 
-## What's next
+Each channel defines its continuation-token format. The same token
+resumes the same conversation; the built-in HTTP channel rotates its
+opaque token after every accepted follow-up and returns `409` for a
+stale token. See [Session identifiers](./sessions.md#session-identifiers)
+for the full contract.
 
-Continue with these pages:
+## Related
 
-- [Webhooks guide](../guides/webhooks.md): the same API, walked through
-- [HTTP API](./http-api.md): session, discovery, and channel routes
-- [Sessions and streaming](./sessions.md): the events channels
-  subscribe to
+- [Webhooks](../guides/webhooks.md)
+- [HTTP API](./http-api.md)
+- [Sessions](./sessions.md)
+- [Hooks](./hooks.md)