@cursor/july 0.1.100 → 0.1.101

package/dist/types.js

@@ -92,6 +92,32 @@ export function normalizeConnectionEffects(effects) {
     }
     return unique;
 }
+/**
+ * Trim, drop blanks, and unique-preserve authored
+ * {@link ConnectionConfig.tools} name lists. Invalid shapes are left
+ * for discovery.
+ */
+export function normalizeConnectionTools(tools) {
+    const unique = [];
+    const seen = new Set();
+    for (const raw of tools) {
+        const name = raw.trim();
+        if (name === "" || seen.has(name)) {
+            continue;
+        }
+        seen.add(name);
+        unique.push(name);
+    }
+    return unique;
+}
+/** True when `toolName` passes the connection's `tools` / `disallowedTools` filter. */
+export function connectionAllowsTool(filter, toolName) {
+    if (filter.tools !== undefined && !filter.tools.includes(toolName)) {
+        return false;
+    }
+    return (filter.disallowedTools === undefined ||
+        !filter.disallowedTools.includes(toolName));
+}
 /** True for the peer-agent transport variant (`{ agent: "<slug>" }`). */
 export function isPeerConnectionTransport(transport) {
     return "agent" in transport;
@@ -146,7 +172,9 @@ export function isSymbolicConnectionTransport(transport) {
 }
 /** True when the connection authors tools instead of a spawn/URL/peer. */
 export function isInlineStdioConnection(connection) {
-    return "tools" in connection && connection.tools !== undefined;
+    return ("tools" in connection &&
+        connection.tools !== undefined &&
+        !Array.isArray(connection.tools));
 }
 // ============================================================================
 // Direct tool calls (deterministic invocation, no model turn)

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.100",
+  "version": "0.1.101",
   "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/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)[];
   /**

package/src/channels/origin/defaults.ts

@@ -0,0 +1,143 @@
+/**
+ * Default stream-event handlers for the Origin channel: reply delivery.
+ *
+ * The GitHub channel posts completed assistant messages back to the PR via
+ * `buildDefaultGitHubEvents`; this is the Origin analogue. Outbound
+ * credentials resolve exactly like `ctx.origin` in hooks (see
+ * ./binding.ts): channel app credentials / `ORIGIN_APP_*` env when
+ * configured, otherwise — for `cursorAccount` channels — the Cursor-account
+ * session exchange, which on hosted v2 acts as the deployment
+ * service-account principal. The `agent-serve` SA scope allowlist includes
+ * `repository:pull_requests:reviews:write`, the scope
+ * `CreatePullRequestComment` checks, so no extra grant is needed.
+ */
+
+import type { ChannelEventHandlers } from "../../types.js";
+import { buildOriginBinding, type OriginHandle } from "./binding.js";
+import type { OriginChannelState } from "./state.js";
+import type { OriginAppOptions } from "./types.js";
+
+/** Hidden marker on outbound Origin comments so consumers can spot them. */
+export const ORIGIN_OUTBOUND_MARKER = "<!-- agent-serve-origin -->";
+
+export function formatOriginOutboundComment(body: string): string {
+  if (body.includes(ORIGIN_OUTBOUND_MARKER)) {
+    return body;
+  }
+  return `${body.trimEnd()}\n\n${ORIGIN_OUTBOUND_MARKER}`;
+}
+
+export interface BuildDefaultOriginEventsOptions {
+  /** Force the signed-in Cursor account / deployment SA credential path. */
+  cursorAccount?: boolean | { repos: readonly string[] };
+  /** Channel-authored outbound app credentials / API base. */
+  app?: OriginAppOptions;
+  /**
+   * When false, skip posting completed assistant messages (and failure
+   * notices) back to the Origin pull request. Defaults to true.
+   */
+  deliverReplies?: boolean;
+  /** Injectable binding builder for tests. */
+  buildBinding?: typeof buildOriginBinding;
+}
+
+function bindingForState(
+  options: BuildDefaultOriginEventsOptions,
+  state: OriginChannelState
+): OriginHandle {
+  const build = options.buildBinding ?? buildOriginBinding;
+  return build({
+    repository: {
+      owner: state.owner,
+      name: state.repo,
+      fullName: `${state.owner}/${state.repo}`,
+    },
+    ...(state.installationId === null
+      ? {}
+      : { installationId: state.installationId }),
+    cursorAccount:
+      options.cursorAccount !== undefined && options.cursorAccount !== false,
+    app: options.app,
+  });
+}
+
+async function postPullRequestComment(
+  options: BuildDefaultOriginEventsOptions,
+  state: OriginChannelState,
+  body: string
+): Promise<void> {
+  if (
+    state.owner === "" ||
+    state.repo === "" ||
+    state.pullRequestNumber === null
+  ) {
+    return;
+  }
+  const origin = bindingForState(options, state);
+  await origin.request({
+    method: "POST",
+    path: `/v1/origin/repos/${encodeURIComponent(state.owner)}/${encodeURIComponent(
+      state.repo
+    )}/pulls/${state.pullRequestNumber}/comments`,
+    body: { body: formatOriginOutboundComment(body) },
+  });
+}
+
+/**
+ * Built-in delivery: post assistant text on `message.completed`, and a
+ * short error comment on turn/session failure. Every post soft-fails so a
+ * missing outbound credential (or an Origin refusal) never crashes the
+ * session — the GitHub defaults' posture.
+ */
+export function buildDefaultOriginEvents(
+  options: BuildDefaultOriginEventsOptions = {}
+): ChannelEventHandlers<OriginChannelState> {
+  const deliverReplies = options.deliverReplies !== false;
+
+  return {
+    async "message.completed"(event, channel) {
+      if (!deliverReplies) {
+        return;
+      }
+      if (event.data.finishReason === "tool_call" || event.data.text === "") {
+        return;
+      }
+      try {
+        await postPullRequestComment(options, channel.state, event.data.text);
+      } catch {
+        // Soft-fail delivery so a missing credential does not crash the session.
+      }
+    },
+
+    async "turn.failed"(_event, channel) {
+      await postFailure(options, channel, deliverReplies);
+    },
+
+    async "session.failed"(_event, channel) {
+      await postFailure(options, channel, deliverReplies);
+    },
+  };
+}
+
+async function postFailure(
+  options: BuildDefaultOriginEventsOptions,
+  channel: { state: OriginChannelState },
+  deliverReplies: boolean
+): Promise<void> {
+  if (!deliverReplies) {
+    return;
+  }
+  try {
+    await postPullRequestComment(
+      options,
+      channel.state,
+      [
+        "I hit an error while handling your request.",
+        "",
+        "Please try again, or reach out if it keeps failing.",
+      ].join("\n")
+    );
+  } catch {
+    // Soft-fail.
+  }
+}

package/src/channels/origin/index.ts

@@ -26,8 +26,10 @@ export * from "./api.js";
 export * from "./binding.js";
 export * from "./checks.js";
 export * from "./cursor-account.js";
+export * from "./defaults.js";
 export * from "./events.js";
 export * from "./origin-channel.js";
 export * from "./origin-webhook.js";
 export * from "./reactions.js";
+export * from "./state.js";
 export * from "./types.js";

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

@@ -18,13 +18,16 @@ import type {
   AgentCloudOptions,
   AuthContext,
   ChannelDefinition,
+  ChannelEventHandlers,
   ChannelHandlerArgs,
+  JsonValue,
 } from "../../types.js";
 import { buildOriginBinding } from "./binding.js";
 import {
   parseCursorOriginRepoScope,
   registerOriginCursorAccountRuntime,
 } from "./cursor-account.js";
+import { buildDefaultOriginEvents } from "./defaults.js";
 import { deriveOriginWebhookEvents, ORIGIN_CHANNEL_KIND } from "./events.js";
 import {
   DEFAULT_ORIGIN_API_BASE_URL,
@@ -32,6 +35,11 @@ import {
   type OriginWebhookHeaders,
   verifyOriginWebhook,
 } from "./origin-webhook.js";
+import {
+  emptyOriginChannelState,
+  type OriginChannelState,
+  originChannelStateForEvent,
+} from "./state.js";
 import type {
   OriginActor,
   OriginChannelOptions,
@@ -432,6 +440,7 @@ function enrichEventContext(input: {
     ...input.ctx,
     host: input.args.host,
     artifacts: input.args.artifacts,
+    send: input.args.send,
     origin: buildOriginBinding({
       repository: input.ctx.repository,
       installationId: input.ctx.installationId,
@@ -504,6 +513,7 @@ async function startTurn(input: {
   message: string;
   dispatch: OriginTurnDispatch;
   cloud?: AgentCloudOptions;
+  state: OriginChannelState;
 }): Promise<Response> {
   const source = continuationSource(input.options.continuation, "origin");
   const session = await input.args.send(input.message, {
@@ -513,6 +523,10 @@ async function startTurn(input: {
       : {}),
     title: input.dispatch.title ?? defaultOriginTitle(input.ctx),
     ...(input.cloud === undefined ? {} : { cloud: input.cloud }),
+    state: input.state as unknown as JsonValue,
+    // Resume must refresh the triggering comment / delivery identifiers so
+    // reply delivery targets the latest wake, not the session's first.
+    refreshState: input.state as unknown as JsonValue,
   });
   if (isDeferredChannelSession(session)) {
     // Hosted admission captured the send; the control plane allocates the
@@ -569,6 +583,8 @@ async function applyDispatch(input: {
   extra: Record<string, unknown>;
   message: string;
   cloud?: AgentCloudOptions;
+  /** Comment id that woke this dispatch (comment events only). */
+  triggeringCommentId?: string;
 }): Promise<Response> {
   if (input.dispatch === null) {
     return skipped("not_dispatched", input.extra);
@@ -587,6 +603,14 @@ async function applyDispatch(input: {
     message,
     dispatch: input.dispatch,
     cloud: input.cloud,
+    state: originChannelStateForEvent({
+      repository: input.ctx.repository,
+      pullRequestNumber: input.ctx.pullRequestNumber,
+      installationId: input.ctx.installationId,
+      deliveryId: input.ctx.deliveryId,
+      eventType: input.ctx.eventType,
+      triggeringCommentId: input.triggeringCommentId,
+    }),
   });
 }
 
@@ -654,6 +678,7 @@ export async function dispatchOriginWebhook(input: {
       dispatch,
       extra: { event: eventType },
       message: `Origin comment on ${ctx.repository.fullName}#${ctx.pullRequestNumber}`,
+      triggeringCommentId: commentId,
     });
   }
 
@@ -798,7 +823,7 @@ export function getOriginChannelOptions(
 
 export function originChannel(
   options: OriginChannelOptions = {}
-): ChannelDefinition {
+): ChannelDefinition<OriginChannelState> {
   const usesCursorAccount =
     options.cursorAccount === true || typeof options.cursorAccount === "object";
   const cursorScope =
@@ -833,8 +858,19 @@ export function originChannel(
     );
   }
 
+  const events: ChannelEventHandlers<OriginChannelState> = {
+    ...buildDefaultOriginEvents({
+      cursorAccount: channelOptions.cursorAccount,
+      app: channelOptions.app,
+      deliverReplies: channelOptions.deliverReplies,
+    }),
+    ...options.events,
+  };
+
   const definition = defineChannel({
     auth,
+    state: emptyOriginChannelState(),
+    events,
     onStart: options.onStart,
     onStop: options.onStop,
     meta: {

package/src/channels/origin/state.ts

@@ -0,0 +1,54 @@
+/**
+ * Durable per-session Origin channel state.
+ *
+ * Persisted with the turn (same mechanism as `GitHubChannelState`) so
+ * channel stream-event handlers — reply delivery in ./defaults.ts — can
+ * rebuild a repo-bound Origin handle without re-parsing the webhook.
+ */
+
+export interface OriginChannelState {
+  owner: string;
+  repo: string;
+  pullRequestNumber: number | null;
+  /** Origin app installation id from the delivery envelope, when present. */
+  installationId: string | null;
+  /** Comment id that woke the turn (comment events only). */
+  triggeringCommentId: string | null;
+  deliveryId: string | null;
+  eventType: string | null;
+}
+
+export function emptyOriginChannelState(
+  overrides: Partial<OriginChannelState> = {}
+): OriginChannelState {
+  return {
+    owner: "",
+    repo: "",
+    pullRequestNumber: null,
+    installationId: null,
+    triggeringCommentId: null,
+    deliveryId: null,
+    eventType: null,
+    ...overrides,
+  };
+}
+
+/** Build the per-turn channel state from a dispatched event's context. */
+export function originChannelStateForEvent(input: {
+  repository: { owner: string; name: string };
+  pullRequestNumber: number;
+  installationId?: string;
+  deliveryId?: string;
+  eventType: string;
+  triggeringCommentId?: string;
+}): OriginChannelState {
+  return emptyOriginChannelState({
+    owner: input.repository.owner,
+    repo: input.repository.name,
+    pullRequestNumber: input.pullRequestNumber,
+    installationId: input.installationId ?? null,
+    triggeringCommentId: input.triggeringCommentId ?? null,
+    deliveryId: input.deliveryId ?? null,
+    eventType: input.eventType,
+  });
+}