tinker-agent 2.4.0 → 2.6.0

package/src/session/session-store-contracts.ts

@@ -0,0 +1,304 @@
+import type {
+  ContextRevisionId,
+  IterationId,
+  MessageId,
+  ProtocolFrameId,
+  RuntimeIdFactory,
+  SessionId,
+  ToolCallId,
+  TurnId,
+} from "../ids/runtime-id";
+import type { MeasuredContextAnchor } from "../agent/context-meter";
+import type { ModelContextProfile } from "../model/model-context-profile";
+import type { ModelMessageProtocol } from "../model/model-client";
+import { sha256, stableJsonStringify } from "../model/model-request-preflight";
+import type { ProjectInstructionManifest } from "../instructions/project-instructions";
+import type { SkillScope } from "../skills/skill-loader";
+import type {
+  ContextSurfaceChanges,
+  StoredContextSurfaceV8,
+} from "../context/context-surface";
+import type { SwapOverride } from "../context/context-revision";
+import { SWAP_OBSERVATION_FORMAT } from "../context/context-swap-renderer";
+
+export type SessionMediaCompatibility = {
+  readonly policyVersion: string;
+  readonly policySha256: string;
+  readonly inputModalities: readonly ("text" | "image")[];
+  readonly toolResultModalities: readonly ("text" | "image")[];
+};
+
+export type CompletedTurnMessageSnapshot =
+  | {
+      readonly ordinal: number;
+      readonly role: "user";
+      readonly content: string;
+    }
+  | {
+      readonly ordinal: number;
+      readonly role: "assistant";
+      readonly content: string | null;
+      readonly reasoningContent?: string | null;
+    }
+  | {
+      readonly ordinal: number;
+      readonly role: "tool";
+      readonly name: string;
+      readonly content: string;
+    };
+
+export type CompletedTurnSnapshot = {
+  readonly messages: readonly CompletedTurnMessageSnapshot[];
+};
+
+export type SessionCompatibilityContract = {
+  modelName: string;
+  profileName?: string;
+  includeReasoningContent: boolean;
+  contextProfile: ModelContextProfile;
+  messageProtocol: ModelMessageProtocol;
+  media: SessionMediaCompatibility;
+};
+
+export type StoredSessionMetaV10 = {
+  schemaVersion: 10;
+  schemaFingerprint: string;
+  initializationState: "creating" | "ready";
+  sessionId: SessionId;
+  workspaceRoot: string;
+  modelName: string;
+  systemPromptSha256: string;
+  projectInstruction?: ProjectInstructionManifest;
+  sessionCompatibilityJson: string | null;
+  sessionCompatibilitySha256: string | null;
+  activeRevisionId: ContextRevisionId | null;
+  nextTurnNumber: number;
+  nextEventSequence: number;
+  openCount: number;
+  createdAt: string;
+  updatedAt: string;
+  lastOpenedAt: string;
+  lastClosedAt: string | null;
+  lastCloseReason:
+    | "oneshot_complete"
+    | "tui_exit"
+    | "session_switch"
+    | "runner_failed"
+    | "initialization_failed"
+    | null;
+};
+
+export type SessionCloseReason = NonNullable<StoredSessionMetaV10["lastCloseReason"]>;
+
+export type SessionRecoveryResult = {
+  recoveredTurnId?: TurnId;
+  recoveredFrameId?: ProtocolFrameId;
+  syntheticCompletionCount: number;
+  recallIndexRebuilt: boolean;
+};
+
+export type StoredMeasuredContextState = {
+  revisionId: ContextRevisionId;
+  anchor: MeasuredContextAnchor;
+};
+
+export type CommitSwapRevisionInput = {
+  revisionId: ContextRevisionId;
+  expectedBaseRevisionId: ContextRevisionId;
+  expectedBaseRevisionNumber: number;
+  expectedCanonicalThroughOrdinal: number;
+  expectedBaseActiveOverrideManifestSha256: string;
+  policyVersion: "swap-only-v1";
+  rendererFormat: typeof SWAP_OBSERVATION_FORMAT;
+  planHash: string;
+  addedOverrides: readonly SwapOverride[];
+  nextActiveOverrideManifestSha256: string;
+  canonicalSequenceSha256: string;
+  renderedMessageSha256: string;
+  activeTurnId?: TurnId;
+};
+
+export type CommitSwapRevisionFaultStage =
+  | "before_revision_insert"
+  | "after_revision_insert"
+  | "after_first_override_insert"
+  | "after_overrides_insert"
+  | "after_measurement_delete"
+  | "after_active_update";
+
+export type CommitSwapRevisionOptions = {
+  faultInjector?: (stage: CommitSwapRevisionFaultStage) => void;
+};
+
+export type CommitSurfaceRefreshInput = {
+  revisionId: ContextRevisionId;
+  expectedBaseRevisionId: ContextRevisionId;
+  expectedBaseRevisionNumber: number;
+  expectedCanonicalThroughOrdinal: number;
+  expectedBaseActiveOverrideManifestSha256: string;
+  surface: StoredContextSurfaceV8;
+  changes: ContextSurfaceChanges;
+  changeManifestSha256: string;
+  canonicalSequenceSha256: string;
+  renderedMessageSha256: string;
+};
+
+export type CommitSurfaceRefreshFaultStage =
+  | "before_surface_insert"
+  | "after_surface_insert"
+  | "after_revision_insert"
+  | "after_measurement_delete"
+  | "after_active_update";
+
+export type CommitSurfaceRefreshOptions = {
+  faultInjector?: (stage: CommitSurfaceRefreshFaultStage) => void;
+};
+
+export type CommitPrefixRetirementRevisionInput = {
+  revisionId: ContextRevisionId;
+  expectedBaseRevisionId: ContextRevisionId;
+  expectedBaseRevisionNumber: number;
+  expectedBaseKeepFromOrdinal: number;
+  expectedCanonicalThroughOrdinal: number;
+  expectedSurfaceSha256: string;
+  expectedBaseActiveOverrideManifestSha256: string;
+  policyVersion: "recall-first-retirement-v1";
+  planHash: string;
+  nextKeepFromOrdinal: number;
+  retiredThroughOrdinal: number;
+  retiredTurnCount: number;
+  retiredFrameCount: number;
+  retiredMessageCount: number;
+  nextActiveOverrideCount: number;
+  nextActiveOverrideManifestSha256: string;
+  canonicalSequenceSha256: string;
+  renderedMessageSha256: string;
+  activeTurnId?: TurnId;
+};
+
+export type CommitPrefixRetirementRevisionFaultStage =
+  | "before_revision_insert"
+  | "after_revision_insert"
+  | "after_override_readback"
+  | "after_measurement_delete"
+  | "after_active_update"
+  | "after_snapshot_readback";
+
+export type CommitPrefixRetirementRevisionOptions = {
+  faultInjector?: (stage: CommitPrefixRetirementRevisionFaultStage) => void;
+};
+
+export type StoredSkillActivation = {
+  readonly activationMessageId: MessageId;
+  readonly toolCallId: ToolCallId;
+  readonly sessionId: SessionId;
+  readonly name: string;
+  readonly scope: SkillScope;
+  readonly skillFileSha256: string;
+  readonly state: "pending" | "dispatched" | "promoted" | "rejected";
+  readonly dispatchedIterationId?: IterationId;
+  readonly settledRevisionId?: ContextRevisionId;
+  readonly rejectionReason?: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+};
+
+export type CommitSkillsUpdateInput = {
+  revisionId: ContextRevisionId;
+  expectedBaseRevisionId: ContextRevisionId;
+  expectedBaseRevisionNumber: number;
+  expectedCanonicalThroughOrdinal: number;
+  expectedBaseActiveOverrideManifestSha256: string;
+  surface: StoredContextSurfaceV8;
+  changes: ContextSurfaceChanges;
+  changeManifestSha256: string;
+  activationManifestSha256: string;
+  addedOverrides: readonly SwapOverride[];
+  nextActiveOverrideManifestSha256: string;
+  settlements: readonly {
+    activationMessageId: MessageId;
+    name: string;
+    state: "promoted" | "rejected";
+    rejectionReason?: string;
+  }[];
+  canonicalSequenceSha256: string;
+  renderedMessageSha256: string;
+};
+
+export type CommitSkillsUpdateFaultStage =
+  | "before_surface_insert"
+  | "after_surface_insert"
+  | "after_revision_insert"
+  | "after_first_override_insert"
+  | "after_overrides_insert"
+  | "after_activations_update"
+  | "after_measurement_delete"
+  | "after_active_update";
+
+export type CommitSkillsUpdateOptions = {
+  faultInjector?: (stage: CommitSkillsUpdateFaultStage) => void;
+};
+
+export type CloneSessionFaultStage =
+  | "after_staging_mkdir"
+  | "after_snapshot"
+  | "after_trigger_drop"
+  | "after_identity_update"
+  | "after_revision_hash_rewrite"
+  | "after_trigger_reinstall"
+  | "after_recall_validation"
+  | "after_event_rewrite"
+  | "after_observation_render"
+  | "after_artifact_validation"
+  | "before_publish_rename";
+
+export type CloneSessionStoreInput = {
+  targetSessionId: SessionId;
+  faultInjector?: (stage: CloneSessionFaultStage) => void;
+};
+
+export function skillActivationManifestSha256(
+  settlements: CommitSkillsUpdateInput["settlements"],
+): string {
+  return sha256(
+    stableJsonStringify(
+      [...settlements]
+        .sort(
+          (left, right) =>
+            compareCanonicalText(left.name, right.name) ||
+            compareCanonicalText(left.activationMessageId, right.activationMessageId),
+        )
+        .map((settlement) => ({
+          activationMessageId: settlement.activationMessageId,
+          name: settlement.name,
+          state: settlement.state,
+          ...(settlement.rejectionReason === undefined
+            ? {}
+            : { rejectionReason: settlement.rejectionReason }),
+        })),
+    ),
+  );
+}
+
+export type CreateNewSessionStoreInput = {
+  workspaceRoot: string;
+  sessionId: SessionId;
+  modelName: string;
+  systemPrompt: string;
+  projectInstruction?: ProjectInstructionManifest;
+  idFactory: RuntimeIdFactory;
+  clock?: () => string;
+  homeRoot?: string;
+};
+
+export type OpenSessionStoreInput = {
+  workspaceRoot: string;
+  sessionId: SessionId;
+  clock?: () => string;
+  allowIncomplete?: boolean;
+  homeRoot?: string;
+};
+
+function compareCanonicalText(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

package/src/session/session-store-filesystem.ts

@@ -0,0 +1,245 @@
+import path from "node:path";
+import { chmod, lstat, mkdir, realpath, rmdir, unlink } from "node:fs/promises";
+import type { SessionId } from "../ids/runtime-id";
+import { canonicalHomeRoot, workspaceStorageRoot } from "./workspace-storage";
+import { SessionError } from "./session-errors";
+
+export async function assertPathMissing(
+  filePath: string,
+  sessionId: SessionId,
+): Promise<void> {
+  try {
+    await lstat(filePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  throw new SessionError(
+    "SESSION_ALREADY_EXISTS",
+    "clone_session",
+    `Session directory already exists: ${filePath}.`,
+    { sessionId },
+  );
+}
+
+export async function canonicalWorkspaceRoot(workspaceRoot: string): Promise<string> {
+  if (!path.isAbsolute(workspaceRoot)) {
+    throw new Error("Session workspace root must be absolute.");
+  }
+  return realpath(workspaceRoot);
+}
+
+export async function ensureSessionsRoot(
+  workspaceRoot: string,
+  homeRoot?: string,
+): Promise<string> {
+  const tinkerRoot = workspaceStorageRoot(
+    workspaceRoot,
+    await canonicalHomeRoot(homeRoot),
+  );
+  const sessionsRoot = path.join(tinkerRoot, "sessions");
+  await mkdir(sessionsRoot, { recursive: true, mode: 0o700 });
+  await validateSessionsRoot(sessionsRoot);
+  await chmod(tinkerRoot, 0o700);
+  await chmod(sessionsRoot, 0o700);
+  return sessionsRoot;
+}
+
+export async function validateSessionsRoot(
+  sessionsRoot: string,
+  sessionId?: SessionId,
+): Promise<void> {
+  const tinkerRoot = path.dirname(sessionsRoot);
+  for (const directory of [tinkerRoot, sessionsRoot]) {
+    let stats;
+    try {
+      stats = await lstat(directory);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        throw new SessionError(
+          "SESSION_STORE_NOT_FOUND",
+          "validate_session_root",
+          `Session root does not exist: ${directory}.`,
+          { sessionId, cause: error },
+        );
+      }
+      throw error;
+    }
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+      throw new SessionError(
+        "SESSION_PERMISSION_INVALID",
+        "validate_session_root",
+        `Session root must not be a symlink: ${directory}.`,
+        { sessionId },
+      );
+    }
+  }
+  if ((await realpath(sessionsRoot)) !== sessionsRoot) {
+    throw new SessionError(
+      "SESSION_PERMISSION_INVALID",
+      "validate_session_root",
+      `Session root resolves outside its canonical path: ${sessionsRoot}.`,
+      { sessionId },
+    );
+  }
+}
+
+export function safeSessionDirectory(
+  sessionsRoot: string,
+  sessionId: SessionId,
+): string {
+  const value = String(sessionId);
+  if (
+    value.trim() === "" ||
+    value !== value.trim() ||
+    value.includes("/") ||
+    value.includes("\\") ||
+    value === "." ||
+    value === ".."
+  ) {
+    throw new SessionError(
+      "SESSION_ID_INVALID",
+      "resolve_session_path",
+      `Unsafe session ID: ${JSON.stringify(value)}.`,
+      { sessionId },
+    );
+  }
+  const directory = path.join(sessionsRoot, value);
+  if (path.dirname(directory) !== sessionsRoot) {
+    throw new SessionError(
+      "SESSION_ID_INVALID",
+      "resolve_session_path",
+      `Session ID escapes the sessions directory: ${JSON.stringify(value)}.`,
+      { sessionId },
+    );
+  }
+  return directory;
+}
+
+export async function validateSecureDirectory(
+  directory: string,
+  sessionId: SessionId,
+): Promise<void> {
+  let stats;
+  try {
+    stats = await lstat(directory);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new SessionError(
+        "SESSION_STORE_NOT_FOUND",
+        "open_session",
+        `Session directory does not exist: ${directory}.`,
+        { sessionId, cause: error },
+      );
+    }
+    throw error;
+  }
+  if (
+    !stats.isDirectory() ||
+    stats.isSymbolicLink() ||
+    (stats.mode & 0o077) !== 0 ||
+    (typeof process.getuid === "function" && stats.uid !== process.getuid())
+  ) {
+    throw new SessionError(
+      "SESSION_PERMISSION_INVALID",
+      "open_session",
+      `Session directory must be an owner-only real directory: ${directory}.`,
+      { sessionId },
+    );
+  }
+}
+
+export async function validateSecureFile(
+  filePath: string,
+  sessionId: SessionId,
+): Promise<void> {
+  let stats;
+  try {
+    stats = await lstat(filePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new SessionError(
+        "SESSION_STORE_NOT_FOUND",
+        "open_session",
+        `Session database does not exist: ${filePath}.`,
+        { sessionId, cause: error },
+      );
+    }
+    throw error;
+  }
+  if (
+    !stats.isFile() ||
+    stats.isSymbolicLink() ||
+    (stats.mode & 0o077) !== 0 ||
+    (typeof process.getuid === "function" && stats.uid !== process.getuid())
+  ) {
+    throw new SessionError(
+      "SESSION_PERMISSION_INVALID",
+      "open_session",
+      `Session database must be an owner-only regular file: ${filePath}.`,
+      { sessionId },
+    );
+  }
+}
+
+export async function validateSecureOptionalFile(
+  filePath: string,
+  sessionId: SessionId,
+): Promise<void> {
+  try {
+    await lstat(filePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  await validateSecureFile(filePath, sessionId);
+}
+
+export async function removeKnownInitializationFiles(
+  sessionDirectory: string,
+): Promise<void> {
+  for (const name of [
+    "session.sqlite-wal",
+    "session.sqlite-shm",
+    "session.sqlite",
+    "events.jsonl",
+    "observations.md",
+    "active.lock.reclaim",
+    "active.lock",
+  ]) {
+    await unlinkIfExists(path.join(sessionDirectory, name));
+  }
+  try {
+    await rmdir(sessionDirectory);
+  } catch (error) {
+    if (
+      !new Set(["ENOENT", "ENOTEMPTY"]).has((error as NodeJS.ErrnoException).code ?? "")
+    ) {
+      throw error;
+    }
+  }
+}
+
+export async function chmodIfExists(filePath: string, mode: number): Promise<void> {
+  try {
+    await chmod(filePath, mode);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+  }
+}
+
+export async function unlinkIfExists(filePath: string): Promise<void> {
+  try {
+    await unlink(filePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+      throw error;
+    }
+  }
+}