Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
import { readApprovalInputPreview } from '@hooks/domain/trackerToProgress'
import { classifyTier } from '@hooks/useTaskTier'
import { buildResponseFileAttachments } from '@lib/chatMessageAttachments'
import {
extractAssistantReply,
isAuthorizationError,
isConfirmedHostAccessRevoked,
} from '@lib/format'
import type { ProgressStep } from '@/uiTypes'
import type {
ChatMessageAttachment,
SessionTokensLite,
TaskProgressStreamEvent,
} from '../../../../src/types'
import {
type AgentTaskTracker,
type AttachOptions,
type ResendPayload,
type TaskKey,
type TaskPendingApproval,
type TaskState,
type TrackerCallbacks,
parseTaskKey,
} from './types'
/** No `open` within this window → treat the stream as failed to connect. */
const CONNECTION_TIMEOUT_MS = 5_000
/** Watchdog tick cadence. */
const WATCHDOG_INTERVAL_MS = 5_000
/** No SSE event for this long (with no terminal) → trip the idle watchdog. */
const WATCHDOG_IDLE_MS = 30_000
/**
* Max consecutive re-rejoins for one key before we stop re-rejoining and let the
* task settle (idle/offline). A re-rejoin happens when a stream-loss terminal
* triggers `onTrackerTerminal` → reconcile → `rejoinIfRunning`; if the re-opened
* SSE never reaches a real `open`/terminal under sustained network stress, the
* connect/idle timers would otherwise loop "Connecting" forever. The counter is
* reset on a real `open`, a fresh `start`, or `resetRejoinAttempts` (P1-B).
*/
const MAX_REJOIN_ATTEMPTS = 3
function errMessage(err: unknown): string {
return err instanceof Error ? err.message : String(err)
}
/**
* Folds the OPEN pause segment (if any) into the `pausedMs` accumulator and
* re-establishes the §AC3 invariant `pausedAt !== undefined` ⟺ segment OPEN.
*
* The D.5b tier is meant to measure how long the AGENT has been working, not
* wall-clock: freezing the clock while suspended is only half of it, because on
* resume the age would jump back to `now - startedAt` and swallow the whole
* human wait (approve after 10min → instant T4 "your agent is still working").
* Closed segments live here; the open one stays covered by the `pausedAt`
* freeze in `useTaskTier`. Idempotent (no open segment → no-op), so callers can
* invoke it defensively on any resume/terminal path.
*/
function closePauseSegment(s: TaskState): void {
if (s.pausedAt === undefined) return
s.pausedMs = (s.pausedMs ?? 0) + Math.max(0, Date.now() - s.pausedAt)
s.pausedAt = undefined
}
/**
* Lifecycle owner for in-flight agent tasks. Lives in a React context provider
* (so it survives controller re-renders) but is a plain class — testable
* without React. Each task is keyed by (agentRef, chatId); the SSE progress
* stream, the 5s connect timeout and the 30s idle watchdog are owned here, not
* in the controller closure (pre-D.3 they lived inside `sendAgentMessage`).
*/
export class TaskTracker implements AgentTaskTracker {
private states = new Map<TaskKey, TaskState>()
private listeners = new Map<TaskKey, Set<(s: TaskState) => void>>()
private unsubs = new Map<TaskKey, () => Promise<void>>()
private connTimers = new Map<TaskKey, ReturnType<typeof setTimeout>>()
private watchdogTimers = new Map<TaskKey, ReturnType<typeof setInterval>>()
private terminalFired = new Set<TaskKey>()
/**
* Keys whose SSE already delivered a `terminal` event, set BEFORE the
* terminal-completed branch awaits `getTaskResult`. `terminalFired` alone
* can't guard that window: the bridge emits `closed` right behind `terminal`
* (replay-then-close on a finished task), and `closed` running during the
* fetch await would fire a spurious `source:'stream'` terminal, turning a
* successful reply into a stream-loss (C-race, spec Anexo C.2 paso 4).
*/
private terminalReceived = new Set<TaskKey>()
/** Consecutive re-rejoins per key with no intervening real `open`/terminal. */
private rejoinAttempts = new Map<TaskKey, number>()
/**
* Coordinator-owned Resend payloads keyed by taskId (B15). Explicit lifecycle:
* written by `setResend` at send time, cleared in `release` (the key's teardown)
* — a stream-loss on a NON-visible chat no longer destroys the payload of a
* still-live task, since that path defers `release` to reconcile (B11).
*/
private pendingResend = new Map<string, ResendPayload>()
private callbacks: TrackerCallbacks = { onTerminal: () => undefined }
setCallbacks(cb: TrackerCallbacks): void {
this.callbacks = { ...this.callbacks, ...cb }
}
start(key: TaskKey, taskId: string, userMessageId: string): void {
// Thin wrapper over the coordinator `attach` (single open path, spec §4.2).
this.attach(key, taskId, userMessageId, { reason: 'send', armConnTimeout: true })
}
/**
* Coordinator open path (spec-v2 §4.2). Idempotent by `(key, taskId)`:
* - same taskId already tracked AND still LIVE → no-op (`true`).
* - same taskId but its terminal already fired (a B11 deferred non-visible
* stream-loss left a dead zombie that was NOT released to keep its Resend
* payload alive during the hidden window) → `release` + re-open, so a reopen
* rejoin actually re-attaches the SSE instead of no-oping on the corpse.
* - a DIFFERENT taskId tracked → `release` the old entry first (explicit
* teardown of its SSE unsub + timers + resend, never a silent clobber),
* then open the new one — closing B6 (a fresh task over a stale one) and B7
* (the stale entry's unsub can't leak, `release` tears it down).
* `reason:'rejoin'` consumes the bounded re-rejoin quota and returns `false`
* when capped; `reason:'send'`/`'reconcile'` reset the quota (a deliberate open
* always gets a full quota).
*/
attach(key: TaskKey, taskId: string, anchorMessageId: string, opts: AttachOptions = {}): boolean {
const existing = this.states.get(key)
if (existing) {
// Idempotent re-entry guard (B6) — but ONLY for a LIVE entry. A terminal-
// fired zombie of the same task (B11 deferred stream-loss) is dead; fall
// through to release + re-open so the rejoin genuinely re-subscribes.
if (existing.taskId === taskId && !this.terminalFired.has(key)) return true
// Re-opening the SAME task's dead zombie must NOT drop its Resend payload
// (B11: it lives until the reopen reconcile settles). `release` clears it by
// taskId, so preserve + restore for the identical task only.
const preservedResend =
existing.taskId === taskId ? this.pendingResend.get(taskId) : undefined
this.release(key)
if (preservedResend) this.pendingResend.set(taskId, preservedResend)
}
const isRejoin = opts.reason === 'rejoin'
if (isRejoin) {
const attempts = this.rejoinAttempts.get(key) ?? 0
if (attempts >= MAX_REJOIN_ATTEMPTS) return false
this.rejoinAttempts.set(key, attempts + 1)
} else {
// A fresh send / deliberate reconcile re-open is not a re-rejoin: reset the
// bounded counter so it always gets its full quota.
this.rejoinAttempts.delete(key)
}
const armConnTimeout = opts.armConnTimeout ?? !isRejoin
this.startInternal(key, taskId, anchorMessageId, armConnTimeout)
return true
}
setResend(taskId: string, payload: ResendPayload): void {
this.pendingResend.set(taskId, payload)
}
getResend(taskId: string): ResendPayload | undefined {
return this.pendingResend.get(taskId)
}
/** Alias of `ack`: total teardown for a key (SSE unsub, timers, entry, resend). */
release(key: TaskKey): void {
this.ack(key)
}
/** Release every tracked key — logout / team-switch / renderer unmount (R-F13,
* GAP-N4): no late terminal/side-effect can fire after this returns. */
releaseAll(): void {
for (const key of [...this.states.keys()]) this.release(key)
// Any orphan unsubs (subscription resolved after its entry was released) and
// dangling resend payloads are swept too.
for (const [key, unsub] of [...this.unsubs.entries()]) {
void unsub().catch(() => undefined)
this.unsubs.delete(key)
}
this.pendingResend.clear()
this.rejoinAttempts.clear()
}
/**
* Clear the bounded re-rejoin counter for a key. Called by a deliberate,
* user-initiated reconcile (e.g. opening the chat via `switchToChat`) so the
* user always gets a fresh rejoin quota — only the automatic stream-loss
* terminal → rejoin cycle is what the cap is meant to stop.
*/
resetRejoinAttempts(key: TaskKey): void {
this.rejoinAttempts.delete(key)
}
rejoinIfRunning(key: TaskKey, taskId: string, userMessageId?: string): boolean {
if (this.states.has(key)) return true // already following this key
// Bound re-rejoins: a stream-loss terminal triggers a reconcile that may
// re-rejoin a still-`processing` task. If the re-opened SSE keeps failing to
// `open` under sustained network stress, this would loop "Connecting"
// forever. After the cap, stop re-rejoining and settle (no entry created →
// idle/offline). The counter resets on a real `open` (genuine reconnect), a
// fresh `start` (new send), or `resetRejoinAttempts` (user-initiated
// reconcile) — never on the stream-loss `ack`, which would defeat the cap
// (P1-B). Return `false` on the capped no-op so the controller can surface a
// recovery affordance (offline banner) instead of a frozen stepper.
const attempts = this.rejoinAttempts.get(key) ?? 0
if (attempts >= MAX_REJOIN_ATTEMPTS) return false
this.rejoinAttempts.set(key, attempts + 1)
// Do NOT arm the 5s connect-timeout on a rejoin: a rejoin under the same
// network stress that dropped the stream legitimately needs longer to
// re-open, and a hard `source:'stream'` terminal here would immediately
// re-rejoin (the loop). The 30s idle watchdog remains the real liveness guard.
this.startInternal(key, taskId, userMessageId ?? '<unknown>', false)
return true
}
private startInternal(
key: TaskKey,
taskId: string,
userMessageId: string,
armConnTimeout: boolean
): void {
const now = Date.now()
this.states.set(key, {
taskId,
userMessageId,
status: 'connecting',
startedAt: now,
lastEventAt: now,
steps: [],
currentIteration: 0,
})
this.terminalFired.delete(key)
this.terminalReceived.delete(key)
this.emit(key)
if (armConnTimeout) this.armConnectionTimeout(key)
this.armWatchdog(key)
void this.openSse(key, taskId)
}
get(key: TaskKey): TaskState | undefined {
return this.states.get(key)
}
subscribe(key: TaskKey, fn: (s: TaskState) => void): () => void {
let set = this.listeners.get(key)
if (!set) {
set = new Set()
this.listeners.set(key, set)
}
set.add(fn)
const current = this.states.get(key)
if (current) fn({ ...current }) // sync-up: immediate emit of current state
return () => {
const s = this.listeners.get(key)
s?.delete(fn)
if (s && s.size === 0) this.listeners.delete(key)
}
}
ack(key: TaskKey): void {
// Drop the coordinator-owned Resend payload for this key's task (B15): the
// teardown is the single lifecycle point, so an ack without a terminal no
// longer retains the base64 attachments forever.
const acked = this.states.get(key)
if (acked) this.pendingResend.delete(acked.taskId)
this.states.delete(key)
// Listener registrations belong to the SUBSCRIBERS (the active chat's
// mirror effect, placeholders), not to the task: they were never torn down
// by an ack conceptually, and deleting them here silenced every later task
// on the same key — the active-chat mirror only re-subscribes on a
// chat/agent switch, so the next send rendered a frozen 'connecting'
// stepper (B1, spec Anexo C.1). Subscribers remove themselves via the
// unsubscribe fn returned by `subscribe`, which already prunes empty sets.
this.terminalFired.delete(key)
this.terminalReceived.delete(key)
// NOTE: intentionally do NOT reset `rejoinAttempts` here. The stream-loss
// reconcile acks the key BEFORE re-rejoining (useAgentChatController), so
// resetting here would zero the counter every cycle and defeat the cap. The
// counter is reset only on a real `open` (genuine reconnect) or a fresh
// `start` (new send) — both guarantee a clean quota.
this.clearTimers(key)
const unsub = this.unsubs.get(key)
if (unsub) {
void unsub().catch(() => undefined)
this.unsubs.delete(key)
}
}
async cancel(key: TaskKey): Promise<void> {
const state = this.states.get(key)
if (!state) return
const { agentRef } = parseTaskKey(key)
// Cross-ref D.3 P1: cancelTask signature is (hostRef, taskId) — no hostRefs[].
await window.clerum.rpc.cancelTask(agentRef, state.taskId)
// Do not mutate state here — wait for the SSE `terminal: cancelled`.
}
private emit(key: TaskKey): void {
const state = this.states.get(key)
if (!state) return
const set = this.listeners.get(key)
if (set) set.forEach(fn => fn({ ...state })) // shallow copy → referential change
}
/** Apply a mutation to the state and notify subscribers. */
private mutate(key: TaskKey, fn: (s: TaskState) => void): void {
const state = this.states.get(key)
if (!state) return
fn(state)
this.emit(key)
}
private armConnectionTimeout(key: TaskKey): void {
const timer = setTimeout(() => {
this.connTimers.delete(key)
// A genuine `terminal` already arrived and is awaiting `getTaskResult`
// (a slow durable fetch can outlast the 5s connect window). The terminal
// implies the stream connected, so there is nothing to time out — the
// real terminal handler owns completion and will fire/clear on its own.
// Skipping (mirrors the SSE `closed`/`error` guards) avoids overwriting a
// successful reply with a spurious `source:'stream'` failure. One-shot: no
// re-arm needed. When no terminal is pending this is a real dead-connect →
// fail as before.
if (this.terminalReceived.has(key)) return
this.mutate(key, s => {
s.status = 'failed'
s.terminalResult = {
kind: 'error',
source: 'stream',
message: 'Progress stream connection timeout',
}
})
void this.fireTerminal(key)
}, CONNECTION_TIMEOUT_MS)
this.connTimers.set(key, timer)
}
private armWatchdog(key: TaskKey): void {
const timer = setInterval(() => {
const state = this.states.get(key)
if (!state) {
this.clearWatchdog(key)
return
}
// A genuine `terminal` already arrived and is awaiting `getTaskResult`
// (a slow durable fetch can exceed the 30s idle window). The real
// `terminal` handler owns completion and will fire/clear on its own — the
// watchdog must NOT pre-empt it with a spurious stream-loss (mirrors the
// SSE `closed`/`error` guards, which also skip once `terminalReceived`).
// The interval is left running but simply no-ops each tick until the
// terminal path settles: `getTaskResult` is bounded by the RPC request
// timeout, so it always resolves or rejects into `fireTerminal` (both the
// success and the `result_fetch` catch branches), which clears every timer
// via `clearTimers`. No re-arm, no unbounded interval.
if (this.terminalReceived.has(key)) return
if (Date.now() - state.lastEventAt > WATCHDOG_IDLE_MS) {
this.clearWatchdog(key)
this.mutate(key, s => {
s.status = 'failed'
s.terminalResult = {
kind: 'error',
source: 'stream',
message: 'Watchdog: no terminal SSE received within 30s',
}
})
void this.fireTerminal(key)
}
}, WATCHDOG_INTERVAL_MS)
this.watchdogTimers.set(key, timer)
}
private clearConnectionTimeout(key: TaskKey): void {
const t = this.connTimers.get(key)
if (t) {
clearTimeout(t)
this.connTimers.delete(key)
}
}
private clearWatchdog(key: TaskKey): void {
const t = this.watchdogTimers.get(key)
if (t) {
clearInterval(t)
this.watchdogTimers.delete(key)
}
}
private clearTimers(key: TaskKey): void {
this.clearConnectionTimeout(key)
this.clearWatchdog(key)
}
private async openSse(key: TaskKey, taskId: string): Promise<void> {
const { agentRef } = parseTaskKey(key)
try {
const unsub = await window.clerum.rpc.subscribeTaskProgress(agentRef, taskId, event =>
this.handleEvent(key, event)
)
// B7 — staleness by (key, taskId), not key alone: between `attach` and this
// await resolving, the entry may have been RELEASED (acked/terminal) or
// REPLACED by a fresh task (`attach` of a new taskId released this one and
// opened another). Storing this now-stale unsub under `key` would either
// leak it (release already ran) or overwrite the live task's unsub (replace)
// — a doubled/orphaned socket (GAP-D4). Only keep it when the entry is still
// THIS exact task.
if (this.states.get(key)?.taskId !== taskId) {
void unsub().catch(() => undefined)
return
}
this.unsubs.set(key, unsub)
} catch (err) {
this.clearTimers(key)
this.mutate(key, s => {
s.status = 'failed'
s.terminalResult = { kind: 'error', source: 'stream', message: errMessage(err) }
})
void this.fireTerminal(key)
}
}
private async handleEvent(key: TaskKey, event: TaskProgressStreamEvent): Promise<void> {
const state = this.states.get(key)
if (!state || this.terminalFired.has(key)) return
state.lastEventAt = Date.now()
switch (event.type) {
case 'waiting':
// De-collapsed from `open` (spec-v2 §4.5-1, R6/B2b). The connection is
// ESTABLISHED (server acknowledged the subscription) but the reporter is
// NOT live yet — the task may be queued behind another (FIFO per session).
// So: clear the 5s connect-timeout (a legitimately queued fresh send must
// not be failed as a dead connect) but DO NOT reset the bounded re-rejoin
// counter — `waiting` does not prove task liveness. Only a real `open`
// does. Leaving the status at 'connecting' shows an honest Queued/Connecting
// stepper. `lastEventAt` is already bumped above (resets the idle watchdog).
this.clearConnectionTimeout(key)
return
case 'open':
this.clearConnectionTimeout(key)
// A real `open` proves the (re-)joined stream is live → reset the bounded
// re-rejoin counter so a future, unrelated drop gets its full quota. (Only
// a real `open` resets it now — the bridge no longer collapses `waiting`
// into `open`, so a mere connection-established no longer resets the cap.)
this.rejoinAttempts.delete(key)
this.mutate(key, s => {
// Don't downgrade a suspended approval to 'streaming': on a rejoin the
// server replays the sticky `suspended` event to the late subscriber
// (V2) BEFORE `open`, so `pendingApproval` may already be set — the
// `open` must preserve it until a real post-approve event arrives.
if (!s.pendingApproval) s.status = 'streaming'
})
return
case 'tool_start': {
const data = event.data as Record<string, unknown>
const step: ProgressStep = {
toolCallId: typeof data.toolCallId === 'string' ? data.toolCallId : crypto.randomUUID(),
toolName: typeof data.toolName === 'string' ? data.toolName : 'unknown',
displayName:
typeof data.displayName === 'string'
? data.displayName
: typeof data.toolName === 'string'
? data.toolName
: 'Tool',
intentSummary: typeof data.intentSummary === 'string' ? data.intentSummary : '',
iteration: typeof data.iteration === 'number' ? data.iteration : 0,
stepIndex: typeof data.stepIndex === 'number' ? data.stepIndex : 0,
totalSteps: typeof data.totalSteps === 'number' ? data.totalSteps : 0,
state: 'running',
inputPreview: typeof data.inputPreview === 'string' ? data.inputPreview : undefined,
}
const wasSuspended = state.status === 'suspended'
this.mutate(key, s => {
s.status = 'streaming'
s.llmElapsedMs = undefined
s.steps = [...s.steps, step]
s.currentIteration = step.iteration || s.currentIteration
// Execution moved past the approval (decided on ANY surface: in-chat,
// notification, another device) — drop it so the suspended affordance
// can't linger on a running task, and CLOSE the pause segment: the wait
// is over and must not count as agent work in the D.5b tier (§AC3).
if (wasSuspended) {
s.pendingApproval = undefined
closePauseSegment(s)
}
})
if (wasSuspended) this.fireResumed(key)
return
}
case 'tool_progress': {
const data = event.data as Record<string, unknown>
const targetId = typeof data.toolCallId === 'string' ? data.toolCallId : ''
const elapsedMs = typeof data.elapsedMs === 'number' ? data.elapsedMs : undefined
const rawPreview = data.outputPreview
const hasNewPreview =
rawPreview &&
typeof rawPreview === 'object' &&
Array.isArray((rawPreview as { headLines?: unknown }).headLines)
const freshPreview = hasNewPreview
? (rawPreview as ProgressStep['liveOutputPreview'])
: undefined
this.mutate(key, s => {
s.steps = s.steps.map(step =>
step.toolCallId === targetId && step.state === 'running'
? { ...step, elapsedMs, liveOutputPreview: freshPreview ?? step.liveOutputPreview }
: step
)
})
return
}
case 'tool_complete': {
const data = event.data as Record<string, unknown>
const targetId = typeof data.toolCallId === 'string' ? data.toolCallId : ''
const isError = Boolean(data.isError) || Boolean(data.errorSummary)
const durationMs = typeof data.durationMs === 'number' ? data.durationMs : undefined
const errorSummary = typeof data.errorSummary === 'string' ? data.errorSummary : undefined
const metadata =
data.metadata && typeof data.metadata === 'object' && !Array.isArray(data.metadata)
? (data.metadata as Record<string, unknown>)
: undefined
const rawPreview = data.outputPreview
const outputPreview =
rawPreview &&
typeof rawPreview === 'object' &&
Array.isArray((rawPreview as { headLines?: unknown }).headLines)
? (rawPreview as ProgressStep['outputPreview'])
: undefined
const rawTokens = data.tokens as
| { input?: unknown; output?: unknown; cacheRead?: unknown; cacheWrite?: unknown }
| undefined
const tokens =
rawTokens &&
typeof rawTokens === 'object' &&
typeof rawTokens.input === 'number' &&
typeof rawTokens.output === 'number' &&
(rawTokens.cacheRead === undefined || typeof rawTokens.cacheRead === 'number') &&
(rawTokens.cacheWrite === undefined || typeof rawTokens.cacheWrite === 'number')
? (rawTokens as SessionTokensLite)
: undefined
this.mutate(key, s => {
s.steps = s.steps.map(step =>
step.toolCallId === targetId
? {
...step,
state: isError ? ('error' as const) : ('completed' as const),
metadata,
durationMs,
tokens,
errorSummary,
outputPreview,
}
: step
)
})
return
}
case 'llm_in_progress': {
const data = event.data as Record<string, unknown>
const elapsedMs = typeof data.elapsedMs === 'number' ? data.elapsedMs : undefined
const iteration = typeof data.iteration === 'number' ? data.iteration : undefined
const wasSuspended = state.status === 'suspended'
this.mutate(key, s => {
s.status = 'streaming'
s.llmElapsedMs = elapsedMs
s.currentIteration = iteration ?? s.currentIteration
// Same resume bookkeeping as `tool_start` — the approval was decided and
// the pause segment closes here too (§AC3, tier = active time).
if (wasSuspended) {
s.pendingApproval = undefined
closePauseSegment(s)
}
})
if (wasSuspended) this.fireResumed(key)
return
}
case 'suspended': {
const sd = event.data
// OPEN a pause segment: stamp `pausedAt` ONLY on the TRANSITION into
// suspended (§AC3 freezes the D.5b tier timer at `pausedAt` so an approval
// wait can't escalate the nudges; the segment is closed into `pausedMs` on
// resume/terminal, which is what keeps the tier measuring ACTIVE time once
// the task runs again). This event is NOT once-per-suspension: mcp-host keeps the last
// `suspended` as a sticky event and replays it to every new subscriber, and
// the main-process bridge (`appService.startTaskProgressStream`) reconnects
// the SSE transparently whenever the 300s RPC token lapses mid-stream
// (`auth-expired`) — i.e. roughly every 5 min on a long approval wait. Each
// replay re-entering this branch used to re-stamp `pausedAt = now`, turning
// the "frozen" age (`pausedAt - startedAt`) back into full wall-clock and
// escalating the task to T3/T4/T5 while it sat suspended. Guarding on the
// PREVIOUS status keeps a genuine RE-suspension correct: a decided approval
// routes through `tool_start`/`llm_in_progress`, which set status back to
// 'streaming', so the next `suspended` is a real transition and re-stamps.
const wasSuspended = state.status === 'suspended'
this.mutate(key, s => {
s.status = 'suspended'
if (!wasSuspended) s.pausedAt = Date.now()
s.pendingApproval = sd.requestId
? {
requestId: sd.requestId,
displayName: sd.displayName || 'Unknown Tool',
// U5: preserved so downstream (stepper prompt, deep-link
// correlation) can distinguish a connect_required suspension and
// resume the right task. Undefined for ordinary approvals.
reason: sd.reason,
mcpServerName: sd.mcpServerName,
inputPreview: readApprovalInputPreview(
(sd as { inputPreview?: unknown }).inputPreview
),
}
: undefined
})
const updated = this.states.get(key)
if (updated?.pendingApproval) this.callbacks.onSuspended?.(key, { ...updated })
return
}
case 'terminal': {
// Mark the terminal as RECEIVED before any await: the bridge emits
// `closed` immediately behind `terminal` on a finished task, and the
// completed branch below awaits `getTaskResult` — without this flag the
// `closed` handler would win that window and fire a spurious
// stream-loss terminal, discarding the successful reply (C-race).
this.terminalReceived.add(key)
const td = event.data
if (td.status === 'cancelled') {
this.mutate(key, s => {
s.status = 'cancelled'
s.terminalResult = { kind: 'cancelled', reason: td.reason }
})
await this.fireTerminal(key)
return
}
if (td.status === 'failed' && td.error?.message) {
const failedTaskId = state.taskId
let attachments: ChatMessageAttachment[] = []
try {
const { agentRef } = parseTaskKey(key)
const result = await window.clerum.rpc.getTaskResult(agentRef, failedTaskId, [agentRef])
attachments = buildResponseFileAttachments(result)
} catch (error) {
if (isAuthorizationError(error)) {
if (this.states.get(key)?.taskId !== failedTaskId) return
this.mutate(key, s => {
s.status = 'failed'
s.terminalResult = {
kind: 'error',
source: 'authority',
message: 'Host authorization rejected',
authority: isConfirmedHostAccessRevoked(error) ? 'revoked' : 'uncertain',
}
})
await this.fireTerminal(key)
return
}
// Preserve the authoritative terminal error if artifact retrieval fails.
}
if (this.states.get(key)?.taskId !== failedTaskId) return
this.mutate(key, s => {
s.status = 'failed'
s.terminalResult = {
kind: 'error',
source: 'failed',
message: td.error!.message!,
...(attachments.length ? { attachments } : {}),
code: td.error!.code,
provider: td.error!.provider,
}
})
await this.fireTerminal(key)
return
}
// status === 'completed' (or 'failed' with no message) → fetch the result
const completedTaskId = state.taskId
try {
const { agentRef } = parseTaskKey(key)
const result = await window.clerum.rpc.getTaskResult(agentRef, completedTaskId, [
agentRef,
])
// Re-check identity after the await (mirrors openSse's B7 guard): an
// `attach`/resend may have RELEASED this key or REPLACED it with a fresh
// task while `getTaskResult` was in flight. Writing the old reply over the
// new task's state — and letting `fireTerminal` stamp `terminalFired` on
// it — would corrupt the live task into a permanent zombie (H2). Bail so
// only the superseding task's own terminal settles it.
if (this.states.get(key)?.taskId !== completedTaskId) return
const reply = extractAssistantReply(result)
const attachments = buildResponseFileAttachments(result)
// A durable failure may arrive after a terminal event with no error
// detail. Preserve that authoritative envelope; treating it as a reply
// would release the retained visual input and report false success.
const envelope = result as {
success?: boolean
error?: string | { message?: string; code?: string; provider?: string }
}
if (envelope.error || envelope.success === false || td.status === 'failed') {
const error = envelope.error
this.mutate(key, s => {
s.status = 'failed'
s.terminalResult = {
kind: 'error',
source: 'failed',
message: typeof error === 'string' ? error : (error?.message ?? 'The task failed.'),
code: typeof error === 'object' ? error.code : undefined,
provider: typeof error === 'object' ? error.provider : undefined,
...(attachments.length ? { attachments } : {}),
}
})
await this.fireTerminal(key)
return
}
this.mutate(key, s => {
s.status = 'completed'
s.terminalResult = {
kind: 'reply',
content: reply,
...(attachments.length ? { attachments } : {}),
}
})
} catch (error) {
// Same post-await identity guard on the failure branch — a replacement
// during the await must not have its state overwritten with this error.
if (this.states.get(key)?.taskId !== completedTaskId) return
this.mutate(key, s => {
s.status = 'failed'
s.terminalResult = {
kind: 'error',
source: isAuthorizationError(error) ? 'authority' : 'result_fetch',
message: isAuthorizationError(error)
? 'Host authorization rejected'
: 'Failed to retrieve task result after completion',
...(isAuthorizationError(error)
? {
authority: isConfirmedHostAccessRevoked(error)
? ('revoked' as const)
: ('uncertain' as const),
}
: {}),
}
})
}
await this.fireTerminal(key)
return
}
case 'error': {
// Transport-level stream error. Pre-stream-recovery this fell through to
// `default` (the 30s watchdog would eventually fail it). Now the bridge
// only emits `error` after exhausting its reconnect attempts (or on
// task_not_found_or_expired), so treat it as a definitive stream-loss
// terminal immediately — `onTrackerTerminal` then reconciles against the
// server (which may still hold the result or a pending approval). This
// closes the ~30s dead window between "bridge gave up" and "watchdog".
if (this.terminalFired.has(key) || this.terminalReceived.has(key)) return
this.mutate(key, s => {
s.status = 'failed'
s.terminalResult = {
kind: 'error',
source: 'stream',
message: event.message || 'Progress stream error',
}
})
await this.fireTerminal(key)
return
}
case 'gone': {
// Structured transport give-up (spec-v2 §4.5-2, R6): the main-process
// bridge exhausted its bounded reconnect or hit task_not_found_or_expired.
// NOT a task failure — treat it exactly like a definitive `error`
// stream-loss: fire a `source:'stream'` terminal so `onTrackerTerminal`
// reconciles against the server (re-attach if the server is still non-idle,
// else settle with the durable result / offline). The `reason` is carried
// through for telemetry/diagnostics.
if (this.terminalFired.has(key) || this.terminalReceived.has(key)) return
this.mutate(key, s => {
s.status = 'failed'
s.terminalResult = {
kind: 'error',
source: 'stream',
message: `Progress stream gone (${event.reason})`,
}
})
await this.fireTerminal(key)
return
}
case 'closed':
if (!this.terminalFired.has(key) && !this.terminalReceived.has(key)) {
this.mutate(key, s => {
s.status = 'failed'
s.terminalResult = {
kind: 'error',
source: 'stream',
message: 'Progress stream closed without terminal event',
}
})
await this.fireTerminal(key)
}
return
default:
// heartbeat / thinking / unknown — lastEventAt already bumped (resets watchdog).
return
}
}
/**
* A suspended task received a post-approval event — the approval was decided
* (approve on any surface, or deny of the single tool with the loop going
* on). Lets the controller flip the per-chat `awaiting_approval` badge back
* to `processing`; a stale badge would otherwise feed the approval re-seed
* effect and re-stamp a decided approval (C.2 loop, ingredients i+iv).
*/
private fireResumed(key: TaskKey): void {
const state = this.states.get(key)
if (state) this.callbacks.onResumed?.(key, { ...state })
}
private async fireTerminal(key: TaskKey): Promise<void> {
if (this.terminalFired.has(key)) return
this.terminalFired.add(key)
this.clearTimers(key)
// A task can reach terminal with its pause segment still OPEN — a denied
// approval that ends the run goes suspended → `terminal: cancelled` with no
// resume event in between, and a gate can also fail/time out. Close it here so
// the §AC3 invariant holds at terminal and the totals below are complete.
// Guarded: `mutate` always emits, and the common case (no open segment) must
// not fire an extra notification to every subscriber on each terminal.
if (this.states.get(key)?.pausedAt !== undefined) this.mutate(key, s => closePauseSegment(s))
const state = this.states.get(key)
if (!state) return
// Telemetry (§4.8): the coordinator owns the task lifecycle, so it emits the
// duration + elapsed-time tier on the terminal (moved off the hook, which
// previously logged it in `onTrackerTerminal`). `duration_ms` stays wall-clock
// (that's what the user waited), but the tier is classified off `active_ms`:
// the tier exists to describe how long the AGENT worked, and a long approval
// wait would otherwise report a T4/T5 that no nudge ever showed.
const durationMs = Date.now() - state.startedAt
const pausedMs = state.pausedMs ?? 0
const activeMs = Math.max(0, durationMs - pausedMs)
console.log('[telemetry] task_duration_seconds', {
duration_ms: durationMs,
paused_ms: pausedMs,
active_ms: activeMs,
status: state.status,
tier_at_terminal: classifyTier(activeMs),
})
// B8 — a throwing consumer callback must never wedge the coordinator: the
// timers are already cleared above (before the await), and the error is caught
// and reported via telemetry instead of bubbling as an unhandled rejection.
// Ack stays the consumer's job
// (a zombie entry may need to survive until a reconcile), so a throw before
// the consumer's ack still surfaces here rather than being silently lost.
try {
await this.callbacks.onTerminal(key, { ...state })
} catch (err) {
console.error('[telemetry] terminal_callback_error', { key, message: errMessage(err) })
// B8 — a THROW (not an intentional early `return`, e.g. B11's non-visible
// defer) means the consumer never reached its `ack`/defer decision: the
// entry + its SSE subscription would leak forever as a `terminalFired`
// zombie. Defensively tear the key down here. This only runs on an
// unexpected exception, so it can't defeat B11's deliberate deferral (which
// returns normally and is not caught).
this.ack(key)
}
// No automatic ack — the consumer acks once it has persisted/consumed the
// terminal state. This lets a controller sitting on a different chat pick up
// the result when the user returns.
}
}