Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript
43.6 KB
Raw Blame
/**
 * `/runtime/*` — HTTP surface that agent-runner pods talk to.
 *
 * Every endpoint maps 1:1 to a method on `AgentRuntimeClient`. The pod
 * never accesses Postgres or Redis directly; it issues an HTTP call,
 * the server delegates to `inprocClient`, and the response is the same
 * JSON shape declared in `client.ts`.
 *
 * Auth: every request carries `Authorization: Bearer <agent-runtime
 * JWT>`. The JWT pins `{ agentId, companyId, computerId, assignmentId }`.
 * Endpoints take identity and placement from the *token* (not the request
 * body) and compare them with the live database row, so a compromised or
 * replaced runtime can't operate as another Agent placement.
 *
 * Mount at `/runtime` from `server/src/index.ts`. Not nested under
 * `/api` so a pod token is not mistaken for a human session. Human
 * `/api` auth is header-based (`Authorization: Bearer` or
 * `x-session-token`); there is no cookie session, and `authMiddleware`
 * never rejects a request on its own.
 */
import { json, type NextFunction, type Request, type Response, Router } from 'express'
import { publicBodyParserError } from '../../body-parser-errors.js'
import { AGENDA_CLASSIFIER_ERROR, claimStallNudge, classifyAgendaActionable, gatherAgentAgenda, renderAgendaBrief } from '../agenda.js'
import { runCli } from '../cli.js'
import { buildTriageRequest, gatherClaimsByConvo } from '../inbox-triage.js'
import {
  createAgentRun,
  finishAgentRunForOwner,
  recordAgentEventForOwner,
  recordTriage,
  touchAgentRunForOwner,
} from '../observability.js'
import { buildTeamRosterText, getPersona } from '../personas.js'
import { consumeAgentTurnToken } from '../scheduler.js'
import {
  isRuntimeAgentAuthorized,
  withRuntimeAgentRunAuthorization,
  withRuntimeAttachmentReadAuthorization,
  withRuntimeConversationAuthorization,
  withRuntimeMessageReadAuthorization,
} from './authorization.js'
import { normalizeByoaSource } from './byoa-source.js'
import { buildRuntimeArgv } from './cli-argv.js'
import type { RuntimeTokenUsage } from './client.js'
import { attachFsEndpoints } from './fs-endpoints.js'
import { inprocClient } from './inproc-client.js'
import { type AgentRuntimeClaims, verifyAgentToken } from './jwt.js'
import { attachWakeStream, } from './wake-bus.js'
import { normalizeStorageKey } from '../../storage-keys.js'
import { storage } from '../../storage.js'

export type { WakeEvent } from './wake-bus.js'

interface RuntimeRequest extends Request {
  agent?: AgentRuntimeClaims
}

type AuthorizedAgentRuntimeClaims = AgentRuntimeClaims & { companyId: string }
const MAX_LLM_HOPS_PER_BATCH = 100
const MAX_PG_INTEGER = 2_147_483_647
const RUN_STATUSES = new Set(['running', 'completed', 'failed', 'skipped'])
const EVENT_LEVELS = new Set(['debug', 'info', 'warn', 'error'])
const LLM_CALL_STATUSES = new Set(['ok', 'rate_limited', 'timeout', 'failed'])

function isPlainRecord(value: unknown): value is Record<string, unknown> {
  return value !== null && typeof value === 'object' && !Array.isArray(value)
}

function isNonNegativePgInteger(value: unknown): value is number {
  return Number.isInteger(value) && (value as number) >= 0 && (value as number) <= MAX_PG_INTEGER
}

function isRuntimeTokenUsage(value: unknown): value is RuntimeTokenUsage {
  if (!isPlainRecord(value)) return false
  const counts = [value.inputTokens, value.cachedInputTokens, value.cacheCreationTokens, value.outputTokens]
  return counts.every(isNonNegativePgInteger)
    && (counts as number[]).reduce((sum, count) => sum + count, 0) <= MAX_PG_INTEGER
}

async function authMiddleware(req: RuntimeRequest, res: Response, next: NextFunction): Promise<void> {
  const header = req.headers['authorization']
  if (!header || typeof header !== 'string' || !header.startsWith('Bearer ')) {
    res.status(401).json({ error: 'missing bearer token' })
    return
  }

  let claims: AgentRuntimeClaims
  try {
    claims = verifyAgentToken(header.slice('Bearer '.length).trim())
  } catch (err) {
    res.status(401).json({ error: err instanceof Error ? err.message : 'invalid token' })
    return
  }

  if (!claims.companyId) {
    res.status(403).json({ error: 'companyId claim required' })
    return
  }

  try {
    // A valid signature only proves what was true when the token was minted.
    // Re-check tenant, Computer, and opaque placement generation on every
    // request so moves, offboarding, and Computer revocation invalidate an old
    // runtime immediately across the whole surface.
    if (!(await isRuntimeAgentAuthorized(claims))) {
      res.status(403).json({ error: 'agent runtime assignment changed or was revoked' })
      return
    }
  } catch (err) {
    console.error('[runtime] token assignment validation failed', err instanceof Error ? err.message : err)
    res.status(503).json({ error: 'runtime authorization unavailable' })
    return
  }

  req.agent = claims
  next()
}

function withAgent(
  handler: (claims: AuthorizedAgentRuntimeClaims, req: RuntimeRequest, res: Response) => Promise<void>,
) {
  return async (req: RuntimeRequest, res: Response): Promise<void> => {
    const claims = req.agent
    if (!claims) { res.status(401).json({ error: 'unauthenticated' }); return }
    if (!claims.companyId) { res.status(403).json({ error: 'companyId claim required' }); return }
    try {
      await handler(claims as AuthorizedAgentRuntimeClaims, req, res)
    } catch (err) {
      const msg = err instanceof Error ? err.message : String(err)
      console.error(`[runtime] ${req.method} ${req.path} failed`, msg)
      res.status(500).json({ error: 'runtime request failed' })
    }
  }
}

export const runtimeRouter: Router = Router()
runtimeRouter.use(authMiddleware as never)
// JWT signature, tenant claim, and exact current Agent placement are checked
// before any body parser reads JSON. Most runtime calls are small; the FUSE
// whole-file write endpoint installs its compatibility parser at the route.
const runtimeJsonParser = json({ limit: '4mb' })
runtimeRouter.use((req, res, next) => {
  if (req.method === 'PUT' && /^\/fs\/write\/?$/.test(req.path)) {
    next()
    return
  }
  runtimeJsonParser(req, res, next)
})

// ─── wake stream: server pushes events to the agent's long-running pod ─

runtimeRouter.get('/wake-stream', withAgent(async (c, _req, res) => {
  await attachWakeStream(c.sub, res, {
    // The HTTP middleware validates at connection time. Re-check before every
    // event as well because this response can remain open across a tenant move.
    authorize: () => isRuntimeAgentAuthorized(c),
  })
  // Don't end — attachWakeStream keeps the response open until the
  // client disconnects.
}))

// ─── workspace FS: the Pod's FUSE driver lives over these endpoints ─

attachFsEndpoints(runtimeRouter, withAgent)

// ─── canonical action surface: cumora CLI ──────────────────────────
//
// Pods don't run the cumora CLI in-process (they have no DB access).
// Instead the in-pod `cumora` binary is a thin curl shim that POSTs
// argv here; we run it on the server's behalf. Auth: bearer token is
// the same agent-runtime JWT; we *strip* any `--as` the caller passed
// and inject the token's pinned agentId so a compromised pod can't
// impersonate another agent.
runtimeRouter.post('/cli', withAgent(async (c, req, res) => {
  const body = req.body as { argv?: unknown } | undefined
  const argv = Array.isArray(body?.argv) ? body!.argv.filter((x): x is string => typeof x === 'string') : null
  if (!argv) { res.status(400).json({ error: 'argv (string[]) required' }); return }

  // Drop any client-supplied `--as <id>` / `--as=<id>` — the JWT pins
  // identity, and we prepend `--as <jwt.sub>` so runCli resolves to the
  // pinned agent. Implementation lives in cli-argv.ts so the strip
  // rules can be unit-tested in isolation.
  const result = await runCli(buildRuntimeArgv(c.sub, argv))
  res.json({
    text: result.text,
    exitCode: result.exitCode,
    ok: result.ok,
    sideEffects: result.sideEffects ?? [],
    attachmentReads: result.attachmentReads ?? [],
  })
}))

// ─── reads ──────────────────────────────────────────────────────────

runtimeRouter.get('/persona', withAgent(async (c, _req, res) => {
  res.json({ persona: await inprocClient.loadPersona(c.sub) })
}))

runtimeRouter.post('/conversation/company-id', withAgent(async (_c, req, res) => {
  const body = req.body as { conversationId?: string } | undefined
  if (!body?.conversationId) { res.status(400).json({ error: 'conversationId required' }); return }
  res.json({ companyId: await inprocClient.getConversationCompanyId(body.conversationId) })
}))

runtimeRouter.get('/inbox', withAgent(async (c, req, res) => {
  const rows = await inprocClient.loadInbox(c.sub)
  // Advance the freshness-preflight "seen" boundary per-convo to the max
  // seq we just surfaced — the caller will SHOW these rows to the agent
  // (default path: daemon's snapshotUnread → brief → big brain). For
  // probe-only callers (maybeSteer's "should I steer?" check; the
  // engine-failure target lookup), pass `?probe=1` to skip the advance:
  // those paths don't necessarily inject the rows into the agent's
  // session, and advancing here would pollute the baseline past what
  // the brain has actually been shown, letting duplicate-collisions
  // slip past cmdReply's preflight (observed today: bram saw Iris's
  // "1" via maybeSteer's loadInbox, baseline advanced past Iris's seq,
  // Bram's preflight then saw nothing newer and posted a duplicate "1").
  const probe = String(req.query.probe ?? '').trim() === '1'
  if (!probe && rows.length > 0) {
    const perConvoMaxSeq = new Map<string, number>()
    for (const r of rows) {
      const cur = perConvoMaxSeq.get(r.conversation_id) ?? 0
      if (r.sequence > cur) perConvoMaxSeq.set(r.conversation_id, r.sequence)
    }
    const { recordSeen } = await import('../seen-boundary.js')
    await Promise.all([...perConvoMaxSeq.entries()].map(([cid, seq]) => recordSeen(c.sub, cid, seq)))
  }
  res.json({ rows })
}))

// BYOA engines use this authenticated endpoint instead of a raw storage URL.
// The object must be both a Cumora chat attachment and referenced by a message
// this exact runtime placement can read. The server redirects to a freshly
// generated storage URL; callers cannot select an arbitrary fetch target.
runtimeRouter.get('/attachment', withAgent(async (c, req, res) => {
  const key = normalizeStorageKey(typeof req.query.key === 'string' ? req.query.key : '')
  const messageId = typeof req.query.messageId === 'string' && req.query.messageId
    ? req.query.messageId
    : undefined
  if (!key?.startsWith('attachments/')) {
    res.status(400).json({ error: 'invalid chat attachment key' })
    return
  }
  if (!(await withRuntimeAttachmentReadAuthorization({
    agentId: c.sub,
    companyId: c.companyId,
    key,
    messageId,
  }))) {
    res.status(403).json({ error: 'attachment is not readable by this agent' })
    return
  }
  const metadata = await storage.statObject(key)
  if (!metadata) {
    res.status(404).json({ error: 'attachment not found' })
    return
  }
  res.setHeader('Cache-Control', 'private, no-store')
  res.redirect(303, await storage.publicUrl(key))
}))

// BYOA: build the triage request server-side (we have the DB for inbox+context)
// but DON'T run the model — return either an empty-inbox verdict (nothing to
// judge) or the {instructions, input} prompt. The daemon runs it on its LOCAL
// small brain, so judgment never leaves the operator's machine and never spends
// cloud quota. This is the whole point of BYOA: local compute. NB: no regex
// decides anything — every actionability/mode call is the small model's.
runtimeRouter.get('/inbox-triage/payload', withAgent(async (c, _req, res) => {
  if (!c.companyId) { res.status(403).json({ error: 'companyId claim required' }); return }
  const persona = await inprocClient.loadPersona(c.sub)
  if (!persona) { res.status(404).json({ error: 'agent not found' }); return }
  // A still-valid token can outlive an administrative tenant reassignment.
  // Pin the subject's current tenant before loading its inbox; otherwise an old
  // tenant's daemon can ask this route to assemble prompt content from the new
  // tenant while loadContext alone remains correctly scoped to the JWT claim.
  if (persona.companyId !== c.companyId) {
    res.status(403).json({ error: 'agent does not belong to token tenant' })
    return
  }
  const inbox = await inprocClient.loadInbox(c.sub)
  const convoIds = [...new Set(inbox.map((m) => m.conversation_id))]
  // Content-blind cost floor (NOT a loop decision). The daemon self-polls every
  // 20s, bypassing the scheduler's fan-out rate limit, so a runaway could spin
  // the local model unbounded. Bound it by the agent's activation budget — same
  // counter the cloud fan-out uses. Whether to reply is still 100% the small
  // model's call (it sees "thread heat" and goes quiet on agent-only threads);
  // this only stops cost from running away if the model fails to.
  if (convoIds.length > 0 && !(await consumeAgentTurnToken(c.sub))) {
    res.json({ verdict: {
      actionable: false,
      reason: 'turn-rate floor: over activation budget this minute — deferring (the next minute or a human revives it)',
      promptNote: '',
      source: 'rate-limited',
    } })
    return
  }
  const context = await inprocClient.loadContext(c.sub, c.companyId, convoIds)
  // Authoritative "real work here" signal (active worklog claims per
  // convo) — lets the gate suppress unclaimed agent-only chatter from FACT, and
  // sets the claim-aware loop-cap tier. Same gather the cloud path uses. The
  // supervision signal rides along (same as the cloud path): a human actively
  // reading the company elevates activity side-rooms to the HIGH backstop.
  const [claimsByConvo, humanActiveInCompany] = await Promise.all([
    gatherClaimsByConvo(inbox),
    persona.companyId ? inprocClient.humanRecentlyActive(persona.companyId).catch(() => false) : Promise.resolve(false),
  ])
  // Pure GATE — TRULY identical to the cloud agent's triage. Cloud (turn.ts) calls
  // classifyInboxTriage WITHOUT `strict`, i.e. the lenient prompt that biases toward
  // "relevant → wake". BYOA used to pass strict:true — the long, aggressive
  // skip-everything prompt (ACK-loop / duplicate / thread-heat suppression) meant as
  // a token-saving conservative gate. That divergence is exactly why BYOA went silent
  // on a repeated human directive (it judged "新开狼人杀 again = duplicate → skip")
  // while Cloud answered. Same model, DIFFERENT prompt → different behavior. Drop
  // strict so BYOA runs the EXACT same gate prompt as Cloud. Cost is still bounded by
  // the per-minute activation rate floor above, not by an aggressive prompt.
  res.json(buildTriageRequest({ agentId: c.sub, persona, inbox, context, claimsByConvo, humanActiveInCompany }))
}))

// BOARD-AWARENESS for BYOA: the daemon has no DB, so the server gathers this
// agent's actionable AGENDA — Kanban cards assigned to / @-mentioning them in
// non-done columns + due calendar events — and runs the SAME cheap cerebellum
// classifier the cloud idle scheduler (idle.ts) uses, returning a focused brief
// when there is real work. This is what makes a BYOA agent PROACTIVELY pick up
// assigned board tasks instead of only reacting to a chat push. The classifier
// runs on the cloud support model (Cumora-subsidized), so it does NOT spend the
// operator's quota; the operator's brain is spent only on the actual work. The
// daemon gates calls behind a "quiet for N minutes" window (its anti-loop), so
// this isn't hit every poll. Empty / non-actionable → { actionable: false }.
runtimeRouter.get('/agenda', withAgent(async (c, _req, res) => {
  if (!c.companyId) { res.json({ actionable: false }); return }
  const agenda = await gatherAgentAgenda(c.sub, c.companyId)
  if (agenda.cards.length === 0 && agenda.events.length === 0 && agenda.stalls.length === 0) {
    res.json({ actionable: false, cards: 0, events: 0, stalls: 0 })
    return
  }
  const persona = await getPersona(c.sub)
  if (!persona) { res.json({ actionable: false }); return }
  const verdict = await classifyAgendaActionable({ persona, companyId: c.companyId, agenda, agentId: c.sub })
  if (!verdict.actionable) {
    res.json({ actionable: false, cards: agenda.cards.length, events: agenda.events.length, stalls: agenda.stalls.length, reason: verdict.reason })
    return
  }
  // The cerebellum said yes. Now CLAIM each stall so exactly ONE agent nudges it
  // (and never twice for the same stall state) — keep only the stalls this agent
  // won; others are being handled by whoever claimed first. Cards/events are
  // per-agent (no race), so they pass through untouched.
  //
  // Pass source='fallback' when the verdict came from the deterministic
  // fallback (classifier 503) so the NX TTL is short (5min vs 45min) — a "no"
  // from the chosen agent shouldn't permanently lock out other members.
  const nudgeSource = verdict.reason.startsWith(AGENDA_CLASSIFIER_ERROR) ? 'fallback' : 'classified'
  const wonStalls = []
  for (const s of agenda.stalls) {
    if (await claimStallNudge(s.conversationId, { source: nudgeSource })) wonStalls.push(s)
  }
  const finalAgenda = { cards: agenda.cards, events: agenda.events, stalls: wonStalls }
  // If stalls were the ONLY reason and another agent already claimed them all,
  // there's nothing left for THIS agent to do — don't wake its big brain.
  if (finalAgenda.cards.length === 0 && finalAgenda.events.length === 0 && finalAgenda.stalls.length === 0) {
    res.json({ actionable: false, cards: 0, events: 0, stalls: 0, reason: 'stall already claimed by another agent' })
    return
  }
  res.json({
    actionable: true,
    focus: verdict.focus,
    brief: renderAgendaBrief(finalAgenda, verdict.focus),
    cards: finalAgenda.cards.length,
    events: finalAgenda.events.length,
    stalls: finalAgenda.stalls.length,
  })
}))

runtimeRouter.post('/memory/query', withAgent(async (c, req, res) => {
  const body = req.body as {
    queryText?: string
    limits?: { semantic?: number; recent?: number; total?: number }
    projectIds?: string[]
    conversationIds?: string[]
  } | undefined
  const rows = await inprocClient.loadMemory(c.sub, body?.queryText ?? '', body?.limits, {
    projectIds: body?.projectIds,
    conversationIds: body?.conversationIds,
  })
  res.json({ rows })
}))

runtimeRouter.post('/context', withAgent(async (c, req, res) => {
  if (!c.companyId) { res.status(403).json({ error: 'companyId claim required' }); return }
  const body = req.body as { conversationIds?: string[] } | undefined
  const rows = await inprocClient.loadContext(c.sub, c.companyId, body?.conversationIds ?? [])
  res.json({ rows })
}))

runtimeRouter.get('/climate', withAgent(async (c, _req, res) => {
  res.json({ rows: await inprocClient.loadClimate(c.sub) })
}))

runtimeRouter.get('/skills', withAgent(async (c, _req, res) => {
  res.json({ rows: await inprocClient.loadSkillsIndex(c.sub) })
}))

runtimeRouter.post('/faces', withAgent(async (c, req, res) => {
  if (!c.companyId) { res.status(403).json({ error: 'companyId claim required' }); return }
  const body = req.body as { participantIds?: string[] } | undefined
  const rows = await inprocClient.loadFaces(c.companyId, body?.participantIds ?? [])
  res.json({ rows })
}))

runtimeRouter.get('/system-prompt', withAgent(async (c, _req, res) => {
  res.json({ prompt: await inprocClient.buildSystemPrompt(c.sub) })
}))

// The live team roster (names + roles + ids), scoped to the agent's company.
// BYOA agents fetch this each real turn so they know WHO their teammates are and
// what each does — the cloud agent already gets it baked into its system prompt.
runtimeRouter.get('/roster', withAgent(async (c, _req, res) => {
  const persona = await inprocClient.loadPersona(c.sub)
  if (!persona) { res.status(404).json({ error: 'agent not found' }); return }
  res.json({ roster: await buildTeamRosterText(persona.companyId, c.sub) })
}))

// ─── status + presence ──────────────────────────────────────────────

runtimeRouter.post('/status', withAgent(async (c, req, res) => {
  const body = req.body as { status?: string } | undefined
  if (!body?.status) { res.status(400).json({ error: 'status required' }); return }
  await inprocClient.setStatus(c.sub, body.status as 'avail' | 'working' | 'thinking' | 'waiting' | 'resting')
  res.json({ ok: true })
}))

runtimeRouter.post('/status/heartbeat', withAgent(async (c, req, res) => {
  const body = req.body as { status?: string } | undefined
  if (!body?.status) { res.status(400).json({ error: 'status required' }); return }
  await inprocClient.heartbeatStatus(c.sub, body.status as 'working' | 'thinking' | 'waiting')
  res.json({ ok: true })
}))

runtimeRouter.post('/typing', withAgent(async (c, req, res) => {
  const body = req.body as { conversationId?: string; done?: boolean } | undefined
  if (!body?.conversationId) { res.status(400).json({ error: 'conversationId required' }); return }
  const gate = await withRuntimeConversationAuthorization({
    agentId: c.sub,
    companyId: c.companyId,
    conversationIds: [body.conversationId],
    task: () => inprocClient.publishTyping({
      conversationId: body.conversationId as string,
      agentId: c.sub,
      done: Boolean(body.done),
      companyId: c.companyId,
    }),
  })
  if (!gate.authorized) { res.status(403).json({ error: 'not a member of that conversation' }); return }
  res.json({ ok: true })
}))

// ─── observability ──────────────────────────────────────────────────

runtimeRouter.post('/runs', withAgent(async (c, req, res) => {
  const body = req.body as {
    trigger?: Record<string, unknown>
    inputMessageIds?: string[]
    inboxCount?: number
    fingerprint?: string
  } | undefined
  if ((body !== undefined && !isPlainRecord(body))
    || (body?.trigger !== undefined && !isPlainRecord(body.trigger))
    || (body?.inputMessageIds !== undefined
      && (!Array.isArray(body.inputMessageIds) || body.inputMessageIds.some((id) => typeof id !== 'string')))
    || (body?.inboxCount !== undefined && !isNonNegativePgInteger(body.inboxCount))
    || (body?.fingerprint !== undefined && typeof body.fingerprint !== 'string')) {
    res.status(400).json({ error: 'invalid run payload' }); return
  }
  const gate = await withRuntimeAgentRunAuthorization({
    agentId: c.sub,
    companyId: c.companyId,
    runIds: [],
    task: (client) => createAgentRun({
      agentId: c.sub,
      companyId: c.companyId,
      trigger: body?.trigger,
      inputMessageIds: body?.inputMessageIds,
      inboxCount: body?.inboxCount,
      fingerprint: body?.fingerprint,
    }, client),
  })
  if (!gate.authorized || !gate.result) {
    res.status(403).json({ error: 'agent does not belong to token tenant' }); return
  }
  res.json({ runId: gate.result })
}))

runtimeRouter.post('/events', withAgent(async (c, req, res) => {
  const body = req.body as {
    runId?: string
    kind?: string
    level?: 'debug' | 'info' | 'warn' | 'error'
    title?: string
    data?: Record<string, unknown>
    stage?: string
  } | undefined
  if (typeof body?.runId !== 'string' || !body.runId
    || typeof body.kind !== 'string' || !body.kind
    || typeof body.title !== 'string' || !body.title) {
    res.status(400).json({ error: 'runId, kind, title required' }); return
  }
  if ((body.level !== undefined && !EVENT_LEVELS.has(body.level))
    || (body.data !== undefined && !isPlainRecord(body.data))
    || (body.stage !== undefined && typeof body.stage !== 'string')) {
    res.status(400).json({ error: 'invalid event payload' }); return
  }
  const gate = await withRuntimeAgentRunAuthorization({
    agentId: c.sub,
    companyId: c.companyId,
    runIds: [body.runId],
    task: (client) => recordAgentEventForOwner({
      runId: body.runId!,
      agentId: c.sub,
      companyId: c.companyId,
      kind: body.kind!,
      level: body.level,
      title: body.title!,
      data: body.data,
      stage: body.stage,
    }, client),
  })
  if (!gate.authorized || !gate.result) { res.status(404).json({ error: 'agent run not found' }); return }
  res.json({ ok: true })
}))

// Record one LOCAL (BYOA) triage in the cost ledger. The daemon runs triage on
// the operator's own machine, so the server never sees its usage unless the
// daemon posts it here. Identity comes from the JWT. Best-effort. (Cloud triage
// is recorded inline in classifyInboxTriage — it never hits this route.)
runtimeRouter.post('/triage', withAgent(async (c, req, res) => {
  const body = req.body as {
    source?: string
    model?: string | null
    actionable?: boolean
    reason?: string | null
    usage?: import('./client.js').RuntimeTokenUsage | null
    daemonVersion?: string
  } | undefined
  if ((body !== undefined && !isPlainRecord(body))
    || (body?.source !== undefined && typeof body.source !== 'string')
    || (body?.model !== undefined && body.model !== null && typeof body.model !== 'string')
    || (body?.actionable !== undefined && typeof body.actionable !== 'boolean')
    || (body?.reason !== undefined && body.reason !== null && typeof body.reason !== 'string')
    || (body?.usage !== undefined && body.usage !== null && !isRuntimeTokenUsage(body.usage))
    || (body?.daemonVersion !== undefined && typeof body.daemonVersion !== 'string')) {
    res.status(400).json({ error: 'invalid triage payload' }); return
  }
  const daemonVersion = typeof body?.daemonVersion === 'string' && body.daemonVersion.trim() ? body.daemonVersion.trim().slice(0, 32) : null
  const source = normalizeByoaSource(body?.source)
  void recordTriage({
    agentId: c.sub,
    companyId: c.companyId,
    source,
    model: body?.model ?? null,
    actionable: body?.actionable === true,
    reason: body?.reason ?? null,
    usage: body?.usage ?? null,
  })
  // ALSO mirror to the universal ledger so BYOA local triage shows up next to
  // cloud spend on the Observability page. The agent_triages row keeps the
  // verdict / reason for the triage-economics view; llm_calls just holds the
  // raw call shape. Same fire-and-forget discipline as recordTriage above.
  if (body?.usage) {
    const { recordLlmCall } = await import('../llm-ledger.js')
    void recordLlmCall({
      purpose: 'inbox-triage',
      companyId: c.companyId,
      agentId: c.sub,
      source,
      model: body.model ?? '<unknown>',
      usage: {
        inputTokens: body.usage.inputTokens ?? 0,
        cachedInputTokens: body.usage.cachedInputTokens ?? 0,
        cacheCreationTokens: body.usage.cacheCreationTokens ?? 0,
        outputTokens: body.usage.outputTokens ?? 0,
      },
      latencyMs: 0,
      status: 'ok',
      extras: { actionable: body.actionable === true, reason: (body.reason ?? '').slice(0, 200) },
      daemonVersion,
    })
  }
  res.json({ ok: true })
}))

// Per-HOP trajectory for BYOA agents. The daemon's ClaudeSession /
// CodexSession emits one EngineHopReport per assistant message (Claude) or
// per turn-completed (Codex) and batches them into one POST per N hops or
// every ~250ms (whichever first). This endpoint accepts a batch + inserts
// one llm_calls row per hop with the appropriate source ('byoa-claude' |
// 'byoa-codex' | 'byoa-grok' | 'byoa-cursor' | 'byoa-opencode' | 'byoa-pi').
// The server commits the bounded batch atomically; the daemon still treats an
// HTTP/DB failure as best-effort so observability can never break the wake.
runtimeRouter.post('/llm-calls', withAgent(async (c, req, res) => {
  const body = req.body as {
    source?: string
    /** agent-cli (npm cumora) version of the daemon emitting this batch. One
     *  version per batch — there's no mid-batch upgrade. Missing on pre-
     *  version daemons → rows recorded with daemon_version=NULL. */
    daemonVersion?: string
    hops?: Array<{
      purpose?: string
      runId?: string | null
      conversationId?: string | null
      model?: string
      usage?: import('./client.js').RuntimeTokenUsage | null
      latencyMs?: number
      status?: 'ok' | 'rate_limited' | 'timeout' | 'failed'
      error?: string | null
      extras?: Record<string, unknown>
    }>
  } | undefined
  if ((body !== undefined && !isPlainRecord(body))
    || (body?.source !== undefined && typeof body.source !== 'string')
    || (body?.daemonVersion !== undefined && typeof body.daemonVersion !== 'string')
    || (body?.hops !== undefined && !Array.isArray(body.hops))) {
    res.status(400).json({ error: 'invalid LLM batch payload' }); return
  }
  const source = normalizeByoaSource(body?.source)
  const daemonVersion = typeof body?.daemonVersion === 'string' && body.daemonVersion.trim() ? body.daemonVersion.trim().slice(0, 32) : null
  const hops = Array.isArray(body?.hops) ? body!.hops : []
  if (hops.length === 0) { res.json({ ok: true, inserted: 0 }); return }
  if (hops.length > MAX_LLM_HOPS_PER_BATCH) {
    res.status(413).json({ error: `too many hops (max ${MAX_LLM_HOPS_PER_BATCH})` }); return
  }
  const runIds: string[] = []
  for (const hop of hops) {
    if (!isPlainRecord(hop)) {
      res.status(400).json({ error: 'each hop must be an object' }); return
    }
    if (hop.runId !== undefined && hop.runId !== null) {
      if (typeof hop.runId !== 'string' || !hop.runId) {
        res.status(400).json({ error: 'runId must be a non-empty string or null' }); return
      }
      runIds.push(hop.runId)
    }
    if ((hop.purpose !== undefined && typeof hop.purpose !== 'string')
      || (hop.conversationId !== undefined && hop.conversationId !== null && typeof hop.conversationId !== 'string')
      || (hop.model !== undefined && typeof hop.model !== 'string')
      || (hop.usage !== undefined && hop.usage !== null && !isRuntimeTokenUsage(hop.usage))
      || (hop.latencyMs !== undefined && !isNonNegativePgInteger(hop.latencyMs))
      || (hop.status !== undefined && (typeof hop.status !== 'string' || !LLM_CALL_STATUSES.has(hop.status)))
      || (hop.error !== undefined && hop.error !== null && typeof hop.error !== 'string')
      || (hop.extras !== undefined && !isPlainRecord(hop.extras))) {
      res.status(400).json({ error: 'invalid hop payload' }); return
    }
  }
  // Whitelist purposes the daemon may declare — anything else gets coerced
  // to 'agent-turn' so a future daemon version naming an unknown purpose
  // doesn't smuggle a free-form string into the rollup.
  const KNOWN_PURPOSES = new Set([
    'agent-turn', 'inbox-triage', 'synthetic-wake-gate', 'agenda',
    'compaction', 'completion-verify', 'steer-summary',
  ])
  const records = hops.map((h) => {
    const purpose = (typeof h.purpose === 'string' && KNOWN_PURPOSES.has(h.purpose) ? h.purpose : 'agent-turn') as 'agent-turn'
    const model = typeof h.model === 'string' && h.model ? h.model : '<unknown>'
    return {
      purpose,
      companyId: c.companyId,
      agentId: c.sub,
      runId: h.runId ?? null,
      conversationId: h.conversationId ?? null,
      source,
      model,
      usage: h.usage ? {
        inputTokens: h.usage.inputTokens ?? 0,
        cachedInputTokens: h.usage.cachedInputTokens ?? 0,
        cacheCreationTokens: h.usage.cacheCreationTokens ?? 0,
        outputTokens: h.usage.outputTokens ?? 0,
      } : null,
      latencyMs: typeof h.latencyMs === 'number' && Number.isFinite(h.latencyMs) ? h.latencyMs : 0,
      status: h.status ?? 'ok',
      error: h.error ?? null,
      extras: h.extras,
      daemonVersion,
    }
  })
  const { recordLlmCallsBatch } = await import('../llm-ledger.js')
  const gate = await withRuntimeAgentRunAuthorization({
    agentId: c.sub,
    companyId: c.companyId,
    runIds,
    task: (client) => recordLlmCallsBatch(records, client),
  })
  if (!gate.authorized) { res.status(404).json({ error: 'agent run not found' }); return }
  res.json({ ok: true, inserted: hops.length })
}))

// Heartbeat a long engine turn so the 10-min stale-run sweeper doesn't reap it.
// BYOA emits no mid-run events (cloud does), so its daemon pings this while the
// engine turn is in flight. Best-effort: a DB hiccup must not break the turn.
runtimeRouter.post('/runs/:runId/heartbeat', withAgent(async (c, req, res) => {
  const runId = String(req.params.runId)
  const gate = await withRuntimeAgentRunAuthorization({
    agentId: c.sub,
    companyId: c.companyId,
    runIds: [runId],
    task: (client) => touchAgentRunForOwner({
      runId,
      agentId: c.sub,
      companyId: c.companyId,
    }, client),
  })
  if (!gate.authorized || !gate.result?.owned) { res.status(404).json({ error: 'agent run not found' }); return }
  res.json({ ok: true, touched: gate.result.touched })
}))

runtimeRouter.post('/runs/:runId/finish', withAgent(async (c, req, res) => {
  const runId = String(req.params.runId)
  const body = req.body as {
    status?: 'running' | 'completed' | 'failed' | 'skipped'
    summary?: string
    error?: string | null
    toolCallCount?: number
    tokenCount?: number
    model?: string | null
    usage?: import('./client.js').RuntimeTokenUsage | null
  } | undefined
  if (!body?.status) { res.status(400).json({ error: 'status required' }); return }
  if (typeof body.status !== 'string' || !RUN_STATUSES.has(body.status)
    || (body.summary !== undefined && typeof body.summary !== 'string')
    || (body.error !== undefined && body.error !== null && typeof body.error !== 'string')
    || (body.toolCallCount !== undefined && !isNonNegativePgInteger(body.toolCallCount))
    || (body.tokenCount !== undefined && !isNonNegativePgInteger(body.tokenCount))
    || (body.model !== undefined && body.model !== null && typeof body.model !== 'string')
    || (body.usage !== undefined && body.usage !== null && !isRuntimeTokenUsage(body.usage))) {
    res.status(400).json({ error: 'invalid finish payload' }); return
  }
  const gate = await withRuntimeAgentRunAuthorization({
    agentId: c.sub,
    companyId: c.companyId,
    runIds: [runId],
    task: (client) => finishAgentRunForOwner({
      runId,
      agentId: c.sub,
      companyId: c.companyId,
      status: body.status!,
      summary: body.summary,
      error: body.error,
      toolCallCount: body.toolCallCount,
      tokenCount: body.tokenCount,
      model: body.model,
      usage: body.usage,
    }, client),
  })
  if (!gate.authorized || !gate.result) { res.status(404).json({ error: 'agent run not found' }); return }
  res.json({ ok: true })
}))

// ─── steering busy heartbeat ────────────────────────────────────────
//
// The pod's HttpRuntimeClient pings these every ~2s during a turn so
// the cumora-server's message-routing path can tell at a glance
// whether an agent is currently mid-turn (→ deliver a steer event)
// or idle (→ deliver a normal wake). agentId comes from the JWT, not
// the body — same impersonation defence as every other endpoint here.

runtimeRouter.post('/busy/heartbeat', withAgent(async (c, req, res) => {
  const body = req.body as { ttlSec?: number } | undefined
  const ttlSec = typeof body?.ttlSec === 'number' && body.ttlSec > 0 && body.ttlSec <= 300 ? body.ttlSec : 5
  await inprocClient.recordBusyHeartbeat(c.sub, ttlSec)
  res.json({ ok: true })
}))

runtimeRouter.post('/busy/clear', withAgent(async (c, _req, res) => {
  await inprocClient.clearBusyHeartbeat(c.sub)
  res.json({ ok: true })
}))

// ─── thinking-claim — peer-visible "I'm composing" signal ─────────
runtimeRouter.post('/thinking/mark', withAgent(async (c, req, res) => {
  const body = req.body as { conversationIds?: string[]; ttlSec?: number } | undefined
  const ids = Array.isArray(body?.conversationIds)
    ? [...new Set(body.conversationIds.filter((s) => typeof s === 'string'))].sort()
    : []
  if (ids.length > 100) { res.status(400).json({ error: 'at most 100 conversationIds' }); return }
  const ttlSec = typeof body?.ttlSec === 'number' && body.ttlSec > 0 && body.ttlSec <= 600 ? body.ttlSec : 60
  const gate = await withRuntimeConversationAuthorization({
    agentId: c.sub,
    companyId: c.companyId,
    conversationIds: ids,
    task: async () => {
      await inprocClient.markThinking(c.sub, ids, ttlSec)
      // Stamp the freshness-preflight compose-anchor at turn start. NX-style
      // preservation keeps heartbeats from moving the anchor later.
      if (ids.length > 0) {
        const { recordComposeAnchor, getComposeAnchor } = await import('../seen-boundary.js')
        const now = Date.now()
        await Promise.all(ids.map(async (cid) => {
          const existing = await getComposeAnchor(c.sub, cid)
          if (existing > 0 && now - existing < 30 * 60_000) return
          await recordComposeAnchor(c.sub, cid, now)
        }))
      }
    },
  })
  if (!gate.authorized) { res.status(403).json({ error: 'not a member of every conversation' }); return }
  res.json({ ok: true })
}))
runtimeRouter.post('/thinking/unmark', withAgent(async (c, req, res) => {
  const body = req.body as { conversationIds?: string[] } | undefined
  const ids = Array.isArray(body?.conversationIds)
    ? [...new Set(body.conversationIds.filter((s) => typeof s === 'string'))].sort()
    : []
  if (ids.length > 100) { res.status(400).json({ error: 'at most 100 conversationIds' }); return }
  const gate = await withRuntimeConversationAuthorization({
    agentId: c.sub,
    companyId: c.companyId,
    conversationIds: ids,
    task: async () => {
      await inprocClient.unmarkThinking(c.sub, ids)
      if (ids.length > 0) {
        const { clearComposeAnchor } = await import('../seen-boundary.js')
        await Promise.all(ids.map((cid) => clearComposeAnchor(c.sub, cid)))
      }
    },
  })
  if (!gate.authorized) { res.status(403).json({ error: 'not a member of every conversation' }); return }
  res.json({ ok: true })
}))
runtimeRouter.get('/thinking/peek', withAgent(async (c, req, res) => {
  const cid = typeof req.query.conversationId === 'string' ? req.query.conversationId : ''
  if (!cid) { res.status(400).json({ error: 'conversationId required' }); return }
  const gate = await withRuntimeConversationAuthorization({
    agentId: c.sub,
    companyId: c.companyId,
    conversationIds: [cid],
    task: () => inprocClient.peekThinking(cid),
  })
  if (!gate.authorized) { res.status(403).json({ error: 'not a member of that conversation' }); return }
  res.json({ agents: gate.result ?? [] })
}))

// ─── worklog — anti-duplicate-work claims ───────────────────────────
// Mirrors the thinking-claim endpoints but for heavy actions
// (web-search, doc draft, image gen) rather than typing indicators.
runtimeRouter.post('/worklog/claim', withAgent(async (c, req, res) => {
  const body = req.body as {
    scopeKey?: string
    taskType?: string
    subject?: string
    ttlSec?: number
  } | undefined
  if (!body?.scopeKey || !body.taskType || !body.subject) {
    res.status(400).json({ error: 'scopeKey, taskType, subject required' }); return
  }
  const scopeConversationIds = body.scopeKey === `tenant:${c.companyId}` ? [] : [body.scopeKey]
  const gate = await withRuntimeConversationAuthorization({
    agentId: c.sub,
    companyId: c.companyId,
    conversationIds: scopeConversationIds,
    task: () => inprocClient.claimWork({
      scopeKey: body.scopeKey as string,
      agentId: c.sub,
      taskType: body.taskType as Parameters<typeof inprocClient.claimWork>[0]['taskType'],
      subject: body.subject as string,
      ttlSec: typeof body.ttlSec === 'number' && body.ttlSec > 0 && body.ttlSec <= 3600 ? body.ttlSec : undefined,
    }),
  })
  if (!gate.authorized) { res.status(403).json({ error: 'worklog scope is not authorized' }); return }
  res.json(gate.result)
}))
runtimeRouter.post('/worklog/release', withAgent(async (c, req, res) => {
  const body = req.body as {
    scopeKey?: string
    taskType?: string
    subject?: string
  } | undefined
  if (!body?.scopeKey || !body.taskType || !body.subject) {
    res.status(400).json({ error: 'scopeKey, taskType, subject required' }); return
  }
  const scopeConversationIds = body.scopeKey === `tenant:${c.companyId}` ? [] : [body.scopeKey]
  const gate = await withRuntimeConversationAuthorization({
    agentId: c.sub,
    companyId: c.companyId,
    conversationIds: scopeConversationIds,
    task: () => inprocClient.releaseWork({
      scopeKey: body.scopeKey as string,
      agentId: c.sub,
      taskType: body.taskType as Parameters<typeof inprocClient.releaseWork>[0]['taskType'],
      subject: body.subject as string,
    }),
  })
  if (!gate.authorized) { res.status(403).json({ error: 'worklog scope is not authorized' }); return }
  res.json({ ok: true })
}))
runtimeRouter.get('/worklog/peek', withAgent(async (c, req, res) => {
  const sk = typeof req.query.scopeKey === 'string' ? req.query.scopeKey : ''
  if (!sk) { res.status(400).json({ error: 'scopeKey required' }); return }
  const scopeConversationIds = sk === `tenant:${c.companyId}` ? [] : [sk]
  const gate = await withRuntimeConversationAuthorization({
    agentId: c.sub,
    companyId: c.companyId,
    conversationIds: scopeConversationIds,
    task: () => inprocClient.peekWorklog(sk),
  })
  if (!gate.authorized) { res.status(403).json({ error: 'worklog scope is not authorized' }); return }
  res.json({ entries: gate.result ?? [] })
}))

// ─── steering dedup: advance per-agent conversation_reads cursor ─────
//
// At turn end the pod tells us which messages it already consumed via
// a mid-turn steer drain, so the next wake's loadInbox doesn't surface
// them again. agentId from JWT (c.sub).
runtimeRouter.post('/conversation/mark-read', withAgent(async (c, req, res) => {
  const body = req.body as { conversationId?: string; upToMessageId?: string } | undefined
  if (!body?.conversationId || !body.upToMessageId) {
    res.status(400).json({ error: 'conversationId and upToMessageId required' }); return
  }
  const gate = await withRuntimeMessageReadAuthorization({
    agentId: c.sub,
    companyId: c.companyId,
    conversationId: body.conversationId,
    messageId: body.upToMessageId,
    task: (client) => inprocClient.markConversationRead({
      agentId: c.sub,
      companyId: c.companyId,
      conversationId: body.conversationId as string,
      upToMessageId: body.upToMessageId as string,
    }, client),
  })
  if (!gate.authorized) { res.status(403).json({ error: 'message is not readable in that conversation' }); return }
  res.json({ ok: true })
}))

runtimeRouter.post('/notices', withAgent(async (c, req, res) => {
  const body = req.body as {
    conversationId?: string
    noticeKind?: string
    text?: string
    dedupeKey?: string
    dedupeTtlSec?: number
  } | undefined
  if (!body?.conversationId || !body.noticeKind || !body.text || !body.dedupeKey) {
    res.status(400).json({ error: 'conversationId, noticeKind, text, dedupeKey required' })
    return
  }
  // Identity comes from the JWT, NEVER the body. postSystemNotice performs
  // participant + conversation membership validation and the write under one
  // transaction, closing the check-then-write revocation window.
  const out = await inprocClient.postSystemNotice({
    conversationId: body.conversationId,
    companyId: c.companyId,
    agentId: c.sub,
    noticeKind: body.noticeKind,
    text: body.text,
    dedupeKey: body.dedupeKey,
    dedupeTtlSec: body.dedupeTtlSec ?? 3600,
  })
  if (!out.authorized) {
    res.status(403).json({ error: 'not a member of that conversation' })
    return
  }
  res.json({ posted: out.posted })
}))

// Keep body-parser failures machine-readable and avoid exposing its default
// HTML error page to runtime clients. Authentication failures have already
// returned before this parser can run.
runtimeRouter.use((err: unknown, _req: Request, res: Response, next: NextFunction) => {
  const parserError = publicBodyParserError(err)
  if (parserError) {
    res.status(parserError.status).json({ error: parserError.message })
    return
  }
  next(err)
})