@threadcrumbs/threadnauts 1.3.0 → 1.4.0

package/server/threadbare.mjs

@@ -0,0 +1,252 @@
+import fsp from 'node:fs/promises'
+import path from 'node:path'
+import { clip } from '@threadcrumbs/common/lib/telemetry-fields'
+import { threadcrumbsDataDir } from '@threadcrumbs/common/license/store'
+import { isAskId, locateThreadgauge } from './threadgauge.mjs'
+
+export const APP = 'threadnauts'
+export const THREADBARE_RELEASED = Date.UTC(2026, 10, 9) / 1000
+export const CONTROL_BODY_LIMIT = 16 * 1024
+
+const REUSE_FOUND_MS = 15000
+const READ_TIMEOUT_MS = 3000
+const SEND_TIMEOUT_MS = 30000
+const THREAD_MAX = 300
+const VALUE_MAX = 8000
+const OPTIONS_MAX = 8
+const WHY_MAX = 500
+const NAME_MAX = 80
+const PROMPT_MAX = 4000
+const PRESETS_MAX = 120
+
+const PRESET_ID = /^[a-z0-9][a-z0-9-]{0,39}$/
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/
+const COMMANDER_ACTIONS = new Set(['approve', 'deny', 'stop', 'retry'])
+const ANSWER_KINDS = new Set(['option', 'allow', 'deny', 'retry'])
+const APPLIES = new Set(['any', 'asking', 'done', 'working', 'error'])
+const STATUSES = new Set(['asking', 'error', 'done', 'working', 'delegating', 'idle'])
+const THREADS_MAX = 100
+const SEEN_MAX = 100
+const RUN_BATCH = 50
+const APPROVALS = new Set(['approve', 'deny'])
+const HELD_KINDS = new Set(['approval', 'question'])
+const ASKS_MAX = 8
+const DELIVERIES = new Set(['now', 'queued', 'resumed'])
+const PASSED_ERRORS = new Set(['pro', 'not-found', 'uncertain', 'changed', 'setup', 'failed', 'bad-request', 'too-large'])
+
+export const tokenFile = (dataDir) => path.join(dataDir, 'agent-controls', 'apps', `${APP}.token`)
+
+const isPlainObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v)
+const onlyKeys = (body, keys) => isPlainObject(body) && Object.keys(body).every((key) => keys.includes(key))
+const isThreadId = (v) => typeof v === 'string' && v.length > 0 && v.length <= THREAD_MAX && v.includes(':') && !CONTROL_CHARS.test(v)
+const isAnswerText = (v) => typeof v === 'string' && v.trim().length > 0 && v.length <= VALUE_MAX && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(v)
+
+export const checkAsksThread = (thread) => (isThreadId(thread) ? thread : null)
+
+export function keepAsks(answer) {
+  const asks = Array.isArray(answer?.asks) ? answer.asks : []
+  return {
+    can: answer?.can?.answer === true,
+    why: typeof answer?.why === 'string' ? clip(answer.why, WHY_MAX) : '',
+    asks: asks.filter((ask) => isPlainObject(ask) && isAskId(ask.id) && HELD_KINDS.has(ask.kind)).slice(0, ASKS_MAX).map((ask) => ({ id: ask.id, kind: ask.kind })),
+  }
+}
+
+export function checkRunBody(body) {
+  if (!onlyKeys(body, ['preset', 'threads', 'seen'])) return null
+  const { preset, threads } = body
+  if (typeof preset !== 'string' || !PRESET_ID.test(preset)) return null
+  if (!Array.isArray(threads) || !threads.length || threads.length > THREADS_MAX || !threads.every(isThreadId) || new Set(threads).size !== threads.length) return null
+  if (body.seen === undefined) return { preset, threads: [...threads] }
+  if (!isPlainObject(body.seen)) return null
+  const seen = Object.entries(body.seen)
+  if (!seen.length || seen.length > SEEN_MAX || !seen.every(([thread, ask]) => threads.includes(thread) && isAskId(ask))) return null
+  return { preset, threads: [...threads], seen: Object.fromEntries(seen) }
+}
+
+export function checkAnswerBody(body) {
+  if (!onlyKeys(body, ['thread', 'answer']) || !isThreadId(body.thread)) return null
+  const answer = body.answer
+  if (!isPlainObject(answer) || !ANSWER_KINDS.has(answer.kind)) return null
+  if (answer.id !== undefined && !isAskId(answer.id)) return null
+  const id = answer.id === undefined ? {} : { id: answer.id }
+  if (answer.kind !== 'option') return onlyKeys(answer, ['kind', 'id']) ? { thread: body.thread, answer: { kind: answer.kind, ...id } } : null
+  if (!onlyKeys(answer, ['kind', 'value', 'id'])) return null
+  const value = answer.value
+  const fine = isAnswerText(value) || (Array.isArray(value) && value.length > 0 && value.length <= OPTIONS_MAX && value.every(isAnswerText) && value.join('').length <= VALUE_MAX)
+  return fine ? { thread: body.thread, answer: { kind: 'option', value: Array.isArray(value) ? [...value] : value, ...id } } : null
+}
+
+const runnable = (preset) => preset.kind === 'prompt' || (preset.kind === 'action' && COMMANDER_ACTIONS.has(preset.action))
+
+function keepPreset(raw, builtIn) {
+  if (!isPlainObject(raw) || typeof raw.id !== 'string' || !PRESET_ID.test(raw.id)) return null
+  const kind = raw.kind === 'action' ? 'action' : raw.kind === 'prompt' ? 'prompt' : null
+  if (!kind || typeof raw.name !== 'string' || !raw.name.trim()) return null
+  const preset = { id: raw.id, name: clip(raw.name, NAME_MAX), kind, applies: APPLIES.has(raw.applies) ? raw.applies : 'any', confirm: raw.confirm === true, builtIn }
+  if (kind === 'action') preset.action = typeof raw.action === 'string' ? raw.action : ''
+  if (kind === 'prompt') {
+    if (typeof raw.text !== 'string' || !raw.text.trim()) return null
+    preset.text = raw.text.slice(0, PROMPT_MAX)
+  }
+  if (Array.isArray(raw.when)) preset.when = raw.when.filter((s) => STATUSES.has(s))
+  return runnable(preset) ? preset : null
+}
+
+export function keepPresets(answer) {
+  const list = (items, builtIn) => (Array.isArray(items) ? items.slice(0, PRESETS_MAX).map((p) => keepPreset(p, builtIn)).filter(Boolean) : [])
+  return { builtIn: list(answer?.builtIn, true), mine: list(answer?.mine, false) }
+}
+
+const outcome = {
+  off: () => ({ ok: false, error: 'off', why: 'Turn on “Let Threadnauts send” in Threadgauge’s Settings › Agent controls.' }),
+  missing: () => ({ ok: false, error: 'no-threadgauge', why: 'Threadgauge isn’t running.' }),
+  old: () => ({ ok: false, error: 'old', why: 'This Threadgauge is too old to send prompts and actions. Update it to send from Threadnauts.' }),
+}
+
+function sent(answer) {
+  const kept = { ok: true }
+  if (DELIVERIES.has(answer?.delivery)) kept.delivery = answer.delivery
+  return kept
+}
+
+function refused(answer, fallback) {
+  const error = typeof answer?.error === 'string' ? answer.error : ''
+  const kept = { ok: false, error: PASSED_ERRORS.has(error) ? error : 'failed', why: clip(typeof answer?.why === 'string' && answer.why ? answer.why : fallback, WHY_MAX) }
+  if (typeof answer?.fix?.text === 'string' && answer.fix.text) kept.fix = { text: clip(answer.fix.text, WHY_MAX) }
+  return kept
+}
+
+export function fromThreadgauge(status, answer) {
+  if (status >= 200 && status < 300 && answer?.ok !== false) return sent(answer)
+  const error = typeof answer?.error === 'string' ? answer.error : ''
+  if (status === 403 && (error === 'origin' || error === 'token')) return outcome.off()
+  if (status === 404 && error !== 'not-found') return outcome.old()
+  return refused(answer, `Threadgauge answered ${status}.`)
+}
+
+const UNSAID = { ok: false, error: 'failed', why: 'Threadgauge didn’t say what happened to it.' }
+
+export function resultsFromThreadgauge(threads, status, answer) {
+  if (!Array.isArray(answer?.results)) {
+    const whole = fromThreadgauge(status, answer)
+    return threads.map((thread) => ({ thread, ...(whole.ok ? UNSAID : whole) }))
+  }
+  const said = new Map(answer.results.filter((r) => r && typeof r.thread === 'string').map((r) => [r.thread, r]))
+  return threads.map((thread) => {
+    const result = said.get(thread)
+    return { thread, ...(!result ? UNSAID : result.ok === true ? sent(result) : refused(result, 'Threadgauge didn’t send it.')) }
+  })
+}
+
+export function threadbareCommander({ fetch = globalThis.fetch, find = () => locateThreadgauge({ fetch }), dataDir = () => threadcrumbsDataDir(), pro = async () => false, now = Date.now } = {}) {
+  let found = { at: -Infinity, where: null }
+  const forget = () => (found = { at: -Infinity, where: null })
+
+  async function where() {
+    if (now() - found.at > REUSE_FOUND_MS) found = { at: now(), where: await find() }
+    return found.where
+  }
+
+  async function readToken() {
+    try {
+      return (await fsp.readFile(tokenFile(dataDir()), 'utf8')).trim()
+    } catch {
+      return ''
+    }
+  }
+
+  async function read(origin, route, token = null) {
+    const response = await fetch(`${origin}${route}`, { ...(token ? { headers: { Authorization: `Bearer ${token}` } } : {}), signal: AbortSignal.timeout(READ_TIMEOUT_MS) })
+    return { status: response.status, answer: await response.json().catch(() => null) }
+  }
+
+  async function control(origin, route, body, token) {
+    const response = await fetch(`${origin}/api/threadbare/${route}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+    })
+    return { status: response.status, answer: await response.json().catch(() => null) }
+  }
+
+  async function reachable(shape, act) {
+    const token = await readToken()
+    if (!token) return shape(outcome.off())
+    const at = await where()
+    if (!at) return shape(outcome.missing())
+    try {
+      return await act(at.origin, token)
+    } catch {
+      forget()
+      return shape(outcome.missing())
+    }
+  }
+
+  async function state({ anotherDevice = false } = {}) {
+    if (anotherDevice) return { state: 'this-computer', url: null }
+    const at = await where()
+    if (!at) return { state: 'no-threadgauge', url: null }
+    let presets
+    try {
+      presets = await read(at.origin, '/api/threadbare/presets')
+    } catch {
+      forget()
+      return { state: 'no-threadgauge', url: null }
+    }
+    if (presets.status === 404) return { state: 'old', url: at.url }
+    const allowed = Boolean(await readToken())
+    return { state: allowed ? 'ready' : 'off', url: at.url, pro: Boolean(await pro()), presets: keepPresets(presets.answer) }
+  }
+
+  async function runBatch(origin, token, body) {
+    try {
+      const { status, answer: said } = await control(origin, 'run', body, token)
+      return resultsFromThreadgauge(body.threads, status, said)
+    } catch {
+      forget()
+      return null
+    }
+  }
+
+  function run({ preset, threads, seen = {} }) {
+    const each = (whole) => ({ results: threads.map((thread) => ({ thread, ...whole })) })
+    return reachable(each, async (origin, token) => {
+      const presets = await read(origin, '/api/threadbare/presets')
+      if (presets.status === 404) return each(outcome.old())
+      const { builtIn, mine } = keepPresets(presets.answer)
+      const found = [...builtIn, ...mine].find((p) => p.id === preset)
+      if (!found) return each({ ok: false, error: 'not-found', why: 'That prompt or action isn’t one the Commander can send from Threadgauge now.' })
+      const approval = found.kind === 'action' && APPROVALS.has(found.action)
+      const sendable = approval ? threads.filter((thread) => Object.hasOwn(seen, thread)) : threads
+      const said = new Map()
+      let gone = false
+      for (let at = 0; at < sendable.length; at += RUN_BATCH) {
+        const batch = sendable.slice(at, at + RUN_BATCH)
+        const body = approval ? { preset, threads: batch, seen: Object.fromEntries(batch.map((thread) => [thread, seen[thread]])) } : { preset, threads: batch }
+        const results = gone ? null : await runBatch(origin, token, body)
+        gone = !results
+        for (const result of results ?? batch.map((thread) => ({ thread, ...outcome.missing() }))) said.set(result.thread, result)
+      }
+      const unseen = { ok: false, error: 'changed', why: 'Threadnauts didn’t show what it asks, so it wasn’t answered.' }
+      return { results: threads.map((thread) => said.get(thread) ?? { thread, ...unseen }) }
+    })
+  }
+
+  function answer({ thread, answer: given }) {
+    return reachable((whole) => whole, async (origin, token) => {
+      const { status, answer: said } = await control(origin, 'answer', { thread, answer: given }, token)
+      return fromThreadgauge(status, said)
+    })
+  }
+
+  function asks({ thread }) {
+    return reachable((whole) => whole, async (origin, token) => {
+      const { status, answer: said } = await read(origin, `/api/threadbare/reach?thread=${encodeURIComponent(thread)}`, token)
+      return status === 200 ? { ok: true, ...keepAsks(said) } : fromThreadgauge(status, said)
+    })
+  }
+
+  return { state, run, answer, asks }
+}

package/server/threadgauge.mjs

@@ -1,126 +1,129 @@
-import { DETAIL_LIMITS, clip, clipBlock } from '@threadcrumbs/common/lib/telemetry-fields'
-
-const FIRST_PORT = 5274
-const PORTS_TO_TRY = 20
-const LOOPBACKS = ['127.0.0.1', '::1']
-const PROBE_TIMEOUT_MS = 500
-const SESSIONS_TIMEOUT_MS = 2000
-const HISTORY_TIMEOUT_MS = 8000
-const REUSE_OLDER_MS = 15000
-const REUSE_FOUND_MS = 15000
-const ASK_QUESTIONS = 4
-const ASK_OPTIONS = 8
-const LABEL_MAX = 160
-const STATUS_MAX = 40
-
-const originOf = (host, port) => `http://${host.includes(':') ? `[${host}]` : host}:${port}`
-
-async function answersAsThreadgauge(origin, fetch) {
-  try {
-    const response = await fetch(`${origin}/api/about`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) })
-    return (await response.json())?.app === 'threadgauge'
-  } catch {
-    return false
-  }
-}
-
-export async function locateThreadgauge({ fetch = globalThis.fetch, first = FIRST_PORT, tries = PORTS_TO_TRY, hosts = LOOPBACKS } = {}) {
-  const probes = []
-  for (let port = first; port < first + tries; port++) for (const host of hosts) probes.push({ port, origin: originOf(host, port) })
-  const found = await Promise.all(probes.map(({ origin }) => answersAsThreadgauge(origin, fetch)))
-  const index = found.indexOf(true)
-  return index === -1 ? null : { url: `http://localhost:${probes[index].port}/`, origin: probes[index].origin }
-}
-
-export const findThreadgauge = async (options) => (await locateThreadgauge(options))?.url ?? null
-
-const text = (max) => (v) => (typeof v === 'string' ? clip(v, max) : null)
-const block = (max) => (v) => (typeof v === 'string' ? clipBlock(v, max) : null)
-const label = text(LABEL_MAX)
-const words = block(DETAIL_LIMITS.errorText)
-const number = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null)
-const list = (v, max, keep) => (Array.isArray(v) ? v.filter((x) => x && typeof x === 'object').slice(0, max).map(keep) : null)
-
-function keepAsk(ask) {
-  if (!ask || typeof ask !== 'object') return null
-  if (ask.type === 'question') {
-    const option = (o) => ({ label: label(o.label) ?? '', description: words(o.description) ?? '' })
-    const question = (q) => ({ header: label(q.header) ?? '', text: words(q.text) ?? '', options: list(q.options, ASK_OPTIONS, option) ?? [], multiple: q.multiple === true })
-    return { type: 'question', questions: list(ask.questions, ASK_QUESTIONS, question) ?? [] }
-  }
-  if (ask.type === 'approval') return { type: 'approval', tool: label(ask.tool) ?? '', target: label(ask.target) ?? '', kind: label(ask.kind) ?? 'other' }
-  if (ask.type === 'error') return { type: 'error', text: words(ask.text) ?? '' }
-  return { type: 'unknown' }
-}
-
-const SESSION_FIELDS = {
-  status: text(STATUS_MAX),
-  statusReason: text(STATUS_MAX),
-  ask: keepAsk,
-  context: (c) => (c && typeof c === 'object' ? { used: number(c.used), limit: number(c.limit) } : null),
-  tool: (t) => (t && typeof t === 'object' ? { name: label(t.name) ?? '', startedAt: number(t.startedAt), target: label(t.target) ?? '', kind: label(t.kind) ?? 'other' } : null),
-  turnStartedAt: number,
-  workingSubagents: (subs) => list(subs, DETAIL_LIMITS.subagents, (s) => ({ id: label(s.id) ?? '', name: label(s.name) ?? '' })),
-  awaiting: (threads) => list(threads, DETAIL_LIMITS.subagents, (t) => ({ id: label(t.id) ?? '', title: label(t.title) ?? '' })),
-  subagents: number,
-  live: (v) => v === true,
-  plan: (p) => (p && typeof p === 'object' ? { done: number(p.done), total: number(p.total), current: label(p.current) ?? '' } : null),
-  tokens: (t) => (t && typeof t === 'object' ? { output: number(t.output) } : null),
-  lines: (l) => (l && typeof l === 'object' ? { added: number(l.added), removed: number(l.removed) } : null),
-}
-
-export function keepSessionFields(session) {
-  const kept = {}
-  for (const [field, keep] of Object.entries(SESSION_FIELDS)) if (field in session) kept[field] = keep(session[field])
-  return kept
-}
-
-function withoutText(ask) {
-  if (!ask) return ask
-  if (ask.type === 'question') return { type: 'question', questions: [] }
-  if (ask.type === 'approval') return { type: 'approval', tool: ask.tool, target: '', kind: ask.kind }
-  if (ask.type === 'error') return { type: 'error', text: '' }
-  return ask
-}
-
-export function keepForAnotherDevice(kept) {
-  const out = { ...kept }
-  if ('ask' in out) out.ask = withoutText(out.ask)
-  if (out.tool) out.tool = { ...out.tool, target: '' }
-  if (out.awaiting) out.awaiting = out.awaiting.map(({ id }) => ({ id, title: '' }))
-  if (out.plan) out.plan = { ...out.plan, current: '' }
-  return out
-}
-
-const listOf = async (response) => {
-  const { sessions = [] } = response.ok ? await response.json() : {}
-  return (Array.isArray(sessions) ? sessions : []).filter((s) => s && typeof s.id === 'string')
-}
-
-export function threadgaugeSessions({ fetch = globalThis.fetch, find = () => locateThreadgauge({ fetch }), now = Date.now } = {}) {
-  let found = { at: -Infinity, where: null }
-  let older = { at: -Infinity, origin: null, list: [] }
-  async function olderList(origin) {
-    if (older.origin === origin && now() - older.at <= REUSE_OLDER_MS) return older.list
-    const list = await listOf(await fetch(`${origin}/api/history`, { signal: AbortSignal.timeout(HISTORY_TIMEOUT_MS) }))
-    older = { at: now(), origin, list }
-    return list
-  }
-  return async function sessions({ id = null, all = false, anotherDevice = false } = {}) {
-    if (now() - found.at > REUSE_FOUND_MS) found = { at: now(), where: await find() }
-    const where = found.where
-    if (!where) return { url: null, sessions: {} }
-    if (!id && !all) return { url: where.url, sessions: {} }
-    try {
-      const live = await listOf(await fetch(`${where.origin}/api/sessions`, { signal: AbortSignal.timeout(SESSIONS_TIMEOUT_MS) }))
-      const listed = new Set(live.map((s) => s.id))
-      const everything = all ? [...live, ...(await olderList(where.origin)).filter((s) => !listed.has(s.id))] : live
-      const wanted = everything.filter((s) => all || s.id === id)
-      const keep = (s) => (anotherDevice ? keepForAnotherDevice(keepSessionFields(s)) : keepSessionFields(s))
-      return { url: where.url, sessions: Object.fromEntries(wanted.map((s) => [s.id, keep(s)])) }
-    } catch {
-      found = { at: -Infinity, where: null }
-      return { url: null, sessions: {} }
-    }
-  }
-}
+import { DETAIL_LIMITS, clip, clipBlock } from '@threadcrumbs/common/lib/telemetry-fields'
+
+const FIRST_PORT = 5274
+const PORTS_TO_TRY = 20
+const LOOPBACKS = ['127.0.0.1', '::1']
+const PROBE_TIMEOUT_MS = 500
+const SESSIONS_TIMEOUT_MS = 2000
+const HISTORY_TIMEOUT_MS = 8000
+const REUSE_OLDER_MS = 15000
+const REUSE_FOUND_MS = 15000
+const ASK_QUESTIONS = 4
+const ASK_OPTIONS = 8
+const LABEL_MAX = 160
+const STATUS_MAX = 40
+const ASK_ID_MAX = 128
+
+const originOf = (host, port) => `http://${host.includes(':') ? `[${host}]` : host}:${port}`
+
+async function answersAsThreadgauge(origin, fetch) {
+  try {
+    const response = await fetch(`${origin}/api/about`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) })
+    return (await response.json())?.app === 'threadgauge'
+  } catch {
+    return false
+  }
+}
+
+export async function locateThreadgauge({ fetch = globalThis.fetch, first = FIRST_PORT, tries = PORTS_TO_TRY, hosts = LOOPBACKS } = {}) {
+  const probes = []
+  for (let port = first; port < first + tries; port++) for (const host of hosts) probes.push({ port, origin: originOf(host, port) })
+  const found = await Promise.all(probes.map(({ origin }) => answersAsThreadgauge(origin, fetch)))
+  const index = found.indexOf(true)
+  return index === -1 ? null : { url: `http://localhost:${probes[index].port}/`, origin: probes[index].origin }
+}
+
+export const findThreadgauge = async (options) => (await locateThreadgauge(options))?.url ?? null
+
+const text = (max) => (v) => (typeof v === 'string' ? clip(v, max) : null)
+const block = (max) => (v) => (typeof v === 'string' ? clipBlock(v, max) : null)
+const label = text(LABEL_MAX)
+const words = block(DETAIL_LIMITS.errorText)
+const number = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null)
+const list = (v, max, keep) => (Array.isArray(v) ? v.filter((x) => x && typeof x === 'object').slice(0, max).map(keep) : null)
+
+export const isAskId = (v) => typeof v === 'string' && v.length > 0 && v.length <= ASK_ID_MAX && !/[\u0000-\u001f\u007f]/.test(v)
+
+function keepAsk(ask) {
+  if (!ask || typeof ask !== 'object') return null
+  if (ask.type === 'question') {
+    const option = (o) => ({ label: label(o.label) ?? '', description: words(o.description) ?? '' })
+    const question = (q) => ({ header: label(q.header) ?? '', text: words(q.text) ?? '', options: list(q.options, ASK_OPTIONS, option) ?? [], multiple: q.multiple === true })
+    return { type: 'question', questions: list(ask.questions, ASK_QUESTIONS, question) ?? [] }
+  }
+  if (ask.type === 'approval') return { type: 'approval', tool: label(ask.tool) ?? '', target: label(ask.target) ?? '', kind: label(ask.kind) ?? 'other' }
+  if (ask.type === 'error') return { type: 'error', text: words(ask.text) ?? '' }
+  return { type: 'unknown' }
+}
+
+const SESSION_FIELDS = {
+  status: text(STATUS_MAX),
+  statusReason: text(STATUS_MAX),
+  ask: keepAsk,
+  context: (c) => (c && typeof c === 'object' ? { used: number(c.used), limit: number(c.limit) } : null),
+  tool: (t) => (t && typeof t === 'object' ? { name: label(t.name) ?? '', startedAt: number(t.startedAt), target: label(t.target) ?? '', kind: label(t.kind) ?? 'other' } : null),
+  turnStartedAt: number,
+  workingSubagents: (subs) => list(subs, DETAIL_LIMITS.subagents, (s) => ({ id: label(s.id) ?? '', name: label(s.name) ?? '' })),
+  awaiting: (threads) => list(threads, DETAIL_LIMITS.subagents, (t) => ({ id: label(t.id) ?? '', title: label(t.title) ?? '' })),
+  subagents: number,
+  live: (v) => v === true,
+  plan: (p) => (p && typeof p === 'object' ? { done: number(p.done), total: number(p.total), current: label(p.current) ?? '' } : null),
+  tokens: (t) => (t && typeof t === 'object' ? { output: number(t.output) } : null),
+  lines: (l) => (l && typeof l === 'object' ? { added: number(l.added), removed: number(l.removed) } : null),
+}
+
+export function keepSessionFields(session) {
+  const kept = {}
+  for (const [field, keep] of Object.entries(SESSION_FIELDS)) if (field in session) kept[field] = keep(session[field])
+  return kept
+}
+
+function withoutText(ask) {
+  if (!ask) return ask
+  if (ask.type === 'question') return { type: 'question', questions: [] }
+  if (ask.type === 'approval') return { type: 'approval', tool: ask.tool, target: '', kind: ask.kind }
+  if (ask.type === 'error') return { type: 'error', text: '' }
+  return ask
+}
+
+export function keepForAnotherDevice(kept) {
+  const out = { ...kept }
+  if ('ask' in out) out.ask = withoutText(out.ask)
+  if (out.tool) out.tool = { ...out.tool, target: '' }
+  if (out.awaiting) out.awaiting = out.awaiting.map(({ id }) => ({ id, title: '' }))
+  if (out.plan) out.plan = { ...out.plan, current: '' }
+  return out
+}
+
+const listOf = async (response) => {
+  const { sessions = [] } = response.ok ? await response.json() : {}
+  return (Array.isArray(sessions) ? sessions : []).filter((s) => s && typeof s.id === 'string')
+}
+
+export function threadgaugeSessions({ fetch = globalThis.fetch, find = () => locateThreadgauge({ fetch }), now = Date.now } = {}) {
+  let found = { at: -Infinity, where: null }
+  let older = { at: -Infinity, origin: null, list: [] }
+  async function olderList(origin) {
+    if (older.origin === origin && now() - older.at <= REUSE_OLDER_MS) return older.list
+    const list = await listOf(await fetch(`${origin}/api/history`, { signal: AbortSignal.timeout(HISTORY_TIMEOUT_MS) }))
+    older = { at: now(), origin, list }
+    return list
+  }
+  return async function sessions({ id = null, all = false, anotherDevice = false } = {}) {
+    if (now() - found.at > REUSE_FOUND_MS) found = { at: now(), where: await find() }
+    const where = found.where
+    if (!where) return { url: null, sessions: {} }
+    if (!id && !all) return { url: where.url, sessions: {} }
+    try {
+      const live = await listOf(await fetch(`${where.origin}/api/sessions`, { signal: AbortSignal.timeout(SESSIONS_TIMEOUT_MS) }))
+      const listed = new Set(live.map((s) => s.id))
+      const everything = all ? [...live, ...(await olderList(where.origin)).filter((s) => !listed.has(s.id))] : live
+      const wanted = everything.filter((s) => all || s.id === id)
+      const keep = (s) => (anotherDevice ? keepForAnotherDevice(keepSessionFields(s)) : keepSessionFields(s))
+      return { url: where.url, sessions: Object.fromEntries(wanted.map((s) => [s.id, keep(s)])) }
+    } catch {
+      found = { at: -Infinity, where: null }
+      return { url: null, sessions: {} }
+    }
+  }
+}