@sixb/core 0.1.2 → 0.1.4

package/src/storage/agents/in-memory.ts

@@ -5,8 +5,17 @@ import { parseSixbFailure } from "../../errors/internal"
 import type { SixbFailure } from "../../errors/types"
 import type { ExecutionStorage } from "../executions"
 import { AgentStorageError } from "./errors"
-import { assertAgentRunExecution } from "./provider"
+import {
+  agentContextCheckpointMatchesCreateInput,
+  assertAgentContextCheckpointAnchors,
+  assertAgentContextCheckpointAuthority,
+  assertAgentContextCheckpointReplayState,
+  assertAgentRunExecution,
+  assertCreateAgentContextCheckpointInput,
+} from "./provider"
 import type {
+  AgentContextCheckpointRecord,
+  AgentContextCheckpointStore,
   AgentMessageRecord,
   AgentMessageStore,
   AgentRunFailureCode,
@@ -17,8 +26,10 @@ import type {
   AgentThreadStore,
   AppendAgentMessageInput,
   ConfirmAgentRunExecutionOwnershipInput,
+  CreateAgentContextCheckpointInput,
   CreateAgentRunInput,
   CreateAgentThreadInput,
+  DeleteAgentMessagesByRunInput,
   FinishAgentRunInput,
   FinishQueuedAgentRunInput,
   ListAgentMessagesInput,
@@ -77,21 +88,23 @@ function applyWindow<T>(rows: T[], offset = 0, limit?: number): Window<T> {
 }
 
 /**
- * Shared in-memory state behind the three sub-stores. They are tiered for ergonomics
+ * Shared in-memory state behind the four sub-stores. They are tiered for ergonomics
  * (`storage.runs.create(...)`), but several operations span tables — creating/finishing a run
- * updates the thread anchor, appending a message bumps thread stats — so they all read and write the
- * same maps through this object.
+ * updates the thread anchor, appending a message bumps thread stats, and checkpoint creation reads
+ * run/thread/message anchors — so they all read and write the same maps through this object.
  */
 interface AgentStoreState {
   readonly threads: Map<string, AgentThreadRecord>
   readonly runs: Map<string, AgentRunRecord>
   readonly messages: Map<string, AgentMessageRecord>
+  readonly checkpoints: Map<string, AgentContextCheckpointRecord>
 }
 
 export interface InMemoryAgentStorageSnapshot {
   readonly threads: Map<string, AgentThreadRecord>
   readonly runs: Map<string, AgentRunRecord>
   readonly messages: Map<string, AgentMessageRecord>
+  readonly checkpoints: Map<string, AgentContextCheckpointRecord>
 }
 
 // ── threads ───────────────────────────────────────────────────────────────────────────────────
@@ -466,6 +479,50 @@ class InMemoryAgentMessageStore implements AgentMessageStore {
     return clone(message)
   }
 
+  async deleteByRunId(input: DeleteAgentMessagesByRunInput): Promise<number> {
+    const threadKey = key(input.projectId, input.threadId)
+    const thread = this.state.threads.get(threadKey)
+    if (!thread) {
+      throw new AgentStorageError(
+        "thread_not_found",
+        `[Sixb] Agent thread '${input.threadId}' not found for project '${input.projectId}'.`
+      )
+    }
+
+    const messages = [...this.state.messages.entries()].filter(
+      ([, message]) =>
+        message.projectId === input.projectId &&
+        message.threadId === input.threadId &&
+        message.runId === input.runId
+    )
+    if (messages.length === 0) {
+      return 0
+    }
+
+    for (const [messageKey] of messages) {
+      this.state.messages.delete(messageKey)
+    }
+
+    const remainingMessages = [...this.state.messages.values()]
+      .filter(
+        (message) => message.projectId === input.projectId && message.threadId === input.threadId
+      )
+      .sort((left, right) => right.seq - left.seq)
+    const latestMessage = remainingMessages[0]
+    const updatedAt = new Date()
+    this.state.threads.set(
+      threadKey,
+      clone({
+        ...thread,
+        messageCount: remainingMessages.length,
+        lastMessageAt: latestMessage?.createdAt,
+        updatedAt,
+      })
+    )
+
+    return messages.length
+  }
+
   async getById(params: { projectId: string; id: string }): Promise<AgentMessageRecord | null> {
     const record = this.state.messages.get(key(params.projectId, params.id))
     return record ? clone(record) : null
@@ -478,6 +535,7 @@ class InMemoryAgentMessageStore implements AgentMessageStore {
     const filtered = [...this.state.messages.values()]
       .filter((message) => message.projectId === input.projectId)
       .filter((message) => message.threadId === input.threadId)
+      .filter((message) => (input.afterSeq === undefined ? true : message.seq > input.afterSeq))
       .filter((message) => (roles ? roles.has(message.role) : true))
       .sort((a, b) => (order === "asc" ? a.seq - b.seq : b.seq - a.seq))
 
@@ -496,21 +554,143 @@ class InMemoryAgentMessageStore implements AgentMessageStore {
   }
 }
 
+// ── context checkpoints ──────────────────────────────────────────────────────────────────────
+
+class InMemoryAgentContextCheckpointStore implements AgentContextCheckpointStore {
+  constructor(private readonly state: AgentStoreState) {}
+
+  async create(input: CreateAgentContextCheckpointInput): Promise<AgentContextCheckpointRecord> {
+    assertCreateAgentContextCheckpointInput(input)
+
+    // No `await` between authority checks and append: this is one in-memory critical section.
+    const run = this.state.runs.get(key(input.projectId, input.createdByRunId)) ?? null
+    const thread = this.state.threads.get(key(input.projectId, input.threadId)) ?? null
+    assertAgentContextCheckpointAuthority({ create: input, run, thread })
+
+    const messages = [...this.state.messages.values()].filter(
+      (message) => message.projectId === input.projectId && message.threadId === input.threadId
+    )
+    const headSeq = messages.reduce((head, message) => Math.max(head, message.seq), 0)
+    const latest = this.findLatest(input.projectId, input.threadId)
+
+    const existingForRun = [...this.state.checkpoints.values()].find(
+      (checkpoint) =>
+        checkpoint.projectId === input.projectId &&
+        checkpoint.createdByRunId === input.createdByRunId
+    )
+    if (existingForRun) {
+      if (agentContextCheckpointMatchesCreateInput(existingForRun, input)) {
+        assertAgentContextCheckpointReplayState({
+          create: input,
+          existing: existingForRun,
+          latest,
+          headSeq,
+        })
+        return clone(existingForRun)
+      }
+      throw new AgentStorageError(
+        "invalid_state",
+        `[Sixb] Agent run '${input.createdByRunId}' already created a different context checkpoint.`
+      )
+    }
+
+    if (this.state.checkpoints.has(key(input.projectId, input.id))) {
+      throw new AgentStorageError(
+        "duplicate_id",
+        `[Sixb] Agent context checkpoint '${input.id}' already exists for project '${input.projectId}'.`
+      )
+    }
+
+    const firstRetained =
+      messages
+        .filter((message) => message.seq > input.summarizedThroughSeq)
+        .sort((left, right) => left.seq - right.seq)[0] ?? null
+    assertAgentContextCheckpointAnchors({
+      create: input,
+      latest,
+      headSeq,
+      firstRetained,
+    })
+
+    const record: AgentContextCheckpointRecord = {
+      id: input.id,
+      projectId: input.projectId,
+      threadId: input.threadId,
+      createdByRunId: input.createdByRunId,
+      ...(input.expectedPreviousCheckpointId === null
+        ? {}
+        : { previousCheckpointId: input.expectedPreviousCheckpointId }),
+      reason: input.reason,
+      summary: input.summary,
+      summaryFormatVersion: input.summaryFormatVersion,
+      summarizedThroughSeq: input.summarizedThroughSeq,
+      observedHeadSeq: input.observedHeadSeq,
+      estimatedInputTokensBefore: input.estimatedInputTokensBefore,
+      estimatedInputTokensAfter: input.estimatedInputTokensAfter,
+      summaryModelId: input.summaryModelId,
+      createdAt: new Date(input.createdAt ?? new Date()),
+    }
+    this.state.checkpoints.set(key(input.projectId, input.id), clone(record))
+    return clone(record)
+  }
+
+  async getLatest(input: {
+    readonly projectId: string
+    readonly threadId: string
+  }): Promise<AgentContextCheckpointRecord | null> {
+    const record = this.findLatest(input.projectId, input.threadId)
+    return record ? clone(record) : null
+  }
+
+  async getByRunIds(input: {
+    readonly projectId: string
+    readonly runIds: readonly string[]
+  }): Promise<readonly AgentContextCheckpointRecord[]> {
+    const byRunId = new Map(
+      [...this.state.checkpoints.values()]
+        .filter((checkpoint) => checkpoint.projectId === input.projectId)
+        .map((checkpoint) => [checkpoint.createdByRunId, checkpoint] as const)
+    )
+    return [...new Set(input.runIds)].flatMap((runId) => {
+      const checkpoint = byRunId.get(runId)
+      return checkpoint ? [clone(checkpoint)] : []
+    })
+  }
+
+  private findLatest(projectId: string, threadId: string): AgentContextCheckpointRecord | null {
+    return (
+      [...this.state.checkpoints.values()]
+        .filter(
+          (checkpoint) => checkpoint.projectId === projectId && checkpoint.threadId === threadId
+        )
+        .sort(
+          (left, right) =>
+            right.summarizedThroughSeq - left.summarizedThroughSeq ||
+            right.createdAt.getTime() - left.createdAt.getTime() ||
+            right.id.localeCompare(left.id)
+        )[0] ?? null
+    )
+  }
+}
+
 export class InMemoryAgentStorage implements AgentStorage {
   private readonly state: AgentStoreState = {
     threads: new Map(),
     runs: new Map(),
     messages: new Map(),
+    checkpoints: new Map(),
   }
 
   readonly threads: InMemoryAgentThreadStore
   readonly runs: InMemoryAgentRunStore
   readonly messages: InMemoryAgentMessageStore
+  readonly checkpoints: InMemoryAgentContextCheckpointStore
 
   constructor(executions: ExecutionStorage) {
     this.threads = new InMemoryAgentThreadStore(this.state)
     this.runs = new InMemoryAgentRunStore(this.state, executions)
     this.messages = new InMemoryAgentMessageStore(this.state)
+    this.checkpoints = new InMemoryAgentContextCheckpointStore(this.state)
   }
 
   snapshot(): InMemoryAgentStorageSnapshot {
@@ -518,6 +698,7 @@ export class InMemoryAgentStorage implements AgentStorage {
       threads: structuredClone(this.state.threads),
       runs: structuredClone(this.state.runs),
       messages: structuredClone(this.state.messages),
+      checkpoints: structuredClone(this.state.checkpoints),
     }
   }
 
@@ -525,6 +706,7 @@ export class InMemoryAgentStorage implements AgentStorage {
     replace(this.state.threads, snapshot.threads)
     replace(this.state.runs, snapshot.runs)
     replace(this.state.messages, snapshot.messages)
+    replace(this.state.checkpoints, snapshot.checkpoints)
   }
 }
 

package/src/storage/agents/index.ts

@@ -3,6 +3,9 @@ export { AgentStorageError } from "./errors"
 export type { InMemoryAgentStorageSnapshot } from "./in-memory"
 export { InMemoryAgentStorage } from "./in-memory"
 export type {
+  AgentContextCheckpointReason,
+  AgentContextCheckpointRecord,
+  AgentContextCheckpointStore,
   AgentExecutionStatus,
   AgentMessageRecord,
   AgentMessageRole,
@@ -22,8 +25,10 @@ export type {
   AgentThreadStore,
   AppendAgentMessageInput,
   ConfirmAgentRunExecutionOwnershipInput,
+  CreateAgentContextCheckpointInput,
   CreateAgentRunInput,
   CreateAgentThreadInput,
+  DeleteAgentMessagesByRunInput,
   FinishAgentRunInput,
   FinishQueuedAgentRunInput,
   ListAgentMessagesInput,

package/src/storage/agents/provider.ts

@@ -2,6 +2,13 @@ import { agentServiceAccountId } from "../../agents/authority"
 import type { ExecutionStorage } from "../executions"
 import { findAgentRunExecution } from "../executions/run-link"
 import { AgentStorageError } from "./errors"
+import type {
+  AgentContextCheckpointRecord,
+  AgentMessageRecord,
+  AgentRunRecord,
+  AgentThreadRecord,
+  CreateAgentContextCheckpointInput,
+} from "./types"
 
 /** Validate the semantic link between a conversational Agent run and its immutable execution. */
 export async function assertAgentRunExecution(input: {
@@ -25,3 +32,221 @@ export async function assertAgentRunExecution(input: {
     )
   }
 }
+
+/** Validate provider-independent checkpoint fields before entering a storage critical section. */
+export function assertCreateAgentContextCheckpointInput(
+  input: CreateAgentContextCheckpointInput,
+  prefix = "Sixb"
+): void {
+  for (const [name, value] of [
+    ["id", input.id],
+    ["projectId", input.projectId],
+    ["threadId", input.threadId],
+    ["createdByRunId", input.createdByRunId],
+    ["executionToken", input.executionToken],
+    ["summary", input.summary],
+    ["summaryModelId", input.summaryModelId],
+  ] as const) {
+    if (value.trim().length === 0) {
+      throw new AgentStorageError(
+        "invalid_input",
+        `[${prefix}] Agent context checkpoint '${name}' must not be empty.`
+      )
+    }
+  }
+
+  if (input.summaryFormatVersion !== 1) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint summary format version must be 1.`
+    )
+  }
+  if (input.reason !== "threshold" && input.reason !== "overflow") {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint reason must be 'threshold' or 'overflow'.`
+    )
+  }
+  if (
+    input.expectedPreviousCheckpointId !== null &&
+    input.expectedPreviousCheckpointId.trim().length === 0
+  ) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint expected previous id must not be empty.`
+    )
+  }
+  if (input.createdAt && !Number.isFinite(input.createdAt.getTime())) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint createdAt must be a valid date.`
+    )
+  }
+
+  for (const [name, value, minimum] of [
+    ["expectedHeadSeq", input.expectedHeadSeq, 1],
+    ["summarizedThroughSeq", input.summarizedThroughSeq, 1],
+    ["observedHeadSeq", input.observedHeadSeq, 1],
+    ["estimatedInputTokensBefore", input.estimatedInputTokensBefore, 0],
+    ["estimatedInputTokensAfter", input.estimatedInputTokensAfter, 0],
+  ] as const) {
+    if (!Number.isSafeInteger(value) || value < minimum) {
+      throw new AgentStorageError(
+        "invalid_input",
+        `[${prefix}] Agent context checkpoint '${name}' must be a safe integer greater than or equal to ${minimum}.`
+      )
+    }
+  }
+
+  if (input.observedHeadSeq !== input.expectedHeadSeq) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint observed head must equal its expected message head.`
+    )
+  }
+  if (input.summarizedThroughSeq >= input.observedHeadSeq) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint must retain the triggering head message.`
+    )
+  }
+}
+
+/** Assert that the current delivery still owns the active conversational run. */
+export function assertAgentContextCheckpointAuthority(input: {
+  readonly create: CreateAgentContextCheckpointInput
+  readonly run: AgentRunRecord | null
+  readonly thread: AgentThreadRecord | null
+  readonly prefix?: string
+}): asserts input is typeof input & {
+  readonly run: AgentRunRecord
+  readonly thread: AgentThreadRecord
+} {
+  const { create, run, thread } = input
+  const prefix = input.prefix ?? "Sixb"
+  if (!run) {
+    throw new AgentStorageError(
+      "run_not_found",
+      `[${prefix}] Agent run '${create.createdByRunId}' not found for project '${create.projectId}'.`
+    )
+  }
+  if (!thread) {
+    throw new AgentStorageError(
+      "thread_not_found",
+      `[${prefix}] Agent thread '${create.threadId}' not found for project '${create.projectId}'.`
+    )
+  }
+  if (run.threadId !== create.threadId) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent run '${run.id}' does not belong to thread '${create.threadId}'.`
+    )
+  }
+  if (run.status !== "running") {
+    throw new AgentStorageError(
+      "invalid_state",
+      `[${prefix}] Agent run '${run.id}' is not running (status '${run.status}').`
+    )
+  }
+  if (!run.execution || run.execution.token !== create.executionToken) {
+    throw new AgentStorageError(
+      "execution_lost",
+      `[${prefix}] Execution token is no longer current on agent run '${run.id}'.`
+    )
+  }
+  if (thread.activeRunId !== run.id) {
+    throw new AgentStorageError(
+      "invalid_state",
+      `[${prefix}] Agent run '${run.id}' no longer owns thread '${thread.id}'.`
+    )
+  }
+}
+
+/** Assert both compare-and-swap anchors and the retained-turn boundary. */
+export function assertAgentContextCheckpointAnchors(input: {
+  readonly create: CreateAgentContextCheckpointInput
+  readonly latest: AgentContextCheckpointRecord | null
+  readonly headSeq: number
+  readonly firstRetained: AgentMessageRecord | null
+  readonly prefix?: string
+}): void {
+  const { create, latest, headSeq, firstRetained } = input
+  const prefix = input.prefix ?? "Sixb"
+  if (headSeq !== create.expectedHeadSeq) {
+    throw new AgentStorageError(
+      "invalid_state",
+      `[${prefix}] Agent thread '${create.threadId}' message head changed from ${create.expectedHeadSeq} to ${headSeq}.`
+    )
+  }
+
+  const latestId = latest?.id ?? null
+  if (latestId !== create.expectedPreviousCheckpointId) {
+    throw new AgentStorageError(
+      "invalid_state",
+      `[${prefix}] Agent thread '${create.threadId}' checkpoint head changed.`
+    )
+  }
+  if (latest && create.summarizedThroughSeq <= latest.summarizedThroughSeq) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint boundary must advance beyond sequence ${latest.summarizedThroughSeq}.`
+    )
+  }
+  if (!firstRetained || firstRetained.seq !== create.summarizedThroughSeq + 1) {
+    throw new AgentStorageError(
+      "invalid_state",
+      `[${prefix}] Agent context checkpoint boundary does not align with stored thread messages.`
+    )
+  }
+  if (firstRetained.role !== "user") {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[${prefix}] Agent context checkpoint must retain a complete turn beginning with a user message.`
+    )
+  }
+}
+
+/** Validate the mutable anchors again before returning an idempotently created checkpoint. */
+export function assertAgentContextCheckpointReplayState(input: {
+  readonly create: CreateAgentContextCheckpointInput
+  readonly existing: AgentContextCheckpointRecord
+  readonly latest: AgentContextCheckpointRecord | null
+  readonly headSeq: number
+  readonly prefix?: string
+}): void {
+  const prefix = input.prefix ?? "Sixb"
+  if (input.headSeq !== input.create.expectedHeadSeq) {
+    throw new AgentStorageError(
+      "invalid_state",
+      `[${prefix}] Agent thread '${input.create.threadId}' message head changed from ${input.create.expectedHeadSeq} to ${input.headSeq}.`
+    )
+  }
+  if (input.latest?.id !== input.existing.id) {
+    throw new AgentStorageError(
+      "invalid_state",
+      `[${prefix}] Agent thread '${input.create.threadId}' checkpoint head changed after '${input.existing.id}'.`
+    )
+  }
+}
+
+/** Compare the durable semantic payload; delivery token and generated timestamp are not content. */
+export function agentContextCheckpointMatchesCreateInput(
+  record: AgentContextCheckpointRecord,
+  input: CreateAgentContextCheckpointInput
+): boolean {
+  return (
+    record.id === input.id &&
+    record.projectId === input.projectId &&
+    record.threadId === input.threadId &&
+    record.createdByRunId === input.createdByRunId &&
+    (record.previousCheckpointId ?? null) === input.expectedPreviousCheckpointId &&
+    record.reason === input.reason &&
+    record.summary === input.summary &&
+    record.summaryFormatVersion === input.summaryFormatVersion &&
+    record.summarizedThroughSeq === input.summarizedThroughSeq &&
+    record.observedHeadSeq === input.observedHeadSeq &&
+    record.estimatedInputTokensBefore === input.estimatedInputTokensBefore &&
+    record.estimatedInputTokensAfter === input.estimatedInputTokensAfter &&
+    record.summaryModelId === input.summaryModelId
+  )
+}

package/src/storage/agents/types.ts

@@ -69,15 +69,17 @@ export const AGENT_RUN_FAILURE_CODES = [
 export type AgentRunFailureCode = (typeof AGENT_RUN_FAILURE_CODES)[number]
 
 /**
- * Why a run ended — our own SDK-independent vocabulary (it mirrors the AI SDK unified finish
- * reasons), so reads are typed and exhaustive without core depending on `ai`. `other`/`unknown` are
- * catch-alls: a provider value we don't recognise still records *that* the run ended.
+ * Why a run ended — our own SDK-independent vocabulary. It includes the AI SDK's unified finish
+ * reasons plus platform-level endings such as `timeout`, so reads are typed and exhaustive without
+ * core depending on `ai`. `other`/`unknown` are catch-alls: an unrecognised provider value still
+ * records *that* the run ended.
  */
 export const AGENT_RUN_FINISH_REASONS = [
   "stop",
   "length",
   "content-filter",
   "tool-calls",
+  "timeout",
   "error",
   "other",
   "unknown",
@@ -287,9 +289,17 @@ export interface AppendAgentMessageInput extends AgentMessage {
   readonly completedAt?: Date
 }
 
+export interface DeleteAgentMessagesByRunInput {
+  readonly projectId: string
+  readonly threadId: string
+  readonly runId: string
+}
+
 export interface ListAgentMessagesInput {
   readonly projectId: string
   readonly threadId: string
+  /** Return only messages whose per-thread sequence is greater than this retained boundary. */
+  readonly afterSeq?: number
   readonly roles?: readonly AgentMessageRole[]
   readonly limit?: number
   readonly offset?: number
@@ -302,6 +312,55 @@ export interface ListAgentMessagesResult {
   readonly total: number
 }
 
+// ── agent_context_checkpoints — append-only model-context boundaries ──────────────────────────
+
+export type AgentContextCheckpointReason = "threshold" | "overflow"
+
+/**
+ * A durable summary boundary used only when projecting a thread into model context.
+ *
+ * Checkpoints never replace or mutate transcript messages. Normal thread reads remain authoritative
+ * and complete; the worker reads the latest checkpoint and only the retained message tail.
+ */
+export interface AgentContextCheckpointRecord {
+  readonly id: string
+  readonly projectId: string
+  readonly threadId: string
+  readonly createdByRunId: string
+  readonly previousCheckpointId?: string
+  readonly reason: AgentContextCheckpointReason
+  readonly summary: string
+  readonly summaryFormatVersion: 1
+  readonly summarizedThroughSeq: number
+  readonly observedHeadSeq: number
+  readonly estimatedInputTokensBefore: number
+  readonly estimatedInputTokensAfter: number
+  readonly summaryModelId: string
+  readonly createdAt: Date
+}
+
+export interface CreateAgentContextCheckpointInput {
+  readonly id: string
+  readonly projectId: string
+  readonly threadId: string
+  readonly createdByRunId: string
+  /** Compare-and-swap anchor. `null` means the thread must not have a prior checkpoint. */
+  readonly expectedPreviousCheckpointId: string | null
+  /** Compare-and-swap anchor for the complete transcript observed by the summarizer. */
+  readonly expectedHeadSeq: number
+  /** Current delivery token for `createdByRunId`; stale redeliveries must not write. */
+  readonly executionToken: string
+  readonly reason: AgentContextCheckpointReason
+  readonly summary: string
+  readonly summaryFormatVersion: 1
+  readonly summarizedThroughSeq: number
+  readonly observedHeadSeq: number
+  readonly estimatedInputTokensBefore: number
+  readonly estimatedInputTokensAfter: number
+  readonly summaryModelId: string
+  readonly createdAt?: Date
+}
+
 // ── Store ───────────────────────────────────────────────────────────────────────────────────────
 
 export interface AgentThreadStore {
@@ -337,12 +396,32 @@ export interface AgentRunStore {
 export interface AgentMessageStore {
   /** Insert a message (its `parts` are the canonical content) and bump thread stats. */
   append(input: AppendAgentMessageInput): Promise<AgentMessageRecord>
+  /** Delete every message produced by one run and repair the thread's message stats. */
+  deleteByRunId(input: DeleteAgentMessagesByRunInput): Promise<number>
   getById(params: { projectId: string; id: string }): Promise<AgentMessageRecord | null>
   list(input: ListAgentMessagesInput): Promise<ListAgentMessagesResult>
 }
 
+export interface AgentContextCheckpointStore {
+  /**
+   * Append one checkpoint after atomically validating run ownership and both transcript anchors.
+   * Repeating the same payload for the same creating run is idempotent.
+   */
+  create(input: CreateAgentContextCheckpointInput): Promise<AgentContextCheckpointRecord>
+  /** Return checkpoints created by the requested runs, in first-occurrence input order. */
+  getByRunIds(input: {
+    readonly projectId: string
+    readonly runIds: readonly string[]
+  }): Promise<readonly AgentContextCheckpointRecord[]>
+  getLatest(input: {
+    readonly projectId: string
+    readonly threadId: string
+  }): Promise<AgentContextCheckpointRecord | null>
+}
+
 export interface AgentStorage {
   readonly threads: AgentThreadStore
   readonly runs: AgentRunStore
   readonly messages: AgentMessageStore
+  readonly checkpoints: AgentContextCheckpointStore
 }