Files
archived-orca/src/main/runtime/structured-agent-session-integration.test.ts
T

878 lines
32 KiB
TypeScript

import './rpc/unused-default-rpc-methods.test-fixture'
import { scriptedCodexCatalogSession } from './scripted-codex-model-catalog.test-fixture'
// Exercise shipped RPC, schemas, capability gate, stores, lease and adapter; only the Codex app-server child is fake.
import { mkdtemp, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import type {
CodexAppServerConnection,
CodexAppServerConnectionHandlers
} from '../codex/app-server/codex-app-server-connection-types'
import type { openCodexAppServerConnection } from '../codex/codex-app-server-connection'
import { computeAgentSessionPayloadFingerprint } from '../../shared/agent-session-mutation-envelope'
import { DESKTOP_RENDERER_RUNTIME_CLIENT_CAPABILITIES } from '../ipc/desktop-renderer-runtime-capabilities'
import { AGENT_SESSION_CREATE_MESSAGE_RUNTIME_CAPABILITY } from '../../shared/agent-session-create-capabilities'
import type {
AgentJournalRenderItem,
AgentJournalSubmission
} from '../../shared/agent-session-journal-types'
import type {
AgentSessionHistoryResult,
AgentSessionSubscribeEvent
} from '../../shared/agent-session-wire'
import { attachFingerprintFields } from '../native-chat/agent-session-wire/structured-agent-session-attach'
import { getStructuredAgentSessionHost } from '../native-chat/agent-session-wire/structured-agent-session-registry'
import { importLegacyTranscriptIntoJournal } from '../native-chat/agent-session-journal/journal-legacy-import'
import type { AgentSessionJournal } from '../native-chat/agent-session-journal/journal-store'
import { createTrackedJournalOpener } from '../native-chat/agent-session-journal/journal-host-database-test-support'
import type { OrcaRuntimeService } from './orca-runtime'
import { readPersistedTestAgentSessionStoreText } from './agent-session-record-store-test-harness'
import type { RpcRequest, RpcResponse } from './rpc/core'
import { RpcDispatcher } from './rpc/dispatcher'
import type { NativeChatShellEnvironmentPolicy } from '../../shared/native-chat/native-chat-shell-environment'
import { STRUCTURED_AGENT_SESSION_METHODS } from './rpc/methods/structured-agent-session'
import {
ensureStructuredAgentSessionHost,
stopStructuredAgentSessionRuntime
} from './structured-agent-session-runtime'
import { createStructuredAgentSessionLogger } from '../native-chat/agent-session-wire/structured-agent-session-logger'
import { codexProviderHandle } from '../../shared/agent-session-provider-handle-encoding'
import { scriptedCodexTransport } from './scripted-codex-transport.test-fixture'
const journals = createTrackedJournalOpener()
const SESSION = 'session-integration-1'
const THREAD = 'thread-integration'
const TURN = 'turn-1'
const WORKSPACE = 'workspace-1'
const JOURNAL_IDENTITY = {
sessionId: SESSION,
workspaceId: WORKSPACE,
hostId: 'local',
agent: 'codex' as const,
providerHandle: codexProviderHandle(THREAD)
}
// Use current pending-send capability; older clients wait for settlement because they cannot render pending bubbles.
const CLIENT = {
clientId: 'device-a',
clientKind: 'runtime' as const,
clientCapabilities: DESKTOP_RENDERER_RUNTIME_CLIENT_CAPABILITIES.filter(
(capability) => capability !== AGENT_SESSION_CREATE_MESSAGE_RUNTIME_CAPABILITY
)
}
type CodexScript = {
connections: FakeConnection[]
openConnection: typeof openCodexAppServerConnection
live: () => FakeConnection
notify: (method: string, params: unknown) => void
ask: (id: number, method: string, params: unknown) => void
}
// `closed` is readonly on the real connection; the fake flips it so the test can
// see the takeover reap the previous child.
type FakeConnection = Omit<CodexAppServerConnection, 'closed'> & {
closed: boolean
handlers: CodexAppServerConnectionHandlers
calls: { method: string; params?: Record<string, unknown> }[]
replies: { id: number | string; result?: unknown; code?: number }[]
resumedThreadId: string | null
launch: Parameters<typeof openCodexAppServerConnection>[0]
}
function fakeCodex(): CodexScript {
const connections: FakeConnection[] = []
const openConnection: typeof openCodexAppServerConnection = async (launch, handlers = {}) => {
const connection: FakeConnection = {
launch,
handlers,
calls: [],
replies: [],
resumedThreadId: null,
pid: 4321,
closed: false,
get closeResult(): CodexAppServerConnection['closeResult'] {
return connection.closed ? { root: 'exited', tree: 'exited' } : null
},
request: async (method, params) => {
connection.calls.push({ method, params })
if (method === 'thread/goal/get') {
return { goal: null }
}
if (method === 'thread/start') {
return { thread: { id: THREAD, path: '/rollouts/integration.jsonl' } }
}
if (method === 'thread/resume') {
connection.resumedThreadId = (params as { threadId: string }).threadId
return { thread: { id: connection.resumedThreadId } }
}
if (method === 'turn/start') {
return { turn: { id: TURN } }
}
if (method === 'model/list') {
return {
data: [
{
model: 'gpt-live',
displayName: 'GPT Live',
hidden: false,
supportedReasoningEfforts: [
{ reasoningEffort: 'medium', description: 'Balanced' },
{ reasoningEffort: 'high', description: 'Deep reasoning' }
],
defaultReasoningEffort: 'medium',
isDefault: true
}
],
nextCursor: null
}
}
return {}
},
notify: () => {},
respond: (id, result) => connection.replies.push({ id, result }),
respondWithError: (id, code) => connection.replies.push({ id, code }),
close: async () => {
connection.closed = true
return true
}
}
connections.push(connection)
return connection
}
const live = (): FakeConnection => {
const connection = connections.at(-1)
if (!connection) {
throw new Error('no codex app-server has been opened')
}
return connection
}
return {
connections,
openConnection,
live,
notify: (method, params) => live().handlers.onNotification?.(method, params),
ask: (id, method, params) => live().handlers.onServerRequest?.({ id, method, params })
}
}
let operations = 0
/** Use ledger-shaped ids with its real clock; future-dated ids are refused. */
function operationId(): string {
operations += 1
return `${Date.now()}-${operations.toString(16).padStart(32, '0')}`
}
function envelope(method: string, fields: Record<string, unknown>, fence: number | null) {
return {
sessionId: SESSION,
clientOperationId: operationId(),
expectedRuntimeFence: fence,
payloadFingerprint: computeAgentSessionPayloadFingerprint({
method,
sessionId: SESSION,
fields
})
}
}
function attachParams(fence: number | null) {
const params = {
location: {
executionHostId: 'local' as const,
wslDistro: null,
workspaceId: WORKSPACE,
workspaceKind: 'git-worktree' as const
},
provider: 'codex' as const,
agent: 'codex',
accountHome: { variable: 'CODEX_HOME' as const, path: '/home/dev/.codex' },
runtimeKind: 'native' as const,
providerHandle: { kind: 'codex' as const, threadId: THREAD }
}
const mutation = envelope('agentSession.attach', {}, fence)
mutation.payloadFingerprint = computeAgentSessionPayloadFingerprint({
method: 'agentSession.attach',
sessionId: SESSION,
fields: attachFingerprintFields({ ...params, envelope: mutation })
})
return { ...params, envelope: mutation }
}
function createIntentParams() {
const worktree = `id:${WORKSPACE}`
const fields = { worktree, agent: 'codex' }
return { envelope: envelope('agentSession.create', fields, null), ...fields }
}
let codex: CodexScript
/** Accepted first; the delivery loop hands the send over as `turn/start` after the reply. */
const handedOverAs = (params: Record<string, unknown>) =>
vi.waitFor(() =>
expect(codex.live().calls.at(-1)).toMatchObject({ method: 'turn/start', params })
)
let root: string
let dispatcher: RpcDispatcher
let bootEnvironmentReads: number
let codexOverrideReads: number
let configuredCodexProfile: string
let shellEnvironmentPolicy: NativeChatShellEnvironmentPolicy
async function call(method: string, params: unknown): Promise<RpcResponse> {
const replies: RpcResponse[] = []
const request: RpcRequest = { id: `req-${operations}`, authToken: 'token', method, params }
await dispatcher.dispatchStreaming(request, (raw) => replies.push(JSON.parse(raw)), CLIENT)
const first = replies[0]
if (!first) {
throw new Error(`no reply for ${method}`)
}
return first
}
async function ok<T>(method: string, params: unknown): Promise<T> {
const response = await call(method, params)
expect(response, `${method} failed: ${JSON.stringify(response)}`).toMatchObject({ ok: true })
const result = (response as { result: { ok: boolean; value?: T; refusal?: unknown } }).result
expect(result, `${method} refused: ${JSON.stringify(result.refusal)}`).toMatchObject({ ok: true })
return result.value as T
}
async function subscribe(
requestId: string,
cursor?: { epoch: string; sequence: number }
): Promise<AgentSessionSubscribeEvent[]> {
const frames: AgentSessionSubscribeEvent[] = []
await dispatcher.dispatchStreaming(
{
id: requestId,
authToken: 'token',
method: 'agentSession.subscribe',
params: { sessionId: SESSION, ...(cursor ? { cursor } : {}) }
},
(raw) => {
const response = JSON.parse(raw) as { ok: boolean; result?: AgentSessionSubscribeEvent }
if (response.ok && response.result) {
frames.push(response.result)
}
},
CLIENT
)
return frames
}
/** Flush provider writes; real clients wait for their subscription frames. */
const drainStreamedEvents = (): Promise<void> =>
getStructuredAgentSessionHost()?.flushStreamedEvents(SESSION) ?? Promise.resolve()
function textOf(item: AgentJournalRenderItem): string {
const body = item.body
return body?.kind === 'message'
? body.blocks.map((block) => (block.type === 'text' ? block.text : '')).join('')
: ''
}
async function submissionOf(clientMessageId: string): Promise<AgentJournalSubmission | undefined> {
return (await getStructuredAgentSessionHost()?.journalSnapshot(SESSION))?.submissions.find(
(entry) => entry.clientMessageId === clientMessageId
)
}
async function historyPage(
direction: 'tail' | 'before' | 'after',
extra: Record<string, unknown> = {}
): Promise<AgentSessionHistoryResult> {
const response = await call('agentSession.history', {
sessionId: SESSION,
direction,
...extra
})
return (response as { result: AgentSessionHistoryResult }).result
}
async function readKnownOptions(): Promise<RpcResponse> {
return vi.waitFor(async () => {
const result = await call('agentSession.options', { sessionId: SESSION })
expect(result).toMatchObject({
ok: true,
result: {
models: [{ id: 'gpt-live', defaultEffort: 'medium' }],
current: { model: 'gpt-live' }
}
})
return result
})
}
beforeEach(async () => {
operations = 0
root = await mkdtemp(join(tmpdir(), 'orca-structured-integration-'))
codex = fakeCodex()
bootEnvironmentReads = 0
codexOverrideReads = 0
configuredCodexProfile = 'configured'
shellEnvironmentPolicy = { inheritAll: true, names: [] }
const runtime = {
getRuntimeId: () => 'runtime-1',
resolveStructuredAgentSessionLocalWorkspacePath: async () => `/repos/${WORKSPACE}`,
getClientSettings: () => ({ experimentalNativeChat: true }),
getStructuredAgentSessionCreateSupport: async () => ({ supported: true }),
structuredAgentSessionLaunchSeedOptions: () => undefined,
resolveStructuredAgentSessionCreateIntent: async () => {
const {
envelope: _envelope,
providerHandle: _providerHandle,
...resolved
} = attachParams(null)
return { ...resolved, options: { model: 'gpt-live' } }
},
publishStructuredAgentSessionTab: () => {},
ensureStructuredAgentSessionHost: () =>
ensureStructuredAgentSessionHost({
logger: createStructuredAgentSessionLogger(),
stateDirectory: root,
hostId: 'local',
claimKeyId: 'key-1',
resolveWorkspacePath: async (workspaceId) => `/repos/${workspaceId}`,
resolveCodexCommand: () => '/usr/local/bin/codex',
runCodexCatalogSession: scriptedCodexCatalogSession,
resolveAgentAccountHome: async () => ({ variable: 'CODEX_HOME', path: '/home/dev/.codex' }),
resolveLaunchArgs: () => [],
resolveClaudeAuthPolicy: () => ({ account: 'managed' }),
resolveEnvironment: async () => {
bootEnvironmentReads += 1
return {
PATH: '/shell/bin:/usr/bin',
EXAMPLE_GATEWAY_TOKEN: 'shell-exported',
CODEX_HOME: '/shell/home'
}
},
resolveShellEnvironmentPolicy: () => shellEnvironmentPolicy,
resolveAgentLaunchEnv: (agent): Record<string, string> => {
if (agent !== 'codex') {
return {}
}
codexOverrideReads += 1
return { CODEX_PROFILE: configuredCodexProfile }
},
...scriptedCodexTransport(codex.openConnection)
}).then(() => undefined),
registerOwnedSubscriptionCleanup: vi.fn((_id: string, dispose: () => void) => ({
releaseIfCurrent: dispose
}))
}
dispatcher = new RpcDispatcher({
runtime: runtime as unknown as OrcaRuntimeService,
methods: STRUCTURED_AGENT_SESSION_METHODS
})
})
function itemsOf(frames: AgentSessionSubscribeEvent[]): AgentJournalRenderItem[] {
const items = new Map<string, AgentJournalRenderItem>()
for (const frame of frames) {
const published =
frame.type === 'snapshot' || frame.type === 'reset'
? frame.page.items
: frame.type === 'batch'
? frame.batch.items
: []
for (const item of published) {
items.set(item.itemId, item)
}
}
return [...items.values()]
}
function cursorOf(frames: AgentSessionSubscribeEvent[]): { epoch: string; sequence: number } {
for (let index = frames.length - 1; index >= 0; index -= 1) {
const frame = frames[index] as AgentSessionSubscribeEvent
if (frame.type === 'batch') {
return frame.batch.cursor
}
if (frame.type === 'snapshot' || frame.type === 'reset') {
return frame.page.liveCursor ?? frame.page.window.nextCursor
}
}
throw new Error('subscription published no cursor')
}
afterEach(async () => {
await journals.closeAll()
await stopStructuredAgentSessionRuntime()
await rm(root, { recursive: true, force: true })
})
describe('a structured codex session over agentSession.*', () => {
it('hydrates provider options after activating a legacy-imported journal', async () => {
const journal = await journals.open({
identity: JOURNAL_IDENTITY,
stateDirectory: root
})
const rollout = join(root, 'legacy-rollout.jsonl')
await writeFile(
rollout,
`${JSON.stringify({
type: 'event_msg',
timestamp: '2026-08-05T10:00:02.000Z',
payload: { type: 'user_message', message: 'legacy question', kind: 'plain' }
})}\n`
)
await importLegacyTranscriptIntoJournal({
journal,
agent: 'codex',
sessionId: THREAD,
fence: 0,
options: { filePath: rollout }
})
await journals.closeAll()
const created = await ok<{ page: { items: AgentJournalRenderItem[] } }>(
'agentSession.create',
createIntentParams()
)
expect(created.page.items.map(textOf)).toContain('legacy question')
await readKnownOptions()
})
it('dispatches and streams a plain first send from a fresh session', async () => {
const created = await ok<{ fence: number; page: { items: unknown[] } }>(
'agentSession.create',
createIntentParams()
)
expect(created.page.items).toEqual([])
expect(codex.live().launch.env).toMatchObject({
CODEX_PROFILE: 'configured',
EXAMPLE_GATEWAY_TOKEN: 'shell-exported',
CODEX_HOME: '/home/dev/.codex'
})
const store = await readPersistedTestAgentSessionStoreText(root)
expect(store).toContain('/home/dev/.codex')
expect(store).not.toContain('EXAMPLE_GATEWAY_TOKEN')
expect(store).not.toContain('"launchEnv"')
const stream = await subscribe('sub-first-send')
const body = { kind: 'message', role: 'user', blocks: [{ type: 'text', text: 'hi' }] }
const sent = await ok<{
clientMessageId: string
submission: { dispatchState: string; providerItemId: string | null }
}>('agentSession.send', {
envelope: envelope('agentSession.send', { body }, created.fence),
body
})
// Admission does not identify a message: coalesced turn/start answers name the running turn; only its echo identifies the send.
expect(sent.submission).toMatchObject({ dispatchState: 'pending', providerItemId: null })
await handedOverAs({ threadId: THREAD, clientUserMessageId: sent.clientMessageId })
codex.notify('turn/started', { turn: { id: TURN } })
// Only the echoed clientId identifies the submission to settle.
codex.notify('item/completed', {
item: {
type: 'userMessage',
id: 'item-0',
clientId: sent.clientMessageId,
content: [{ type: 'text', text: 'hi' }]
}
})
codex.notify('item/started', { item: { type: 'agentMessage', id: 'item-1', text: '' } })
codex.notify('item/agentMessage/delta', { itemId: 'item-1', delta: 'Hello.' })
codex.notify('item/completed', {
item: { type: 'agentMessage', id: 'item-1', text: 'Hello.' }
})
await drainStreamedEvents()
expect(itemsOf(stream).map(textOf).filter(Boolean)).toEqual(['hi', 'Hello.'])
// Echo ordinal 0 must use the same identityFor key as history replay.
await vi.waitFor(async () =>
expect(await submissionOf(sent.clientMessageId)).toMatchObject({
dispatchState: 'accepted',
providerItemId: `codex:${THREAD}:${TURN}:0`
})
)
})
it('runs create → send → stream → approval → cancel → reconnect → page history', async () => {
// Create builds the host lazily.
expect(getStructuredAgentSessionHost()).toBeNull()
const created = await ok<{ fence: number; page: { items: unknown[] } }>(
'agentSession.create',
createIntentParams()
)
expect(created.page.items).toEqual([])
// Create answers at spawn; the thread opens once Codex has initialized.
await vi.waitFor(() =>
expect(codex.live().calls.find((call) => call.method === 'thread/start')).toMatchObject({
params: { cwd: `/repos/${WORKSPACE}` }
})
)
const fence = created.fence
const stream = await subscribe('sub-1')
expect(stream[0]).toMatchObject({ type: 'snapshot', sessionId: SESSION })
await readKnownOptions()
await ok('agentSession.setOption', {
envelope: envelope('agentSession.setOption', { key: 'model', value: 'gpt-live' }, fence),
key: 'model',
value: 'gpt-live'
})
await ok('agentSession.setOption', {
envelope: envelope('agentSession.setOption', { key: 'effort', value: 'high' }, fence),
key: 'effort',
value: 'high'
})
await vi.waitFor(async () =>
expect(await call('agentSession.options', { sessionId: SESSION })).toMatchObject({
ok: true,
result: { current: { model: 'gpt-live', effort: 'high' } }
})
)
expect(itemsOf(stream)).toEqual([])
const body = { kind: 'message', role: 'user', blocks: [{ type: 'text', text: 'list files' }] }
const sent = await ok<{
clientMessageId: string
submission: { dispatchState: string; providerItemId: string | null }
}>('agentSession.send', {
envelope: envelope('agentSession.send', { body }, fence),
body
})
// Accepted sends stay pending without identity until the provider echo.
expect(sent.submission).toMatchObject({ dispatchState: 'pending', providerItemId: null })
await handedOverAs({
threadId: THREAD,
clientUserMessageId: sent.clientMessageId,
model: 'gpt-live',
effort: 'high'
})
codex.notify('turn/started', { turn: { id: TURN } })
// The echo must settle into the pending client bubble without appending a duplicate.
codex.notify('item/completed', {
item: {
type: 'userMessage',
id: 'item-0',
clientId: sent.clientMessageId,
content: [{ type: 'text', text: 'list files' }]
}
})
await drainStreamedEvents()
expect(itemsOf(stream).filter((item) => textOf(item) === 'list files')).toHaveLength(1)
// Use the echo identity so replay computes the same key.
await vi.waitFor(async () =>
expect(await submissionOf(sent.clientMessageId)).toMatchObject({
dispatchState: 'accepted',
providerItemId: `codex:${THREAD}:${TURN}:0`
})
)
codex.notify('item/started', { item: { type: 'agentMessage', id: 'item-1', text: '' } })
codex.notify('item/agentMessage/delta', { itemId: 'item-1', delta: 'Two ' })
codex.notify('item/agentMessage/delta', { itemId: 'item-1', delta: 'files.' })
await drainStreamedEvents()
// Before 60ms the coalescer must hold both deltas without journaling a partial row.
expect(itemsOf(stream).filter((item) => textOf(item).startsWith('Two'))).toEqual([])
codex.notify('item/completed', {
item: { type: 'agentMessage', id: 'item-1', text: 'Two files.' }
})
await drainStreamedEvents()
const answer = itemsOf(stream).find((item) => textOf(item) === 'Two files.')
// Keyed by (threadId, turnId, ordinal), so a resumed thread reuses this row.
expect(answer?.itemId).toBe(`codex:${THREAD}:${TURN}:1`)
codex.notify('item/started', {
item: { type: 'commandExecution', id: 'item-2', command: 'ls -la', status: 'inProgress' }
})
codex.ask(7, 'item/commandExecution/requestApproval', {
threadId: THREAD,
turnId: TURN,
itemId: 'item-2',
availableDecisions: ['accept', 'decline']
})
await drainStreamedEvents()
const approval = itemsOf(stream).find((item) => item.body?.kind === 'approval')
expect(approval?.body).toMatchObject({ title: 'Run a command?', detail: 'ls -la' })
const answered = await ok<{ resolution: { state: string; selectedOptionId: string } }>(
'agentSession.respondToApproval',
{
envelope: envelope(
'agentSession.respondTo:approval',
{
itemId: approval?.itemId,
expectedRevision: approval?.revision,
optionId: 'accept'
},
fence
),
itemId: approval?.itemId,
expectedRevision: approval?.revision,
optionId: 'accept'
}
)
expect(answered.resolution).toMatchObject({ state: 'resolved', selectedOptionId: 'accept' })
expect(codex.live().replies).toEqual([{ id: 7, result: { decision: 'accept' } }])
const cancelled = await ok<{ turnId: string; cancelled: boolean }>('agentSession.cancel', {
envelope: envelope('agentSession.cancel', { turnId: TURN }, fence),
turnId: TURN
})
expect(cancelled).toEqual({ turnId: TURN, cancelled: true })
expect(codex.live().calls.slice(-3)).toEqual([
{ method: 'thread/goal/get', params: { threadId: THREAD } },
{ method: 'turn/interrupt', params: { threadId: THREAD, turnId: TURN } },
{ method: 'thread/goal/get', params: { threadId: THREAD } }
])
// Disconnect reaps the subscription while retaining the session and child.
await call('agentSession.unsubscribe', { sessionId: SESSION })
const lastCursor = cursorOf(stream)
codex.notify('item/completed', {
item: { type: 'agentMessage', id: 'item-3', text: 'Stopped.' }
})
codex.notify('turn/completed', { turn: { id: TURN } })
await drainStreamedEvents()
const missed = await subscribe('sub-2', lastCursor)
expect(missed[0]?.type).toBe('batch')
expect(
itemsOf(missed).some(
(item) => item.body?.kind === 'tool-call' && item.body.state === 'failed'
)
).toBe(true)
expect(itemsOf(missed).map(textOf).filter(Boolean)).toEqual(['Stopped.'])
// Stop closes the old child; takeover advances the fence and resumes the proven thread.
const reaped = codex.live()
await vi.waitFor(() => expect(reaped.closed).toBe(true))
await getStructuredAgentSessionHost()
?.collaboratorsForTests()
.serialize(SESSION, async () => {})
const stoppedFence =
getStructuredAgentSessionHost()?.deps.store.getRecord(SESSION)?.lease.runtimeFence ?? fence
const resumed = await ok<{ fence: number; page: { items: AgentJournalRenderItem[] } }>(
'agentSession.ensure',
attachParams(stoppedFence)
)
expect(resumed.fence).toBe(stoppedFence + 1)
expect(codex.live().resumedThreadId).toBe(THREAD)
expect(await readKnownOptions()).toMatchObject({
ok: true,
result: { current: { effort: 'high' } }
})
expect(resumed.page.items.map(textOf)).toContain('Two files.')
const tail = await historyPage('tail', { limit: 2 })
expect(tail.ok).toBe(true)
if (!tail.ok) {
throw new Error('history reset')
}
expect(tail.page.hasOlder).toBe(true)
const older = await historyPage('before', {
cursor: tail.page.window.nextCursor,
limit: 10
})
if (!older.ok) {
throw new Error('history reset')
}
expect(older.page.hasOlder).toBe(false)
// Pages must cover the streamed conversation without overlap; turn lifecycle rows are revised, never tombstoned.
expect([...older.page.items, ...tail.page.items].map((item) => item.body?.kind)).toEqual([
'message',
'turn',
'message',
'tool-call',
'approval',
'status',
'message'
])
expect([...older.page.items, ...tail.page.items].map(textOf)).toEqual([
'list files',
'',
'Two files.',
'',
'',
'',
'Stopped.'
])
})
it('caches shell exports but re-reads configured overrides for a resume', async () => {
shellEnvironmentPolicy = { inheritAll: false, names: [] }
const created = await ok<{ fence: number }>('agentSession.create', createIntentParams())
expect(codex.live().launch.env?.EXAMPLE_GATEWAY_TOKEN).toBeUndefined()
expect(bootEnvironmentReads).toBe(1)
const beforeResume = codexOverrideReads
configuredCodexProfile = 'updated'
shellEnvironmentPolicy = { inheritAll: false, names: ['EXAMPLE_GATEWAY_TOKEN'] }
const resumed = await ok<{ fence: number }>('agentSession.ensure', attachParams(created.fence))
expect(resumed.fence).toBe(created.fence + 1)
expect(codex.live().resumedThreadId).toBe(THREAD)
expect(codex.live().launch.env).toMatchObject({
CODEX_PROFILE: 'updated',
EXAMPLE_GATEWAY_TOKEN: 'shell-exported'
})
expect(bootEnvironmentReads).toBe(1)
expect(codexOverrideReads).toBeGreaterThan(beforeResume)
})
it('refuses to build a host for a client that never advertised the capability', async () => {
const replies: RpcResponse[] = []
await dispatcher.dispatchStreaming(
{
id: 'req-gate',
authToken: 'token',
method: 'agentSession.create',
params: attachParams(null)
},
(raw) => replies.push(JSON.parse(raw)),
{ clientKind: 'runtime', clientCapabilities: ['terminal.stream.v1'] }
)
expect(replies[0]).toMatchObject({ ok: false })
// Gate before host construction, which opens storage and can spawn children.
expect(getStructuredAgentSessionHost()).toBeNull()
expect(codex.connections).toEqual([])
})
it('joins final deferred writes before runtime teardown completes', async () => {
await ok<{ fence: number }>('agentSession.create', createIntentParams())
codex.notify('turn/started', { threadId: THREAD, turn: { id: TURN } })
codex.notify('item/started', {
threadId: THREAD,
turnId: TURN,
item: { type: 'agentMessage', id: 'item-final', text: '' }
})
await drainStreamedEvents()
codex.notify('item/agentMessage/delta', {
threadId: THREAD,
turnId: TURN,
itemId: 'item-final',
delta: 'Final text before shutdown.'
})
const host = getStructuredAgentSessionHost()
const journal = (
host as unknown as { sessions: Map<string, { journal: AgentSessionJournal }> }
).sessions.get(SESSION)!.journal
const appendEntered = Promise.withResolvers<void>()
const appendGate = Promise.withResolvers<void>()
const originalAppend = journal.appendItem.bind(journal)
vi.spyOn(journal, 'appendItem').mockImplementationOnce(async (...args) => {
appendEntered.resolve()
await appendGate.promise
return originalAppend(...args)
})
let stopped = false
const stopping = stopStructuredAgentSessionRuntime().then(() => {
stopped = true
})
await appendEntered.promise
await new Promise<void>((resolve) => setImmediate(resolve))
const waitedForFinalAppend = !stopped
appendGate.resolve()
await stopping
expect(waitedForFinalAppend).toBe(true)
const reopened = await journals.open({
identity: JOURNAL_IDENTITY,
stateDirectory: root
})
expect(reopened.snapshot().items.map(textOf)).toContain('Final text before shutdown.')
expect(
reopened
.snapshot()
.items.some(
(item) => item.body?.kind === 'status' && item.body.turnLifecycle?.state === 'running'
)
).toBe(false)
})
it('persists complete command output while publishing a shortened copy', async () => {
await ok<{ fence: number }>('agentSession.create', createIntentParams())
const stream = await subscribe('sub-large-output')
const output = 'large command output\n'.repeat(2_000)
codex.notify('item/completed', {
threadId: THREAD,
turnId: TURN,
item: {
type: 'commandExecution',
id: 'item-large-output',
command: 'print-many-lines',
status: 'completed',
exitCode: 0,
aggregatedOutput: output
}
})
await drainStreamedEvents()
const snapshot = await getStructuredAgentSessionHost()?.journalSnapshot(SESSION)
const item = snapshot?.items.find((candidate) => candidate.body?.kind === 'tool-call')
const bounded = item?.body?.kind === 'tool-call' ? item.body.output : undefined
expect(bounded).toMatchObject({ head: output, truncated: false, byteLength: output.length })
const published = itemsOf(stream).find((candidate) => candidate.itemId === item?.itemId)
expect(published?.shortened).toBe(true)
expect(published?.body).toMatchObject({
output: { head: output.slice(0, 16 * 1024), truncated: true, byteLength: output.length }
})
})
it('keeps an answered prompt resolved after the provider exits', async () => {
const created = await ok<{ fence: number }>('agentSession.create', createIntentParams())
codex.notify('turn/started', { threadId: THREAD, turn: { id: TURN } })
codex.notify('item/started', {
threadId: THREAD,
turnId: TURN,
item: {
type: 'commandExecution',
id: 'item-needs-answer',
command: 'build',
status: 'inProgress'
}
})
codex.ask(9, 'item/commandExecution/requestApproval', {
threadId: THREAD,
turnId: TURN,
itemId: 'item-needs-answer',
availableDecisions: ['accept', 'decline']
})
await drainStreamedEvents()
const host = getStructuredAgentSessionHost()
let snapshot = await host?.journalSnapshot(SESSION)
const approval = snapshot?.items.find((item) => item.body?.kind === 'approval')
expect(approval?.body).toMatchObject({
kind: 'approval',
resolution: { state: 'pending' }
})
await ok('agentSession.respondToApproval', {
envelope: envelope(
'agentSession.respondTo:approval',
{
itemId: approval?.itemId,
expectedRevision: approval?.revision,
optionId: 'accept'
},
created.fence
),
itemId: approval?.itemId,
expectedRevision: approval?.revision,
optionId: 'accept'
})
codex.live().handlers.onExit?.(new Error('provider exited after answer'))
await drainStreamedEvents()
snapshot = await host?.journalSnapshot(SESSION)
expect(snapshot?.items.find((item) => item.itemId === approval?.itemId)?.body).toMatchObject({
kind: 'approval',
resolution: { state: 'resolved', selectedOptionId: 'accept' }
})
})
})