@cursor/july 0.1.100 → 0.1.101

package/src/internal/server.ts

@@ -72,6 +72,7 @@ import { CursorGithubCredentialProvider } from "./cursor/github-credentials.js";
 import {
   DeploymentEventRelay,
   fanOutDeploymentEvent,
+  mergeResolvedSubscriptions,
   type ResolvedSubscription,
   resolveDeploymentSubscriptions,
 } from "./cursor-deployment-relay.js";
@@ -111,6 +112,7 @@ import {
 import { createHostPlatforms, warmupHostGitHubAuth } from "./host-platforms.js";
 import { registerHostedDeliveryRoute } from "./hosted-delivery.js";
 import { hostedErrorStackSnippet } from "./hosted-execution-diag.js";
+import { flushHostedExecutionProcessDeath } from "./hosted-execution-flush.js";
 import {
   buildHttpChannelRoutes,
   errorResponse,
@@ -194,6 +196,7 @@ import {
   unregisterSessionRunFatalFlush,
 } from "./session-run-log.js";
 import { sessionUrlsForRequest } from "./session-urls.js";
+import { flushLocalStartLog, selectStartLogStore } from "./start-log-store.js";
 import { catalogDetailEntry, catalogListEntry } from "./tool-catalog.js";
 
 function memoryHealthFields(engines: readonly SessionEngine[]) {
@@ -256,6 +259,8 @@ export interface StartServerInternalOptions {
   mcpOauthSecrets?: McpOauthSecretsTarget;
   /** Test seam: persist hosted-execution run logs without a live store. */
   sessionRunLog?: ReturnType<typeof selectSessionRunLogStore>;
+  /** Test seam: persist the engine start.log tee without a live store. */
+  startLogStore?: ReturnType<typeof selectStartLogStore>;
 }
 
 /**
@@ -550,10 +555,35 @@ export async function startServer(
           snapshotLogs: () => logRing.since(),
         })
       : undefined);
+  const startLogStore =
+    options.startLogStore ??
+    (mounts.length === 1 && mounts[0] !== undefined
+      ? selectStartLogStore({
+          project: mounts[0].project,
+          logger,
+        })
+      : undefined);
+  // The running claim stamps this before the turn; process-death flush
+  // reuses it so the tee snapshot lands under the same ses_ key.
+  let lastStartLogId: string | undefined;
+  const flushStartLog = async (startLogId: string): Promise<void> => {
+    lastStartLogId = startLogId;
+    if (startLogStore === undefined) {
+      return;
+    }
+    await flushLocalStartLog({ store: startLogStore, startLogId });
+  };
   if (sessionRunLog !== undefined) {
-    registerSessionRunFatalFlush((error) =>
-      sessionRunLog.flushProcessDeath("uncaught_exception", error)
-    );
+    registerSessionRunFatalFlush(async (error) => {
+      await flushHostedExecutionProcessDeath({
+        flushProcessDeath: (reason, flushError) =>
+          sessionRunLog.flushProcessDeath(reason, flushError),
+        flushStartLog,
+        startLogId: lastStartLogId,
+        reason: "uncaught_exception",
+        error,
+      });
+    });
   }
   const sdkRunner =
     options.runner ??
@@ -770,6 +800,7 @@ export async function startServer(
       logRing,
       diagStateRoot: baseStateRoot,
       sessionRunLog,
+      flushStartLog,
       ...(options.authToken === undefined
         ? {}
         : { authToken: options.authToken }),
@@ -1224,7 +1255,13 @@ export async function startServer(
     },
     close: async () => {
       if (sessionRunLog !== undefined) {
-        await sessionRunLog.flushProcessDeath("process_exit");
+        await flushHostedExecutionProcessDeath({
+          flushProcessDeath: (reason) =>
+            sessionRunLog.flushProcessDeath(reason),
+          flushStartLog,
+          startLogId: lastStartLogId,
+          reason: "process_exit",
+        });
         unregisterSessionRunFatalFlush();
       }
       playgroundDev?.stop();
@@ -1282,6 +1319,7 @@ function mountAgentRoutes(
     logger: (line: string) => void;
     logRing: LogRing;
     sessionRunLog?: ReturnType<typeof selectSessionRunLogStore>;
+    flushStartLog?: (startLogId: string) => Promise<void>;
     authToken?: string;
     allowAnonymous?: boolean;
     /** Cursor account bridge + this mount's account MCP connections, when authored. */
@@ -1303,6 +1341,7 @@ function mountAgentRoutes(
     logger,
     logRing,
     sessionRunLog,
+    flushStartLog,
   } = args;
   // "" (single) -> "/v1/..."; "my-agent" (multi) -> "/my-agent/v1/...".
   const base = slug === "" ? "" : `/${slug}`;
@@ -1366,7 +1405,12 @@ function mountAgentRoutes(
         : { stateRoot: args.diagStateRoot }),
       ...(sessionRunLog === undefined
         ? {}
-        : { persistSessionRun: (document) => sessionRunLog.persist(document) }),
+        : {
+            persistSessionRun: async (document) => {
+              await sessionRunLog.persist(document);
+            },
+            flushStartLog,
+          }),
       snapshotLogs: () => logRing.since(),
     });
   }
@@ -1474,51 +1518,6 @@ function mountAgentRoutes(
     },
   });
 
-  // v2 only: one session-level hosted-execution log on the framework
-  // store. Distinct from GET /v1/logs (process-wide ring). Keyed by the
-  // factory session public id so an execute_throw that never minted a
-  // July session is still readable after the pod parks.
-  if (isV2Project(project) && sessionRunLog !== undefined) {
-    router.add({
-      method: "GET",
-      pattern: `${base}/v1/session/:sessionId/runs`,
-      auth: httpAuth,
-      handler: async (_request, ctx) => {
-        const sessionId = ctx.params.sessionId ?? "";
-        if (sessionId.length === 0 || sessionId.includes("/")) {
-          return errorResponse(
-            400,
-            "invalid_request",
-            "Expected a session id."
-          );
-        }
-        const record = await engine.getOrRestoreSession(sessionId);
-        if (record === undefined) {
-          return errorResponse(
-            404,
-            "session_not_found",
-            `Unknown session ${sessionId}.`
-          );
-        }
-        const ownership = requireSessionOwner(record, ctx.auth, {
-          relax: relaxSessionReadAuth,
-          beyondLoopback: relaxSessionReadAuthBeyondLoopback,
-          requestIp: ctx.requestIp,
-        });
-        if (ownership !== undefined) {
-          return ownership;
-        }
-        const document = await sessionRunLog.read(sessionId);
-        return jsonResponse({
-          sessionId,
-          updatedAt: document?.updatedAt,
-          lastFailure: document?.lastFailure ?? null,
-          executions: document?.executions ?? [],
-        });
-      },
-    });
-  }
-
   router.add({
     method: "GET",
     pattern: `${base}/v1/sessions`,
@@ -2694,13 +2693,11 @@ interface CursorDeploymentTarget {
   runtime: MountedRuntime;
   channelId: string;
   options: DeploymentsChannelOptions;
-  subscriptions: ResolvedSubscription[];
 }
 
-/** Every mounted `deploymentsChannel`, with its resolved subscriptions. */
+/** Every mounted `deploymentsChannel`. Subscriptions are re-resolved live. */
 function collectCursorDeploymentTargets(
-  runtimes: MountedRuntime[],
-  skipped: string[]
+  runtimes: MountedRuntime[]
 ): CursorDeploymentTarget[] {
   const targets: CursorDeploymentTarget[] = [];
   for (const runtime of runtimes) {
@@ -2709,19 +2706,24 @@ function collectCursorDeploymentTargets(
       if (options === undefined) {
         continue;
       }
-      const subscriptions = resolveDeploymentSubscriptions(options);
-      if (subscriptions.length === 0) {
-        // Declared the channel but named no deploy sources — usually an unset
-        // env var. Say so rather than starting a relay that receives nothing.
-        skipped.push(`${runtime.slug || runtime.project.name}/${channel.id}`);
-        continue;
-      }
-      targets.push({ runtime, channelId: channel.id, options, subscriptions });
+      targets.push({
+        runtime,
+        channelId: channel.id,
+        options,
+      });
     }
   }
   return targets;
 }
 
+function liveDeploymentSubscriptionUnion(
+  targets: readonly CursorDeploymentTarget[]
+): ResolvedSubscription[] {
+  return mergeResolvedSubscriptions(
+    targets.map((target) => resolveDeploymentSubscriptions(target.options))
+  );
+}
+
 /**
  * Cursor deployment-events relay: automatic when a mounted agent authored
  * `deploymentsChannel({ ... })`. One relay per process reads
@@ -2736,13 +2738,7 @@ function startCursorDeploymentRelay(input: {
   logger: (line: string) => void;
 }): DeploymentEventRelay | undefined {
   const { options, runtimes, accountKey, logger } = input;
-  const skipped: string[] = [];
-  const targets = collectCursorDeploymentTargets(runtimes, skipped);
-  if (skipped.length > 0) {
-    logger(
-      `[agent-sdk] deployment-events: no deploy sources declared on ${skipped.join(", ")}; those channels receive nothing`
-    );
-  }
+  const targets = collectCursorDeploymentTargets(runtimes);
   if (targets.length === 0) {
     return undefined;
   }
@@ -2757,34 +2753,19 @@ function startCursorDeploymentRelay(input: {
       `This project has channels subscribed to deployment events (deploymentsChannel({ deploySourceUris })) but the host is not signed in to Cursor. ${SIGN_IN_HINT}`
     );
   }
-  // Union across channels: one registration per deploy source for the whole
-  // process, however many channels named it. Per-channel environment and
-  // event-type filtering happens at dispatch.
-  const bySource = new Map<string, ResolvedSubscription>();
-  for (const target of targets) {
-    for (const subscription of target.subscriptions) {
-      const existing = bySource.get(subscription.deploySourceUri);
-      if (existing === undefined) {
-        bySource.set(subscription.deploySourceUri, {
-          deploySourceUri: subscription.deploySourceUri,
-          environments: [...subscription.environments],
-          events: new Set(subscription.events),
-        });
-        continue;
-      }
-      for (const event of subscription.events) existing.events.add(event);
-      // An empty environment list means "every environment", so it absorbs.
-      existing.environments =
-        existing.environments.length === 0 ||
-        subscription.environments.length === 0
-          ? []
-          : [
-              ...new Set([
-                ...existing.environments,
-                ...subscription.environments,
-              ]),
-            ];
-    }
+  // Union is re-resolved on each heartbeat and fan-out so a channel that
+  // refreshes `deploySourceUris` after start (Change Monitor lists the
+  // team's sources every 10 minutes) registers the new URIs.
+  const initial = liveDeploymentSubscriptionUnion(targets);
+  if (initial.length === 0) {
+    logger(
+      `[agent-sdk] deployment-events: no deploy sources yet on ${targets
+        .map(
+          (target) =>
+            `${target.runtime.slug || target.runtime.project.name}/${target.channelId}`
+        )
+        .join(", ")}; the relay will register when a channel lists some`
+    );
   }
   // Same host split as scm-events: `/v0/deployment-events/*` is on
   // api.cursor.com, not api2.
@@ -2795,7 +2776,7 @@ function startCursorDeploymentRelay(input: {
     baseUrl: cursorExternalApiUrl(),
     apiKey: accountKey.apiKey,
     stateDir: join(baseStateRoot, "deployment-events"),
-    subscriptions: [...bySource.values()],
+    subscriptions: () => liveDeploymentSubscriptionUnion(targets),
     logger,
     dispatch: async (event) =>
       fanOutDeploymentEvent({
@@ -2803,7 +2784,7 @@ function startCursorDeploymentRelay(input: {
         logger,
         targets: targets.map((target) => ({
           name: `${target.runtime.slug || target.runtime.project.name}/${target.channelId}`,
-          subscriptions: target.subscriptions,
+          subscriptions: resolveDeploymentSubscriptions(target.options),
           deliver: (delivered) =>
             dispatchDeploymentEvent({
               options: target.options,
@@ -2818,7 +2799,7 @@ function startCursorDeploymentRelay(input: {
   });
   relay.start();
   logger(
-    `[agent-sdk] deployment-events: relaying ${bySource.size} deploy-source subscription(s) to ${targets.length} channel(s)`
+    `[agent-sdk] deployment-events: relaying ${initial.length} deploy-source subscription(s) to ${targets.length} channel(s)`
   );
   return relay;
 }

package/src/internal/session-engine.ts

@@ -50,16 +50,17 @@ import {
   type ConnectionTransport,
   DEFAULT_MODEL,
   DIRECT_TOOL_CALL_CHANNEL_ID,
+  type DiscoveredConnection,
   type DiscoveredTool,
   type HookHandler,
   type HostContext,
   type HostMcpRegistry,
+  type HostMcpToolInfo,
   type HttpChannelDefinition,
   isCursorAccountTransport,
   isHostOauthConnectionTransport,
   isSymbolicConnectionTransport,
   type JsonValue,
-  type McpToolAnnotations,
   type PendingApproval,
   type PendingAuth,
   type ReceiveInput,
@@ -89,7 +90,12 @@ import {
 } from "./advertise-tools.js";
 import { ApprovalGate } from "./approval-gate.js";
 import { ArtifactsStore } from "./artifacts-store.js";
-import { assertTimeArgs, normalizeAsOf, sessionClock } from "./as-of.js";
+import {
+  assertTimeArgs,
+  normalizeAsOf,
+  schemaTimeWindowKeys,
+  sessionClock,
+} from "./as-of.js";
 import { SessionAuthError, samePrincipal } from "./auth.js";
 import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
 import {
@@ -600,18 +606,25 @@ export class SessionEngine {
   setResolvedConnections(connections: EngineResolvedConnection[]): void {
     this.resolvedConnections = connections;
     for (const connection of connections) {
+      const authored = this.authoredConnection(connection.name);
       this.mcpHost.addConnection({
+        ...(authored ?? { name: connection.name }),
         name: connection.name,
         transport: {
           url: connection.localUrl,
-          ...(connection.headers === undefined
-            ? {}
-            : { headers: connection.headers }),
+          headers: connection.headers,
         },
       });
     }
   }
 
+  private authoredConnection(name: string): DiscoveredConnection | undefined {
+    return (
+      this.project.agent.connections.find((item) => item.name === name) ??
+      this.project.agent.hostConnections?.find((item) => item.name === name)
+    );
+  }
+
   setCloudServerToolsConnection(connection: ConnectionTransport): void {
     this.cloudServerToolsConnection = connection;
   }
@@ -2753,6 +2766,9 @@ export class SessionEngine {
         input: validation.value,
         asOf: args.record.asOf,
         timeArgs: args.tool.definition.timeArgs,
+        ...(args.tool.advertised === true && args.record.asOf !== undefined
+          ? { timeWindow: schemaTimeWindowKeys(args.tool.inputSchema) }
+          : {}),
       });
       if (decision.kind === "answer") {
         this.stubbedCallIds.get(args.record.sessionId)?.add(toolCallId);
@@ -3083,13 +3099,6 @@ export class SessionEngine {
     await this.oauthHub.persistFor(connection, authored.transport.url);
   }
 
-  private authoredConnection(name: string) {
-    return (
-      this.project.agent.connections.find((entry) => entry.name === name) ??
-      this.project.agent.hostConnections?.find((entry) => entry.name === name)
-    );
-  }
-
   private async mintAuthUrl(
     connection: string,
     sessionId: string
@@ -3632,6 +3641,9 @@ export class SessionEngine {
       input: validation.value,
       asOf: record?.asOf,
       timeArgs: tool.definition.timeArgs,
+      ...(tool.advertised === true && record?.asOf !== undefined
+        ? { timeWindow: schemaTimeWindowKeys(tool.inputSchema) }
+        : {}),
     });
 
     const started = Date.now();
@@ -3770,28 +3782,42 @@ export class SessionEngine {
   }
 
   /**
-   * Whether a dry run answers a bridged MCP call, for the cloud host bridge —
+   * Whether the host answers a bridged MCP call, for the cloud host bridge —
    * the one tool path that does not reach {@link executeServerTool}, because
    * it forwards to `host.mcp` instead of invoking a tool body.
    *
-   * A bridged tool carries no `defineTool`, so it declares no effect, and the
-   * policy reads an undeclared tool as a write. In a dry run that answers
-   * bridged reads too; resolving effects from a server's own listing is the
-   * next unit's work.
+   * A frozen session refuses forward-looking time args here even when it is
+   * not a dry run. A bridged tool carries no `defineTool`, so it declares no
+   * effect, and the policy reads an undeclared tool as a write. In a dry run
+   * that answers bridged reads too; resolving effects from a server's own
+   * listing is the next unit's work.
    */
   async bridgedCallAnswer(args: {
     sessionId: string;
     connectionName: string;
     toolName: string;
+    input?: unknown;
   }): Promise<
     { answered: true; result: SDKCustomToolResult } | { answered: false }
   > {
     // Read off the in-flight turn's context rather than the session store:
     // the bridge already refuses a call with no active turn, so the record is
-    // in memory. That keeps this free for the sessions that are not dry runs,
-    // which is every session today — the listing below is only paid inside a
-    // dry run.
+    // in memory. The listing below is only paid inside a dry run.
     const context = this.activeToolContexts.get(args.sessionId);
+    if (context?.record.asOf !== undefined) {
+      const decision = decideToolCall({
+        dryRun: false,
+        effect: undefined,
+        input: args.input,
+        asOf: context.record.asOf,
+      });
+      if (decision.kind === "unbounded") {
+        this.logger(
+          `[session] bridged tool ${args.toolName} refused, unbounded_time (${args.sessionId})`
+        );
+        return { answered: true, result: toolErrorResult(decision.message) };
+      }
+    }
     if (context?.record.dryRun !== true) {
       return { answered: false };
     }
@@ -3799,14 +3825,16 @@ export class SessionEngine {
     // server's own listing annotations; a tool the listing cannot classify
     // refuses rather than being stubbed. A failed listing classifies nothing,
     // which lands on the same refusal — never on a run.
-    const annotations = await this.bridgedToolAnnotations(
-      args.connectionName,
-      args.toolName
-    );
+    const info = await this.bridgedToolInfo(args.connectionName, args.toolName);
     const decision = decideToolCall({
       dryRun: true,
       effect: undefined,
-      mcpTool: { name: args.toolName, annotations },
+      mcpTool: { name: args.toolName, annotations: info?.annotations },
+      input: args.input,
+      asOf: context.record.asOf,
+      ...(context.record.asOf !== undefined
+        ? { timeWindow: schemaTimeWindowKeys(info?.inputSchema) }
+        : {}),
     });
     if (decision.kind === "run") {
       return { answered: false };
@@ -3842,13 +3870,13 @@ export class SessionEngine {
    * undefined when the tool is unlisted, unannotated, or the listing fails —
    * all of which the policy reads as unclassified, the refusing state.
    */
-  private async bridgedToolAnnotations(
+  private async bridgedToolInfo(
     connectionName: string,
     toolName: string
-  ): Promise<McpToolAnnotations | undefined> {
+  ): Promise<HostMcpToolInfo | undefined> {
     try {
       const listed = await this.host.mcp.listTools(connectionName);
-      return listed.find((tool) => tool.name === toolName)?.annotations;
+      return listed.find((tool) => tool.name === toolName);
     } catch {
       return undefined;
     }

package/src/internal/session-run-log.ts

@@ -14,7 +14,8 @@
  * session key with `processDeath: true` and the real throw. Soft-fail on
  * persist so a store outage never changes the hosted-execution HTTP reply.
  *
- * Keys: {@link storageKeys.sessionRun}.
+ * Same flush moments as `hosted-execution.json` and the start.log tee —
+ * see `hosted-execution-flush.ts`. Keys: {@link storageKeys.sessionRun}.
  */
 
 import type { FileSink } from "../files.js";

package/src/internal/start-log-store.ts

@@ -0,0 +1,177 @@
+/**
+ * Durable hosted `start.log` on the framework file store. **v2 only.**
+ *
+ * The engine tees stdout/stderr to a local file. That file is the v2
+ * customer log (errors, traces, debug). It is NOT written to S3 per line:
+ * callers snapshot the local buffer and PUT once. The Temporal host does
+ * a last catch-up at the end of the delivery so the object is complete
+ * after park/discard.
+ *
+ * Same flush moments as `hosted-execution.json` and session-runs —
+ * see `hosted-execution-flush.ts`. Keys: {@link storageKeys.log}.
+ * Values are raw UTF-8, not JSON.
+ */
+
+import { readFile } from "node:fs/promises";
+import type { FileSink } from "../files.js";
+import {
+  cursorFrameworkStoreSourceId,
+  cursorHostedFiles,
+} from "../files-backends/cursor-hosted.js";
+import { storageKeys } from "../storage-protocol.js";
+import type { AgentProject } from "../types.js";
+import { resolveApiKeySync } from "./cursor/credentials.js";
+import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
+import { describeError } from "./describe-error.js";
+
+/**
+ * Last N bytes flushed to the store. Matches the Temporal catch-up cap
+ * so guest snapshots and host catch-up stay interchangeable. The store
+ * allows 64 MiB; this keeps the dashboard snapshot bounded.
+ */
+export const START_LOG_STORE_MAX_BYTES: number = 2 * 1024 * 1024;
+
+/** Same path the hosted start command tees. Overridable in tests. */
+export const DEFAULT_ENGINE_START_LOG_PATH =
+  "/workspace/.agent-serve/start.log";
+
+export interface StartLogStore {
+  persist(startLogId: string, contents: string): Promise<void>;
+  read(startLogId: string): Promise<string | undefined>;
+}
+
+function decodeSinkBody(body: Uint8Array | { body: Uint8Array }): Uint8Array {
+  return body instanceof Uint8Array ? body : body.body;
+}
+
+export function tailStartLogText(raw: string, maxBytes: number): string {
+  const encoded = new TextEncoder().encode(raw);
+  if (encoded.byteLength <= maxBytes) {
+    return raw;
+  }
+  return new TextDecoder().decode(
+    encoded.subarray(encoded.byteLength - maxBytes)
+  );
+}
+
+export function resolveEngineStartLogPath(
+  env: NodeJS.ProcessEnv = process.env
+): string {
+  const configured = env.AGENT_SERVE_ENGINE_START_LOG_PATH?.trim();
+  return configured !== undefined && configured.length > 0
+    ? configured
+    : DEFAULT_ENGINE_START_LOG_PATH;
+}
+
+/**
+ * Read the local engine tee. Missing/empty is `undefined` (no store write).
+ * Soft-fail: a local read error must not change hosted-execution HTTP.
+ */
+export async function readLocalStartLogText(args?: {
+  path?: string;
+  maxBytes?: number;
+}): Promise<string | undefined> {
+  const path = args?.path ?? resolveEngineStartLogPath();
+  const maxBytes = args?.maxBytes ?? START_LOG_STORE_MAX_BYTES;
+  try {
+    const raw = await readFile(path, "utf8");
+    if (raw.length === 0) {
+      return undefined;
+    }
+    return tailStartLogText(raw, maxBytes);
+  } catch (error) {
+    if (
+      error !== null &&
+      typeof error === "object" &&
+      "code" in error &&
+      (error as { code?: string }).code === "ENOENT"
+    ) {
+      return undefined;
+    }
+    return undefined;
+  }
+}
+
+export function createStartLogStore(input: {
+  sink: FileSink;
+  agentName: string;
+  logger?: (line: string) => void;
+}): StartLogStore {
+  const { sink, agentName } = input;
+  const logger = input.logger ?? (() => {});
+
+  return {
+    async persist(startLogId, contents) {
+      const key = storageKeys.log(agentName, startLogId);
+      const body = tailStartLogText(contents, START_LOG_STORE_MAX_BYTES);
+      try {
+        await sink.put(key, new TextEncoder().encode(body));
+      } catch (error) {
+        logger(
+          `[agent-sdk] start-log: persist failed for ${startLogId} (${describeError(error)})`
+        );
+      }
+    },
+
+    async read(startLogId) {
+      const key = storageKeys.log(agentName, startLogId);
+      try {
+        const body = await sink.get(key);
+        if (body === undefined) {
+          return undefined;
+        }
+        const text = new TextDecoder().decode(decodeSinkBody(body));
+        return text.length === 0 ? undefined : text;
+      } catch (error) {
+        logger(
+          `[agent-sdk] start-log: read failed for ${startLogId} (${describeError(error)})`
+        );
+        return undefined;
+      }
+    },
+  };
+}
+
+/**
+ * Same selection as the session-run log: architecture-v2 hosted engines.
+ */
+export function selectStartLogStore(input: {
+  project: AgentProject;
+  logger?: (line: string) => void;
+  env?: Record<string, string | undefined>;
+}): StartLogStore | undefined {
+  if (input.project.agent.architecture !== "v2") {
+    return undefined;
+  }
+  const env = input.env ?? process.env;
+  if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+    return undefined;
+  }
+  const envSnapshot = env as NodeJS.ProcessEnv;
+  return createStartLogStore({
+    sink: cursorHostedFiles({
+      resolveStoreSourceId: () => cursorFrameworkStoreSourceId(envSnapshot),
+      resolveApiKey: () => resolveApiKeySync()?.apiKey,
+    }),
+    agentName: input.project.name,
+    logger: input.logger,
+  });
+}
+
+/**
+ * Snapshot the local tee into the store. No-op when the file is missing
+ * or empty. Soft-fail inside {@link StartLogStore.persist}.
+ */
+export async function flushLocalStartLog(args: {
+  store: StartLogStore;
+  startLogId: string;
+  path?: string;
+}): Promise<void> {
+  const contents = await readLocalStartLogText(
+    args.path === undefined ? undefined : { path: args.path }
+  );
+  if (contents === undefined) {
+    return;
+  }
+  await args.store.persist(args.startLogId, contents);
+}