@cursor/july 0.2.0 → 0.2.1

package/src/internal/store-api-protocol.ts

@@ -0,0 +1,222 @@
+/**
+ * Domain-call wire contract for the factory store API:
+ * `POST /internal/agentsdk/store/api/<call>` carrying a versioned JSON
+ * envelope `{ v, call, payload }`. This is the lane where the **server** owns
+ * the storage pattern (journal sharding, rotation, compaction), so a
+ * pathological pattern is fixable in a backend deploy instead of a July
+ * release plus a rebake of every deployment. The verb lane (`/flush`,
+ * `/read`, `/list`) keeps carrying bulk presigned file IO.
+ *
+ * Deliberately duplicated on the backend
+ * (`backend/server/src/factory/agent-sdk/agentsdkStoreApiProtocol.ts`): this
+ * package is published to npm, so the backend cannot depend on it and it
+ * cannot depend on backend packages. A backend drift test compares the two
+ * sources — same shape as the hosted-delivery protocol twins — which is why
+ * every exported constant here stays a single `export const NAME = <literal>;`
+ * line and every schema field stays on its own line.
+ *
+ * Evolution rules (the compat contract): additive optional fields only; no
+ * renames, no retypes, no semantic reuse of an old field; unknown fields are
+ * ignored, never rejected; removing a field means deprecating it in place
+ * forever. A breaking change means a new `v`, and the server keeps serving
+ * every previous `v`.
+ */
+
+import { z } from "zod";
+
+export const STORE_API_PROTOCOL_VERSION = 1;
+
+/** Path family on the factory surface; one segment per call. */
+export const STORE_API_PATH = "/internal/agentsdk/store/api";
+
+export const STORE_API_MEMORY_APPEND_CALL = "memory.append";
+
+/**
+ * Semantic cap on one serialized memory record. Text fields are truncated
+ * client-side (`memoryHook` default 2000 chars per field), so a well-formed
+ * record is a few KiB; 16 KiB is generous headroom, not a target. The cap is
+ * part of the wire contract but rides the layers, not the schema: the
+ * backend's store controller enforces it as a typed 4xx, and the store API
+ * client (`cursor/store-api-client.ts`) pre-checks it before spending a
+ * doomed request.
+ */
+export const MEMORY_APPEND_MAX_RECORD_BYTES: number = 16 * 1024;
+
+/** Serialized size of a record, as counted against the byte cap. */
+export function serializedRecordBytes(record: unknown): number {
+  return new TextEncoder().encode(JSON.stringify(record)).byteLength;
+}
+
+/**
+ * One turn's memory record as it crosses the wire — July's
+ * `TurnMemoryRecord` (memory.ts). The extra-key record mirrors the schema's
+ * `.passthrough()`: a newer client's additive optional fields are journaled
+ * verbatim rather than stripped by an older server.
+ */
+export type TurnMemoryRecordWire = {
+  at: string;
+  sessionId: string;
+  channelId: string;
+  status: "completed" | "failed";
+  title?: string;
+  sdkAgentId?: string;
+  userMessage?: string;
+  result?: string;
+  usage?: Record<string, unknown>;
+} & Record<string, unknown>;
+
+/**
+ * Wire schema for {@link TurnMemoryRecordWire}. Per-field caps are
+ * deliberately absent: the client truncates text at authoring time and
+ * {@link MEMORY_APPEND_MAX_RECORD_BYTES} bounds the whole record.
+ */
+export const turnMemoryRecordWireSchema: z.ZodType<TurnMemoryRecordWire> = z
+  .object({
+    at: z.string().min(1),
+    sessionId: z.string().min(1),
+    channelId: z.string().min(1),
+    status: z.enum(["completed", "failed"]),
+    title: z.string().optional(),
+    sdkAgentId: z.string().optional(),
+    userMessage: z.string().optional(),
+    result: z.string().optional(),
+    usage: z.object({}).passthrough().optional(),
+  })
+  .passthrough();
+
+/** `memory.append` validated payload. */
+export type MemoryAppendPayload = {
+  agent: string;
+  record: TurnMemoryRecordWire;
+};
+
+/**
+ * `memory.append` payload shape. The agent name becomes a store key segment
+ * on the server, so it must be exactly one segment. Unknown payload fields
+ * are stripped (= ignored), per the evolution rules. The byte cap is
+ * semantics, not shape — the backend's store controller owns it.
+ */
+export const memoryAppendPayloadSchema: z.ZodType<MemoryAppendPayload> =
+  z.object({
+    agent: z
+      .string()
+      .min(1)
+      .max(256)
+      .refine(
+        name =>
+          !name.includes("/") &&
+          !name.includes("\\") &&
+          name !== "." &&
+          name !== "..",
+        { message: "agent must be a single store key segment" }
+      ),
+    record: turnMemoryRecordWireSchema,
+  });
+
+/** The versioned request body for the `memory.append` call. */
+export type MemoryAppendEnvelope = {
+  v: typeof STORE_API_PROTOCOL_VERSION;
+  call: typeof STORE_API_MEMORY_APPEND_CALL;
+  payload: MemoryAppendPayload;
+};
+
+/** The whole request body. Unknown envelope fields are stripped (= ignored). */
+export const memoryAppendEnvelopeSchema: z.ZodType<MemoryAppendEnvelope> =
+  z.object({
+    v: z.literal(STORE_API_PROTOCOL_VERSION),
+    call: z.literal(STORE_API_MEMORY_APPEND_CALL),
+    payload: memoryAppendPayloadSchema,
+  });
+
+/** `memory.append` success body. */
+export type MemoryAppendResponse = {
+  v: typeof STORE_API_PROTOCOL_VERSION;
+  ok: true;
+};
+
+/**
+ * Success body. Failures answer the store surface's standard error JSON
+ * (`{ code, error }`) with a matching HTTP status.
+ */
+export const memoryAppendResponseSchema: z.ZodType<MemoryAppendResponse> =
+  z.object({
+    v: z.literal(STORE_API_PROTOCOL_VERSION),
+    ok: z.literal(true),
+  });
+
+export const STORE_API_MEMORY_READ_CALL = "memory.read";
+
+/** `memory.read` validated payload. */
+export type MemoryReadPayload = {
+  agent: string;
+};
+
+/**
+ * `memory.read` payload shape — the same single-segment agent name rule as
+ * `memory.append`, since the name addresses the same journal key family.
+ */
+export const memoryReadPayloadSchema: z.ZodType<MemoryReadPayload> = z.object({
+  agent: z
+    .string()
+    .min(1)
+    .max(256)
+    .refine(
+      name =>
+        !name.includes("/") &&
+        !name.includes("\\") &&
+        name !== "." &&
+        name !== "..",
+      { message: "agent must be a single store key segment" }
+    ),
+});
+
+/** The versioned request body for the `memory.read` call. */
+export type MemoryReadEnvelope = {
+  v: typeof STORE_API_PROTOCOL_VERSION;
+  call: typeof STORE_API_MEMORY_READ_CALL;
+  payload: MemoryReadPayload;
+};
+
+/** The whole request body. Unknown envelope fields are stripped (= ignored). */
+export const memoryReadEnvelopeSchema: z.ZodType<MemoryReadEnvelope> = z.object(
+  {
+    v: z.literal(STORE_API_PROTOCOL_VERSION),
+    call: z.literal(STORE_API_MEMORY_READ_CALL),
+    payload: memoryReadPayloadSchema,
+  }
+);
+
+/**
+ * `memory.read` success body. The call is flush-on-read: the server drains
+ * the agent's pending append buffer before presigning. Best-effort: when
+ * the drain succeeds the journal includes every append that preceded the
+ * read; a busy flush lock, a buffer outage, or an oversized backlog
+ * degrades to the already-flushed state (callers must not regress their
+ * local view on a shorter download). `journal` is null while the agent has
+ * no journal at all.
+ */
+export type MemoryReadResponse = {
+  v: typeof STORE_API_PROTOCOL_VERSION;
+  ok: true;
+  journal: {
+    url: string;
+    expiresAt: string;
+  } | null;
+};
+
+/**
+ * Success body. Failures answer the store surface's standard error JSON
+ * (`{ code, error }`) with a matching HTTP status.
+ */
+export const memoryReadResponseSchema: z.ZodType<MemoryReadResponse> = z.object(
+  {
+    v: z.literal(STORE_API_PROTOCOL_VERSION),
+    ok: z.literal(true),
+    journal: z
+      .object({
+        url: z.string().min(1),
+        expiresAt: z.string().min(1),
+      })
+      .nullable(),
+  }
+);

package/src/memory.ts

@@ -18,20 +18,29 @@
  *
  * On Cursor-managed hosting the default is {@link agentStoreMemoryBackend}:
  * the journal lives on the deployment's Agent Store (survives deploys,
- * visible on cloud VMs under the store mount) and is mirrored to
- * `<stateRoot>/memory/journal.jsonl` so the workspace symlink read path
- * keeps working for local-runtime turns.
+ * visible on cloud VMs under the store mount), written exclusively through
+ * the `memory.append` domain call — the server owns the journal pattern —
+ * and mirrored to `<stateRoot>/memory/journal.jsonl` (hydrated per session
+ * via `memory.read`, appended locally per turn) so the workspace symlink
+ * read path keeps working for local-runtime turns. The
+ * `factory-api-v1` pin file exists only on hosted pods — plain local dev
+ * runs {@link fileMemoryBackend} and never sees the hosted lane.
  */
 
 import { randomUUID } from "node:crypto";
 import { appendFile, mkdir, rename, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { agentStoreKeys, FileConflictError, type FileSink } from "./files.js";
+import { agentStoreKeys } from "./files.js";
 import {
-  cursorHostedFiles,
+  type CursorHostedFilesOptions,
   isCursorHostedFilesAvailable,
 } from "./files-backends/cursor-hosted.js";
 import { defineHook } from "./hooks.js";
+import {
+  createStoreApiClient,
+  isStoreApiLaneEnabled,
+  type StoreApiClient,
+} from "./internal/cursor/store-api-client.js";
 import type { HookContext, HookDefinition, TurnUsage } from "./types.js";
 
 /** Name of the shared memory directory under the agent state root. */
@@ -61,6 +70,13 @@ export interface MemoryBackend {
     record: TurnMemoryRecord,
     ctx: { stateRoot: string; agentName: string }
   ): Promise<void>;
+  /**
+   * Optional session-start hook: bring the backend's local read path up to
+   * date before the session's first turn reads it. A freshness upgrade, not
+   * a correctness gate — implementations soft-fail and keep whatever read
+   * state already exists.
+   */
+  prepareSession?(ctx: { stateRoot: string; agentName: string }): Promise<void>;
 }
 
 export interface FileMemoryBackendOptions {
@@ -113,120 +129,233 @@ export function fileMemoryBackend(
 }
 
 export interface AgentStoreMemoryBackendOptions {
-  /** Sink override (tests). Defaults to the deployment's Agent Store. */
-  sink?: FileSink;
-  /** Rotation threshold, same meaning as {@link FileMemoryBackendOptions}. */
+  /**
+   * Local mirror rotation threshold, same meaning as
+   * {@link FileMemoryBackendOptions}. The durable journal's rotation is the
+   * server's (`memory.append` controller), not this.
+   */
   maxJournalBytes?: number;
-  /** Backoff sleep override (tests). */
-  sleep?: (ms: number) => Promise<void>;
-  /** Jitter source override (tests). Returns [0, 1). */
-  random?: () => number;
-}
-
-/**
- * CAS attempts per append. The journal is one deployment-wide key written by
- * every engine pod, so under concurrent turn traffic the etag precondition
- * loses races routinely; each retry needs headroom to land.
- */
-const MEMORY_CAS_MAX_ATTEMPTS = 5;
-
-/**
- * Jittered exponential backoff between CAS attempts. Retrying immediately is
- * a fleet-wide stampede: every losing pod re-GETs the full journal and
- * re-PUTs in lockstep, which multiplied reads ~65x on one deployment during
- * the 2026-09-18 Agent Store read storm and tripped the store's
- * per-service-account read limit (every pod shares the deployment
- * credential). Jitter desynchronizes the writers so most retries land on the
- * first or second attempt.
- */
-function memoryCasBackoffMs(attempt: number, random: () => number): number {
-  return 100 * 2 ** attempt * (0.5 + random());
+  /**
+   * Cursor-hosted transport overrides (tests): base URL, credential, store
+   * source id, protocol pin, fetch. Feeds the default
+   * {@link storeApiClient} and the lane-availability check.
+   */
+  hosted?: CursorHostedFilesOptions;
+  /**
+   * Domain-lane client override (tests). Defaults to
+   * {@link createStoreApiClient} over {@link hosted} — the module that owns
+   * the `memory.append` / `memory.read` transport, typed errors, and
+   * bounded backoff.
+   */
+  storeApiClient?: StoreApiClient;
 }
 
 /**
  * Journal on the deployment's Agent Store — durable across deploys, visible
- * on cloud VMs under the store mount. Appends are read-modify-write with
- * etag preconditions (retried on a lost race), then mirrored to
- * `<stateRoot>/memory/journal.jsonl` for the workspace symlink read path.
+ * on cloud VMs under the store mount, written exclusively through the
+ * `memory.append` domain call: the server owns the journal's storage
+ * pattern (Redis-buffered flush, rotation), so a pathological pattern is
+ * fixable in a backend deploy instead of a July release plus a rebake.
+ *
+ * There is no client-composed fallback. The read-modify-write CAS lane that
+ * predated the domain call (and caused the 2026-09-18 Agent Store read
+ * storm) was removed in 0.2.1 together with v2 hosting binding the
+ * `factory-api-v1` pin unconditionally and refusing artifacts frozen on an
+ * older July. A hosted pod without the pin is therefore a misconfiguration
+ * (a server predating the pin change, or a local env naming a hosted store
+ * without one): records are dropped loudly, never written client-side.
  */
 export function agentStoreMemoryBackend(
   options: AgentStoreMemoryBackendOptions = {}
 ): MemoryBackend {
-  const sink = options.sink ?? cursorHostedFiles();
+  const hosted = options.hosted ?? {};
   const maxJournalBytes = options.maxJournalBytes ?? 5 * 1024 * 1024;
-  const sleep =
-    options.sleep ??
-    ((ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms)));
-  const random = options.random ?? Math.random;
-  // Appends are chained per journal key (same shape as fileMemoryBackend);
-  // a failed append must not poison the chain for later turns. The chain
-  // serializes appends within this pod only — pods race each other on the
-  // shared key, which is what the CAS retry (with backoff) absorbs.
+  // Mirror work is chained per journal key (same shape as
+  // fileMemoryBackend): hydration and appends on one agent's mirror never
+  // interleave, and a failed step must not poison the chain for later turns.
   const appendChains = new Map<string, Promise<void>>();
 
-  const append = async (
+  // Transport, envelope, typed errors, and bounded backoff all live in the
+  // client; this module only decides which lane an append takes.
+  const storeApiClient = options.storeApiClient ?? createStoreApiClient(hosted);
+
+  /**
+   * The domain lane still owes local-runtime sessions their read path:
+   * cloud-runtime turns read the journal through the store mount, but
+   * local-runtime turns on hosted pods (the default `runtime: "local"`)
+   * read `<stateRoot>/memory/journal.jsonl` via the workspace symlink, and
+   * on hosting the only writer of that file is this backend. So the lane
+   * keeps the mirror live without reintroducing the CAS read pattern:
+   * hydrate it once from the store when the file is absent (a fresh pod
+   * after a deploy), then append each successfully posted record locally,
+   * rotating at {@link maxJournalBytes} like {@link fileMemoryBackend}.
+   * Server-buffered records not yet flushed when a pod hydrates are the
+   * lane's documented staleness window (~30 s / 64 KiB), and other pods'
+   * appends surface on the next hydration — advisory memory, same envelope
+   * as the server side.
+   */
+  const hydratedMirrors = new Set<string>();
+  let mirrorRotationSeq = 0;
+  const maintainLocalMirror = async (
     record: TurnMemoryRecord,
     ctx: { stateRoot: string; agentName: string }
   ): Promise<void> => {
-    const key = agentStoreKeys.memoryJournal(ctx.agentName);
-    const line = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
-    for (let attempt = 0; attempt < MEMORY_CAS_MAX_ATTEMPTS; attempt += 1) {
-      const current = await sink.get(key);
-      const currentBody =
-        current === undefined
-          ? new Uint8Array(0)
-          : current instanceof Uint8Array
-            ? current
-            : current.body;
-      const etag =
-        current === undefined || current instanceof Uint8Array
-          ? undefined
-          : current.etag;
-      let next: Uint8Array;
-      let rotatedStamp: string | undefined;
-      if (currentBody.byteLength >= maxJournalBytes) {
-        rotatedStamp = `${Date.now()}-${randomUUID().slice(0, 8)}`;
-        await sink.put(
-          agentStoreKeys.memoryJournalRotated(ctx.agentName, rotatedStamp),
-          currentBody,
-          { ifMatch: null }
-        );
-        next = line;
-      } else {
-        next = Buffer.concat([currentBody, line]);
-      }
-      try {
-        await sink.put(key, next, {
-          ifMatch: current === undefined ? null : etag,
+    const dir = join(ctx.stateRoot, MEMORY_DIR_NAME);
+    const path = join(dir, "journal.jsonl");
+    if (!hydratedMirrors.has(path)) {
+      // Appends are chained per journal key, so this guard never races
+      // itself for one agent. Backstop for a session that appended before
+      // any prepareSession hydration ran (e.g. a custom hook ordering).
+      hydratedMirrors.add(path);
+      const existing = await stat(path).catch(() => undefined);
+      if (existing === undefined) {
+        const content = await storeApiClient.memoryReadContent({
+          agent: ctx.agentName,
         });
-      } catch (error) {
-        if (
-          error instanceof FileConflictError &&
-          attempt < MEMORY_CAS_MAX_ATTEMPTS - 1
-        ) {
-          await sleep(memoryCasBackoffMs(attempt, random));
-          continue;
+        if (content !== undefined) {
+          await mirrorJournalLocally(ctx.stateRoot, content);
         }
-        throw error;
-      }
-      await mirrorJournalLocally(ctx.stateRoot, next);
-      if (rotatedStamp !== undefined) {
-        // Rotated segments sit beside the live journal locally too, so the
-        // workspace symlink read path keeps pre-rotation history.
-        await writeFile(
-          join(ctx.stateRoot, MEMORY_DIR_NAME, `journal-${rotatedStamp}.jsonl`),
-          currentBody
-        );
       }
+    }
+    await mkdir(dir, { recursive: true });
+    const size = (await stat(path).catch(() => undefined))?.size ?? 0;
+    if (size >= maxJournalBytes) {
+      mirrorRotationSeq += 1;
+      await rename(
+        path,
+        join(dir, `journal-${Date.now()}-${mirrorRotationSeq}.jsonl`)
+      );
+    }
+    await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
+  };
+
+  /**
+   * One `memory.append` domain call; the server appends to the server-owned
+   * journal. On success the record is also appended to the local mirror so
+   * the workspace symlink read path stays live (see
+   * {@link maintainLocalMirror}).
+   *
+   * Failure policy: log and give up for this record. Memory is advisory and
+   * the hook runner treats an append failure as non-fatal to the turn;
+   * falling back to the CAS path per-record would reintroduce the write
+   * storm under exactly the server brownout that makes this call fail. A
+   * failed POST also skips the mirror — the mirror must never show a record
+   * the durable journal will not have.
+   */
+  const appendViaStoreApi = async (
+    record: TurnMemoryRecord,
+    ctx: { stateRoot: string; agentName: string }
+  ): Promise<void> => {
+    try {
+      await storeApiClient.memoryAppend({ agent: ctx.agentName, record });
+    } catch (error) {
+      console.warn(
+        `[agent-serve] memory.append dropped one record for "${ctx.agentName}": ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
       return;
     }
+    try {
+      await maintainLocalMirror(record, ctx);
+    } catch (error) {
+      console.warn(
+        `[agent-serve] memory mirror update failed for "${ctx.agentName}" (journal record is durable): ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  };
+
+  /**
+   * Session-start hydration: one `memory.read` (flush-on-read server-side,
+   * so the pending buffer — including a burst another pod appended — lands
+   * first) and the mirror is rewritten to global state; the session then
+   * reads everything appended before it started. Soft-fail: a failed
+   * hydration keeps the existing mirror.
+   */
+  const hydrateMirror = async (ctx: {
+    stateRoot: string;
+    agentName: string;
+  }): Promise<void> => {
+    const path = join(ctx.stateRoot, MEMORY_DIR_NAME, "journal.jsonl");
+    try {
+      const content = await storeApiClient.memoryReadContent({
+        agent: ctx.agentName,
+      });
+      if (content !== undefined) {
+        // Never regress the read path: every mirrored record was
+        // server-acked before it was written locally, so a download SHORTER
+        // than the mirror means the server's flush-on-read was degraded (a
+        // busy lock, a Redis outage — the acked tail is still buffered) or
+        // the journal rotated. Keeping the richer mirror loses nothing;
+        // rewriting would hide records the agent has already seen.
+        const mirroredBytes =
+          (await stat(path).catch(() => undefined))?.size ?? 0;
+        if (content.byteLength >= mirroredBytes) {
+          await mirrorJournalLocally(ctx.stateRoot, content);
+        }
+      }
+      // Either way the read answered: skip the append path's absent-file
+      // hydration for the rest of this process.
+      hydratedMirrors.add(path);
+    } catch (error) {
+      console.warn(
+        `[agent-serve] memory hydration failed for "${ctx.agentName}" (keeping the existing mirror): ${
+          error instanceof Error ? error.message : String(error)
+        }`
+      );
+    }
+  };
+
+  /**
+   * Hosted pods carry the pin and a provisioned store by construction (v2
+   * hosting binds `factory-api-v1` unconditionally and refuses pre-0.2.1
+   * artifacts). Reaching this without them means a misconfigured
+   * environment; there is no client-side write to fall back to.
+   */
+  const refuseMisconfiguredLane = (agentName: string, verb: string): void => {
+    console.error(
+      `[agent-serve] memory ${verb} for "${agentName}" dropped: the store API lane is unavailable (missing/foreign AGENT_SERVE_STORE_PROTOCOL pin or no provisioned store). This July has no client-side journal fallback; fix the hosting pin.`
+    );
   };
 
   return {
+    async prepareSession(ctx) {
+      // Chained on the same per-journal key as appends, so hydration never
+      // interleaves with an append's mirror write.
+      const key = agentStoreKeys.memoryJournal(ctx.agentName);
+      const prior = appendChains.get(key) ?? Promise.resolve();
+      const next = prior
+        .catch(() => {})
+        .then(async () => {
+          if (!isStoreApiLaneEnabled(hosted)) {
+            refuseMisconfiguredLane(ctx.agentName, "hydration");
+            return;
+          }
+          await hydrateMirror(ctx);
+        });
+      appendChains.set(key, next);
+      await next;
+    },
+
     async appendTurn(record, ctx) {
+      // Soft-fail by construction (appendViaStoreApi never throws), but
+      // still chained per journal key: the local mirror's hydrate-then-
+      // append must not interleave with itself. Lane availability is
+      // re-resolved lazily per append, so a pin bound after serve start
+      // takes effect without a restart.
       const key = agentStoreKeys.memoryJournal(ctx.agentName);
       const prior = appendChains.get(key) ?? Promise.resolve();
-      const next = prior.catch(() => {}).then(() => append(record, ctx));
+      const next = prior
+        .catch(() => {})
+        .then(async () => {
+          if (!isStoreApiLaneEnabled(hosted)) {
+            refuseMisconfiguredLane(ctx.agentName, "append");
+            return;
+          }
+          await appendViaStoreApi(record, ctx);
+        });
       appendChains.set(key, next);
       await next;
     },
@@ -334,6 +463,24 @@ export function memoryHook(options: MemoryHookOptions = {}): HookDefinition {
 
   return defineHook({
     events: {
+      async "session.started"(_event, ctx) {
+        // Bring the mirror (the workspace symlink read path) up to date
+        // before the session's first turn reads it. Backends without a
+        // prepareSession (plain files) have nothing to freshen. Soft-fail:
+        // hydration is a freshness upgrade, never a turn blocker.
+        try {
+          await backend.prepareSession?.({
+            stateRoot: ctx.stateRoot,
+            agentName: ctx.agent.name,
+          });
+        } catch (error) {
+          console.warn(
+            `[agent-serve] memory hydration at session start failed: ${
+              error instanceof Error ? error.message : String(error)
+            }`
+          );
+        }
+      },
       async "message.received"(event, ctx) {
         pendingMessages.set(
           pendingKey(ctx, event.turnId),

package/src/reminders.ts

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

package/src/types.ts

@@ -3000,6 +3000,34 @@ export interface ReminderUntilContext {
   mcp: HostMcpRegistry;
 }
 
+/**
+ * Send fields a reminder followup may carry onto the turn it starts, the
+ * subset of {@link SendMessageOptions} a host pipeline needs when the fire
+ * itself prepares the turn (channel state for a later `defineResult.commit`,
+ * a session title, a cloud-attach reset). Continuation addressing stays the
+ * reminder's stored binding and is not overridable here.
+ */
+export interface ReminderFollowupOptions {
+  /** Initial channel state when the followup creates the session. */
+  state?: JsonValue;
+  /** Shallow-merged into an existing session's channel state (see {@link SendMessageOptions.refreshState}). */
+  refreshState?: JsonValue;
+  /** Session display title (applied when creating a new session). */
+  title?: string;
+  /** See {@link SendMessageOptions.clearCloudOverride}. */
+  clearCloudOverride?: boolean;
+  /**
+   * Open a new session under this principal when the stored continuation
+   * has none anywhere (pod or durable storage) — the session an inbound
+   * delivery on that key would create, so later deliveries under the same
+   * principal keep joining it. A durable session that exists but cannot be
+   * materialized still throws, matching prompt fires: opening over it would
+   * shadow the record. Omitted, a missing session also keeps the existing
+   * behavior: the followup throws.
+   */
+  openAuth?: AuthContext;
+}
+
 export interface ReminderFireContext extends ReminderUntilContext {
   appAuth: AuthContext;
   /**
@@ -3013,7 +3041,9 @@ export interface ReminderFireContext extends ReminderUntilContext {
    * completes, because the pod may stop once the fire's outcome is applied;
    * locally and on v1 it resolves as soon as the turn is admitted.
    */
-  followup(args: { message: string }): Promise<ChannelSession>;
+  followup(
+    args: { message: string } & ReminderFollowupOptions
+  ): Promise<ChannelSession>;
   cancel(reason?: string): Promise<void>;
   /**
    * Durable artifacts (unbound — the reminder is bound to a continuation