@cursor/july 0.1.113 → 0.1.114

package/docs/reference/artifacts.md

@@ -1,17 +1,16 @@
 ---
 title: "Artifacts"
-description: "Tag durable outputs (reviewed PRs, reports) so they persist across sessions, stream as events, and list over HTTP."
+description: "Declare, tag, list, stream, and download durable agent outputs."
 ---
 
 # Artifacts
 
-An artifact marks a durable output the agent produced: a reviewed PR
-URL, a generated report, a decision record. Sessions come and go;
-artifacts persist across them, capped and listable, so the people
-supervising an agent see what it shipped without replaying event
-streams.
+Artifacts are durable outputs such as reviewed pull requests, reports,
+or decision records. An artifact kind defines the data it accepts, and
+the artifacts API tags or updates records by key. Records persist across
+sessions and can be listed, streamed, or downloaded.
 
-## Declare kinds
+## Artifact kinds
 
 Author `agent/artifacts.ts` with `defineArtifacts` from
 `@cursor/july/artifacts`:
@@ -32,26 +31,21 @@ export default defineArtifacts({
 });
 ```
 
-`defineArtifacts` accepts three fields. `kinds` declares the artifact
-kinds: with kinds declared, `tag` accepts only these; with none, any
-kind string is accepted freeform. Each kind's `description` says what it
-holds and doubles as the model-facing prompt for `tag_artifact`. An
-optional Zod `schema` validates payloads before they persist (the parsed
-output is stored, so defaults and coercions apply). `agentTool` exposes
-the model-facing `tag_artifact` tool generated from the kinds registry;
-it requires at least one declared kind. `max` is the retention cap,
-default 1000: on insert past the cap, the oldest-updated artifact is
-evicted.
-
-## Tag from host code
-
-Every handler surface carries `ctx.artifacts` (or `args.artifacts`),
-an `ArtifactsApi` with `tag` and `list`: tools, hooks, channel route
-handlers and `onStart`, schedule `run` handlers, and reminder `run`
-handlers. Tool and hook facades are session-bound, so `tag` auto-fills
-the `sessionId` (and `turnId` when known). Channel, schedule, and
-reminder facades are unbound; pass `sessionId` in the tag input to
-attribute one.
+| Option | Contract |
+| --- | --- |
+| `kinds` | Map of accepted kind names to a non-empty `description` and optional Zod `schema` |
+| `agentTool` | Expose `tag_artifact` to the model; requires at least one declared kind |
+| `max` | Positive retention cap; defaults to `1000` and evicts the oldest-updated record |
+
+With declared kinds, `tag` rejects any other kind. With no registry, it
+accepts free-form kind names and defaults an omitted kind to
+`"artifact"`. A kind's schema validates `data`, and the parsed value is
+stored, including schema defaults and coercions.
+
+## Tag artifacts from host code
+
+Tools, hooks, channel handlers, channel `onStart`, schedules, and
+reminders receive an `ArtifactsApi` with `tag` and `list`.
 
 ```ts
 await ctx.artifacts.tag({
@@ -62,56 +56,63 @@ await ctx.artifacts.tag({
 });
 ```
 
-`key` is the upsert handle: tagging the same key again replaces the
-record instead of creating a new one, so re-reviewing a PR updates one
-row. A `contents` payload (string or bytes, with an optional
-`contentType`) attaches a file or blob served at
-`GET /v1/artifacts/:id/content`; re-tagging a keyed artifact without
-`contents` keeps the existing payload.
-
-## Let the model tag
+| Tag field | Contract |
+| --- | --- |
+| `data` | Required JSON data, validated when the kind has a schema |
+| `kind` | Declared or free-form kind |
+| `key` | Agent-wide upsert key; the same key updates one record across kinds |
+| `title` | Optional display title |
+| `contents` | String or bytes served by the content route |
+| `contentType` | MIME type for `contents` |
+| `sessionId`, `turnId` | Attribute the artifact to a session or turn |
+| `source` | `"host"` or `"model"`; defaults to `"host"` |
+
+Tool, hook, result, and channel-event contexts are session-bound, so
+they fill `sessionId` and the current `turnId`. Channel routes,
+`onStart`, schedules, and reminders receive an unbound facade; pass
+`sessionId` to attribute an artifact.
+
+Re-tagging a key without `contents` keeps its file or blob when the
+`sessionId` stays the same. Rebinding the key to another session without
+new contents removes the previous payload. `tag` returns the stored
+`ArtifactRecord`.
+
+| Record field | Contract |
+| --- | --- |
+| `id` | Stable ID derived from `key`, or a generated ID when no key is set |
+| `kind`, `data` | Validated kind and JSON payload |
+| `key`, `title` | Optional upsert key and display title |
+| `content` | Optional `{ size, contentType? }` metadata |
+| `sessionId`, `turnId` | Optional session attribution |
+| `source` | `"host"` or `"model"` |
+| `createdAt`, `updatedAt` | ISO-8601 timestamps |
+
+## Expose `tag_artifact` to the model
 
 With `agentTool: true`, the `tag_artifact` server tool materializes from
-the kinds registry. Its description tells the model to tag notable
-outputs and lists each kind with its description, and its input schema
-is a discriminated union over the declared kinds, so a schema'd kind is
-validated exactly like a host-side tag. An authored tool named
-`tag_artifact` shadows the built-in, with a warning.
-
-## Observe and list
+the kinds registry. Its input accepts the declared kinds and validates
+their data with the same schemas as host-side tagging. The kind
+descriptions tell the model which output each one represents.
 
-Tagging emits an `artifact.tagged` event on the attributed session's
-stream, carrying the record: `id`, `kind`, `key`, `title`, `data`, and
-`source` (`"host"` for host code, `"model"` for `tag_artifact`). Hooks,
-channel `events`, and evals see it like any other
-[stream event](./sessions.md#which-events-can-i-stream).
+An authored tool named `tag_artifact` takes precedence over the generated
+tool.
 
-Over HTTP:
+## List artifacts
 
-```bash
-curl 'http://127.0.0.1:3000/<slug>/v1/artifacts?kind=reviewed-pr&limit=20'
-curl 'http://127.0.0.1:3000/<slug>/v1/artifacts/<id>/content'
-```
+`list({ kind?, sessionId? })` returns matching records newest-updated
+first. HTTP callers can list records and download content through the
+[artifact routes](./http-api.md#list-and-download-artifacts).
 
-`GET /v1/artifacts` returns records newest-updated first, filterable by
-`kind` and `sessionId`. Session ownership applies, same as
-`/v1/sessions`. The playground renders tagged artifacts too.
-
-## Gate evals on tagging
-
-`t.taggedArtifact(kind?, predicate?)` gates an eval on at least one
-artifact tagged during the test turn, optionally of one kind and
-matching a predicate over the record:
-
-```ts
-t.taggedArtifact("reviewed-pr", (record) => record.source === "model");
-```
+## Stream artifact tags
 
-## What's next
+Tagging an artifact with a `sessionId` emits `artifact.tagged` on that
+session. Its event data contains `id`, `kind`, `key`, `title`, `data`,
+and `source`. See [Stream events](./sessions.md#stream-events) for the
+event envelope.
 
-Continue with these pages:
+## Related
 
-- [Sessions and streaming](./sessions.md): the `artifact.tagged` event
-  in the full vocabulary
-- [Tools](./tools.md): the `ctx` that carries `artifacts`
-- [Evals](../evals.md): the assertions `taggedArtifact` sits beside
+- [Sessions](./sessions.md)
+- [Tools](./tools.md)
+- [Evals](./evals.md)
+- [HTTP API](./http-api.md)

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)