@cocorograph/hub-agent 0.8.114 → 0.8.116

package/src/grok-stream-bridge.mjs

@@ -0,0 +1,756 @@
+import { randomUUID } from 'node:crypto'
+import { EventEmitter } from 'node:events'
+import { readPositiveIntEnv, sanitizePositiveInt } from './positive-int-env.mjs'
+import { GrokAcpClient } from './grok-acp-client.mjs'
+import { isUnderRemoval } from './chat-removal-guard.mjs'
+import { getOrCreateSiblingToken } from './sibling-token.mjs'
+
+// hub-bundle.mjs の HUB_MCP_NAMES と揃える。重い依存を避け、ここで定義する。
+const HUB_MCP_NAMES = new Set(['hub', 'hub_staff'])
+
+function siblingEnvFor(cwd, inherited = process.env) {
+  const env = {
+    ...inherited,
+    COCKPIT_SIBLING_TOKEN: getOrCreateSiblingToken(cwd),
+    COCKPIT_SIBLING_CWD: cwd,
+    COCKPIT_REVIEW_EVENTS: '1',
+    COCKPIT_DELEGATE_EVENT_ACK: '1',
+    COCKPIT_SIBLING_SELF_KIND: 'grok',
+  }
+  delete env.CLAUDE_CODE_SESSION_ID
+  delete env.CODEX_THREAD_ID
+  return env
+}
+
+// 完了済み配送 ID の保持上限。上限を超えた古い完了済み ID の再送は再実行されうる。
+const MAX_ACCEPTED_REQUEST_IDS = 500
+// 未完了（実行中・キュー待ち）の配送 ID の上限。超えたら受理せず busy を返す（未完了 ID は追い出さない）。
+const MAX_PENDING_DELIVERIES = 100
+// 連結した 1 件の履歴項目の上限（UTF-8 バイト）。超えるなら新しい項目に分けて、末尾 1 件にも
+// 履歴全体の上限が効くようにする（連結し続けると末尾 1 件が無制限に育つため）。
+const HISTORY_MERGE_MAX_BYTES = 64 * 1024
+const utf8Bytes = (value) => Buffer.byteLength(JSON.stringify(value), 'utf8')
+
+// Only extensions observed with Build 1.0.67 may receive an empty success response.
+const ignoredRequests = new Set([
+  'session/setup', 'mcp/init_progress', 'sessions/changed', 'queue/changed',
+  'mcp/server_status', 'models/update', 'settings/update', 'announcements/update',
+  'session_notification', 'mcp_initialized', 'session/prompt_complete',
+].map((name) => `_x.ai/${name}`))
+
+function promptFromMessage(message) {
+  const content = typeof message === 'string' ? message : message?.content
+  if (Array.isArray(content)) {
+    return content.filter((block) => block && block.type === 'text' && typeof block.text === 'string')
+      .map((block) => ({ type: 'text', text: block.text }))
+  }
+  return typeof content === 'string' && content.length ? [{ type: 'text', text: content }] : []
+}
+
+export class GrokStreamBridge extends EventEmitter {
+  constructor({ grokCmd, env, args, requestTimeoutMs, logger, detachTtlMs, detachedReapTtlMs,
+    stuckTurnTtlMs, deadTerminalTtlMs, warmCwdMax, warmPerCwdMax, historyMaxItems, historyMaxBytes } = {}) {
+    super()
+    this.options = { grokCmd, env, args, requestTimeoutMs, logger }
+    this.sessions = new Map()
+    this.clients = new Set()
+    this.closed = false
+    this.sessionSeq = 0
+    const bound = (value, name, fallback) => sanitizePositiveInt(value,
+      readPositiveIntEnv(name, fallback, logger), { logger, label: name })
+    this._detachTtlMs = bound(detachTtlMs, 'HUB_AGENT_GROK_IDLE_DETACH_TTL_MS', 7 * 86400000)
+    this._detachedReapTtlMs = bound(detachedReapTtlMs, 'HUB_AGENT_GROK_DETACHED_REAP_TTL_MS', 30 * 60000)
+    this._stuckTurnTtlMs = bound(stuckTurnTtlMs, 'HUB_AGENT_GROK_STUCK_TURN_TTL_MS', 3600000)
+    this._deadTerminalTtlMs = bound(deadTerminalTtlMs, 'HUB_AGENT_GROK_DEAD_TERMINAL_TTL_MS', 3600000)
+    this._warmCwdMax = bound(warmCwdMax, 'HUB_AGENT_WARM_CWD_MAX', 20)
+    this._warmPerCwdMax = bound(warmPerCwdMax, 'HUB_AGENT_WARM_PER_CWD_MAX', 3)
+    this._historyMaxItems = bound(historyMaxItems, 'HUB_AGENT_GROK_HISTORY_MAX_ITEMS', 200)
+    this._historyMaxBytes = bound(historyMaxBytes, 'HUB_AGENT_GROK_HISTORY_MAX_BYTES', 1.5 * 1024 * 1024)
+    this.listRequests = new Map()
+    // Clients whose process group survived SIGKILL. Kept for diagnostics; never re-signalled.
+    this.unreaped = new Set()
+  }
+
+  _client(cwd, session) {
+    if (this.closed) throw new Error('Grok bridge is shut down')
+    // Each conversation owns its process; bind the capability to that process's cwd.
+    const client = new GrokAcpClient({ ...this.options, cwd,
+      env: siblingEnvFor(cwd || process.cwd(), this.options.env) })
+    this.clients.add(client)
+    // Before the session is ready, a transport error or exit rejects the pending attach request;
+    // the attach caller reports it once (phase=attach), so the bridge stays silent here.
+    client.on('error', (error) => {
+      if (!session || session.readyDone) this.emit('grok_error', { stream_id: session?.stream_id, message: error.message })
+      void this._dispose(client)
+    })
+    client.on('exit', ({ code, signal }) => {
+      if (session && !session.dead && !session.readyDone) {
+        this._forget(session)
+      } else if (session && !session.dead) {
+        this._forget(session)
+        this.emit('grok_error', { stream_id: session.stream_id, session_id: session.sessionId, message: `grok ACP exited (code=${code}, signal=${signal})` })
+        this.emit('grok_exit', { cwd: session.cwd, stream_id: session.stream_id,
+          session_id: session.sessionId, reason: 'process-exit', code, signal, lastSeq: session.updateSeq })
+      }
+      void this._dispose(client)
+    })
+    client.on('request', ({ id, method, params }) => {
+      if (method === 'session/request_permission' && session && !session.dead) {
+        if (session.turnSeq === session.cancelledTurn) {
+          client.respond(id, { outcome: { outcome: 'cancelled' } })
+          return
+        }
+        const token = randomUUID()
+        session.pendingPermissions.set(token, { rpcId: id, turn: session.turnSeq, params })
+        this.emit('grok_permission', { stream_id: session.stream_id, request_id: token, params })
+      } else if (ignoredRequests.has(method)) client.respond(id, {})
+      else client.respondError(id, { code: -32601, message: 'Method not found' })
+    })
+    const authTriggered = new Set()
+    client.on('notification', ({ method, params }) => {
+      if (method === '_x.ai/mcp/server_status' && session && !session.dead &&
+          params?.status === 'unavailable' && HUB_MCP_NAMES.has(params.name) &&
+          typeof params.sessionId === 'string') {
+        const key = JSON.stringify([params.sessionId, params.name])
+        if (!authTriggered.has(key)) {
+          authTriggered.add(key)
+          void Promise.resolve().then(() => {
+            if (session.dead) return
+            return client.request('_x.ai/mcp/auth_trigger', {
+              session_id: params.sessionId, server_name: params.name,
+            }, { timeoutMs: 300000 })
+          }).then((result) => {
+            if (result) this.options.logger?.info?.({ name: params.name, status: result.status }, 'grok MCP authentication result')
+          }).catch(() => {
+            this.options.logger?.warn?.({ name: params.name }, 'grok MCP authentication failed')
+          })
+        }
+      }
+      if (method === 'session/update' && session && !session.dead) {
+        if (!params || typeof params !== 'object' || Array.isArray(params) || typeof params.sessionId !== 'string' ||
+            !params.update || typeof params.update !== 'object' || Array.isArray(params.update)) {
+          this.options.logger?.warn?.('grok ACP: invalid session/update skipped')
+          return
+        }
+        this._touch(session)
+        this._recordUpdate(session, params.update)
+        if (session.readyDone) this.emit('grok_event', { stream_id: session.stream_id,
+          session_id: params.sessionId, seq: session.updateSeq, update: params.update })
+      }
+    })
+    return client
+  }
+
+  _liveSessions() { return [...new Set(this.sessions.values())].filter((s) => !s.dead) }
+
+  _touch(session, stream_id) {
+    const now = Date.now()
+    session.lastActivityMs = now
+    if (session.streamIds.has(stream_id)) session.lastActivityByStream.set(stream_id, now)
+  }
+
+  // historyBytes is maintained incrementally as the UTF-8 size of JSON.stringify(historyItems);
+  // re-serialising the whole history per streamed chunk would block the event loop shared with
+  // Claude/Codex.
+  _recordUpdate(session, update) {
+    const seq = ++session.updateSeq
+    const at_ms = Date.now()
+    const previous = session.historyItems.at(-1)
+    // Chunks merge only within one history epoch (bumped at load completion, turn start and turn
+    // end) so replies from different turns never become one item, and only while the merged item
+    // stays under HISTORY_MERGE_MAX_BYTES so the overall bound also applies to the last item.
+    const mergeable = session.historyMergeEpoch === session.historyEpoch &&
+      previous?.update.sessionUpdate === update.sessionUpdate &&
+      ['agent_message_chunk', 'agent_thought_chunk'].includes(update.sessionUpdate) &&
+      previous.update.content?.type === 'text' && update.content?.type === 'text' &&
+      typeof previous.update.content.text === 'string' && typeof update.content.text === 'string'
+    // Exact for concatenation except a surrogate pair split across chunks (an estimate is enough).
+    const delta = mergeable
+      ? utf8Bytes(update.content.text) - 2 + String(seq).length - String(previous.seq).length +
+        String(at_ms).length - String(previous.at_ms).length
+      : 0
+    // The merged item must also fit the configured total (minus the enclosing "[]"), otherwise a
+    // small historyMaxBytes is exceeded by merging alone (the last item is never dropped).
+    const mergeCap = Math.min(HISTORY_MERGE_MAX_BYTES, this._historyMaxBytes - 2)
+    if (mergeable && session.historyItemBytes.at(-1) + delta <= mergeCap) {
+      previous.update.content.text += update.content.text
+      previous.seq = seq
+      previous.at_ms = at_ms
+      session.historyItemBytes[session.historyItemBytes.length - 1] += delta
+      session.historyBytes += delta
+    } else {
+      const entry = { seq, update: structuredClone(update), at_ms }
+      const bytes = utf8Bytes(entry)
+      session.historyItems.push(entry)
+      session.historyItemBytes.push(bytes)
+      session.historyBytes += bytes + (session.historyItems.length > 1 ? 1 : 0)
+      session.historyMergeEpoch = session.historyEpoch
+    }
+    while (session.historyItems.length > 1 && (session.historyItems.length > this._historyMaxItems ||
+        session.historyBytes > this._historyMaxBytes)) {
+      session.historyItems.shift()
+      session.historyBytes -= session.historyItemBytes.shift() + 1
+      session.historyTruncated = true
+    }
+  }
+
+  _snapshot(session, warm) {
+    return { sessionId: session.sessionId, resuming: warm || !!session.resumeSessionId, warm,
+      history: structuredClone(session.historyItems), historyTruncated: session.historyTruncated,
+      lastSeq: session.updateSeq, turnActive: warm && session.promptInFlight,
+      queueState: this._queueStateOf(session) }
+  }
+
+  _forget(session) {
+    session.dead = true
+    for (const item of session.inputQueue.splice(0)) {
+      item.reject(new Error('Grok session detached'))
+    }
+    session.acceptedRequestIds.clear()
+    for (const entry of session.pendingPermissions.values()) {
+      session.client.respond(entry.rpcId, { outcome: { outcome: 'cancelled' } })
+    }
+    session.pendingPermissions.clear()
+    for (const sid of session.streamIds) {
+      if (this.sessions.get(sid) === session) this.sessions.delete(sid)
+    }
+  }
+
+  async _dispose(client) {
+    for (const session of this._liveSessions()) {
+      if (session.client === client) this._forget(session)
+    }
+    let reaped = false
+    try { reaped = await client.stop() } catch { /* Retain failed cleanup in unreaped diagnostics. */ }
+    if (this.clients.delete(client) && !reaped) {
+      this.unreaped.add(client)
+      this.emit('grok_error', { message: 'grok ACP process group could not be reaped' })
+    }
+    return reaped
+  }
+
+  async _initialize(client) {
+    client.start()
+    return client.request('initialize', { protocolVersion: 1, clientCapabilities: {} })
+  }
+
+  _applyConfig(session, { model, effort }) {
+    const changes = [['model', model], ['reasoning_effort', effort]]
+      .filter(([id, value]) => value && value !== session.config?.[id])
+    if (!changes.length) return null
+    return (async () => {
+      for (const [configId, value] of changes) {
+        await session.client.request('session/set_config_option', {
+          sessionId: session.sessionId, configId, value,
+        })
+        session.config ??= {}
+        session.config[configId] = value
+      }
+    })()
+  }
+
+  async attach({ stream_id, cwd, model, effort, resumeSessionId, attachId }) {
+    if (this.closed) throw new Error('Grok bridge is shut down')
+    if (isUnderRemoval(cwd)) throw new Error(`worktree removal in progress: ${cwd}`)
+    // Re-run the lookup after a failed shared start: another waiter may already have registered a
+    // replacement, and every waiter must join it rather than start its own process. Lookup and the
+    // cold registration below run synchronously after the last await, so no gap opens between them.
+    const failed = new Set()
+    for (;;) {
+      if (this.closed) throw new Error('Grok bridge is shut down')
+      const live = this._liveSessions().filter((s) => !failed.has(s))
+      const existing = (attachId && live.find((s) => s.attachId === attachId)) ||
+        (resumeSessionId && live.find((s) => s.cwd === cwd && (s.sessionId === resumeSessionId ||
+          (s.sessionId === null && s.resumeSessionId === resumeSessionId))))
+      if (!existing) break
+      const sessionId = await existing.ready
+      if (!sessionId || existing.dead) { failed.add(existing); continue }
+      if (this.closed) throw new Error('Grok bridge is shut down')
+      const occupied = this.sessions.get(stream_id)
+      if (occupied && occupied !== existing) throw new Error('stream already attached')
+      if (existing.dead || existing.client.closed) throw new Error('Grok session detached')
+      existing.streamIds.add(stream_id)
+      if (!existing.lastActivityByStream.has(stream_id)) existing.lastActivityByStream.set(stream_id, Date.now())
+      this.sessions.set(stream_id, existing)
+      existing.stream_id = stream_id
+      existing.detachRequested = false
+      existing.browserDetachedAtMs = null
+      existing.explicitBrowserDetachPendingAttach = false
+      this._touch(existing, stream_id)
+      for (const [token, entry] of existing.pendingPermissions) {
+        this.emit('grok_permission', { stream_id: existing.stream_id, request_id: token, params: entry.params })
+      }
+      return this._snapshot(existing, true)
+    }
+    if (this.sessions.has(stream_id)) throw new Error('stream already attached')
+    // The loop above may have awaited a shared start; removal can begin meanwhile, so check again
+    // right before spawning (same as the Codex bridge).
+    if (isUnderRemoval(cwd)) throw new Error(`worktree removal in progress: ${cwd}`)
+    const now = Date.now()
+    let resolveReady
+    const session = { seq: ++this.sessionSeq, stream_id, cwd, attachId, resumeSessionId,
+      streamIds: new Set([stream_id]), lastActivityByStream: new Map([[stream_id, now]]),
+      ready: new Promise((resolve) => { resolveReady = resolve }), readyDone: false, dead: false,
+      detachRequested: false, explicitBrowserDetachPendingAttach: false, browserDetachedAtMs: null,
+      lastActivityMs: now, lastTurnAtMs: now, promptInFlight: false,
+      inputQueue: [], dispatchingInput: null, queueStateSeq: 0,
+      acceptedInputIds: [], cancelledInputIds: [], canceledBeforeArrival: new Set(),
+      pendingPermissions: new Map(), turnSeq: 0, cancelledTurn: null, acceptedRequestIds: new Map(),
+      sessionId: null, updateSeq: 0, historyItems: [], historyItemBytes: [], historyBytes: 2, historyEpoch: 0, historyMergeEpoch: -1,
+      historyTruncated: false }
+    const client = session.client = this._client(cwd, session)
+    this.sessions.set(stream_id, session)
+    try {
+      await this._initialize(client)
+      const result = await client.request(resumeSessionId ? 'session/load' : 'session/new', {
+        cwd, mcpServers: [], ...(resumeSessionId ? { sessionId: resumeSessionId } : {}),
+      })
+      session.sessionId = resumeSessionId || result.sessionId
+      if (!session.sessionId) throw new Error('ACP response has no sessionId')
+      await this._applyConfig(session, { model, effort })
+      if (this.sessions.get(stream_id) !== session || client.closed) throw new Error('Grok session detached')
+      session.readyDone = true
+      session.historyEpoch++
+      resolveReady(session.sessionId)
+      this._reconcileWarmBounds(Date.now(), 'attach')
+      return this._snapshot(session, false)
+    } catch (error) {
+      session.readyDone = true
+      resolveReady(null)
+      this._forget(session)
+      // Not emitted here: the caller reports the thrown error once, tagged phase=attach.
+      await this._dispose(client)
+      throw error
+    }
+  }
+
+  _require(stream_id) {
+    const session = this.sessions.get(stream_id)
+    if (!session || session.dead || !session.readyDone || session.client.closed) throw new Error('Grok session is not ready')
+    return session
+  }
+
+  input({ stream_id, message, inputId, model, effort }) {
+    const session = this._require(stream_id)
+    const prompt = promptFromMessage(message)
+    if (!prompt.length) throw new Error('Grok prompt is empty')
+    this._touch(session, stream_id)
+    return { turn: this._enqueue(session, prompt, inputId, { model, effort }) }
+  }
+
+  _enqueue(session, prompt, inputId, config = {}) {
+    const id = typeof inputId === 'string' ? inputId : null
+    if (session.canceledBeforeArrival.has(id)) {
+      session.canceledBeforeArrival.delete(id)
+      this._recordInputId(session.cancelledInputIds, id)
+      this._emitQueueState(session)
+      return Promise.resolve(null)
+    }
+    const turn = new Promise((resolve, reject) => {
+      session.inputQueue.push({ inputId: id, text: prompt.map((block) => block.text).join('\n'),
+        prompt, config, resolve, reject })
+    })
+    // 完了を待たない注入の失敗も通知する。待機取消は正常な応答で扱う。
+    turn.catch((error) => {
+      if (error.reason === 'cancelled') return
+      this.emit('grok_error', { stream_id: session.stream_id, session_id: session.sessionId,
+        inputId: id, message: error.message, lastSeq: session.updateSeq })
+    })
+    this._pump(session)
+    this._emitQueueState(session)
+    return turn
+  }
+
+  _recordInputId(ids, id) {
+    if (!id) return
+    ids.push(id)
+    if (ids.length > 256) ids.splice(0, ids.length - 256)
+  }
+
+  _pump(session) {
+    if (session.dead || session.promptInFlight || session.dispatchingInput || !session.inputQueue.length) return
+    const item = session.inputQueue.shift()
+    session.dispatchingInput = item
+    const { prompt, inputId } = item
+    const run = async () => {
+      session.promptInFlight = true
+      session.historyEpoch++
+      const turn = ++session.turnSeq
+      try {
+        const configuring = this._applyConfig(session, item.config)
+        if (configuring) await configuring
+        if (session.dead || session.client.closed) throw new Error('Grok session detached')
+        if (session.cancelledTurn === turn) {
+          this._recordInputId(session.cancelledInputIds, inputId)
+          this._emitQueueState(session)
+          const result = { stopReason: 'cancelled' }
+          this.emit('grok_turn_complete', { stream_id: session.stream_id, session_id: session.sessionId,
+            stopReason: result.stopReason, lastSeq: session.updateSeq })
+          return result
+        }
+        this._recordInputId(session.acceptedInputIds, inputId)
+        this._emitQueueState(session, item)
+        for (const block of prompt) {
+          const update = { sessionUpdate: 'user_message_chunk',
+            content: { type: 'text', text: block.text },
+            ...(inputId != null ? { _meta: { 'cockpit/input_id': inputId } } : {}) }
+          this._recordUpdate(session, update)
+          if (session.readyDone) this.emit('grok_event', { stream_id: session.stream_id,
+            session_id: session.sessionId, seq: session.updateSeq, update })
+        }
+        // ACP prompt resolves only at turn completion, including time spent awaiting permission.
+        const result = await session.client.request('session/prompt', {
+          sessionId: session.sessionId, prompt,
+        }, { timeoutMs: 0 })
+        // lastSeq lets the browser detect a dropped tail (chunks are not buffered while the Hub link
+        // is down) even when no further update follows; it then re-attaches to read the history.
+        this.emit('grok_turn_complete', { stream_id: session.stream_id, session_id: session.sessionId, stopReason: result.stopReason, lastSeq: session.updateSeq })
+        return result
+      } finally {
+        session.promptInFlight = false
+        session.historyEpoch++
+        session.lastTurnAtMs = Date.now()
+        this._clearTurnPermissions(session, turn)
+      }
+    }
+    run().then(item.resolve, item.reject).finally(() => {
+      session.dispatchingInput = null
+      this._pump(session)
+    })
+  }
+
+  queueState(stream_id) {
+    return this._queueStateOf(this._require(stream_id))
+  }
+
+  // 内部の通知・ready は session を直接渡す。_require を通すと、通信が閉じた直後に
+  // 積んだ後・取消応答の後で例外になり、受理済みの入力や取消の通知が途中で止まる。
+  _queueStateOf(session) {
+    const pending = session.inputQueue
+    return { type: 'queue_state', pending: pending.length,
+      messages: pending.map((item) => item.text),
+      items: pending.map((item) => ({ id: item.inputId || '', text: item.text })),
+      seq: session.queueStateSeq, generation: session.seq,
+      accepted: [...session.acceptedInputIds], cancelled: [...session.cancelledInputIds] }
+  }
+
+  _emitQueueState(session, startedItem = null) {
+    if (session.dead) return
+    session.queueStateSeq++
+    const snapshot = this._queueStateOf(session)
+    snapshot.started = startedItem ? [startedItem.text] : []
+    snapshot.startedIds = startedItem ? [startedItem.inputId] : []
+    this.emit('grok_queue_state', { stream_id: session.stream_id,
+      session_id: session.sessionId, queue_state: snapshot })
+  }
+
+  cancelQueued({ stream_id, id }) {
+    const session = this.sessions.get(stream_id)
+    if (!session || session.dead) return { outcome: 'stream_missing', flush: () => {} }
+    if (typeof id !== 'string' || !id) throw new Error('invalid_input_id')
+    // 取消の応答を先に送れるよう、状態通知は呼び出し側の flush に委ねる。
+    const flush = () => this._emitQueueState(session)
+    const index = session.inputQueue.findIndex((item) => item.inputId === id)
+    if (index >= 0) {
+      const [item] = session.inputQueue.splice(index, 1)
+      this._recordInputId(session.cancelledInputIds, id)
+      item.reject(Object.assign(new Error('Grok queued input cancelled'), { reason: 'cancelled' }))
+      return { outcome: 'cancelled', flush }
+    }
+    if (session.cancelledInputIds.includes(id)) return { outcome: 'cancelled', flush }
+    // 送出済みの項目はキュー取消では止められない（実行中の停止は interrupt）。
+    if (session.dispatchingInput?.inputId === id || session.acceptedInputIds.includes(id)) {
+      return { outcome: 'already_started', flush }
+    }
+    // 通信順序で取消が入力より先に届いても、後着の入力を実行しない。
+    if (session.canceledBeforeArrival.size >= 1024) session.canceledBeforeArrival.clear()
+    session.canceledBeforeArrival.add(id)
+    return { outcome: 'cancelled', flush }
+  }
+
+  _clearTurnPermissions(session, turn, cancel = false) {
+    const requestIds = []
+    for (const [token, entry] of session.pendingPermissions) {
+      if (entry.turn !== turn) continue
+      session.pendingPermissions.delete(token)
+      requestIds.push(token)
+      if (cancel) session.client.respond(entry.rpcId, { outcome: { outcome: 'cancelled' } })
+    }
+    // browser は承認カードの生死を推測できない（中断の送信と応答の間に届いた承認など）ため、
+    // 破棄した承認を確定情報として知らせる。
+    if (requestIds.length) {
+      this.emit('grok_permission_cancelled', { stream_id: session.stream_id, session_id: session.sessionId, request_ids: requestIds })
+    }
+  }
+
+  interrupt({ stream_id }) {
+    const session = this._require(stream_id)
+    this._touch(session, stream_id)
+    session.cancelledTurn = session.turnSeq
+    this._clearTurnPermissions(session, session.turnSeq, true)
+    session.client.notify('session/cancel', { sessionId: session.sessionId })
+  }
+
+  permissionReply({ stream_id, request_id, result }) {
+    const session = this.sessions.get(stream_id)
+    const entry = session?.pendingPermissions.get(request_id)
+    if (!entry || session.dead || !session.streamIds.has(stream_id) || session.client.closed ||
+        entry.turn !== session.turnSeq || entry.turn === session.cancelledTurn) return
+    this._touch(session, stream_id)
+    session.pendingPermissions.delete(request_id)
+    session.client.respond(entry.rpcId, result)
+  }
+
+  detach({ stream_id }) {
+    const session = this.sessions.get(stream_id)
+    if (!session || session.dead) return
+    if (session.streamIds.size > 1) {
+      this._dropStream(session, stream_id)
+      return
+    }
+    session.detachRequested = true
+    session.explicitBrowserDetachPendingAttach = true
+    session.browserDetachedAtMs ??= Date.now()
+  }
+
+  _dropStream(session, stream_id) {
+    session.streamIds.delete(stream_id)
+    session.lastActivityByStream.delete(stream_id)
+    if (this.sessions.get(stream_id) === session) this.sessions.delete(stream_id)
+    if (session.stream_id === stream_id) session.stream_id = Array.from(session.streamIds).at(-1)
+  }
+
+  keepalive({ stream_id }) {
+    const session = this.sessions.get(stream_id)
+    if (!session || session.dead || session.explicitBrowserDetachPendingAttach) return false
+    session.detachRequested = false
+    session.browserDetachedAtMs = null
+    this._touch(session, stream_id)
+    return true
+  }
+
+  gcDeadTerminals(ttlMs = this._deadTerminalTtlMs) {
+    const now = Date.now()
+    let removed = 0
+    for (const session of this._liveSessions()) {
+      for (const sid of Array.from(session.streamIds)) {
+        if (session.streamIds.size <= 1) break
+        if (now - (session.lastActivityByStream.get(sid) ?? 0) < ttlMs) continue
+        this._dropStream(session, sid)
+        removed++
+      }
+      if (session.streamIds.size === 1) {
+        const [sid] = session.streamIds
+        if (now - (session.lastActivityByStream.get(sid) ?? 0) >= ttlMs) {
+          session.detachRequested = true
+          session.browserDetachedAtMs ??= now
+        }
+      }
+    }
+    return removed
+  }
+
+  _isProtected(session, now) {
+    if (!session.readyDone && !session.dead) return true
+    // A stuck running turn must not stay protected just because inputs are queued behind it
+    // (they cannot start until it completes); reaping rejects both the turn and the queue.
+    if (session.promptInFlight) return now - session.lastActivityMs <= this._stuckTurnTtlMs
+    return session.inputQueue.length > 0
+  }
+
+  hasActiveWork(now = Date.now()) {
+    return this._liveSessions().some((session) => this._isProtected(session, now))
+  }
+
+  listWarmCandidates(now = Date.now()) {
+    return this._liveSessions().map((session) => ({ kind: 'grok', cwd: session.cwd,
+      recency: session.lastActivityMs, seq: session.seq, protected: this._isProtected(session, now),
+      reap: (reason) => this._reapSession(session, now, reason) }))
+  }
+
+  _reapSession(session, now, reason) {
+    if (session.dead) return
+    this._forget(session)
+    void this._dispose(session.client)
+    this.emit('grok_exit', { cwd: session.cwd, stream_id: session.stream_id, session_id: session.sessionId,
+      reason: ['session-deleted', 'chat-stop', 'chat-stop-all', 'worktree-remove'].includes(reason) ? reason : 'idle-reaped',
+      lastSeq: session.updateSeq })
+  }
+
+  _reconcileWarmBounds(now, reason = 'warm-bounds') {
+    let evicted = 0
+    const byCwd = new Map()
+    for (const session of this._liveSessions()) {
+      if (!byCwd.has(session.cwd)) byCwd.set(session.cwd, [])
+      byCwd.get(session.cwd).push(session)
+    }
+    for (const sessions of byCwd.values()) {
+      sessions.sort((a, b) => b.lastActivityMs - a.lastActivityMs || b.seq - a.seq)
+      for (const session of sessions.slice(this._warmPerCwdMax)) {
+        if (this._isProtected(session, now)) continue
+        this._reapSession(session, now, `${reason}:per-cwd`)
+        evicted++
+      }
+    }
+    const cwdInfo = new Map()
+    for (const session of this._liveSessions()) {
+      if (!cwdInfo.has(session.cwd)) cwdInfo.set(session.cwd, { recency: -Infinity, seq: -Infinity, protected: false, sessions: [] })
+      const info = cwdInfo.get(session.cwd)
+      info.recency = Math.max(info.recency, session.lastActivityMs)
+      info.seq = Math.max(info.seq, session.seq)
+      info.protected ||= this._isProtected(session, now)
+      info.sessions.push(session)
+    }
+    const overflow = cwdInfo.size - this._warmCwdMax
+    const evictable = [...cwdInfo.values()].filter((info) => !info.protected)
+      .sort((a, b) => a.recency - b.recency || a.seq - b.seq)
+    for (const info of evictable.slice(0, Math.max(0, overflow))) {
+      for (const session of info.sessions) {
+        this._reapSession(session, now, `${reason}:cwd-lru`)
+        evicted++
+      }
+    }
+    return evicted
+  }
+
+  reconcileSessions() {
+    const now = Date.now()
+    let reaped = 0
+    this.gcDeadTerminals()
+    for (const session of this._liveSessions()) {
+      if (this._isProtected(session, now)) continue
+      const idle = now - session.lastActivityMs
+      let reason
+      if (session.promptInFlight && idle > this._stuckTurnTtlMs) reason = 'stuck-turn'
+      else if (session.browserDetachedAtMs !== null && now - session.browserDetachedAtMs > this._detachedReapTtlMs) reason = 'browser-detached-ttl'
+      else if (!session.promptInFlight && idle > this._detachTtlMs) reason = 'idle-ttl'
+      if (reason) { this._reapSession(session, now, reason); reaped++ }
+    }
+    return reaped + this._reconcileWarmBounds(now, 'warm-bounds')
+  }
+
+  gcAbandonedSessions() { return this.reconcileSessions() }
+
+  async stopSessionForStream({ stream_id, reason }) {
+    const session = this.sessions.get(stream_id)
+    if (!session || session.dead) return 0
+    this._reapSession(session, Date.now(), reason)
+    await this._dispose(session.client)
+    return 1
+  }
+
+  async stopSessionsForCwd({ cwd, reason }) {
+    const sessions = this._liveSessions().filter((session) => session.cwd === cwd)
+    await Promise.all(sessions.map(({ stream_id }) => this.stopSessionForStream({ stream_id, reason })))
+    return sessions.length
+  }
+
+  /**
+   * Waits until every client is reaped or given up on. `unreaped` counts every client whose
+   * process group could not be confirmed gone (including earlier detach/exit failures); it is
+   * not a live count, and those groups are never re-signalled.
+   */
+  async shutdown() {
+    this.closed = true
+    for (const session of this._liveSessions()) this._reapSession(session, Date.now(), 'shutdown')
+    await Promise.all([...this.clients].map((client) => this._dispose(client)))
+    return { unreaped: this.unreaped.size }
+  }
+
+  listThreads({ cwd, limit } = {}) {
+    const key = JSON.stringify([cwd ?? null, limit ?? null])
+    if (this.listRequests.has(key)) return this.listRequests.get(key)
+    const request = this._listThreads({ cwd, limit })
+    this.listRequests.set(key, request)
+    const clear = () => { this.listRequests.delete(key) }
+    request.then(clear, clear)
+    return request
+  }
+
+  async _listThreads({ cwd, limit }) {
+    const client = this._client(cwd)
+    try {
+      const init = await this._initialize(client)
+      if (!init.agentCapabilities?.sessionCapabilities?.list) return []
+      const sessions = []
+      const cursors = new Set()
+      let cursor
+      do {
+        const result = await client.request('session/list', { ...(cwd ? { cwd } : {}), ...(cursor ? { cursor } : {}) })
+        sessions.push(...result.sessions)
+        cursor = result.nextCursor
+        if (cursor && cursors.has(cursor)) throw new Error('Repeated ACP session/list cursor')
+        cursors.add(cursor)
+      } while (cursor && (limit == null || sessions.length < limit))
+      return limit == null ? sessions : sessions.slice(0, Math.max(0, limit))
+    } catch (error) {
+      if (error.code === -32601) return []
+      this.emit('grok_error', { message: error.message })
+      throw error
+    } finally { await this._dispose(client) }
+  }
+
+  _readySessions() { return this._liveSessions().filter((s) => s.readyDone && !s.client.closed) }
+  getThreadId(stream_id) { return this._readySessions().find((s) => s.streamIds.has(stream_id))?.sessionId ?? null }
+  getCwd(stream_id) { return this._readySessions().find((s) => s.streamIds.has(stream_id))?.cwd ?? null }
+  liveSessionForCwd(cwd) { return this._readySessions().find((s) => s.cwd === cwd) ?? null }
+  _describe(session) {
+    return { kind: 'grok', cwd: session.cwd, stream_id: session.stream_id, thread_id: session.sessionId,
+      busy: session.promptInFlight, detached: session.detachRequested,
+      idle_ms: Date.now() - (session.lastTurnAtMs ?? session.lastActivityMs) }
+  }
+  describeLiveSessions(cwd) {
+    return this._liveSessions().filter((s) => !cwd || s.cwd === cwd).map((s) => this._describe(s))
+  }
+  async sendToCwd(cwd, text, source, requestId) {
+    const live = this._readySessions().filter((s) => s.cwd === cwd)
+    // Attached (not detach-requested) sessions take precedence, as in codex sendToCwd: a warm
+    // session the browser left must not make the only attached one ambiguous.
+    const attached = live.filter((s) => !s.detachRequested)
+    const candidates = attached.length ? attached : live
+    if (!candidates.length) return { status: 'not_found' }
+    if (candidates.length > 1) return { status: 'ambiguous', candidates: candidates.map((session) => this._describe(session)) }
+    return this._deliverInjection(candidates[0], text, source, requestId)
+  }
+
+  async sendToStream(cwd, id, text, source, requestId) {
+    if (!cwd || !id || !text) return { status: 'not_found' }
+    const live = this._readySessions().filter((s) => s.cwd === cwd)
+    const byStream = live.find((s) => s.streamIds.has(id))
+    const candidates = byStream ? [byStream] : live.filter((s) => s.sessionId === id)
+    if (!candidates.length) return { status: 'not_found' }
+    if (candidates.length > 1) return { status: 'ambiguous', candidates: candidates.map((s) => this._describe(s)) }
+    return this._deliverInjection(candidates[0], text, source, requestId)
+  }
+
+  async _deliverInjection(session, text, source, requestId) {
+    const ids = session.acceptedRequestIds
+    if (requestId != null && ids.has(requestId)) return { status: 'duplicate' }
+    if (requestId != null && [...ids.values()].filter((state) => state === 'pending').length >= MAX_PENDING_DELIVERIES) {
+      return { status: 'busy' }
+    }
+    const prompt = promptFromMessage({ content: text })
+    if (!prompt.length) throw new Error('Grok prompt is empty')
+    // As in codex sendToCwd: an accepted delivery makes the session the active routing target
+    // (detachRequested=false) while browser absence stays tracked by browserDetachedAtMs.
+    // explicitBrowserDetachPendingAttach is left as is, so stale keepalives stay rejected.
+    session.detachRequested = false
+    this._touch(session)
+    if (session.browserDetachedAtMs !== null) session.browserDetachedAtMs = Date.now()
+    const turn = this._enqueue(session, prompt, requestId)
+    if (requestId != null) {
+      ids.set(requestId, 'pending')
+      const settle = () => {
+        if (ids.get(requestId) !== 'pending') return
+        ids.set(requestId, 'done')
+        let done = [...ids.values()].filter((state) => state === 'done').length
+        for (const [id, state] of ids) {
+          if (done <= MAX_ACCEPTED_REQUEST_IDS) break
+          if (state === 'done') { ids.delete(id); done-- }
+        }
+      }
+      turn.then(settle, settle)
+    }
+    return { status: 'delivered', session: { stream_id: session.stream_id, sessionId: session.sessionId } }
+  }
+}