Store Claude subagent identity facts in indexed journal columns

Agent rows record their producer, tool-call alias and attempt beside the
row, so an acquisition snapshot reads aliases, attempts and the roster
without decoding bodies. The projection version bump reconverts chats.
This commit is contained in:
Brennan Benson
2026-11-08 00:13:38 -08:00
parent e45654e3ac
commit 5a099a6733
11 changed files with 228 additions and 23 deletions
@@ -1,7 +1,7 @@
import type { AgentJournalProducerLinkage } from '../../shared/agent-session/journal/agent-session-journal-types'
import { namedSubagents } from '../../shared/native-chat/transcript/native-chat-subagent-items'
import type { StructuredAgentSessionLinkageJournal } from '../native-chat/agent-session-wire/journal-ingress/structured-agent-session-journal-views'
import { isBoundedClaudeTaskId } from './claude-background-task-tracker'
import { isBoundedClaudeTaskId } from './claude-background-task-frames'
type Reading = {
canonicalByToolUse: Map<string, string>
@@ -9,6 +9,48 @@ type Reading = {
subagents: Set<string>
}
/** The saved identity facts a Claude acquisition reads once, before translating. */
export type ClaudeJournaledIdentities = {
canonicalByToolUse: [toolUseId: string, agentId: string][]
attemptByAgent: [agentId: string, attempt: number][]
subagents: string[]
}
/** One row's contribution, stored beside it so a snapshot never decodes bodies. */
export function claudeAgentRowFacts({
agentId,
providerParentRef,
producerKind,
attempt
}: AgentJournalProducerLinkage): {
agentId: string
parentRef: string | null
attempt: number
} | null {
if (producerKind !== 'agent' || agentId === undefined) {
return null
}
// Provisional self-stamps do not establish aliases.
const aliases =
providerParentRef !== undefined &&
agentId !== providerParentRef &&
isBoundedClaudeTaskId(agentId) &&
isBoundedClaudeTaskId(providerParentRef)
return { agentId, parentRef: aliases ? providerParentRef : null, attempt: attempt ?? 1 }
}
/** Visit visible items in insertion order, as the memory journal does. */
export function readClaudeJournaledIdentities(
visit: StructuredAgentSessionLinkageJournal['visitItemsWithLinkage']
): ClaudeJournaledIdentities {
const reading = read({ visitItemsWithLinkage: visit })
return {
canonicalByToolUse: [...reading.canonicalByToolUse],
attemptByAgent: [...reading.attemptByAgent],
subagents: [...reading.subagents]
}
}
/** Cache per bound journal epoch; reads before binding must not populate the cache. */
export class ClaudeJournaledSubagents {
private journal: StructuredAgentSessionLinkageJournal | null = null
@@ -39,7 +81,9 @@ export class ClaudeJournaledSubagents {
}
}
function read(journal: StructuredAgentSessionLinkageJournal): Reading {
function read(
journal: Pick<StructuredAgentSessionLinkageJournal, 'visitItemsWithLinkage'>
): Reading {
const reading: Reading = {
canonicalByToolUse: new Map(),
attemptByAgent: new Map(),
@@ -56,24 +100,16 @@ function read(journal: StructuredAgentSessionLinkageJournal): Reading {
return reading
}
function readAgentRow(
reading: Reading,
{ agentId, providerParentRef, producerKind, attempt }: AgentJournalProducerLinkage
): void {
if (producerKind !== 'agent' || agentId === undefined) {
function readAgentRow(reading: Reading, linkage: AgentJournalProducerLinkage): void {
const facts = claudeAgentRowFacts(linkage)
if (!facts) {
return
}
reading.attemptByAgent.set(
agentId,
Math.max(attempt ?? 1, reading.attemptByAgent.get(agentId) ?? 1)
facts.agentId,
Math.max(facts.attempt, reading.attemptByAgent.get(facts.agentId) ?? 1)
)
// Provisional self-stamps do not establish aliases.
if (
providerParentRef !== undefined &&
agentId !== providerParentRef &&
isBoundedClaudeTaskId(agentId) &&
isBoundedClaudeTaskId(providerParentRef)
) {
reading.canonicalByToolUse.set(providerParentRef, agentId)
if (facts.parentRef !== null) {
reading.canonicalByToolUse.set(facts.parentRef, facts.agentId)
}
}
@@ -13,6 +13,10 @@ import type { JournalItemLinkageVisitor } from './journal-store-contracts'
import type { JournalReducerState } from './projection/journal-reducer'
import type { JournalItemEcho } from './projection/journal-item-echo'
import type { JournalThreadGoalSource } from './projection/journal-thread-goal-source'
import {
readClaudeJournaledIdentities,
type ClaudeJournaledIdentities
} from '../../claude/claude-subagent-journaled-identities'
import { readJournalInput, type JournalInputReader } from './journal-input-reads'
import { readJournalUsageLimitCut, readJournalOrcaStopCut } from './journal-status-cuts'
import type { NativeChatUsageLimitCut } from '../../../shared/native-chat/native-chat-usage-limit-cut'
@@ -84,6 +88,8 @@ export type AgentSessionJournalReads = {
messageOptions(clientMessageId: string): Promise<JournalMessageOptions>
continuationContext(): Promise<JournalContinuationContext>
threadGoalSource(): Promise<JournalThreadGoalSource>
/** Saved Claude aliases, attempts and roster, read once per acquisition. */
claudeIdentities(): Promise<ClaudeJournaledIdentities>
contextUsage(): Promise<AgentSessionContextUsage>
visitItems(filter: JournalItemFilter, visit: JournalItemLinkageVisitor): Promise<void>
}
@@ -105,6 +111,7 @@ type FoldedJournalReads = {
| 'orcaStopCut'
| 'statusState'
| 'statusIndicators'
| 'claudeIdentities'
>
]: (
...args: Parameters<AgentSessionJournalReads[K]>
@@ -198,6 +205,7 @@ export function foldedJournalReads(
}
}),
threadGoalSource: now(journal.threadGoalSource),
claudeIdentities: now(() => readClaudeJournaledIdentities(journal.visitItemsWithLinkage)),
contextUsage: now(journal.contextUsage),
visitItems: now((filter: JournalItemFilter, visit: JournalItemLinkageVisitor) => {
const kinds = new Set(filter.kinds)
@@ -0,0 +1,93 @@
import { mkdtemp, rm } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, expect, it } from 'vitest'
import type { AgentJournalItemBody } from '../../../shared/agent-session/journal/agent-session-journal-types'
import { claudeProviderHandle } from '../../../shared/agent-session/lifecycle/agent-session-provider-handle-encoding'
import { openStructuredAgentSessionSqlJournalDatabase } from '../../runtime/agent-session/structured-agent-session-journal-open'
import type { JournalSqlDatabase } from './database/journal-sql-database'
import { SqlAgentSessionJournal } from './journal-sql-store'
import {
journalSqlReaderPath,
journalSqlWorkerPath
} from './journal-sql-worker-bundle.test-fixture'
const roots: string[] = []
const databases: JournalSqlDatabase[] = []
afterEach(async () => {
await Promise.all(databases.splice(0).map((database) => database.close()))
await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
})
const text = (value: string): AgentJournalItemBody => ({
kind: 'message',
role: 'assistant',
blocks: [{ type: 'text', text: value }]
})
const thread = { kind: 'thread' as const }
it('snapshots saved Claude aliases, attempts and roster from indexed columns', async () => {
const root = await mkdtemp(join(tmpdir(), 'journal-sql-claude-identities-'))
roots.push(root)
const { journalDatabase } = await openStructuredAgentSessionSqlJournalDatabase({
stateDirectory: root,
writerPath: journalSqlWorkerPath(),
readerPath: journalSqlReaderPath(),
logger: { warn: () => {}, error: () => {} }
})
databases.push(journalDatabase)
const sql = await SqlAgentSessionJournal.open({
database: journalDatabase,
identity: {
sessionId: 'session',
workspaceId: 'workspace',
hostId: 'host',
agent: 'claude',
providerHandle: claudeProviderHandle('claude-session', null)
},
now: () => 100
})
const row = (id: string) => ({ provider: 'orca' as const, clientMessageId: id })
await sql.appendItem(
row('roster'),
{
kind: 'message',
role: 'assistant',
blocks: [{ type: 'subagent', id: 'agent-a', label: 'A', state: 'working', groupId: 'turn' }]
},
{ fence: 1, turnScope: thread }
)
await sql.appendItem(row('a1'), text('a'), {
fence: 1,
turnScope: thread,
agentId: 'agent-a',
providerParentRef: 'toolu_1',
producerKind: 'agent'
})
// A provisional self-stamp records an attempt but no alias.
await sql.appendItem(row('a3'), text('a again'), {
fence: 1,
turnScope: thread,
agentId: 'agent-a',
providerParentRef: 'agent-a',
producerKind: 'agent',
attempt: 3
})
// The later alias for the same tool call wins.
await sql.appendItem(row('b1'), text('b'), {
fence: 1,
turnScope: thread,
agentId: 'agent-b',
providerParentRef: 'toolu_1',
producerKind: 'agent'
})
expect(await sql.reads.claudeIdentities()).toEqual({
canonicalByToolUse: [['toolu_1', 'agent-b']],
attemptByAgent: expect.arrayContaining([
['agent-a', 3],
['agent-b', 1]
]),
subagents: ['agent-a']
})
})
@@ -0,0 +1,35 @@
import type { ClaudeJournaledIdentities } from '../../claude/claude-subagent-journaled-identities'
import type { JournalSqlScope } from './journal-sql-scope'
/** Read the derived columns only: the last alias per parent, the floored highest attempt, the roster. */
export function readJournalSqlClaudeIdentities(scope: JournalSqlScope): ClaudeJournaledIdentities {
const canonical = new Map<string, string>()
for (const row of scope.db
.prepare(`SELECT producer_parent_ref, producer_agent_id FROM journal_proj_items
WHERE session_id=? AND epoch=? AND producer_parent_ref IS NOT NULL AND hidden=0 ORDER BY ordinal`)
.all(...scope.prefix)) {
scope.examined(row)
canonical.set(String(row.producer_parent_ref), String(row.producer_agent_id))
}
const attempts: [string, number][] = []
for (const row of scope.db
.prepare(`SELECT producer_agent_id, MAX(producer_attempt) AS attempt FROM journal_proj_items
WHERE session_id=? AND epoch=? AND producer_agent_id IS NOT NULL AND hidden=0
GROUP BY producer_agent_id`)
.all(...scope.prefix)) {
scope.examined(row)
attempts.push([String(row.producer_agent_id), Math.max(1, Number(row.attempt))])
}
const subagents = new Set<string>()
for (const row of scope.db
.prepare(`SELECT subagent_names FROM journal_proj_items
WHERE session_id=? AND epoch=? AND subagent_names IS NOT NULL AND hidden=0 ORDER BY ordinal`)
.all(...scope.prefix)) {
scope.examined(row)
const names: { id: string }[] = JSON.parse(String(row.subagent_names))
for (const { id } of names) {
subagents.add(id)
}
}
return { canonicalByToolUse: [...canonical], attemptByAgent: attempts, subagents: [...subagents] }
}
@@ -21,6 +21,8 @@ import { JournalSqlReadValues } from './journal-sql-read-values'
import { readJournalSqlInput } from './journal-sql-input-reads'
import { agentJournalSubmissionKey } from '../../../shared/agent-session/journal/agent-session-journal-item-key'
import { currentAgentSessionThreadGoalSourceBySequence } from '../../../shared/agent-session/agent-session-thread-goal'
import type { ClaudeJournaledIdentities } from '../../claude/claude-subagent-journaled-identities'
import { readJournalSqlClaudeIdentities } from './journal-sql-claude-identities'
/** Item reads by type and position; each names the rows it decodes, as projection reads do. */
export type JournalSqlItemRead =
@@ -34,6 +36,7 @@ export type JournalSqlItemRead =
| { kind: 'running-turn' }
| { kind: 'context-usage' }
| { kind: 'thread-goal-source' }
| { kind: 'claude-identities' }
| { kind: 'named-turn'; turnId: string }
| { kind: 'message-options'; clientMessageId: string }
| { kind: 'continuation-context' }
@@ -44,6 +47,7 @@ export type JournalSqlItemReadResult =
| { kind: 'running-turn'; running: { item: AgentJournalRenderItem; turnId: string } | null }
| { kind: 'context-usage'; usage: AgentSessionContextUsage }
| { kind: 'thread-goal-source'; source: JournalThreadGoalSource }
| { kind: 'claude-identities'; identities: ClaudeJournaledIdentities }
| { kind: 'named-turn'; turn: JournalNamedTurn }
| { kind: 'message-options'; options: JournalMessageOptions }
| { kind: 'continuation-context'; context: JournalContinuationContext }
@@ -157,6 +161,8 @@ export function readJournalSqlItems(
}
return { kind: 'context-usage', usage: latestStructuredAgentContextFacts(turns.toReversed()) }
}
case 'claude-identities':
return { kind: 'claude-identities', identities: readJournalSqlClaudeIdentities(scope) }
case 'thread-goal-source': {
// The newest transition wins; on equal sequence the earlier-written row, as a fold scan keeps it.
const rows = scope.db
@@ -43,6 +43,9 @@ CREATE TABLE IF NOT EXISTS journal_proj_items (
lifecycle_state TEXT,
assistant_prose INTEGER NOT NULL DEFAULT 0,
turn_scope_kind TEXT,
producer_agent_id TEXT,
producer_parent_ref TEXT,
producer_attempt INTEGER,
PRIMARY KEY (session_id, epoch, entry_key)
) WITHOUT ROWID;
CREATE INDEX IF NOT EXISTS journal_proj_items_position
@@ -69,6 +72,14 @@ CREATE INDEX IF NOT EXISTS journal_proj_items_kind
CREATE INDEX IF NOT EXISTS journal_proj_items_unsettled
ON journal_proj_items(session_id, epoch, ordinal)
WHERE lifecycle_state IN ('running','pending') OR live_work=1;
CREATE INDEX IF NOT EXISTS journal_proj_items_parent_alias
ON journal_proj_items(session_id, epoch, producer_parent_ref, ordinal DESC)
WHERE producer_parent_ref IS NOT NULL;
CREATE INDEX IF NOT EXISTS journal_proj_items_agent_attempt
ON journal_proj_items(session_id, epoch, producer_agent_id, producer_attempt DESC)
WHERE producer_agent_id IS NOT NULL;
CREATE INDEX IF NOT EXISTS journal_proj_items_roster
ON journal_proj_items(session_id, epoch, ordinal) WHERE subagent_names IS NOT NULL;
CREATE INDEX IF NOT EXISTS journal_proj_items_turn_scope
ON journal_proj_items(session_id, epoch, turn_item_id, kind) WHERE turn_item_id IS NOT NULL;
`
@@ -11,6 +11,7 @@ import {
subagentItemBlock
} from '../../../shared/native-chat/transcript/native-chat-subagent-items'
import { journalItemStatusMetadata } from './journal-item-status-metadata'
import { claudeAgentRowFacts } from '../../claude/claude-subagent-journaled-identities'
import type { JournalSqlScope } from './journal-sql-scope'
import type { SqliteRow } from '../../sqlite/sqlite-statement'
import type { JournalSqlValueLocation, StoredJournalSqlValue } from './journal-sql-value-codec'
@@ -47,6 +48,12 @@ function journalSqlItemSubagentColumns(item: AgentJournalRenderItem) {
]
}
/** Agent linkage facts a Claude identity snapshot selects by index. */
function journalSqlItemProducerColumns(item: AgentJournalRenderItem) {
const facts = claudeAgentRowFacts(item)
return [facts?.agentId ?? null, facts?.parentRef ?? null, facts?.attempt ?? null]
}
/** Item incarnations keep original log pointers; only values without a saved outcome stay inline. */
export class JournalSqlItemValues {
private readonly pending = new Map<string, JournalSqlValueLocation>()
@@ -222,8 +229,9 @@ export class JournalSqlItemValues {
(session_id, epoch, entry_key, incarnation, ordinal, sequence, sequence_index,
revision, kind, turn_id, turn_item_id, opener_item_id, root, subagent_id, context_clear, byte_size,
message_role, command_entry, lifecycle_state, assistant_prose, turn_scope_kind,
live_work, subagent_row, subagent_group_key, subagent_names)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
live_work, subagent_row, subagent_group_key, subagent_names,
producer_agent_id, producer_parent_ref, producer_attempt)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
ON CONFLICT(session_id, epoch, entry_key) DO UPDATE SET
incarnation=excluded.incarnation, ordinal=excluded.ordinal, sequence=excluded.sequence,
sequence_index=excluded.sequence_index, revision=excluded.revision, kind=excluded.kind,
@@ -233,7 +241,9 @@ export class JournalSqlItemValues {
message_role=excluded.message_role, command_entry=excluded.command_entry,
lifecycle_state=excluded.lifecycle_state, assistant_prose=excluded.assistant_prose,
turn_scope_kind=excluded.turn_scope_kind, live_work=excluded.live_work, subagent_row=excluded.subagent_row,
subagent_group_key=excluded.subagent_group_key, subagent_names=excluded.subagent_names`)
subagent_group_key=excluded.subagent_group_key, subagent_names=excluded.subagent_names,
producer_agent_id=excluded.producer_agent_id, producer_parent_ref=excluded.producer_parent_ref,
producer_attempt=excluded.producer_attempt`)
.run(
...this.scope.prefix,
location.key,
@@ -241,7 +251,8 @@ export class JournalSqlItemValues {
ordinal,
...journalSqlItemMetadata(item, bytes),
Number(lostLiveWorkJournalBody(item.body) !== null),
...journalSqlItemSubagentColumns(item)
...journalSqlItemSubagentColumns(item),
...journalSqlItemProducerColumns(item)
)
}
}
@@ -5,7 +5,7 @@ import { AgentSessionJournalError } from './writing/journal-write-guards'
import { readJournalSessionEpoch } from './durable-rows/journal-row-table'
/** Bumped whenever a projection table's meaning changes; a different version reconverts. */
export const JOURNAL_SQL_PROJECTION_VERSION = 2
export const JOURNAL_SQL_PROJECTION_VERSION = 3
export function journalSqlMetaSchema(): string {
return `CREATE TABLE IF NOT EXISTS journal_proj_meta (
@@ -179,6 +179,7 @@ function read(
case 'running-turn':
case 'context-usage':
case 'thread-goal-source':
case 'claude-identities':
case 'named-turn':
case 'message-options':
case 'continuation-context':
@@ -109,6 +109,7 @@ export function journalSqlReads(
lastProviderActivityAt: async (fence) => (await read({ kind: 'provider-activity', fence })).at,
runningTurn: async () => (await read({ kind: 'running-turn' })).running,
threadGoalSource: async () => (await read({ kind: 'thread-goal-source' })).source,
claudeIdentities: async () => (await read({ kind: 'claude-identities' })).identities,
contextUsage: async () => (await read({ kind: 'context-usage' })).usage,
visitItems: async (filter, visit) => {
let afterOrdinal = -1
@@ -7,7 +7,10 @@ const STATUS_COLUMNS = [
['command_entry', 'INTEGER NOT NULL DEFAULT 0'],
['lifecycle_state', 'TEXT'],
['assistant_prose', 'INTEGER NOT NULL DEFAULT 0'],
['turn_scope_kind', 'TEXT']
['turn_scope_kind', 'TEXT'],
['producer_agent_id', 'TEXT'],
['producer_parent_ref', 'TEXT'],
['producer_attempt', 'INTEGER']
] as const
function normalizedIndex(sql: string): string {