@huynle/hub 0.9.1 → 0.10.0

package/src/central/agent/conversation.ts

@@ -0,0 +1,625 @@
+// Conversation for apps (AF3, docs/plans/2026-11-08-app-front-contracts.md §1.2, §5; Hub decisions zn7oxf4g,
+// nixct956 2): an app holds a conversation with one of ITS sessions through its server.
+//
+//   GET  /api/agent/sessions/:addr/stream        conversation:read   SSE of closed-allowlist frames (below)
+//   POST /api/agent/sessions/:addr/conversation  conversation:write  {on, front?} → {on, agent?, front?}
+//   POST /api/agent/sessions/:addr/utterance     conversation:write  {text 1–4000} → 202 {inboxID} (an action)
+//   POST /api/agent/sessions/:addr/interrupt     conversation:write  → 204
+// Typed turns are the existing act prompt (acting-routes.ts, which admits conversation:write too); the log is widened
+// to conversation:read (read-routes.ts). Both use appSessionCheck from here.
+//
+// "The app's sessions" for conversation (§1.2; user decision 2026-11-09): started by a launch whose `by` is the app's
+// party, or covered by an active grant the app holds that allows `prompt` and whose scope covers the session's project
+// (an answer-only or stop-only grant exposes nothing); subagents count with their root. Every other session, a deleted
+// one and the user's Concierge sessions answer 404 not_found exactly like an unknown address.
+// Writes by an app also need a grant allowing `prompt` that covers the session (403 forbidden for a session it only
+// launched), the user's kill
+// switch off (423 paused); utterances count against the grant's maxActionsPerHour (429, Grants.consume: increment
+// first, then check, so parallel writes never pass it). Every app write is in the agent audit as app:<id>.
+// An utterance carries the same hub-prompt provenance as a typed app turn (a deliver of kind "prompt" from
+// app:<id> under the grant, steered into the running turn), never the console's plain steer (the user's own voice).
+//
+// The stream: `ready` first (once subscribed), then `delta` (the session's own text, never a subagent's, never
+// reasoning; rootID dropped), `say`, `heard`, `status` (state + blocker count, never blocker text) and
+// `conversation`; `reset {refresh}` when a resume point is not covered; `end {reason}` last. `id:` lines carry the
+// hub's live event ids (the console stream's), `event: ping` heartbeats carry the latest cursor. Resume with
+// Last-Event-ID (or ?last=): one pod replays from its live event log (it holds streamed text too); in a cluster the
+// shared log never holds streamed text (cluster/live.ts), so a covered resume replays and then always sends
+// reset {log}. A cursor the log does not cover: ready, then reset {log, status, conversation}.
+// Re-checks every recheckMs and on revocation pulses (AppStreams.pulse): the credential (token_expired, revoked,
+// a scope removed: revoked), the session (gone: deleted, AppStreams.deleted on this pod at once, the directory's
+// deletedAt on any pod) and ownership (grant: also a grant narrowed to drop prompt). Caps per hub process: 4 streams per app
+// credential, 20 per user (AppStreams.reserve: a synchronous check-and-count, so parallel connects never pass
+// them). A reader leaving more than bufferMaxBytes unsent gets end {slow}; the hub's fan-out never waits for it.
+// Streamed text is model output and untrusted: sent as it is (JSON-encoded), never marked up.
+import { APP_STREAM_LIMITS, type AppStreamEndReason, type SessionState } from "../../protocol"
+import type { Registry } from "../registry"
+import { type GrantVerb, inProjects } from "./policy"
+import { type AgentActor, type AppActor, readCredentials, type VerifyResult } from "./actor"
+import type { ActingSwitch } from "./acting-switch"
+import { auditOf } from "./acting"
+import type { AgentAudit, AuditDecision, AuditOutcome } from "./audit"
+import type { Directory } from "./directory"
+import { partyFromActor } from "./envelope"
+import { AgentError } from "./errors"
+import type { Grant, Grants } from "./grants"
+import { AGENT_JSON_BODY_MAX, boundedText } from "./body"
+import type { AgentContext, AgentRoute } from "./routes"
+
+// A literal: routes.ts imports this module (AGENT_PREFIX is not initialised yet when it loads).
+const PREFIX = "/api/agent/sessions/:addr"
+const NO_STORE = { "cache-control": "no-store" }
+const SSE_HEADERS = { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" }
+const RETRY = `retry: ${APP_STREAM_LIMITS.retryMs}\n\n`
+/** Longest utterance (characters), the console's and the apps'. */
+export const MAX_UTTERANCE_CHARS = 4000
+const STATES: ReadonlySet<string> = new Set(["idle", "working", "blocked", "error"])
+
+// ---------- the event source (http.ts: the console stream's listeners or the cluster live fan-out) ----------
+
+export interface SourceEvent {
+  /** The live event id (absent for streamed text in a cluster). */
+  readonly id?: string
+  readonly message: { readonly type: string; readonly [key: string]: unknown }
+}
+
+export interface StreamSource {
+  /** Cluster mode: the shared log holds no streamed text, so a resume always ends with reset {log}. */
+  readonly clustered: boolean
+  /** The user's live events from now on. */
+  subscribe(userID: string, handler: (event: SourceEvent) => void): { readonly ready: Promise<void>; close(): void }
+  /** The user's events after `lastID`, oldest first; undefined when the log does not cover the gap. */
+  since(userID: string, lastID: string): Promise<readonly SourceEvent[] | undefined>
+  /** The id of the user's latest event. */
+  latest(userID: string): Promise<string>
+}
+
+// ---------- caps and revocation pulses ----------
+
+/** Deleted session IDs AppStreams remembers. */
+const DELETED_KEPT = 5000
+
+/** Open app streams of this hub process: the caps (per credential, per user) and the revocation pulses. */
+export class AppStreams {
+  private readonly perCredential = new Map<string, number>()
+  private readonly perUser = new Map<string, number>()
+  private readonly checks = new Map<string, Set<() => void>>()
+  /** Sessions deleted while this process ran (bounded): gone at once, before any directory write lands. */
+  private readonly removed = new Set<string>()
+
+  constructor(private readonly limits: { readonly perApp: number; readonly perUser: number } = { perApp: APP_STREAM_LIMITS.streamsPerApp, perUser: APP_STREAM_LIMITS.streamsPerUser }) {}
+
+  /**
+   * Takes a stream slot of the credential (and its user), or undefined at a cap. Synchronous check-and-count, so
+   * parallel connects can never pass a cap. The release is idempotent.
+   */
+  reserve(userID: string, credential: string): (() => void) | undefined {
+    const key = `${userID}\n${credential}`
+    const mine = this.perCredential.get(key) ?? 0
+    const all = this.perUser.get(userID) ?? 0
+    if (mine >= this.limits.perApp || all >= this.limits.perUser) return undefined
+    this.perCredential.set(key, mine + 1)
+    this.perUser.set(userID, all + 1)
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      const left = (this.perCredential.get(key) ?? 1) - 1
+      if (left > 0) this.perCredential.set(key, left)
+      else this.perCredential.delete(key)
+      const userLeft = (this.perUser.get(userID) ?? 1) - 1
+      if (userLeft > 0) this.perUser.set(userID, userLeft)
+      else this.perUser.delete(userID)
+    }
+  }
+
+  /** Runs `check` on every pulse for the user; returns the unsubscribe. */
+  watch(userID: string, check: () => void): () => void {
+    let set = this.checks.get(userID)
+    if (!set) this.checks.set(userID, (set = new Set()))
+    set.add(check)
+    return () => {
+      set.delete(check)
+      if (!set.size) this.checks.delete(userID)
+    }
+  }
+
+  /** Something that may revoke a stream changed (a token, connection, grant or user): re-check the user's streams now. */
+  pulse(userID: string): void {
+    for (const check of [...(this.checks.get(userID) ?? [])]) check()
+  }
+
+  /** A session of the user was deleted: its streams end (gone) now. */
+  deleted(userID: string, sessionID: string): void {
+    this.removed.add(sessionID)
+    if (this.removed.size > DELETED_KEPT) this.removed.delete(this.removed.values().next().value!)
+    this.pulse(userID)
+  }
+
+  /** Whether this process saw the session deleted. */
+  wasDeleted(sessionID: string): boolean {
+    return this.removed.has(sessionID)
+  }
+
+  /** Open streams of a user (tests, diagnostics). */
+  open(userID: string): number {
+    return this.perUser.get(userID) ?? 0
+  }
+}
+
+// ---------- frames ----------
+
+type Frame = Record<string, unknown> & { readonly type: string }
+
+/** A live message as an app frame for `sessionID` (whose root is `rootID`), or undefined when it is not one. */
+export function appFrame(message: SourceEvent["message"], sessionID: string, rootID: string): Frame | undefined {
+  const m = message as Record<string, unknown>
+  switch (m.type) {
+    case "delta":
+      if (m.sessionID !== sessionID || typeof m.text !== "string") return undefined
+      return { type: "delta", sessionID, ...(typeof m.messageID === "string" ? { messageID: m.messageID } : {}), ...(isOrdinal(m.ordinal) ? { ordinal: m.ordinal } : {}), text: m.text }
+    case "say":
+      if (m.sessionID !== sessionID || typeof m.messageID !== "string" || !isOrdinal(m.ordinal) || typeof m.text !== "string") return undefined
+      return { type: "say", sessionID, messageID: m.messageID, ordinal: m.ordinal, ...(isOrdinal(m.seq) ? { seq: m.seq } : {}), text: m.text }
+    case "heard":
+      if (m.sessionID !== sessionID || typeof m.inboxID !== "string") return undefined
+      return { type: "heard", sessionID, inboxID: m.inboxID }
+    case "conversation":
+      if (m.sessionID !== sessionID || typeof m.on !== "boolean") return undefined
+      return { type: "conversation", sessionID, on: m.on, ...(typeof m.front === "boolean" ? { front: m.front } : {}), ...(m.reason === "front_failed" ? { reason: "front_failed" } : {}) }
+    case "status": {
+      if (m.sessionID !== rootID || !Array.isArray(m.sessions)) return undefined
+      const entry = (m.sessions as Array<Record<string, unknown>>).find((s) => s?.id === sessionID)
+      if (!entry || typeof entry.state !== "string" || !STATES.has(entry.state)) return undefined
+      const blockers = Array.isArray(entry.blockers) ? entry.blockers.length : 0
+      return { type: "status", sessionID, state: entry.state, blockers, ...(typeof entry.since === "number" && Number.isFinite(entry.since) ? { since: entry.since } : {}) }
+    }
+    default:
+      return undefined
+  }
+}
+
+const isOrdinal = (value: unknown): value is number => Number.isInteger(value) && (value as number) >= 0
+
+// ---------- the stream ----------
+
+export interface AppStreamOptions {
+  readonly userID: string
+  readonly sessionID: string
+  readonly rootID: string
+  readonly source: StreamSource
+  readonly signal: AbortSignal
+  /** Last-Event-ID or ?last=. */
+  readonly lastID?: string
+  /** The session now, for `ready`. */
+  ready(): { readonly status: SessionState; readonly conversation: { readonly on: boolean; readonly front?: boolean } }
+  /** The re-check: a reason ends the stream; undefined keeps it. A throw keeps it (the next one tries again). */
+  check(): Promise<AppStreamEndReason | undefined>
+  /** Revocation pulses: `run` re-checks at once; returns the unsubscribe. */
+  subscribeChecks?(run: () => void): () => void
+  /** Once, when the stream ends for any reason (the cap slot). */
+  onClose?(): void
+  readonly draining?: AbortSignal
+  readonly now?: () => number
+  readonly heartbeatMs?: number
+  readonly recheckMs?: number
+  readonly bufferMaxBytes?: number
+}
+
+/** The SSE response of one app stream (see the header). */
+export function appStream(options: AppStreamOptions): Response {
+  const { userID, sessionID, rootID, source } = options
+  if (options.draining?.aborted) {
+    options.onClose?.()
+    return new Response(RETRY, { headers: SSE_HEADERS })
+  }
+  const now = options.now ?? Date.now
+  const max = options.bufferMaxBytes ?? APP_STREAM_LIMITS.bufferMaxBytes
+  const encoder = new TextEncoder()
+  let controller!: ReadableStreamDefaultController<Uint8Array>
+  let open = true
+  let cursor: string | undefined
+  let lastStatus: string | undefined
+  let subscription: { close(): void } | undefined
+  const timers: ReturnType<typeof setInterval>[] = []
+  const unsubscribe: (() => void)[] = []
+
+  const finish = () => {
+    if (!open) return
+    open = false
+    for (const timer of timers) clearInterval(timer)
+    subscription?.close()
+    for (const off of unsubscribe) off()
+    options.onClose?.()
+  }
+  const close = () => {
+    finish()
+    try {
+      controller.close()
+    } catch {}
+  }
+  const enqueue = (chunk: string): boolean => {
+    try {
+      controller.enqueue(encoder.encode(chunk))
+      return true
+    } catch {
+      finish()
+      return false
+    }
+  }
+  const end = (reason: AppStreamEndReason) => {
+    if (!open) return
+    enqueue(`data: ${JSON.stringify({ type: "end", at: now(), reason })}\n\n`)
+    close()
+  }
+  const write = (chunk: string) => {
+    if (!open || !enqueue(chunk)) return
+    // More than the limit waits unsent: the reader is too slow; never queue without bound.
+    if ((controller.desiredSize ?? 0) < 0) end("slow")
+  }
+  const frame = (data: Frame, id?: string) => {
+    if (data.type === "status") {
+      const key = JSON.stringify(data)
+      if (key === lastStatus) return
+      lastStatus = key
+    }
+    write(`${id ? `id: ${id}\n` : ""}data: ${JSON.stringify(data)}\n\n`)
+  }
+  const replayed = new Set<string>()
+  const forward = (event: SourceEvent) => {
+    if (!open) return
+    if (event.id !== undefined) {
+      if (replayed.has(event.id)) return
+      cursor = event.id
+    }
+    const data = appFrame(event.message, sessionID, rootID)
+    if (data) frame(data, event.id)
+  }
+
+  let checking = false
+  let again = false
+  const runCheck = async () => {
+    if (!open) return
+    if (checking) {
+      again = true
+      return
+    }
+    checking = true
+    try {
+      do {
+        again = false
+        const reason = await options.check().catch((cause: unknown) => {
+          console.error(`[hub] app stream re-check failed: ${(cause as Error).message}`)
+          return undefined
+        })
+        if (reason) return end(reason)
+      } while (again && open)
+    } finally {
+      checking = false
+    }
+  }
+
+  const run = async () => {
+    let pending: SourceEvent[] | undefined = []
+    const subscribed = source.subscribe(userID, (event) => (pending ? pending.push(event) : forward(event)))
+    subscription = subscribed
+    if (!open) subscribed.close()
+    try {
+      await subscribed.ready
+      const missed = options.lastID ? await source.since(userID, options.lastID) : undefined
+      const latest = await source.latest(userID)
+      if (!open) return
+      const covered = options.lastID !== undefined && missed !== undefined
+      cursor = covered ? options.lastID : latest
+      const state = options.ready()
+      frame({ type: "ready", at: now(), sessionID, status: state.status, conversation: { on: state.conversation.on, ...(state.conversation.front !== undefined ? { front: state.conversation.front } : {}) } }, cursor)
+      if (covered) {
+        for (const event of missed!) {
+          if (event.id !== undefined) {
+            replayed.add(event.id)
+            cursor = event.id
+          }
+          const data = appFrame(event.message, sessionID, rootID)
+          if (data) frame(data, event.id)
+        }
+        if (source.clustered) frame({ type: "reset", at: now(), refresh: ["log"] })
+      } else if (options.lastID !== undefined) frame({ type: "reset", at: now(), refresh: ["log", "status", "conversation"] })
+    } catch (cause) {
+      console.error(`[hub] app stream did not start: ${(cause as Error).message}`)
+      write(RETRY)
+      return close()
+    }
+    const waiting = pending
+    pending = undefined
+    for (const event of waiting) forward(event)
+  }
+
+  const stream = new ReadableStream<Uint8Array>(
+    {
+      start(c) {
+        controller = c
+        options.signal.addEventListener("abort", () => close(), { once: true })
+        if (options.draining) {
+          const draining = options.draining
+          const onDrain = () => {
+            if (!open) return
+            enqueue(RETRY)
+            close()
+          }
+          draining.addEventListener("abort", onDrain, { once: true })
+          unsubscribe.push(() => draining.removeEventListener("abort", onDrain))
+        }
+        timers.push(setInterval(() => write(`event: ping\n${cursor ? `id: ${cursor}\n` : ""}data: 0\n\n`), options.heartbeatMs ?? APP_STREAM_LIMITS.heartbeatMs))
+        timers.push(setInterval(() => void runCheck(), options.recheckMs ?? APP_STREAM_LIMITS.recheckMs))
+        if (options.subscribeChecks) unsubscribe.push(options.subscribeChecks(() => void runCheck()))
+        void run()
+      },
+      cancel() {
+        finish()
+      },
+    },
+    { highWaterMark: max, size: (chunk) => chunk?.byteLength ?? 0 },
+  )
+  return new Response(stream, { headers: SSE_HEADERS })
+}
+
+// ---------- "the app's sessions" (§1.2) ----------
+
+export interface AppSessionDeps {
+  readonly registry: Pick<Registry, "rootOf" | "session" | "sessionTenant">
+  readonly directory: Pick<Directory, "resolveOne"> & Partial<Pick<Directory, "deleted">>
+  readonly grants: Pick<Grants, "list">
+  /** (AF3) Sessions this process saw deleted (AppStreams.wasDeleted). */
+  readonly deletedHere?: (sessionID: string) => boolean
+  /** Launches: `by` is the launcher's party (`app:<id>`). */
+  readonly launches?: { list(userID: string): Promise<readonly { readonly by?: string; readonly sessionID?: string }[]> }
+  /** (CON-04) Sessions only the user acts on (the Concierge's): never an app's. */
+  readonly protects?: (userID: string, sessionID: string) => Promise<boolean>
+}
+
+export interface AppTarget {
+  readonly sessionID: string
+  readonly rootID: string
+  /** The session's directory when a process reports it (or last reported it). */
+  readonly directory?: string
+}
+
+const notFound = (addr: string) => new AgentError("not_found", `No session ${addr}`)
+
+/** The addressed session of the user (not_found otherwise; an ambiguity reads as not_found too: no IDs leak). */
+export function locateSession(deps: Pick<AppSessionDeps, "registry" | "directory" | "deletedHere">, userID: string, addr: string): AppTarget {
+  let sessionID: string
+  try {
+    sessionID = deps.directory.resolveOne(userID, addr).sessionID
+  } catch (cause) {
+    if (cause instanceof AgentError && (cause.code === "not_found" || cause.code === "ambiguous")) throw notFound(addr)
+    throw cause
+  }
+  const tenant = deps.registry.sessionTenant(sessionID)
+  if (tenant !== undefined && tenant !== userID) throw notFound(addr)
+  const rootID = deps.registry.rootOf(sessionID) ?? sessionID
+  // Deleted (it, or its root): gone, like an unknown session.
+  for (const id of new Set([sessionID, rootID])) if (deps.deletedHere?.(id) || deps.directory.deleted?.(userID, id)) throw notFound(addr)
+  const directory = deps.registry.session(rootID)?.directory ?? deps.registry.session(sessionID)?.directory
+  return { sessionID, rootID, ...(directory ? { directory } : {}) }
+}
+
+/**
+ * Whether the target is the app's: launched by it, or covered by an active grant it holds that allows one of `verbs`
+ * (any verb when none are given: contract §1.2's base rule, e.g. for AF4). Conversation (stream, log, writes) passes
+ * CONVERSATION_VERBS (user decision 2026-11-09: only a prompt grant exposes a conversation).
+ */
+export async function isAppSession(deps: AppSessionDeps, actor: AppActor, userID: string, target: AppTarget, verbs?: readonly GrantVerb[]): Promise<boolean> {
+  if (deps.protects && ((await deps.protects(userID, target.rootID)) || (await deps.protects(userID, target.sessionID)))) return false
+  const party = `app:${actor.tokenID}`
+  if (target.directory) {
+    for (const grant of await deps.grants.list(userID)) {
+      if (grant.state !== "active" || grant.holder !== party || !inProjects(target.directory, grant.scope.projects)) continue
+      if (!verbs || verbs.some((verb) => grant.allow.includes(verb))) return true
+    }
+  }
+  if (deps.launches) {
+    for (const launch of await deps.launches.list(userID)) {
+      if (launch.by === party && launch.sessionID !== undefined && (launch.sessionID === target.rootID || launch.sessionID === target.sessionID)) return true
+    }
+  }
+  return false
+}
+
+/** The grant verbs that make a session an app's for conversation (stream, log, writes). */
+export const CONVERSATION_VERBS: readonly GrantVerb[] = ["prompt"]
+
+/** The addressed session when it is the app's for conversation; not_found otherwise. Users: their own sessions. */
+export async function appSessionCheck(deps: AppSessionDeps, actor: AgentActor, userID: string, addr: string): Promise<AppTarget> {
+  const target = locateSession(deps, userID, addr)
+  if (actor.kind === "app" && !(await isAppSession(deps, actor, userID, target, CONVERSATION_VERBS))) throw notFound(addr)
+  return target
+}
+
+// ---------- the routes ----------
+
+/** What the conversation routes run on the hub (http.ts: the console's conversation machinery). */
+export interface ConversationPorts {
+  /** Conversation mode on/off (front: the voice front), as POST /api/sessions/:id/conversation does. */
+  conversation(sessionID: string, on: boolean, front: boolean, options: { readonly taps: boolean }): Promise<{ readonly on: boolean; readonly agent?: string; readonly front?: boolean }>
+  /**
+   * An utterance to the session (its front while one is active), tracked for `heard`. With `prompt`: delivered as an
+   * agent prompt with that provenance (an app's); without: the console's steer (the user's own).
+   */
+  utterance(sessionID: string, text: string, prompt?: { readonly from: string; readonly to: string; readonly grant: string }): Promise<string>
+  /** Barge-in: stops the front's turn (or the session's). */
+  interrupt(sessionID: string): Promise<void>
+  /** Conversation mode now (front: present once a front was asked for). */
+  conversationOf(sessionID: string): { readonly on: boolean; readonly front?: boolean }
+  /** The session's state now. */
+  stateOf(sessionID: string): SessionState
+}
+
+export interface ConversationRouteDeps extends AppSessionDeps {
+  readonly ports: ConversationPorts
+  readonly source: StreamSource
+  readonly streams: AppStreams
+  readonly grants: Pick<Grants, "list" | "usable" | "consume">
+  readonly acting: Pick<ActingSwitch, "ensureActing">
+  readonly audit: Pick<AgentAudit, "record">
+  readonly store: { user(id: string): { readonly disabled?: boolean } | undefined }
+  /** Verifies a bearer again (the re-check): the hub's bearer verifiers in order. */
+  verify(token: string): Promise<VerifyResult>
+  readonly cookieName: string
+  readonly draining?: AbortSignal
+  readonly now?: () => number
+  readonly heartbeatMs?: number
+  readonly recheckMs?: number
+  readonly bufferMaxBytes?: number
+}
+
+type Body = Record<string, unknown>
+
+async function bodyOf(request: Request, optional = false): Promise<Body> {
+  const raw = await boundedText(request, AGENT_JSON_BODY_MAX)
+  if (!raw.trim() && optional) return {}
+  const value: unknown = JSON.parse(raw)
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new AgentError("invalid", "Body must be a JSON object")
+  return value as Body
+}
+
+/** A port's failure without its text (never pass upstream or internal error text to apps). */
+function portFailure(cause: unknown): unknown {
+  if (cause instanceof AgentError) return cause
+  const status = (cause as { status?: unknown }).status
+  const message = cause instanceof Error ? cause.message : ""
+  if (status === 409 || /disconnected|offline|no process|timed out/i.test(message)) return new AgentError("offline", "The session's machine is offline or did not answer")
+  console.error(`[hub] conversation write failed: ${message}`)
+  return new AgentError("internal", "Internal error")
+}
+
+export function conversationRoutes(deps: ConversationRouteDeps): AgentRoute[] {
+  const READ = { scope: "conversation:read" } as const
+  const WRITE = { scope: "conversation:write" } as const
+
+  /** The write check order for apps: the app's session (404) → root only → kill switch → prompt grant → hourly cap → kill switch. */
+  async function write<T>(context: AgentContext, verb: "conversation" | "utterance" | "interrupt", counts: boolean, run: (target: AppTarget, grant?: Grant) => Promise<T>): Promise<T> {
+    const { actor, user, params } = context
+    const target = await appSessionCheck(deps, actor, user.id, params.addr!)
+    if (target.rootID !== target.sessionID) throw new AgentError("invalid", "A conversation is with a root session, not a subagent session")
+    if (!deps.registry.session(target.sessionID)) throw new AgentError("offline", "No process reports this session now")
+    if (actor.kind !== "app") return run(target).catch((cause: unknown) => Promise.reject(portFailure(cause)))
+    let grant: Grant | undefined
+    const record = (decision: AuditDecision, outcome: AuditOutcome, reason?: string) =>
+      deps.audit.record(user.id, { actor: partyFromActor(actor), verb, target: { sessionID: target.sessionID }, ...(grant ? { grant: grant.id } : {}), decision, ...(reason ? { reason } : {}), outcome })
+    try {
+      deps.acting.ensureActing(user.id)
+      const usable = target.directory ? await deps.grants.usable(actor, "prompt", { directory: target.directory }) : []
+      if (!usable.length) throw new AgentError("forbidden", "No grant lets this app prompt in this session", { hint: "The user grants prompt on the session's project" })
+      grant = usable[0]!
+      if (counts) await deps.grants.consume(grant)
+      deps.acting.ensureActing(user.id)
+      const result = await run(target, grant).catch((cause: unknown) => Promise.reject(portFailure(cause)))
+      await record("allow", "ok")
+      return result
+    } catch (cause) {
+      const [decision, outcome] = auditOf(cause)
+      await record(decision, outcome, cause instanceof Error ? cause.message : undefined)
+      throw cause
+    }
+  }
+
+  return [
+    {
+      method: "GET",
+      path: `${PREFIX}/stream`,
+      allow: READ,
+      async handle(context) {
+        const { actor, user, request, url, params } = context
+        const target = await appSessionCheck(deps, actor, user.id, params.addr!)
+        // Apps by their credential; the user's own devices (they reach every route) by device.
+        const credential = actor.kind === "app" ? `app:${actor.tokenID}` : actor.kind === "user" ? `device:${actor.deviceID}` : `session:${actor.sessionID}`
+        const release = deps.streams.reserve(user.id, credential)
+        if (!release) {
+          throw new AgentError("rate_limited", `At most ${APP_STREAM_LIMITS.streamsPerApp} streams per app and ${APP_STREAM_LIMITS.streamsPerUser} per user`, { hint: "Close a stream first", extra: { retryAfter: 5 } })
+        }
+        const bearer = readCredentials(request, deps.cookieName).bearer
+        let directory = target.directory
+        const check = async (): Promise<AppStreamEndReason | undefined> => {
+          const owner = deps.store.user(user.id)
+          if (!owner || owner.disabled) return "revoked"
+          let current: AgentActor = actor
+          if (actor.kind === "app") {
+            const verified = bearer ? await deps.verify(bearer) : undefined
+            if (verified === "expired") return "token_expired"
+            if (!verified || verified.kind !== "app" || verified.tokenID !== actor.tokenID || verified.userID !== user.id) return "revoked"
+            if (!verified.scopes.includes("conversation:read")) return "revoked"
+            current = verified
+          }
+          let now: AppTarget
+          try {
+            now = locateSession(deps, user.id, target.sessionID)
+          } catch (cause) {
+            if (cause instanceof AgentError && cause.code === "not_found") return "gone"
+            throw cause
+          }
+          // A session briefly not reported keeps the directory it had (its grant still covers it).
+          directory = now.directory ?? directory
+          if (current.kind === "app" && !(await isAppSession(deps, current, user.id, { ...now, ...(directory ? { directory } : {}) }, CONVERSATION_VERBS))) return "grant"
+          return undefined
+        }
+        const lastID = request.headers.get("last-event-id") ?? url.searchParams.get("last") ?? undefined
+        return appStream({
+          userID: user.id,
+          sessionID: target.sessionID,
+          rootID: target.rootID,
+          source: deps.source,
+          signal: request.signal,
+          ...(lastID ? { lastID } : {}),
+          ready: () => ({ status: deps.ports.stateOf(target.sessionID), conversation: deps.ports.conversationOf(target.sessionID) }),
+          check,
+          subscribeChecks: (run) => deps.streams.watch(user.id, run),
+          onClose: release,
+          ...(deps.draining ? { draining: deps.draining } : {}),
+          ...(deps.now ? { now: deps.now } : {}),
+          ...(deps.heartbeatMs !== undefined ? { heartbeatMs: deps.heartbeatMs } : {}),
+          ...(deps.recheckMs !== undefined ? { recheckMs: deps.recheckMs } : {}),
+          ...(deps.bufferMaxBytes !== undefined ? { bufferMaxBytes: deps.bufferMaxBytes } : {}),
+        })
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/conversation`,
+      allow: WRITE,
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        const { on, front } = body
+        if (typeof on !== "boolean" || (front !== undefined && typeof front !== "boolean")) throw new AgentError("invalid", "Expected {on: boolean, front?: boolean}")
+        const result = await write(context, "conversation", false, (target) => deps.ports.conversation(target.sessionID, on, front === true, { taps: context.actor.kind === "user" }))
+        return Response.json({ on: result.on, ...(result.agent !== undefined ? { agent: result.agent } : {}), ...(result.front !== undefined ? { front: result.front } : {}) }, { headers: NO_STORE })
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/utterance`,
+      allow: WRITE,
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        const text = typeof body.text === "string" ? body.text.trim() : ""
+        if (!text) throw new AgentError("invalid", "text must be a non-empty string", { extra: { limit: MAX_UTTERANCE_CHARS } })
+        if (text.length > MAX_UTTERANCE_CHARS) throw new AgentError("invalid", `An utterance is at most ${MAX_UTTERANCE_CHARS} characters`, { extra: { limit: MAX_UTTERANCE_CHARS } })
+        const { actor, params } = context
+        const inboxID = await write(context, "utterance", true, (target, grant) =>
+          deps.ports.utterance(target.sessionID, text, actor.kind === "app" && grant ? { from: `app:${actor.tokenID}`, to: params.addr!, grant: grant.id } : undefined),
+        )
+        return Response.json({ inboxID }, { status: 202, headers: NO_STORE })
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/interrupt`,
+      allow: WRITE,
+      async handle(context) {
+        await bodyOf(context.request, true)
+        await write(context, "interrupt", false, (target) => deps.ports.interrupt(target.sessionID))
+        return new Response(null, { status: 204, headers: NO_STORE })
+      },
+    },
+  ]
+}