Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.
TypeScript adeagent-ideai-agentsautomationbotclaude-codecodexghosttygrok-bothermes-agentmobile-appmuseopenclawopencodeorchestrationpiruntimeterminalworktreesyc-backed
import { describe, expect, expectTypeOf, it } from 'vitest'
import {
decodePersistedAgentSessionProviderHandleChain,
encodePersistedAgentSessionProviderHandleChain,
isAgentSessionHandleProvider,
type AgentSessionProviderHandle,
type AgentSessionProviderHandleLink
} from './agent-session-provider-handle'
import {
agentSessionJournalProviderHandle,
agentSessionProviderHandleFromWire,
agentSessionProviderHandleKey,
agentSessionProviderHandleRoot,
agentSessionWireProviderHandle,
claudeProviderHandle,
codexProviderHandle,
decodePersistedAgentSessionProviderHandle,
encodePersistedAgentSessionProviderHandle
} from './agent-session-provider-handle-encoding'
import {
isPersistedAgentSessionRecord,
type AgentSessionRecord,
type AgentSessionLease
} from './agent-session-record'
import { normalizeLegacyHandoffLease } from './agent-session-legacy-handoff-lease'
import {
decodePersistedAgentSessionRecord,
encodeAgentSessionRecord
} from './agent-session-record-stored-form'
import {
agentSessionLeaseFixture,
agentSessionRecordFixture
} from './agent-session-record.test-fixture'
/** The pre-neutral-handle guard applied to every stored handle. */
function olderBuildReadsHandle(value: unknown): boolean {
const isHandleField = (field: unknown): boolean =>
typeof field === 'string' && field.length > 0 && field.length <= 512 && field === field.trim()
if (typeof value !== 'object' || value === null || !('provider' in value)) {
return false
}
if (value.provider === 'claude') {
return (
'sessionId' in value &&
isHandleField(value.sessionId) &&
'leafUuid' in value &&
(value.leafUuid === null || isHandleField(value.leafUuid))
)
}
return value.provider === 'codex' && 'threadId' in value && isHandleField(value.threadId)
}
/** A Claude record row exactly as builds before this change wrote it: a fork with its seed key. */
const STORED_CLAUDE_ROW = JSON.stringify({
schemaVersion: 2,
sessionId: 'session-alpha-1',
location: {
executionHostId: 'local',
wslDistro: null,
workspaceId: 'workspace-1',
workspaceKind: 'git-worktree'
},
provider: 'claude',
providerHandleChain: [
{
linkId: 'link-1',
handle: { provider: 'claude', sessionId: 'sess-1', leafUuid: 'leaf-1' },
origin: 'created',
mintedAtFence: 6,
observedAt: 1000
},
{
linkId: 'link-2',
handle: { provider: 'claude', sessionId: 'sess-2', leafUuid: null },
origin: 'forked',
mintedAtFence: 7,
observedAt: 1500,
forkedFromKey: 'claude:["sess-1","leaf-1"]'
}
],
accountHome: { variable: 'CLAUDE_CONFIG_DIR', path: '/home/user/.claude' },
lease: agentSessionLeaseFixture({ provenHandleLinkId: 'link-2' }),
createdAt: 1000,
updatedAt: 2000
})
/** A Codex row with a creation that replaced one Codex never saved. */
const STORED_CODEX_ROW = JSON.stringify({
...JSON.parse(STORED_CLAUDE_ROW),
provider: 'codex',
providerHandleChain: [
{
linkId: 'codex-7-thread-new',
handle: { provider: 'codex', threadId: 'thread-new' },
origin: 'created',
mintedAtFence: 7,
observedAt: 1500,
supersedesKey: 'codex:"thread-unsaved"'
}
],
accountHome: { variable: 'CODEX_HOME', path: '/home/user/.codex' },
lease: agentSessionLeaseFixture({ provenHandleLinkId: 'codex-7-thread-new' })
})
describe('a record row older builds wrote', () => {
it.each([undefined, 0, 6, 7, 9, Number.MAX_SAFE_INTEGER])(
'keeps a valid legacy next-fence floor %s readable',
(minimumNextFence) => {
const record = agentSessionRecordFixture(agentSessionLeaseFixture({ minimumNextFence }))
const stored = JSON.parse(JSON.stringify(encodeAgentSessionRecord(record)))
expect(isPersistedAgentSessionRecord(stored)).toBe(true)
expect(decodePersistedAgentSessionRecord(stored).record.lease.minimumNextFence).toBe(
minimumNextFence
)
}
)
it.each([
['Claude', STORED_CLAUDE_ROW],
['Codex', STORED_CODEX_ROW]
])('reads a %s row and writes it back byte for byte', (_name, row) => {
const stored: unknown = JSON.parse(row)
expect(isPersistedAgentSessionRecord(stored)).toBe(true)
if (!isPersistedAgentSessionRecord(stored)) {
return
}
const { record, normalized } = decodePersistedAgentSessionRecord(stored)
expect(normalized).toBe(false)
expectTypeOf(record).toMatchTypeOf<AgentSessionRecord>()
expect(JSON.stringify(encodeAgentSessionRecord(record))).toBe(row)
})
it.each([undefined, 25, 0, -1, '25', null, Number.NaN, Number.POSITIVE_INFINITY])(
'normalizes a saved sleep value %s without hiding the conversation',
(sleptAt) => {
const stored = { ...encodeAgentSessionRecord(agentSessionRecordFixture()), sleptAt }
expect(isPersistedAgentSessionRecord(stored)).toBe(true)
const decoded = decodePersistedAgentSessionRecord(stored)
expectTypeOf(decoded.record).toMatchTypeOf<AgentSessionRecord>()
expect(decoded.record.sleptAt).toBe(sleptAt === 25 ? 25 : undefined)
expect(decoded.normalized).toBe(sleptAt !== undefined && sleptAt !== 25)
}
)
it('hands shared code only the neutral handle', () => {
const stored: unknown = JSON.parse(STORED_CLAUDE_ROW)
if (!isPersistedAgentSessionRecord(stored)) {
throw new Error('fixture row must be readable')
}
const { record } = decodePersistedAgentSessionRecord(stored)
expect(record.providerHandleChain.map((link) => link.handle)).toEqual([
{ transport: 'claude-sdk', agent: 'claude', nativeId: 'sess-1', resumeCursor: 'leaf-1' },
{ transport: 'claude-sdk', agent: 'claude', nativeId: 'sess-2' }
])
})
it('still reports a lease only the removed terminal handoff wrote', () => {
const record = agentSessionRecordFixture()
const stored = encodeAgentSessionRecord(record)
expect(decodePersistedAgentSessionRecord(stored)).toEqual({ record, normalized: false })
const lease = {
...stored.lease,
runtimeKind: 'tui' as const,
handoffStage: 'preparing' as const,
claimStatus: 'live' as const
}
const normalized = normalizeLegacyHandoffLease(lease)
expectTypeOf(normalized.runtimeKind).toEqualTypeOf<AgentSessionLease['runtimeKind']>()
expectTypeOf(normalized.handoffStage).toEqualTypeOf<AgentSessionLease['handoffStage']>()
expectTypeOf(normalized.claimStatus).toEqualTypeOf<AgentSessionLease['claimStatus']>()
const decoded = decodePersistedAgentSessionRecord({ ...stored, lease })
expectTypeOf(decoded.record).toMatchTypeOf<AgentSessionRecord>()
expect(decoded).toEqual({
record: {
...record,
lease: { ...record.lease, claimStatus: 'conflicted', handoffStage: 'recovering' }
},
normalized: true
})
const unknownFloor: unknown = 'bad'
const observed = decodePersistedAgentSessionRecord({
...stored,
lease: { ...lease, minimumNextFence: unknownFloor }
})
expectTypeOf(observed.record.lease.minimumNextFence).toEqualTypeOf<unknown>()
expectTypeOf(observed.record).not.toMatchTypeOf<AgentSessionRecord>()
expect(observed.record.lease.minimumNextFence).toBe('bad')
})
})
describe('what this build writes', () => {
it('stores Claude and Codex handles in the typed form older builds read', () => {
const claude = claudeProviderHandle('sess-1', 'leaf-1')
const codex = codexProviderHandle('thread-1')
expect(encodePersistedAgentSessionProviderHandle(claude)).toEqual({
provider: 'claude',
sessionId: 'sess-1',
leafUuid: 'leaf-1'
})
expect(encodePersistedAgentSessionProviderHandle(claudeProviderHandle('sess-1', null))).toEqual(
{ provider: 'claude', sessionId: 'sess-1', leafUuid: null }
)
expect(encodePersistedAgentSessionProviderHandle(codex)).toEqual({
provider: 'codex',
threadId: 'thread-1'
})
for (const handle of [claude, codex]) {
const stored = encodePersistedAgentSessionProviderHandle(handle)
expect(olderBuildReadsHandle(stored)).toBe(true)
expect(decodePersistedAgentSessionProviderHandle(stored)).toEqual(handle)
}
})
it('keeps the persisted key and root strings older builds derived', () => {
// Fork seeds, superseded creations and resume offers store these; a new spelling strands them.
const claude = claudeProviderHandle('sess-1', 'leaf-1')
expect(agentSessionProviderHandleKey(claude)).toBe('claude:["sess-1","leaf-1"]')
expect(agentSessionProviderHandleKey(claudeProviderHandle('sess-1', null))).toBe(
'claude:["sess-1",null]'
)
expect(agentSessionProviderHandleRoot(claude)).toBe('claude:"sess-1"')
expect(agentSessionProviderHandleKey(codexProviderHandle('t'))).toBe('codex:"t"')
expect(agentSessionProviderHandleRoot(codexProviderHandle('t'))).toBe('codex:"t"')
})
it('round-trips another transport in the neutral form, which an older build refuses', () => {
const grok = {
transport: 'acp',
agent: 'grok',
nativeId: 'acp-session-1',
resumeCursor: '{"cwd":"/repo"}'
}
const stored = encodePersistedAgentSessionProviderHandle(grok)
expect(stored).toEqual(grok)
expect(decodePersistedAgentSessionProviderHandle(JSON.parse(JSON.stringify(stored)))).toEqual(
grok
)
// Unknown providers must never impersonate Codex on an older build.
expect(olderBuildReadsHandle(stored)).toBe(false)
expect(isAgentSessionHandleProvider(grok.agent)).toBe(false)
expect(agentSessionWireProviderHandle(grok)).toBeNull()
// Root, not the resume cursor: the cursor is resume state, not identity.
expect(agentSessionProviderHandleRoot(grok)).toBe('acp/grok:"acp-session-1"')
expect(agentSessionProviderHandleKey(grok)).toBe(agentSessionProviderHandleRoot(grok))
})
it('refuses a stored handle that is not the one form its transport writes', () => {
for (const value of [
// Claude or Codex in the neutral form: no build writes it.
{ transport: 'claude-sdk', agent: 'claude', nativeId: 'sess-1' },
{ transport: 'codex-app-server', agent: 'codex', nativeId: 'thread-1' },
// Both forms at once: reading either identity would erase the other.
{ provider: 'grok', transport: 'acp', agent: 'grok', nativeId: 'x' },
{
provider: 'codex',
threadId: 'thread-1',
transport: 'acp',
agent: 'grok',
nativeId: 'acp-thread',
resumeCursor: 'resume-token'
},
{ provider: 'codex', threadId: 'thread-1', nativeId: 'other-thread' },
{
provider: 'claude',
sessionId: 'sess-1',
leafUuid: null,
transport: 'acp',
agent: 'grok',
nativeId: 'other'
},
{ provider: 'claude', sessionId: 'sess-1', leafUuid: null, resumeCursor: 'leaf-2' },
{ provider: 'claude', sessionId: 'sess-1' },
{ provider: 'claude', sessionId: 'sess-1', leafUuid: '' },
{ provider: 'codex', threadId: ' padded ' },
{ transport: 'a:b', agent: 'grok', nativeId: 'x' },
{ transport: 'acp', agent: 'grok', nativeId: 'x', resumeCursor: '' },
null
]) {
expect(decodePersistedAgentSessionProviderHandle(value)).toBeNull()
}
})
it('still reads a typed handle that carries an unrelated field', () => {
expect(
decodePersistedAgentSessionProviderHandle({ provider: 'codex', threadId: 't', note: 1 })
).toEqual(codexProviderHandle('t'))
expect(
decodePersistedAgentSessionProviderHandle({
provider: 'claude',
sessionId: 'sess-1',
leafUuid: 'leaf-1',
note: 1
})
).toEqual(claudeProviderHandle('sess-1', 'leaf-1'))
})
it('drops a field a later build put on a handle, but keeps one on the link or record', () => {
const stored = JSON.parse(STORED_CODEX_ROW)
stored.providerHandleChain[0].handle.laterHandleField = 'x'
stored.providerHandleChain[0].laterLinkField = 'y'
stored.laterRecordField = 'z'
expect(isPersistedAgentSessionRecord(stored)).toBe(true)
if (!isPersistedAgentSessionRecord(stored)) {
return
}
const written = JSON.parse(
JSON.stringify(encodeAgentSessionRecord(decodePersistedAgentSessionRecord(stored).record))
)
expect(written.laterRecordField).toBe('z')
expect(written.providerHandleChain[0].laterLinkField).toBe('y')
expect(written.providerHandleChain[0].handle).toEqual({
provider: 'codex',
threadId: 'thread-new'
})
const neutral = { transport: 'acp', agent: 'grok', nativeId: 's', resumeCursor: 'c' }
const decoded = decodePersistedAgentSessionProviderHandle({ ...neutral, laterHandleField: 1 })
expect(decoded && encodePersistedAgentSessionProviderHandle(decoded)).toEqual(neutral)
})
it.each([
['Claude', STORED_CLAUDE_ROW],
['Codex', STORED_CODEX_ROW]
])('refuses a whole %s row whose handle also names a neutral identity', (_name, row) => {
const stored = JSON.parse(row)
Object.assign(stored.providerHandleChain[0].handle, {
transport: 'acp',
agent: 'grok',
nativeId: 'acp-thread',
resumeCursor: 'resume-token'
})
expect(isPersistedAgentSessionRecord(stored)).toBe(false)
})
})
describe('the wire and journal forms', () => {
it('maps the attach wire handle both ways for Claude and Codex', () => {
const claudeWire = { kind: 'claude', sessionId: 'sess-1', leafUuid: null } as const
const codexWire = { kind: 'codex', threadId: 'thread-1' } as const
expect(agentSessionProviderHandleFromWire(claudeWire)).toEqual(
claudeProviderHandle('sess-1', null)
)
expect(agentSessionWireProviderHandle(agentSessionProviderHandleFromWire(claudeWire))).toEqual(
claudeWire
)
expect(agentSessionWireProviderHandle(agentSessionProviderHandleFromWire(codexWire))).toEqual(
codexWire
)
})
it('records the journal rows exactly as before, and another transport as opaque', () => {
expect(
agentSessionJournalProviderHandle({
agent: 'claude',
providerHandle: claudeProviderHandle('sess-1', 'leaf-1')
})
).toEqual({ kind: 'claude', sessionId: 'sess-1', leafUuid: 'leaf-1' })
expect(
agentSessionJournalProviderHandle({
agent: 'codex',
providerHandle: codexProviderHandle('t')
})
).toEqual({ kind: 'codex', threadId: 't' })
expect(agentSessionJournalProviderHandle({ agent: 'codex', providerHandle: null })).toEqual({
kind: 'opaque',
agent: 'codex',
value: 'pending'
})
expect(
agentSessionJournalProviderHandle({
agent: 'grok',
providerHandle: { transport: 'acp', agent: 'grok', nativeId: 's' }
})
).toEqual({ kind: 'opaque', agent: 'grok', value: 's' })
})
})
describe('a chat whose saved conversation could not be restored', () => {
const acp = (nativeId: string): AgentSessionProviderHandle => ({
transport: 'acp',
agent: 'grok',
nativeId
})
const link = (
linkId: string,
nativeId: string,
fence: number,
extra: Partial<AgentSessionProviderHandleLink> = {}
): AgentSessionProviderHandleLink => ({
linkId,
handle: acp(nativeId),
origin: 'created',
mintedAtFence: fence,
observedAt: fence * 1_000,
...extra
})
const lost = (nativeId: string, replacedAt: number) => ({
key: agentSessionProviderHandleKey(acp(nativeId)),
reason: 'restore-failed',
replacedAt
})
// Opened, reopened, lost and replaced twice, and the second replacement reopened.
const chain = [
link('l1', 's-1', 1),
link('l2', 's-1', 2, { origin: 'resumed' }),
link('l3', 's-2', 3, { replaces: lost('s-1', 3_000) }),
link('l4', 's-3', 4, { replaces: lost('s-2', 4_000) }),
link('l5', 's-3', 7, { origin: 'resumed' })
]
it('stores the chain as it is held, and reads every link back', () => {
const stored = JSON.parse(JSON.stringify(encodePersistedAgentSessionProviderHandleChain(chain)))
expect(stored).toEqual(chain)
expect(decodePersistedAgentSessionProviderHandleChain(stored)).toEqual(chain)
})
it('refuses a stored replacement that opens the chain or names another conversation', () => {
const stored = JSON.parse(JSON.stringify(encodePersistedAgentSessionProviderHandleChain(chain)))
expect(decodePersistedAgentSessionProviderHandleChain(stored.slice(2))).toBeNull()
stored[3].replaces.key = agentSessionProviderHandleKey(acp('s-1'))
expect(decodePersistedAgentSessionProviderHandleChain(stored)).toBeNull()
})
})
it.each([
null,
'open',
{},
{ state: 'open', at: -1 },
{ state: 'settled', at: 10, outcome: 'newer' },
{ state: 'open', at: 10, prompt: 'p'.repeat(281) }
])('ignores malformed optional last-turn metadata: %j', (lastTurn) => {
const stored = { ...encodeAgentSessionRecord(agentSessionRecordFixture()), lastTurn }
expect(isPersistedAgentSessionRecord(stored)).toBe(true)
expect(decodePersistedAgentSessionRecord(stored).record.lastTurn).toBeUndefined()
})
it('preserves the saved turn and unknown JSON through a record transition', () => {
const stored = {
...encodeAgentSessionRecord(agentSessionRecordFixture()),
lastTurn: { state: 'settled', outcome: 'success', at: 10 },
laterField: 'keep'
}
const record = decodePersistedAgentSessionRecord(stored).record
expect(encodeAgentSessionRecord({ ...record, updatedAt: 20 })).toMatchObject({
lastTurn: stored.lastTurn,
laterField: 'keep'
})
})
it('stores a delivered kill in the form older builds read and reads only that exact pair back', () => {
const evidence = { detail: 'killed', observedAt: 40, ownerFence: 7 } as const
const withEvidence = (deathEvidence: unknown) => ({
...encodeAgentSessionRecord(agentSessionRecordFixture()),
lease: { ...agentSessionLeaseFixture({ claimStatus: 'released' }), deathEvidence }
})
const killed = agentSessionRecordFixture(
agentSessionLeaseFixture({
claimStatus: 'released',
deathEvidence: { kind: 'kill-delivered', ...evidence }
})
)
const stored = encodeAgentSessionRecord(killed)
expect(stored.lease.deathEvidence).toEqual({ kind: 'pid-absent', delivery: 'kill', ...evidence })
expect(isPersistedAgentSessionRecord(stored)).toBe(true)
expect(decodePersistedAgentSessionRecord(stored).record).toEqual(killed)
// Rows written before this encoding, a plain absent pid, and stale or foreign markers.
for (const [saved, read] of [
[
{ kind: 'kill-delivered', ...evidence },
{ kind: 'kill-delivered', ...evidence }
],
[
{ kind: 'pid-absent', ...evidence },
{ kind: 'pid-absent', ...evidence }
],
[
{ kind: 'pid-absent', delivery: 'signal', ...evidence },
{ kind: 'pid-absent', ...evidence }
],
[
{ kind: 'exit-observed', delivery: 'kill', ...evidence },
{ kind: 'exit-observed', ...evidence }
]
]) {
const row: unknown = withEvidence(saved)
if (!isPersistedAgentSessionRecord(row)) {
throw new Error('the stored evidence fixture must pass record validation')
}
expect(decodePersistedAgentSessionRecord(row).record.lease.deathEvidence).toEqual(read)
}
})