@cursor/july 0.1.1 → 0.1.3

package/dist/internal/session-engine.js

@@ -26,8 +26,8 @@ var __rest = (this && this.__rest) || function (s, e) {
         }
     return t;
 };
-import { mkdir, rm } from "node:fs/promises";
-import { join } from "node:path";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { mergeABInstructions, resolveABMaxPlaygroundSessions, resolveABSplit, } from "../ab.js";
 import { slackThreadPermalink } from "../channels/slack/links.js";
 import { DIRECT_TOOL_CALL_CHANNEL_ID, isSymbolicConnectionTransport, } from "../types.js";
@@ -37,18 +37,21 @@ import { buildABSnapshot } from "./ab-snapshot.js";
 import { ApprovalGate } from "./approval-gate.js";
 import { samePrincipal } from "./auth.js";
 import { mergeCloudOptions, resolveSessionRuntime } from "./cloud-merge.js";
+import { isDevMode } from "./dev-mode.js";
 import { EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
 import { createHostPlatforms } from "./host-platforms.js";
 import { formatContinuationToken, newContinuationKey, newSessionId, newToolCallId, } from "./ids.js";
 import { validateToolInput } from "./json-schema.js";
 import { McpHost } from "./mcp-host.js";
+import { buildIdentitySection, buildSessionContextBlock, SCHEDULE_CHANNEL_PREFIX, } from "./prompt-context.js";
 import { assertCloudCanHonorAccountServersFilters } from "./resolved-connections.js";
 import { SessionStore } from "./session-store.js";
+import { StorageCoordinator } from "./storage-coordinator.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
 import { buildAgentToolsCatalog, materializeWorkspace, writeWorkspaceFiles, } from "./workspace.js";
 export const HTTP_CHANNEL_ID = "http";
-export const SCHEDULE_CHANNEL_PREFIX = "schedule:";
+export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
 export class SessionBusyError extends Error {
     constructor(sessionId) {
         super(`Session ${sessionId} already has a running turn; wait for session.waiting before sending a follow-up`);
@@ -106,8 +109,10 @@ export class ApprovalInterruptedError extends Error {
 }
 export class SessionEngine {
     constructor(options) {
-        var _a;
-        var _b;
+        var _a, _b;
+        var _c, _d, _e;
+        /** In-flight lazy restores, deduped per channel + continuation key. */
+        this.restoreInFlight = new Map();
         this.channelsById = new Map();
         /** Sessions with a turn being admitted (before the run promise exists). */
         this.pendingTurns = new Set();
@@ -126,17 +131,29 @@ export class SessionEngine {
         this.project = options.project;
         this.stateRoot = options.stateRoot;
         this.runner = options.runner;
-        this.logger = (_b = options.logger) !== null && _b !== void 0 ? _b : (() => { });
+        this.logger = (_c = options.logger) !== null && _c !== void 0 ? _c : (() => { });
         this.sessions = new SessionStore(join(options.stateRoot, "sessions"));
         this.logs = new EventLogStore((sessionId) => this.sessions.eventFilePath(sessionId), (sessionId, error) => this.logger(`[agent-serve] failed to persist events for ${sessionId}: ${describeError(error)}`));
-        this.abCollector = new ABCollector(options.project.abs, this.logger, (sessionId) => __awaiter(this, void 0, void 0, function* () { return (yield this.logs.get(sessionId)).snapshot(0); }), Object.assign({ projectRoot: options.project.rootDir }, (((_a = options.project.abConfig) === null || _a === void 0 ? void 0 : _a.persistSamples) === undefined
-            ? {}
-            : { persistSamples: options.project.abConfig.persistSamples })));
+        this.storage =
+            options.project.storage === undefined
+                ? undefined
+                : new StorageCoordinator({
+                    definition: options.project.storage,
+                    agentName: options.project.name,
+                    projectRoot: options.project.rootDir,
+                    logger: this.logger,
+                });
+        // Domain-specific hooks win; the defineStorage sink is the fallback.
+        const persistSamples = (_d = (_a = options.project.abConfig) === null || _a === void 0 ? void 0 : _a.persistSamples) !== null && _d !== void 0 ? _d : (_b = this.storage) === null || _b === void 0 ? void 0 : _b.asABSamplePersistence();
+        this.abCollector = new ABCollector(options.project.abs, this.logger, (sessionId) => __awaiter(this, void 0, void 0, function* () { return (yield this.logs.get(sessionId)).snapshot(0); }), {
+            projectRoot: options.project.rootDir,
+            persistSamples,
+        });
         // Peer and Cursor-account transports are symbolic until the serve host
         // resolves them; the host-side MCP registry starts with the concrete
         // connections and gains the rest via setResolvedConnections.
         this.mcpHost = new McpHost(options.project.agent.connections.filter((connection) => !isSymbolicConnectionTransport(connection.transport)));
-        this.platforms = createHostPlatforms();
+        this.platforms = (_e = options.platforms) !== null && _e !== void 0 ? _e : createHostPlatforms();
         for (const channel of options.project.channels) {
             this.channelsById.set(channel.id, channel.definition);
         }
@@ -181,11 +198,17 @@ export class SessionEngine {
      */
     send(channelId_1, message_1) {
         return __awaiter(this, arguments, void 0, function* (channelId, message, options = {}) {
-            var _a, _b, _c;
-            const auth = (_a = options.auth) !== null && _a !== void 0 ? _a : null;
-            const existing = options.continuationToken === undefined
+            var _a;
+            var _b, _c, _d;
+            const auth = (_b = options.auth) !== null && _b !== void 0 ? _b : null;
+            let existing = options.continuationToken === undefined
                 ? undefined
                 : yield this.sessions.findByContinuation(channelId, options.continuationToken);
+            if (existing === undefined && options.continuationToken !== undefined) {
+                // Local miss: the session may live only in the storage sink (it
+                // fell outside the startup restore window, or restore is lazy-only).
+                existing = yield this.restoreSessionByContinuation(channelId, options.continuationToken);
+            }
             if (existing !== undefined) {
                 if (!samePrincipal(existing.auth, auth)) {
                     throw new SessionAuthError(existing.sessionId);
@@ -209,9 +232,9 @@ export class SessionEngine {
             let record = {
                 sessionId: newSessionId(),
                 channelId,
-                mode: (_b = options.mode) !== null && _b !== void 0 ? _b : "chat",
+                mode: (_c = options.mode) !== null && _c !== void 0 ? _c : "chat",
                 purpose,
-                continuationKey: (_c = options.continuationToken) !== null && _c !== void 0 ? _c : newContinuationKey(),
+                continuationKey: (_d = options.continuationToken) !== null && _d !== void 0 ? _d : newContinuationKey(),
                 auth,
                 title: options.title,
                 channelState,
@@ -224,6 +247,7 @@ export class SessionEngine {
                 updatedAt: now,
             };
             yield this.sessions.save(record);
+            (_a = this.storage) === null || _a === void 0 ? void 0 : _a.sessionRecord(record);
             yield this.appendEvent(record.sessionId, {
                 type: "session.started",
                 data: { channelId },
@@ -515,7 +539,10 @@ export class SessionEngine {
                     // Yield so the HTTP NDJSON writer can flush tool start/result
                     // events while sibling parallel tools are still executing.
                     if (update.type === "tool-call-started" ||
-                        update.type === "tool-call-completed") {
+                        update.type === "tool-call-completed" ||
+                        // Nested subagent progress (newer SDKs); string check keeps
+                        // typecheck green against older published `@cursor/sdk` pins.
+                        update.type === "tool-call-delta") {
                         yield yieldEventLoop();
                     }
                 }), signal);
@@ -579,8 +606,8 @@ export class SessionEngine {
         });
     }
     buildTurnRequest(record, agent, turnId, prompt, isFirstTurn, emit, onUpdate, signal) {
-        var _a;
-        var _b;
+        var _a, _b, _c;
+        var _d;
         // Per-session cloud attach (channel/tool handoff) forces cloud runtime
         // even when the agent defaults to local for chat server tools.
         const runtime = resolveSessionRuntime({
@@ -594,14 +621,24 @@ export class SessionEngine {
             })
             : undefined;
         let turnPrompt = prompt;
+        if (isFirstTurn) {
+            const contextBlock = buildSessionContextBlock({
+                sessionId: record.sessionId,
+                channelId: record.channelId,
+                channelKind: (_b = (_a = this.channelsById.get(record.channelId)) === null || _a === void 0 ? void 0 : _a.meta) === null || _b === void 0 ? void 0 : _b.kind,
+                environment: isDevMode() ? "local dev server" : "hosted deployment",
+            });
+            turnPrompt = `${contextBlock}\n\n${prompt}`;
+        }
         if (runtime === "cloud" && isFirstTurn) {
             const preamble = [
-                (_b = (_a = agent.instructions) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : "",
+                (_d = (_c = agent.instructions) === null || _c === void 0 ? void 0 : _c.trim()) !== null && _d !== void 0 ? _d : "",
+                buildIdentitySection(agent),
                 buildAgentToolsCatalog(agent.tools, { includeScripts: true }),
             ]
                 .filter((part) => part !== "")
                 .join("\n\n");
-            turnPrompt = preamble === "" ? prompt : `${preamble}\n\n${prompt}`;
+            turnPrompt = `${preamble}\n\n${turnPrompt}`;
         }
         return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId }, (record.sdkAgentId === undefined
             ? {}
@@ -996,11 +1033,22 @@ export class SessionEngine {
     }
     queueDispatch(sessionId, event) {
         var _a;
-        const chain = (_a = this.dispatchChains.get(sessionId)) !== null && _a !== void 0 ? _a : Promise.resolve();
+        var _b;
+        // Single funnel for both append paths (appendEvent + the held-log emit),
+        // so the storage sink sees every durable event exactly once.
+        (_a = this.storage) === null || _a === void 0 ? void 0 : _a.event(event);
+        const chain = (_b = this.dispatchChains.get(sessionId)) !== null && _b !== void 0 ? _b : Promise.resolve();
         const next = chain
             .then(() => this.dispatchEvent(sessionId, event))
             .catch((error) => {
             this.logger(`[agent-serve] event dispatch failed for ${sessionId}: ${describeError(error)}`);
+        })
+            .then(() => {
+            var _a;
+            // Turn-end flush happens here — after the boundary event's handlers
+            // and their record updates settled — so the persisted record carries
+            // the turn's final channel state and continuation token.
+            (_a = this.storage) === null || _a === void 0 ? void 0 : _a.eventDispatched(event);
         });
         this.dispatchChains.set(sessionId, next);
     }
@@ -1127,10 +1175,29 @@ export class SessionEngine {
      */
     abSnapshot(caller, options) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            var _b;
             const sessions = yield this.listSessions(caller, options);
             const abConfig = this.project.abConfig;
             const maxPlaygroundSessions = resolveABMaxPlaygroundSessions(abConfig === null || abConfig === void 0 ? void 0 : abConfig.maxPlaygroundSessions);
             const foldedSessions = sessions.slice(0, maxPlaygroundSessions);
+            // Backfill for a replacement host with nothing local to fold (e.g.
+            // lazy-only restore before any session resumed): serve the persisted
+            // aggregate instead of an empty surface. Gated on the host having no
+            // sessions AT ALL — the persisted snapshot spans every principal, so a
+            // caller who merely owns no sessions must not see it. Loaded once per
+            // process (playground polls this route ~every 4s); skip the persist
+            // side effect below — re-saving a restored snapshot would echo stale
+            // data back into the store.
+            if (foldedSessions.length === 0 &&
+                this.storage !== undefined &&
+                (yield this.sessions.list()).length === 0) {
+                (_b = this.restoredAbSnapshot) !== null && _b !== void 0 ? _b : (this.restoredAbSnapshot = this.storage.getLatestAbSnapshot());
+                const restoredSnapshot = yield this.restoredAbSnapshot;
+                if (restoredSnapshot !== undefined) {
+                    return restoredSnapshot;
+                }
+            }
             const snapshot = yield buildABSnapshot({
                 experiments: this.project.abs,
                 agentName: this.project.name,
@@ -1158,6 +1225,10 @@ export class SessionEngine {
                     this.logger(`[agent-serve] ab persistSnapshots.save threw: ${describeError(error)}`);
                 }
             }
+            else {
+                // defineStorage fallback (throttled inside the coordinator).
+                (_a = this.storage) === null || _a === void 0 ? void 0 : _a.abSnapshot(snapshot);
+            }
             return snapshot;
         });
     }
@@ -1275,12 +1346,14 @@ export class SessionEngine {
         var _a;
         const chain = (_a = this.updateChains.get(sessionId)) !== null && _a !== void 0 ? _a : Promise.resolve();
         const next = chain.then(() => __awaiter(this, void 0, void 0, function* () {
+            var _a;
             const current = yield this.sessions.get(sessionId);
             if (current === undefined) {
                 throw new Error(`Session ${sessionId} not found`);
             }
             const updated = Object.assign(Object.assign({}, updater(current)), { updatedAt: new Date().toISOString() });
             yield this.sessions.save(updated);
+            (_a = this.storage) === null || _a === void 0 ? void 0 : _a.sessionRecord(updated);
             return updated;
         }));
         this.updateChains.set(sessionId, next.catch(() => { }));
@@ -1289,6 +1362,167 @@ export class SessionEngine {
     // ==========================================================================
     // Lifecycle
     // ==========================================================================
+    /**
+     * Restore sessions from the authored storage sink. Called once at
+     * serve start, before channels accept traffic: any persisted session
+     * missing from the local `--state-root` is materialized there — events
+     * as `events.ndjson`, record as `session.json` — after which every
+     * existing read path (continuation lookup, event replay/streams, A/B
+     * fold hydration) works unchanged. Local state always wins over the
+     * sink, so restarts on the same host are no-ops.
+     *
+     * Failures are logged and skipped; a broken store (including rows that
+     * violate the SessionRecord shape) never blocks serve start.
+     */
+    restoreStoredSessions() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const storage = this.storage;
+            if (storage === undefined || !storage.canBulkRestore) {
+                return;
+            }
+            const policy = storage.policy.restore;
+            if (policy === "off") {
+                return;
+            }
+            try {
+                yield this.runBulkRestore(storage, policy);
+            }
+            catch (error) {
+                this.logger(`[agent-serve] session restore failed: ${describeError(error)}`);
+            }
+        });
+    }
+    runBulkRestore(storage, policy) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const loaded = yield storage.listSessions();
+            // Guardrails on whatever the sink returned: drop invalid rows and
+            // sessions older than the age window, then restore newest-first under
+            // the count cap. Anything filtered out here stays reachable through
+            // the lazy continuation-lookup path.
+            const cutoff = Date.now() - policy.maxAgeMs;
+            const candidates = loaded
+                .map((record) => ({
+                record,
+                // Numeric timestamp for both the age filter and the sort; a
+                // non-string updatedAt (e.g. a raw DB Date from an untyped sink)
+                // parses to NaN and is dropped instead of crashing serve start.
+                updatedAt: typeof (record === null || record === void 0 ? void 0 : record.updatedAt) === "string"
+                    ? Date.parse(record.updatedAt)
+                    : Number.NaN,
+            }))
+                .filter(({ record, updatedAt }) => typeof (record === null || record === void 0 ? void 0 : record.sessionId) === "string" &&
+                record.sessionId !== "" &&
+                updatedAt >= cutoff)
+                .sort((a, b) => b.updatedAt - a.updatedAt)
+                .slice(0, policy.maxSessions)
+                .map(({ record }) => record);
+            let restored = 0;
+            let budget = policy.maxTotalBytes;
+            // Sink round trips dominate restore latency, so event streams are
+            // fetched with bounded parallelism; writes stay sequential, newest
+            // first, so the byte budget is enforced deterministically.
+            outer: for (let i = 0; i < candidates.length; i += RESTORE_FETCH_CONCURRENCY) {
+                const chunk = candidates.slice(i, i + RESTORE_FETCH_CONCURRENCY);
+                const fetched = yield Promise.all(chunk.map((record) => __awaiter(this, void 0, void 0, function* () {
+                    try {
+                        // Local state always wins over the sink.
+                        if ((yield this.sessions.get(record.sessionId)) !== undefined) {
+                            return undefined;
+                        }
+                        const events = yield storage.listSessionEvents(record.sessionId);
+                        return { record, events };
+                    }
+                    catch (error) {
+                        this.logger(`[agent-serve] failed to restore session ${record.sessionId}: ${describeError(error)}`);
+                        return undefined;
+                    }
+                })));
+                for (const item of fetched) {
+                    if (item === undefined) {
+                        continue;
+                    }
+                    const ndjson = eventsNdjson(item.events);
+                    // Budget is checked BEFORE anything is written: one oversized
+                    // session cannot blow past maxTotalBytes on disk. Skipped sessions
+                    // stay reachable through the lazy path.
+                    const bytes = Buffer.byteLength(JSON.stringify(item.record), "utf8") +
+                        (ndjson === undefined ? 0 : Buffer.byteLength(ndjson, "utf8"));
+                    if (bytes > budget) {
+                        this.logger(`[agent-serve] session restore stopped at the ${policy.maxTotalBytes}-byte budget after ${restored} session(s); remaining sessions restore lazily on resume`);
+                        break outer;
+                    }
+                    try {
+                        yield this.materializeSession(item.record, ndjson);
+                        budget -= bytes;
+                        restored += 1;
+                    }
+                    catch (error) {
+                        this.logger(`[agent-serve] failed to restore session ${item.record.sessionId}: ${describeError(error)}`);
+                    }
+                }
+            }
+            if (restored > 0) {
+                this.logger(`[agent-serve] restored ${restored} session(s) from storage`);
+            }
+        });
+    }
+    /**
+     * Lazy restore: a continuation lookup missed locally, so ask the sink
+     * for that one session and materialize it before resuming. Disk grows
+     * with sessions that are actually resumed, not with history.
+     *
+     * Concurrent misses for the same key (webhook redeliveries, retries)
+     * share one in-flight restore — a second materialization racing the
+     * first resumed turn could truncate events the turn already appended.
+     * Sink errors propagate and fail the send (see
+     * {@link StorageCoordinator.getSessionByContinuation}).
+     */
+    restoreSessionByContinuation(channelId, continuationKey) {
+        const storage = this.storage;
+        if (storage === undefined) {
+            return Promise.resolve(undefined);
+        }
+        const key = `${channelId}\u0000${continuationKey}`;
+        let pending = this.restoreInFlight.get(key);
+        if (pending === undefined) {
+            pending = this.loadAndMaterializeByContinuation(storage, channelId, continuationKey).finally(() => this.restoreInFlight.delete(key));
+            this.restoreInFlight.set(key, pending);
+        }
+        return pending;
+    }
+    loadAndMaterializeByContinuation(storage, channelId, continuationKey) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const record = yield storage.getSessionByContinuation(channelId, continuationKey);
+            if (record === undefined) {
+                // Definitive miss: the caller starts a fresh session under this token.
+                return undefined;
+            }
+            const local = yield this.sessions.get(record.sessionId);
+            if (local !== undefined) {
+                return local;
+            }
+            const events = yield storage.listSessionEvents(record.sessionId);
+            yield this.materializeSession(record, eventsNdjson(events));
+            this.logger(`[agent-serve] lazily restored session ${record.sessionId} from storage`);
+            return record;
+        });
+    }
+    /**
+     * Write one restored session to the local state root. Events land on
+     * disk before the record: a session becomes visible (and addressable via
+     * its continuation key) only with its full stream in place, and the
+     * lazily opened event log hydrates from this file.
+     */
+    materializeSession(record, eventsNdjson) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (eventsNdjson !== undefined) {
+                const filePath = this.sessions.eventFilePath(record.sessionId);
+                yield mkdir(dirname(filePath), { recursive: true });
+                yield writeFile(filePath, eventsNdjson, "utf8");
+            }
+            yield this.sessions.save(record);
+        });
+    }
     trackBackground(promise) {
         this.backgroundWork.add(promise);
         void promise
@@ -1300,18 +1534,28 @@ export class SessionEngine {
     /** Drain running turns, dispatches, and pending writes, then dispose. */
     close() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b;
+            var _a, _b, _c;
             this.approvals.cancelAll("deny");
             yield Promise.allSettled([...this.activeTurns.values()]);
             yield Promise.allSettled([...this.backgroundWork]);
             yield Promise.allSettled([...this.dispatchChains.values()]);
             yield Promise.allSettled([...this.updateChains.values()]);
             yield this.logs.flushAll();
+            yield (_a = this.storage) === null || _a === void 0 ? void 0 : _a.close();
             yield this.mcpHost.close();
-            yield (_b = (_a = this.runner).dispose) === null || _b === void 0 ? void 0 : _b.call(_a);
+            yield (_c = (_b = this.runner).dispose) === null || _c === void 0 ? void 0 : _c.call(_b);
         });
     }
 }
+/** Parallel event-stream loads during the startup bulk restore. */
+const RESTORE_FETCH_CONCURRENCY = 8;
+/** NDJSON payload for a restored event stream; undefined when empty. */
+function eventsNdjson(events) {
+    if (events.length === 0) {
+        return undefined;
+    }
+    return `${events.map((event) => JSON.stringify(event)).join("\n")}\n`;
+}
 function subagentPrompt(subagent) {
     var _a;
     if (subagent.instructions !== undefined && subagent.instructions !== "") {

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

@@ -0,0 +1,21 @@
+/**
+ * Session list / event fetch for CLI (`sessions`, `session`, chat reattach).
+ *
+ * Customer-facing errors never include hosting URLs or infra jargon.
+ */
+import type { SessionEvent, SessionSummary } from "../types.js";
+import { type RequestAuth } from "./request-headers.js";
+export declare function listSessions(args: {
+    baseUrl: string;
+    auth?: RequestAuth;
+    fetchImpl?: typeof fetch;
+}): Promise<SessionSummary[]>;
+export declare function fetchSessionEvents(args: {
+    baseUrl: string;
+    sessionId: string;
+    auth?: RequestAuth;
+    fetchImpl?: typeof fetch;
+}): Promise<SessionEvent[]>;
+/** Format a sessions table (id, channel, mode, turns, running, updated). */
+export declare function formatSessionsTable(sessions: SessionSummary[]): string;
+//# sourceMappingURL=sessions-client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessions-client.d.ts","sourceRoot":"","sources":["../../src/internal/sessions-client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAuB,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAE7E,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,CA8B5B;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;AAgCD,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,EAAE,GAAG,MAAM,CActE"}

package/dist/internal/sessions-client.js

@@ -0,0 +1,168 @@
+/**
+ * Session list / event fetch for CLI (`sessions`, `session`, chat reattach).
+ *
+ * Customer-facing errors never include hosting URLs or infra jargon.
+ */
+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 { sanitizeCustomerError } from "./logs-client.js";
+import { mergeRequestHeaders } from "./request-headers.js";
+export function listSessions(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const baseUrl = args.baseUrl.replace(/\/$/, "");
+        const fetchImpl = (_a = args.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+        let resp;
+        try {
+            resp = yield fetchImpl(`${baseUrl}/v1/sessions`, {
+                headers: mergeRequestHeaders(args.auth),
+            });
+        }
+        catch (error) {
+            throw new Error(sanitizeCustomerError(error instanceof Error ? error.message : "Could not list sessions."));
+        }
+        if (!resp.ok) {
+            throw new Error(`Could not list sessions (HTTP ${resp.status}).`);
+        }
+        const body = (yield resp.json());
+        if (!Array.isArray(body.sessions)) {
+            return [];
+        }
+        const out = [];
+        for (const row of body.sessions) {
+            const parsed = parseSessionSummary(row);
+            if (parsed !== undefined) {
+                out.push(parsed);
+            }
+        }
+        return out;
+    });
+}
+export function fetchSessionEvents(args) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const baseUrl = args.baseUrl.replace(/\/$/, "");
+        const fetchImpl = (_a = args.fetchImpl) !== null && _a !== void 0 ? _a : fetch;
+        const path = `/v1/session/${encodeURIComponent(args.sessionId)}/events`;
+        try {
+            const jsonResp = yield fetchImpl(`${baseUrl}${path}?format=json`, {
+                headers: mergeRequestHeaders(args.auth),
+            });
+            if (jsonResp.ok) {
+                const body = (yield jsonResp.json());
+                if (Array.isArray(body.events)) {
+                    return body.events;
+                }
+            }
+            else if (jsonResp.status === 404) {
+                throw new Error(`Session ${args.sessionId} not found.`);
+            }
+            else if (jsonResp.status === 403) {
+                throw new Error(`Session ${args.sessionId} is not readable by this caller.`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith("Session ")) {
+                throw error;
+            }
+            // Fall through to NDJSON.
+        }
+        try {
+            const resp = yield fetchImpl(`${baseUrl}${path}`, {
+                headers: mergeRequestHeaders(args.auth),
+            });
+            if (resp.status === 404) {
+                throw new Error(`Session ${args.sessionId} not found.`);
+            }
+            if (resp.status === 403) {
+                throw new Error(`Session ${args.sessionId} is not readable by this caller.`);
+            }
+            if (!resp.ok) {
+                throw new Error(`Could not fetch session events (HTTP ${resp.status}).`);
+            }
+            const text = yield resp.text();
+            const events = [];
+            for (const line of text.split("\n")) {
+                if (line.trim() === "") {
+                    continue;
+                }
+                try {
+                    events.push(JSON.parse(line));
+                }
+                catch (_b) {
+                    // skip malformed lines
+                }
+            }
+            return events;
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith("Session ")) {
+                throw error;
+            }
+            if (error instanceof Error && error.message.startsWith("Could not fetch")) {
+                throw new Error(sanitizeCustomerError(error.message));
+            }
+            throw new Error(sanitizeCustomerError(error instanceof Error
+                ? error.message
+                : "Could not fetch session events."));
+        }
+    });
+}
+/** Lenient parse so partial stubs / older servers still list by sessionId. */
+function parseSessionSummary(value) {
+    if (typeof value !== "object" || value === null) {
+        return undefined;
+    }
+    const row = value;
+    if (typeof row.sessionId !== "string" || row.sessionId === "") {
+        return undefined;
+    }
+    const continuationToken = typeof row.continuationToken === "string"
+        ? row.continuationToken
+        : row.continuationToken === null
+            ? null
+            : null;
+    return {
+        sessionId: row.sessionId,
+        channelId: typeof row.channelId === "string" ? row.channelId : "",
+        mode: row.mode === "task" ? "task" : "chat",
+        title: typeof row.title === "string" ? row.title : undefined,
+        turnCount: typeof row.turnCount === "number" ? row.turnCount : 0,
+        running: row.running === true,
+        createdAt: typeof row.createdAt === "string" ? row.createdAt : "",
+        updatedAt: typeof row.updatedAt === "string" ? row.updatedAt : "",
+        continuationToken,
+        externalUrl: typeof row.externalUrl === "string" ? row.externalUrl : undefined,
+    };
+}
+/** Format a sessions table (id, channel, mode, turns, running, updated). */
+export function formatSessionsTable(sessions) {
+    if (sessions.length === 0) {
+        return "No sessions.\n";
+    }
+    const header = ["SESSION", "CHANNEL", "MODE", "TURNS", "RUNNING", "UPDATED"];
+    const rows = sessions.map((s) => [
+        s.sessionId,
+        s.channelId,
+        s.mode,
+        String(s.turnCount),
+        s.running ? "yes" : "no",
+        s.updatedAt,
+    ]);
+    return `${renderTable(header, rows)}\n`;
+}
+function renderTable(header, rows) {
+    const widths = header.map((h, i) => Math.max(h.length, ...rows.map((row) => { var _a; return ((_a = row[i]) !== null && _a !== void 0 ? _a : "").length; })));
+    const renderRow = (row) => row
+        .map((cell, i) => { var _a; return cell.padEnd((_a = widths[i]) !== null && _a !== void 0 ? _a : 0); })
+        .join("  ")
+        .trimEnd();
+    return [renderRow(header), ...rows.map(renderRow)].join("\n");
+}