Threads Schema
Conversation containers owned by the Convex Agent component
Ownership
Threads are owned and persisted by the Convex Agent component in its own database namespace — not the root app schema.
The root authSessions table references the document agent thread via
agentThreadId. blockAgentThreads binds a working-document block to its
separate Block Goldie thread. To read either transcript, query the Agent
component using its ID (e.g. components.agent.threads.getThread).
blockAgentThreads has business key prefix bat_, documentKey, blockKey,
and threadId, indexed uniquely by (documentKey, blockKey). It is a binding,
not a messages table: the Agent component remains the sole transcript owner.
blockAgentTurnEvents is the append-only typed-turn audit. It records the
fresh block agenda and structured outcome for evidence and stale-safe proposal
recovery. It is not a transcript or proposal queue and is indexed by the bound
document/block pair and component thread.
Fields
These fields reflect the Agent component's thread model:
| Field | Type | Description |
|---|---|---|
_id | string | Convex document ID (the agentThreadId stored in sessions) |
title | string | Human-readable label |
summary | string | Short summary of the conversation state |
status | "active" | "closed" | Conversation lifecycle state |
Notes
- Do not define a
threadstable in the root app schema — the Agent component manages its own storage. - Access thread data via queries that delegate to
components.agentand check the caller's access first (the/agent-devplayground that read any thread by id was removed, owner ruling 2026-09-25).