@cursor/july 0.1.114 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cursor/july",
-  "version": "0.1.114",
+  "version": "0.2.0",
   "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/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,
@@ -68,6 +70,10 @@ import {
   slackWakeChannelState,
 } from "./dispatch.js";
 import { createEventIdDedupe, type EventIdDedupe } from "./event-id-dedupe.js";
+import {
+  parseChannelMessageEvent,
+  parseEventBodyBotUserId,
+} from "./inbound.js";
 import {
   dispatchBlockAction,
   dispatchInteractiveFromPayload,
@@ -245,6 +251,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 +373,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 +415,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 +777,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 +796,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/internal/cli-deploy.ts

@@ -1658,11 +1658,18 @@ export async function cmdStop(
   }
   const cancellation =
     "cancellation" in accepted ? accepted.cancellation : undefined;
+  // The backend escalates a publisher's stop of a multi-tenant app to the
+  // application-level suspension; say so, and how to undo it.
+  const stoppedGlobally = "scope" in accepted && accepted.scope === "global";
   if (ctx.noWait) {
     if (ctx.json) {
       ctx.out(`${JSON.stringify(accepted, null, 2)}\n`);
     } else {
-      ctx.out(`Stop accepted for ${slug} (status: ${accepted.status}).\n`);
+      ctx.out(
+        stoppedGlobally
+          ? `Stop accepted for ${slug} across all tenants (status: ${accepted.status}).\n`
+          : `Stop accepted for ${slug} (status: ${accepted.status}).\n`
+      );
     }
     return cancellation?.failed === 0 || cancellation === undefined ? 0 : 1;
   }
@@ -1681,6 +1688,10 @@ export async function cmdStop(
   }
   if (ctx.json) {
     ctx.out(`${JSON.stringify(detail, null, 2)}\n`);
+  } else if (stoppedGlobally) {
+    ctx.out(
+      `Stopped ${slug} across all tenants (team ${ctx.teamId}); resume with \`${CLI} start ${slug} --global\`.\n`
+    );
   } else {
     ctx.out(`Stopped ${slug} (team ${ctx.teamId}).\n`);
   }

package/src/internal/deploy-client.ts

@@ -295,6 +295,12 @@ export interface AgentkitStopAccepted {
   applicationId: string;
   releaseId: string;
   status: string;
+  /**
+   * `"global"` when the backend escalated the stop to the application-level
+   * suspension — the default for a multi-tenant app stopped by its
+   * publisher. Resume needs `start <slug> --global`.
+   */
+  scope?: "global";
   cancellation?: AgentkitCancelRunsResult;
 }
 
@@ -471,6 +477,9 @@ const agentkitStopAcceptedSchema = z
     applicationId: z.string().min(1),
     releaseId: z.string().min(1),
     status: z.string(),
+    // Tolerate scope values a newer backend may add: parse only "global",
+    // drop anything else rather than failing the stop response.
+    scope: z.literal("global").optional().catch(undefined),
     cancellation: agentkitCancelRunsResultSchema.optional(),
   })
   .passthrough();

package/src/internal/discovery/agent-config.ts

@@ -33,16 +33,18 @@ export function runtimeArchitectureCompatibilityError(agent: {
     : undefined;
 }
 
+/** Author-facing default when {@link AgentConfig.architecture} is omitted. */
+export const DEFAULT_AGENT_ARCHITECTURE: AgentArchitecture = "v2";
+
 export function resolveArchitecture(
   ctx: DiscoveryContext,
   agentDir: string,
   architecture: AgentArchitecture | undefined
 ): AgentArchitecture | undefined {
-  if (
-    architecture === undefined ||
-    architecture === "v1" ||
-    architecture === "v2"
-  ) {
+  if (architecture === undefined) {
+    return DEFAULT_AGENT_ARCHITECTURE;
+  }
+  if (architecture === "v1" || architecture === "v2") {
     return architecture;
   }
   ctx.diagnostics.push({
@@ -55,7 +57,7 @@ export function resolveArchitecture(
 
 /**
  * `persistent: true` selects the long-lived-pod hosting mode of v2. It has
- * no meaning on v1 (resident engine) or when the architecture is unset.
+ * no meaning on v1 (resident engine).
  */
 export function resolvePersistent(
   ctx: DiscoveryContext,

package/src/internal/framework-storage-selection.ts

@@ -66,7 +66,7 @@ import { resolveAgentV2Hosting } from "./v2-hosting.js";
 export interface FrameworkStorageSelectionInput {
   /** `agent/storage.ts`, when the author wrote one (v1 only: discovery rejects it on v2). */
   readonly authored: StorageDefinition | undefined;
-  /** {@link AgentConfig.architecture}; omitted means v1. */
+  /** {@link AgentConfig.architecture}; discovery fills `"v2"` when omitted. */
   readonly architecture?: AgentArchitecture | undefined;
   /** Environment override for tests; defaults to `process.env`. */
   readonly env?: Record<string, string | undefined>;

package/src/internal/platform-timers.ts

@@ -236,6 +236,28 @@ async function timedWorkJsonFetch(
   });
 }
 
+const CP_ERROR_BODY_LIMIT = 512;
+
+/**
+ * Read failures carry status and a bounded body: the guest logs them once
+ * per process, and a 405 body names the route the caller should be on.
+ */
+async function reminderCpReadError(
+  what: string,
+  response: Response
+): Promise<Error> {
+  let body = "";
+  try {
+    body = (await response.text()).trim();
+  } catch {
+    // Status-only detail.
+  }
+  const detail = body === "" ? "" : ` ${body.slice(0, CP_ERROR_BODY_LIMIT)}`;
+  return new Error(
+    `reminder CP ${what} failed: HTTP ${response.status}${detail}`
+  );
+}
+
 /**
  * Cursor-hosted HTTP ReminderControlPlane for architecture v2.
  * Speaks factory `/internal/agentsdk/reminders` (ELB → factory ECS).
@@ -275,7 +297,7 @@ export function createCursorHostedReminderControlPlane(
         return undefined;
       }
       if (!response.ok) {
-        throw new Error(`reminder CP get failed: HTTP ${response.status}`);
+        throw await reminderCpReadError("get", response);
       }
       const parsed: unknown = await response.json();
       return isReminderRecord(parsed) ? parsed : undefined;
@@ -287,7 +309,7 @@ export function createCursorHostedReminderControlPlane(
         `${AGENTSDK_REMINDERS_PREFIX}/reminders`
       );
       if (!response.ok) {
-        throw new Error(`reminder CP list failed: HTTP ${response.status}`);
+        throw await reminderCpReadError("list", response);
       }
       const parsed: unknown = await response.json();
       if (