@cursor/july 0.1.8 → 0.1.10

package/src/internal/session-engine.ts

@@ -45,6 +45,7 @@ import {
   type SessionEvent,
   type SessionEventPayload,
   type SessionInfo,
+  type SessionListSource,
   type SessionRecord,
   type SessionSummary,
   type SlackNudgeHostApi,
@@ -73,7 +74,6 @@ import {
 import { validateToolInput } from "./json-schema.js";
 import { McpHost } from "./mcp-host.js";
 import {
-  buildIdentitySection,
   buildSessionContextBlock,
   SCHEDULE_CHANNEL_PREFIX,
 } from "./prompt-context.js";
@@ -83,7 +83,8 @@ import { SessionStore } from "./session-store.js";
 import { StorageCoordinator } from "./storage-coordinator.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
 import {
-  buildAgentToolsCatalog,
+  buildAgentsMdContent,
+  isNestedInGitRepo,
   materializeWorkspace,
   writeWorkspaceFiles,
 } from "./workspace.js";
@@ -1019,12 +1020,22 @@ export class SessionEngine {
           return rest;
         });
       }
+      // The harness only loads the scaffolded AGENTS.md when the session
+      // workspace is its own project root. With a per-session cwd override
+      // (PR worktree) the scaffold lands elsewhere, and a workspace nested
+      // inside a git repo re-roots harness rules at that repo — in both
+      // cases deliver instructions inline on the first turn instead.
+      const instructionsInvisibleToHarness =
+        isFirstTurn &&
+        (record.workspaceOverride !== undefined ||
+          (await isNestedInGitRepo(harnessCwd)));
       const request = this.buildTurnRequest(
         record,
         agent,
         turnId,
         message,
         isFirstTurn,
+        instructionsInvisibleToHarness,
         emit,
         async (update) => {
           mapper.handleUpdate(update);
@@ -1120,6 +1131,7 @@ export class SessionEngine {
     turnId: string,
     prompt: string,
     isFirstTurn: boolean,
+    instructionsInvisibleToHarness: boolean,
     emit: (payload: SessionEventPayload) => void,
     onUpdate: RunnerTurnRequest["onUpdate"],
     signal: AbortSignal
@@ -1147,15 +1159,21 @@ export class SessionEngine {
       });
       turnPrompt = `${contextBlock}\n\n${prompt}`;
     }
-    if (runtime === "cloud" && isFirstTurn) {
-      const preamble = [
-        agent.instructions?.trim() ?? "",
-        buildIdentitySection(agent),
-        buildAgentToolsCatalog(agent.tools, { includeScripts: true }),
-      ]
-        .filter((part) => part !== "")
-        .join("\n\n");
-      turnPrompt = `${preamble}\n\n${turnPrompt}`;
+    if (isFirstTurn) {
+      if (runtime === "cloud") {
+        // Cloud VMs have no materialized workspace: ship the full context,
+        // including agent tool script bodies.
+        const preamble = buildAgentsMdContent(agent, { includeScripts: true });
+        turnPrompt = `${preamble}\n\n${turnPrompt}`;
+      } else if (instructionsInvisibleToHarness) {
+        // Local workspace whose AGENTS.md the harness will not load. With a
+        // per-session harness cwd override, agent tool scripts live only in
+        // the durable scaffold dir — embed bodies like cloud. Otherwise the
+        // catalog can reference on-disk paths under the harness cwd.
+        const includeScripts = record.workspaceOverride !== undefined;
+        const preamble = buildAgentsMdContent(agent, { includeScripts });
+        turnPrompt = `${preamble}\n\n${turnPrompt}`;
+      }
     }
     return {
       sessionId: record.sessionId,
@@ -1810,13 +1828,88 @@ export class SessionEngine {
    * observability surface across every principal (channel-driven runs,
    * schedule/task sessions, other callers). The route auth chain still
    * gates who may call this at all.
+   *
+   * When the project uses `cursorHostedStorage`, prefers durable Bugbot rows
+   * (merged with any newer local records not flushed yet). Falls back to the
+   * local `--state-root` store when the sink is unavailable.
    */
   async listSessions(
     caller: AuthContext | null,
     options?: { includeAll?: boolean }
   ): Promise<SessionSummary[]> {
+    return (await this.listSessionsWithSource(caller, options)).sessions;
+  }
+
+  /**
+   * Same as {@link listSessions}, plus which store answered
+   * (`cursor-hosted` = durable DB via the control-plane proxy; `local` =
+   * `--state-root`).
+   */
+  async listSessionsWithSource(
+    caller: AuthContext | null,
+    options?: { includeAll?: boolean }
+  ): Promise<{ sessions: SessionSummary[]; source: SessionListSource }> {
     const includeAll = options?.includeAll ?? false;
+    if (this.storage?.isCursorHosted === true) {
+      try {
+        const records = await this.mergeStoredAndLocalSessions();
+        return {
+          sessions: this.summarizeSessionRecords(records, caller, includeAll),
+          source: "cursor-hosted",
+        };
+      } catch (error) {
+        this.logger(
+          `[agentkit] cursor-hosted session list failed; falling back to local: ${describeError(error)}`
+        );
+      }
+    }
     const records = await this.sessions.list();
+    // Local store is createdAt-asc; reverse so newest created leads.
+    return {
+      sessions: this.summarizeSessionRecords(
+        [...records].reverse(),
+        caller,
+        includeAll
+      ),
+      source: "local",
+    };
+  }
+
+  /**
+   * Durable sink rows plus local records (local wins on the same id when
+   * newer — covers debounce windows that have not flushed yet). Newest
+   * `updatedAt` first.
+   */
+  private async mergeStoredAndLocalSessions(): Promise<SessionRecord[]> {
+    const storage = this.storage;
+    if (storage === undefined) {
+      throw new Error("storage is not configured");
+    }
+    const stored = await storage.listSessionsFromSink();
+    const local = await this.sessions.list();
+    const byId = new Map<string, SessionRecord>();
+    for (const record of stored) {
+      byId.set(record.sessionId, record);
+    }
+    for (const record of local) {
+      const existing = byId.get(record.sessionId);
+      if (
+        existing === undefined ||
+        record.updatedAt.localeCompare(existing.updatedAt) >= 0
+      ) {
+        byId.set(record.sessionId, record);
+      }
+    }
+    return [...byId.values()].sort((a, b) =>
+      b.updatedAt.localeCompare(a.updatedAt)
+    );
+  }
+
+  private summarizeSessionRecords(
+    records: readonly SessionRecord[],
+    caller: AuthContext | null,
+    includeAll: boolean
+  ): SessionSummary[] {
     return records
       .filter((record) => includeAll || samePrincipal(record.auth, caller))
       .map((record) => {
@@ -1841,8 +1934,7 @@ export class SessionEngine {
                 ),
           ...(externalUrl === undefined ? {} : { externalUrl }),
         };
-      })
-      .reverse();
+      });
   }
 
   /**

package/src/internal/sessions-client.ts

@@ -4,15 +4,33 @@
  * Customer-facing errors never include hosting URLs or infra jargon.
  */
 
-import type { SessionEvent, SessionSummary } from "../types.js";
+import type {
+  SessionEvent,
+  SessionListSource,
+  SessionSummary,
+} from "../types.js";
 import { sanitizeCustomerError } from "./logs-client.js";
 import { mergeRequestHeaders, type RequestAuth } from "./request-headers.js";
 
+export interface ListedSessions {
+  sessions: SessionSummary[];
+  /** Present when the server reports which store answered. */
+  source?: SessionListSource;
+}
+
 export async function listSessions(args: {
   baseUrl: string;
   auth?: RequestAuth;
   fetchImpl?: typeof fetch;
 }): Promise<SessionSummary[]> {
+  return (await listSessionsWithSource(args)).sessions;
+}
+
+export async function listSessionsWithSource(args: {
+  baseUrl: string;
+  auth?: RequestAuth;
+  fetchImpl?: typeof fetch;
+}): Promise<ListedSessions> {
   const baseUrl = args.baseUrl.replace(/\/$/, "");
   const fetchImpl = args.fetchImpl ?? fetch;
   let resp: Response;
@@ -30,18 +48,21 @@ export async function listSessions(args: {
   if (!resp.ok) {
     throw new Error(`Could not list sessions (HTTP ${resp.status}).`);
   }
-  const body = (await resp.json()) as { sessions?: unknown };
-  if (!Array.isArray(body.sessions)) {
-    return [];
-  }
-  const out: SessionSummary[] = [];
-  for (const row of body.sessions) {
-    const parsed = parseSessionSummary(row);
-    if (parsed !== undefined) {
-      out.push(parsed);
+  const body = (await resp.json()) as { sessions?: unknown; source?: unknown };
+  const sessions: SessionSummary[] = [];
+  if (Array.isArray(body.sessions)) {
+    for (const row of body.sessions) {
+      const parsed = parseSessionSummary(row);
+      if (parsed !== undefined) {
+        sessions.push(parsed);
+      }
     }
   }
-  return out;
+  const source =
+    body.source === "cursor-hosted" || body.source === "local"
+      ? body.source
+      : undefined;
+  return source === undefined ? { sessions } : { sessions, source };
 }
 
 export async function fetchSessionEvents(args: {
@@ -186,10 +207,24 @@ export async function resolvePreviousSessionId(args: {
   return pickPreviousSession(sessions)?.sessionId;
 }
 
+/** Human label for {@link SessionListSource} in CLI output. */
+export function formatSessionListSource(source: SessionListSource): string {
+  return source === "cursor-hosted"
+    ? "Listing from cursor-hosted storage (durable DB)."
+    : "Listing from local session store.";
+}
+
 /** Format a sessions table (id, channel, mode, turns, running, updated). */
-export function formatSessionsTable(sessions: SessionSummary[]): string {
+export function formatSessionsTable(
+  sessions: SessionSummary[],
+  options?: { source?: SessionListSource }
+): string {
+  const sourceLine =
+    options?.source === undefined
+      ? ""
+      : `${formatSessionListSource(options.source)}\n`;
   if (sessions.length === 0) {
-    return "No sessions.\n";
+    return `${sourceLine}No sessions.\n`;
   }
   const header = ["SESSION", "CHANNEL", "MODE", "TURNS", "RUNNING", "UPDATED"];
   const rows = sessions.map((s) => [
@@ -200,7 +235,7 @@ export function formatSessionsTable(sessions: SessionSummary[]): string {
     s.running ? "yes" : "no",
     s.updatedAt,
   ]);
-  return `${renderTable(header, rows)}\n`;
+  return `${sourceLine}${renderTable(header, rows)}\n`;
 }
 
 function renderTable(header: string[], rows: string[][]): string {

package/src/internal/storage-coordinator.ts

@@ -24,6 +24,7 @@ import {
   type StorageDefinition,
   storageKeys,
 } from "../storage.js";
+import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
 import type { JsonValue, SessionEvent, SessionRecord } from "../types.js";
 import type { ABSnapshot } from "./ab-snapshot.js";
 import { describeError } from "./describe-error.js";
@@ -261,6 +262,14 @@ export class StorageCoordinator {
     return this.definition.list !== undefined;
   }
 
+  /**
+   * True when the authored sink is `cursorHostedStorage` (Bugbot via the
+   * control-plane proxy). `GET /v1/sessions` prefers this durable list.
+   */
+  get isCursorHosted(): boolean {
+    return isCursorHostedStorage(this.definition);
+  }
+
   /**
    * Saved session records for this agent (startup restore). Errors are
    * logged and read as "nothing saved" — a broken store must never block
@@ -275,6 +284,33 @@ export class StorageCoordinator {
       .filter((record) => record != null);
   }
 
+  /**
+   * Session records from the sink for the sessions API. Unlike
+   * {@link listSessions}, missing `list` or a thrown sink error **propagates**
+   * so the caller can fall back to the local session store.
+   */
+  async listSessionsFromSink(): Promise<SessionRecord[]> {
+    const list = this.definition.list;
+    if (list === undefined) {
+      throw new Error("storage sink has no list");
+    }
+    const entries = await list(
+      storageKeys.sessionPrefix(this.agentName),
+      this.context("restore")
+    );
+    if (!Array.isArray(entries)) {
+      throw new Error("storage list returned a non-array");
+    }
+    return entries
+      .map((entry) => entry.value as unknown as SessionRecord)
+      .filter(
+        (record) =>
+          record != null &&
+          typeof record.sessionId === "string" &&
+          record.sessionId !== ""
+      );
+  }
+
   /**
    * Saved event stream for one session: chunk values concatenated in key
    * order (chunks are keyed by their first event's index, zero-padded, so

package/src/internal/workspace.ts

@@ -8,7 +8,7 @@
  */
 
 import { chmod, copyFile, mkdir, stat, writeFile } from "node:fs/promises";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, join, parse, relative, resolve } from "node:path";
 import type {
   DiscoveredSkill,
   DiscoveredTool,
@@ -123,22 +123,59 @@ export function buildAgentToolsCatalog(
   return `${parts.join("\n").trimEnd()}\n`;
 }
 
+/**
+ * The full AGENTS.md-equivalent context for an agent: instructions, identity
+ * section, and the agent-side tool catalog. Written to the session workspace
+ * as `AGENTS.md`, and inlined into the first turn's prompt when the harness
+ * cannot discover that file (cloud runtime, or a local workspace the harness
+ * will not treat as the project root — see {@link isNestedInGitRepo}).
+ */
+export function buildAgentsMdContent(
+  agent: ResolvedAgent,
+  options: { includeScripts: boolean }
+): string {
+  return [
+    agent.instructions?.trim() ?? "",
+    buildIdentitySection(agent),
+    buildAgentToolsCatalog(agent.tools, {
+      includeScripts: options.includeScripts,
+    }),
+  ]
+    .filter((part) => part !== "")
+    .join("\n\n");
+}
+
+/**
+ * True when `dir` sits strictly inside a git repository (a `.git` exists in
+ * an ancestor directory but not in `dir` itself). The Cursor harness resolves
+ * its project root by walking up to the nearest git root, so a nested session
+ * workspace loses its own `AGENTS.md` / `.cursor` scaffold: the enclosing
+ * repo's rules load instead, and the (necessarily gitignored) workspace files
+ * are skipped by nested rule discovery.
+ */
+export async function isNestedInGitRepo(dir: string): Promise<boolean> {
+  let current = resolve(dir);
+  if (await exists(join(current, ".git"))) {
+    // The workspace is itself a repo root; the harness roots rules here.
+    return false;
+  }
+  const { root } = parse(current);
+  while (current !== root) {
+    current = dirname(current);
+    if (await exists(join(current, ".git"))) {
+      return true;
+    }
+  }
+  return false;
+}
+
 export async function materializeWorkspace(
   options: MaterializeWorkspaceOptions
 ): Promise<void> {
   const { agent, workspaceDir, seed } = options;
   await mkdir(workspaceDir, { recursive: true });
 
-  const agentToolsSection = buildAgentToolsCatalog(agent.tools, {
-    includeScripts: false,
-  });
-  const agentsMd = [
-    agent.instructions?.trim() ?? "",
-    buildIdentitySection(agent),
-    agentToolsSection,
-  ]
-    .filter((part) => part !== "")
-    .join("\n\n");
+  const agentsMd = buildAgentsMdContent(agent, { includeScripts: false });
   await writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
 
   for (const tool of agent.tools) {

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

@@ -0,0 +1,267 @@
+/**
+ * Cursor-managed durable storage for hosted agents.
+ *
+ * Talks to the control-plane storage proxy
+ * (`POST /internal/agent-serve/storage/*`) using the engine's pod
+ * `CURSOR_API_KEY`. The server resolves `deployment_id` from that service
+ * account — engines never receive a Bugbot DSN and cannot address another
+ * deployment's rows.
+ *
+ * On Cursor-managed hosting the start script pins `CURSOR_API_BASE_URL` to
+ * `https://api.cursor.com` (where the proxy is mounted). Locally, point
+ * `CURSOR_API_BASE_URL` at a backend that mounts Agent Serve routes and use
+ * a deployment SA key, or use `@cursor/july/storage/postgres-kv` /
+ * `file-kv` instead.
+ *
+ * ```ts
+ * import { defineStorage } from "@cursor/july/storage";
+ * import { cursorHostedStorage } from "@cursor/july/storage/cursor-hosted";
+ *
+ * export default defineStorage({
+ *   ...cursorHostedStorage(),
+ * });
+ * ```
+ */
+
+import type { ABSnapshot } from "../ab.js";
+import type { EvalRunSnapshot } from "../evals.js";
+import type {
+  StorageABTable,
+  StorageConfig,
+  StorageEntry,
+  StorageEvalsTable,
+} from "../storage.js";
+import type { JsonValue } from "../types.js";
+
+/**
+ * Same default as {@link cursorExternalApiUrl} in the CLI credentials module,
+ * inlined here so this storage entrypoint does not import CLI/zod code.
+ * Hosted monorepo examples load this file from `packages/agent-serve/src`
+ * while `npm install` runs in the example package — a credentials import
+ * would resolve `zod` from the wrong `node_modules` tree and crash serve.
+ */
+const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
+
+/**
+ * Reserved so user `secrets set` cannot smuggle a Bugbot DSN into the pod.
+ * Not injected by Cursor hosting (storage is HTTP-proxied).
+ */
+export const AGENT_SERVE_HOSTED_STORAGE_DATABASE_URL_ENV_VAR =
+  "BUGBOTDB_URL" as const;
+
+/**
+ * Diagnostic / self-host deployment id. Not the hosted-storage authz
+ * boundary — the proxy scopes rows from the authenticated service account.
+ */
+export const AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR =
+  "AGENT_SERVE_DEPLOYMENT_ID" as const;
+
+/**
+ * Platform-managed secret / env names. User `secrets set` / DELETE cannot
+ * claim these.
+ */
+export const CURSOR_HOSTED_STORAGE_ENV_VARS: readonly [
+  typeof AGENT_SERVE_HOSTED_STORAGE_DATABASE_URL_ENV_VAR,
+  typeof AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR,
+] = [
+  AGENT_SERVE_HOSTED_STORAGE_DATABASE_URL_ENV_VAR,
+  AGENT_SERVE_DEPLOYMENT_ID_ENV_VAR,
+];
+
+export interface CursorHostedStorageOptions {
+  /**
+   * Control-plane base URL (default: `CURSOR_API_BASE_URL`, else
+   * `https://api.cursor.com`).
+   */
+  baseUrl?: string;
+  /** Bearer credential (default: `CURSOR_API_KEY`). */
+  apiKey?: string;
+  /** Injected for tests. */
+  fetch?: typeof fetch;
+}
+
+/**
+ * Marker stamped on {@link cursorHostedStorage} so the engine can prefer
+ * durable Bugbot rows for `GET /v1/sessions` (survives `defineStorage` spread).
+ * Explicit `unique symbol` annotation required for `--isolatedDeclarations`
+ * (TS9010).
+ */
+export const CURSOR_HOSTED_STORAGE: unique symbol = Symbol.for(
+  "@cursor/july.storage.cursor-hosted"
+);
+
+/** True when `value` is (or was built from) {@link cursorHostedStorage}. */
+export function isCursorHostedStorage(value: unknown): boolean {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Record<symbol, unknown>)[CURSOR_HOSTED_STORAGE] === true
+  );
+}
+
+type CursorHostedStorageMethods = Required<
+  Pick<StorageConfig, "put" | "get" | "delete" | "list">
+> & {
+  readonly [CURSOR_HOSTED_STORAGE]: true;
+  evals: StorageEvalsTable;
+  abs: StorageABTable;
+};
+
+function resolveApiKey(options: CursorHostedStorageOptions): string {
+  const key = (options.apiKey ?? process.env.CURSOR_API_KEY)?.trim();
+  if (key === undefined || key === "") {
+    throw new Error(
+      "cursorHostedStorage requires CURSOR_API_KEY (deployment pod credential on Cursor hosting)"
+    );
+  }
+  return key;
+}
+
+function resolveBaseUrl(options: CursorHostedStorageOptions): string {
+  const raw = (
+    options.baseUrl ??
+    process.env.CURSOR_API_BASE_URL ??
+    DEFAULT_CURSOR_EXTERNAL_API_URL
+  ).trim();
+  return raw.endsWith("/") ? raw.slice(0, -1) : raw;
+}
+
+async function storageRpc<T>(
+  options: CursorHostedStorageOptions,
+  path: string,
+  body: Record<string, unknown>
+): Promise<T> {
+  const baseUrl = resolveBaseUrl(options);
+  const apiKey = resolveApiKey(options);
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("cursorHostedStorage requires fetch");
+  }
+  const response = await fetchImpl(`${baseUrl}${path}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await response.text();
+  let parsed: unknown;
+  try {
+    parsed = text.length === 0 ? {} : JSON.parse(text);
+  } catch {
+    throw new Error(
+      `cursorHostedStorage ${path} returned non-JSON (${response.status})`
+    );
+  }
+  if (!response.ok) {
+    const error =
+      parsed !== null &&
+      typeof parsed === "object" &&
+      "error" in parsed &&
+      typeof (parsed as { error: unknown }).error === "string"
+        ? (parsed as { error: string }).error
+        : `HTTP ${response.status}`;
+    throw new Error(`cursorHostedStorage ${path}: ${error}`);
+  }
+  return parsed as T;
+}
+
+/**
+ * Cursor-hosted `defineStorage` methods (control-plane storage proxy →
+ * Bugbot `agent_serve_*` tables). Spread into `defineStorage({...})`.
+ */
+export function cursorHostedStorage(
+  options: CursorHostedStorageOptions = {}
+): CursorHostedStorageMethods {
+  return {
+    [CURSOR_HOSTED_STORAGE]: true,
+    async put(key, value): Promise<void> {
+      await storageRpc(options, "/internal/agent-serve/storage/kv/put", {
+        key,
+        value,
+      });
+    },
+    async get(key): Promise<JsonValue | undefined> {
+      const result = await storageRpc<{
+        found: boolean;
+        value: JsonValue | null;
+      }>(options, "/internal/agent-serve/storage/kv/get", { key });
+      if (!result.found) {
+        return undefined;
+      }
+      return result.value ?? undefined;
+    },
+    async delete(key): Promise<void> {
+      await storageRpc(options, "/internal/agent-serve/storage/kv/delete", {
+        key,
+      });
+    },
+    async list(prefix): Promise<StorageEntry[]> {
+      const result = await storageRpc<{
+        entries: Array<{ key: string; value: JsonValue }>;
+      }>(options, "/internal/agent-serve/storage/kv/list", { prefix });
+      return result.entries;
+    },
+    evals: {
+      async put(run, ctx): Promise<void> {
+        await storageRpc(options, "/internal/agent-serve/storage/evals/put", {
+          agentName: ctx.agentName,
+          run,
+        });
+      },
+      async delete(runId, ctx): Promise<void> {
+        await storageRpc(
+          options,
+          "/internal/agent-serve/storage/evals/delete",
+          {
+            agentName: ctx.agentName,
+            runId,
+          }
+        );
+      },
+      async list(ctx): Promise<EvalRunSnapshot[]> {
+        const result = await storageRpc<{ runs: EvalRunSnapshot[] }>(
+          options,
+          "/internal/agent-serve/storage/evals/list",
+          { agentName: ctx.agentName }
+        );
+        return result.runs;
+      },
+    },
+    abs: {
+      async putSample(sample, ctx): Promise<void> {
+        await storageRpc(
+          options,
+          "/internal/agent-serve/storage/abs/put-sample",
+          {
+            agentName: ctx.agentName,
+            sample,
+          }
+        );
+      },
+      async putSnapshot(snapshot, ctx): Promise<void> {
+        await storageRpc(
+          options,
+          "/internal/agent-serve/storage/abs/put-snapshot",
+          {
+            agentName: ctx.agentName,
+            snapshot,
+          }
+        );
+      },
+      async getSnapshot(ctx): Promise<ABSnapshot | undefined> {
+        const result = await storageRpc<{
+          found: boolean;
+          snapshot: ABSnapshot | null;
+        }>(options, "/internal/agent-serve/storage/abs/get-snapshot", {
+          agentName: ctx.agentName,
+        });
+        if (!result.found) {
+          return undefined;
+        }
+        return result.snapshot ?? undefined;
+      },
+    },
+  };
+}