@cursor/july 0.1.114 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.114",
+  "version": "0.2.1",
   "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": {

package/skills/setup-slack/SKILL.md

@@ -123,7 +123,7 @@ export default slackChannel({
   envPrefix: "JENNY",
   engagement: {
     channelPosts: {
-      allow: ["#alerts"], // ["*"] for every joined channel
+      allow: ["C0123ABCDEF", "#alerts"], // ≥1 channel id required, ≤10 ids
       posts: "top-level",
     },
   },

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

@@ -2,7 +2,8 @@
  * Opt-in channel watch: dispatch on posts in allowlisted channels.
  *
  * Filtering rules (the anti-slop guarantees):
- * - Only configured channels are watched; `"*"` opts into every channel.
+ * - Only configured channels are watched. The allowlist is finite: watching
+ *   every channel the bot is in is not expressible.
  * - Top-level posts only by default; thread replies never dispatch unless
  *   `posts: "all"` is configured.
  * - Posts that @mention the bot are skipped here (the `app_mention` path
@@ -21,21 +22,69 @@ import type { SlackChannelPostsOptions, SlackMessage } from "./types.js";
 
 const CHANNEL_ID_PATTERN = /^[CG][A-Z0-9]+$/;
 
-/** Allowlist over channel ids and `#names` (names resolve lazily), or `*`. */
+/**
+ * Channel-watch allowlist contract, mirrored by the control plane's
+ * deploy-time validation (proto posture: both sides validate
+ * independently). Ids are required because on Cursor-managed hosting they
+ * become channel-scoped subscription edges — the control plane drops
+ * channel posts outside the id set before any compute wakes, and it cannot
+ * resolve `#names`.
+ */
+export const CHANNEL_POSTS_MAX_CHANNEL_IDS = 10;
+
+/** The channel-id (`C…`/`G…`) entries of an allowlist, deduped. */
+export function channelPostIdEntries(entries: readonly string[]): string[] {
+  const ids = new Set<string>();
+  for (const raw of entries) {
+    const entry = raw.trim();
+    if (CHANNEL_ID_PATTERN.test(entry)) {
+      ids.add(entry);
+    }
+  }
+  return [...ids];
+}
+
+/**
+ * Validate `channelPosts.allow` at definition time. Returns an actionable
+ * error string (to be prefixed with the option path), or undefined.
+ */
+export function validateChannelPostsAllow(
+  entries: readonly string[]
+): string | undefined {
+  if (entries.some(entry => entry.trim() === "*")) {
+    return (
+      'no longer supports "*": list the channels to watch by id (C…/G…), ' +
+      `up to ${CHANNEL_POSTS_MAX_CHANNEL_IDS} channels.`
+    );
+  }
+  const ids = channelPostIdEntries(entries);
+  if (ids.length === 0) {
+    return (
+      "must include at least one channel id (C…/G…). Ids define the " +
+      "watched set on Cursor-managed hosting; `#name` entries alone are " +
+      "not enough."
+    );
+  }
+  if (ids.length > CHANNEL_POSTS_MAX_CHANNEL_IDS) {
+    return `lists ${ids.length} channel ids; the maximum is ${CHANNEL_POSTS_MAX_CHANNEL_IDS}.`;
+  }
+  return undefined;
+}
+
+/** Allowlist over channel ids and `#names` (names resolve lazily). */
 export class SlackChannelAllowlist {
   private readonly ids = new Set<string>();
   private readonly names = new Set<string>();
-  private all = false;
 
   constructor(entries: readonly string[]) {
     for (const raw of entries) {
       const entry = raw.trim();
-      if (entry === "") {
+      // "*" is rejected at definition time (validateChannelPostsAllow);
+      // ignore it here so a stale config degrades to its explicit entries.
+      if (entry === "" || entry === "*") {
         continue;
       }
-      if (entry === "*") {
-        this.all = true;
-      } else if (entry.startsWith("#")) {
+      if (entry.startsWith("#")) {
         this.names.add(entry.slice(1).toLowerCase());
       } else if (CHANNEL_ID_PATTERN.test(entry)) {
         this.ids.add(entry);
@@ -47,7 +96,7 @@ export class SlackChannelAllowlist {
   }
 
   matches(channelId: string): boolean {
-    return this.all || this.ids.has(channelId);
+    return this.ids.has(channelId);
   }
 
   unresolvedNames(): string[] {

package/src/channels/slack/inbound.ts

@@ -218,6 +218,30 @@ export function parseAssistantThreadStarted(
   };
 }
 
+/**
+ * The receiving app's own bot user id from an Events API envelope. Slack
+ * stamps `authorizations[]` on every `event_callback` with the installed
+ * bot user the delivery is for, so a hosted guest learns its identity from
+ * the verified body without an `auth.test` round trip.
+ */
+export function parseEventBodyBotUserId(body: unknown): string | undefined {
+  const root = asRecord(body);
+  if (root === null || root.type !== "event_callback") {
+    return undefined;
+  }
+  if (!Array.isArray(root.authorizations)) {
+    return undefined;
+  }
+  for (const entry of root.authorizations) {
+    const authorization = asRecord(entry);
+    const userId = asString(authorization?.user_id);
+    if (userId !== undefined && userId !== "") {
+      return userId;
+    }
+  }
+  return undefined;
+}
+
 /**
  * Parse DM / IM messages. More generous than a strict channel_type check:
  * accepts `channel_type === "im"` or channel ids starting with `D`, and

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

@@ -25,10 +25,12 @@ import {
 } from "../../internal/continuation-identity.js";
 import { AGENT_SERVE_GENERATION_ENV_VAR } from "../../internal/cursor-relay-core.js";
 import { attachHostedAdmissionAdapter } from "../../internal/hosted-admission-adapter.js";
+import type { HostedAdmissionPlatformHandoff } from "../../internal/hosted-delivery-protocol.js";
 import type {
   ArtifactsApi,
   ChannelDefinition,
   ChannelEventHandlers,
+  ChannelHandlerArgs,
   HostContext,
   JsonValue,
   ReceiveInput,
@@ -46,6 +48,7 @@ import {
   createChannelPostWatcher,
   resolveChannelNames,
   SlackChannelAllowlist,
+  validateChannelPostsAllow,
 } from "./channel-watch.js";
 import {
   credentialsFromEnv,
@@ -68,6 +71,10 @@ import {
   slackWakeChannelState,
 } from "./dispatch.js";
 import { createEventIdDedupe, type EventIdDedupe } from "./event-id-dedupe.js";
+import {
+  parseChannelMessageEvent,
+  parseEventBodyBotUserId,
+} from "./inbound.js";
 import {
   dispatchBlockAction,
   dispatchInteractiveFromPayload,
@@ -181,10 +188,10 @@ export function slackChannel(
   const followUpStatus = options.followUpStatus ?? !silent;
   const channelPosts = engagement.channelPosts;
   if (channelPosts !== undefined) {
-    const entries = channelPosts.allow.filter(entry => entry.trim() !== "");
-    if (entries.length === 0) {
+    const allowError = validateChannelPostsAllow(channelPosts.allow);
+    if (allowError !== undefined) {
       throw new Error(
-        'slackChannel engagement.channelPosts.allow must list at least one channel (id, #name, or "*").'
+        `slackChannel engagement.channelPosts.allow ${allowError}`
       );
     }
   }
@@ -245,6 +252,113 @@ export function slackChannel(
   let channelWatch: ChannelPostWatcher | undefined;
   let botMentionGate: SlackBotMentionGate | undefined;
 
+  // Hosted admission never runs the Socket Mode branch of `onStart`, so the
+  // channel watch is built per delivery there. The allowlist and its `#name`
+  // resolution are shared across the pod; the bot's identity comes from the
+  // verified envelope.
+  let hostedAllowlist: SlackChannelAllowlist | undefined;
+  let hostedAllowlistReady: Promise<void> | undefined;
+
+  async function resolveHostedAllowlistNames(
+    allowlist: SlackChannelAllowlist
+  ): Promise<void> {
+    const names = allowlist.unresolvedNames();
+    if (names.length === 0) {
+      return;
+    }
+    try {
+      const botToken = await tryResolveBotToken(credentials);
+      if (botToken === undefined) {
+        getLog().error("channel watch setup degraded", {
+          error: "no bot token; #name entries stay unresolved",
+        });
+        return;
+      }
+      const { WebClient } = await import("@slack/web-api");
+      allowlist.applyResolvedNames(
+        await resolveChannelNames(new WebClient(botToken), names, getLog())
+      );
+    } catch (error) {
+      getLog().error("channel watch setup degraded", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Only a channel post needs the watcher, so mentions and DMs never wait on
+   * it, and a channel already matched by id never waits on `#name` resolution.
+   */
+  async function hostedChannelWatch(
+    payload: unknown,
+    args: ChannelHandlerArgs,
+    platformHandoff: HostedAdmissionPlatformHandoff | undefined
+  ): Promise<ChannelPostWatcher | undefined> {
+    if (channelPosts === undefined) {
+      return undefined;
+    }
+    const channelEvent = parseChannelMessageEvent(payload, {
+      includeBotAuthored: true,
+    });
+    if (channelEvent === null || channelEvent.kind === "deleted") {
+      return undefined;
+    }
+    hostedAllowlist ??= new SlackChannelAllowlist(channelPosts.allow);
+    if (
+      !hostedAllowlist.matches(channelEvent.message.channelId) &&
+      hostedAllowlist.unresolvedNames().length > 0
+    ) {
+      hostedAllowlistReady ??= resolveHostedAllowlistNames(hostedAllowlist);
+      await hostedAllowlistReady;
+    }
+    const botUserId = parseEventBodyBotUserId(payload);
+    return createChannelPostWatcher({
+      // Admission answers before a debounce timer could fire; edits arrive
+      // as their own deliveries and the edge drops them.
+      options: { ...channelPosts, debounceMs: 0 },
+      allowlist: hostedAllowlist,
+      getBotUserId: () => botUserId,
+      log: getLog(),
+      dispatch: (message, eventId) => {
+        args.waitUntil(
+          dispatchInboundMessage({
+            kind: "channel_post",
+            message,
+            handler: onChannelPost,
+            propagateHandlerErrors: true,
+            send: args.send,
+            credentials,
+            host: args.host,
+            artifacts: args.artifacts,
+            log: getLog(),
+            evalCommandsEnabled,
+            followUpStatus,
+            ack: reply.ack,
+            blockExternals,
+            continuation: options.continuation,
+            ...(args.hasContinuationSession === undefined
+              ? {}
+              : { hasContinuationSession: args.hasContinuationSession }),
+            ...(args.isContinuationBusy === undefined
+              ? {}
+              : { isContinuationBusy: args.isContinuationBusy }),
+            ...(args.getContinuationLastBotMessageTs === undefined
+              ? {}
+              : {
+                  getContinuationLastBotMessageTs:
+                    args.getContinuationLastBotMessageTs,
+                }),
+            ...(args.interruptContinuation === undefined
+              ? {}
+              : { interruptContinuation: args.interruptContinuation }),
+            ...(eventId === undefined ? {} : { eventId }),
+            ...(platformHandoff === undefined ? {} : { platformHandoff }),
+          })
+        );
+      },
+    });
+  }
+
   function inboundDeps(args: {
     send: SendMessageFn;
     waitUntil: (promise: Promise<unknown>) => void;
@@ -260,7 +374,10 @@ export function slackChannel(
     ) => Promise<string | undefined>;
     interruptContinuation?: (continuationToken: string) => Promise<boolean>;
     platformHandoff?: SlackInboundDispatchDeps["platformHandoff"];
+    /** Per-delivery watcher (hosted); the Socket Mode watcher otherwise. */
+    channelWatch?: ChannelPostWatcher;
   }): SlackInboundDispatchDeps {
+    const watch = args.channelWatch ?? channelWatch;
     return {
       send: args.send,
       continuation: options.continuation,
@@ -299,7 +416,7 @@ export function slackChannel(
       ...(args.interruptContinuation === undefined
         ? {}
         : { interruptContinuation: args.interruptContinuation }),
-      ...(channelWatch === undefined ? {} : { channelWatch }),
+      ...(watch === undefined ? {} : { channelWatch: watch }),
       ...(botMentionGate === undefined ? {} : { botMentionGate }),
       suggestedPrompts: options.suggestedPrompts,
       suggestedPromptsTitle: options.suggestedPromptsTitle,
@@ -661,6 +778,11 @@ export function slackChannel(
     // would otherwise swallow the control plane's own retry of a delivery
     // that failed after the id was marked handled.
     dispatch: async ({ payload, args, platformHandoff }) => {
+      const hostedWatch = await hostedChannelWatch(
+        payload,
+        args,
+        platformHandoff
+      );
       const dispatched = dispatchInboundFromEventBody(
         payload,
         inboundDeps({
@@ -675,6 +797,7 @@ export function slackChannel(
           getContinuationLastBotMessageTs: args.getContinuationLastBotMessageTs,
           interruptContinuation: args.interruptContinuation,
           ...(platformHandoff === undefined ? {} : { platformHandoff }),
+          ...(hostedWatch === undefined ? {} : { channelWatch: hostedWatch }),
         })
       );
       return skipped(dispatched ? "not_engaged" : "not_dispatchable");

package/src/channels/slack/types.ts

@@ -517,28 +517,27 @@ export type SlackBlockActionHandler = (
 
 /**
  * Opt-in channel watch: dispatch on posts in configured channels without an
- * @mention. Use `"*"` for every channel the bot has joined.
+ * @mention. The watched set is a finite list — mentions are global (any
+ * channel the bot is in), but listening without a mention names its
+ * channels.
  */
 export interface SlackChannelPostsOptions {
   /**
-   * Channels to watch: ids (`C…` / `G…`), `#names`, or `"*"` for every
-   * channel the bot is in. Must be non-empty (empty is a definition error).
-   * `#names` are resolved to ids via `conversations.list` when the channel
-   * starts; the bot must be a member of each watched channel to receive its
+   * Channels to watch. Must include at least one channel id (`C…` / `G…`)
+   * and at most 10 distinct ids; `"*"` is a definition error. `#name`
+   * entries may accompany ids (resolved via `conversations.list` on Socket
+   * Mode), but on Cursor-managed hosting the id entries alone define the
+   * watched set: each id becomes a channel-scoped subscription, and the
+   * control plane drops channel posts outside that set before any compute
+   * wakes. The bot must be a member of each watched channel to receive its
    * messages.
-   *
-   * `"*"` suits agents whose handler decides per message (a thread the agent
-   * is already in, say) rather than per channel. Every delivered message then
-   * reaches {@link SlackChannelOptions.onChannelPost}, and each one costs a
-   * `users.info` external-sender check first unless
-   * {@link SlackAccessPolicy.blockExternals} is off.
    */
   allow: string[];
   /**
    * Which posts dispatch. `"top-level"` (default) fires only on new
    * channel posts — never on replies inside other people's threads, so the
    * agent can take fresh intake but cannot barge into conversations.
-   * `"all"` also dispatches thread replies (Socket Mode only).
+   * `"all"` also dispatches thread replies in allowlisted channels.
    */
   posts?: "top-level" | "all";
   /**

package/src/files-backends/cursor-hosted.ts

@@ -57,19 +57,19 @@ import {
   type FileSinkPutResult,
 } from "../files.js";
 import {
-  AGENT_SERVE_FACTORY_FLUSH_PROTOCOL,
+  type CursorApiTransportOptions,
+  resolveCursorApiBaseUrl,
+  resolveCursorApiFetch,
+  resolveCursorApiKey,
+} from "../internal/cursor/cursor-api-transport.js";
+import {
   resolveDeploymentStoreSourceIdSync,
   resolveFrameworkStoreSourceIdSync,
   resolveStoreProtocolSync,
+  storeProtocolEnablesFactoryFlush,
 } from "../internal/cursor/hosted-store-secrets.js";
 import { createAgentStorePresignedUrlValidatorForBackend } from "./agent-store-presigned-url.js";
 
-/**
- * Same default as the hosted storage backend, inlined so this entrypoint does
- * not import CLI code.
- */
-const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
-
 const AGENT_SERVE_FILES_PATH = "/v0/agent-serve-files";
 
 /**
@@ -156,18 +156,12 @@ export function isCursorUserStoreFilesAvailable(
   return key !== undefined && key !== "";
 }
 
-export interface CursorHostedFilesOptions {
-  /** Control-plane base URL (default: `CURSOR_API_BASE_URL`, else api.cursor.com). */
-  baseUrl?: string;
-  /** Bearer credential (default: `CURSOR_API_KEY`). */
-  apiKey?: string;
-  /**
-   * Lazy credential, re-resolved on every call and preferred over
-   * {@link apiKey} — hosted freeze snapshots listen unsigned and bind the
-   * key file after serve start. Kept separate so `apiKey` stays a plain
-   * string.
-   */
-  resolveApiKey?: () => string | undefined;
+/**
+ * Base URL / credential / fetch resolution is the shared
+ * {@link CursorApiTransportOptions} (`internal/cursor/cursor-api-transport.ts`),
+ * so this sink and the domain-lane store API client resolve identically.
+ */
+export interface CursorHostedFilesOptions extends CursorApiTransportOptions {
   /** File store to address (default: `AGENT_SERVE_STORE_SOURCE_ID`). */
   storeSourceId?: string;
   /**
@@ -178,13 +172,12 @@ export interface CursorHostedFilesOptions {
   resolveStoreSourceId?: () => string | undefined;
   /**
    * Lazy store protocol pin (default: env, then the task-bound file). When it
-   * answers {@link AGENT_SERVE_FACTORY_FLUSH_PROTOCOL} and the source id maps
-   * to a deployment store role, requests ride the factory store API instead
-   * of `/v0/agent-serve-files`. Any other value keeps `/v0`.
+   * enables the factory flush wire (`factory-flush-v1`, or the superset
+   * domain-API pin `factory-api-v1`) and the source id maps to a deployment
+   * store role, requests ride the factory store API instead of
+   * `/v0/agent-serve-files`. Any other value keeps `/v0`.
    */
   resolveStoreProtocol?: () => string | undefined;
-  /** Test seam; defaults to global fetch. */
-  fetch?: typeof fetch;
 }
 
 /**
@@ -295,7 +288,7 @@ export function cursorHostedFiles(
     const sourceId = resolveStoreSourceId(options);
     const protocol =
       options.resolveStoreProtocol?.() ?? resolveStoreProtocolSync();
-    if (protocol === AGENT_SERVE_FACTORY_FLUSH_PROTOCOL) {
+    if (storeProtocolEnablesFactoryFlush(protocol)) {
       // The factory API addresses stores by role, so map the pinned source id
       // back to the role it was pinned from. A source id matching neither (a
       // local-dev override) has no role there and stays on `/v0`, as does any
@@ -567,7 +560,7 @@ export function cursorHostedFiles(
           };
         }
         try {
-          const response = await fetchImpl(options)(
+          const response = await resolveCursorApiFetch(options)(
             assertPresignedUrlSafe(options, instruction.url),
             {
               method: "PUT",
@@ -818,7 +811,7 @@ export function cursorHostedFiles(
         if (url === undefined) {
           return undefined;
         }
-        const response = await fetchImpl(options)(
+        const response = await resolveCursorApiFetch(options)(
           assertPresignedUrlSafe(options, url),
           {
             method: "GET",
@@ -992,9 +985,9 @@ function assertPresignedUrlSafe(
     return url.toString();
   }
   try {
-    createAgentStorePresignedUrlValidatorForBackend(resolveBaseUrl(options))(
-      url
-    );
+    createAgentStorePresignedUrlValidatorForBackend(
+      resolveCursorApiBaseUrl(options)
+    )(url);
   } catch (error) {
     throw new Error(
       `cursorHostedFiles: refused presigned URL: ${
@@ -1005,14 +998,6 @@ function assertPresignedUrlSafe(
   return url.toString();
 }
 
-function fetchImpl(options: CursorHostedFilesOptions): typeof fetch {
-  const impl = options.fetch ?? globalThis.fetch;
-  if (typeof impl !== "function") {
-    throw new Error("cursorHostedFiles requires fetch");
-  }
-  return impl;
-}
-
 /**
  * The file store this engine's deployment owns. Every request names it, so
  * the server resolves the store row and this process never handles a store id.
@@ -1034,17 +1019,6 @@ function resolveStoreSourceId(options: CursorHostedFilesOptions): string {
   return id;
 }
 
-function resolveApiKey(options: CursorHostedFilesOptions): string {
-  const configured = options.resolveApiKey?.() ?? options.apiKey;
-  const key = (configured ?? process.env.CURSOR_API_KEY)?.trim();
-  if (key === undefined || key === "") {
-    throw new Error(
-      "cursorHostedFiles requires CURSOR_API_KEY (deployment pod credential on Cursor hosting)"
-    );
-  }
-  return key;
-}
-
 const DEV_PRESIGN_HOSTS: ReadonlySet<string> = new Set(
   (process.env.CURSOR_HOSTED_FILES_DEV_PRESIGN_HOSTS ?? "")
     .split(",")
@@ -1052,19 +1026,6 @@ const DEV_PRESIGN_HOSTS: ReadonlySet<string> = new Set(
     .filter(host => host.length > 0)
 );
 
-function resolveBaseUrl(options: CursorHostedFilesOptions): string {
-  return trimTrailingSlash(
-    options.baseUrl ??
-      process.env.CURSOR_API_BASE_URL ??
-      DEFAULT_CURSOR_EXTERNAL_API_URL
-  );
-}
-
-function trimTrailingSlash(raw: string): string {
-  const trimmed = raw.trim();
-  return trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
-}
-
 /**
  * Public agent-serve-files API call. The pod credential is the whole authorization:
  * the API forwards this caller's identity to the store service, which checks it
@@ -1077,7 +1038,7 @@ async function storePost<T>(
 ): Promise<T> {
   return await postJson<T>(
     options,
-    `${resolveBaseUrl(options)}${AGENT_SERVE_FILES_PATH}${path}`,
+    `${resolveCursorApiBaseUrl(options)}${AGENT_SERVE_FILES_PATH}${path}`,
     body
   );
 }
@@ -1088,7 +1049,7 @@ async function storeGet<T>(
 ): Promise<T> {
   return await sendJson<T>(
     options,
-    `${resolveBaseUrl(options)}${AGENT_SERVE_FILES_PATH}${path}`,
+    `${resolveCursorApiBaseUrl(options)}${AGENT_SERVE_FILES_PATH}${path}`,
     "GET"
   );
 }
@@ -1096,7 +1057,9 @@ async function storeGet<T>(
 /**
  * Factory store API call — same base URL and pod credential as
  * {@link storePost}, different path family. The server resolves the
- * deployment (and the addressed store role) from the credential.
+ * deployment (and the addressed store role) from the credential. The
+ * domain-call lane one path family deeper is NOT here: it belongs to the
+ * store API client (`../internal/cursor/store-api-client.ts`).
  */
 async function flushPost<T>(
   options: CursorHostedFilesOptions,
@@ -1105,7 +1068,7 @@ async function flushPost<T>(
 ): Promise<T> {
   return await postJson<T>(
     options,
-    `${resolveBaseUrl(options)}${AGENTSDK_STORE_PATH}${path}`,
+    `${resolveCursorApiBaseUrl(options)}${AGENTSDK_STORE_PATH}${path}`,
     body
   );
 }
@@ -1124,10 +1087,10 @@ async function sendJson<T>(
   method: "GET" | "POST",
   body?: Record<string, unknown>
 ): Promise<T> {
-  const response = await fetchImpl(options)(url, {
+  const response = await resolveCursorApiFetch(options)(url, {
     method,
     headers: {
-      Authorization: `Bearer ${resolveApiKey(options)}`,
+      Authorization: `Bearer ${resolveCursorApiKey(options)}`,
       ...(body === undefined ? {} : { "Content-Type": "application/json" }),
     },
     ...(body === undefined ? {} : { body: JSON.stringify(body) }),

package/src/index.ts

@@ -166,6 +166,7 @@ export type {
   ReminderDefinition,
   ReminderFireContext,
   ReminderFireResult,
+  ReminderFollowupOptions,
   ReminderHandlerConfig,
   ReminderHostApi,
   ReminderInfo,