@cursor/july 0.1.91 → 0.1.93

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

@@ -2,6 +2,7 @@ import { z } from "zod";
 
 import { defineChannel, localDevStrict, POST } from "../../channels.js";
 import { resolveDeploymentSubscriptions } from "../../internal/cursor-deployment-relay.js";
+import { bindLocalIngressSend } from "../../internal/local-ingress.js";
 import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
 import {
   DEPLOYMENT_EVENT_TYPES,
@@ -39,6 +40,24 @@ export function getDeploymentsChannelOptions(
   return deploymentsChannelOptionsByDefinition.get(definition);
 }
 
+/**
+ * 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.
+ */
+export function deriveDeploymentEventTypes(
+  options: Pick<DeploymentsChannelOptions, "deploySourceUris" | "events">
+): string[] {
+  const events = new Set<string>();
+  for (const subscription of resolveDeploymentSubscriptions(options)) {
+    for (const event of subscription.events) {
+      events.add(event);
+    }
+  }
+  return [...events].sort();
+}
+
 /**
  * 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
@@ -49,7 +68,15 @@ export async function dispatchDeploymentEvent(input: {
   event: DeploymentEvent;
   args: ChannelHandlerArgs;
 }): Promise<Response> {
-  await input.options.onEvent(input.event, input.args);
+  await input.options.onEvent(
+    input.event,
+    bindLocalIngressSend(input.args, {
+      identity: input.options.continuation,
+      kind: DEPLOYMENTS_CHANNEL_KIND,
+      eventType: input.event.eventType,
+      payload: input.event,
+    })
+  );
   return Response.json({ ok: true });
 }
 
@@ -89,7 +116,10 @@ export function deploymentsChannel(
 
   const definition = defineChannel({
     auth: options.auth ?? [localDevStrict()],
-    meta: { kind: DEPLOYMENTS_CHANNEL_KIND },
+    meta: {
+      kind: DEPLOYMENTS_CHANNEL_KIND,
+      deploymentEventTypes: deriveDeploymentEventTypes(options),
+    },
     ...(options.onStart === undefined ? {} : { onStart: options.onStart }),
     ...(options.onStop === undefined ? {} : { onStop: options.onStop }),
     routes: [

package/src/channels/deployments/types.ts

@@ -1,3 +1,4 @@
+import type { ContinuationIdentity } from "../../continuation.js";
 import type { ChannelDefinition, ChannelHandlerArgs } from "../../types.js";
 
 /** {@link ChannelMeta.kind} value used by {@link deploymentsChannel}. */
@@ -77,4 +78,11 @@ export interface DeploymentsChannelOptions {
   auth?: ChannelDefinition["auth"];
   onStart?: ChannelDefinition["onStart"];
   onStop?: ChannelDefinition["onStop"];
+  /**
+   * Continuation selector. Omitted inherits {@link AgentConfig.architecture}:
+   * `"deployments.none/v1"` unless the agent set `architecture: "v2"` (then
+   * `"deployments.deployment/v2"`). Override with `"deployments.none/v2"`
+   * for one-shot events.
+   */
+  continuation?: ContinuationIdentity;
 }

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

@@ -480,6 +480,39 @@ function verifyWebhookSha256Signature(args: {
  * Run authored GitHub hooks and `send()`. Does not extract a v2 mailbox —
  * the local CP (or hosted verified ingress) stamps before this runs.
  */
+export type GitHubDispatchOutcome = "skip" | "send" | "task";
+
+const dispatchOutcomeByResponse = new WeakMap<
+  Response,
+  GitHubDispatchOutcome
+>();
+
+function withDispatchOutcome(
+  response: Response,
+  outcome: GitHubDispatchOutcome
+): Response {
+  dispatchOutcomeByResponse.set(response, outcome);
+  return response;
+}
+
+export function getGitHubDispatchOutcome(
+  response: Response
+): GitHubDispatchOutcome | undefined {
+  return dispatchOutcomeByResponse.get(response);
+}
+
+const PROPAGATE_BACKGROUND_ERRORS = Symbol("propagateBackgroundErrors");
+
+type GitHubHandlerArgs = ChannelHandlerArgs & {
+  [PROPAGATE_BACKGROUND_ERRORS]?: true;
+};
+
+export function withPropagatingGitHubBackgroundErrors(
+  args: ChannelHandlerArgs
+): ChannelHandlerArgs {
+  return Object.assign(args, { [PROPAGATE_BACKGROUND_ERRORS]: true as const });
+}
+
 export async function dispatchGitHubWebhook(input: {
   options: GitHubChannelOptions;
   eventName: string | null;
@@ -1589,25 +1622,25 @@ async function startTurn(input: {
     scheduleAfterAck(input.args, async () => {
       await sendTurn();
     });
-    return Response.json(
-      { ok: true, dispatched: true, mode: "turn" },
-      { status: 202 }
+    return withDispatchOutcome(
+      Response.json(
+        { ok: true, dispatched: true, mode: "turn" },
+        { status: 202 }
+      ),
+      "send"
     );
   }
 
   const session = await sendTurn();
-  return Response.json({
-    ok: true,
-    sessionId: session.id,
-    isNew: session.isNew,
-    continuationToken: session.continuationToken,
-  });
-}
-
-function reportBackgroundFailure(error: unknown): void {
-  const detail =
-    error instanceof Error ? (error.stack ?? error.message) : String(error);
-  console.error(`[github] background dispatch failed: ${detail}`);
+  return withDispatchOutcome(
+    Response.json({
+      ok: true,
+      sessionId: session.id,
+      isNew: session.isNew,
+      continuationToken: session.continuationToken,
+    }),
+    "send"
+  );
 }
 
 function scheduleAfterAck(
@@ -1617,14 +1650,25 @@ function scheduleAfterAck(
   // Defer past the current turn so the 202 can flush before work starts
   // (and so tests can assert scheduling without racing microtasks).
   args.waitUntil(
-    new Promise<void>((resolve) => {
+    new Promise<void>((resolve, reject) => {
       setImmediate(() => {
         Promise.resolve()
           .then(work)
           .then(
             () => resolve(),
             (error: unknown) => {
-              reportBackgroundFailure(error);
+              if (
+                (args as GitHubHandlerArgs)[PROPAGATE_BACKGROUND_ERRORS] ===
+                true
+              ) {
+                reject(error);
+                return;
+              }
+              const detail =
+                error instanceof Error
+                  ? (error.stack ?? error.message)
+                  : String(error);
+              console.error(`[github] background dispatch failed: ${detail}`);
               resolve();
             }
           );
@@ -1639,9 +1683,12 @@ function acknowledgeTask(
   extra: Record<string, unknown>
 ): Response {
   scheduleAfterAck(args, dispatch.task);
-  return Response.json(
-    { ok: true, dispatched: true, mode: "task", ...extra },
-    { status: 202 }
+  return withDispatchOutcome(
+    Response.json(
+      { ok: true, dispatched: true, mode: "task", ...extra },
+      { status: 202 }
+    ),
+    "task"
   );
 }
 
@@ -1649,7 +1696,10 @@ function skipped(
   reason: string,
   extra: Record<string, unknown> = {}
 ): Response {
-  return Response.json({ ok: true, skipped: true, reason, ...extra });
+  return withDispatchOutcome(
+    Response.json({ ok: true, skipped: true, reason, ...extra }),
+    "skip"
+  );
 }
 
 function formatCiMessage(

package/src/continuation.ts

@@ -13,7 +13,7 @@
  *
  * Per-channel selectors still override type (`"github.issue/v2"`,
  * `"github.none/v2"`). Other `/v2` selectors: `"slack.thread/v2"`,
- * `"origin.pr/v2"`, `"none/v2"`.
+ * `"origin.pr/v2"`, `"deployments.deployment/v2"`, `"none/v2"`.
  */
 
 export type {

package/src/internal/authored-alias-hooks.ts

@@ -3,19 +3,22 @@
  * node:module `register()` from authored-loaders.ts; runs on Node's loader
  * thread — keep this module dependency-free).
  *
- * Authored files import the framework by bare specifier. From a published
- * install those need help in two cases:
+ * Authored files import the framework by bare specifier. On compiled runs the
+ * CLI pins every public package name onto the running `dist/` entries via
+ * `directAliases` so channel-option WeakMaps stay single-copy:
  *
- * - `@anysphere/agent-serve[/subpath]` (the historical monorepo name) is not
- *   on npm, so it can never resolve from a user project. `directAliases` map
- *   it straight onto the running package's dist entries.
- * - `@cursor/july[/subpath]` (the published name) and `@cursor/agentkit
- *   [/subpath]` (the future public name) normally resolve through the
- *   project's own node_modules; `fallbackAliases` only apply when that
- *   fails (npx/global installs, projects without a local dependency), so a
- *   real install in the user's project keeps precedence.
+ * - `@anysphere/agent-serve[/subpath]` (historical monorepo name; not on npm)
+ * - `@cursor/july[/subpath]` (published name)
+ * - `@cursor/agentkit[/subpath]` (future public name)
  *
- * A third case is first-party factory agents that relative-import this
+ * Preferring a project's own `node_modules` (or tsx tsconfig paths that map
+ * onto this package's `src/`) would load a second module instance and break
+ * `getGitHubChannelOptions` / continuation stamping / hosted-delivery.
+ *
+ * `fallbackAliases` remains for tests and any future soft remap; production
+ * registration leaves it empty.
+ *
+ * A separate case is first-party factory agents that relative-import this
  * package's `src/` from a monorepo checkout. Hosted engines `npm install`
  * only the agent directory, so files under `packages/agent-serve/src` have
  * no `node_modules`. Bare specifiers from that tree (`zod`, octokit, …)

package/src/internal/authored-loaders.ts

@@ -8,12 +8,13 @@
  * ESM loader itself on startup.
  *
  * On compiled runs it additionally registers alias hooks so authored bare
- * imports of the framework resolve against the running package: the
- * historical `@anysphere/agent-serve[/x]` name always, and
- * `@cursor/july[/x]` / `@cursor/agentkit[/x]` as fallbacks when the user's
- * project has no local install (npx / global). The same hooks retry bare
- * npm specifiers from monorepo `packages/agent-serve/` source against this
- * package (hosted factory engines install only the agent directory).
+ * imports of the framework resolve against the running package's `dist/` —
+ * `@anysphere/agent-serve[/x]`, `@cursor/july[/x]`, and `@cursor/agentkit[/x]`
+ * all short-circuit to the same files the CLI loaded. Channel option WeakMaps
+ * (`getGitHubChannelOptions`, …) require that identity; letting tsx path-map
+ * or a second install win loads a duplicate module and breaks continuation /
+ * hosted-delivery lookups. Bare npm deps from monorepo `packages/agent-serve/`
+ * source still retry against this package (hosted factory engines).
  * Source runs (tsx from the monorepo) skip both — the host loader and
  * tsconfig paths already cover them.
  */
@@ -168,18 +169,21 @@ function registerFrameworkAliases(): void {
   }
   const distDir = join(packageRootDir(), "dist");
   const directAliases: Record<string, string> = {};
-  const fallbackAliases: Record<string, string> = {};
   for (const [subpath, file] of AUTHORING_ENTRY_FILES) {
     const target = pathToFileURL(join(distDir, file)).href;
     const suffix = subpath === "" ? "" : `/${subpath}`;
+    // Always pin framework imports to this process's dist. Channel factories
+    // stash options in module-local WeakMaps; a second copy (tsx tsconfig
+    // paths → src/, or a mismatched node_modules install) makes
+    // getGitHubChannelOptions miss and hosted-delivery return 422.
     directAliases[`${LEGACY_PACKAGE_NAME}${suffix}`] = target;
-    fallbackAliases[`${PACKAGE_NAME}${suffix}`] = target;
-    fallbackAliases[`${AGENTKIT_PACKAGE_NAME}${suffix}`] = target;
+    directAliases[`${PACKAGE_NAME}${suffix}`] = target;
+    directAliases[`${AGENTKIT_PACKAGE_NAME}${suffix}`] = target;
   }
   const hooksUrl = new URL("./authored-alias-hooks.js", import.meta.url);
   const data: AuthoredAliasHookData = {
     directAliases,
-    fallbackAliases,
+    fallbackAliases: {},
     // Hosted factory agents relative-import this package's src/ from a
     // monorepo checkout while npm install ran only in the agent directory.
     // Bare specifiers from that tree retry against this package.json.

package/src/internal/cli-deploy.ts

@@ -6,7 +6,7 @@
  * All intelligence is server-side (backend/server/src/agentServe/); these
  * handlers resolve parameters (credentials, team, slug, the project's
  * `hosting` / `architecture` manifest block), call the v1 agent-serve or
- * v2 agentkit management API through `deploy-client.ts`, poll status, and
+ * v2 agentsdk management API through `deploy-client.ts`, poll status, and
  * render.
  */
 
@@ -658,7 +658,7 @@ async function deployOne(
     if (!ctx.json) {
       ctx.err("  architecture: v2\n");
     }
-    return deployOneAgentkit(ctx, extras, {
+    return deployOneAgentsdk(ctx, extras, {
       slug,
       gitRepoUrl,
       gitRef,
@@ -782,7 +782,7 @@ async function deployOne(
  * poll the matching GET. The v2 accept path starts freeze bake; it does
  * not mint an engine alias or alias token.
  */
-async function deployOneAgentkit(
+async function deployOneAgentsdk(
   ctx: DeployCliContext,
   extras: { jsonCollect?: unknown[] } | undefined,
   args: {
@@ -1189,10 +1189,10 @@ export async function cmdStop(
     return ctx;
   }
   // Stop takes only a slug, so there is no manifest to dispatch on (unlike
-  // deploy). The v2 agentkit control plane goes first: v1 endpoints refuse
+  // deploy). The v2 agentsdk control plane goes first: v1 endpoints refuse
   // `architecture: "v2"` slugs with a 409 rather than a 404, so v1-first
   // could not fall through. A v2 404 (including an older backend without
-  // the agentkit mount) falls back to the v1 stop.
+  // the `/internal/agentkit` mount) falls back to the v1 stop.
   let architecture: "v1" | "v2" = "v2";
   let accepted: StopAccepted | AgentkitStopAccepted;
   try {

package/src/internal/continuation-channel.ts

@@ -1,9 +1,11 @@
+import { getDeploymentsChannelOptions } from "../channels/deployments/deployments-channel.js";
 import { getGitHubChannelOptions } from "../channels/github/github-channel.js";
 import { getOriginChannelOptions } from "../channels/origin/origin-channel.js";
 import { getSlackChannelOptions } from "../channels/slack/slack-channel.js";
 import type {
   AgentArchitecture,
   ChannelDefinition,
+  ChannelMeta,
   HttpChannelDefinition,
 } from "../types.js";
 import {
@@ -14,23 +16,48 @@ import {
   normalizeIdentity,
 } from "./continuation-identity.js";
 
+type ContinuationChannelOptions = {
+  continuation?: ContinuationIdentity;
+};
+
+const CONTINUATION_CHANNEL_PACKS: ReadonlyArray<{
+  kind: "github" | "slack" | "origin" | "deployments";
+  getOptions: (definition: object) => ContinuationChannelOptions | undefined;
+  usesDeclaredEvents: boolean;
+}> = [
+  {
+    kind: "github",
+    getOptions: getGitHubChannelOptions,
+    usesDeclaredEvents: true,
+  },
+  {
+    kind: "slack",
+    getOptions: getSlackChannelOptions,
+    usesDeclaredEvents: false,
+  },
+  {
+    kind: "origin",
+    getOptions: getOriginChannelOptions,
+    usesDeclaredEvents: true,
+  },
+  {
+    kind: "deployments",
+    getOptions: getDeploymentsChannelOptions,
+    usesDeclaredEvents: true,
+  },
+];
+
 export function channelContinuationIdentity(
   definition: object | undefined
 ): ContinuationIdentity {
   if (definition === undefined) {
     return defaultContinuationSelector();
   }
-  const github = getGitHubChannelOptions(definition);
-  if (github !== undefined) {
-    return normalizeIdentity(github.continuation, "github");
-  }
-  const slack = getSlackChannelOptions(definition);
-  if (slack !== undefined) {
-    return normalizeIdentity(slack.continuation, "slack");
-  }
-  const origin = getOriginChannelOptions(definition);
-  if (origin !== undefined) {
-    return normalizeIdentity(origin.continuation, "origin");
+  for (const pack of CONTINUATION_CHANNEL_PACKS) {
+    const options = pack.getOptions(definition);
+    if (options !== undefined) {
+      return normalizeIdentity(options.continuation, pack.kind);
+    }
   }
   return defaultContinuationSelector();
 }
@@ -44,8 +71,9 @@ export function httpContinuationIdentity(
 /**
  * Stamp `/v2` continuation defaults onto channel constructors that omitted
  * `continuation` when the agent deploys onto v2 architecture. GitHub/Origin
- * type (`pr` / `issue` / `none`) follows declared webhook events. Explicit
- * per-channel selectors are left alone. Idempotent.
+ * type (`pr` / `issue` / `none`) follows declared webhook events.
+ * Deployments default to `deployments.deployment/v2`. Explicit per-channel
+ * selectors are left alone. Idempotent.
  */
 export function applyAgentContinuationDefaults(project: {
   agent: { architecture?: AgentArchitecture };
@@ -70,42 +98,34 @@ function stampOmittedChannelContinuation(
   definition: object,
   version: ContinuationProtocolVersion
 ): void {
-  const events = declaredChannelEventTypes(definition);
-  const github = getGitHubChannelOptions(definition);
-  if (github !== undefined) {
-    if (github.continuation === undefined) {
-      github.continuation = defaultContinuationSelector(
-        "github",
-        version,
-        events
-      );
+  const events = channelDeclaredEventTypes(
+    (definition as ChannelDefinition).meta
+  );
+  for (const pack of CONTINUATION_CHANNEL_PACKS) {
+    const options = pack.getOptions(definition);
+    if (options === undefined) {
+      continue;
     }
-    return;
-  }
-  const slack = getSlackChannelOptions(definition);
-  if (slack !== undefined) {
-    if (slack.continuation === undefined) {
-      slack.continuation = defaultContinuationSelector("slack", version);
-    }
-    return;
-  }
-  const origin = getOriginChannelOptions(definition);
-  if (origin !== undefined) {
-    if (origin.continuation === undefined) {
-      origin.continuation = defaultContinuationSelector(
-        "origin",
+    if (options.continuation === undefined) {
+      options.continuation = defaultContinuationSelector(
+        pack.kind,
         version,
-        events
+        pack.usesDeclaredEvents ? events : undefined
       );
     }
+    return;
   }
 }
 
-function declaredChannelEventTypes(
-  definition: object
+/** Kind-specific event lists on `ChannelMeta`; a definition sets at most one. */
+export function channelDeclaredEventTypes(
+  meta: ChannelMeta | undefined
 ): readonly string[] | undefined {
-  const meta = (definition as ChannelDefinition).meta;
-  return meta?.githubWebhookEvents ?? meta?.originWebhookEvents;
+  return (
+    meta?.githubWebhookEvents ??
+    meta?.originWebhookEvents ??
+    meta?.deploymentEventTypes
+  );
 }
 
 export function handshakeChannelContinuation(input: {
@@ -113,10 +133,7 @@ export function handshakeChannelContinuation(input: {
   definition: ChannelDefinition;
 }): { ok: true } | { ok: false; error: string } {
   const kind = input.definition.meta?.kind;
-  const eventTypes = [
-    ...(input.definition.meta?.githubWebhookEvents ?? []),
-    ...(input.definition.meta?.originWebhookEvents ?? []),
-  ];
+  const eventTypes = channelDeclaredEventTypes(input.definition.meta);
   const result = handshakeContinuation({
     kind,
     eventTypes,