tinker-agent 2.8.0 → 2.10.0

package/src/session/resume-projection.ts

@@ -160,28 +160,25 @@ function projectTurn(
     .query("SELECT * FROM messages WHERE turn_id = ? ORDER BY ordinal")
     .all(turnId) as Array<Record<string, unknown>>;
   const promptRows = messages.filter((message) => message.role === "user");
-  if (promptRows.length !== 1) {
-    throw new Error(
-      `Turn ${turnId} must contain exactly one user message; found ${promptRows.length}.`,
-    );
-  }
   const prompt = promptRows[0];
-  if (prompt === undefined) {
-    throw new Error(`Turn ${turnId} user message disappeared.`);
-  }
-  const userPrompt = truncateUserPromptProjection(
-    readUserPromptProjection(database, prompt),
-    MAX_TIMELINE_PROMPT_CODE_POINTS,
-  );
-  const allItems: TimelineItem[] = [
-    {
-      id: `resume-${requireString(prompt.message_id, "message_id")}`,
-      label: "prompt",
-      text: userPrompt.text,
-      userPrompt,
-      status: "text",
-    },
-  ];
+  if (prompt === undefined || messages[0] !== prompt) {
+    throw new Error(`Turn ${turnId} must start with a user message.`);
+  }
+  const allItems: TimelineItem[] = [projectPrompt(database, prompt, "prompt")];
+  let nextPromptIndex = 1;
+  const appendFollowUpsBefore = (ordinal: number): void => {
+    while (nextPromptIndex < promptRows.length) {
+      const followUp = promptRows[nextPromptIndex];
+      if (
+        followUp === undefined ||
+        safeNumber(followUp.ordinal, "user ordinal") >= ordinal
+      ) {
+        break;
+      }
+      allItems.push(projectPrompt(database, followUp, "follow-up"));
+      nextPromptIndex += 1;
+    }
+  };
   const assistantsByIteration = new Map<string, Record<string, unknown>>();
   for (const message of messages) {
     const role = requireString(message.role, "message role");
@@ -224,6 +221,15 @@ function projectTurn(
     .query("SELECT * FROM iterations WHERE turn_id = ? ORDER BY iteration_number")
     .all(turnId) as Array<Record<string, unknown>>;
   for (const iteration of iterations) {
+    const iterationId = requireString(iteration.iteration_id, "iteration_id");
+    const assistant = assistantsByIteration.get(iterationId);
+    // Steering is committed between complete tool exchanges. An unanswered
+    // terminal iteration has no ordinal, so all remaining follow-ups precede it.
+    appendFollowUpsBefore(
+      assistant === undefined
+        ? Number.POSITIVE_INFINITY
+        : safeNumber(assistant.ordinal, "assistant ordinal"),
+    );
     allItems.push(
       ...projectIteration(
         iteration,
@@ -234,6 +240,8 @@ function projectTurn(
       ),
     );
   }
+  // The iteration limit can end a turn immediately after steering was applied.
+  appendFollowUpsBefore(Number.POSITIVE_INFINITY);
   if (assistantsByIteration.size > 0) {
     throw new Error(
       `Turn ${turnId} has assistant messages without matching iterations.`,
@@ -265,6 +273,24 @@ function projectTurn(
   };
 }
 
+function projectPrompt(
+  database: Database,
+  message: Record<string, unknown>,
+  label: "prompt" | "follow-up",
+): TimelineItem {
+  const userPrompt = truncateUserPromptProjection(
+    readUserPromptProjection(database, message),
+    MAX_TIMELINE_PROMPT_CODE_POINTS,
+  );
+  return {
+    id: `resume-${requireString(message.message_id, "message_id")}`,
+    label,
+    text: userPrompt.text,
+    userPrompt,
+    status: "text",
+  };
+}
+
 function readUserPromptProjection(
   database: Database,
   prompt: Record<string, unknown>,

package/src/session/session-history-access.ts

@@ -0,0 +1,238 @@
+import { Database } from "bun:sqlite";
+import { lstat, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import { throwIfTurnCancelled } from "../agent/turn-cancellation";
+import { parseSessionId, type SessionId } from "../ids/runtime-id";
+import { SessionError } from "./session-errors";
+import {
+  createSessionHistoryReader,
+  RecallHistoryError,
+  type SessionHistoryReader,
+} from "./session-history-reader";
+import { verifyReadableSessionSchema } from "./session-schema";
+import {
+  safeSessionDirectory,
+  validateSecureDirectory,
+  validateSecureFile,
+  validateSecureOptionalFile,
+  validateSessionsRoot,
+} from "./session-store-filesystem";
+import { canonicalHomeRoot, workspaceStorageRoot } from "./workspace-storage";
+
+export type RecallSessionErrorCode =
+  | "RECALL_SESSION_NOT_FOUND"
+  | "RECALL_SESSION_AMBIGUOUS"
+  | "RECALL_SESSION_UNSUPPORTED"
+  | "RECALL_SESSION_UNAVAILABLE";
+
+export class RecallSessionError extends Error {
+  constructor(
+    readonly code: RecallSessionErrorCode,
+    message: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "RecallSessionError";
+  }
+}
+
+export interface SessionHistoryAccess {
+  readonly currentSessionId: SessionId;
+  withHistoryReader<T>(
+    sessionId: SessionId | undefined,
+    signal: AbortSignal,
+    read: (reader: SessionHistoryReader, workspaceRoot: string) => T,
+  ): Promise<T>;
+}
+
+/** External history never goes through execution locks, recovery or migrations. */
+export function createSessionHistoryAccess(input: {
+  historyReader: SessionHistoryReader;
+  workspaceRoot: string;
+  homeRoot?: string;
+}): SessionHistoryAccess {
+  return {
+    currentSessionId: input.historyReader.sessionId,
+    async withHistoryReader(sessionId, signal, read) {
+      throwIfTurnCancelled(signal);
+      if (sessionId === undefined || sessionId === input.historyReader.sessionId) {
+        const result = read(input.historyReader, input.workspaceRoot);
+        throwIfTurnCancelled(signal);
+        return result;
+      }
+      // Defence in depth: this session API also rejects non-canonical IDs.
+      parseSessionId(sessionId);
+      try {
+        const location = await locateHistorySession({ ...input, sessionId, signal });
+        throwIfTurnCancelled(signal);
+        await validateHistoryFiles(location.databasePath, sessionId);
+        throwIfTurnCancelled(signal);
+        const database = new Database(location.databasePath, {
+          readonly: true,
+          strict: true,
+          safeIntegers: true,
+        });
+        try {
+          // Connection-local only. Never change journal mode or ignore a live WAL.
+          database.exec("PRAGMA busy_timeout = 250");
+          const result = database.transaction(() => {
+            throwIfTurnCancelled(signal);
+            if (verifyReadableSessionSchema(database, sessionId) !== "current") {
+              throw new RecallSessionError(
+                "RECALL_SESSION_UNSUPPORTED",
+                "Selected session requires migration; Recall does not upgrade history.",
+              );
+            }
+            const workspaceRoot = validateHistoryIdentity(
+              database,
+              location,
+              sessionId,
+            );
+            const reader = createSessionHistoryReader({
+              database,
+              sessionId,
+              requireOpen: () => throwIfTurnCancelled(signal),
+            });
+            const value = read(reader, workspaceRoot);
+            throwIfTurnCancelled(signal);
+            return value;
+          })();
+          throwIfTurnCancelled(signal);
+          return result;
+        } finally {
+          database.close(true);
+        }
+      } catch (error) {
+        throwIfTurnCancelled(signal);
+        if (
+          error instanceof RecallSessionError ||
+          error instanceof RecallHistoryError
+        ) {
+          throw error;
+        }
+        const code =
+          error instanceof SessionError && error.code === "SESSION_SCHEMA_UNSUPPORTED"
+            ? "RECALL_SESSION_UNSUPPORTED"
+            : "RECALL_SESSION_UNAVAILABLE";
+        const reason = error instanceof Error ? error.message : "Unknown read failure";
+        throw new RecallSessionError(
+          code,
+          `Selected session ${sessionId}: ${reason.slice(0, 400)}`,
+          { cause: error },
+        );
+      }
+    },
+  };
+}
+
+type HistoryLocation = { databasePath: string; homeRoot: string; projectRoot: string };
+
+async function locateHistorySession(input: {
+  workspaceRoot: string;
+  homeRoot?: string;
+  sessionId: SessionId;
+  signal: AbortSignal;
+}): Promise<HistoryLocation> {
+  const homeRoot = await canonicalHomeRoot(input.homeRoot);
+  const currentProject = workspaceStorageRoot(input.workspaceRoot, homeRoot);
+  const projectsRoot = path.dirname(currentProject);
+  // Do not follow aliases in the storage hierarchy or silently skip failed scans.
+  for (const directory of [path.dirname(projectsRoot), projectsRoot]) {
+    if (!(await exists(directory))) {
+      throw new RecallSessionError(
+        "RECALL_SESSION_NOT_FOUND",
+        "Selected session does not exist.",
+      );
+    }
+    const stats = await lstat(directory);
+    if (!stats.isDirectory() || (await realpath(directory)) !== directory) {
+      throw new Error("History storage root must be a canonical real directory.");
+    }
+  }
+  const projects = await readdir(projectsRoot, { withFileTypes: true });
+  const roots = new Set([currentProject]);
+  for (const project of projects) {
+    throwIfTurnCancelled(input.signal);
+    if (project.isSymbolicLink()) {
+      throw new Error(
+        "Cannot complete history lookup through a symlinked project directory.",
+      );
+    }
+    if (project.isDirectory()) roots.add(path.join(projectsRoot, project.name));
+  }
+  const candidates: HistoryLocation[] = [];
+  for (const projectRoot of roots) {
+    throwIfTurnCancelled(input.signal);
+    const sessionsRoot = path.join(projectRoot, "sessions");
+    if (!(await exists(sessionsRoot))) continue;
+    await validateSessionsRoot(sessionsRoot, input.sessionId);
+    const directory = safeSessionDirectory(sessionsRoot, input.sessionId);
+    if (await exists(directory)) {
+      candidates.push({
+        databasePath: path.join(directory, "session.sqlite"),
+        homeRoot,
+        projectRoot,
+      });
+    }
+  }
+  if (candidates.length === 0) {
+    throw new RecallSessionError(
+      "RECALL_SESSION_NOT_FOUND",
+      "Selected session does not exist.",
+    );
+  }
+  if (candidates.length !== 1) {
+    throw new RecallSessionError(
+      "RECALL_SESSION_AMBIGUOUS",
+      "Selected session ID occurs in multiple project directories.",
+    );
+  }
+  return candidates[0];
+}
+
+async function exists(filePath: string): Promise<boolean> {
+  try {
+    await lstat(filePath);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function validateHistoryFiles(databasePath: string, sessionId: SessionId) {
+  const directory = path.dirname(databasePath);
+  await validateSecureDirectory(path.dirname(path.dirname(directory)), sessionId);
+  await validateSecureDirectory(path.dirname(directory), sessionId);
+  await validateSecureDirectory(directory, sessionId);
+  await validateSecureFile(databasePath, sessionId);
+  await validateSecureOptionalFile(`${databasePath}-wal`, sessionId);
+  await validateSecureOptionalFile(`${databasePath}-shm`, sessionId);
+}
+
+function validateHistoryIdentity(
+  database: Database,
+  location: HistoryLocation,
+  sessionId: SessionId,
+): string {
+  const rows = database
+    .query("SELECT session_id, workspace_root, initialization_state FROM session_meta")
+    .all() as Array<Record<string, unknown>>;
+  const meta = rows[0];
+  if (
+    rows.length !== 1 ||
+    meta?.session_id !== sessionId ||
+    meta.initialization_state !== "ready" ||
+    typeof meta.workspace_root !== "string" ||
+    !path.isAbsolute(meta.workspace_root) ||
+    path.normalize(meta.workspace_root) !== meta.workspace_root ||
+    workspaceStorageRoot(meta.workspace_root, location.homeRoot) !==
+      location.projectRoot
+  ) {
+    throw new Error(
+      "Selected session identity, workspace storage path or initialization state is invalid.",
+    );
+  }
+  // The original workspace may no longer exist. Its stored canonical path is enough.
+  return meta.workspace_root;
+}

package/src/session/session-store-context-readers.ts

@@ -0,0 +1,183 @@
+import type { Database } from "bun:sqlite";
+import type { StoredContextRevisionV8 } from "../context/context-revision";
+import type {
+  ActiveTurnBoundary,
+  ClosedTurnBoundary,
+} from "../context/prefix-retirement-planner";
+import { type ProtocolContextView } from "../context/protocol-frame";
+import type { ContextRevisionId, SessionId, TurnId } from "../ids/runtime-id";
+import {
+  type StoredMeasuredContextState,
+  type StoredSessionMetaV10,
+} from "./session-store-contracts";
+import { requireItem } from "./session-store-sql";
+import {
+  enumFromSql,
+  numberFromSql,
+  recordFromSql,
+  sha256FromSql,
+  stringFromSql,
+  timestampFromSql,
+} from "./session-store-value-codecs";
+
+export function requireActiveRevisionId(meta: StoredSessionMetaV10): ContextRevisionId {
+  if (meta.initializationState !== "ready" || meta.activeRevisionId === null) {
+    throw new Error("Session has no active context revision.");
+  }
+  return meta.activeRevisionId;
+}
+
+export function previousRevision(
+  revisions: readonly StoredContextRevisionV8[],
+  revision: StoredContextRevisionV8,
+): StoredContextRevisionV8 | undefined {
+  return revisions[revision.revisionNumber - 2];
+}
+
+function decodeMeasuredContextState(
+  value: unknown,
+  expectedSessionId: SessionId,
+): StoredMeasuredContextState {
+  const row = recordFromSql(value, "context measurement state");
+  const sessionId = stringFromSql(row.session_id, "session_id") as SessionId;
+  if (sessionId !== expectedSessionId) {
+    throw new Error(
+      `Context measurement session ID ${sessionId} does not match store.`,
+    );
+  }
+  const promptTokens = numberFromSql(row.prompt_tokens, "prompt_tokens");
+  const completionTokens = numberFromSql(row.completion_tokens, "completion_tokens");
+  const totalTokens = numberFromSql(row.total_tokens, "total_tokens");
+  if (totalTokens !== promptTokens + completionTokens) {
+    throw new Error(
+      "Context measurement total_tokens must equal prompt_tokens + completion_tokens.",
+    );
+  }
+
+  timestampFromSql(row.updated_at, "updated_at");
+  return Object.freeze({
+    revisionId: stringFromSql(row.revision_id, "revision_id") as ContextRevisionId,
+    anchor: Object.freeze({
+      totalTokens,
+      promptTokens,
+      completionTokens,
+      segmentCount: numberFromSql(row.segment_count, "segment_count"),
+      prefixHash: sha256FromSql(row.prefix_hash, "prefix_hash"),
+      requestConfigHash: sha256FromSql(row.request_config_hash, "request_config_hash"),
+      toolSchemaHash: sha256FromSql(row.tool_schema_hash, "tool_schema_hash"),
+    }),
+  });
+}
+
+export function readRetirementBoundaries(
+  database: Database,
+  canonical: ProtocolContextView,
+  activeTurnId?: TurnId,
+): {
+  readonly closedTurns: readonly ClosedTurnBoundary[];
+  readonly activeTurn?: ActiveTurnBoundary;
+} {
+  const rows = database
+    .query("SELECT * FROM turns ORDER BY turn_number")
+    .all() as Array<Record<string, unknown>>;
+  const boundaries: ClosedTurnBoundary[] = [];
+  let activeTurn: ActiveTurnBoundary | undefined;
+  let expectedOrdinal = 2;
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = requireItem(rows, index, "turn row");
+    const turnId = stringFromSql(row.turn_id, "turn_id") as TurnId;
+    const turnNumber = numberFromSql(row.turn_number, "turn_number");
+    const status = enumFromSql(
+      row.status,
+      ["open", "completed", "failed", "cancelled", "interrupted"] as const,
+      "turn status",
+    );
+    const frames = canonical.frames.filter((frame) => frame.turnId === turnId);
+    const messages = canonical.messages.filter(
+      (message) => message.role !== "system" && message.turnId === turnId,
+    );
+    const firstMessage = messages[0];
+    const lastMessage = messages.at(-1);
+    if (status === "open") {
+      if (
+        activeTurnId === undefined ||
+        turnId !== activeTurnId ||
+        index !== rows.length - 1 ||
+        turnNumber !== index + 1 ||
+        messages.length < 1 ||
+        frames.length < 1 ||
+        firstMessage?.role !== "user" ||
+        firstMessage.ordinal !== expectedOrdinal ||
+        lastMessage?.ordinal !== canonical.messages.length ||
+        frames.some((frame) => frame.state !== "closed")
+      ) {
+        throw new Error(`Turn ${turnId} has an invalid active boundary.`);
+      }
+      activeTurn = Object.freeze({
+        turnId,
+        turnNumber,
+        firstOrdinal: expectedOrdinal,
+      });
+      expectedOrdinal = canonical.messages.length + 1;
+      continue;
+    }
+    let nextFrameOrdinal = expectedOrdinal;
+    for (const frame of frames) {
+      if (
+        frame.state !== "closed" ||
+        frame.firstOrdinal !== nextFrameOrdinal ||
+        frame.lastOrdinal === undefined
+      ) {
+        throw new Error(`Turn ${turnId} has an invalid closed frame boundary.`);
+      }
+      nextFrameOrdinal = frame.lastOrdinal + 1;
+    }
+    if (
+      turnNumber !== index + 1 ||
+      frames.length < 1 ||
+      messages.length < 1 ||
+      firstMessage?.role !== "user" ||
+      firstMessage.ordinal !== expectedOrdinal ||
+      lastMessage === undefined ||
+      nextFrameOrdinal !== lastMessage.ordinal + 1
+    ) {
+      throw new Error(`Turn ${turnId} has an invalid canonical boundary.`);
+    }
+    boundaries.push(
+      Object.freeze({
+        turnId,
+        turnNumber,
+        status,
+        firstOrdinal: expectedOrdinal,
+        lastOrdinal: lastMessage.ordinal,
+        frameCount: frames.length,
+        messageCount: messages.length,
+      }),
+    );
+    expectedOrdinal = lastMessage.ordinal + 1;
+  }
+  if (expectedOrdinal !== canonical.messages.length + 1) {
+    throw new Error("Closed turn boundaries do not cover canonical history.");
+  }
+  if ((activeTurnId === undefined) !== (activeTurn === undefined)) {
+    throw new Error("Active retirement boundary does not match the open turn.");
+  }
+  return Object.freeze({
+    closedTurns: Object.freeze(boundaries),
+    ...(activeTurn === undefined ? {} : { activeTurn }),
+  });
+}
+
+export function loadMeasuredContextState(
+  database: Database,
+  sessionId: SessionId,
+): StoredMeasuredContextState | undefined {
+  const rows = database.query("SELECT * FROM context_measurement_state").all();
+  if (rows.length > 1) {
+    throw new Error(
+      `Expected at most one context measurement row; found ${rows.length}.`,
+    );
+  }
+  const row = rows[0];
+  return row === undefined ? undefined : decodeMeasuredContextState(row, sessionId);
+}