tinker-agent 2.5.0 → 2.7.0

package/src/session/session-clone-helpers.ts

@@ -0,0 +1,249 @@
+import path from "node:path";
+import { chmod, lstat, open, readFile } from "node:fs/promises";
+import { Database } from "bun:sqlite";
+import type { SessionId } from "../ids/runtime-id";
+import { stableJsonStringify } from "../model/model-request-preflight";
+import type { ProtocolContextView } from "../context/protocol-frame";
+import {
+  canonicalSequenceHash,
+  renderedMessageHash,
+} from "../context/compiled-context-hash";
+import { ContextRevisionCompiler } from "../context/context-revision-compiler";
+import type { AgentEvent } from "../events/types";
+import { renderObservationLogEvent } from "../events/observation-text-log";
+import type { CloneSessionFaultStage } from "./session-store-contracts";
+import { validateSecureFile } from "./session-store-filesystem";
+import {
+  decodeContextRevision,
+  decodeContextSurface,
+  decodeStoredSwapOverride,
+  decodeStoredToolCalls,
+  protocolPrefixView,
+} from "./session-store-record-codecs";
+
+export const SESSION_SCOPED_TABLES = [
+  "session_meta",
+  "turns",
+  "iterations",
+  "protocol_frames",
+  "messages",
+  "tool_results",
+  "context_surfaces",
+  "context_revisions",
+  "context_overrides",
+  "skill_activations",
+  "context_measurement_state",
+] as const;
+
+export function rekeyStoredToolCalls(
+  database: Database,
+  targetSessionId: SessionId,
+): void {
+  const rows = database
+    .query(
+      `SELECT message_id, tool_calls_json FROM messages
+       WHERE tool_calls_json IS NOT NULL ORDER BY ordinal`,
+    )
+    .all() as Array<{ message_id: string; tool_calls_json: string }>;
+  for (const row of rows) {
+    const calls = decodeStoredToolCalls(row.tool_calls_json).map((call) => ({
+      ...call,
+      sessionId: targetSessionId,
+    }));
+    database
+      .query("UPDATE messages SET tool_calls_json = ? WHERE message_id = ?")
+      .run(stableJsonStringify(calls), row.message_id);
+  }
+}
+
+export function rekeyProtocolView(
+  source: ProtocolContextView,
+  targetSessionId: SessionId,
+): ProtocolContextView {
+  return {
+    sessionId: targetSessionId,
+    faulted: source.faulted,
+    frames: source.frames.map((frame) => ({
+      ...frame,
+      sessionId: targetSessionId,
+    })),
+    messages: source.messages.map((message) => ({
+      ...message,
+      sessionId: targetSessionId,
+      ...(message.role === "assistant" && message.toolCalls !== undefined
+        ? {
+            toolCalls: message.toolCalls.map((call) => ({
+              ...call,
+              sessionId: targetSessionId,
+            })),
+          }
+        : {}),
+    })),
+    toolResults: source.toolResults.map((result) => ({
+      ...result,
+      sessionId: targetSessionId,
+    })),
+  };
+}
+
+export function rewriteCloneRevisionHashes(
+  database: Database,
+  canonical: ProtocolContextView,
+): void {
+  const surfaces = database
+    .query("SELECT * FROM context_surfaces")
+    .all()
+    .map(decodeContextSurface);
+  const surfacesById = new Map(surfaces.map((surface) => [surface.surfaceId, surface]));
+  const revisions = database
+    .query("SELECT * FROM context_revisions ORDER BY revision_number")
+    .all()
+    .map(decodeContextRevision);
+  const revisionNumberById = new Map(
+    revisions.map((revision) => [revision.revisionId, revision.revisionNumber]),
+  );
+  const overrides = database
+    .query(
+      `SELECT co.* FROM context_overrides co
+       JOIN context_revisions cr ON cr.revision_id = co.introduced_revision_id
+       ORDER BY cr.revision_number, co.ordinal`,
+    )
+    .all()
+    .map(decodeStoredSwapOverride);
+  const compiler = new ContextRevisionCompiler();
+  for (const revision of revisions) {
+    const surface = surfacesById.get(revision.surfaceId);
+    if (surface === undefined) {
+      throw new Error(`Cloned revision ${revision.revisionId} has no surface.`);
+    }
+    const activeOverrides = overrides.filter(
+      (override) =>
+        (revisionNumberById.get(override.introducedRevisionId) ??
+          Number.POSITIVE_INFINITY) <= revision.revisionNumber &&
+        override.ordinal >= revision.keepFromOrdinal,
+    );
+    const prefix = protocolPrefixView(canonical, revision.sourceThroughOrdinal);
+    const compiled = compiler.compileForIdentityRekey({
+      canonical: prefix,
+      revisionId: revision.revisionId,
+      activeOverrides,
+      keepFromOrdinal: revision.keepFromOrdinal,
+      surface,
+    });
+    database
+      .query(
+        `UPDATE context_revisions
+         SET canonical_sequence_sha256 = ?, rendered_message_sha256 = ?
+         WHERE revision_id = ?`,
+      )
+      .run(
+        canonicalSequenceHash(canonical, revision.sourceThroughOrdinal),
+        renderedMessageHash(compiled.entries, revision.sourceThroughOrdinal),
+        revision.revisionId,
+      );
+  }
+}
+
+export async function cloneDiagnosticFiles(input: {
+  sourceDirectory: string;
+  stagingDirectory: string;
+  sourceSessionId: SessionId;
+  targetSessionId: SessionId;
+  nextEventSequence: number;
+  faultInjector?: (stage: CloneSessionFaultStage) => void;
+}): Promise<void> {
+  const sourcePath = path.join(input.sourceDirectory, "events.jsonl");
+  try {
+    await lstat(sourcePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return;
+    }
+    throw error;
+  }
+  await validateSecureFile(sourcePath, input.sourceSessionId);
+
+  const bytes = await readFile(sourcePath);
+  const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  const rawLines = text.split("\n");
+  if (rawLines.at(-1) === "") {
+    rawLines.pop();
+  }
+  const events: AgentEvent[] = [];
+  let previousSequence = 0;
+  for (const [index, line] of rawLines.entries()) {
+    if (line === "") {
+      throw new Error(`Session event log contains an empty line at ${index + 1}.`);
+    }
+    let value: unknown;
+    try {
+      value = JSON.parse(line);
+    } catch (error) {
+      throw new Error(`Session event log has invalid JSON at line ${index + 1}.`, {
+        cause: error,
+      });
+    }
+    if (!isEventEnvelope(value)) {
+      throw new Error(
+        `Session event log has an invalid envelope at line ${index + 1}.`,
+      );
+    }
+    if (value.sessionId !== input.sourceSessionId) {
+      throw new Error(`Session event log identity changed at line ${index + 1}.`);
+    }
+    if (value.eventSequence <= previousSequence) {
+      throw new Error(
+        `Session event sequence is not strictly increasing at line ${index + 1}.`,
+      );
+    }
+    if (value.eventSequence >= input.nextEventSequence) {
+      throw new Error(
+        `Session event sequence exceeds the canonical next counter at line ${index + 1}.`,
+      );
+    }
+    previousSequence = value.eventSequence;
+    events.push({ ...value, sessionId: input.targetSessionId });
+  }
+
+  const eventText = events.map((event) => JSON.stringify(event)).join("\n");
+  await writePrivateNewFile(
+    path.join(input.stagingDirectory, "events.jsonl"),
+    eventText === "" ? "" : `${eventText}\n`,
+  );
+  input.faultInjector?.("after_event_rewrite");
+  const observationText = events
+    .map((event) => renderObservationLogEvent(event))
+    .filter((block): block is string => block !== undefined)
+    .join("");
+  await writePrivateNewFile(
+    path.join(input.stagingDirectory, "observations.md"),
+    observationText,
+  );
+  input.faultInjector?.("after_observation_render");
+}
+
+function isEventEnvelope(value: unknown): value is AgentEvent {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.sessionId === "string" &&
+    Number.isSafeInteger(record.eventSequence) &&
+    Number(record.eventSequence) >= 1 &&
+    typeof record.timestamp === "string" &&
+    typeof record.type === "string" &&
+    record.data !== null &&
+    typeof record.data === "object"
+  );
+}
+
+async function writePrivateNewFile(filePath: string, content: string): Promise<void> {
+  const handle = await open(filePath, "wx", 0o600);
+  try {
+    await handle.writeFile(content, "utf8");
+  } finally {
+    await handle.close();
+  }
+  await chmod(filePath, 0o600);
+}

package/src/session/session-compatibility-codec.ts

@@ -0,0 +1,401 @@
+import type { ContextRevisionId, SessionId } from "../ids/runtime-id";
+import {
+  createModelContextProfile,
+  type ModelContextProfile,
+} from "../model/model-context-profile";
+import {
+  MODEL_MESSAGE_PROTOCOL_ADAPTERS,
+  type ModelMessageProtocol,
+} from "../model/model-client";
+import { sha256, stableJsonStringify } from "../model/model-request-preflight";
+import { immutableCanonicalClone } from "../context/protocol-frame";
+import type { ProjectInstructionManifest } from "../instructions/project-instructions";
+import {
+  IMAGE_INPUT_POLICY,
+  IMAGE_INPUT_POLICY_VERSION,
+} from "../image/image-input-policy";
+import type {
+  SessionCompatibilityContract,
+  StoredSessionMetaV10,
+} from "./session-store-contracts";
+import {
+  assertObjectKeys,
+  enumFromSql,
+  nullableNumberFromSql,
+  nullableStringFromSql,
+  numberFromJson,
+  numberFromSql,
+  parseJson,
+  recordFromSql,
+  sha256FromSql,
+  stringFromSql,
+  timestampFromSql,
+} from "./session-store-value-codecs";
+
+export function createSessionCompatibilityContract(input: {
+  modelName: string;
+  profileName?: string;
+  includeReasoningContent: boolean;
+  contextProfile: ModelContextProfile;
+  messageProtocol: ModelMessageProtocol;
+  inputModalities: readonly ("text" | "image")[];
+  toolResultModalities: readonly ("text" | "image")[];
+}): SessionCompatibilityContract {
+  if (input.modelName.trim() === "") {
+    throw new Error("Session compatibility model name must not be empty.");
+  }
+  if (input.profileName !== undefined && input.profileName.trim() === "") {
+    throw new Error("Session compatibility profile name must not be empty.");
+  }
+  if (typeof input.includeReasoningContent !== "boolean") {
+    throw new Error("Session compatibility reasoning replay flag must be boolean.");
+  }
+  if (
+    !MODEL_MESSAGE_PROTOCOL_ADAPTERS.includes(input.messageProtocol.adapter) ||
+    input.messageProtocol.serializationVersion.trim() === ""
+  ) {
+    throw new Error("Session compatibility message protocol is invalid.");
+  }
+  const inputModalities = normalizeInputModalities(input.inputModalities);
+  const toolResultModalities = normalizeInputModalities(input.toolResultModalities);
+  if (toolResultModalities.includes("image") && !inputModalities.includes("image")) {
+    throw new Error("Session compatibility image tool results require image input.");
+  }
+  return Object.freeze({
+    modelName: input.modelName,
+    ...(input.profileName === undefined ? {} : { profileName: input.profileName }),
+    includeReasoningContent: input.includeReasoningContent,
+    contextProfile: Object.freeze(createModelContextProfile(input.contextProfile)),
+    messageProtocol: immutableCanonicalClone(input.messageProtocol),
+    media: Object.freeze({
+      policyVersion: IMAGE_INPUT_POLICY_VERSION,
+      policySha256: sha256(
+        stableJsonStringify({
+          version: IMAGE_INPUT_POLICY_VERSION,
+          ...IMAGE_INPUT_POLICY,
+        }),
+      ),
+      inputModalities,
+      toolResultModalities,
+    }),
+  });
+}
+
+export function normalizeSessionCompatibilityContract(
+  contract: SessionCompatibilityContract,
+): SessionCompatibilityContract {
+  return createSessionCompatibilityContract({
+    modelName: contract.modelName,
+    ...(contract.profileName === undefined
+      ? {}
+      : { profileName: contract.profileName }),
+    includeReasoningContent: contract.includeReasoningContent,
+    contextProfile: contract.contextProfile,
+    messageProtocol: contract.messageProtocol,
+    inputModalities: contract.media.inputModalities,
+    toolResultModalities: contract.media.toolResultModalities,
+  });
+}
+
+function normalizeInputModalities(
+  modalities: readonly ("text" | "image")[],
+): readonly ("text" | "image")[] {
+  if (
+    modalities.length === 0 ||
+    modalities.some((value) => value !== "text" && value !== "image") ||
+    new Set(modalities).size !== modalities.length ||
+    !modalities.includes("text")
+  ) {
+    throw new Error("Session compatibility input modalities are invalid.");
+  }
+  return Object.freeze(
+    modalities.includes("image") ? (["text", "image"] as const) : (["text"] as const),
+  );
+}
+
+export function decodeMeta(
+  value: unknown,
+  expectedSessionId: SessionId,
+): StoredSessionMetaV10 {
+  const row = recordFromSql(value, "session metadata");
+  const sessionId = stringFromSql(row.session_id, "session_id") as SessionId;
+  if (sessionId !== expectedSessionId) {
+    throw new Error(`Metadata session ID ${sessionId} does not match directory.`);
+  }
+  const schemaVersion = numberFromSql(row.schema_version, "schema_version");
+  if (schemaVersion !== 10) {
+    throw new Error(
+      `Session metadata schema version must be 10; received ${schemaVersion}.`,
+    );
+  }
+  const projectInstructionFile = nullableStringFromSql(
+    row.project_instruction_file,
+    "project_instruction_file",
+  );
+  const projectInstructionByteLength = nullableNumberFromSql(
+    row.project_instruction_byte_length,
+    "project_instruction_byte_length",
+  );
+  const projectInstructionSha256 = nullableStringFromSql(
+    row.project_instruction_sha256,
+    "project_instruction_sha256",
+  );
+  if (
+    (projectInstructionFile === null) !== (projectInstructionByteLength === null) ||
+    (projectInstructionFile === null) !== (projectInstructionSha256 === null)
+  ) {
+    throw new Error("Project instruction metadata must be entirely set or null.");
+  }
+  if (
+    projectInstructionFile !== null &&
+    projectInstructionFile !== "AGENTS.md" &&
+    projectInstructionFile !== "CLAUDE.md"
+  ) {
+    throw new Error(`Invalid project instruction file ${projectInstructionFile}.`);
+  }
+  const projectInstruction: ProjectInstructionManifest | undefined =
+    projectInstructionFile === null ||
+    projectInstructionByteLength === null ||
+    projectInstructionSha256 === null
+      ? undefined
+      : {
+          path: projectInstructionFile === "AGENTS.md" ? "AGENTS.md" : "CLAUDE.md",
+          byteLength: projectInstructionByteLength,
+          sha256: sha256FromSql(projectInstructionSha256, "project_instruction_sha256"),
+        };
+  const initializationState = enumFromSql(
+    row.initialization_state,
+    ["creating", "ready"] as const,
+    "initialization_state",
+  );
+  const sessionCompatibilityJson = nullableStringFromSql(
+    row.session_compatibility_json,
+    "session_compatibility_json",
+  );
+  const sessionCompatibilitySha256 = nullableStringFromSql(
+    row.session_compatibility_sha256,
+    "session_compatibility_sha256",
+  );
+  const activeRevisionId = nullableStringFromSql(
+    row.active_revision_id,
+    "active_revision_id",
+  ) as ContextRevisionId | null;
+  const modelName = stringFromSql(row.model_name, "model_name");
+  const storedContract =
+    sessionCompatibilityJson === null
+      ? undefined
+      : decodeSessionCompatibilityContract(sessionCompatibilityJson);
+  if (
+    (sessionCompatibilityJson === null) !== (sessionCompatibilitySha256 === null) ||
+    (sessionCompatibilityJson !== null &&
+      sha256(sessionCompatibilityJson) !== sessionCompatibilitySha256) ||
+    (initializationState === "creating") !== (activeRevisionId === null) ||
+    (initializationState === "creating") !== (sessionCompatibilityJson === null) ||
+    (storedContract !== undefined &&
+      (storedContract.modelName !== modelName ||
+        stableJsonStringify(storedContract) !== sessionCompatibilityJson))
+  ) {
+    throw new Error("Session compatibility or initialization metadata is invalid.");
+  }
+  return {
+    schemaVersion,
+    schemaFingerprint: stringFromSql(row.schema_fingerprint, "schema_fingerprint"),
+    initializationState,
+    sessionId,
+    workspaceRoot: stringFromSql(row.workspace_root, "workspace_root"),
+    modelName,
+    systemPromptSha256: stringFromSql(row.system_prompt_sha256, "system_prompt_sha256"),
+    ...(projectInstruction === undefined ? {} : { projectInstruction }),
+    sessionCompatibilityJson,
+    sessionCompatibilitySha256,
+    activeRevisionId,
+    nextTurnNumber: numberFromSql(row.next_turn_number, "next_turn_number"),
+    nextEventSequence: numberFromSql(row.next_event_sequence, "next_event_sequence"),
+    openCount: numberFromSql(row.open_count, "open_count"),
+    createdAt: timestampFromSql(row.created_at, "created_at"),
+    updatedAt: timestampFromSql(row.updated_at, "updated_at"),
+    lastOpenedAt: timestampFromSql(row.last_opened_at, "last_opened_at"),
+    lastClosedAt:
+      row.last_closed_at === null
+        ? null
+        : timestampFromSql(row.last_closed_at, "last_closed_at"),
+    lastCloseReason:
+      row.last_close_reason === null
+        ? null
+        : enumFromSql(
+            row.last_close_reason,
+            [
+              "oneshot_complete",
+              "tui_exit",
+              "session_switch",
+              "runner_failed",
+              "initialization_failed",
+            ] as const,
+            "last_close_reason",
+          ),
+  };
+}
+
+export function compatibilityContractDifferences(
+  storedJson: string | null,
+  current: SessionCompatibilityContract,
+): string[] {
+  if (storedJson === null) {
+    return ["sessionCompatibility"];
+  }
+  const stored = parseJson(storedJson, "session_compatibility_json");
+  if (typeof stored !== "object" || stored === null || Array.isArray(stored)) {
+    return ["sessionCompatibility"];
+  }
+  const record = stored as Record<string, unknown>;
+  const fields: readonly (keyof SessionCompatibilityContract)[] = [
+    "modelName",
+    "profileName",
+    "includeReasoningContent",
+    "contextProfile",
+    "messageProtocol",
+    "media",
+  ];
+  return fields.filter((key) => {
+    const storedValue = record[key];
+    const currentValue = current[key];
+    if (storedValue === undefined || currentValue === undefined) {
+      return storedValue !== currentValue;
+    }
+    return stableJsonStringify(storedValue) !== stableJsonStringify(currentValue);
+  });
+}
+
+function decodeSessionCompatibilityContract(
+  json: string,
+): SessionCompatibilityContract {
+  const record = recordFromSql(
+    parseJson(json, "session_compatibility_json"),
+    "session compatibility contract",
+  );
+  assertObjectKeys(
+    record,
+    [
+      "modelName",
+      "profileName",
+      "includeReasoningContent",
+      "contextProfile",
+      "messageProtocol",
+      "media",
+    ],
+    [
+      "modelName",
+      "includeReasoningContent",
+      "contextProfile",
+      "messageProtocol",
+      "media",
+    ],
+    "session compatibility contract",
+  );
+  const contextProfile = recordFromSql(
+    record.contextProfile,
+    "session compatibility context profile",
+  );
+  assertObjectKeys(
+    contextProfile,
+    ["contextWindowTokens", "maxSupportedOutputTokens"],
+    ["contextWindowTokens", "maxSupportedOutputTokens"],
+    "session compatibility context profile",
+  );
+  const messageProtocol = recordFromSql(
+    record.messageProtocol,
+    "session compatibility message protocol",
+  );
+  assertObjectKeys(
+    messageProtocol,
+    ["adapter", "serializationVersion"],
+    ["adapter", "serializationVersion"],
+    "session compatibility message protocol",
+  );
+  const media = recordFromSql(record.media, "session compatibility media");
+  assertObjectKeys(
+    media,
+    ["policyVersion", "policySha256", "inputModalities", "toolResultModalities"],
+    ["policyVersion", "policySha256", "inputModalities", "toolResultModalities"],
+    "session compatibility media",
+  );
+  const inputModalities = decodeCompatibilityModalities(media.inputModalities, "input");
+  const toolResultModalities = decodeCompatibilityModalities(
+    media.toolResultModalities,
+    "tool result",
+  );
+  if (toolResultModalities.includes("image") && !inputModalities.includes("image")) {
+    throw new Error("Session compatibility image tool results require image input.");
+  }
+  if (typeof record.includeReasoningContent !== "boolean") {
+    throw new Error("Session compatibility reasoning replay flag must be boolean.");
+  }
+  const modelName = stringFromSql(record.modelName, "compatibility modelName");
+  const profileName =
+    record.profileName === undefined
+      ? undefined
+      : stringFromSql(record.profileName, "compatibility profileName");
+  const context = createModelContextProfile({
+    contextWindowTokens: numberFromJson(
+      contextProfile.contextWindowTokens,
+      "compatibility contextWindowTokens",
+    ),
+    maxSupportedOutputTokens: numberFromJson(
+      contextProfile.maxSupportedOutputTokens,
+      "compatibility maxSupportedOutputTokens",
+    ),
+  });
+  const protocol: ModelMessageProtocol = Object.freeze({
+    adapter: enumFromSql(
+      messageProtocol.adapter,
+      MODEL_MESSAGE_PROTOCOL_ADAPTERS,
+      "compatibility message adapter",
+    ),
+    serializationVersion: stringFromSql(
+      messageProtocol.serializationVersion,
+      "compatibility serializationVersion",
+    ),
+  });
+  const policyVersion = stringFromSql(
+    media.policyVersion,
+    "compatibility image policyVersion",
+  );
+  const policySha256 = stringFromSql(
+    media.policySha256,
+    "compatibility image policySha256",
+  );
+  if (!/^[0-9a-f]{64}$/.test(policySha256)) {
+    throw new Error("Session image policy hash is invalid.");
+  }
+  return Object.freeze({
+    modelName,
+    ...(record.profileName === undefined ? {} : { profileName: profileName! }),
+    includeReasoningContent: record.includeReasoningContent,
+    contextProfile: Object.freeze(context),
+    messageProtocol: protocol,
+    media: Object.freeze({
+      policyVersion,
+      policySha256,
+      inputModalities,
+      toolResultModalities,
+    }),
+  });
+}
+
+function decodeCompatibilityModalities(
+  value: unknown,
+  label: string,
+): readonly ("text" | "image")[] {
+  if (!Array.isArray(value)) {
+    throw new Error(`Session compatibility ${label} modalities must be an array.`);
+  }
+  return normalizeInputModalities(
+    value.map((modality) =>
+      enumFromSql(
+        modality,
+        ["text", "image"] as const,
+        `compatibility ${label} modality`,
+      ),
+    ),
+  );
+}