@cursor/july 0.1.80 → 0.1.82

package/src/internal/continuation-identity.ts

@@ -0,0 +1,597 @@
+/**
+ * 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`.
+ *
+ * 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
+ * and per-agent format strings are rejected.
+ */
+
+import { randomBytes } from "node:crypto";
+
+export type ConversationType = "pr" | "issue" | "thread" | "origin-pr";
+
+export const CONTINUATION_SELECTORS = [
+  "github.pr/v1",
+  "github.pr/v2",
+  "github.issue/v1",
+  "github.issue/v2",
+  "github.none/v2",
+  "slack.thread/v1",
+  "slack.thread/v2",
+  "slack.none/v2",
+  "origin.pr/v1",
+  "origin.pr/v2",
+  "origin.none/v2",
+  "none/v1",
+  "none/v2",
+] as const;
+
+export type ContinuationSelector = (typeof CONTINUATION_SELECTORS)[number];
+export type ContinuationIdentity = ContinuationSelector;
+/** Agent-root protocol version. Omit / `"v1"` keeps engine minting. */
+export type ContinuationProtocolVersion = "v1" | "v2";
+
+export type ParsedContinuation = {
+  selector: ContinuationSelector;
+  version: 1 | 2;
+  type: ConversationType | "none";
+  kind: "github" | "slack" | "origin" | "http";
+};
+
+export type ContinuationClaim = {
+  type: ConversationType;
+  resource:
+    | { owner: string; repo: string; number: number }
+    | { channelId: string; threadTs: string }
+    | { fullName: string; number: number };
+};
+
+export type MailboxContinuation = {
+  key: string;
+};
+
+export type ContinuationBuiltin = {
+  type: ConversationType;
+  kind: "github" | "slack" | "origin";
+  events: readonly string[];
+  format: string;
+};
+
+export const BUILTINS: readonly ContinuationBuiltin[] = [
+  {
+    type: "pr",
+    kind: "github",
+    events: [
+      "pull_request",
+      "issue_comment",
+      "pull_request_review",
+      "pull_request_review_comment",
+      "check_suite",
+      "check_run",
+    ],
+    format: "github-pr:{fullName}#{number}",
+  },
+  {
+    type: "issue",
+    kind: "github",
+    events: ["issues", "issue_comment"],
+    format: "github-issue:{fullName}#{number}",
+  },
+  {
+    type: "thread",
+    kind: "slack",
+    events: ["message", "app_mention"],
+    format: "{channelId}:{threadTs}",
+  },
+  {
+    type: "origin-pr",
+    kind: "origin",
+    events: [
+      "pull_request.created",
+      "pull_request.published",
+      "pull_request.head_ref.pushed",
+      "pull_request.base_ref.updated",
+      "pull_request.closed",
+      "pull_request.merged",
+      "pull_request.comment.created",
+      "pull_request.review.submitted",
+    ],
+    format: "origin-pr:{fullName}#{number}",
+  },
+] as const;
+
+export class V2EngineError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "V2EngineError";
+  }
+}
+
+const SELECTOR_FIELDS: {
+  [K in ContinuationSelector]: Omit<ParsedContinuation, "selector">;
+} = {
+  "github.pr/v1": { version: 1, type: "pr", kind: "github" },
+  "github.pr/v2": { version: 2, type: "pr", kind: "github" },
+  "github.issue/v1": { version: 1, type: "issue", kind: "github" },
+  "github.issue/v2": { version: 2, type: "issue", kind: "github" },
+  "github.none/v2": { version: 2, type: "none", kind: "github" },
+  "slack.thread/v1": { version: 1, type: "thread", kind: "slack" },
+  "slack.thread/v2": { version: 2, type: "thread", kind: "slack" },
+  "slack.none/v2": { version: 2, type: "none", kind: "slack" },
+  "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" },
+  "none/v1": { version: 1, type: "none", kind: "http" },
+  "none/v2": { version: 2, type: "none", kind: "http" },
+};
+
+export function isContinuationSelector(
+  value: string
+): value is ContinuationSelector {
+  return Object.hasOwn(SELECTOR_FIELDS, value);
+}
+
+export function defaultContinuationSelector(
+  kind?: string,
+  version: ContinuationProtocolVersion = "v1",
+  eventTypes?: readonly string[]
+): ContinuationSelector {
+  if (version !== "v2") {
+    switch (kind) {
+      case "github":
+        return "github.pr/v1";
+      case "slack":
+        return "slack.thread/v1";
+      case "origin":
+        return "origin.pr/v1";
+      default:
+        return "none/v1";
+    }
+  }
+  switch (kind) {
+    case "github":
+      return githubV2Default(eventTypes);
+    case "slack":
+      return "slack.thread/v2";
+    case "origin":
+      return originV2Default(eventTypes);
+    default:
+      return "none/v2";
+  }
+}
+
+function githubV2Default(eventTypes?: readonly string[]): ContinuationSelector {
+  const events = eventTypes ?? [];
+  const issueEvents = new Set(builtinForType("issue")?.events ?? []);
+  const prEvents = new Set(builtinForType("pr")?.events ?? []);
+  if (events.length > 0 && events.every((event) => issueEvents.has(event))) {
+    return "github.issue/v2";
+  }
+  if (events.some((event) => !prEvents.has(event))) {
+    return "github.none/v2";
+  }
+  return "github.pr/v2";
+}
+
+function originV2Default(eventTypes?: readonly string[]): ContinuationSelector {
+  const events = eventTypes ?? [];
+  const prEvents = new Set(builtinForType("origin-pr")?.events ?? []);
+  if (events.some((event) => !prEvents.has(event))) {
+    return "origin.none/v2";
+  }
+  return "origin.pr/v2";
+}
+
+export function parseContinuationSelector(
+  selector: string
+): ParsedContinuation | undefined {
+  if (!isContinuationSelector(selector)) {
+    return undefined;
+  }
+  return { selector, ...SELECTOR_FIELDS[selector] };
+}
+
+export function resolveContinuation(
+  raw?: ContinuationIdentity,
+  kind?: string
+): ParsedContinuation {
+  const selector = raw ?? defaultContinuationSelector(kind);
+  const parsed = parseContinuationSelector(selector);
+  if (parsed === undefined) {
+    throw new V2EngineError(
+      `v2: invalid continuation selector ${JSON.stringify(selector)}`
+    );
+  }
+  return parsed;
+}
+
+export function normalizeIdentity(
+  raw?: ContinuationIdentity,
+  kind?: string
+): ContinuationIdentity {
+  return resolveContinuation(raw, kind).selector;
+}
+
+export function continuationSource(
+  identity?: ContinuationIdentity,
+  kind?: string
+): "engine" | "control-plane" {
+  return resolveContinuation(identity, kind).version === 2
+    ? "control-plane"
+    : "engine";
+}
+
+export function isV2DurableContinuationKey(key: string): boolean {
+  return key.startsWith("cont:") || key.startsWith("evt:");
+}
+
+export function newEvtKey(): string {
+  return `evt:${randomBytes(16).toString("hex")}`;
+}
+
+export function builtinForType(
+  type: ConversationType
+): ContinuationBuiltin | undefined {
+  return BUILTINS.find((builtin) => builtin.type === type);
+}
+
+export function formatConversationKey(
+  type: ConversationType,
+  fields: {
+    fullName?: string;
+    number?: number;
+    channelId?: string;
+    threadTs?: string;
+  }
+): string {
+  switch (type) {
+    case "pr":
+      return `github-pr:${fields.fullName}#${fields.number}`;
+    case "issue":
+      return `github-issue:${fields.fullName}#${fields.number}`;
+    case "origin-pr":
+      return `origin-pr:${fields.fullName}#${fields.number}`;
+    case "thread":
+      return `${fields.channelId}:${fields.threadTs}`;
+  }
+}
+
+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`
+      );
+    }
+    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: {
+  kind?: string;
+  eventTypes?: readonly string[];
+  identity?: ContinuationIdentity;
+}): { ok: true } | { ok: false; error: string } {
+  if (input.identity === undefined) {
+    return { ok: true };
+  }
+  const parsed = parseContinuationSelector(input.identity);
+  if (parsed === undefined) {
+    return {
+      ok: false,
+      error: `v2: invalid continuation selector ${JSON.stringify(input.identity)}`,
+    };
+  }
+  if (parsed.version !== 2 || parsed.type === "none") {
+    return { ok: true };
+  }
+  if (
+    input.kind !== undefined &&
+    parsed.kind !== "http" &&
+    input.kind !== parsed.kind
+  ) {
+    return {
+      ok: false,
+      error: `v2: continuation ${parsed.selector} does not match channel kind ${input.kind}`,
+    };
+  }
+  const builtin = builtinForType(parsed.type);
+  if (builtin === undefined) {
+    return {
+      ok: false,
+      error: `v2: unknown continuation type ${parsed.type}`,
+    };
+  }
+  const eventTypes = input.eventTypes ?? [];
+  const allowed = new Set(builtin.events);
+  const unexpected = eventTypes.filter((event) => !allowed.has(event));
+  if (unexpected.length > 0) {
+    return {
+      ok: false,
+      error: `v2: eventTypes ${unexpected.join(", ")} are not in the ${parsed.type} membership`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * CP/pack extract. Returns a `cont:` key when the payload binds the
+ * identity type; undefined on membership miss or missing number (caller
+ * stamps `evt:` and does not join the conversation index).
+ */
+export function extractContinuation(
+  type: ConversationType,
+  eventName: string,
+  payload: unknown
+): string | undefined {
+  const builtin = builtinForType(type);
+  if (builtin === undefined) {
+    return undefined;
+  }
+  if (!builtin.events.includes(eventName)) {
+    return undefined;
+  }
+  switch (type) {
+    case "pr":
+    case "issue":
+      return extractGitHub(type, eventName, payload);
+    case "thread":
+      return extractSlack(payload);
+    case "origin-pr":
+      return extractOrigin(payload);
+  }
+}
+
+export function stampMailboxContinuation(
+  identity: ContinuationIdentity,
+  eventName: string,
+  payload: unknown,
+  kind?: string
+): MailboxContinuation {
+  const parsed = resolveContinuation(identity, kind);
+  if (parsed.version !== 2) {
+    throw new V2EngineError("v2: refusing to stamp a mailbox key for v1");
+  }
+  if (parsed.type === "none") {
+    return { key: newEvtKey() };
+  }
+  const extracted = extractContinuation(parsed.type, eventName, payload);
+  if (extracted === undefined) {
+    return { key: newEvtKey() };
+  }
+  return { key: extracted };
+}
+
+export function resolveV2Key(
+  identity: ContinuationIdentity,
+  options: {
+    claim?: ContinuationClaim;
+    continuationToken?: string;
+    mailboxContinuation?: MailboxContinuation;
+  },
+  kind?: string
+): string {
+  const parsed = resolveContinuation(identity, kind);
+  if (parsed.version !== 2) {
+    throw new V2EngineError("v2: resolveV2Key requires a /v2 selector");
+  }
+  if (options.continuationToken !== undefined) {
+    throw new V2EngineError(
+      "v2: do not pass continuationToken; use mailboxContinuation or claim"
+    );
+  }
+  if (options.claim !== undefined) {
+    if (parsed.type === "none") {
+      throw new V2EngineError("v2: type none cannot take a claim");
+    }
+    if (options.claim.type !== parsed.type) {
+      throw new V2EngineError(
+        `v2: claim type ${options.claim.type} does not match identity type ${parsed.type}`
+      );
+    }
+    return mintClaim(options.claim);
+  }
+  if (options.mailboxContinuation !== undefined) {
+    return options.mailboxContinuation.key;
+  }
+  if (parsed.type === "none") {
+    return newEvtKey();
+  }
+  throw new V2EngineError(
+    "v2: no CP key on mailbox and no claim; refusing to mint in the engine"
+  );
+}
+
+export function bindMailboxContinuationSend<
+  TSession,
+  TOptions extends { mailboxContinuation?: MailboxContinuation },
+>(
+  send: (message: string, options?: TOptions) => Promise<TSession>,
+  mailbox: MailboxContinuation | undefined
+): (message: string, options?: TOptions) => Promise<TSession> {
+  if (mailbox === undefined) {
+    return send;
+  }
+  return (message, options) =>
+    send(message, {
+      ...(options as TOptions),
+      mailboxContinuation: options?.mailboxContinuation ?? mailbox,
+    } as TOptions);
+}
+
+function extractGitHub(
+  type: "pr" | "issue",
+  eventName: string,
+  payload: unknown
+): string | undefined {
+  const record = asRecord(payload);
+  if (record === undefined) {
+    return undefined;
+  }
+  const fullName = githubFullName(record);
+  if (fullName === undefined) {
+    return undefined;
+  }
+  const bound = githubBoundConversation(eventName, record);
+  if (bound === undefined || bound.type !== type) {
+    return undefined;
+  }
+  return `cont:${formatConversationKey(type, {
+    fullName,
+    number: bound.number,
+  })}`;
+}
+
+function githubBoundConversation(
+  eventName: string,
+  payload: Record<string, unknown>
+): { type: "pr" | "issue"; number: number } | undefined {
+  switch (eventName) {
+    case "pull_request":
+    case "pull_request_review":
+    case "pull_request_review_comment":
+    case "pull_request_review_thread": {
+      const number = positiveInt(asRecord(payload.pull_request)?.number);
+      return number === undefined ? undefined : { type: "pr", number };
+    }
+    case "issues": {
+      const number = positiveInt(asRecord(payload.issue)?.number);
+      return number === undefined ? undefined : { type: "issue", number };
+    }
+    case "issue_comment": {
+      const issue = asRecord(payload.issue);
+      const number = positiveInt(issue?.number);
+      if (number === undefined) {
+        return undefined;
+      }
+      return issue?.pull_request !== undefined && issue.pull_request !== null
+        ? { type: "pr", number }
+        : { type: "issue", number };
+    }
+    case "check_suite": {
+      const number = firstPullRequestNumber(asRecord(payload.check_suite));
+      return number === undefined ? undefined : { type: "pr", number };
+    }
+    case "check_run": {
+      const checkRun = asRecord(payload.check_run);
+      const number =
+        firstPullRequestNumber(checkRun) ??
+        firstPullRequestNumber(asRecord(checkRun?.check_suite));
+      return number === undefined ? undefined : { type: "pr", number };
+    }
+    default:
+      return undefined;
+  }
+}
+
+function extractSlack(payload: unknown): string | undefined {
+  const record = asRecord(payload);
+  if (record === undefined) {
+    return undefined;
+  }
+  const channelId =
+    nonEmpty(record.channelId) ??
+    nonEmpty(record.channel_id) ??
+    nonEmpty(record.channel);
+  const threadTs =
+    nonEmpty(record.threadTs) ??
+    nonEmpty(record.thread_ts) ??
+    nonEmpty(record.ts);
+  if (channelId === undefined || threadTs === undefined) {
+    return undefined;
+  }
+  return `cont:${formatConversationKey("thread", { channelId, threadTs })}`;
+}
+
+function extractOrigin(payload: unknown): string | undefined {
+  const record = asRecord(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 fullName =
+    nonEmpty(asRecord(repository)?.fullName) ??
+    nonEmpty(asRecord(repository)?.full_name) ??
+    originFullName(repository);
+  if (number === undefined || fullName === undefined) {
+    return undefined;
+  }
+  return `cont:${formatConversationKey("origin-pr", { fullName, number })}`;
+}
+
+function githubFullName(payload: Record<string, unknown>): string | undefined {
+  const repository = asRecord(payload.repository);
+  return nonEmpty(repository?.full_name) ?? originFullName(repository);
+}
+
+function originFullName(
+  repository: Record<string, unknown> | undefined
+): string | undefined {
+  if (repository === undefined) {
+    return undefined;
+  }
+  const owner =
+    nonEmpty(repository.owner) ??
+    nonEmpty(asRecord(repository.owner)?.login) ??
+    nonEmpty(asRecord(repository.owner)?.name);
+  const name = nonEmpty(repository.name);
+  if (owner === undefined || name === undefined) {
+    return undefined;
+  }
+  return `${owner}/${name}`;
+}
+
+function firstPullRequestNumber(
+  record: Record<string, unknown> | undefined
+): number | undefined {
+  const pullRequests = record?.pull_requests;
+  if (!Array.isArray(pullRequests) || pullRequests.length === 0) {
+    return undefined;
+  }
+  return positiveInt(asRecord(pullRequests[0])?.number);
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function nonEmpty(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== ""
+    ? value.trim()
+    : undefined;
+}
+
+function positiveInt(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+    return value;
+  }
+  if (typeof value === "string" && /^[1-9]\d*$/.test(value)) {
+    return Number(value);
+  }
+  return undefined;
+}

package/src/internal/deploy-manifest.ts

@@ -31,8 +31,15 @@
 
 import { z } from "zod";
 import { isPublicEndpointPolicy } from "../channels.js";
+import type { ContinuationIdentity } from "../continuation.js";
 import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
 import type { AgentProject, AgentProjectInfo } from "../types.js";
+import {
+  applyAgentContinuationDefaults,
+  channelContinuationIdentity,
+  handshakeChannelContinuation,
+} from "./continuation-channel.js";
+import { CONTINUATION_SELECTORS } from "./continuation-identity.js";
 import { projectInfo } from "./discovery.js";
 import { packageVersion } from "./distribution.js";
 
@@ -43,6 +50,8 @@ export const DEPLOY_MANIFEST_VERSION: 1 = 1;
  * module-private (the package builds with isolated declarations); consumers
  * use {@link parseAgentDeployManifest} and the explicit interfaces below.
  */
+const continuationIdentitySchema = z.enum(CONTINUATION_SELECTORS);
+
 const agentDeployManifestV1Schema = z.object({
   manifestVersion: z.literal(DEPLOY_MANIFEST_VERSION),
   generatedAtMs: z.number().int().nonnegative(),
@@ -51,12 +60,14 @@ const agentDeployManifestV1Schema = z.object({
     egressDomains: z.array(z.string().min(1)).max(64),
     publicRoutePaths: z.array(z.string().min(1)).max(64),
     frameworkStorage: z.enum(["cursor-hosted", "other", "none"]).optional(),
+    architecture: z.enum(["v1", "v2"]).optional(),
     channels: z
       .array(
         z.object({
           id: z.string().min(1).max(128),
           kind: z.string().min(1).max(32).optional(),
           eventTypes: z.array(z.string().min(1).max(64)).max(64).optional(),
+          continuation: continuationIdentitySchema,
         })
       )
       .max(64),
@@ -70,13 +81,26 @@ export interface AgentDeployManifestDeclarations {
   publicRoutePaths: string[];
   /** Where this runtime mirrors framework-owned sessions and event chunks. */
   frameworkStorage?: "cursor-hosted" | "other" | "none";
+  /**
+   * Hosted architecture this release deploys onto. `"v2"` selects the v2
+   * control plane; omitted channel constructors inherit kind `/v2`
+   * continuation defaults. Omit or `"v1"` keeps engine minting.
+   */
+  architecture?: "v1" | "v2";
   /**
    * Mounted channels with their kinds and per-channel event capability.
    * Scope keys are installation config and are never extracted here.
-   * Continuation is opt-in: without a deterministic selector key, every
-   * inbound event starts a fresh session. Selector encoding remains open.
+   * 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.
    */
-  channels: Array<{ id: string; kind?: string; eventTypes?: string[] }>;
+  channels: Array<{
+    id: string;
+    kind?: string;
+    eventTypes?: string[];
+    continuation: ContinuationIdentity;
+  }>;
 }
 
 export interface AgentDeployManifestV1 {
@@ -101,7 +125,12 @@ export function buildAgentDeployManifest(
   project: AgentProject,
   options?: { nowMs?: number; cliVersion?: string }
 ): AgentDeployManifestV1 {
+  applyAgentContinuationDefaults(project);
   const channels = project.channels.map((channel) => {
+    const handshake = handshakeChannelContinuation(channel);
+    if (!handshake.ok) {
+      throw new Error(handshake.error);
+    }
     const kind = channel.definition.meta?.kind;
     const githubEvents = channel.definition.meta?.githubWebhookEvents;
     const originEvents = channel.definition.meta?.originWebhookEvents;
@@ -115,6 +144,7 @@ export function buildAgentDeployManifest(
       id: channel.id,
       kind,
       eventTypes,
+      continuation: channelContinuationIdentity(channel.definition),
     };
   });
 
@@ -139,6 +169,9 @@ export function buildAgentDeployManifest(
           : isCursorHostedStorage(project.storage)
             ? "cursor-hosted"
             : "other",
+      ...(project.agent.architecture === undefined
+        ? {}
+        : { architecture: project.agent.architecture }),
       channels,
     },
     info: projectInfo(project),