@sixb/core 0.0.1

package/src/testing/agent-storage-contract.ts

@@ -0,0 +1,824 @@
+import { describe, expect, test } from "bun:test"
+import { AGENT_MESSAGE_CONTENT_VERSION } from "../agents/message"
+import type { Principal } from "../auth"
+import {
+  type AgentRunExecution,
+  type AgentStorage,
+  AgentStorageError,
+  type AgentStorageErrorCode,
+  type CreateAgentRunInput,
+  type CreateAgentThreadInput,
+  type StartAgentRunInput,
+} from "../storage/agents"
+
+export interface AgentStorageContractSuiteOptions<TStorage extends AgentStorage = AgentStorage> {
+  /** Factory that produces a fresh `AgentStorage` instance for each test case. */
+  readonly createStorage: () => TStorage | Promise<TStorage>
+  /** Optional cleanup invoked after every test case. */
+  readonly teardown?: (storage: TStorage) => void | Promise<void>
+}
+
+const projectId = "project-a"
+const otherProjectId = "project-b"
+const owner: Principal = { type: "user", id: "usr_1" }
+const serviceAccount: Extract<Principal, { readonly type: "serviceAccount" }> = {
+  type: "serviceAccount",
+  id: "svc_agent_sales",
+}
+
+function at(value: string): Date {
+  return new Date(value)
+}
+
+async function expectAgentError(
+  promise: Promise<unknown>,
+  code: AgentStorageErrorCode
+): Promise<void> {
+  await expect(promise).rejects.toBeInstanceOf(AgentStorageError)
+  await expect(promise).rejects.toMatchObject({ code })
+}
+
+function threadInput(overrides: Partial<CreateAgentThreadInput> = {}): CreateAgentThreadInput {
+  return {
+    id: "thr_1",
+    projectId,
+    agentId: "sales",
+    ownerPrincipal: owner,
+    createdAt: at("2026-06-23T10:00:00.000Z"),
+    ...overrides,
+  }
+}
+
+function execution(
+  token: string,
+  queueLeaseExpiresAt = at("2026-06-23T10:05:00.000Z")
+): AgentRunExecution {
+  return { token, queueLeaseExpiresAt }
+}
+
+type TestRunInput = CreateAgentRunInput &
+  Omit<StartAgentRunInput, "id" | "projectId"> & {
+    readonly id: string
+    readonly projectId: string
+  }
+
+function runInput(overrides: Partial<TestRunInput> = {}): TestRunInput {
+  return {
+    id: "run_1",
+    projectId,
+    threadId: "thr_1",
+    agentId: "sales",
+    triggerMessageId: "msg_user_1",
+    requestedByPrincipal: owner,
+    execution: execution("exec_1"),
+    createdAt: at("2026-06-23T10:00:10.000Z"),
+    ...overrides,
+  }
+}
+
+async function createAndStartRun(
+  storage: AgentStorage,
+  input: TestRunInput
+): Promise<Awaited<ReturnType<AgentStorage["runs"]["start"]>>> {
+  await storage.runs.create(input)
+  return storage.runs.start({
+    id: input.id,
+    projectId: input.projectId,
+    executionPrincipal: input.executionPrincipal,
+    modelId: input.modelId,
+    execution: input.execution,
+    startedAt: input.startedAt,
+  })
+}
+
+/**
+ * Runs the shared `AgentStorage` contract against any storage implementation.
+ *
+ * This is the storage-independent specification for Sixb agent persistence: thread lifecycle and
+ * project isolation, single-flight run reservation, execution reclaim, run finalization with
+ * execution metadata, and message append with thread-stats bookkeeping.
+ */
+export function runAgentStorageContractSuite<TStorage extends AgentStorage>(
+  label: string,
+  options: AgentStorageContractSuiteOptions<TStorage>
+): void {
+  const withStorage = async (body: (storage: TStorage) => Promise<void>): Promise<void> => {
+    const storage = await options.createStorage()
+    try {
+      await body(storage)
+    } finally {
+      await options.teardown?.(storage)
+    }
+  }
+
+  describe(label, () => {
+    // ── threads ───────────────────────────────────────────────────────────────────────────────
+
+    test("creates threads, isolates projects, and rejects duplicate ids", async () => {
+      await withStorage(async (storage) => {
+        const thread = await storage.threads.create(threadInput({ title: "Q3 pipeline" }))
+        expect(thread).toMatchObject({
+          id: "thr_1",
+          agentId: "sales",
+          title: "Q3 pipeline",
+          status: "active",
+          activeRunId: null,
+          messageCount: 0,
+        })
+        expect(thread.ownerPrincipal).toEqual(owner)
+
+        await expectAgentError(storage.threads.create(threadInput()), "duplicate_id")
+
+        // Same id under a different project is allowed and isolated.
+        await expect(
+          storage.threads.create(threadInput({ projectId: otherProjectId }))
+        ).resolves.toMatchObject({ projectId: otherProjectId })
+        await expect(storage.threads.getById({ projectId, id: "thr_1" })).resolves.toMatchObject({
+          title: "Q3 pipeline",
+        })
+        await expect(
+          storage.threads.getById({ projectId: "nope", id: "thr_1" })
+        ).resolves.toBeNull()
+      })
+    })
+
+    test("lists threads with filters, ordering, and pagination", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(
+          threadInput({ id: "thr_a", agentId: "sales", createdAt: at("2026-06-23T10:00:00.000Z") })
+        )
+        await storage.threads.create(
+          threadInput({
+            id: "thr_b",
+            agentId: "support",
+            createdAt: at("2026-06-23T10:01:00.000Z"),
+          })
+        )
+        await storage.threads.create(
+          threadInput({
+            id: "thr_c",
+            agentId: "sales",
+            status: "archived",
+            createdAt: at("2026-06-23T10:02:00.000Z"),
+          })
+        )
+        await storage.threads.create(threadInput({ id: "thr_other", projectId: otherProjectId }))
+
+        const all = await storage.threads.list({ projectId, order: "asc" })
+        expect(all.threads.map((thread) => thread.id)).toEqual(["thr_a", "thr_b", "thr_c"])
+        expect(all.total).toBe(3)
+        expect(all.hasMore).toBe(false)
+
+        const sales = await storage.threads.list({ projectId, agentId: "sales", order: "asc" })
+        expect(sales.threads.map((thread) => thread.id)).toEqual(["thr_a", "thr_c"])
+
+        const visibleAgents = await storage.threads.list({
+          projectId,
+          agentIds: ["support"],
+          order: "asc",
+        })
+        expect(visibleAgents.threads.map((thread) => thread.id)).toEqual(["thr_b"])
+
+        const salesVisibleAgents = await storage.threads.list({
+          projectId,
+          agentId: "sales",
+          agentIds: ["support"],
+          order: "asc",
+        })
+        expect(salesVisibleAgents.threads).toEqual([])
+        expect(salesVisibleAgents.total).toBe(0)
+
+        const active = await storage.threads.list({ projectId, statuses: ["active"], order: "asc" })
+        expect(active.threads.map((thread) => thread.id)).toEqual(["thr_a", "thr_b"])
+
+        const firstPage = await storage.threads.list({ projectId, order: "asc", limit: 2 })
+        expect(firstPage.threads.map((thread) => thread.id)).toEqual(["thr_a", "thr_b"])
+        expect(firstPage.hasMore).toBe(true)
+        expect(firstPage.total).toBe(3)
+
+        const secondPage = await storage.threads.list({
+          projectId,
+          order: "asc",
+          limit: 2,
+          offset: 2,
+        })
+        expect(secondPage.threads.map((thread) => thread.id)).toEqual(["thr_c"])
+        expect(secondPage.hasMore).toBe(false)
+      })
+    })
+
+    // ── durable queued runs ────────────────────────────────────────────────────────────────────
+
+    test("creates a queued run before execution and claims the thread", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+
+        const queued = await storage.runs.create(runInput({ id: "run_1" }))
+        expect(queued).toMatchObject({ status: "queued", attempt: 0, threadId: "thr_1" })
+        expect(queued.execution).toBeUndefined()
+        expect(queued.startedAt).toBeUndefined()
+        await expect(storage.runs.list({ projectId, statuses: ["queued"] })).resolves.toMatchObject(
+          {
+            runs: [{ id: "run_1", status: "queued" }],
+            total: 1,
+          }
+        )
+        await expect(storage.threads.getById({ projectId, id: "thr_1" })).resolves.toMatchObject({
+          activeRunId: "run_1",
+        })
+
+        const started = await storage.runs.start({
+          projectId,
+          id: "run_1",
+          executionPrincipal: serviceAccount,
+          modelId: "test-model",
+          execution: execution("exec_1"),
+          startedAt: at("2026-06-23T10:01:00.000Z"),
+        })
+        expect(started).toMatchObject({ status: "running", attempt: 1, modelId: "test-model" })
+        expect(started.execution).toEqual(execution("exec_1"))
+        expect(started.executionPrincipal).toEqual(serviceAccount)
+        expect(started.startedAt?.toISOString()).toBe("2026-06-23T10:01:00.000Z")
+      })
+    })
+
+    test("finishes a queued run and releases the thread", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+        await storage.runs.create(runInput({ id: "run_1" }))
+
+        const cancelled = await storage.runs.finishQueued({
+          projectId,
+          id: "run_1",
+          status: "cancelled",
+          error: "Cancelled before execution",
+          completedAt: at("2026-06-23T10:01:00.000Z"),
+        })
+        expect(cancelled).toMatchObject({
+          status: "cancelled",
+          attempt: 0,
+          error: "Cancelled before execution",
+        })
+        await expect(storage.threads.getById({ projectId, id: "thr_1" })).resolves.toMatchObject({
+          activeRunId: null,
+        })
+        await expectAgentError(
+          storage.runs.start({
+            projectId,
+            id: "run_1",
+            execution: execution("exec_1"),
+          }),
+          "invalid_state"
+        )
+
+        await storage.runs.create(runInput({ id: "run_2" }))
+        await expect(
+          storage.runs.finishQueued({
+            projectId,
+            id: "run_2",
+            status: "failed",
+            error: "Agent is unavailable",
+          })
+        ).resolves.toMatchObject({ status: "failed", attempt: 0, error: "Agent is unavailable" })
+      })
+    })
+
+    // ── single-flight execution ─────────────────────────────────────────────────────────────────
+
+    test("allows a single active run per thread", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+
+        const run = await createAndStartRun(storage, runInput({ id: "run_1" }))
+        expect(run).toMatchObject({ status: "running", attempt: 1, threadId: "thr_1" })
+        expect(run.requestedByPrincipal).toEqual(owner)
+        expect(run.execution?.token).toBe("exec_1")
+        await expect(storage.threads.getById({ projectId, id: "thr_1" })).resolves.toMatchObject({
+          activeRunId: "run_1",
+        })
+
+        await expectAgentError(
+          createAndStartRun(storage, runInput({ id: "run_2", execution: execution("exec_2") })),
+          "active_run_exists"
+        )
+
+        // Reservation against an unknown thread / duplicate run id.
+        await expectAgentError(
+          createAndStartRun(storage, runInput({ id: "run_x", threadId: "ghost" })),
+          "thread_not_found"
+        )
+      })
+    })
+
+    test("never lets two concurrent queued runs both claim one thread", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+
+        const results = await Promise.allSettled([
+          createAndStartRun(storage, runInput({ id: "run_a", execution: execution("exec_a") })),
+          createAndStartRun(storage, runInput({ id: "run_b", execution: execution("exec_b") })),
+        ])
+        const fulfilled = results.filter((result) => result.status === "fulfilled")
+        const rejected = results.filter(
+          (result): result is PromiseRejectedResult => result.status === "rejected"
+        )
+        expect(fulfilled).toHaveLength(1)
+        expect(rejected).toHaveLength(1)
+        expect(rejected[0].reason).toBeInstanceOf(AgentStorageError)
+        expect(rejected[0].reason.code).toBe("active_run_exists")
+      })
+    })
+
+    // ── execution reclaim ───────────────────────────────────────────────────────────────────────
+
+    test("reclaim rotates the execution token and bumps the attempt", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+        await createAndStartRun(storage, runInput({ id: "run_1" }))
+
+        const reclaimed = await storage.runs.reclaim({
+          projectId,
+          id: "run_1",
+          execution: execution("exec_2"),
+        })
+        expect(reclaimed).toMatchObject({ status: "running", attempt: 2 })
+        expect(reclaimed.execution?.token).toBe("exec_2")
+
+        await expectAgentError(
+          storage.runs.finish({
+            projectId,
+            id: "run_1",
+            executionToken: "exec_1",
+            status: "succeeded",
+          }),
+          "execution_lost"
+        )
+      })
+    })
+
+    test("projects confirmed queue ownership monotonically and fences stale executions", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+        await createAndStartRun(
+          storage,
+          runInput({
+            id: "run_1",
+            execution: execution("exec_1", at("2026-06-23T10:02:00.000Z")),
+          })
+        )
+
+        const confirmed = await storage.runs.confirmExecutionOwnership({
+          projectId,
+          id: "run_1",
+          executionToken: "exec_1",
+          queueLeaseExpiresAt: at("2026-06-23T10:03:00.000Z"),
+        })
+        expect(confirmed.execution?.queueLeaseExpiresAt.toISOString()).toBe(
+          "2026-06-23T10:03:00.000Z"
+        )
+
+        const older = await storage.runs.confirmExecutionOwnership({
+          projectId,
+          id: "run_1",
+          executionToken: "exec_1",
+          queueLeaseExpiresAt: at("2026-06-23T10:02:30.000Z"),
+        })
+        expect(older.execution?.queueLeaseExpiresAt.toISOString()).toBe("2026-06-23T10:03:00.000Z")
+
+        await storage.runs.reclaim({
+          projectId,
+          id: "run_1",
+          execution: execution("exec_2", at("2026-06-23T10:04:00.000Z")),
+        })
+        await expectAgentError(
+          storage.runs.confirmExecutionOwnership({
+            projectId,
+            id: "run_1",
+            executionToken: "exec_1",
+            queueLeaseExpiresAt: at("2026-06-23T10:05:00.000Z"),
+          }),
+          "execution_lost"
+        )
+      })
+    })
+
+    test("does not alias stored run records to callers", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+        const run = await createAndStartRun(storage, runInput({ id: "run_1" }))
+
+        const mutableExecution = run.execution as
+          | { token: string; queueLeaseExpiresAt: Date }
+          | undefined
+        if (mutableExecution) {
+          mutableExecution.token = "mutated"
+          mutableExecution.queueLeaseExpiresAt.setTime(0)
+        }
+        const reread = await storage.runs.getById({ projectId, id: "run_1" })
+        expect(reread?.execution?.token).toBe("exec_1")
+      })
+    })
+
+    // ── finalization ────────────────────────────────────────────────────────────────────────────
+
+    test("releasing a run only clears its own thread's active pointer", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput({ id: "thr_1" }))
+        await storage.threads.create(threadInput({ id: "thr_2" }))
+        await createAndStartRun(storage, runInput({ id: "run_1", threadId: "thr_1" }))
+        await createAndStartRun(
+          storage,
+          runInput({
+            id: "run_2",
+            threadId: "thr_2",
+            execution: execution("exec_2"),
+          })
+        )
+
+        await storage.runs.finish({
+          projectId,
+          id: "run_1",
+          executionToken: "exec_1",
+          status: "succeeded",
+        })
+
+        await expect(storage.threads.getById({ projectId, id: "thr_1" })).resolves.toMatchObject({
+          activeRunId: null,
+        })
+        // thr_2's pointer is untouched — the release is scoped to the run's own thread + matching id.
+        await expect(storage.threads.getById({ projectId, id: "thr_2" })).resolves.toMatchObject({
+          activeRunId: "run_2",
+        })
+      })
+    })
+
+    test("finishes a run, records execution metadata, and releases the thread", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+        await createAndStartRun(storage, runInput({ id: "run_1" }))
+
+        const finished = await storage.runs.finish({
+          projectId,
+          id: "run_1",
+          executionToken: "exec_1",
+          status: "succeeded",
+          modelId: "claude-haiku-4-5",
+          finishReason: "stop",
+          usage: { inputTokens: 120, outputTokens: 80, totalTokens: 200 },
+          diagnostics: [
+            {
+              code: "output_file_too_large",
+              severity: "warning",
+              scope: "output",
+              path: "reports/full.csv",
+              message: "This generated file was skipped.",
+            },
+          ],
+          completedAt: at("2026-06-23T10:07:00.000Z"),
+        })
+        expect(finished).toMatchObject({
+          status: "succeeded",
+          modelId: "claude-haiku-4-5",
+          finishReason: "stop",
+        })
+        expect(finished.usage).toEqual({ inputTokens: 120, outputTokens: 80, totalTokens: 200 })
+        expect(finished.diagnostics).toEqual([
+          {
+            code: "output_file_too_large",
+            severity: "warning",
+            scope: "output",
+            path: "reports/full.csv",
+            message: "This generated file was skipped.",
+          },
+        ])
+        await expect(
+          storage.runs.getByIds({ projectId, ids: ["run_1", "missing", "run_1"] })
+        ).resolves.toEqual([finished])
+        expect(finished.execution).toBeUndefined()
+        expect(finished.completedAt?.toISOString()).toBe("2026-06-23T10:07:00.000Z")
+
+        // The thread is released → a new queued run can be created and started.
+        await expect(storage.threads.getById({ projectId, id: "thr_1" })).resolves.toMatchObject({
+          activeRunId: null,
+        })
+        await expect(
+          createAndStartRun(storage, runInput({ id: "run_2", execution: execution("exec_2") }))
+        ).resolves.toMatchObject({ status: "running" })
+      })
+    })
+
+    test("records failure detail and rejects a non-running run or stale execution", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+        await createAndStartRun(storage, runInput({ id: "run_1" }))
+
+        await expectAgentError(
+          storage.runs.finish({
+            projectId,
+            id: "run_1",
+            executionToken: "wrong",
+            status: "failed",
+            error: "boom",
+          }),
+          "execution_lost"
+        )
+
+        const failed = await storage.runs.finish({
+          projectId,
+          id: "run_1",
+          executionToken: "exec_1",
+          status: "failed",
+          error: "ProviderError: boom",
+          completedAt: at("2026-06-23T10:08:00.000Z"),
+        })
+        expect(failed.status).toBe("failed")
+        expect(failed.error).toBe("ProviderError: boom")
+
+        // Already terminal → cannot finish again.
+        await expectAgentError(
+          storage.runs.finish({
+            projectId,
+            id: "run_1",
+            executionToken: "exec_1",
+            status: "succeeded",
+          }),
+          "invalid_state"
+        )
+      })
+    })
+
+    test("lists runs with thread, status, and ordering filters", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput({ id: "thr_1" }))
+        await storage.threads.create(threadInput({ id: "thr_2" }))
+
+        await createAndStartRun(
+          storage,
+          runInput({
+            id: "run_1",
+            threadId: "thr_1",
+            createdAt: at("2026-06-23T10:00:00.000Z"),
+          })
+        )
+        await storage.runs.finish({
+          projectId,
+          id: "run_1",
+          executionToken: "exec_1",
+          status: "succeeded",
+        })
+        await createAndStartRun(
+          storage,
+          runInput({
+            id: "run_2",
+            threadId: "thr_1",
+            execution: execution("exec_2"),
+            createdAt: at("2026-06-23T10:30:00.000Z"),
+          })
+        )
+        await createAndStartRun(
+          storage,
+          runInput({
+            id: "run_3",
+            threadId: "thr_2",
+            execution: execution("exec_3"),
+            createdAt: at("2026-06-23T10:45:00.000Z"),
+          })
+        )
+
+        const forThread1 = await storage.runs.list({ projectId, threadId: "thr_1", order: "asc" })
+        expect(forThread1.runs.map((run) => run.id)).toEqual(["run_1", "run_2"])
+
+        const running = await storage.runs.list({ projectId, statuses: ["running"], order: "asc" })
+        expect(running.runs.map((run) => run.id)).toEqual(["run_2", "run_3"])
+
+        const all = await storage.runs.list({ projectId, order: "desc" })
+        expect(all.runs.map((run) => run.id)).toEqual(["run_3", "run_2", "run_1"])
+      })
+    })
+
+    test("filters queued runs by their effective created timestamp", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput({ id: "thr_before" }))
+        await storage.threads.create(threadInput({ id: "thr_inside" }))
+        await storage.threads.create(threadInput({ id: "thr_after" }))
+
+        await storage.runs.create(
+          runInput({
+            id: "run_before",
+            threadId: "thr_before",
+            createdAt: at("2026-06-23T10:00:00.000Z"),
+          })
+        )
+        await storage.runs.create(
+          runInput({
+            id: "run_inside",
+            threadId: "thr_inside",
+            createdAt: at("2026-06-23T11:00:00.000Z"),
+          })
+        )
+        await storage.runs.create(
+          runInput({
+            id: "run_after",
+            threadId: "thr_after",
+            createdAt: at("2026-06-23T12:00:00.000Z"),
+          })
+        )
+
+        const result = await storage.runs.list({
+          projectId,
+          statuses: ["queued"],
+          startedAfter: at("2026-06-23T10:30:00.000Z"),
+          startedBefore: at("2026-06-23T11:30:00.000Z"),
+          order: "asc",
+        })
+        expect(result.runs.map((run) => run.id)).toEqual(["run_inside"])
+        expect(result.total).toBe(1)
+        expect(result.hasMore).toBe(false)
+      })
+    })
+
+    // ── messages ──────────────────────────────────────────────────────────────────────────────
+
+    test("appends messages, assigns seq, and bumps thread stats", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+
+        const userMessage = await storage.messages.append({
+          id: "msg_user_1",
+          projectId,
+          threadId: "thr_1",
+          runId: null,
+          role: "user",
+          parts: [{ type: "text", text: "Hello agent" }],
+          authorPrincipal: owner,
+          createdAt: at("2026-06-23T10:00:30.000Z"),
+        })
+        expect(userMessage).toMatchObject({
+          seq: 1,
+          role: "user",
+          runId: null,
+          contentVersion: AGENT_MESSAGE_CONTENT_VERSION,
+        })
+        expect(userMessage.authorPrincipal).toEqual(owner)
+
+        const run = await createAndStartRun(
+          storage,
+          runInput({
+            id: "run_1",
+            executionPrincipal: serviceAccount,
+          })
+        )
+        expect(run.executionPrincipal).toEqual(serviceAccount)
+        const assistantMessage = await storage.messages.append({
+          id: "msg_asst_1",
+          projectId,
+          threadId: "thr_1",
+          runId: "run_1",
+          role: "assistant",
+          authorPrincipal: serviceAccount,
+          parts: [
+            { type: "reasoning", text: "thinking about it" },
+            {
+              type: "tool-call",
+              toolCallId: "call_1",
+              toolName: "bash",
+              input: { cmd: "ls" },
+              state: "output-available",
+              output: "file.txt",
+            },
+            { type: "text", text: "Here is the result" },
+          ],
+          createdAt: at("2026-06-23T10:01:00.000Z"),
+        })
+        expect(assistantMessage).toMatchObject({ seq: 2, role: "assistant", runId: "run_1" })
+        expect(assistantMessage.authorPrincipal).toEqual(serviceAccount)
+
+        const thread = await storage.threads.getById({ projectId, id: "thr_1" })
+        expect(thread).toMatchObject({ messageCount: 2 })
+        expect(thread?.lastMessageAt?.toISOString()).toBe("2026-06-23T10:01:00.000Z")
+
+        // The message's `parts` are the canonical content and round-trip verbatim through storage.
+        const stored = await storage.messages.getById({ projectId, id: "msg_asst_1" })
+        expect(stored?.seq).toBe(2)
+        expect(stored?.parts).toEqual([
+          { type: "reasoning", text: "thinking about it" },
+          {
+            type: "tool-call",
+            toolCallId: "call_1",
+            toolName: "bash",
+            input: { cmd: "ls" },
+            state: "output-available",
+            output: "file.txt",
+          },
+          { type: "text", text: "Here is the result" },
+        ])
+      })
+    })
+
+    test("lists messages with role filter, ordering, and pagination", async () => {
+      await withStorage(async (storage) => {
+        await storage.threads.create(threadInput())
+        await storage.messages.append({
+          id: "m1",
+          projectId,
+          threadId: "thr_1",
+          runId: null,
+          role: "user",
+          parts: [{ type: "text", text: "one" }],
+          createdAt: at("2026-06-23T10:00:00.000Z"),
+        })
+        await createAndStartRun(storage, runInput({ id: "run_1" }))
+        await storage.messages.append({
+          id: "m2",
+          projectId,
+          threadId: "thr_1",
+          runId: "run_1",
+          role: "assistant",
+          parts: [{ type: "text", text: "two" }],
+          createdAt: at("2026-06-23T10:01:00.000Z"),
+        })
+        await storage.messages.append({
+          id: "m3",
+          projectId,
+          threadId: "thr_1",
+          runId: null,
+          role: "user",
+          parts: [{ type: "text", text: "three" }],
+          createdAt: at("2026-06-23T10:02:00.000Z"),
+        })
+
+        const asc = await storage.messages.list({ projectId, threadId: "thr_1", order: "asc" })
+        expect(asc.messages.map((message) => message.id)).toEqual(["m1", "m2", "m3"])
+        expect(asc.total).toBe(3)
+
+        const desc = await storage.messages.list({ projectId, threadId: "thr_1", order: "desc" })
+        expect(desc.messages.map((message) => message.id)).toEqual(["m3", "m2", "m1"])
+
+        const users = await storage.messages.list({
+          projectId,
+          threadId: "thr_1",
+          roles: ["user"],
+          order: "asc",
+        })
+        expect(users.messages.map((message) => message.id)).toEqual(["m1", "m3"])
+
+        const firstPage = await storage.messages.list({
+          projectId,
+          threadId: "thr_1",
+          order: "asc",
+          limit: 2,
+        })
+        expect(firstPage.messages.map((message) => message.id)).toEqual(["m1", "m2"])
+        expect(firstPage.hasMore).toBe(true)
+      })
+    })
+
+    test("rejects appends to missing threads, duplicate messages, and unknown runs", async () => {
+      await withStorage(async (storage) => {
+        await expectAgentError(
+          storage.messages.append({
+            id: "m1",
+            projectId,
+            threadId: "ghost",
+            runId: null,
+            role: "user",
+            parts: [{ type: "text", text: "hi" }],
+          }),
+          "thread_not_found"
+        )
+
+        await storage.threads.create(threadInput())
+        await storage.messages.append({
+          id: "m1",
+          projectId,
+          threadId: "thr_1",
+          runId: null,
+          role: "user",
+          parts: [{ type: "text", text: "hi" }],
+        })
+        await expectAgentError(
+          storage.messages.append({
+            id: "m1",
+            projectId,
+            threadId: "thr_1",
+            runId: null,
+            role: "user",
+            parts: [{ type: "text", text: "dup" }],
+          }),
+          "duplicate_id"
+        )
+        await expectAgentError(
+          storage.messages.append({
+            id: "m2",
+            projectId,
+            threadId: "thr_1",
+            runId: "ghost-run",
+            role: "assistant",
+            parts: [{ type: "text", text: "hi" }],
+          }),
+          "run_not_found"
+        )
+      })
+    })
+  })
+}