@cursor/july 0.1.80 → 0.1.82

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

@@ -6,6 +6,12 @@ import {
   loopbackOnly,
   POST,
 } from "../../channels.js";
+import {
+  bindMailboxContinuationSend,
+  continuationSource,
+  normalizeIdentity,
+  stampMailboxContinuation,
+} from "../../internal/continuation-identity.js";
 import { isDevMode } from "../../internal/dev-mode.js";
 import type {
   AgentCloudOptions,
@@ -443,15 +449,19 @@ function acknowledgeTask(
 }
 
 async function startTurn(input: {
+  options: OriginChannelOptions;
   args: ChannelHandlerArgs;
   ctx: OriginEventContext;
   message: string;
   dispatch: OriginTurnDispatch;
   cloud?: AgentCloudOptions;
 }): Promise<Response> {
+  const source = continuationSource(input.options.continuation, "origin");
   const session = await input.args.send(input.message, {
     auth: input.dispatch.auth,
-    continuationToken: originContinuationKey(input.ctx),
+    ...(source === "engine"
+      ? { continuationToken: originContinuationKey(input.ctx) }
+      : {}),
     title: input.dispatch.title ?? defaultOriginTitle(input.ctx),
     ...(input.cloud === undefined ? {} : { cloud: input.cloud }),
   });
@@ -489,6 +499,7 @@ async function resolveCloudOptions(
 }
 
 async function applyDispatch(input: {
+  options: OriginChannelOptions;
   args: ChannelHandlerArgs;
   ctx: OriginEventContext;
   dispatch: OriginDispatch | null;
@@ -507,6 +518,7 @@ async function applyDispatch(input: {
     ...(input.dispatch.context ?? []),
   ].join("\n");
   return startTurn({
+    options: input.options,
     args: input.args,
     ctx: input.ctx,
     message,
@@ -533,9 +545,21 @@ export async function dispatchOriginWebhook(input: {
       { status: 400 }
     );
   }
+  const identity = normalizeIdentity(input.options.continuation, "origin");
+  let args = input.args;
+  if (continuationSource(identity, "origin") === "control-plane") {
+    const mailbox = stampMailboxContinuation(identity, eventType, {
+      pullRequest: { number: parsed.ctx.pullRequestNumber },
+      repository: { fullName: parsed.ctx.repository.fullName },
+    });
+    args = {
+      ...input.args,
+      send: bindMailboxContinuationSend(input.args.send, mailbox),
+    };
+  }
   const ctx = enrichEventContext({
     ctx: parsed.ctx,
-    args: input.args,
+    args,
     options: input.options,
   });
   const { pullRequest, payload } = parsed;
@@ -568,7 +592,8 @@ export async function dispatchOriginWebhook(input: {
     };
     const dispatch = await input.options.onComment(ctx, comment);
     return applyDispatch({
-      args: input.args,
+      options: input.options,
+      args,
       ctx,
       dispatch,
       extra: { event: eventType },
@@ -588,7 +613,8 @@ export async function dispatchOriginWebhook(input: {
     };
     const dispatch = await input.options.onReview(ctx, review);
     return applyDispatch({
-      args: input.args,
+      options: input.options,
+      args,
       ctx,
       dispatch,
       extra: { event: eventType },
@@ -607,7 +633,8 @@ export async function dispatchOriginWebhook(input: {
       pullRequest
     );
     return applyDispatch({
-      args: input.args,
+      options: input.options,
+      args,
       ctx,
       dispatch,
       extra: { event: eventType },
@@ -622,7 +649,8 @@ export async function dispatchOriginWebhook(input: {
       payload,
     });
     return applyDispatch({
-      args: input.args,
+      options: input.options,
+      args,
       ctx,
       dispatch,
       extra: { event: eventType },
@@ -725,13 +753,23 @@ export function originChannel(
           : localDevStrict())(request, info),
   ];
 
+  const channelOptions: OriginChannelOptions = {
+    ...options,
+  };
+  if (channelOptions.continuation !== undefined) {
+    channelOptions.continuation = normalizeIdentity(
+      channelOptions.continuation,
+      "origin"
+    );
+  }
+
   const definition = defineChannel({
     auth,
     onStart: options.onStart,
     onStop: options.onStop,
     meta: {
       kind: ORIGIN_CHANNEL_KIND,
-      originWebhookEvents: deriveOriginWebhookEvents(options),
+      originWebhookEvents: deriveOriginWebhookEvents(channelOptions),
     },
     routes: [
       POST(routePath, {
@@ -739,17 +777,17 @@ export function originChannel(
         description: "Origin webhook ingress",
         handler: async (request, args) =>
           handleOriginWebhookRequest({
-            options,
+            options: channelOptions,
             request,
             args,
           }),
       }),
     ],
   });
-  originChannelOptionsByDefinition.set(definition, options);
+  originChannelOptionsByDefinition.set(definition, channelOptions);
   if (usesCursorAccount) {
     registerOriginCursorAccountRuntime(definition, {
-      options,
+      options: channelOptions,
       scope: cursorScope,
     });
   }

package/src/channels/origin/types.ts

@@ -1,3 +1,4 @@
+import type { ContinuationIdentity } from "../../continuation.js";
 import type {
   AgentCloudOptions,
   ArtifactsApi,
@@ -195,6 +196,12 @@ export interface OriginChannelOptions {
    * `meta.originWebhookEvents`). Defaults to the set derived from hooks.
    */
   webhookEvents?: readonly string[];
+  /**
+   * Continuation selector. Omitted inherits {@link AgentConfig.architecture}:
+   * `"origin.pr/v1"` unless the agent set `architecture: "v2"` (then
+   * `"origin.pr/v2"`). Override with `"origin.none/v2"` for one-shot events.
+   */
+  continuation?: ContinuationIdentity;
   /**
    * Decide whether an inbound pull-request event starts a turn. Return
    * `{ auth: defaultOriginAuth(ctx) }` to dispatch, `null` to ignore.

package/src/channels/slack/cursor-account.ts

@@ -196,6 +196,7 @@ export async function dispatchCursorSlackEnvelope(args: {
     ...(args.interruptContinuation === undefined
       ? {}
       : { interruptContinuation: args.interruptContinuation }),
+    continuation: runtime.options.continuation,
     ...(envelope.eventId === undefined ? {} : { eventId: envelope.eventId }),
   });
 }

package/src/channels/slack/dispatch.ts

@@ -2,6 +2,13 @@
  * Shared inbound dispatch for Slack Events API bodies and Socket Mode.
  */
 
+import {
+  type ContinuationIdentity,
+  continuationSource,
+  type MailboxContinuation,
+  normalizeIdentity,
+  stampMailboxContinuation,
+} from "../../internal/continuation-identity.js";
 import type {
   ArtifactsApi,
   HostContext,
@@ -121,6 +128,7 @@ export function emptySlackChannelState(
 
 export interface SlackInboundDispatchDeps extends SlackContinuationProbes {
   send: SendMessageFn;
+  continuation?: ContinuationIdentity;
   waitUntil: (promise: Promise<unknown>) => void;
   onAppMention: SlackMessageHandler;
   onDirectMessage: SlackMessageHandler;
@@ -180,6 +188,35 @@ function triggeringMergeMessage(
   };
 }
 
+function continuationArg(identity: ContinuationIdentity | undefined): {
+  continuation?: ContinuationIdentity;
+} {
+  return identity === undefined ? {} : { continuation: identity };
+}
+
+function slackSessionContinuation(
+  identity: ContinuationIdentity | undefined,
+  channelId: string,
+  threadTs: string
+): {
+  probeKey: string;
+  sendPatch:
+    | { continuationToken: string }
+    | { mailboxContinuation: MailboxContinuation };
+} {
+  if (continuationSource(identity, "slack") === "engine") {
+    const key = slackContinuationKey(channelId, threadTs);
+    return { probeKey: key, sendPatch: { continuationToken: key } };
+  }
+  const mailbox = stampMailboxContinuation(
+    normalizeIdentity(identity, "slack"),
+    "message",
+    { channelId, threadTs },
+    "slack"
+  );
+  return { probeKey: mailbox.key, sendPatch: { mailboxContinuation: mailbox } };
+}
+
 export async function dispatchInboundMessage(args: {
   kind:
     | "app_mention"
@@ -210,6 +247,7 @@ export async function dispatchInboundMessage(args: {
    */
   cursorAgentName?: string;
   blockExternals?: boolean;
+  continuation?: ContinuationIdentity;
 }): Promise<void> {
   const { message, kind } = args;
   const log = args.log ?? defaultSlackLog;
@@ -265,7 +303,8 @@ export async function dispatchInboundMessage(args: {
     }
   }
 
-  const continuation = slackContinuationKey(
+  const { probeKey: continuation, sendPatch } = slackSessionContinuation(
+    args.continuation,
     message.channelId,
     message.threadTs
   );
@@ -454,7 +493,7 @@ export async function dispatchInboundMessage(args: {
 
   const sendOptions = {
     auth: decision.auth,
-    continuationToken: continuation,
+    ...sendPatch,
     admission: "coalesce" as const,
     coalesceSourceTs: message.ts,
     state: emptySlackChannelState({
@@ -617,6 +656,7 @@ export function dispatchInboundFromEventBody(
         cursorAgentName: deps.cursorAgentName,
         followUpStatus: deps.followUpStatus,
         blockExternals: deps.blockExternals,
+        ...continuationArg(deps.continuation),
         ...(deps.hasContinuationSession === undefined
           ? {}
           : { hasContinuationSession: deps.hasContinuationSession }),
@@ -660,6 +700,7 @@ export function dispatchInboundFromEventBody(
         cursorAgentName: deps.cursorAgentName,
         followUpStatus: deps.followUpStatus,
         blockExternals: deps.blockExternals,
+        ...continuationArg(deps.continuation),
         ...(deps.hasContinuationSession === undefined
           ? {}
           : { hasContinuationSession: deps.hasContinuationSession }),
@@ -697,6 +738,7 @@ export function dispatchInboundFromEventBody(
         cursorAgentName: deps.cursorAgentName,
         followUpStatus: deps.followUpStatus,
         blockExternals: deps.blockExternals,
+        ...continuationArg(deps.continuation),
         ...(deps.hasContinuationSession === undefined
           ? {}
           : { hasContinuationSession: deps.hasContinuationSession }),

package/src/channels/slack/interactive.ts

@@ -7,6 +7,7 @@
  * `slackChannel({ onBlockAction })`).
  */
 
+import type { ContinuationIdentity } from "../../internal/continuation-identity.js";
 import type {
   ApprovalDecision,
   ArtifactsApi,
@@ -298,6 +299,7 @@ export async function resolveBlockActionCard(args: {
 export interface SlackBlockActionDispatchDeps extends SlackContinuationProbes {
   handler: SlackBlockActionHandler;
   send: SendMessageFn;
+  continuation?: ContinuationIdentity;
   credentials: SlackCredentials | undefined;
   host: HostContext;
   artifacts: ArtifactsApi;
@@ -389,6 +391,9 @@ export async function dispatchBlockAction(
     isContinuationBusy: deps.isContinuationBusy,
     getContinuationLastBotMessageTs: deps.getContinuationLastBotMessageTs,
     interruptContinuation: deps.interruptContinuation,
+    ...(deps.continuation === undefined
+      ? {}
+      : { continuation: deps.continuation }),
   });
   return true;
 }

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

@@ -8,6 +8,10 @@
  */
 
 import { allowAll, defineChannel } from "../../channels.js";
+import {
+  continuationSource,
+  normalizeIdentity,
+} from "../../internal/continuation-identity.js";
 import type {
   ArtifactsApi,
   ChannelDefinition,
@@ -126,10 +130,14 @@ export function resolveDedicatedSlackHostBinding(
  * runtime values are still checked by {@link assertSlackCursorAgentName}.
  */
 export function slackChannel<const Name extends string = string>(
-  options: Omit<SlackChannelOptions, "agentName"> & {
+  authored: Omit<SlackChannelOptions, "agentName"> & {
     agentName?: SlackCursorAgentName<Name>;
   } = {}
 ): ChannelDefinition<SlackChannelState> {
+  const options = { ...authored };
+  if (options.continuation !== undefined) {
+    options.continuation = normalizeIdentity(options.continuation, "slack");
+  }
   const cursorAccount = options.cursorAccount === true;
   if (cursorAccount) {
     // Token pair and the Cursor connection are different Slack apps —
@@ -285,6 +293,7 @@ export function slackChannel<const Name extends string = string>(
   }): SlackInboundDispatchDeps {
     return {
       send: args.send,
+      continuation: options.continuation,
       waitUntil: args.waitUntil,
       onAppMention,
       onDirectMessage,
@@ -359,7 +368,17 @@ export function slackChannel<const Name extends string = string>(
       return send(input.message, {
         auth: input.auth,
         admission: "coalesce",
-        continuationToken: slackContinuationKey(channelId, threadTs),
+        ...(continuationSource(options.continuation, "slack") ===
+        "control-plane"
+          ? {
+              claim: {
+                type: "thread" as const,
+                resource: { channelId, threadTs },
+              },
+            }
+          : {
+              continuationToken: slackContinuationKey(channelId, threadTs),
+            }),
         state: emptySlackChannelState({
           channelId,
           threadTs,
@@ -488,6 +507,7 @@ export function slackChannel<const Name extends string = string>(
                   evalCommandsEnabled,
                   followUpStatus,
                   blockExternals,
+                  continuation: options.continuation,
                   ...(args.hasContinuationSession === undefined
                     ? {}
                     : {
@@ -583,6 +603,7 @@ export function slackChannel<const Name extends string = string>(
             getContinuationLastBotMessageTs:
               args.getContinuationLastBotMessageTs,
             interruptContinuation: args.interruptContinuation,
+            continuation: options.continuation,
           });
         };
       }

package/src/channels/slack/types.ts

@@ -2,6 +2,7 @@
  * Types for the Slack platform channel pack.
  */
 
+import type { ContinuationIdentity } from "../../continuation.js";
 import type {
   AgentCloudOptions,
   ArtifactsApi,
@@ -490,6 +491,12 @@ export interface SlackAccessPolicy {
 
 export interface SlackChannelOptions {
   credentials?: SlackCredentials;
+  /**
+   * Continuation selector. Omitted inherits {@link AgentConfig.architecture}:
+   * `"slack.thread/v1"` unless the agent set `architecture: "v2"` (then
+   * `"slack.thread/v2"`). Override with `"slack.none/v2"` for one-shot events.
+   */
+  continuation?: ContinuationIdentity;
   /** Defaults to `{ respondTo: "thread", blockExternals: true }`. */
   policy?: SlackAccessPolicy;
   /**

package/src/channels.ts

@@ -66,6 +66,7 @@ export {
 import { Buffer } from "node:buffer";
 import { timingSafeEqual } from "node:crypto";
 import { brandDefinition } from "./internal/brand.js";
+import { normalizeIdentity } from "./internal/continuation-identity.js";
 import { isLoopbackAddress, isLoopbackHostname } from "./internal/net.js";
 import type {
   AuthContext,
@@ -127,6 +128,12 @@ export function defineChannel<TState = JsonValue>(
 export function httpChannel(
   config: HttpChannelConfig = {}
 ): HttpChannelDefinition {
+  if (config.continuation !== undefined) {
+    return brandDefinition("http-channel", {
+      ...config,
+      continuation: normalizeIdentity(config.continuation, "http"),
+    });
+  }
   return brandDefinition("http-channel", config);
 }
 

package/src/continuation.ts

@@ -0,0 +1,49 @@
+/**
+ * Public continuation-identity surface for `@cursor/july`.
+ *
+ * Omitted `continuation` on a channel constructor stays `/v1` (engine
+ * minting). Deploy onto the v2 control plane with a root architecture
+ * flag; omitted channels then inherit the kind `/v2` default:
+ *
+ * ```ts
+ * export default defineAgent({
+ *   architecture: "v2",
+ * });
+ * ```
+ *
+ * Per-channel selectors still override type (`"github.issue/v2"`,
+ * `"github.none/v2"`). Other `/v2` selectors: `"slack.thread/v2"`,
+ * `"origin.pr/v2"`, `"none/v2"`.
+ */
+
+export type {
+  ContinuationBuiltin,
+  ContinuationClaim,
+  ContinuationIdentity,
+  ContinuationProtocolVersion,
+  ContinuationSelector,
+  ConversationType,
+  MailboxContinuation,
+  ParsedContinuation,
+} from "./internal/continuation-identity.js";
+export {
+  BUILTINS,
+  bindMailboxContinuationSend,
+  builtinForType,
+  CONTINUATION_SELECTORS,
+  continuationSource,
+  defaultContinuationSelector,
+  extractContinuation,
+  formatConversationKey,
+  handshakeContinuation,
+  isContinuationSelector,
+  isV2DurableContinuationKey,
+  mintClaim,
+  newEvtKey,
+  normalizeIdentity,
+  parseContinuationSelector,
+  resolveContinuation,
+  resolveV2Key,
+  stampMailboxContinuation,
+  V2EngineError,
+} from "./internal/continuation-identity.js";

package/src/files.ts

@@ -142,9 +142,13 @@ export const fileKeys = {
 
 /**
  * Framework-owned keys for state that lives on the deployment's Agent Store
- * but is not author `host.files` data: artifact rows and payloads, and the
- * cross-session memory journal. Kept out of `files/` so author listings never
- * see framework rows.
+ * but is not author `host.files` data: artifact rows and payloads, authored
+ * skills synced for cloud turns, and the cross-session memory journal. Kept
+ * out of `files/` so author listings never see framework rows.
+ *
+ * Skills sit at store-root `skills/<name>/…` so exec-daemon's
+ * `--agent-store-skills-dir` walk finds them the same way it finds user-store
+ * skills. Memory and artifacts stay under {@link STORAGE_KEY_ROOT}.
  */
 export const agentStoreKeys = {
   artifactRow: (agent: string, id: string): string =>
@@ -153,6 +157,9 @@ export const agentStoreKeys = {
     `${STORAGE_KEY_ROOT}/${agent}/artifacts/rows/`,
   artifactContent: (agent: string, id: string): string =>
     `${STORAGE_KEY_ROOT}/${agent}/artifacts/content/${encodeURIComponent(id)}`,
+  skillFile: (skillName: string, relPath: string): string =>
+    `skills/${skillName}/${relPath}`,
+  skillsPrefix: (): string => "skills/",
   memoryDir: (agent: string): string => `${STORAGE_KEY_ROOT}/${agent}/memory`,
   memoryJournal: (agent: string): string =>
     `${STORAGE_KEY_ROOT}/${agent}/memory/journal.jsonl`,

package/src/index.ts

@@ -51,6 +51,33 @@ export {
   publicEndpoint,
 } from "./channels.js";
 export { defineConnection } from "./connections.js";
+export type {
+  ContinuationBuiltin,
+  ContinuationClaim,
+  ContinuationIdentity,
+  ContinuationSelector,
+  ConversationType,
+  MailboxContinuation,
+  ParsedContinuation,
+} from "./continuation.js";
+export {
+  BUILTINS,
+  bindMailboxContinuationSend,
+  CONTINUATION_SELECTORS,
+  continuationSource,
+  defaultContinuationSelector,
+  extractContinuation,
+  formatConversationKey,
+  handshakeContinuation,
+  isContinuationSelector,
+  mintClaim,
+  normalizeIdentity,
+  parseContinuationSelector,
+  resolveContinuation,
+  resolveV2Key,
+  stampMailboxContinuation,
+  V2EngineError,
+} from "./continuation.js";
 export { defineHook } from "./hooks.js";
 export type { LoadAgentProjectOptions } from "./internal/discovery.js";
 export {
@@ -162,7 +189,9 @@ export {
 
 /**
  * Runtime config for an agent — authored at `agent/agent.ts` (the root
- * agent) or `agent/subagents/<id>/agent.ts` (a subagent).
+ * agent) or `agent/subagents/<id>/agent.ts` (a subagent). Set
+ * `architecture: "v2"` to deploy onto the v2 control plane; omitted
+ * channel continuation then inherits kind `/v2` defaults.
  */
 export function defineAgent(config: AgentConfig): AgentConfigDefinition {
   return brandDefinition("agent", config);

package/src/internal/continuation-channel.ts

@@ -0,0 +1,129 @@
+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,
+  HttpChannelDefinition,
+} from "../types.js";
+import {
+  type ContinuationIdentity,
+  type ContinuationProtocolVersion,
+  defaultContinuationSelector,
+  handshakeContinuation,
+  normalizeIdentity,
+} from "./continuation-identity.js";
+
+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");
+  }
+  return defaultContinuationSelector();
+}
+
+export function httpContinuationIdentity(
+  httpChannel: HttpChannelDefinition | undefined
+): ContinuationIdentity {
+  return normalizeIdentity(httpChannel?.continuation, "http");
+}
+
+/**
+ * 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.
+ */
+export function applyAgentContinuationDefaults(project: {
+  agent: { architecture?: AgentArchitecture };
+  channels: ReadonlyArray<{ definition: object }>;
+  httpChannel: HttpChannelDefinition;
+}): void {
+  if (project.agent.architecture !== "v2") {
+    return;
+  }
+  for (const channel of project.channels) {
+    stampOmittedChannelContinuation(channel.definition, "v2");
+  }
+  if (project.httpChannel.continuation === undefined) {
+    project.httpChannel.continuation = defaultContinuationSelector(
+      "http",
+      "v2"
+    );
+  }
+}
+
+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
+      );
+    }
+    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",
+        version,
+        events
+      );
+    }
+  }
+}
+
+function declaredChannelEventTypes(
+  definition: object
+): readonly string[] | undefined {
+  const meta = (definition as ChannelDefinition).meta;
+  return meta?.githubWebhookEvents ?? meta?.originWebhookEvents;
+}
+
+export function handshakeChannelContinuation(input: {
+  id: string;
+  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 result = handshakeContinuation({
+    kind,
+    eventTypes,
+    identity: channelContinuationIdentity(input.definition),
+  });
+  if (!result.ok) {
+    return { ok: false, error: `channel ${input.id}: ${result.error}` };
+  }
+  return result;
+}