@cursor/july 0.1.114 → 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-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/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/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 (