Files
archived-orca/src/main/codex/codex-background-task-tracker.test.ts
T
f2af92b2fa feat(native-chat): show live background work and name each row by kind (#19705)
* fix(codex): reserve the label's share of a qualified command row

A child's label is raw provider text and was spliced into the command
row unbounded, then the pair clipped to the description cap. A label at
or past that cap clipped the command away entirely, leaving a row of
kind 'command' that named an agent and showed no command - the failure
qualification exists to remove, inverted. The same clip could also cut a
surrogate pair, which boundSubagentField already guards against on the
agent row two lines away.

Give the label a reserved share and clip it the way the agent row does.

* feat(native-chat): show live background work and name each row by kind

The strip suppressed itself in three places: the Claude tracker blanked
its roster for the whole of any turn, the Codex tracker returned nothing
while a primary turn was open, and the renderer view gated on
`turnId === null`. Between them, work in flight was never shown — and a
task backgrounded in an earlier turn vanished from the strip as soon as
the next prompt was sent. Claude additionally dropped every foreground
subagent, so a fan-out reported nothing at all.

Report work while it is live, in all three layers. Foreground Claude
work is turn-scoped, so `result` retires it — that is the provider's own
outcome for a task it marked foreground, not a roster sweep. Nothing
settles a Codex child on turn end: those keep reporting well past their
parent, so turn frames only prompt a republish.

Name each ROW by kind — Subagent, Shell command, Workflow, Monitor —
instead of a generic "Background <kind>", each drawing the glyph the
shared tool-icon table already uses for that category. A row that
carries a provider description still shows it unchanged. The collapsed
header summary is deliberately untouched; it is owned elsewhere.

The conversation-command gate is unchanged in effect: an open turn
already refuses first, and Claude foreground work never reaches the
backgrounded set the gate reads.

* fix(native-chat): withhold the row stop Claude foreground work cannot honour

The strip now publishes foreground rows, but `stoppableTaskIds` still filters
on `backgrounded`, so `stopClaudeBackgroundTasks` resolved an empty target list
and returned `{ cancelled: false }` that no renderer reads: the user clicked
"Stop Subagent" and nothing ever happened.

Carry stoppability per row instead of widening the stop to a target the SDK has
no way to reach. `AgentSessionBackgroundTask.stoppable` is absent-means-yes, so
hosts that predate it keep their working control, Claude emits `false` only on
foreground rows, and the strip hides that row's button the same way it already
hides the stop-all a provider cannot honour.

* fix(claude): scope aggregate-roster authority to the work it enumerates

`background_tasks_changed` lists BACKGROUNDED tasks, so a foreground subagent
can never appear in it. Treating it as the whole world meant any such frame
cleared every live foreground row mid-flight and then dropped every later
foreground `task_started` for the rest of the session, killing the in-turn
fan-out the strip exists to show in any session that ever backgrounds anything.

Decide `backgrounded` before the staleness guard and apply the guard only to a
backgrounded start, and retain live foreground entries across a roster replace.
Retained rows count against MAX_TRACKED_TASKS, so the map stays bounded, and a
stale backgrounded start the roster no longer lists is still dropped.

* test(native-chat): pin the strip's monitor amber to the constant that defines it

`MONITOR_GLYPH_COLOR`'s comment claimed a test held it and AgentStateDot's amber
together, but no test imported it — the assertions hardcoded 'text-yellow-500',
so the two could drift with every test still green. Read the colour from the
module, which is what the comment always said was happening. Drop the unused
`BackgroundTaskGlyph` export too: nothing outside the module names it.

* fix(native-chat): keep the task list open across a gap in live work

The strip is now mounted on live work, so a sequential fan-out unmounts it
between one subagent finishing and the next starting: local `useState` meant
the expanded list collapsed itself on every such gap, on top of the strip
flickering above the composer.

Hand the disclosure to the session, keyed by session id so it does not leak
across a session switch. The strip is now controlled and holds no state of its
own, which is what makes it survive its own mount churn.

* fix(codex): route every command-row cut through one surrogate-safe clip

`boundLabel` avoided splitting a pair, then `qualifiedDescription` re-cut the
COMPOSED string with a raw slice: label (<=96) plus separator plus description
(<=512) is up to 611 chars, so that second cut landed at an arbitrary index
inside the description and could publish a lone high surrogate — lossy through
any non-JSON UTF-8 hop. `parse` had the identical hazard on an unqualified
primary-thread command.

One `boundText` helper now owns all three cuts, so no path in the file can emit
a lone surrogate from well-formed input.

* fix(claude): keep terminal evidence for ids an aggregate roster never lists

Narrowing the admission guard to backgrounded starts left a finished FOREGROUND
id with no defence: `replaceAggregateRoster` wiped `terminalTaskIds` wholesale,
so after any `background_tasks_changed` a replayed `task_started` revived a task
whose completion had already been seen — and only a later `result` could settle
it again.

Scope the wipe the same way the guard was scoped: delete only the ids the
incoming roster actually enumerates. A roster still overrules terminal evidence
for the work it lists, which is what that behaviour was added for.

* fix(claude): keep retained rows in place and evict the stalest, not the newest

Re-adding retained foreground entries after the roster made a live row the user
is reading jump below the backgrounded rows on every `background_tasks_changed`,
and the cap `break` kept the STALEST retained rows while dropping the newest.

Merge in the tracked map's own order so a surviving row holds its position, and
count the overflow up front so eviction takes the oldest retained rows. Roster
entries are never starved and the map stays bounded either way.

* fix(claude): retire leftover foreground rows when the next turn starts

A foreground `task_started` arriving with no turn open has no `result` coming
to retire it, so it sat in the strip indefinitely — with no per-row stop, since
foreground rows are not stoppable — and refused conversation commands behind an
instruction nobody could follow.

Settle on turn start as well as on `result`. This is cleanup only: visibility
never consults `startsTurn`, so a missed one degrades to today's behaviour and
can never switch the feature off. It shortens the row's life to the next turn;
the case where no further turn is ever sent is filed separately.

* fix(agent-session): withhold unstoppable rows from readers that predate them

Rule 3 of remote-wire-compatibility: changing what the host publishes reaches
old clients with no wire change. The Claude host published no foreground rows
before this feature; it does now, and a client that cannot read `stoppable`
draws a per-row Stop on every one of them — Claude always sets
`supportsTaskStop` — which filters to the backgrounded ids, stops nothing, and
returns a result no renderer inspects. That is the dead button `stoppable` was
added to remove, reappearing across a version skew.

Negotiate it. A client can advertise the existing background-task-stop
capability and still predate `stoppable`, so this needs its own constant.
Readers that do not advertise it get unstoppable rows dropped, and a state whose
every row is dropped becomes no strip — exactly their pre-feature view.

RUNTIME_PROTOCOL_VERSION is not bumped: this adds an optional field and a new
negotiated capability, and changes no existing field's meaning, which is the
explicit do-not-bump case in protocol-version.ts.

* test(agent-session): name the projected rows so the fixture typechecks

An indexed lookup into the fixture's task list is possibly-undefined under
`pnpm tc`; the rows are more readable named anyway.

* test(web): advertise the row-stop capability in the e2ee auth expectation

The web e2ee handshake started sending
AGENT_SESSION_BACKGROUND_TASK_ROW_STOP_CAPABILITY, and this test asserts the
advertised list by deep equality, so it went red on CI while every targeted
test run stayed green. Add the capability in the position the router sends it.

* test(claude): pin why the roster empties mid-turn in a sequential fan-out

The strip unmounting between two sequential subagents is truthful, not a swept
row: A leaves on the provider's own terminal frame, B does not exist yet, and
backgrounded work spanning the same gap holds the roster open — so an empty
roster is never work the strip is hiding.

Also pins the previous-turn rule against the one the subagent roster already
applies on the same frame: a still-working FOREGROUND child becomes
`unverifiable` there and a backgrounded one is left alone, so the strip drops
the first and keeps the second rather than asserting `live` for either.

---------

Co-authored-by: Merge Sim <merge-sim@users.noreply.github.com>
Co-authored-by: Merge Sim <sim@local>
2026-09-10 12:16:30 -07:00

348 lines
14 KiB
TypeScript

import { describe, expect, it } from 'vitest'
import { CodexBackgroundTaskTracker } from './codex-background-task-tracker'
import {
readCodexBackgroundTaskFrame,
type CodexBackgroundTaskEvent
} from './codex-background-task-frames'
const PRIMARY = 'parent-thread'
const PARENT_TURN = 'parent-turn'
const CHILD = 'child-thread'
const CHILD_TURN = 'child-turn'
function turn(
method: 'turn/started' | 'turn/completed',
threadId: string,
turnId: string,
status = 'completed'
): CodexBackgroundTaskEvent {
return { method, threadId, params: { threadId, turn: { id: turnId, status } } }
}
function activity(
kind = 'started',
parentTurn = PARENT_TURN,
child = CHILD,
name = 'count_a'
): CodexBackgroundTaskEvent {
return {
method: 'item/started',
threadId: PRIMARY,
params: {
threadId: PRIMARY,
turnId: parentTurn,
item: {
type: 'subAgentActivity',
id: `activity-${kind}`,
kind,
agentThreadId: child,
agentPath: `/root/${name}`
}
}
}
}
function runningChild(): CodexBackgroundTaskTracker {
const tracker = new CodexBackgroundTaskTracker(PRIMARY)
tracker.observe(turn('turn/started', PRIMARY, PARENT_TURN))
tracker.observe(turn('turn/started', CHILD, CHILD_TURN))
tracker.observe(activity())
return tracker
}
function command(
threadId = PRIMARY,
method = 'item/started',
commandText = 'sleep 90'
): CodexBackgroundTaskEvent {
return {
method,
threadId,
params: {
threadId,
turnId: PARENT_TURN,
item: {
type: 'commandExecution',
id: 'exec-1',
processId: '71831',
source: 'unifiedExecStartup',
command: commandText,
status: method === 'item/started' ? 'inProgress' : 'completed'
}
}
}
}
describe('readCodexBackgroundTaskFrame', () => {
it('reads activity as child metadata without inferring execution state', () => {
expect(readCodexBackgroundTaskFrame(activity('interacted'), PRIMARY)).toEqual({
kind: 'subagent',
agentThreadId: CHILD,
label: 'count_a',
parentTurnId: PARENT_TURN
})
})
it('reads a child turn with its own execution identity', () => {
expect(readCodexBackgroundTaskFrame(turn('turn/started', CHILD, CHILD_TURN), PRIMARY)).toEqual({
kind: 'turn',
threadId: CHILD,
turnId: CHILD_TURN,
state: 'working'
})
})
it('does not register the primary thread even when its activity path is missing', () => {
const event = activity('interacted', PARENT_TURN, PRIMARY)
;(event.params as { item: { agentPath?: string } }).item.agentPath = undefined
expect(readCodexBackgroundTaskFrame(event, PRIMARY)).toBeNull()
})
})
describe('CodexBackgroundTaskTracker child execution ownership', () => {
it('does not claim work from an activity item without a child turn', () => {
const tracker = new CodexBackgroundTaskTracker(PRIMARY)
tracker.observe(activity())
tracker.observe(activity('interacted'))
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
expect(tracker.state).toBeNull()
})
it('reports an executing child while the spawning turn is still open', () => {
const tracker = runningChild()
const running = {
state: 'monitoring',
supportsStopAll: false,
tasks: [{ id: `codex-agent:${CHILD}`, kind: 'agent', description: 'count_a' }]
}
// The strip is a live view: a fan-out is reported while it runs, not once
// the parent turn happens to end.
expect(tracker.state).toEqual(running)
// Turn end reveals children, it never settles them; the child is unchanged.
expect(tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))).toBe(false)
expect(tracker.state).toEqual(running)
})
it('never settles a child when a primary turn ends', () => {
const tracker = runningChild()
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
for (let index = 0; index < 300; index++) {
expect(tracker.observe(turn('turn/completed', PRIMARY, `later-${index}`))).toBe(false)
}
expect(tracker.state?.tasks).toHaveLength(1)
})
it.each(['completed', 'interrupted', 'failed'])(
'settles on the matching child turn %s',
(status) => {
const tracker = runningChild()
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
expect(tracker.observe(turn('turn/completed', CHILD, CHILD_TURN, status))).toBe(true)
expect(tracker.state).toBeNull()
}
)
it('does not mistake late activity completion for the current child execution', () => {
const tracker = runningChild()
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
tracker.observe(activity('completed'))
expect(tracker.state?.tasks).toHaveLength(1)
})
it.each([PARENT_TURN, 'followup-parent'])(
'reports follow-up work in %s using the new child turn',
(parentTurn) => {
const tracker = runningChild()
tracker.observe(turn('turn/completed', CHILD, CHILD_TURN))
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
tracker.observe(turn('turn/started', PRIMARY, parentTurn))
tracker.observe(activity('interacted', parentTurn))
expect(tracker.state).toBeNull()
tracker.observe(turn('turn/started', CHILD, 'followup-child-turn'))
tracker.observe(turn('turn/completed', PRIMARY, parentTurn))
expect(tracker.state?.tasks).toHaveLength(1)
tracker.observe(turn('turn/completed', CHILD, CHILD_TURN))
tracker.observe(turn('turn/started', CHILD, CHILD_TURN))
tracker.observe(activity('completed'))
expect(tracker.state?.tasks).toHaveLength(1)
tracker.observe(turn('turn/completed', CHILD, 'followup-child-turn'))
expect(tracker.state).toBeNull()
}
)
it('keeps idle send_message activity out of the strip', () => {
const tracker = runningChild()
tracker.observe(turn('turn/completed', CHILD, CHILD_TURN))
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
tracker.observe(activity('interacted', 'message-parent'))
tracker.observe(turn('turn/completed', PRIMARY, 'message-parent'))
expect(tracker.state).toBeNull()
})
it('does not invent another execution for a message to a working child', () => {
const tracker = runningChild()
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
tracker.observe(activity('interacted', 'message-parent'))
tracker.observe(turn('turn/completed', PRIMARY, 'message-parent'))
expect(tracker.state?.tasks).toHaveLength(1)
tracker.observe(turn('turn/completed', CHILD, CHILD_TURN))
expect(tracker.state).toBeNull()
})
it('retains completion delivered before child registration', () => {
const tracker = new CodexBackgroundTaskTracker(PRIMARY)
tracker.observe(turn('turn/started', CHILD, CHILD_TURN))
tracker.observe(turn('turn/completed', CHILD, CHILD_TURN))
tracker.observe(activity())
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
expect(tracker.state).toBeNull()
})
it('publishes no extra state for duplicate owner or metadata events', () => {
const tracker = runningChild()
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
expect(tracker.observe(turn('turn/started', CHILD, CHILD_TURN))).toBe(false)
expect(tracker.observe({ ...activity(), method: 'item/completed' })).toBe(false)
expect(tracker.observe(turn('turn/completed', CHILD, CHILD_TURN))).toBe(true)
expect(tracker.observe(turn('turn/completed', CHILD, CHILD_TURN))).toBe(false)
})
it('bounds retained child history while allowing repeated completed runs', () => {
const tracker = new CodexBackgroundTaskTracker(PRIMARY)
tracker.observe(activity())
for (let index = 0; index < 300; index++) {
const id = `child-turn-${index}`
tracker.observe(turn('turn/started', CHILD, id))
expect(tracker.state?.tasks).toHaveLength(1)
tracker.observe(turn('turn/completed', CHILD, id))
expect(tracker.state).toBeNull()
}
})
it('clears the roster at session teardown', () => {
const tracker = runningChild()
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
expect(tracker.clear()).toBe(true)
expect(tracker.state).toBeNull()
expect(tracker.clear()).toBe(false)
})
})
describe('CodexBackgroundTaskTracker command integration', () => {
it('keeps a primary shell visible from launch until its own completion', () => {
const tracker = new CodexBackgroundTaskTracker(PRIMARY)
const shell = [{ id: 'codex-command:primary:exec-1', kind: 'command', description: 'sleep 90' }]
tracker.observe(turn('turn/started', PRIMARY, PARENT_TURN))
tracker.observe(command())
// Visible while the turn that launched it is still running.
expect(tracker.state?.tasks).toEqual(shell)
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
expect(tracker.state?.tasks).toEqual(shell)
// Only the shell's own completion retires the row.
tracker.observe(command(PRIMARY, 'item/completed'))
expect(tracker.state).toBeNull()
})
it('reveals a child shell only after the child execution finishes', () => {
const tracker = runningChild()
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
tracker.observe(command(CHILD))
expect(tracker.state?.tasks).toHaveLength(1)
tracker.observe(turn('turn/completed', CHILD, CHILD_TURN, 'interrupted'))
expect(tracker.state?.tasks).toEqual([
{
id: `codex-command:thread:${CHILD}:exec-1`,
kind: 'command',
description: 'count_a — sleep 90'
}
])
tracker.observe(command(CHILD, 'item/completed'))
expect(tracker.state).toBeNull()
})
it('leaves a primary shell unqualified', () => {
const tracker = runningChild()
tracker.observe(command(PRIMARY))
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
expect(tracker.state?.tasks).toContainEqual({
id: 'codex-command:primary:exec-1',
kind: 'command',
description: 'sleep 90'
})
})
it('keeps the command visible under a label that would otherwise fill the row', () => {
const tracker = new CodexBackgroundTaskTracker(PRIMARY)
tracker.observe(turn('turn/started', PRIMARY, PARENT_TURN))
tracker.observe(turn('turn/started', CHILD, CHILD_TURN))
tracker.observe(activity('started', PARENT_TURN, CHILD, 'L'.repeat(600)))
tracker.observe(command(CHILD))
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
tracker.observe(turn('turn/completed', CHILD, CHILD_TURN))
const description = tracker.state?.tasks?.[0]?.description
expect(description).toContain('sleep 90')
expect(description).toBe(`${'L'.repeat(95)}… — sleep 90`)
})
it('never cuts a label mid surrogate pair', () => {
const tracker = new CodexBackgroundTaskTracker(PRIMARY)
tracker.observe(turn('turn/started', PRIMARY, PARENT_TURN))
tracker.observe(turn('turn/started', CHILD, CHILD_TURN))
tracker.observe(activity('started', PARENT_TURN, CHILD, `${'L'.repeat(94)}\u{1F600}bad`))
tracker.observe(command(CHILD))
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
tracker.observe(turn('turn/completed', CHILD, CHILD_TURN))
const description = tracker.state?.tasks?.[0]?.description ?? ''
expect(description.isWellFormed()).toBe(true)
expect(description).toBe(`${'L'.repeat(94)}… — sleep 90`)
})
it('never cuts a qualified command mid surrogate pair', () => {
// The label is bounded, then the COMPOSED row is bounded again. That second
// cut lands inside the description, so clipping only the label side leaves a
// lone surrogate — lossy through any non-JSON UTF-8 hop.
const tracker = new CodexBackgroundTaskTracker(PRIMARY)
tracker.observe(turn('turn/started', PRIMARY, PARENT_TURN))
tracker.observe(turn('turn/started', CHILD, CHILD_TURN))
tracker.observe(activity('started', PARENT_TURN, CHILD, 'L'.repeat(96)))
// Places the pair exactly where a raw slice of the composed row splits it.
tracker.observe(command(CHILD, 'item/started', `${'C'.repeat(412)}\u{1F600}${'D'.repeat(200)}`))
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
tracker.observe(turn('turn/completed', CHILD, CHILD_TURN))
const description = tracker.state?.tasks?.[0]?.description ?? ''
expect(description.length).toBeLessThanOrEqual(512)
expect(description.startsWith(`${'L'.repeat(96)} — `)).toBe(true)
expect(description.isWellFormed()).toBe(true)
})
it('never cuts an unqualified primary command mid surrogate pair', () => {
const tracker = new CodexBackgroundTaskTracker(PRIMARY)
tracker.observe(turn('turn/started', PRIMARY, PARENT_TURN))
// The pair straddles the raw description bound itself.
tracker.observe(
command(PRIMARY, 'item/started', `${'C'.repeat(511)}\u{1F600}${'D'.repeat(50)}`)
)
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
const description = tracker.state?.tasks?.[0]?.description ?? ''
expect(description.length).toBeLessThanOrEqual(512)
expect(description.isWellFormed()).toBe(true)
})
it('names a child shell whose label only arrives after the command', () => {
const tracker = new CodexBackgroundTaskTracker(PRIMARY)
tracker.observe(turn('turn/started', PRIMARY, PARENT_TURN))
tracker.observe(turn('turn/started', CHILD, CHILD_TURN))
tracker.observe(command(CHILD))
tracker.observe(turn('turn/completed', PRIMARY, PARENT_TURN))
tracker.observe(activity())
tracker.observe(turn('turn/completed', CHILD, CHILD_TURN))
expect(tracker.state?.tasks).toEqual([
{
id: `codex-command:thread:${CHILD}:exec-1`,
kind: 'command',
description: 'count_a — sleep 90'
}
])
})
})