@cursor/july 0.1.100 → 0.1.102

package/docs/guides/cloud-agents.md

@@ -0,0 +1,98 @@
+---
+title: "Cursor cloud agents"
+description: "Let an agent-sdk agent hand coding work to Cursor cloud agents and steer them: mount the extension, pick the repositories it may touch, and decide what needs approval."
+---
+
+# Cursor cloud agents
+
+The `cursor-cloud-agents` extension lets an agent delegate coding work
+to Cursor cloud agents and stay in the conversation while they do it.
+The cloud agents work on real repository checkouts and push branches and
+pull requests; your agent hands off the task, reports back, and answers
+questions in the meantime. A Slack triage agent turns a bug report into
+a PR, a planner fans a refactor out across repositories, a reviewer asks
+a cloud agent to address its own comments.
+
+This is different from the [cloud runtime](./cloud-runtime.md). The
+runtime moves *this* agent's turns onto a cloud VM. The extension keeps
+the agent where it is and lets it start *other* cloud agents.
+
+## Mount it
+
+The extension ships with `@cursor/july`. Mount it with one file.
+
+```ts
+// agent/extensions/cloud.ts
+import cursorCloudAgents from "@cursor/july/extensions/cursor-cloud-agents";
+
+export default cursorCloudAgents({
+  cloud: {
+    repos: [{ url: "https://github.com/acme/api", startingRef: "main" }],
+    autoCreatePR: true,
+  },
+});
+```
+
+Launches run under the host's signed-in account (`agent-sdk login` or
+`CURSOR_API_KEY`) and spend its cloud-agent budget. Name the
+repositories the agent may target, and keep approval on when you can't.
+
+Mount it on an agent that runs on the local runtime; that is where
+launches park for approval. On the
+[cloud runtime](./cloud-runtime.md#what-changes-on-cloud) approvals
+don't resolve.
+
+## What the agent can do
+
+With the extension mounted, the agent can hand off coding work and stay
+in the conversation while it happens:
+
+- **Hand off a task.** Launch a cloud agent on one of your repositories,
+  or on a pull request, with a self-contained brief. It gets back an
+  agent id and a URL to share.
+- **Check on it.** See whether the agent is still running, what it
+  produced, and which branches or pull requests it pushed.
+- **Read what was done.** Pull the agent's full conversation into the
+  workspace, quote its final report, or trace the exact edits before
+  summarizing for a person.
+- **Steer or stop.** Send a follow-up to an agent it launched; it queues
+  behind the current run, or interrupts it on request. Cancel a run that
+  went sideways.
+- **Keep track.** List the agents launched in this conversation, or
+  everything it has launched before.
+
+A skill teaches the model when to delegate, how to write a brief a cloud
+agent can act on alone, and how to follow up. Everything the extension
+launches stays bound to whoever launched it: an agent started by another
+user, or outside the extension, is out of reach. That separation is only
+as fine as your host's auth; a shared bearer token or `--allow-anonymous`
+makes every caller one principal, so use
+[authored auth](../reference/channels.md#auth-policies) when callers need
+their own.
+
+## Configure it
+
+| Option | What it controls |
+| --- | --- |
+| `cloud` | Launch defaults, in the same shape as the agent's own [cloud options](../reference/agent-config.md#cloud-options). |
+| `cloud.repos` | The repositories the agent may hand work to, with a default branch or pull request for each. Without it, launches run with no repository and the model can't name one, so secrets in `cloud.envVars` never reach a repository you didn't list. |
+| `model` | The model launched agents run. Omit it to use the account default. |
+| `needsApproval` | Park launches and follow-ups for a [human decision](./human-in-the-loop.md). Defaults to `true` when no `cloud.repos` are configured, `false` otherwise. |
+| `apiKey` | A Cursor API key to launch with instead of the host's own. |
+
+## Adjust it
+
+To take a capability away, such as sending follow-ups, mount as a
+directory and disable that tool; see
+[overlays](../reference/extensions.md#adjust-a-mounted-extension).
+
+## What's next
+
+Continue with these pages:
+
+- [Extensions](../reference/extensions.md): how mounts, namespaces, and
+  overrides work
+- [Human-in-the-loop approvals](./human-in-the-loop.md): where parked
+  launches get approved
+- [Cloud runtime](./cloud-runtime.md): run the agent's own turns on
+  cloud agents instead

package/docs/guides/cloud-runtime.md

@@ -118,3 +118,5 @@ Continue with these pages:
   `cloud` fields
 - [GitHub guide](./github.md): the webhook patterns that pair with
   cloud triage
+- [Cursor cloud agents](./cloud-agents.md): keep the agent local and
+  let it launch cloud agents instead

package/docs/reference/connections.md

@@ -124,6 +124,37 @@ be called through the direct tool API.
 In a dry-run session, MCP tools marked read-only run normally. Tools marked
 as writes are stubbed. Tools without effect annotations are unavailable.
 
+## Restrict which tools a connection serves
+
+Use `tools` the same way you allowlist harness tools on the agent. When
+set, the connection serves only those names. Use `disallowedTools` to
+drop names instead. The two combine as deny-wins, same as the Cursor
+SDK. The model and `host.mcp` only see what remains. On a model-visible
+connection, set `advertiseTools: true` so the raw server is not attached.
+
+```ts
+export default defineConnection({
+  url: "https://mcp.example.com/inventory",
+  advertiseTools: true,
+  tools: ["search_skus", "get_stock"],
+});
+
+export default defineConnection({
+  url: "https://mcp.example.com/inventory",
+  advertiseTools: true,
+  disallowedTools: ["place_order", "delete_sku"],
+});
+```
+
+Names are the server's `tools/list` names. Unknown names are omitted. A
+filter that matches nothing on the server fails the turn. Combine with
+`effects: "read"` to keep only the listed tools the server classifies as
+reads.
+
+A list of names is an allowlist. An object of handlers authors TypeScript
+tools. On `host-connections/`, a name list restricts `host.mcp` without
+advertising.
+
 ## Local stdio MCP server
 
 Run a local MCP server as a child process with `command`.

package/docs/reference/extensions.md

@@ -0,0 +1,205 @@
+---
+title: "Extensions"
+description: "Mount a package of tools and skills or a Cursor plugin under a namespace with one file, adjust what it contributes, and author your own as a directory laid out like agent/."
+---
+
+# Extensions
+
+An extension packages tools and skills an agent installs as one unit. You
+mount it with a single file under `agent/extensions/`, and its
+contributions join the agent under a namespace. The package updates
+like any other dependency; nothing is copied into your project. A Cursor
+plugin mounts the same way; see [Mount a Cursor plugin](#mount-a-cursor-plugin).
+
+## Mount an extension
+
+Install the package, then add one file. The filename is the namespace.
+
+```ts
+// agent/extensions/ci.ts
+import ci from "@acme/ci-triage";
+
+export default ci({ org: "acme", token: process.env.BUILDKITE_TOKEN! });
+```
+
+Every contribution is exposed as `<namespace>__<name>`. A `failed_jobs`
+tool from this mount runs in the agent as `ci__failed_jobs`, and a
+`triage` skill loads as `ci__triage`. `agent-sdk info` lists each mount
+with what it contributed, and `GET /v1/info` returns the same under
+`extensions`.
+
+Pass the configuration the extension asks for. The extension validates it
+when the agent loads, so a missing or mistyped field fails
+`agent-sdk validate` instead of a tool call later.
+
+Namespaces follow the tool-name rule, and `__` is reserved: an authored
+`agent/tools/ci__failed_jobs.ts` fails discovery, so nothing outside a
+mount can pose as one of its tools.
+
+## Adjust a mounted extension
+
+To replace or remove a contribution, mount the extension as a directory
+and overlay the slot you want to change.
+
+```text
+agent/extensions/ci/
+├── extension.ts        # the mount: export default ci({ ... })
+├── tools/
+│   ├── job_log.ts      # replaces ci__job_log with your own defineTool
+│   └── retry_job.ts    # export default disableTool() removes ci__retry_job
+└── skills/
+    └── triage.md       # replaces ci__triage
+```
+
+Use the extension's own names inside the directory, without the
+namespace. A file with a name the extension doesn't contribute adds a
+new tool or skill under the namespace. `disableTool()` comes from
+`@cursor/july/extensions` and fails discovery when it names a tool the
+extension doesn't have, so a typo can't silently keep a tool alive.
+A Cursor plugin mount overlays its MCP servers the same way; see below.
+
+## Mount a Cursor plugin
+
+A Cursor plugin is a directory with `.cursor-plugin/plugin.json` (or
+`.claude-plugin/plugin.json`, or `plugin.json`) and any of `skills/`,
+`commands/`, `agents/`, and `mcp.json`. Copy the plugin into your project
+and mount it with `cursorPlugin`. The filename is the namespace, as with
+any extension.
+
+```ts
+// agent/extensions/notion.ts
+import { cursorPlugin } from "@cursor/july/extensions";
+
+export default cursorPlugin({
+  path: "plugins/notion-workspace", // relative to the project root
+  variables: { NOTION_TOKEN: process.env.NOTION_TOKEN! },
+});
+```
+
+The plugin joins the agent under that namespace:
+
+| Plugin content | Becomes |
+| --- | --- |
+| `skills/<name>/SKILL.md` | skill `notion__<name>` |
+| `commands/<name>.md` | skill `notion__<name>`, since a command is a procedure the model runs on request |
+| `agents/<name>.md` | subagent `notion__<name>` |
+| MCP servers in `mcp.json` or the manifest | connection `notion__<server>` |
+
+`variables` fills the `${NAME}` placeholders the plugin's MCP config
+declares; names you leave out come from the environment by exact name. A
+placeholder nothing fills fails `agent-sdk validate`, so a server never
+attaches half configured. A server that declares an OAuth client
+authorizes through [host MCP OAuth](../guides/mcp-oauth.md) as
+`agent-sdk mcp oauth notion__<server>`; its secret names collapse the
+namespace separator, so `notion__notion` stores `MCP_OAUTH_NOTION_NOTION_*`.
+A server that lists `enabledTools` mounts as an advertised connection with
+that allowlist and requires the local runtime; `agent-sdk validate` fails
+otherwise.
+
+Mounting a plugin trusts it like authored code: its servers run the
+commands and read the environment variables its config names. Review a
+plugin before you vendor it.
+
+Plugin rules and hooks are not mounted; `agent-sdk validate` warns when a
+plugin carries them. To drop or reconfigure one of the plugin's servers,
+mount as a directory and overlay `mcp-connections/<server>.ts`. An
+overlaid server is never read from the plugin, so it needs no variables.
+
+```text
+agent/extensions/cloudflare/
+├── extension.ts                        # export default cursorPlugin({ path: "plugins/cloudflare" })
+└── mcp-connections/
+    ├── cloudflare-docs.ts              # replaces cloudflare__cloudflare-docs with your defineConnection
+    └── cloudflare-bindings.ts          # export default disableConnection() drops it
+```
+
+`disableConnection()` comes from `@cursor/july/extensions` and fails
+discovery when it names a server the plugin doesn't declare.
+
+## Build an extension
+
+An extension is a directory laid out like `agent/`. `extension.ts`
+declares it; `tools/` and `skills/` hold the contributions in the same
+authoring forms as [Tools](./tools.md) and [Skills](./skills.md).
+
+```text
+@acme/ci-triage/
+├── package.json
+├── extension.ts        # defineExtension
+├── tools/
+│   ├── failed_jobs.ts
+│   ├── job_log.ts
+│   └── retry_job.ts
+├── skills/
+│   └── triage.md
+└── lib/
+    └── buildkite.ts    # shared code, never discovered
+```
+
+Declare the extension with its root and, when consumers must configure
+it, a schema for their settings.
+
+```ts
+// extension.ts
+import { defineExtension } from "@cursor/july/extensions";
+import { z } from "zod";
+
+export default defineExtension({
+  root: import.meta.dirname,
+  description: "Investigate failing CI builds on Buildkite.",
+  config: z.object({
+    org: z.string(),
+    token: z.string(),
+    logTailLines: z.number().int().positive().default(200),
+  }),
+});
+```
+
+The default export is what consumers call to mount the extension, and it
+is also how your own modules read the consumer's settings. Import it and
+read `extension.config`; the value is validated and has defaults applied.
+
+```ts
+// tools/job_log.ts
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+import extension from "../extension.js";
+import { jobLogTail } from "../lib/buildkite.js";
+
+export default defineTool({
+  description: "Read the tail of a CI job's log.",
+  effect: "read",
+  inputSchema: z.object({ pipeline: z.string(), build: z.number(), job: z.string() }),
+  async execute({ pipeline, build, job }) {
+    const { org, token, logTailLines } = extension.config;
+    return jobLogTail({ org, token, pipeline, build, job, lines: logTailLines });
+  },
+});
+```
+
+Because the consumer picks the namespace, have skills and tool
+descriptions refer to sibling tools by their short names and say they
+appear under the mount's namespace (`<namespace>__job_log`).
+
+Publish the built `extension.js` as the package entry point with
+`tools/` and `skills/` beside it. `root` is read from the built file, so
+copy `skills/*.md` into the build output or author skills as `.ts` with
+`defineSkill`.
+
+Only `tools/` and `skills/` are mounted from an extension tree.
+Instructions, connections, hooks, channels, and the runtime
+configuration belong to the agent that mounts the extension;
+`agent-sdk validate` warns when a tree carries agent slots such as
+`instructions.md`, `connections/`, `hooks/`, `channels/`, or
+`schedules/`.
+
+## What's next
+
+Continue with these pages:
+
+- [Cursor cloud agents](../guides/cloud-agents.md): the extension that
+  lets an agent launch and steer cloud agents
+- [Tools](./tools.md): the tool contract extensions contribute to
+- [Skills](./skills.md): the skill forms an extension can carry
+- [Project layout](./project-layout.md): where `agent/extensions/` sits
+  in the tree

package/docs/reference/http-api.md

@@ -53,7 +53,7 @@ and `playgroundUrl` deep-links the session in the playground.
 | `message` | Required user message |
 | `title` | Session title |
 | `dryRun` | Run read tools and stub write tools |
-| `asOf` | ISO-8601 instant with a timezone, frozen at create; the prompt states it, `ctx.now()` returns it, and tools declaring `timeArgs` refuse calls not bounded at or before it. `400` when unusable |
+| `asOf` | ISO-8601 instant with a timezone, frozen at create; the prompt states it, `ctx.now()` returns it, and tool calls with relative, later-than-`asOf`, or omitted schema-declared time bounds are refused. `400` when unusable |
 | `workspaceFiles` | UTF-8 files written into the session workspace |
 | `cloud` | Per-session cloud options merged over the agent defaults |
 

package/docs/reference/project-layout.md

@@ -21,6 +21,8 @@ experiments can override their file-derived name.
 | `agent/host-connections/anytool.ts` | Host MCP connection `anytool` (host + `mcp oauth` only) |
 | `agent/skills/pr-review.md` | skill `pr-review` |
 | `agent/subagents/reviewer/` | subagent `reviewer` |
+| `agent/extensions/ci.ts` | extension mount `ci`; its tools and skills become `ci__<name>` |
+| `agent/extensions/notion.ts` | Cursor plugin mount `notion` (`cursorPlugin`); its skills, agents, and MCP servers become `notion__<name>` |
 | `agent/channels/drive.ts` | channel `drive`, routes under `/v1/channels/drive` |
 | `agent/ab.ts` | A/B experiment `ab` unless `name` overrides it |
 | `agent/ab/concise.ts` | A/B experiment `concise` unless `name` overrides it |
@@ -71,6 +73,7 @@ Each path maps to a capability and a reference page.
 | `agent/mcp-connections/<name>.ts` | MCP servers, available to the model, to server tools (`ctx.host.mcp`), and to channel/schedule handlers (`args.host.mcp`) | [MCP connections](./connections.md) |
 | `agent/host-connections/<name>.ts` | Privileged MCP servers for `ctx.host.mcp` and `mcp oauth`. The model never sees them. | [MCP connections](./connections.md) |
 | `agent/subagents/<id>/` | Child agent directory; `description` required | [Subagents](./subagents.md) |
+| `agent/extensions/<ns>.ts` or `agent/extensions/<ns>/` | A mounted extension or Cursor plugin; its contributions become `<ns>__<name>` | [Extensions](./extensions.md) |
 | `agent/channels/*.ts` | HTTP surfaces beyond the built-in session API; `slack.ts` and `github.ts` use the platform packs | [Channels](./channels.md) |
 | `agent/hooks/*.ts` | Observe-only event subscribers, never fatal | [Hooks](./hooks.md) |
 | `agent/otel.ts` | `defineOtel` OTLP export (traces, metrics, optional logs) | [OpenTelemetry](../guides/opentelemetry.md) |

package/docs/reference/skills.md

@@ -85,4 +85,6 @@ Continue with these pages:
 
 - [Instructions](./instructions.md): what stays always-on
 - [Tools](./tools.md): when prose needs to become code
+- [Extensions](./extensions.md): skills installed as a package under a
+  namespace
 - [Project layout](./project-layout.md): where skills sit in the tree

package/docs/reference/tools.md

@@ -343,4 +343,6 @@ Continue with these pages:
   lifecycle in full
 - [MCP connections](./connections.md): tools that come from MCP servers
   instead
+- [Extensions](./extensions.md): tools installed as a package under a
+  namespace
 - [Evals](../evals.md): gating tool decisions with `calledTool`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.100",
+  "version": "0.1.102",
   "description": "(early alpha) Filesystem-first framework for defining Cursor agents as markdown and TypeScript and serving them over channels with the Cursor SDK.",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
@@ -95,6 +95,20 @@
       "import": "./dist/skills.js",
       "default": "./dist/skills.js"
     },
+    "./extensions": {
+      "anysphere-source": "./src/extensions.ts",
+      "bun": "./dist/extensions.js",
+      "types": "./dist/extensions.d.ts",
+      "import": "./dist/extensions.js",
+      "default": "./dist/extensions.js"
+    },
+    "./extensions/cursor-cloud-agents": {
+      "anysphere-source": "./src/extensions/cursor-cloud-agents/extension.ts",
+      "bun": "./dist/extensions/cursor-cloud-agents/extension.js",
+      "types": "./dist/extensions/cursor-cloud-agents/extension.d.ts",
+      "import": "./dist/extensions/cursor-cloud-agents/extension.js",
+      "default": "./dist/extensions/cursor-cloud-agents/extension.js"
+    },
     "./schedules": {
       "anysphere-source": "./src/schedules.ts",
       "types": "./dist/schedules.d.ts",
@@ -215,7 +229,7 @@
     }
   },
   "scripts": {
-    "build": "tsgo -p tsconfig.build.json && node scripts/bundle-publish-shims.mjs && pnpm run build:playground && pnpm run docs:build",
+    "build": "tsgo -p tsconfig.build.json && node scripts/bundle-publish-shims.mjs && node scripts/copy-extension-assets.mjs && pnpm run build:playground && pnpm run docs:build",
     "build:dist": "node scripts/build-hosted-dist.mjs",
     "postinstall": "node -e \"try{const p='./scripts/install-cursor-skills.mjs';if(require('fs').existsSync(p))require('child_process').execFileSync(process.execPath,[p],{stdio:'inherit'})}catch{}\"",
     "build:playground": "vite build --config playground/vite.config.ts",
@@ -240,7 +254,7 @@
   },
   "dependencies": {
     "@bazel/runfiles": "6.5.0",
-    "@cursor/sdk": "1.0.30",
+    "@cursor/sdk": "1.0.31",
     "@modelcontextprotocol/sdk": "1.25.1",
     "@octokit/auth-app": "^7.2.0",
     "@octokit/rest": "^21.1.1",
@@ -303,4 +317,4 @@
     "yaml": "^2.4.2",
     "zustand": "^5.0.9"
   }
-}
+}

package/skills/framework-map/SKILL.md

@@ -44,6 +44,7 @@ Path is identity. Full list: README "Folder structure".
 | `agent/mcp-connections/<name>.ts` | MCP. Never name an account file `cursor.ts`. `advertiseTools: true` for named local tools |
 | `agent/host-connections/<name>.ts` | Privileged MCP for `ctx.host.mcp` / `mcp oauth` |
 | `agent/subagents/<id>/` | Child agent (`description` required) |
+| `agent/extensions/<ns>.ts` | Mounted extension or Cursor plugin (`cursorPlugin({ path })`); contributions are `<ns>__<name>` |
 | `agent/channels/*.ts` | Slack / GitHub / custom HTTP |
 | `agent/hooks/*.ts` | Observe-only |
 | `agent/ab.ts` or `agent/ab/*.ts` | Live A/B (`defineAB`) |

package/src/bin/agent-serve.ts

@@ -426,8 +426,8 @@ Options:
   --all              deploy: every child agent under a multi-agent --dir
                      (skips the interactive picker; mutually exclusive with
                      --slug).
-  --cursor-events-repo  deploy: repo (owner/name) whose SCM events the
-                     deployed engine pulls (repeatable).
+  --cursor-events-repo  deploy: repo (owner/name) the deployed agent
+                     watches (repeatable).
   --allow-domain     deploy: egress domain the engine pod may reach
                      (repeatable; unioned with hosting.egressDomains from the
                      agent manifest). Repo-backed deploys only.
@@ -1160,6 +1160,15 @@ async function main(argv: string[]): Promise<number> {
           info.skills.map((s) => `${s.name} — ${s.description}`)
         )
       );
+      lines.push(
+        section(
+          "extensions",
+          info.extensions.map(
+            (e) =>
+              `${e.name} — ${[...e.tools, ...e.skills].join(", ") || "(nothing contributed)"}`
+          )
+        )
+      );
       lines.push(
         section(
           "MCP connections",

package/src/channels/deployments/deployments-channel.ts

@@ -1,7 +1,11 @@
 import { z } from "zod";
 
 import { defineChannel, localDevStrict, POST } from "../../channels.js";
-import { resolveDeploymentSubscriptions } from "../../internal/cursor-deployment-relay.js";
+import {
+  deploymentEventMatches,
+  resolveDeploymentSubscriptions,
+} from "../../internal/cursor-deployment-relay.js";
+import { attachHostedAdmissionAdapter } from "../../internal/hosted-admission-adapter.js";
 import { bindLocalIngressSend } from "../../internal/local-ingress.js";
 import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
 import {
@@ -43,14 +47,28 @@ export function getDeploymentsChannelOptions(
 /**
  * Events a {@link deploymentsChannel} dispatches on, unioned from its
  * subscriptions. Published as `meta.deploymentEventTypes` so the deploy
- * manifest can extract `eventTypes`. An empty deploy-source list is an
- * inert channel and yields no events.
+ * manifest can extract `eventTypes`.
+ *
+ * A channel with no resolved subscriptions declares the full event set:
+ * deploy sources usually come from env vars read at module load, and the
+ * hosted freeze bakes hermetically (no customer env/secrets), so deriving
+ * `[]` there would leave the manifest without event types and no
+ * subscription edge could ever materialize (invariant 26). Capability is
+ * the channel's code shape — `onEvent` handles any deployment event —
+ * while sources/environments/event narrowing are runtime subscription
+ * config; the hosted-admission adapter re-applies them before authored
+ * code runs. Inertness is still guaranteed by scope: a deploy that names
+ * no deploy sources binds no edges.
  */
 export function deriveDeploymentEventTypes(
   options: Pick<DeploymentsChannelOptions, "deploySourceUris" | "events">
 ): string[] {
+  const subscriptions = resolveDeploymentSubscriptions(options);
+  if (subscriptions.length === 0) {
+    return [...DEPLOYMENT_EVENT_TYPES].sort();
+  }
   const events = new Set<string>();
-  for (const subscription of resolveDeploymentSubscriptions(options)) {
+  for (const subscription of subscriptions) {
     for (const event of subscription.events) {
       events.add(event);
     }
@@ -59,9 +77,9 @@ export function deriveDeploymentEventTypes(
 }
 
 /**
- * Core deployment-event dispatch, used by the channel's replay route and by
- * the serve host's relay fan-out. Whether the event matches this channel's
- * subscriptions is the caller's decision.
+ * Core deployment-event dispatch, used by the channel's replay route, the
+ * serve host's relay fan-out, and the hosted-admission adapter. Whether the
+ * event matches this channel's subscriptions is the caller's decision.
  */
 export async function dispatchDeploymentEvent(input: {
   options: DeploymentsChannelOptions;
@@ -77,7 +95,61 @@ export async function dispatchDeploymentEvent(input: {
       payload: input.event,
     })
   );
-  return Response.json({ ok: true });
+  // "task": authored `onEvent` ran to completion without a captured send.
+  // Hosted admission only consults this when no send was captured.
+  return withDispatchOutcome(Response.json({ ok: true }), "task");
+}
+
+export type DeploymentsDispatchOutcome = "skip" | "task";
+
+const dispatchOutcomeByResponse = new WeakMap<
+  Response,
+  DeploymentsDispatchOutcome
+>();
+
+function withDispatchOutcome(
+  response: Response,
+  outcome: DeploymentsDispatchOutcome
+): Response {
+  dispatchOutcomeByResponse.set(response, outcome);
+  return response;
+}
+
+export function getDeploymentsDispatchOutcome(
+  response: Response
+): DeploymentsDispatchOutcome | undefined {
+  return dispatchOutcomeByResponse.get(response);
+}
+
+/**
+ * Whether this channel admits the event on a hosted pod. The hosted
+ * control plane fans out on `(deploy_source, eventType, team)` edges only —
+ * environments are not edge identity — so this is where the environment
+ * filter (and a stale-edge guard for sources/events) lives, mirroring what
+ * the v1 relay does before `onEvent`.
+ *
+ * A channel with NO resolved subscriptions admits everything the control
+ * plane delivered: deploy sources usually come from env vars read at
+ * module load, and the hosted freeze bakes hermetically (no customer env),
+ * so on a restored pod an env-configured channel resolves empty — the
+ * deploy-time edges (bound from the watched repositories) already carry
+ * the customer's scope, and refusing here would silently drop every
+ * delivery. Same posture as {@link deriveDeploymentEventTypes}: authored
+ * subscriptions narrow; an unconfigured channel defers to the deploy scope.
+ */
+export function deploymentEventMatchesChannel(
+  options: DeploymentsChannelOptions,
+  event: DeploymentEvent
+): boolean {
+  const subscriptions = resolveDeploymentSubscriptions(options);
+  if (subscriptions.length === 0) {
+    return true;
+  }
+  return subscriptions.some(
+    (subscription) =>
+      subscription.deploySourceUri === event.deploySourceUri.toLowerCase() &&
+      deploymentEventMatches(subscription, event)
+  );
 }
 
 /**
@@ -102,6 +174,13 @@ export async function dispatchDeploymentEvent(input: {
  * have. Nothing is pushed to this deployment and no shared secret exists on
  * either side.
  *
+ * Hosted v2 deployments do not poll: the control plane fans verified factory
+ * deployment events out on `deploy_source` subscription edges — derived from
+ * the deploy's watched `repositories`, since factory records deploy sources
+ * as Origin repo URLs — and delivers through hosted admission. The attached
+ * adapter re-applies this channel's subscription filter — environments are
+ * not edge identity — and skips before authored code runs.
+ *
  * The route on this channel exists for local replay (`agent-sdk` and tests):
  * POST an event body and it runs the same `onEvent`.
  */
@@ -136,5 +215,35 @@ export function deploymentsChannel(
     ],
   });
   deploymentsChannelOptionsByDefinition.set(definition, options);
+  // Hosted v2 delivery: the control plane admits a deployments mailbox item
+  // (deploy_source edge match) and posts the claim-checked factory envelope
+  // here. Environments are not edge identity, so non-matching environments
+  // (and stale-edge sources/events) are filtered to `skip` before authored
+  // code runs — the same pre-`onEvent` filter the v1 relay applies.
+  attachHostedAdmissionAdapter(definition, {
+    kind: DEPLOYMENTS_CHANNEL_KIND,
+    dispatch: async ({ payload, args }) => {
+      const parsed = deploymentEventSchema.safeParse(payload);
+      if (!parsed.success) {
+        return Response.json(
+          { ok: false, error: "invalid_deployment_event" },
+          { status: 400 }
+        );
+      }
+      const event = parsed.data as DeploymentEvent;
+      if (!deploymentEventMatchesChannel(options, event)) {
+        return withDispatchOutcome(
+          Response.json({
+            ok: true,
+            skipped: true,
+            reason: "subscription_mismatch",
+          }),
+          "skip"
+        );
+      }
+      return dispatchDeploymentEvent({ options, event, args });
+    },
+    getOutcome: (response) => getDeploymentsDispatchOutcome(response),
+  });
   return definition;
 }

package/src/channels/deployments/types.ts

@@ -54,9 +54,10 @@ export interface DeploymentsChannelOptions {
    * and then receives nothing. A bare string takes the default environment and
    * event filters.
    *
-   * There is no team-wide subscription: every deploy source is named. At least
-   * one is required — an empty list is how a consumer *deregisters*, so it
-   * cannot also mean "everything".
+   * There is no team-wide subscription: every deploy source is named. An
+   * empty list is how a consumer *deregisters*, so it cannot also mean
+   * "everything". A live array that starts empty and is filled later is
+   * re-read on each registration heartbeat.
    */
   deploySourceUris: readonly (string | DeploymentSubscription)[];
   /**