@cursor/july 0.1.92 → 0.1.93

package/src/internal/continuation-identity.ts

@@ -2,20 +2,27 @@
  * Continuation identity is a closed selector string. Omitted `continuation`
  * on a channel constructor stays `/v1` (engine pack minting) so existing
  * agents do not change: `githubChannel()` → `github.pr/v1`, `slackChannel()`
- * → `slack.thread/v1`, `originChannel()` → `origin.pr/v1`, `httpChannel()`
- * → `none/v1`.
+ * → `slack.thread/v1`, `originChannel()` → `origin.pr/v1`,
+ * `deploymentsChannel()` → `deployments.none/v1`, `httpChannel()` →
+ * `none/v1`.
  *
  * Opt the whole agent into the v2 control plane with
  * `defineAgent({ architecture: "v2" })`. That stamps `/v2` defaults from
  * the channel kind and declared events (`github.pr/v2`, `github.issue/v2`,
- * `github.none/v2`, `slack.thread/v2`, …) onto every channel that omitted
- * a selector. An explicit per-channel selector still overrides. JSONPath
+ * `github.none/v2`, `slack.thread/v2`, `origin.pr/v2`,
+ * `deployments.deployment/v2`, …) onto every channel that omitted a
+ * selector. An explicit per-channel selector still overrides. JSONPath
  * and per-agent format strings are rejected.
  */
 
 import { randomBytes } from "node:crypto";
 
-export type ConversationType = "pr" | "issue" | "thread" | "origin-pr";
+export type ConversationType =
+  | "pr"
+  | "issue"
+  | "thread"
+  | "origin-pr"
+  | "deployment";
 
 export const CONTINUATION_SELECTORS = [
   "github.pr/v1",
@@ -29,6 +36,9 @@ export const CONTINUATION_SELECTORS = [
   "origin.pr/v1",
   "origin.pr/v2",
   "origin.none/v2",
+  "deployments.none/v1",
+  "deployments.none/v2",
+  "deployments.deployment/v2",
   "none/v1",
   "none/v2",
 ] as const;
@@ -42,7 +52,7 @@ export type ParsedContinuation = {
   selector: ContinuationSelector;
   version: 1 | 2;
   type: ConversationType | "none";
-  kind: "github" | "slack" | "origin" | "http";
+  kind: "github" | "slack" | "origin" | "deployments" | "http";
 };
 
 export type ContinuationClaim = {
@@ -50,7 +60,8 @@ export type ContinuationClaim = {
   resource:
     | { owner: string; repo: string; number: number }
     | { channelId: string; threadTs: string }
-    | { fullName: string; number: number };
+    | { fullName: string; number: number }
+    | { deploymentId: string };
 };
 
 export type MailboxContinuation = {
@@ -59,7 +70,7 @@ export type MailboxContinuation = {
 
 export type ContinuationBuiltin = {
   type: ConversationType;
-  kind: "github" | "slack" | "origin";
+  kind: "github" | "slack" | "origin" | "deployments";
   events: readonly string[];
   format: string;
 };
@@ -105,6 +116,12 @@ export const BUILTINS: readonly ContinuationBuiltin[] = [
     ],
     format: "origin-pr:{fullName}#{number}",
   },
+  {
+    type: "deployment",
+    kind: "deployments",
+    events: ["deployment.created", "deployment.succeeded"],
+    format: "deployments:{deploymentId}",
+  },
 ] as const;
 
 export class V2EngineError extends Error {
@@ -128,6 +145,13 @@ const SELECTOR_FIELDS: {
   "origin.pr/v1": { version: 1, type: "origin-pr", kind: "origin" },
   "origin.pr/v2": { version: 2, type: "origin-pr", kind: "origin" },
   "origin.none/v2": { version: 2, type: "none", kind: "origin" },
+  "deployments.none/v1": { version: 1, type: "none", kind: "deployments" },
+  "deployments.none/v2": { version: 2, type: "none", kind: "deployments" },
+  "deployments.deployment/v2": {
+    version: 2,
+    type: "deployment",
+    kind: "deployments",
+  },
   "none/v1": { version: 1, type: "none", kind: "http" },
   "none/v2": { version: 2, type: "none", kind: "http" },
 };
@@ -151,6 +175,8 @@ export function defaultContinuationSelector(
         return "slack.thread/v1";
       case "origin":
         return "origin.pr/v1";
+      case "deployments":
+        return "deployments.none/v1";
       default:
         return "none/v1";
     }
@@ -162,6 +188,8 @@ export function defaultContinuationSelector(
       return "slack.thread/v2";
     case "origin":
       return originV2Default(eventTypes);
+    case "deployments":
+      return deploymentsV2Default(eventTypes);
     default:
       return "none/v2";
   }
@@ -189,6 +217,17 @@ function originV2Default(eventTypes?: readonly string[]): ContinuationSelector {
   return "origin.pr/v2";
 }
 
+function deploymentsV2Default(
+  eventTypes?: readonly string[]
+): ContinuationSelector {
+  const events = eventTypes ?? [];
+  const deploymentEvents = new Set(builtinForType("deployment")?.events ?? []);
+  if (events.some((event) => !deploymentEvents.has(event))) {
+    return "deployments.none/v2";
+  }
+  return "deployments.deployment/v2";
+}
+
 export function parseContinuationSelector(
   selector: string
 ): ParsedContinuation | undefined {
@@ -249,6 +288,7 @@ export function formatConversationKey(
     number?: number;
     channelId?: string;
     threadTs?: string;
+    deploymentId?: string;
   }
 ): string {
   switch (type) {
@@ -260,30 +300,51 @@ export function formatConversationKey(
       return `origin-pr:${fields.fullName}#${fields.number}`;
     case "thread":
       return `${fields.channelId}:${fields.threadTs}`;
+    case "deployment":
+      return `deployments:${fields.deploymentId}`;
   }
 }
 
 export function mintClaim(claim: ContinuationClaim): string {
-  const resource = claim.resource;
-  if ("channelId" in resource && "threadTs" in resource) {
-    if (claim.type !== "thread") {
-      throw new V2EngineError(
-        `v2: claim type ${claim.type} does not match thread resource`
-      );
+  switch (claim.type) {
+    case "thread": {
+      const resource = claim.resource;
+      if (!("channelId" in resource && "threadTs" in resource)) {
+        throw new V2EngineError(
+          "v2: thread claim requires channelId and threadTs"
+        );
+      }
+      return `cont:${formatConversationKey("thread", resource)}`;
+    }
+    case "deployment": {
+      const resource = claim.resource;
+      if (!("deploymentId" in resource)) {
+        throw new V2EngineError("v2: deployment claim requires deploymentId");
+      }
+      return `cont:${formatConversationKey("deployment", resource)}`;
+    }
+    case "pr":
+    case "issue":
+    case "origin-pr": {
+      const resource = claim.resource;
+      const fullName =
+        "fullName" in resource
+          ? resource.fullName
+          : "owner" in resource
+            ? `${resource.owner}/${resource.repo}`
+            : undefined;
+      const number = "number" in resource ? resource.number : undefined;
+      if (fullName === undefined || number === undefined) {
+        throw new V2EngineError(
+          `v2: ${claim.type} claim requires repository and number`
+        );
+      }
+      return `cont:${formatConversationKey(claim.type, {
+        fullName,
+        number,
+      })}`;
     }
-    return `cont:${formatConversationKey("thread", resource)}`;
-  }
-  const fullName =
-    "fullName" in resource
-      ? resource.fullName
-      : `${resource.owner}/${resource.repo}`;
-  if (claim.type === "thread") {
-    throw new V2EngineError("v2: thread claim requires channelId and threadTs");
   }
-  return `cont:${formatConversationKey(claim.type, {
-    fullName,
-    number: resource.number,
-  })}`;
 }
 
 export function handshakeContinuation(input: {
@@ -358,18 +419,16 @@ export function extractContinuation(
       return extractSlack(payload);
     case "origin-pr":
       return extractOrigin(payload);
+    case "deployment":
+      return extractDeployment(payload);
   }
 }
 
 /**
- * Extract primitive used by the control plane (hosted
- * `routeVerifiedIngressContinuation` and local
- * `routeLocalIngressContinuation`). Channel adapters must not call this.
- */
-/**
- * Extract primitive used by the control plane (hosted
- * `routeVerifiedIngressContinuation` and local
- * `routeLocalIngressContinuation`). Channel adapters must not call this.
+ * CP mailbox stamp. Hosted `routeVerifiedIngressContinuation` and local
+ * `routeLocalIngressContinuation` call this; channel adapters must not.
+ * Membership miss or missing identity fields stamp `evt:` instead of
+ * joining the conversation index.
  */
 export function stampMailboxContinuation(
   identity: ContinuationIdentity,
@@ -533,15 +592,13 @@ function extractSlack(payload: unknown): string | undefined {
 }
 
 function extractOrigin(payload: unknown): string | undefined {
-  const record = asRecord(payload);
+  const record = originExtractRecord(payload);
   if (record === undefined) {
     return undefined;
   }
   const inner = asRecord(record.pullRequest) ?? asRecord(record.pull_request);
   const number = positiveInt(inner?.number);
-  const repository =
-    asRecord(record.repository) ??
-    asRecord(asRecord(asRecord(record.event)?.payload)?.repository);
+  const repository = asRecord(record.repository) ?? asRecord(inner?.repository);
   const fullName =
     nonEmpty(asRecord(repository)?.fullName) ??
     nonEmpty(asRecord(repository)?.full_name) ??
@@ -552,6 +609,33 @@ function extractOrigin(payload: unknown): string | undefined {
   return `cont:${formatConversationKey("origin-pr", { fullName, number })}`;
 }
 
+/**
+ * Mailbox stores the Origin delivery envelope; local/hosted CP extract
+ * also accepts the compact `{ pullRequest, repository }` shape.
+ */
+function originExtractRecord(
+  payload: unknown
+): Record<string, unknown> | undefined {
+  const record = asRecord(payload);
+  if (record === undefined) {
+    return undefined;
+  }
+  const nested = asRecord(asRecord(record.event)?.payload);
+  if (nested !== undefined && asRecord(record.pullRequest) === undefined) {
+    return nested;
+  }
+  return record;
+}
+
+function extractDeployment(payload: unknown): string | undefined {
+  const record = asRecord(payload);
+  const deploymentId = nonEmpty(record?.deploymentId);
+  if (deploymentId === undefined) {
+    return undefined;
+  }
+  return `cont:${formatConversationKey("deployment", { deploymentId })}`;
+}
+
 function githubFullName(payload: Record<string, unknown>): string | undefined {
   const repository = asRecord(payload.repository);
   return nonEmpty(repository?.full_name) ?? originFullName(repository);
@@ -564,6 +648,7 @@ function originFullName(
     return undefined;
   }
   const owner =
+    nonEmpty(asRecord(repository.owner)?.slug) ??
     nonEmpty(repository.owner) ??
     nonEmpty(asRecord(repository.owner)?.login) ??
     nonEmpty(asRecord(repository.owner)?.name);

package/src/internal/deploy-manifest.ts

@@ -37,6 +37,7 @@ import type { AgentProject, AgentProjectInfo } from "../types.js";
 import {
   applyAgentContinuationDefaults,
   channelContinuationIdentity,
+  channelDeclaredEventTypes,
   handshakeChannelContinuation,
 } from "./continuation-channel.js";
 import { CONTINUATION_SELECTORS } from "./continuation-identity.js";
@@ -95,8 +96,8 @@ export interface AgentDeployManifestDeclarations {
    * Scope keys are installation config and are never extracted here.
    * Omitted channel `continuation` is `/v1` (engine minting) unless the
    * agent set `architecture: "v2"`, which stamps kind `/v2` defaults
-   * (`github.pr/v2`, `slack.thread/v2`, `origin.pr/v2`). Per-channel
-   * selectors still override type.
+   * (`github.pr/v2`, `slack.thread/v2`, `origin.pr/v2`,
+   * `deployments.deployment/v2`). Per-channel selectors still override type.
    */
   channels: Array<{
     id: string;
@@ -141,14 +142,9 @@ export function buildAgentDeployManifest(
       throw new Error(handshake.error);
     }
     const kind = channel.definition.meta?.kind;
-    const githubEvents = channel.definition.meta?.githubWebhookEvents;
-    const originEvents = channel.definition.meta?.originWebhookEvents;
+    const declaredEvents = channelDeclaredEventTypes(channel.definition.meta);
     const eventTypes =
-      githubEvents !== undefined
-        ? [...githubEvents].sort()
-        : originEvents !== undefined
-          ? [...originEvents].sort()
-          : undefined;
+      declaredEvents === undefined ? undefined : [...declaredEvents].sort();
     return {
       id: channel.id,
       kind,

package/src/internal/discovery.ts

@@ -2311,6 +2311,9 @@ export function projectInfo(project: AgentProject): AgentProjectInfo {
         if (meta?.originWebhookEvents !== undefined) {
           info.originWebhookEvents = meta.originWebhookEvents;
         }
+        if (meta?.deploymentEventTypes !== undefined) {
+          info.deploymentEventTypes = meta.deploymentEventTypes;
+        }
         if (meta?.slackChannelPosts !== undefined) {
           info.slackChannelPosts = meta.slackChannelPosts;
         }

package/src/internal/distribution.ts

@@ -21,8 +21,9 @@ export const PACKAGE_NAME = "@cursor/july";
 export const LEGACY_PACKAGE_NAME = "@anysphere/agent-serve";
 
 /**
- * Future public package name; aliased with the same fallback-only semantics
- * as PACKAGE_NAME so the eventual rename keeps authored imports working.
+ * Future public package name; aliased with the same direct-to-running-dist
+ * semantics as PACKAGE_NAME so the eventual rename keeps authored imports
+ * on the CLI's module identity.
  */
 export const AGENTKIT_PACKAGE_NAME = "@cursor/agentkit";
 
@@ -117,7 +118,7 @@ export function formatCliVersion(options?: { json?: boolean }): string {
  * runtime mirror of the package `exports` map (the source of truth;
  * `authored-loaders.test.ts` asserts they stay identical). The alias hooks
  * derive `@anysphere/agent-serve[/x]`, `@cursor/july[/x]`, and
- * `@cursor/agentkit[/x]` targets from this list.
+ * `@cursor/agentkit[/x]` direct targets from this list.
  */
 export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   readonly [subpath: string, file: string]

package/src/internal/hosted-delivery-protocol.ts

@@ -0,0 +1,114 @@
+export const HOSTED_DELIVERY_PROTOCOL_VERSION = 2;
+export const HOSTED_DELIVERY_HEADER = "x-agent-sdk-hosted-delivery";
+export const HOSTED_ADMISSION_PATH = "/v1/internal/hosted-admission";
+export const HOSTED_EXECUTION_PATH = "/v1/internal/hosted-execution";
+
+export type HostedAdmission = {
+  v: 2;
+  channelId: string;
+  channelKind: "github";
+  eventType: string;
+  deliveryId: string;
+  sessionMode: "event" | "continuation";
+  mailboxContinuationKey: string;
+  payload: unknown;
+};
+
+export type HostedAdmissionOutcome =
+  | { ok: true; v: 2; outcome: "skip" | "task" }
+  | { ok: true; v: 2; outcome: "send"; admissionToken: string };
+
+export type HostedExecution = {
+  v: 2;
+  admissionToken: string;
+  sessionPublicId: string;
+};
+
+export type HostedExecutionOutcome = {
+  ok: true;
+  v: 2;
+  outcome: "send";
+};
+
+const DELIVERY_KEYS = new Set([
+  "v",
+  "channelId",
+  "channelKind",
+  "eventType",
+  "deliveryId",
+  "sessionMode",
+  "mailboxContinuationKey",
+  "payload",
+]);
+const EXECUTION_KEYS = new Set(["v", "admissionToken", "sessionPublicId"]);
+
+function boundedString(value: unknown, max: number): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= max;
+}
+
+export function parseHostedAdmission(
+  value: unknown
+): HostedAdmission | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const body = value as Record<string, unknown>;
+  if (
+    Object.keys(body).some((key) => !DELIVERY_KEYS.has(key)) ||
+    !Object.hasOwn(body, "payload") ||
+    body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION ||
+    !boundedString(body.channelId, 128) ||
+    body.channelKind !== "github" ||
+    !boundedString(body.eventType, 128) ||
+    !boundedString(body.deliveryId, 256) ||
+    (body.sessionMode !== "event" && body.sessionMode !== "continuation") ||
+    !boundedString(body.mailboxContinuationKey, 512)
+  ) {
+    return undefined;
+  }
+  const prefix = body.sessionMode === "event" ? "evt:" : "cont:";
+  return body.mailboxContinuationKey.startsWith(prefix)
+    ? (body as HostedAdmission)
+    : undefined;
+}
+
+export function parseHostedExecution(
+  value: unknown
+): HostedExecution | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const body = value as Record<string, unknown>;
+  if (
+    Object.keys(body).some((key) => !EXECUTION_KEYS.has(key)) ||
+    body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION ||
+    !boundedString(body.admissionToken, 128) ||
+    typeof body.sessionPublicId !== "string" ||
+    !/^ses_[a-f0-9]{24}$/.test(body.sessionPublicId)
+  ) {
+    return undefined;
+  }
+  return body as HostedExecution;
+}
+
+export function parseHostedAdmissionOutcome(
+  value: unknown
+): HostedAdmissionOutcome | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const body = value as Record<string, unknown>;
+  if (
+    body.ok !== true ||
+    body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION ||
+    (body.outcome !== "skip" &&
+      body.outcome !== "send" &&
+      body.outcome !== "task")
+  ) {
+    return undefined;
+  }
+  if (body.outcome === "send" && !boundedString(body.admissionToken, 128)) {
+    return undefined;
+  }
+  return body as HostedAdmissionOutcome;
+}