@vybestack/llxprt-code 0.10.0 → 0.11.0-nightly.260728.ffaa8d5d7

package/src/zed-integration/zed-session-loader.ts

@@ -0,0 +1,193 @@
+/**
+ * @license
+ * Copyright 2025 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Resume + error-classification helpers for ACP session/load (loadSession)
+ * (issue #1604). These own the I/O-touching parts of a load (the recorded-history
+ * resume, the corrupt-vs-missing session-file probe, the live-session re-attach
+ * probe, and the in-memory history bridge) plus the final RequestError
+ * normalization, kept OUT of zedIntegration.ts so that near-cap file stays within
+ * its max-lines budget and the load orchestration is individually testable.
+ */
+
+import { readdir } from 'node:fs/promises';
+import * as acp from '@agentclientprotocol/sdk';
+import type { Config, IContent } from '@vybestack/llxprt-code-core';
+import { DebugLogger } from '@vybestack/llxprt-code-core';
+import type { Agent } from '@vybestack/llxprt-code-agents';
+import {
+  classifyResumeFailure,
+  findMatchingSessionFile,
+  isEnoent,
+  wrapReplayFailure,
+} from './zed-session-errors.js';
+
+/**
+ * A readdir-like directory lister injected for testability (FINDING B / #1604
+ * re-attach). Production passes {@link nodeChatSessionFileLister} (a thin wrapper
+ * over `node:fs/promises` readdir); tests pass an honest fake that returns the
+ * directory entry names, NOT a result-shaped mock of our matching logic, so the
+ * real chats-dir derivation + filename matching are exercised.
+ */
+export type ChatSessionFileLister = (
+  chatsDir: string,
+) => Promise<readonly string[]>;
+
+/**
+ * Default {@link ChatSessionFileLister}: the real `node:fs/promises` readdir,
+ * wrapped so it satisfies the lister signature regardless of readdir's overloads.
+ */
+export const nodeChatSessionFileLister: ChatSessionFileLister = (chatsDir) =>
+  readdir(chatsDir);
+
+const logger = new DebugLogger('llxprt:zed-integration:session-loader');
+
+/**
+ * Resumes the agent's recorded history, mapping a resume rejection to a precise
+ * ACP RequestError via {@link classifyResumeFailure}. When the plain
+ * classification would be "not found", the on-disk session-file namespace (the
+ * same chats dir the recording writes to) is probed so a corrupt-but-present
+ * session is reported as internalError ("file exists but could not be
+ * read/replayed") rather than being misreported as resourceNotFound (FINDING B).
+ */
+export async function resumeAgentHistory(
+  agent: Agent,
+  sessionId: string,
+  sessionConfig: Config,
+  listFiles: ChatSessionFileLister = nodeChatSessionFileLister,
+): Promise<readonly IContent[]> {
+  try {
+    return await agent.session.resume(sessionId);
+  } catch (error) {
+    throw await classifyResumeFailure(sessionId, error, () =>
+      listSessionFileNames(sessionConfig, listFiles),
+    );
+  }
+}
+
+/**
+ * Lists the chats-dir entry names for the corrupt-vs-missing probe (FINDING B),
+ * deriving the directory the SAME way the recording layer does
+ * (via Storage.getProjectChatsDir()) and delegating the actual read
+ * to the injected {@link ChatSessionFileLister} (FINDING C1) so the resume probe
+ * and the re-attach probe ({@link hasRecordedSessionFile}) share ONE injected
+ * lister rather than one hardcoding readdir. A read failure propagates to
+ * {@link classifyResumeFailure}, which classifies it (ENOENT → genuinely
+ * missing; other → indeterminate/internalError) so the original resume failure
+ * is never silently masked.
+ */
+async function listSessionFileNames(
+  sessionConfig: Config,
+  listFiles: ChatSessionFileLister,
+): Promise<readonly string[]> {
+  const chatsDir = chatsDirFor(sessionConfig);
+  return listFiles(chatsDir);
+}
+
+/**
+ * Re-attach decision probe (#1604): true when a recorded session file for
+ * `sessionId` already exists on disk under the ZedAgent config's chats dir.
+ *
+ * A freshly created but UNPROMPTED session has no recording — SessionRecordingService
+ * only materializes the JSONL file on the FIRST content event — so this returns
+ * false for it, signalling loadSession to RE-ATTACH the live in-memory session
+ * (replaying its in-memory history) instead of destroying it and failing a disk
+ * resume that would find no file. Once the session has been prompted (a file
+ * exists), this returns true and loadSession takes the destroy-prior + disk-resume
+ * path. An ENOENT probe failure is treated as "no recording present" (returns
+ * false, logged at debug) so a missing directory safely routes to re-attach;
+ * other probe failures propagate so permission and I/O errors remain visible.
+ *
+ * The directory is derived the SAME way the recording layer does
+ * (via Storage.getProjectChatsDir()) and matched with the SAME
+ * filename rule the corrupt-vs-missing resume probe uses
+ * ({@link findMatchingSessionFile}), keeping the two in lockstep.
+ */
+export async function hasRecordedSessionFile(
+  config: Config,
+  sessionId: string,
+  listFiles: ChatSessionFileLister = nodeChatSessionFileLister,
+): Promise<boolean> {
+  try {
+    const chatsDir = chatsDirFor(config);
+    const entries = await listFiles(chatsDir);
+    return findMatchingSessionFile(sessionId, entries) !== null;
+  } catch (error) {
+    if (isEnoent(error)) {
+      logger.debug(
+        () =>
+          `hasRecordedSessionFile: chats dir absent (ENOENT) for ${sessionId}; ` +
+          `treating as no on-disk recording (re-attach): ${String(error)}`,
+      );
+      return false;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Reads a live agent's in-memory conversation as neutral IContent[] for the
+ * re-attach replay (#1604). `agent.getHistory()` already returns neutral
+ * AgentMessage/IContent values, so preserving them directly keeps every block
+ * intact and maps identically to a disk resume. A fresh unprompted session has
+ * empty history, yielding an empty array (zero replay updates).
+ */
+export async function readAgentHistoryAsIContent(
+  agent: Agent,
+): Promise<readonly IContent[]> {
+  return [...(await agent.getHistory())];
+}
+
+/**
+ * {@link readAgentHistoryAsIContent} with replay-failure normalization: a
+ * getHistory()/conversion rejection is wrapped exactly like a delivery failure
+ * ({@link wrapReplayFailure} -> internalError, phase:'replay') so a re-attach
+ * load always rejects with a well-formed RequestError — consistent with the
+ * disk-resume path's error semantics.
+ */
+export async function readAgentHistoryForReplay(
+  agent: Agent,
+  sessionId: string,
+): Promise<readonly IContent[]> {
+  try {
+    return await readAgentHistoryAsIContent(agent);
+  } catch (error) {
+    throw wrapReplayFailure(sessionId, error);
+  }
+}
+
+/**
+ * The chats directory (where session recordings live), delegated to
+ * Storage.getProjectChatsDir() — the single source of truth shared with
+ * SessionControl.chatsDir() (the recording/resume path that WRITES the files),
+ * so the probe↔recording filename match can never drift on the location
+ * (FINDING C3).
+ */
+function chatsDirFor(config: Config): string {
+  return config.storage.getProjectChatsDir();
+}
+
+/**
+ * Normalizes a post-fromConfig load failure into an ACP RequestError (FINDING E).
+ * An error that is ALREADY a RequestError (e.g. the precise error returned by
+ * {@link resumeAgentHistory}) passes through unchanged; any other throw (such as
+ * one while constructing the Session AFTER resume already adopted the recording +
+ * lock) is wrapped as internalError carrying the detail, so the caller can always
+ * dispose the fresh agent and rethrow a single, well-formed RequestError.
+ */
+export function toLoadRequestError(
+  sessionId: string,
+  error: unknown,
+): acp.RequestError {
+  if (error instanceof acp.RequestError) {
+    return error;
+  }
+  const rawDetail = error instanceof Error ? error.message : String(error);
+  const detail =
+    rawDetail ||
+    (error instanceof Error ? error.constructor.name : 'unknown error');
+  return acp.RequestError.internalError({ sessionId, reason: detail }, detail);
+}

package/src/zed-integration/zed-session-pagination.ts

@@ -0,0 +1,240 @@
+/**
+ * @license
+ * Copyright 2026 Vybestack LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as acp from '@agentclientprotocol/sdk';
+
+export interface LifecycleSession {
+  readonly sessionId: string;
+  readonly cwd: string;
+  readonly updatedAt: string;
+  readonly title?: string;
+  /**
+   * Immutable creation timestamp used for stable ordering (issue #1611).
+   * Falls back to updatedAt for legacy sessions without a persisted createdAt.
+   */
+  readonly createdAt?: string;
+}
+
+/**
+ * Self-contained, process-independent snapshot cursor (issue #1611).
+ *
+ * The cursor encodes the full (createdAt, sessionId) tuple of the last item on
+ * the previous page so the next page can be computed from the cursor alone,
+ * without any shared in-process state. The `v` field distinguishes v1 (legacy
+ * updatedAt-based, unstable) from v2 (createdAt-based, immutable).
+ */
+interface CursorPayload {
+  readonly v: 2;
+  readonly cwd: string | null;
+  readonly createdAt: string;
+  readonly sessionId: string;
+}
+
+interface LegacyCursorPayload {
+  readonly version: 1;
+  readonly cwd: string | null;
+  readonly updatedAt: string;
+  readonly sessionId: string;
+}
+
+interface PaginationRequest {
+  readonly cwd: string | null;
+  readonly cursor: string | null;
+}
+
+interface PaginationResult {
+  readonly sessions: readonly LifecycleSession[];
+  readonly nextCursor?: string;
+}
+
+export function paginateSessions(
+  sessions: readonly LifecycleSession[],
+  request: PaginationRequest,
+  pageSize: number,
+): PaginationResult {
+  if (!Number.isInteger(pageSize) || pageSize <= 0) {
+    throw acp.RequestError.invalidParams(
+      { pageSize },
+      'pageSize must be a positive integer',
+    );
+  }
+  const cursor = decodeCursor(request.cursor, request.cwd);
+  const ordered = [...sessions]
+    .filter((session) => request.cwd === null || session.cwd === request.cwd)
+    .sort(compareSessions);
+  const remaining =
+    cursor === null
+      ? ordered
+      : ordered.filter((session) => compareWithCursor(session, cursor) > 0);
+  const page = remaining.slice(0, pageSize);
+  if (remaining.length <= pageSize) {
+    return { sessions: page };
+  }
+  const last = page[page.length - 1];
+  return { sessions: page, nextCursor: encodeCursor(last, request.cwd) };
+}
+
+/**
+ * Orders sessions by createdAt DESC then sessionId DESC.
+ *
+ * createdAt is the immutable session_start timestamp — it never changes when
+ * a session is updated (issue #1611). Falls back to updatedAt when createdAt
+ * is absent (legacy sessions recorded before this change) so they still sort
+ * deterministically. Using updatedAt as a fallback is acceptable because legacy
+ * sessions are static (no new writes), so their updatedAt is effectively
+ * immutable too.
+ */
+function compareSessions(a: LifecycleSession, b: LifecycleSession): number {
+  return compareByCreatedAtAndId(
+    getCreatedAt(a),
+    a.sessionId,
+    getCreatedAt(b),
+    b.sessionId,
+  );
+}
+
+function compareWithCursor(
+  session: LifecycleSession,
+  cursor: CursorPayload,
+): number {
+  return compareByCreatedAtAndId(
+    getCreatedAt(session),
+    session.sessionId,
+    cursor.createdAt,
+    cursor.sessionId,
+  );
+}
+
+function compareByCreatedAtAndId(
+  aCreatedAt: string,
+  aId: string,
+  bCreatedAt: string,
+  bId: string,
+): number {
+  const timestamp = compareDescending(aCreatedAt, bCreatedAt);
+  return timestamp === 0 ? compareDescending(aId, bId) : timestamp;
+}
+
+function compareDescending(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+  return a > b ? -1 : 1;
+}
+
+function getCreatedAt(session: LifecycleSession): string {
+  const createdAt =
+    session.createdAt === undefined
+      ? Number.NaN
+      : Date.parse(session.createdAt);
+  if (Number.isFinite(createdAt)) {
+    return new Date(createdAt).toISOString();
+  }
+  const updatedAt = Date.parse(session.updatedAt);
+  if (Number.isFinite(updatedAt)) {
+    return new Date(updatedAt).toISOString();
+  }
+  // Invalid or non-standard timestamps (corrupted/legacy data). Fall back to
+  // the epoch sentinel so sort order is deterministic and cursor encoding
+  // never embeds an invalid value that would break decode (issue #1611).
+  return new Date(0).toISOString();
+}
+
+function encodeCursor(session: LifecycleSession, cwd: string | null): string {
+  const payload: CursorPayload = {
+    v: 2,
+    cwd,
+    createdAt: getCreatedAt(session),
+    sessionId: session.sessionId,
+  };
+  return Buffer.from(JSON.stringify(payload)).toString('base64url');
+}
+
+function decodeCursor(
+  cursor: string | null,
+  cwd: string | null,
+): CursorPayload | null {
+  if (cursor === null) {
+    return null;
+  }
+  let detail: string;
+  try {
+    const value: unknown = JSON.parse(
+      Buffer.from(cursor, 'base64url').toString('utf8'),
+    );
+    const decoded = normalizeCursorPayload(value);
+    if (decoded === null) {
+      throw new Error('malformed cursor payload');
+    }
+    if (decoded.cwd !== cwd) {
+      throw new Error('cursor cwd does not match request cwd');
+    }
+    return decoded;
+  } catch (error) {
+    detail = error instanceof Error ? error.message : 'invalid encoding';
+  }
+  throw acp.RequestError.invalidParams(
+    { cursor },
+    `Invalid session cursor: ${detail}`,
+  );
+}
+
+function normalizeCursorPayload(value: unknown): CursorPayload | null {
+  if (isCursorPayload(value)) {
+    return value;
+  }
+  if (!isLegacyCursorPayload(value)) {
+    return null;
+  }
+  return {
+    v: 2,
+    cwd: value.cwd,
+    createdAt: new Date(Date.parse(value.updatedAt)).toISOString(),
+    sessionId: value.sessionId,
+  };
+}
+
+function isCursorPayload(value: unknown): value is CursorPayload {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    record.v === 2 &&
+    hasValidCursorIdentity(record) &&
+    isCanonicalTimestamp(record.createdAt)
+  );
+}
+
+function isLegacyCursorPayload(value: unknown): value is LegacyCursorPayload {
+  if (value === null || typeof value !== 'object') {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    record.version === 1 &&
+    hasValidCursorIdentity(record) &&
+    typeof record.updatedAt === 'string' &&
+    Number.isFinite(Date.parse(record.updatedAt))
+  );
+}
+
+function hasValidCursorIdentity(record: Record<string, unknown>): boolean {
+  const hasValidCwd = record.cwd === null || typeof record.cwd === 'string';
+  const hasValidSessionId =
+    typeof record.sessionId === 'string' && record.sessionId.length > 0;
+  return hasValidCwd && hasValidSessionId;
+}
+
+function isCanonicalTimestamp(value: unknown): value is string {
+  if (typeof value !== 'string' || value.length === 0) {
+    return false;
+  }
+  const timestamp = Date.parse(value);
+  return (
+    Number.isFinite(timestamp) && new Date(timestamp).toISOString() === value
+  );
+}