@cursor/bdk 0.2.6 → 0.2.8

package/dist/internal/session-engine.js

@@ -48,7 +48,7 @@ import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
 import { applyCloudUsageToEvents, cloudSdkAgentIdFromEvents, isUnpricedCompletedTurn, mapSdkTokenUsage, } from "./cloud-turn-cost.js";
 import { resolveConnectionEnvTemplates } from "./connection-env.js";
 import { applyAgentContinuationDefaults, channelContinuationIdentity, httpContinuationIdentity, } from "./continuation-channel.js";
-import { continuationSource, resolveV2Key, V2EngineError } from "./continuation-identity.js";
+import { continuationSource, isOneShotContinuationKey, resolveV2Key, V2EngineError, } from "./continuation-identity.js";
 import { describeError, describeErrorCode } from "./describe-error.js";
 import { isDevMode } from "./dev-mode.js";
 import { EventLogStore } from "./event-log.js";
@@ -76,7 +76,7 @@ import { steeringEnabled } from "./steering.js";
 import { StorageCoordinator, isTurnBoundaryEvent } from "./storage-coordinator.js";
 import { decideToolCall, directCallEffect } from "./tool-policy.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
-import { estimateTurnCostFromApi, roundCostUsd } from "./turn-cost.js";
+import { estimateTurnCostFromApi, roundCostUsd, } from "./turn-cost.js";
 import { TurnGovernor } from "./turn-governor.js";
 import { TurnLeaseStore } from "./turn-lease-store.js";
 import { TurnOutbox } from "./turn-outbox.js";
@@ -213,7 +213,7 @@ export class SessionEngine {
         var _a, _b, _c, _d, _e;
         /** In-flight lazy restores, deduped per channel + continuation key. */
         this.restoreInFlight = new Map();
-        /** In-flight authored files → Agent Store syncs (see syncToCloudStore). */
+        /** In-flight authored-file syncs for cloud turns. */
         this.cloudSyncs = new Map();
         this.channelsById = new Map();
         /** Sessions with a turn being admitted (before the run promise exists). */
@@ -297,7 +297,7 @@ export class SessionEngine {
         this.askDedupe = new SlackAskDedupeStore(join(options.stateRoot, "slack-asks"));
         this.turnLeases = new TurnLeaseStore(join(options.stateRoot, "turn-leases"));
         this.outbox = new TurnOutbox(join(options.stateRoot, "outbox"));
-        this.logs = new EventLogStore(sessionId => this.sessions.eventFilePath(sessionId), (sessionId, error) => this.logger(`[agent-sdk] failed to persist events for ${sessionId}: ${describeError(error)}`));
+        this.logs = new EventLogStore(sessionId => this.sessions.eventFilePath(sessionId), (sessionId, error) => this.logger(`[bdk] failed to persist events for ${sessionId}: ${describeError(error)}`));
         // Framework session state (records, event chunks, continuations) is
         // mirrored to whatever this selects; see framework-storage-selection.ts
         // for why the choice does not belong to the agent author.
@@ -335,9 +335,9 @@ export class SessionEngine {
             config: options.project.artifacts,
             sink: managedV2Files === null || managedV2Files === void 0 ? void 0 : managedV2Files(),
             // v1 and self-hosted v2 still evict oldest-updated rows past max.
-            // Hosted v2 does not: the installation file store keeps every row,
-            // and tag must not list the prefix. Read per tag so a generation
-            // env bound after serve start takes effect.
+            // Managed v2 leaves retention to the platform, so tagging never scans
+            // the full artifact set. Resolve this for each tag so hosting changes
+            // take effect without recreating the store.
             enforceCap: () => {
                 const hosting = resolveAgentV2Hosting({
                     architecture: options.project.agent.architecture,
@@ -644,8 +644,7 @@ export class SessionEngine {
             if (isDuringHostedAdmission()) {
                 // Only sends that bypassed the admission capture stub (typically a
                 // startup-captured `onStart` send) reach the engine inside the
-                // admission window; running one would leak an invisible local session
-                // on a sessionless pod.
+                // admission window; running one would create an invisible local session.
                 throw new HostedAdmissionLocalSendError();
             }
             if (options.clearCloudOverride === true && options.cloud !== undefined) {
@@ -662,7 +661,7 @@ export class SessionEngine {
                 }
                 const cKey = resolveV2Key(identity, options);
                 sendOptions = Object.assign(Object.assign({}, options), { continuationToken: cKey });
-                skipContinuationLookup = cKey.startsWith("evt:");
+                skipContinuationLookup = isOneShotContinuationKey(cKey);
             }
             const auth = (_c = sendOptions.auth) !== null && _c !== void 0 ? _c : null;
             let existing = skipContinuationLookup || sendOptions.continuationToken === undefined
@@ -678,9 +677,9 @@ export class SessionEngine {
             if (existing === undefined && sendOptions.hostedSessionId !== undefined) {
                 const byId = yield this.getOrRestoreSession(sendOptions.hostedSessionId);
                 if (byId !== undefined) {
-                    // evt: skips the mailbox index; same hostedSessionId is a Temporal
-                    // retry. cont:session:<id> is the explicit CP resume (keep the
-                    // original key so a PR lane stays addressable by its webhooks).
+                    // The same hostedSessionId signals a delivery retry. An explicit
+                    // resume keeps the original key so a PR lane remains addressable by
+                    // its webhooks.
                     if (byId.continuationKey !== sendOptions.continuationToken &&
                         ((_a = sendOptions.mailboxContinuation) === null || _a === void 0 ? void 0 : _a.key) !==
                             hostedSessionResumeKey(sendOptions.hostedSessionId)) {
@@ -1195,9 +1194,8 @@ export class SessionEngine {
                     if (this.turnAborts.get(sessionId) === abort) {
                         this.turnAborts.delete(sessionId);
                     }
-                    // Failed/cancelled owners must not start a coalesced successor.
-                    // Hosted execute would then 503 and Temporal/FIFO would re-run the
-                    // same follow-ups as full deliveries.
+                    // Failed or cancelled owners must not start a coalesced successor;
+                    // managed delivery retries the same follow-ups.
                     if (wasCurrent && !abort.signal.aborted && outcome.status === "finished") {
                         const drain = this.drainCoalescedFollowups(sessionId).catch(error => {
                             this.logger(`[session] coalesce drain failed for ${sessionId}: ${describeError(error)}`);
@@ -1629,11 +1627,11 @@ export class SessionEngine {
                 // that cannot warm resolves cleanly, and logging success there would
                 // tell an operator the workspace is hot when nothing touched it.
                 this.logger(outcome.warmed
-                    ? `[agent-sdk] warmed ${workspaceDir} in ${Date.now() - startedAt}ms`
-                    : `[agent-sdk] did not warm ${workspaceDir}: ${outcome.reason}`);
+                    ? `[bdk] warmed ${workspaceDir} in ${Date.now() - startedAt}ms`
+                    : `[bdk] did not warm ${workspaceDir}: ${outcome.reason}`);
             }
             catch (error) {
-                this.logger(`[agent-sdk] could not warm ${workspaceDir}: ${describeError(error)}`);
+                this.logger(`[bdk] could not warm ${workspaceDir}: ${describeError(error)}`);
             }
         });
     }
@@ -1668,7 +1666,7 @@ export class SessionEngine {
                     this.queueDispatch(sessionId, event, eventContext);
                 }
                 catch (error) {
-                    this.logger(`[agent-sdk] failed to record event for ${sessionId}: ${describeError(error)}`);
+                    this.logger(`[bdk] failed to record event for ${sessionId}: ${describeError(error)}`);
                 }
             };
             // Read by closure, so the mapper still sees it while draining after the
@@ -1811,27 +1809,23 @@ export class SessionEngine {
             }
             const finalResult = (_d = outcome.result) !== null && _d !== void 0 ? _d : mapper.finalText;
             const finalUsage = (_e = outcome.usage) !== null && _e !== void 0 ? _e : mapper.usage;
-            const finalCost = finalUsage === undefined
-                ? undefined
-                : yield this.estimateTurnCost({
-                    model: (_f = this.project.agent.model) !== null && _f !== void 0 ? _f : DEFAULT_MODEL,
-                    usage: finalUsage,
-                    agentId: record.sdkAgentId,
-                    conversationId: (_g = record.sdkAgentId) !== null && _g !== void 0 ? _g : sessionId,
-                });
-            if (finalCost !== undefined) {
-                outcome = Object.assign(Object.assign({}, outcome), { cost: finalCost });
-            }
             if (outcome.status === "finished") {
-                yield this.appendEvent(sessionId, {
+                const completed = yield this.appendEvent(sessionId, {
                     type: "turn.completed",
                     turnId,
                     data: {
                         result: finalResult,
                         usage: finalUsage,
-                        cost: finalCost,
                     },
                 }, eventContext);
+                if (finalUsage !== undefined) {
+                    this.stampTurnCost(sessionId, completed, {
+                        model: (_f = this.project.agent.model) !== null && _f !== void 0 ? _f : DEFAULT_MODEL,
+                        usage: finalUsage,
+                        agentId: record.sdkAgentId,
+                        conversationId: (_g = record.sdkAgentId) !== null && _g !== void 0 ? _g : sessionId,
+                    });
+                }
             }
             else {
                 const interrupted = signal.aborted && outcome.status === "cancelled";
@@ -1878,12 +1872,8 @@ export class SessionEngine {
         });
     }
     /**
-     * Sync authored skills onto the Agent Store at `skills/<name>/…` (hosted)
-     * or `agent-serve/<agent>/skills/<name>/…` (personal-key local+cloud)
-     * before the first cloud prompt, so `--agent-store-skills-dir` and the
-     * first-turn S3 scan can discover them. False when the sync fails: the
-     * turn then runs without store skills rather than pointing discovery at
-     * paths that do not exist.
+     * Sync authored skills to cloud-turn storage before the first prompt.
+     * Returns false on failure so the turn runs without unavailable skills.
      */
     ensureCloudSkillsSynced(store) {
         const skills = this.project.agent.skills;
@@ -1895,10 +1885,7 @@ export class SessionEngine {
         }));
     }
     /**
-     * Sync `agent/sandbox/workspace/**` seeds onto the Agent Store at
-     * `workspace/…` (hosted) or `agent-serve/<agent>/workspace/…`
-     * (personal-key local+cloud) before the first cloud prompt, which names
-     * the mounted directory (see buildCloudWorkspaceSection).
+     * Sync authored workspace seeds before the first cloud prompt.
      */
     ensureCloudWorkspaceSynced(store) {
         const seedFiles = this.project.agent.seedFiles;
@@ -1911,7 +1898,7 @@ export class SessionEngine {
     /**
      * Replace this session's store prefix with the pending `workspaceFiles`.
      * Undefined when the write did not land; the prompt must not name the
-     * mount, matching ensureCloudWorkspaceSynced.
+     * directory, matching ensureCloudWorkspaceSynced.
      */
     syncCloudSessionWorkspaceFiles(store, sessionId, files) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1960,15 +1947,10 @@ export class SessionEngine {
     }
     /**
      * With files authored, every first cloud turn re-copies the authored
-     * bytes and the memo only dedupes concurrent first turns. The mount is
-     * writable from cloud sessions, so a once-per-process copy would let one
-     * session's edits masquerade as agent definition for every later session
-     * until the engine restarts; re-syncing keeps the store true to discovery
-     * the same way local materialization always rewrites skills. Without
-     * authored files the sync is best-effort stale cleanup and one attempt
-     * per process is enough, success or not — a deployment without the files
-     * surface must not fail and log on every new session for a feature it
-     * does not use.
+     * bytes; the memo only dedupes concurrent first turns. Cloud sessions can
+     * edit their view, so re-syncing keeps later sessions true to discovery.
+     * Without authored files, one best-effort cleanup attempt per process is
+     * enough.
      */
     syncToCloudStore(surface, store, authored, run) {
         const inFlight = this.cloudSyncs.get(surface);
@@ -1988,11 +1970,9 @@ export class SessionEngine {
         return sync;
     }
     /**
-     * Hosted deployments own the deployment store. Local `serve`/`run` with
-     * a personal API key writes into the USER store under `agent-serve/`.
-     * A persistent deployment's version container has no cloud store at all:
-     * its state directory is the durable copy, and its service-account key
-     * must not be mistaken for a personal one.
+     * Managed ephemeral deployments use deployment-scoped storage. Local cloud
+     * turns use user-scoped storage. Persistent managed deployments use their
+     * durable state directory instead.
      */
     cloudStore() {
         const v2Hosting = resolveAgentV2Hosting({
@@ -2116,12 +2096,10 @@ export class SessionEngine {
                 turnPrompt = `${contextBlock}\n\n${prompt}`;
             }
             if (runtime === "cloud") {
-                // Cloud VMs have no materialized workspace: ship the full context,
-                // including agent tool script bodies. Authored skills and workspace
-                // seeds land on the store mount (skills for native discovery, seeds
-                // for the model's file tools), per-turn workspaceFiles land under
-                // the session prefix, and on hosted deployments the shared memory
-                // journal is on that mount too — say where. When the turn carries
+                // Cloud turns have no materialized workspace, so ship the full context,
+                // including agent tool script bodies. Authored skills, workspace seeds,
+                // per-turn workspaceFiles, and shared memory use managed paths that the
+                // prompt names when available. When the turn carries
                 // the session-bound server-tool MCP endpoint, the preamble catalogs
                 // server tools under that MCP server name *before* the agent-tool
                 // "write the script if missing" recipe, so a model told to "use
@@ -2148,7 +2126,7 @@ export class SessionEngine {
                             this.ensureCloudSkillsSynced(store),
                             this.ensureCloudWorkspaceSynced(store),
                         ]);
-                        // Only name the mount when the bytes landed; a failed sync must
+                        // Only name the directory when the bytes landed; a failed sync must
                         // not send the model looking for files that are not there.
                         if (seedsSynced && agent.seedFiles.length > 0) {
                             sections.push(buildCloudWorkspaceSection(`${store.mountPath}/${store.workspacePrefix}`));
@@ -2174,7 +2152,7 @@ export class SessionEngine {
                 }
             }
             else if (isFirstTurn && runtime === "local" && authoredRoot) {
-                // The harness reports no path for a root it never mounted.
+                // The harness reports no path for a root it never materialized.
                 turnPrompt = `<user_info>\nWorkspace Path: /\n</user_info>\n\n${turnPrompt}`;
             }
             // A virtual root has no scaffold dir either, so its catalog carries the
@@ -3197,8 +3175,7 @@ export class SessionEngine {
                     throw error;
                 }
                 // A session's harness cwd can be a path the serving process cannot
-                // create (e.g. an absolute `local.cwd` like /repo on a hosted pod
-                // where the sandboxed harness would have made it). Read-effect calls
+                // create in a managed runtime. Read-effect calls
                 // fall back to a scratch workspace instead of failing: tools that
                 // resolve their state from the session identity (VFS mounts) never
                 // touch ctx.workspaceDir. Advertised passthroughs are relocatable by
@@ -3478,7 +3455,7 @@ export class SessionEngine {
         const next = chain
             .then(() => this.dispatchEvent(sessionId, event, context))
             .catch(error => {
-            this.logger(`[agent-sdk] event dispatch failed for ${sessionId}: ${describeError(error)}`);
+            this.logger(`[bdk] event dispatch failed for ${sessionId}: ${describeError(error)}`);
         })
             .then(() => {
             var _a;
@@ -3528,7 +3505,7 @@ export class SessionEngine {
                         yield handler(event, channelCtx, sessionCtx);
                     }
                     catch (error) {
-                        this.logger(`[agent-sdk] channel "${record.channelId}" handler for ${event.type} threw: ${describeError(error)}`);
+                        this.logger(`[bdk] channel "${record.channelId}" handler for ${event.type} threw: ${describeError(error)}`);
                     }
                 }
                 if (context !== undefined) {
@@ -3564,7 +3541,7 @@ export class SessionEngine {
                             }, channelState, stateRoot: this.stateRoot }));
                     }
                     catch (error) {
-                        this.logger(`[agent-sdk] hook "${hook.name}" handler for ${event.type} threw: ${describeError(error)}`);
+                        this.logger(`[bdk] hook "${hook.name}" handler for ${event.type} threw: ${describeError(error)}`);
                     }
                 }
             }
@@ -3583,21 +3560,24 @@ export class SessionEngine {
     // ==========================================================================
     /**
      * Wait until everything this session has already emitted is durably
-     * mirrored: its dispatch chain first (the chain's tail runs the turn-end
-     * storage flush, so the record carries the boundary event's handler
-     * mutations), then the storage delivery queue. Hosted v2 awaits this
-     * before the execution reply — the pod can be parked the moment the
-     * reply lands, and an unflushed session record would strand a
-     * conversation whose blobs persisted but whose record (which selects the
-     * conversation to hydrate) never reached the sink. No-op without a
-     * storage mirror.
+     * mirrored: the runner's conversation mirror write, then its dispatch
+     * chain (the chain's tail runs the turn-end storage flush, so the record
+     * carries the boundary event's handler mutations), then the storage
+     * delivery queue. Managed hosting awaits this before the execution reply
+     * because the process may stop as soon as the reply lands. An unflushed
+     * record would strand an otherwise persisted conversation. The storage
+     * steps are no-ops without a storage mirror.
      *
      * Under a debounced event policy the turn-end flush is a timer, not the
-     * chain's tail, so flush explicitly before waiting on the queue; a no-op
-     * when the chain already flushed.
+     * chain's tail, so flush explicitly before waiting on the queue. The flush
+     * is exact: turn-end flushes skip records where only `turnCount` /
+     * `updatedAt` moved, and close() may never run to repair them, which would
+     * leave the durable turn count stale.
      */
     drainSessionDurability(sessionId) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            yield (_b = (_a = this.runner).drainConversation) === null || _b === void 0 ? void 0 : _b.call(_a, sessionId);
             if (this.storage === undefined) {
                 return;
             }
@@ -3605,7 +3585,7 @@ export class SessionEngine {
             if (chain !== undefined) {
                 yield chain.catch(() => { });
             }
-            this.storage.flushSession(sessionId);
+            this.storage.flushSessionExact(sessionId);
             yield this.storage.whenIdle();
         });
     }
@@ -3645,9 +3625,9 @@ export class SessionEngine {
      * 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.
+     * When the project uses `cursorHostedStorage`, prefers Cursor-managed
+     * durable records, merged with any newer local records not flushed yet.
+     * Falls back to the local `--state-root` store when the sink is unavailable.
      */
     listSessions(caller, options) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -3711,7 +3691,7 @@ export class SessionEngine {
     }
     /**
      * Same as {@link listSessions}, plus which store answered
-     * (`cursor-hosted` = durable DB via the control-plane proxy; `local` =
+     * (`cursor-hosted` = Cursor-managed durable storage; `local` =
      * `--state-root`).
      */
     listSessionsWithSource(caller, options) {
@@ -3728,7 +3708,7 @@ export class SessionEngine {
                     };
                 }
                 catch (error) {
-                    this.logger(`[agent-sdk] cursor-hosted session list failed; falling back to local: ${describeError(error)}`);
+                    this.logger(`[bdk] cursor-hosted session list failed; falling back to local: ${describeError(error)}`);
                 }
             }
             const records = yield this.sessions.list();
@@ -3789,7 +3769,7 @@ export class SessionEngine {
                     }
                 }
                 catch (error) {
-                    this.logger(`[agent-sdk] cursor-hosted newest-session lookup failed; falling back to the full list: ${describeError(error)}`);
+                    this.logger(`[bdk] cursor-hosted newest-session lookup failed; falling back to the full list: ${describeError(error)}`);
                 }
             }
             const listed = yield this.listSessionsWithSource(caller, options);
@@ -3901,6 +3881,37 @@ export class SessionEngine {
             });
         });
     }
+    /**
+     * Cost is a display figure resolved over the network, and the session holds
+     * its delivery lease until `turn.completed`, so it is stamped onto the
+     * recorded event afterwards rather than delaying the event. A host that
+     * stops before the estimate lands leaves the turn unpriced; `sessionCost`
+     * prices the session on read.
+     */
+    stampTurnCost(sessionId, completed, input) {
+        void this.priceTurn(input)
+            .then((cost) => __awaiter(this, void 0, void 0, function* () {
+            if (cost === undefined || completed.type !== "turn.completed") {
+                return;
+            }
+            const log = yield this.logs.get(sessionId);
+            log.replace(completed.index, Object.assign(Object.assign({}, completed), { data: Object.assign(Object.assign({}, completed.data), { cost }) }));
+        }))
+            .catch(error => {
+            this.logger(`[bdk] turn cost stamp failed for ${sessionId}: ${describeError(error)}`);
+        });
+    }
+    priceTurn(input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield this.estimateTurnCost(input);
+            }
+            catch (error) {
+                this.logger(`[bdk] turn cost estimate failed: ${describeError(error)}`);
+                return undefined;
+            }
+        });
+    }
     /**
      * Billed/catalog cost for a session. Powers playground, traces, and
      * `agent-sdk cost` via `GET /v1/session/:id/cost`.
@@ -3988,7 +3999,7 @@ export class SessionEngine {
         }
         const work = this.runCloudTurnCostBackfill(sessionId)
             .catch(error => {
-            this.logger(`[agent-sdk] cloud cost backfill failed for ${sessionId}: ${describeError(error)}`);
+            this.logger(`[bdk] cloud cost backfill failed for ${sessionId}: ${describeError(error)}`);
         })
             .finally(() => {
             this.cloudCostBackfill.delete(sessionId);
@@ -4137,7 +4148,7 @@ export class SessionEngine {
                 yield this.runBulkRestore(storage, policy);
             }
             catch (error) {
-                this.logger(`[agent-sdk] session restore failed: ${describeError(error)}`);
+                this.logger(`[bdk] session restore failed: ${describeError(error)}`);
             }
         });
     }
@@ -4178,7 +4189,7 @@ export class SessionEngine {
                         return { record, events };
                     }
                     catch (error) {
-                        this.logger(`[agent-sdk] failed to restore session ${record.sessionId}: ${describeError(error)}`);
+                        this.logger(`[bdk] failed to restore session ${record.sessionId}: ${describeError(error)}`);
                         return undefined;
                     }
                 })));
@@ -4193,7 +4204,7 @@ export class SessionEngine {
                     const bytes = Buffer.byteLength(JSON.stringify(item.record), "utf8") +
                         (ndjson === undefined ? 0 : Buffer.byteLength(ndjson, "utf8"));
                     if (bytes > budget) {
-                        this.logger(`[agent-sdk] session restore stopped at the ${policy.maxTotalBytes}-byte budget after ${restored} session(s); remaining sessions restore lazily on resume`);
+                        this.logger(`[bdk] session restore stopped at the ${policy.maxTotalBytes}-byte budget after ${restored} session(s); remaining sessions restore lazily on resume`);
                         break outer;
                     }
                     try {
@@ -4202,19 +4213,19 @@ export class SessionEngine {
                         restored += 1;
                     }
                     catch (error) {
-                        this.logger(`[agent-sdk] failed to restore session ${item.record.sessionId}: ${describeError(error)}`);
+                        this.logger(`[bdk] failed to restore session ${item.record.sessionId}: ${describeError(error)}`);
                     }
                 }
             }
             if (restored > 0) {
-                this.logger(`[agent-sdk] restored ${restored} session(s) from storage`);
+                this.logger(`[bdk] restored ${restored} session(s) from storage`);
             }
         });
     }
     /**
      * Local session lookup with lazy restore by session id.
      *
-     * `GET /v1/sessions` (cursor-hosted) can list durable rows that were not
+     * `GET /v1/sessions` (cursor-hosted) can list durable records that were not
      * bulk-restored into `--state-root` (restore caps, `restore: "off"`, or
      * eval Open-trace by id). Events/stream/follow-up must materialize that
      * one session before answering, or the playground shows an empty timeline
@@ -4299,11 +4310,11 @@ export class SessionEngine {
             // The durable record's bookkeeping may lag the event stream (the
             // storage coordinator skips volatile-only record rewrites, bounded).
             // New turnIds mint from turnCount, so clamp it to the highest turn the
-            // stream already used — otherwise a replaced pod re-mints turn_N ids
+            // stream already used; otherwise a replacement process re-mints turn_N ids
             // and trajectory/cost grouping merges unrelated turns.
             const restored = withTurnCountClampedToEvents(record, events);
             yield this.materializeSession(restored, eventsNdjson(events));
-            this.logger(`[agent-sdk] lazily restored session ${restored.sessionId} from storage`);
+            this.logger(`[bdk] lazily restored session ${restored.sessionId} from storage`);
             return restored;
         });
     }

package/dist/internal/session-run-log.d.ts

@@ -1,22 +1,9 @@
 /**
- * Durable hosted-execution run log on the framework file store. **v2 only.**
+ * Durable execution history for hosted architecture-v2 sessions.
  *
- * One JSON document per factory session (`ses_…`), with per-execution
- * entries inside. The later customer UI is session-scoped ("why did this
- * session fail?") so a single GET is the read path; continuations are FIFO
- * so last-write-wins merge is safe. Guest-local `hosted-execution.json` and
- * factorydb `last_error` are lossy: the on-disk diag dies with the pod, and
- * the session row only keeps the first 1024 characters of a generic HTTP
- * 500.
- *
- * Process death: persist `running` at turn start so SIGKILL / OOM still
- * leaves a durable leftover. `uncaughtException` / SIGTERM flush the same
- * session key with `processDeath: true` and the real throw. Soft-fail on
- * persist so a store outage never changes the hosted-execution HTTP reply.
- *
- * Same flush moments as `hosted-execution.json` and the start.log tee —
- * see `hosted-execution-flush.ts`. Keys:
- * {@link agentSdkStorageKeys.sessionRun}.
+ * Entries are session-scoped and bounded. The host writes a running entry at
+ * turn start, then records completion or process failure. Persistence errors
+ * never change the hosted execution response.
  */
 import type { FileSink } from "../files.js";
 import type { AgentProject } from "../types.js";
@@ -64,7 +51,7 @@ export type SessionRunLastFailure = {
     error?: SessionRunLogError;
     processDeath?: boolean;
 };
-/** One document per factory session. The customer UI reads this object. */
+/** One document per hosted session, read by the session history UI. */
 export type SessionRunLogDocument = {
     v: typeof SESSION_RUN_LOG_VERSION;
     sessionPublicId: string;
@@ -87,8 +74,8 @@ export interface SessionRunLogStore {
     flushProcessDeath(reason: Extract<SessionRunAbortReason, "process_exit" | "uncaught_exception" | "unhandled_rejection">, error?: unknown): Promise<void>;
 }
 /**
- * Install the crash-handler flush used by `bin/agent-serve` on
- * `uncaughtException`. One process, one active hosted serve.
+ * Install the process-level crash flush. One process has one active hosted
+ * server.
  */
 export declare function registerSessionRunFatalFlush(flush: (error: unknown) => Promise<void>): void;
 export declare function unregisterSessionRunFatalFlush(): void;
@@ -108,10 +95,9 @@ export declare function createSessionRunLogStore(input: {
     snapshotLogs?: () => readonly LogRingEntry[];
 }): SessionRunLogStore;
 /**
- * Same selection as the conversation mirror: architecture-v2 hosted
- * engines (generation env set). Store ids resolve lazily from env or the
- * task-bind files under `/run/cursor/secrets`. Self-hosted and v1 stay on
- * local disk / today's behavior.
+ * Enable durable execution history for architecture-v2 agents on
+ * Cursor-managed hosting. Self-hosted and architecture-v1 agents keep local
+ * behavior.
  */
 export declare function selectSessionRunLogStore(input: {
     project: AgentProject;

package/dist/internal/session-run-log.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-run-log.d.ts","sourceRoot":"","sources":["../../src/internal/session-run-log.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session-run-log.d.ts","sourceRoot":"","sources":["../../src/internal/session-run-log.ts"],"names":[],"mappings":"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"}