@cursor/july 0.1.96 → 0.1.99

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

@@ -0,0 +1,120 @@
+/**
+ * Durable hosted-execution run log on the framework file store. **v2 only.**
+ *
+ * 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.
+ *
+ * Keys: {@link storageKeys.sessionRun}.
+ */
+import type { FileSink } from "../files.js";
+import type { AgentProject } from "../types.js";
+import type { HostedExecutionDiagAbortReason } from "./hosted-execution-diag.js";
+import type { LogRingEntry } from "./log-ring.js";
+export declare const SESSION_RUN_LOG_VERSION = 1;
+/** Last N log-ring lines kept on each execution. */
+export declare const SESSION_RUN_LOG_MAX_ENTRIES = 200;
+/** Per-line cap so a runaway logger cannot blow the document. */
+export declare const SESSION_RUN_LOG_MAX_LINE_CHARS = 4096;
+/** Continuations are FIFO; keep a bounded history for the session UI. */
+export declare const SESSION_RUN_LOG_MAX_EXECUTIONS = 20;
+/** Crash-handler flush must not block `process.exit`. */
+export declare const SESSION_RUN_FATAL_FLUSH_TIMEOUT_MS = 2000;
+export type SessionRunAbortReason = HostedExecutionDiagAbortReason | "process_exit" | "uncaught_exception" | "unhandled_rejection";
+export type SessionRunLogError = {
+    name: string;
+    message: string;
+    stack?: string;
+};
+export type SessionRunExecution = {
+    executionId: string;
+    writtenAt: string;
+    sessionId: string;
+    turnStatus: string;
+    durationMs: number;
+    abortReason?: SessionRunAbortReason;
+    message?: string;
+    error?: SessionRunLogError;
+    /** True when this entry was flushed from a process-death handler. */
+    processDeath?: boolean;
+    logs: LogRingEntry[];
+};
+/**
+ * Latest non-success execution, including leftover `running` after the
+ * process died without a terminal persist (SIGKILL / OOM). Undefined when
+ * the latest execution `turnStatus` is `finished`.
+ */
+export type SessionRunLastFailure = {
+    executionId: string;
+    writtenAt: string;
+    turnStatus: string;
+    abortReason?: SessionRunAbortReason;
+    message?: string;
+    error?: SessionRunLogError;
+    processDeath?: boolean;
+};
+/** One document per factory session. The customer UI reads this object. */
+export type SessionRunLogDocument = {
+    v: typeof SESSION_RUN_LOG_VERSION;
+    sessionPublicId: string;
+    updatedAt: string;
+    lastFailure?: SessionRunLastFailure;
+    executions: SessionRunExecution[];
+};
+/** Persist input: one execution upserted into the session document. */
+export type SessionRunExecutionWrite = SessionRunExecution & {
+    sessionPublicId: string;
+};
+export interface SessionRunLogStore {
+    persist(write: SessionRunExecutionWrite): Promise<void>;
+    read(sessionPublicId: string): Promise<SessionRunLogDocument | undefined>;
+    /**
+     * Upgrade the in-flight `running` claim to a terminal process-death
+     * entry. No-op when no execution is active (already terminal, or never
+     * started). Soft-fail.
+     */
+    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.
+ */
+export declare function registerSessionRunFatalFlush(flush: (error: unknown) => Promise<void>): void;
+export declare function unregisterSessionRunFatalFlush(): void;
+/**
+ * Await the registered crash flush, bounded so a hung store cannot prevent
+ * `process.exit`. Soft-fail.
+ */
+export declare function flushSessionRunFatal(error: unknown): Promise<void>;
+export declare function serializeSessionRunError(error: unknown): SessionRunLogError;
+export declare function snapshotSessionRunLogs(entries: readonly LogRingEntry[]): LogRingEntry[];
+export declare function lastFailureFromExecutions(executions: readonly SessionRunExecution[]): SessionRunLastFailure | undefined;
+export declare function parseSessionRunLogDocument(value: unknown): SessionRunLogDocument | undefined;
+export declare function createSessionRunLogStore(input: {
+    sink: FileSink;
+    agentName: string;
+    logger?: (line: string) => void;
+    snapshotLogs?: () => readonly LogRingEntry[];
+}): SessionRunLogStore;
+/**
+ * Same selection as the conversation mirror: architecture-v2 hosted
+ * engines with a provisioned framework file store. Self-hosted and v1
+ * stay on local disk / today's behavior. This is the only path that
+ * installs the session-run log — v1 never writes these documents.
+ */
+export declare function selectSessionRunLogStore(input: {
+    project: AgentProject;
+    logger?: (line: string) => void;
+    env?: Record<string, string | undefined>;
+    snapshotLogs?: () => readonly LogRingEntry[];
+}): SessionRunLogStore | undefined;
+//# sourceMappingURL=session-run-log.d.ts.map

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

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

package/dist/internal/session-run-log.js

@@ -0,0 +1,359 @@
+/**
+ * Durable hosted-execution run log on the framework file store. **v2 only.**
+ *
+ * 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.
+ *
+ * Keys: {@link storageKeys.sessionRun}.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { cursorFrameworkStoreSourceId, cursorHostedFiles, } from "../files-backends/cursor-hosted.js";
+import { storageKeys } from "../storage-protocol.js";
+import { resolveApiKeySync } from "./cursor/credentials.js";
+import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
+import { describeError } from "./describe-error.js";
+export const SESSION_RUN_LOG_VERSION = 1;
+/** Last N log-ring lines kept on each execution. */
+export const SESSION_RUN_LOG_MAX_ENTRIES = 200;
+/** Per-line cap so a runaway logger cannot blow the document. */
+export const SESSION_RUN_LOG_MAX_LINE_CHARS = 4096;
+/** Continuations are FIFO; keep a bounded history for the session UI. */
+export const SESSION_RUN_LOG_MAX_EXECUTIONS = 20;
+const MAX_ERROR_MESSAGE_CHARS = 4096;
+const MAX_ERROR_STACK_CHARS = 16384;
+const MAX_DOCUMENT_CHARS = 512 * 1024;
+/** Crash-handler flush must not block `process.exit`. */
+export const SESSION_RUN_FATAL_FLUSH_TIMEOUT_MS = 2000;
+let fatalFlush;
+/**
+ * Install the crash-handler flush used by `bin/agent-serve` on
+ * `uncaughtException`. One process, one active hosted serve.
+ */
+export function registerSessionRunFatalFlush(flush) {
+    fatalFlush = flush;
+}
+export function unregisterSessionRunFatalFlush() {
+    fatalFlush = undefined;
+}
+/**
+ * Await the registered crash flush, bounded so a hung store cannot prevent
+ * `process.exit`. Soft-fail.
+ */
+export function flushSessionRunFatal(error) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (fatalFlush === undefined) {
+            return;
+        }
+        yield Promise.race([
+            fatalFlush(error).catch(() => undefined),
+            new Promise((resolve) => {
+                setTimeout(resolve, SESSION_RUN_FATAL_FLUSH_TIMEOUT_MS);
+            }),
+        ]);
+    });
+}
+function boundedText(value, max) {
+    return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+function boundedOptionalText(value, max) {
+    if (value === undefined || value.length === 0) {
+        return undefined;
+    }
+    return boundedText(value, max);
+}
+export function serializeSessionRunError(error) {
+    if (error instanceof Error) {
+        const stack = boundedOptionalText(error.stack, MAX_ERROR_STACK_CHARS);
+        return Object.assign({ name: boundedText(error.name.length > 0 ? error.name : "Error", 128), message: boundedText(error.message, MAX_ERROR_MESSAGE_CHARS) }, (stack === undefined ? {} : { stack }));
+    }
+    return {
+        name: "Error",
+        message: boundedText(String(error), MAX_ERROR_MESSAGE_CHARS),
+    };
+}
+export function snapshotSessionRunLogs(entries) {
+    const tail = entries.slice(-SESSION_RUN_LOG_MAX_ENTRIES);
+    return tail.map((entry) => ({
+        index: entry.index,
+        at: entry.at,
+        line: boundedText(entry.line, SESSION_RUN_LOG_MAX_LINE_CHARS),
+    }));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function decodeSinkBody(body) {
+    return body instanceof Uint8Array ? body : body.body;
+}
+function parseError(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const name = typeof value.name === "string" ? value.name : "";
+    const message = typeof value.message === "string" ? value.message : "";
+    const stack = typeof value.stack === "string" ? value.stack : undefined;
+    return Object.assign({ name,
+        message }, (stack === undefined ? {} : { stack }));
+}
+function parseLogs(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const logs = [];
+    for (const entry of value) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        if (typeof entry.index !== "number" ||
+            typeof entry.at !== "string" ||
+            typeof entry.line !== "string") {
+            continue;
+        }
+        logs.push({ index: entry.index, at: entry.at, line: entry.line });
+    }
+    return logs;
+}
+function parseExecution(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const executionId = typeof value.executionId === "string" ? value.executionId : undefined;
+    const writtenAt = typeof value.writtenAt === "string" ? value.writtenAt : undefined;
+    const sessionId = typeof value.sessionId === "string" ? value.sessionId : undefined;
+    const turnStatus = typeof value.turnStatus === "string" ? value.turnStatus : undefined;
+    const durationMs = typeof value.durationMs === "number" && Number.isFinite(value.durationMs)
+        ? value.durationMs
+        : undefined;
+    if (executionId === undefined ||
+        executionId.length === 0 ||
+        writtenAt === undefined ||
+        sessionId === undefined ||
+        turnStatus === undefined ||
+        turnStatus.length === 0 ||
+        durationMs === undefined ||
+        durationMs < 0) {
+        return undefined;
+    }
+    const abortReason = typeof value.abortReason === "string" ? value.abortReason : undefined;
+    const message = typeof value.message === "string" ? value.message : undefined;
+    const error = parseError(value.error);
+    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ executionId,
+        writtenAt,
+        sessionId,
+        turnStatus,
+        durationMs }, (abortReason === undefined
+        ? {}
+        : { abortReason: abortReason })), (message === undefined ? {} : { message })), (error === undefined ? {} : { error })), (value.processDeath === true ? { processDeath: true } : {})), { logs: parseLogs(value.logs) });
+}
+export function lastFailureFromExecutions(executions) {
+    const latest = executions.at(-1);
+    if (latest === undefined || latest.turnStatus === "finished") {
+        return undefined;
+    }
+    return Object.assign(Object.assign(Object.assign(Object.assign({ executionId: latest.executionId, writtenAt: latest.writtenAt, turnStatus: latest.turnStatus }, (latest.abortReason === undefined
+        ? {}
+        : { abortReason: latest.abortReason })), (latest.message === undefined ? {} : { message: latest.message })), (latest.error === undefined ? {} : { error: latest.error })), (latest.processDeath === true ? { processDeath: true } : {}));
+}
+function boundExecution(write) {
+    const error = write.error === undefined
+        ? undefined
+        : Object.assign({ name: boundedText(write.error.name, 128), message: boundedText(write.error.message, MAX_ERROR_MESSAGE_CHARS) }, (write.error.stack === undefined
+            ? {}
+            : {
+                stack: boundedText(write.error.stack, MAX_ERROR_STACK_CHARS),
+            }));
+    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ executionId: write.executionId, writtenAt: write.writtenAt, sessionId: write.sessionId, turnStatus: write.turnStatus, durationMs: write.durationMs }, (write.abortReason === undefined
+        ? {}
+        : { abortReason: write.abortReason })), (boundedOptionalText(write.message, MAX_ERROR_MESSAGE_CHARS) ===
+        undefined
+        ? {}
+        : {
+            message: boundedOptionalText(write.message, MAX_ERROR_MESSAGE_CHARS),
+        })), (error === undefined ? {} : { error })), (write.processDeath === true ? { processDeath: true } : {})), { logs: snapshotSessionRunLogs(write.logs) });
+}
+function upsertExecution(existing, next) {
+    const executions = existing.filter((entry) => entry.executionId !== next.executionId);
+    executions.push(next);
+    executions.sort((a, b) => a.writtenAt.localeCompare(b.writtenAt));
+    return executions.slice(-SESSION_RUN_LOG_MAX_EXECUTIONS);
+}
+function shrinkSessionDocument(document) {
+    let executions = document.executions;
+    let next = Object.assign(Object.assign({}, document), { executions, lastFailure: lastFailureFromExecutions(executions) });
+    let serialized = JSON.stringify(next);
+    while (serialized.length > MAX_DOCUMENT_CHARS) {
+        const oldestWithLogs = executions.findIndex((entry) => entry.logs.length > 0);
+        if (oldestWithLogs >= 0) {
+            const entry = executions[oldestWithLogs];
+            executions = executions.map((item, index) => index === oldestWithLogs
+                ? Object.assign(Object.assign({}, entry), { logs: entry.logs.slice(Math.ceil(entry.logs.length / 2)) }) : item);
+        }
+        else if (executions.length > 1) {
+            executions = executions.slice(1);
+        }
+        else {
+            break;
+        }
+        next = Object.assign(Object.assign({}, document), { executions, lastFailure: lastFailureFromExecutions(executions) });
+        serialized = JSON.stringify(next);
+    }
+    return next;
+}
+export function parseSessionRunLogDocument(value) {
+    if (!isRecord(value) || value.v !== SESSION_RUN_LOG_VERSION) {
+        return undefined;
+    }
+    const sessionPublicId = typeof value.sessionPublicId === "string"
+        ? value.sessionPublicId
+        : undefined;
+    const updatedAt = typeof value.updatedAt === "string" ? value.updatedAt : undefined;
+    if (sessionPublicId === undefined ||
+        sessionPublicId.length === 0 ||
+        updatedAt === undefined ||
+        !Array.isArray(value.executions)) {
+        return undefined;
+    }
+    const executions = [];
+    for (const entry of value.executions) {
+        const parsed = parseExecution(entry);
+        if (parsed !== undefined) {
+            executions.push(parsed);
+        }
+    }
+    executions.sort((a, b) => a.writtenAt.localeCompare(b.writtenAt));
+    const lastFailure = lastFailureFromExecutions(executions);
+    return Object.assign(Object.assign({ v: SESSION_RUN_LOG_VERSION, sessionPublicId,
+        updatedAt }, (lastFailure === undefined ? {} : { lastFailure })), { executions });
+}
+export function createSessionRunLogStore(input) {
+    var _a;
+    const { sink, agentName } = input;
+    const logger = (_a = input.logger) !== null && _a !== void 0 ? _a : (() => { });
+    let active;
+    const readDocument = (sessionPublicId) => __awaiter(this, void 0, void 0, function* () {
+        const key = storageKeys.sessionRun(agentName, sessionPublicId);
+        const body = yield sink.get(key);
+        if (body === undefined) {
+            return undefined;
+        }
+        try {
+            return parseSessionRunLogDocument(JSON.parse(new TextDecoder().decode(decodeSinkBody(body))));
+        }
+        catch (error) {
+            logger(`[agent-sdk] session-run log: skip unreadable ${key} (${describeError(error)})`);
+            return undefined;
+        }
+    });
+    const persistWrite = (write) => __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const fitted = boundExecution(write);
+        let existing;
+        try {
+            existing = yield readDocument(write.sessionPublicId);
+        }
+        catch (error) {
+            logger(`[agent-sdk] session-run log: persist failed for ${fitted.executionId} (${describeError(error)})`);
+            return;
+        }
+        const executions = upsertExecution((_a = existing === null || existing === void 0 ? void 0 : existing.executions) !== null && _a !== void 0 ? _a : [], fitted);
+        const document = shrinkSessionDocument({
+            v: SESSION_RUN_LOG_VERSION,
+            sessionPublicId: write.sessionPublicId,
+            updatedAt: fitted.writtenAt,
+            executions,
+        });
+        const key = storageKeys.sessionRun(agentName, document.sessionPublicId);
+        try {
+            yield sink.put(key, new TextEncoder().encode(JSON.stringify(document)));
+        }
+        catch (error) {
+            logger(`[agent-sdk] session-run log: persist failed for ${fitted.executionId} (${describeError(error)})`);
+            return;
+        }
+        if (fitted.turnStatus === "running") {
+            active = {
+                sessionPublicId: write.sessionPublicId,
+                executionId: fitted.executionId,
+                sessionId: fitted.sessionId,
+                startedAt: Date.now(),
+            };
+            return;
+        }
+        if ((active === null || active === void 0 ? void 0 : active.executionId) === fitted.executionId) {
+            active = undefined;
+        }
+    });
+    return {
+        persist: persistWrite,
+        read(sessionPublicId) {
+            return __awaiter(this, void 0, void 0, function* () {
+                try {
+                    return yield readDocument(sessionPublicId);
+                }
+                catch (error) {
+                    logger(`[agent-sdk] session-run log: read failed for ${sessionPublicId} (${describeError(error)})`);
+                    return undefined;
+                }
+            });
+        },
+        flushProcessDeath(reason, error) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                var _b;
+                if (active === undefined) {
+                    return;
+                }
+                const current = active;
+                const serialized = error === undefined ? undefined : serializeSessionRunError(error);
+                const message = error instanceof Error
+                    ? error.message
+                    : error !== undefined
+                        ? String(error)
+                        : "process died during hosted execution";
+                yield persistWrite(Object.assign(Object.assign({ sessionPublicId: current.sessionPublicId, executionId: current.executionId, writtenAt: new Date().toISOString(), sessionId: current.sessionId, turnStatus: "error", durationMs: Math.max(0, Date.now() - current.startedAt), abortReason: reason, processDeath: true, message }, (serialized === undefined ? {} : { error: serialized })), { logs: snapshotSessionRunLogs((_b = (_a = input.snapshotLogs) === null || _a === void 0 ? void 0 : _a.call(input)) !== null && _b !== void 0 ? _b : []) }));
+            });
+        },
+    };
+}
+/**
+ * Same selection as the conversation mirror: architecture-v2 hosted
+ * engines with a provisioned framework file store. Self-hosted and v1
+ * stay on local disk / today's behavior. This is the only path that
+ * installs the session-run log — v1 never writes these documents.
+ */
+export function selectSessionRunLogStore(input) {
+    var _a;
+    if (input.project.agent.architecture !== "v2") {
+        return undefined;
+    }
+    const env = (_a = input.env) !== null && _a !== void 0 ? _a : process.env;
+    const frameworkStoreId = cursorFrameworkStoreSourceId(env);
+    if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined ||
+        frameworkStoreId === undefined) {
+        return undefined;
+    }
+    return createSessionRunLogStore(Object.assign({ sink: cursorHostedFiles({
+            storeSourceId: frameworkStoreId,
+            resolveApiKey: () => { var _a; return (_a = resolveApiKeySync()) === null || _a === void 0 ? void 0 : _a.apiKey; },
+        }), agentName: input.project.name, logger: input.logger }, (input.snapshotLogs === undefined
+        ? {}
+        : { snapshotLogs: input.snapshotLogs })));
+}

package/dist/internal/sessions-client.d.ts

@@ -10,16 +10,18 @@ export interface ListedSessions {
     /** Present when the server reports which store answered. */
     source?: SessionListSource;
 }
-export declare function listSessions(args: {
+export interface ListSessionsArgs {
     baseUrl: string;
     auth?: RequestAuth;
     fetchImpl?: typeof fetch;
-}): Promise<SessionSummary[]>;
-export declare function listSessionsWithSource(args: {
-    baseUrl: string;
-    auth?: RequestAuth;
-    fetchImpl?: typeof fetch;
-}): Promise<ListedSessions>;
+    /**
+     * Ask for only the newest visible session (`?latest=1`). The server
+     * answers from memory where it can instead of scanning durable storage.
+     */
+    latest?: boolean;
+}
+export declare function listSessions(args: ListSessionsArgs): Promise<SessionSummary[]>;
+export declare function listSessionsWithSource(args: ListSessionsArgs): Promise<ListedSessions>;
 export declare function fetchSessionEvents(args: {
     baseUrl: string;
     sessionId: string;

package/dist/internal/sessions-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sessions-client.d.ts","sourceRoot":"","sources":["../../src/internal/sessions-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAE5B;AAED,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,cAAc,CAAC,CAiC1B;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAuE1B;AAkCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAClC,cAAc,GAAG,SAAS,CAU5B;AAED,+DAA+D;AAC/D,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO9B;AAED,+DAA+D;AAC/D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAIzE;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAAE,GACvC,MAAM,CAkBR"}
+{"version":3,"file":"sessions-client.d.ts","sourceRoot":"","sources":["../../src/internal/sessions-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,cAAc,EAAE,CAAC,CAE3B;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,cAAc,CAAC,CAkCzB;AAED,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAuE1B;AAmCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAClC,cAAc,GAAG,SAAS,CAU5B;AAED,+DAA+D;AAC/D,wBAAsB,wBAAwB,CAAC,IAAI,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO9B;AAED,+DAA+D;AAC/D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAIzE;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,iBAAiB,CAAA;CAAE,GACvC,MAAM,CAkBR"}

package/dist/internal/sessions-client.js

@@ -24,9 +24,10 @@ export function listSessionsWithSource(args) {
         var _a;
         const baseUrl = args.baseUrl.replace(/\/$/, "");
         const fetchImpl = (_a = args.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+        const query = args.latest === true ? "?latest=1" : "";
         let resp;
         try {
-            resp = yield fetchImpl(`${baseUrl}/v1/sessions`, {
+            resp = yield fetchImpl(`${baseUrl}/v1/sessions${query}`, {
                 headers: mergeRequestHeaders(args.auth),
             });
         }
@@ -146,6 +147,7 @@ function parseSessionSummary(value) {
         queued: typeof row.queued === "boolean" ? row.queued : undefined,
         createdAt: typeof row.createdAt === "string" ? row.createdAt : "",
         updatedAt: typeof row.updatedAt === "string" ? row.updatedAt : "",
+        dryRun: row.dryRun === true ? true : undefined,
         continuationToken,
         externalUrl: typeof row.externalUrl === "string" ? row.externalUrl : undefined,
         prUrl: typeof row.prUrl === "string" ? row.prUrl : undefined,

package/dist/internal/storage-coordinator.d.ts

@@ -98,6 +98,13 @@ export declare class StorageCoordinator implements FrameworkSessionStore, Author
      * so the caller can fall back to the local session store.
      */
     listSessionsFromSink(): Promise<SessionRecord[]>;
+    /**
+     * Newest-written session records from the sink (`GET /v1/sessions?latest=1`
+     * on a host whose local store has nothing for the caller). Same error
+     * posture as {@link listSessionsFromSink}; `undefined` when the sink
+     * cannot order by write time, so the caller falls back to the full list.
+     */
+    listNewestSessionsFromSink(limit: number): Promise<SessionRecord[] | undefined>;
     /**
      * Saved event stream for one session: chunk values concatenated in key
      * order (chunks are keyed by their first event's index, zero-padded, so
@@ -124,6 +131,12 @@ export declare class StorageCoordinator implements FrameworkSessionStore, Author
     /**
      * Whether the sink can serve awaited author reads/writes (`get` is
      * required — `put` is always present on {@link StorageConfig}).
+     *
+     * A sink may keep `get` for framework session state while refusing author
+     * KV: hosted v2 reads sessions from the framework file store but has no
+     * working KV backend, and author handlers that cannot read their own
+     * writes back are better served by the local-disk fallback than by a sink
+     * that accepts every write and forgets it.
      */
     get supportsAuthorKv(): boolean;
     /**

package/dist/internal/storage-coordinator.d.ts.map

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

package/dist/internal/storage-coordinator.js

@@ -34,6 +34,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { resolveStoragePolicy, storageKeys, } from "../storage.js";
 import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
 import { describeError } from "./describe-error.js";
+import { isAuthorKvUnsupported } from "./null-kv-storage.js";
 /** Event types that close a unit of work — flush point for turn-end batching. */
 const TURN_BOUNDARY_EVENTS = new Set([
     "turn.completed",
@@ -62,6 +63,14 @@ const DEBOUNCE_MAX_BATCH = 200;
  * convenience backfill, not a source of truth.
  */
 const AB_SNAPSHOT_MIN_INTERVAL_MS = 60000;
+/** Session records out of raw sink entries; rows without a usable id are dropped. */
+function sessionRecordsOf(entries) {
+    return entries
+        .map((entry) => entry.value)
+        .filter((record) => record != null &&
+        typeof record.sessionId === "string" &&
+        record.sessionId !== "");
+}
 export class StorageCoordinator {
     constructor(options) {
         /** Per-session pending state (events + coalesced record). */
@@ -233,11 +242,26 @@ export class StorageCoordinator {
             if (!Array.isArray(entries)) {
                 throw new Error("storage list returned a non-array");
             }
-            return entries
-                .map((entry) => entry.value)
-                .filter((record) => record != null &&
-                typeof record.sessionId === "string" &&
-                record.sessionId !== "");
+            return sessionRecordsOf(entries);
+        });
+    }
+    /**
+     * Newest-written session records from the sink (`GET /v1/sessions?latest=1`
+     * on a host whose local store has nothing for the caller). Same error
+     * posture as {@link listSessionsFromSink}; `undefined` when the sink
+     * cannot order by write time, so the caller falls back to the full list.
+     */
+    listNewestSessionsFromSink(limit) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const listNewest = this.definition.listNewest;
+            if (listNewest === undefined) {
+                return undefined;
+            }
+            const entries = yield listNewest(storageKeys.sessionPrefix(this.agentName), limit, this.context("restore"));
+            if (!Array.isArray(entries)) {
+                throw new Error("storage listNewest returned a non-array");
+            }
+            return sessionRecordsOf(entries);
         });
     }
     /**
@@ -333,9 +357,16 @@ export class StorageCoordinator {
     /**
      * Whether the sink can serve awaited author reads/writes (`get` is
      * required — `put` is always present on {@link StorageConfig}).
+     *
+     * A sink may keep `get` for framework session state while refusing author
+     * KV: hosted v2 reads sessions from the framework file store but has no
+     * working KV backend, and author handlers that cannot read their own
+     * writes back are better served by the local-disk fallback than by a sink
+     * that accepts every write and forgets it.
      */
     get supportsAuthorKv() {
-        return this.definition.get !== undefined;
+        return (this.definition.get !== undefined &&
+            !isAuthorKvUnsupported(this.definition));
     }
     /**
      * Awaited author KV read. Unlike framework session mirrors, this awaits