@cursor/july 0.2.0 → 0.2.1

package/src/internal/cursor/store-api-client.ts

@@ -0,0 +1,360 @@
+/**
+ * The store API client: July's one gateway to the factory domain-call lane,
+ * `POST /internal/agentsdk/store/api/<call>`. This module owns the whole
+ * transport — base URL and deployment credential (the same resolution the
+ * files sink uses, via `cursor-api-transport.ts`), envelope encoding,
+ * response validation, typed error mapping, and the bounded backoff policy.
+ * Feature modules (`memory.ts`, later `session-run-log.ts`, …) call typed
+ * methods like {@link StoreApiClient.memoryAppend} and never hand-roll
+ * fetch; future domain calls (`sessionRun.report`, `startLog.flush`, …) are
+ * added here as new methods on this one client.
+ *
+ * The lane is selected per pod by the task-bound store protocol pin:
+ * {@link isStoreApiLaneEnabled} is true only under the exact
+ * `factory-api-v1` pin AND with a provisioned deployment store. The
+ * availability check is not redundant: the pin file is written by the hosted
+ * task bind, but a local-dev env var could name the pin without any store to
+ * serve reads — appending into the void. Both resolve lazily per call, so a
+ * pin bound after serve start takes effect without a restart.
+ */
+
+import {
+  MEMORY_APPEND_MAX_RECORD_BYTES,
+  memoryAppendResponseSchema,
+  memoryReadResponseSchema,
+  STORE_API_MEMORY_APPEND_CALL,
+  STORE_API_MEMORY_READ_CALL,
+  STORE_API_PATH,
+  STORE_API_PROTOCOL_VERSION,
+  serializedRecordBytes,
+} from "../store-api-protocol.js";
+import {
+  type CursorApiTransportOptions,
+  resolveCursorApiBaseUrl,
+  resolveCursorApiFetch,
+  resolveCursorApiKey,
+} from "./cursor-api-transport.js";
+import {
+  resolveDeploymentStoreSourceIdSync,
+  resolveStoreProtocolSync,
+  storeProtocolEnablesStoreApi,
+} from "./hosted-store-secrets.js";
+
+export interface StoreApiClientOptions extends CursorApiTransportOptions {
+  /** Deployment store source id override (lane availability check). */
+  storeSourceId?: string;
+  /** Lazy store source id, preferred over {@link storeSourceId}. */
+  resolveStoreSourceId?: () => string | undefined;
+  /** Lazy store protocol pin (default: env, then the task-bound file). */
+  resolveStoreProtocol?: () => string | undefined;
+  /** Backoff sleep override (tests). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Jitter source override (tests). Returns [0, 1). */
+  random?: () => number;
+}
+
+/**
+ * How one domain call failed, after the client's bounded retries:
+ *
+ * - `rejected` — the server (or the client's own pre-check) refused the
+ *   payload with a typed 4xx. Deterministic; never retried.
+ * - `shed` — 429 from the per-deployment limiter or kill switch. Retried
+ *   only within the small Retry-After bound below; retrying harder against
+ *   a shed is exactly the stampede the domain lane exists to prevent.
+ * - `unavailable` — 5xx or a network failure, retried up to the attempt
+ *   bound.
+ * - `bad_response` — a 2xx whose body failed the response schema; a
+ *   contract break, not a transient, so never retried.
+ */
+export type StoreApiFailureKind =
+  | "rejected"
+  | "shed"
+  | "unavailable"
+  | "bad_response";
+
+export class StoreApiCallError extends Error {
+  constructor(
+    readonly kind: StoreApiFailureKind,
+    message: string,
+    readonly status?: number
+  ) {
+    super(message);
+    this.name = "StoreApiCallError";
+  }
+}
+
+/**
+ * Bounded backoff policy. Domain calls run at turn boundaries (a memory
+ * append after `turn.completed`), so the budget is a few short retries, not
+ * persistence: 3 attempts total and never more than 2s asleep between them.
+ * A 429 whose Retry-After exceeds the cap is a deliberate shed (a kill
+ * switch, a hard budget) — give up immediately instead of camping on it.
+ */
+const STORE_API_MAX_ATTEMPTS = 3;
+const STORE_API_MAX_BACKOFF_MS = 2_000;
+
+/**
+ * Hard deadline per fetch (the envelope POSTs and the presigned journal
+ * GET). Without one, a stalled — not failed — connection rides undici's
+ * ~300 s inactivity timers, and hydration runs at the head of the session
+ * dispatch chain where a stall delays every queued handler. 15 s matches
+ * the server's own presigned-fetch deadline and is generous for a ≤5 MiB
+ * journal.
+ */
+const STORE_API_FETCH_TIMEOUT_MS = 15_000;
+
+function backoffMs(attempt: number, random: () => number): number {
+  return Math.min(
+    200 * 2 ** attempt * (0.5 + random()),
+    STORE_API_MAX_BACKOFF_MS
+  );
+}
+
+/**
+ * Is the domain-call lane on for this pod? Exact pin match plus a
+ * provisioned deployment store; anything else keeps the client-side
+ * patterns, fail-safe in both directions like the flush pin itself.
+ */
+export function isStoreApiLaneEnabled(
+  options: StoreApiClientOptions = {}
+): boolean {
+  const protocol =
+    options.resolveStoreProtocol?.() ?? resolveStoreProtocolSync();
+  if (!storeProtocolEnablesStoreApi(protocol)) {
+    return false;
+  }
+  const sourceId = (
+    options.resolveStoreSourceId?.() ??
+    options.storeSourceId ??
+    resolveDeploymentStoreSourceIdSync()
+  )?.trim();
+  return sourceId !== undefined && sourceId !== "";
+}
+
+export type StoreApiClient = {
+  /**
+   * One `memory.append` domain call: the server appends the record to a
+   * server-owned journal shard. Resolves on success; throws
+   * {@link StoreApiCallError} after the bounded retries. The caller owns the
+   * failure policy (memory drops the record — appending is advisory).
+   */
+  memoryAppend(payload: {
+    agent: string;
+    record: Record<string, unknown>;
+  }): Promise<void>;
+  /**
+   * One `memory.read` domain call plus the presigned byte fetch: the server
+   * flushes the agent's pending append buffer (best-effort) and presigns
+   * the canonical journal; this method then downloads it. Undefined while
+   * the agent has no journal. Throws {@link StoreApiCallError} after the
+   * bounded retries — the caller owns the failure policy (hydration keeps
+   * the existing mirror).
+   */
+  memoryReadContent(payload: {
+    agent: string;
+  }): Promise<Uint8Array | undefined>;
+};
+
+export function createStoreApiClient(
+  options: StoreApiClientOptions = {}
+): StoreApiClient {
+  const sleep =
+    options.sleep ??
+    ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));
+  const random = options.random ?? Math.random;
+
+  /** One POST of a versioned envelope; returns the parsed 2xx body. */
+  const postOnce = async (
+    call: string,
+    envelope: Record<string, unknown>
+  ): Promise<Response> => {
+    const fetchImpl = resolveCursorApiFetch(options);
+    return await fetchImpl(
+      `${resolveCursorApiBaseUrl(options)}${STORE_API_PATH}/${call}`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${resolveCursorApiKey(options)}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(envelope),
+        signal: AbortSignal.timeout(STORE_API_FETCH_TIMEOUT_MS),
+      }
+    );
+  };
+
+  /** The response's `Retry-After` in ms, when present and numeric. */
+  const retryAfterDelayMs = (response: Response): number | undefined => {
+    const header = response.headers.get("retry-after")?.trim();
+    const seconds =
+      header === undefined || header === "" ? Number.NaN : Number(header);
+    return Number.isFinite(seconds) ? seconds * 1_000 : undefined;
+  };
+
+  const describeErrorBody = async (response: Response): Promise<string> => {
+    try {
+      const parsed = (await response.json()) as { error?: unknown };
+      if (typeof parsed?.error === "string") {
+        return parsed.error;
+      }
+    } catch {
+      // Non-JSON error body; the status is the message.
+    }
+    return `HTTP ${response.status}`;
+  };
+
+  const callApi = async (
+    call: string,
+    envelope: Record<string, unknown>
+  ): Promise<unknown> => {
+    let lastFailure: StoreApiCallError | undefined;
+    // A shed's Retry-After (when within the cap) overrides the next jittered
+    // backoff; cleared before every attempt.
+    let nextDelayMs: number | undefined;
+    for (let attempt = 0; attempt < STORE_API_MAX_ATTEMPTS; attempt += 1) {
+      if (attempt > 0) {
+        await sleep(nextDelayMs ?? backoffMs(attempt, random));
+      }
+      nextDelayMs = undefined;
+      let response: Response;
+      try {
+        response = await postOnce(call, envelope);
+      } catch (error) {
+        lastFailure = new StoreApiCallError(
+          "unavailable",
+          `store api ${call} transport failure: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+        continue;
+      }
+      if (response.ok) {
+        try {
+          return (await response.json()) as unknown;
+        } catch {
+          throw new StoreApiCallError(
+            "bad_response",
+            `store api ${call} answered non-JSON (${response.status})`,
+            response.status
+          );
+        }
+      }
+      if (response.status === 429) {
+        const retryDelayMs = retryAfterDelayMs(response);
+        const shed = new StoreApiCallError(
+          "shed",
+          `store api ${call} shed: ${await describeErrorBody(response)}`,
+          response.status
+        );
+        if (
+          retryDelayMs !== undefined &&
+          retryDelayMs > STORE_API_MAX_BACKOFF_MS
+        ) {
+          // A long Retry-After is a kill switch or hard budget: obey it by
+          // giving up now, not by camping on the route.
+          throw shed;
+        }
+        nextDelayMs = retryDelayMs;
+        lastFailure = shed;
+        continue;
+      }
+      if (response.status >= 500) {
+        // A degraded 503 carries `Retry-After` too (the server's buffer-down
+        // answer). Honor it clamped to the backoff cap — unlike a shed, a
+        // 5xx is transient by definition, so a long hint never means "give
+        // up", just "wait the cap".
+        const retryDelayMs = retryAfterDelayMs(response);
+        if (retryDelayMs !== undefined) {
+          nextDelayMs = Math.min(retryDelayMs, STORE_API_MAX_BACKOFF_MS);
+        }
+        lastFailure = new StoreApiCallError(
+          "unavailable",
+          `store api ${call} failed: ${await describeErrorBody(response)}`,
+          response.status
+        );
+        continue;
+      }
+      // Any other 4xx is deterministic; retrying re-sends the same refusal.
+      throw new StoreApiCallError(
+        "rejected",
+        `store api ${call} rejected: ${await describeErrorBody(response)}`,
+        response.status
+      );
+    }
+    throw lastFailure ?? new StoreApiCallError("unavailable", "no attempt ran");
+  };
+
+  return {
+    async memoryAppend(payload) {
+      const recordBytes = serializedRecordBytes(payload.record);
+      if (recordBytes > MEMORY_APPEND_MAX_RECORD_BYTES) {
+        // The server-side controller enforces the same cap; checking here
+        // spares a doomed request and fails with the same typed shape.
+        throw new StoreApiCallError(
+          "rejected",
+          `memory.append record is ${recordBytes} serialized bytes; the cap is ${MEMORY_APPEND_MAX_RECORD_BYTES}`
+        );
+      }
+      const body = await callApi(STORE_API_MEMORY_APPEND_CALL, {
+        v: STORE_API_PROTOCOL_VERSION,
+        call: STORE_API_MEMORY_APPEND_CALL,
+        payload,
+      });
+      if (!memoryAppendResponseSchema.safeParse(body).success) {
+        throw new StoreApiCallError(
+          "bad_response",
+          "unexpected memory.append response shape"
+        );
+      }
+    },
+
+    async memoryReadContent(payload) {
+      const body = await callApi(STORE_API_MEMORY_READ_CALL, {
+        v: STORE_API_PROTOCOL_VERSION,
+        call: STORE_API_MEMORY_READ_CALL,
+        payload,
+      });
+      const parsed = memoryReadResponseSchema.safeParse(body);
+      if (!parsed.success) {
+        throw new StoreApiCallError(
+          "bad_response",
+          "unexpected memory.read response shape"
+        );
+      }
+      if (parsed.data.journal === null) {
+        return undefined;
+      }
+      // Bulk bytes ride the presigned URL, never the control plane — same
+      // split as the verb lane. Unretried: the whole call reruns at the
+      // next session start, and hydration keeps the existing mirror.
+      const fetchImpl = resolveCursorApiFetch(options);
+      let response: Response;
+      try {
+        response = await fetchImpl(parsed.data.journal.url, {
+          method: "GET",
+          redirect: "manual",
+          signal: AbortSignal.timeout(STORE_API_FETCH_TIMEOUT_MS),
+        });
+      } catch (error) {
+        throw new StoreApiCallError(
+          "unavailable",
+          `memory.read journal fetch transport failure: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+      }
+      if (response.status === 404) {
+        // The presign raced a rotation or delete; absent is absent.
+        return undefined;
+      }
+      if (!response.ok) {
+        throw new StoreApiCallError(
+          "unavailable",
+          `memory.read journal fetch failed (HTTP ${response.status})`,
+          response.status
+        );
+      }
+      return new Uint8Array(await response.arrayBuffer());
+    },
+  };
+}

package/src/internal/deploy-manifest.ts

@@ -128,6 +128,10 @@ const agentDeployManifestV1Schema = z.object({
           continuation: continuationIdentitySchema,
           catch: catchDeclarationSchema.optional(),
           slackReply: slackReplyDeclarationSchema.optional(),
+          slackChannelPosts: z
+            .array(z.string().min(1).max(80))
+            .max(64)
+            .optional(),
         })
       )
       .max(64),
@@ -166,6 +170,14 @@ export interface AgentDeployManifestDeclarations {
      * hosted runtime starts. Present only for `slack` channels in agentic mode.
      */
     slackReply?: AgentDeployManifestSlackReplyDeclaration;
+    /**
+     * The channel-watch allowlist (`engagement.channelPosts.allow`).
+     * Present only for `slack` channels that watch channel posts. The
+     * control plane materializes channel-scoped subscription edges from
+     * the channel-id entries so posts outside the allowlist drop at
+     * ingress.
+     */
+    slackChannelPosts?: string[];
     /**
      * Control-plane catch routes: present only for an authored channel
      * whose auth chain carries a `sharedSecretAuth` / `hmacSignatureAuth`
@@ -242,6 +254,9 @@ export function buildAgentDeployManifest(
       ...(kind === "slack" && meta?.slackReply !== undefined
         ? { slackReply: meta.slackReply }
         : {}),
+      ...(kind === "slack" && meta?.slackChannelPosts !== undefined
+        ? { slackChannelPosts: [...meta.slackChannelPosts] }
+        : {}),
     };
   });
 

package/src/internal/reminder-runner.ts

@@ -16,6 +16,7 @@ import type {
   ReminderDefinition,
   ReminderFireContext,
   ReminderFireResult,
+  ReminderFollowupOptions,
   ReminderInfo,
   ReminderStatus,
   ReminderUntilContext,
@@ -1447,9 +1448,16 @@ export class ReminderRunner {
     record: ReminderRecord,
     message: string,
     auth: AuthContext | null,
-    settle?: FollowupSettle
+    settle?: FollowupSettle,
+    extra?: ReminderFollowupOptions
   ): Promise<ReminderFireResult> {
-    const sendOptions = this.followupSendOptions(record, auth);
+    const sendOptions: EngineSendOptions = {
+      ...this.followupSendOptions(record, auth),
+      state: extra?.state,
+      refreshState: extra?.refreshState,
+      title: extra?.title,
+      clearCloudOverride: extra?.clearCloudOverride,
+    };
     try {
       const session = await this.engine.send(
         record.channelId,
@@ -1509,8 +1517,19 @@ export class ReminderRunner {
       mcp: this.engine.host.mcp,
       appAuth: APP_AUTH,
       artifacts: this.engine.artifacts,
-      async followup(args: { message: string }) {
-        const { auth } = await self.resolveFollowupTarget(record);
+      async followup(args: { message: string } & ReminderFollowupOptions) {
+        const target = await self.resolveFollowupTarget(record);
+        let auth = target.auth;
+        // `openAuth` opens only when nothing exists anywhere: an unreadable
+        // durable session must not be shadowed by a second one on the same
+        // key (prompt-fire parity).
+        if (
+          auth === undefined &&
+          target.reached === "session_gone" &&
+          args.openAuth !== undefined
+        ) {
+          auth = args.openAuth;
+        }
         if (auth === undefined) {
           // Under the CP protocol the guest never writes reminder status;
           // the fire's `stop` outcome carries the reason instead.
@@ -1521,7 +1540,13 @@ export class ReminderRunner {
             `Reminder "${record.id}" followup: session gone for continuation`
           );
         }
-        const result = await self.sendFollowup(record, args.message, auth);
+        const result = await self.sendFollowup(
+          record,
+          args.message,
+          auth,
+          undefined,
+          args
+        );
         if (result.action === "skip") {
           throw new Error(
             `Reminder "${record.id}" followup skipped: session busy`

package/src/internal/session-engine.ts

@@ -1105,17 +1105,23 @@ export class SessionEngine {
         sendOptions.continuationToken
       );
     }
-    if (
-      existing === undefined &&
-      sendOptions.hostedSessionId !== undefined &&
-      sendOptions.mailboxContinuation?.key ===
-        hostedSessionResumeKey(sendOptions.hostedSessionId)
-    ) {
-      // Explicit control-plane resume of an existing session: the CP named
-      // the session by its own id and stamped the matching resume key. The
-      // session keeps its original continuation key (a PR lane must stay
-      // addressable by its webhooks); this is a follow-up turn by id.
-      existing = await this.getOrRestoreSession(sendOptions.hostedSessionId);
+    if (existing === undefined && sendOptions.hostedSessionId !== undefined) {
+      const byId = await this.getOrRestoreSession(sendOptions.hostedSessionId);
+      if (byId !== undefined) {
+        // evt: skips the mailbox index; same hostedSessionId is a Temporal
+        // retry. cont:session:<id> is the explicit CP resume (keep the
+        // original key so a PR lane stays addressable by its webhooks).
+        if (
+          byId.continuationKey !== sendOptions.continuationToken &&
+          sendOptions.mailboxContinuation?.key !==
+            hostedSessionResumeKey(sendOptions.hostedSessionId)
+        ) {
+          throw new V2EngineError(
+            `v2: hosted session id ${sendOptions.hostedSessionId} already belongs to another mailbox`
+          );
+        }
+        existing = byId;
+      }
     }
 
     if (existing !== undefined) {
@@ -1223,17 +1229,6 @@ export class SessionEngine {
       throw new HostedEnqueueNotActiveError(sendOptions.hostedSessionId);
     }
 
-    if (sendOptions.hostedSessionId !== undefined) {
-      const collision = await this.getOrRestoreSession(
-        sendOptions.hostedSessionId
-      );
-      if (collision !== undefined) {
-        throw new V2EngineError(
-          `v2: hosted session id ${sendOptions.hostedSessionId} already belongs to another mailbox`
-        );
-      }
-    }
-
     const now = new Date().toISOString();
     const channelState = this.initialChannelState(channelId, sendOptions.state);
     const purpose = sendOptions.purpose === "eval" ? "eval" : "live";