tinker-agent 2.8.0 → 2.10.0

package/src/session/session-store-ledger-writer.ts

@@ -0,0 +1,315 @@
+import type { Database } from "bun:sqlite";
+import { AdmissionStaleError, type LedgerMutation } from "../agent/session-ledger";
+import type { IterationId, MessageId, SessionId, TurnId } from "../ids/runtime-id";
+import { stableJsonStringify } from "../model/model-request-preflight";
+import { SessionError, sessionWriteError } from "./session-errors";
+import type { SessionStore } from "./session-store";
+import {
+  insertFrame,
+  insertMessage,
+  insertPendingSkillActivation,
+  insertToolResult,
+} from "./session-store-record-writer";
+import { requireItem, requireSingleChange, runTransaction } from "./session-store-sql";
+import { numberFromSql } from "./session-store-value-codecs";
+
+/** Writes canonical ledger mutations using the session's existing connection. */
+export class SessionStoreLedgerWriter {
+  constructor(
+    private readonly database: Database,
+    private readonly sessionId: SessionId,
+    private readonly clock: () => string,
+    private readonly requireOpen: () => void,
+    private readonly store: Pick<SessionStore, "readMeta" | "loadContextSnapshot">,
+  ) {}
+
+  commit(mutation: LedgerMutation): void {
+    this.requireOpen();
+    const now = this.clock();
+    try {
+      runTransaction(this.database, () => {
+        switch (mutation.kind) {
+          case "begin_turn":
+            this.commitBeginTurn(mutation, now);
+            break;
+          case "append_steering_users":
+            this.commitSteeringUsers(mutation, now);
+            break;
+          case "append_assistant":
+            this.commitAssistant(mutation, now);
+            break;
+          case "commit_tool_completions":
+            this.commitToolCompletions(mutation, now);
+            break;
+          case "finish_turn":
+            this.commitFinishTurn(mutation, now);
+            break;
+        }
+      });
+    } catch (error) {
+      if (error instanceof AdmissionStaleError) {
+        throw error;
+      }
+      throw sessionWriteError(mutation.kind, this.sessionId, error);
+    }
+  }
+
+  private commitBeginTurn(
+    mutation: Extract<LedgerMutation, { kind: "begin_turn" }>,
+    now: string,
+  ): void {
+    const meta = this.store.readMeta();
+    if (mutation.admissionBase !== undefined) {
+      const snapshot = this.store.loadContextSnapshot();
+      const head = snapshot.canonical.messages.at(-1);
+      const base = mutation.admissionBase;
+      if (
+        head === undefined ||
+        base.canonicalMessageCount !== snapshot.canonical.messages.length ||
+        base.canonicalHeadMessageId !== head.messageId ||
+        base.canonicalHeadContentSha256 !== head.contentSha256 ||
+        base.activeRevisionId !== snapshot.revision.revisionId ||
+        base.activeRevisionNumber !== snapshot.revision.revisionNumber ||
+        base.surfaceSha256 !== snapshot.surface.surfaceSha256 ||
+        base.sessionCompatibilitySha256 !== meta.sessionCompatibilitySha256 ||
+        base.nextTurnNumber !== meta.nextTurnNumber
+      ) {
+        throw new AdmissionStaleError();
+      }
+    }
+    if (
+      meta.initializationState !== "ready" ||
+      meta.nextTurnNumber !== mutation.turn.turnNumber
+    ) {
+      throw new Error("Session turn counter or state changed before begin_turn.");
+    }
+    this.database
+      .query(
+        `INSERT INTO turns (
+        session_id, turn_id, turn_number, status, next_iteration_number,
+        last_iteration_id, final_message_id, terminal_detail_json, started_at, finished_at
+      ) VALUES (?, ?, ?, 'open', 1, NULL, NULL, NULL, ?, NULL)`,
+      )
+      .run(this.sessionId, mutation.turn.turnId, mutation.turn.turnNumber, now);
+    insertFrame(this.database, mutation.frame);
+    insertMessage(this.database, mutation.message);
+    const updated = this.database
+      .query(
+        `UPDATE session_meta SET next_turn_number = ?, updated_at = ?
+       WHERE singleton = 1 AND next_turn_number = ?`,
+      )
+      .run(mutation.turn.turnNumber + 1, now, mutation.turn.turnNumber);
+    requireSingleChange(this.database, updated.changes, "advance turn counter");
+  }
+
+  private commitSteeringUsers(
+    mutation: Extract<LedgerMutation, { kind: "append_steering_users" }>,
+    now: string,
+  ): void {
+    const turn = this.requireTurnRow(mutation.turn.turnId);
+    if (turn.status !== "open") {
+      throw new Error(`Turn ${mutation.turn.turnId} is not open.`);
+    }
+    if (
+      mutation.frames.length === 0 ||
+      mutation.frames.length !== mutation.messages.length
+    ) {
+      throw new Error(
+        "Steering user mutation must contain matching frames and messages.",
+      );
+    }
+    for (let index = 0; index < mutation.frames.length; index += 1) {
+      insertFrame(this.database, requireItem(mutation.frames, index, "steering frame"));
+      insertMessage(
+        this.database,
+        requireItem(mutation.messages, index, "steering message"),
+      );
+    }
+    this.touch(now);
+  }
+
+  private commitAssistant(
+    mutation: Extract<LedgerMutation, { kind: "append_assistant" }>,
+    now: string,
+  ): void {
+    const iteration = this.requireIterationRow(mutation.iteration.iterationId);
+    if (iteration.outcome !== "open") {
+      throw new Error(`Iteration ${mutation.iteration.iterationId} is not open.`);
+    }
+    insertFrame(this.database, mutation.frame);
+    insertMessage(this.database, mutation.message);
+    if (
+      mutation.message.role === "assistant" &&
+      mutation.message.toolCalls !== undefined
+    ) {
+      const expected = numberFromSql(
+        iteration.next_tool_call_number,
+        "next_tool_call_number",
+      );
+      if (expected !== 1) {
+        throw new Error(
+          "Assistant tool calls were already allocated for this iteration.",
+        );
+      }
+      const updated = this.database
+        .query(
+          `UPDATE iterations SET next_tool_call_number = ?
+         WHERE iteration_id = ? AND outcome = 'open' AND next_tool_call_number = 1`,
+        )
+        .run(mutation.message.toolCalls.length + 1, mutation.iteration.iterationId);
+      requireSingleChange(this.database, updated.changes, "advance tool call counter");
+    }
+    this.touch(now);
+  }
+
+  private commitToolCompletions(
+    mutation: Extract<LedgerMutation, { kind: "commit_tool_completions" }>,
+    now: string,
+  ): void {
+    const current = this.database
+      .query("SELECT state, last_ordinal FROM protocol_frames WHERE frame_id = ?")
+      .get(mutation.frameBefore.frameId) as {
+      state: string;
+      last_ordinal: unknown;
+    } | null;
+    if (current?.state !== "open" || current.last_ordinal !== null) {
+      throw new Error(`Frame ${mutation.frameBefore.frameId} is not open.`);
+    }
+    for (let index = 0; index < mutation.messages.length; index += 1) {
+      const message = requireItem(mutation.messages, index, "tool message");
+      const result = requireItem(mutation.toolResults, index, "tool result");
+      insertMessage(this.database, message);
+      insertToolResult(this.database, result);
+      insertPendingSkillActivation(this.database, message, result, now);
+    }
+    if (mutation.frameAfter.state === "closed") {
+      const updated = this.database
+        .query(
+          `UPDATE protocol_frames SET state = 'closed', last_ordinal = ?, closed_at = ?
+         WHERE frame_id = ? AND state = 'open' AND last_ordinal IS NULL`,
+        )
+        .run(
+          mutation.frameAfter.lastOrdinal!,
+          mutation.frameAfter.closedAt!,
+          mutation.frameAfter.frameId,
+        );
+      requireSingleChange(this.database, updated.changes, "close tool exchange frame");
+    }
+    this.touch(now);
+  }
+
+  private commitFinishTurn(
+    mutation: Extract<LedgerMutation, { kind: "finish_turn" }>,
+    now: string,
+  ): void {
+    const result = mutation.result;
+    const turnStatus = result.status;
+    const iterationOutcome = result.status;
+    const detail =
+      result.status === "completed"
+        ? stableJsonStringify({ version: 1, finalTextLength: result.finalText.length })
+        : result.status === "failed"
+          ? stableJsonStringify({ version: 1, error: result.error.slice(0, 2_000) })
+          : stableJsonStringify({ version: 1, cancellation: result.cancellation });
+    this.markTerminalRows(
+      mutation.turn.turnId,
+      result.lastIteration.iterationId,
+      turnStatus,
+      iterationOutcome,
+      mutation.finalMessageId ?? null,
+      detail,
+      now,
+    );
+  }
+
+  markTerminalRows(
+    turnId: TurnId,
+    iterationId: IterationId,
+    turnStatus: "completed" | "failed" | "cancelled" | "interrupted",
+    iterationOutcome: "completed" | "failed" | "cancelled" | "interrupted",
+    finalMessageId: MessageId | null,
+    terminalDetailJson: string,
+    now: string,
+  ): void {
+    const iteration = this.database
+      .query(
+        `UPDATE iterations SET outcome = ?, finished_at = ?
+       WHERE iteration_id = ? AND turn_id = ? AND outcome = 'open'`,
+      )
+      .run(iterationOutcome, now, iterationId, turnId);
+    requireSingleChange(this.database, iteration.changes, "finish iteration");
+    const turn = this.database
+      .query(
+        `UPDATE turns SET status = ?, last_iteration_id = ?, final_message_id = ?,
+         terminal_detail_json = ?, finished_at = ?
+       WHERE turn_id = ? AND status = 'open'`,
+      )
+      .run(turnStatus, iterationId, finalMessageId, terminalDetailJson, now, turnId);
+    requireSingleChange(this.database, turn.changes, "finish turn");
+    this.touch(now);
+  }
+
+  markOpenTurnInterrupted(turnId: TurnId, iterationId: IterationId | undefined): void {
+    const now = this.clock();
+    try {
+      runTransaction(this.database, () => {
+        if (iterationId !== undefined) {
+          const iteration = this.database
+            .query(
+              `UPDATE iterations SET outcome = 'interrupted', finished_at = ?
+             WHERE iteration_id = ? AND outcome = 'open'`,
+            )
+            .run(now, iterationId);
+          requireSingleChange(this.database, iteration.changes, "interrupt iteration");
+        }
+        const turn = this.database
+          .query(
+            `UPDATE turns SET status = 'interrupted', finished_at = ?,
+             terminal_detail_json = ?
+           WHERE turn_id = ? AND status = 'open'`,
+          )
+          .run(
+            now,
+            stableJsonStringify({ version: 1, reason: "process_interrupted" }),
+            turnId,
+          );
+        requireSingleChange(this.database, turn.changes, "interrupt turn");
+        this.touch(now);
+      });
+    } catch (error) {
+      throw new SessionError(
+        "SESSION_RECOVERY_FAILED",
+        "recover_open_turn",
+        `Failed to mark turn ${turnId} interrupted.`,
+        { sessionId: this.sessionId, cause: error },
+      );
+    }
+  }
+
+  requireTurnRow(turnId: TurnId): Record<string, unknown> {
+    const row = this.database
+      .query("SELECT * FROM turns WHERE turn_id = ?")
+      .get(turnId) as Record<string, unknown> | null;
+    if (row === null) {
+      throw new Error(`Unknown turn ${turnId}.`);
+    }
+    return row;
+  }
+
+  requireIterationRow(iterationId: IterationId): Record<string, unknown> {
+    const row = this.database
+      .query("SELECT * FROM iterations WHERE iteration_id = ?")
+      .get(iterationId) as Record<string, unknown> | null;
+    if (row === null) {
+      throw new Error(`Unknown iteration ${iterationId}.`);
+    }
+    return row;
+  }
+
+  touch(timestamp: string): void {
+    const updated = this.database
+      .query("UPDATE session_meta SET updated_at = ? WHERE singleton = 1")
+      .run(timestamp);
+    requireSingleChange(this.database, updated.changes, "touch session");
+  }
+}

package/src/session/session-store-record-writer.ts

@@ -0,0 +1,318 @@
+import type { Database } from "bun:sqlite";
+import {
+  canonicalToolResultContentHash,
+  toolResultDisplayText,
+  validateToolResultContent,
+} from "../agent/tool-result-content";
+import {
+  validateStoredContextSurface,
+  type StoredContextSurfaceV8,
+} from "../context/context-surface";
+import {
+  userMessageHash,
+  type CanonicalMessageRecord,
+  type ProtocolFrame,
+  type ToolResultRecord,
+} from "../context/protocol-frame";
+import { validateUserMessage, type ImageAssetRef } from "../image/image-types";
+import { stableJsonStringify } from "../model/model-request-preflight";
+import { imageAssetRefFromAttachment } from "./session-store-record-codecs";
+import { requireItem } from "./session-store-sql";
+import { numberFromSql, timestampFromSql } from "./session-store-value-codecs";
+
+export function insertPendingSkillActivation(
+  database: Database,
+  message: CanonicalMessageRecord,
+  result: ToolResultRecord,
+  now: string,
+): void {
+  if (
+    message.role !== "tool" ||
+    result.completion.kind !== "returned" ||
+    result.completion.raw.kind !== "skill" ||
+    !result.completion.raw.ok ||
+    result.completion.raw.status !== "loaded"
+  ) {
+    return;
+  }
+  const raw = result.completion.raw;
+  if (message.name !== "Skill" || message.messageId !== result.toolMessageId) {
+    throw new Error("Loaded Agent Skill completion has invalid tool identity.");
+  }
+  database
+    .query(
+      `INSERT INTO skill_activations (
+        activation_message_id, tool_call_id, session_id, name, scope,
+        skill_file_sha256, state, dispatched_iteration_id, settled_revision_id,
+        rejection_reason, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, 'pending', NULL, NULL, NULL, ?, ?)`,
+    )
+    .run(
+      message.messageId,
+      result.toolCallId,
+      result.sessionId,
+      raw.name,
+      raw.scope,
+      raw.sha256,
+      now,
+      now,
+    );
+}
+
+export function insertFrame(database: Database, frame: ProtocolFrame): void {
+  database
+    .query(
+      `INSERT INTO protocol_frames (
+      frame_id, session_id, turn_id, iteration_id, kind, state,
+      first_ordinal, last_ordinal, created_at, closed_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      frame.frameId,
+      frame.sessionId,
+      frame.turnId ?? null,
+      frame.iterationId ?? null,
+      frame.kind,
+      frame.state,
+      frame.firstOrdinal,
+      frame.lastOrdinal ?? null,
+      frame.createdAt,
+      frame.closedAt ?? null,
+    );
+}
+
+export function insertMessage(
+  database: Database,
+  message: CanonicalMessageRecord,
+): void {
+  const assistant = message.role === "assistant" ? message : undefined;
+  const tool = message.role === "tool" ? message : undefined;
+  const turnId = "turnId" in message ? message.turnId : null;
+  const iterationId = "iterationId" in message ? message.iterationId : null;
+  const reasoningPresent =
+    assistant !== undefined && assistant.reasoningContent !== undefined ? 1 : 0;
+  database
+    .query(
+      `INSERT INTO messages (
+      message_id, session_id, frame_id, ordinal, role, turn_id, iteration_id,
+      content, content_sha256, reasoning_content, reasoning_content_present,
+      tool_calls_json, provider, model, tool_call_id, provider_tool_call_id,
+      name, origin, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      message.messageId,
+      message.sessionId,
+      message.frameId,
+      message.ordinal,
+      message.role,
+      turnId,
+      iterationId,
+      message.role === "tool" ? message.displayText : message.content,
+      message.contentSha256,
+      assistant?.reasoningContent ?? null,
+      reasoningPresent,
+      assistant?.toolCalls === undefined
+        ? null
+        : stableJsonStringify(assistant.toolCalls),
+      assistant?.provider ?? null,
+      assistant?.model ?? null,
+      tool?.toolCallId ?? null,
+      tool?.providerToolCallId ?? null,
+      tool?.name ?? null,
+      message.origin,
+      message.createdAt,
+    );
+  if (message.role === "user" && message.attachments !== undefined) {
+    insertMessageImageAttachments(database, message);
+  }
+  if (message.role === "tool") {
+    insertToolMessageContentBlocks(database, message);
+  }
+}
+
+function insertMessageImageAttachments(
+  database: Database,
+  message: Extract<CanonicalMessageRecord, { role: "user" }>,
+): void {
+  const userMessage = {
+    role: "user" as const,
+    content: message.content,
+    attachments: message.attachments,
+  };
+
+  validateUserMessage(userMessage);
+  if (userMessageHash(userMessage) !== message.contentSha256) {
+    throw new Error("User image attachment hash does not match the message hash.");
+  }
+  for (let position = 0; position < message.attachments!.length; position += 1) {
+    const attachment = requireItem(message.attachments!, position, "image attachment");
+    ensureImageAsset(
+      database,
+      imageAssetRefFromAttachment(attachment),
+      message.createdAt,
+    );
+    database
+      .query(
+        `INSERT INTO message_image_attachments (
+           message_id, attachment_id, asset_id, position, label,
+           range_start, range_end, original_name
+         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        message.messageId,
+        attachment.attachmentId,
+        attachment.assetId,
+        position,
+        attachment.label,
+        attachment.range.start,
+        attachment.range.end,
+        attachment.originalName,
+      );
+  }
+}
+
+function insertToolMessageContentBlocks(
+  database: Database,
+  message: Extract<CanonicalMessageRecord, { role: "tool" }>,
+): void {
+  validateToolResultContent(message.content);
+  if (
+    canonicalToolResultContentHash(message.content) !== message.contentSha256 ||
+    toolResultDisplayText(message.content) !== message.displayText
+  ) {
+    throw new Error("Tool content blocks do not match canonical message metadata.");
+  }
+  for (let position = 0; position < message.content.length; position += 1) {
+    const block = requireItem(message.content, position, "tool content block");
+    if (block.type === "image") {
+      ensureImageAsset(database, block.asset, message.createdAt);
+    }
+    database
+      .query(
+        `INSERT INTO tool_message_content_blocks (
+           message_id, position, kind, text_content, asset_id
+         ) VALUES (?, ?, ?, ?, ?)`,
+      )
+      .run(
+        message.messageId,
+        position,
+        block.type,
+        block.type === "text" ? block.text : null,
+        block.type === "image" ? block.asset.assetId : null,
+      );
+  }
+}
+
+function ensureImageAsset(
+  database: Database,
+  asset: ImageAssetRef,
+  createdAt: string,
+): void {
+  const existing = database
+    .query(
+      `SELECT mime_type, byte_length, width, height, created_at
+       FROM image_assets WHERE asset_id = ?`,
+    )
+    .get(asset.assetId) as {
+    mime_type: unknown;
+    byte_length: unknown;
+    width: unknown;
+    height: unknown;
+    created_at: unknown;
+  } | null;
+  if (existing === null) {
+    database
+      .query(
+        `INSERT INTO image_assets (
+           asset_id, mime_type, byte_length, width, height, created_at
+         ) VALUES (?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        asset.assetId,
+        asset.mimeType,
+        asset.byteLength,
+        asset.width,
+        asset.height,
+        createdAt,
+      );
+    return;
+  }
+
+  timestampFromSql(existing.created_at, "image asset created_at");
+  if (
+    existing.mime_type !== asset.mimeType ||
+    numberFromSql(existing.byte_length, "image asset byte_length") !==
+      asset.byteLength ||
+    numberFromSql(existing.width, "image asset width") !== asset.width ||
+    numberFromSql(existing.height, "image asset height") !== asset.height
+  ) {
+    throw new Error(`Image asset metadata conflicts for ${asset.assetId}.`);
+  }
+}
+
+export function insertToolResult(database: Database, result: ToolResultRecord): void {
+  const returned = result.completion.kind === "returned" ? result.completion : null;
+  const synthetic = result.completion.kind === "synthetic" ? result.completion : null;
+  database
+    .query(
+      `INSERT INTO tool_results (
+      tool_call_id, session_id, frame_id, tool_message_id, completion_kind,
+      raw_json, raw_sha256, observation_format, synthetic_reason,
+      synthetic_detail, observation_sha256, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      result.toolCallId,
+      result.sessionId,
+      result.frameId,
+      result.toolMessageId,
+      result.completion.kind,
+      returned === null ? null : stableJsonStringify(returned.raw),
+      returned?.rawSha256 ?? null,
+      returned?.observationFormat ?? null,
+      synthetic?.reason ?? null,
+      synthetic?.detail ?? null,
+      result.observationSha256,
+      result.createdAt,
+    );
+}
+
+export function insertContextSurface(
+  database: Database,
+  surface: StoredContextSurfaceV8,
+): void {
+  validateStoredContextSurface(surface);
+  database
+    .query(
+      `INSERT INTO context_surfaces (
+        surface_id, session_id, system_prompt, system_prompt_sha256,
+        recall_contract_version,
+        project_instruction_json, skill_catalog_json, skill_catalog_sha256,
+        active_skills_json, active_skills_sha256, tool_definitions_json,
+        tool_definitions_sha256, tool_schema_sha256, request_config_sha256,
+        request_max_output_tokens, surface_sha256, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    )
+    .run(
+      surface.surfaceId,
+      surface.sessionId,
+      surface.systemPrompt,
+      surface.systemPromptSha256,
+      surface.recallContractVersion,
+      surface.projectInstruction === undefined
+        ? null
+        : stableJsonStringify(surface.projectInstruction),
+      stableJsonStringify(surface.skillCatalog),
+      surface.skillCatalogSha256,
+      stableJsonStringify(surface.activeSkills),
+      surface.activeSkillsSha256,
+      stableJsonStringify(surface.toolDefinitions),
+      surface.toolDefinitionsSha256,
+      surface.toolSchemaSha256,
+      surface.requestConfigSha256,
+      surface.requestMaxOutputTokens,
+      surface.surfaceSha256,
+      surface.createdAt,
+    );
+}