@huynle/hub 0.7.4 → 0.8.0

package/src/central/workspaces/sidechats-routes.ts

@@ -0,0 +1,410 @@
+// Side-chat routes on /api/agent (HWA-13; contract: Workspaces in docs/plans/2026-10-30-hub-workspaces-artifacts-
+// contracts.md and its HWA-06 clarification; records and snapshot rules: ./sidechats.ts):
+//
+//   POST /workspaces/:id/side-chats              {sourceSessionID, sources?, bindingID?, harness?, model?, agent?}
+//                                                Idempotency-Key → 201 {sideChat}               manage + S + M (+ launch)
+//   GET  /workspaces/:id/side-chats?limit&cursor → {items, cursor?} (summaries, no quoted text)  read + S
+//   GET  /workspaces/:id/side-chats/:chat        → {sideChat} (with the snapshot)                read + S + M
+//   GET  /side-chats/:chat                       → {sideChat} (for panes, which know only the ID) read + S + M
+//   POST /workspaces/:id/side-chats/:chat/refresh {expectedRevision} → {sideChat, delivery}      manage + S + M
+//   POST /workspaces/:id/side-chats/:chat/send   {text, confirmed: true} → 201 {sideChatID, sent} users only
+//
+// Who: users (their own records; another user's is not_found). Apps by workspaces:read/manage plus sessions:read
+// (S) and, where transcript text is copied or shown, messages:read (M). Session tokens are refused (membership
+// grants nothing). Nothing here adds authority: the side chat acts through the EXISTING routes as the caller —
+//   - the source transcript through GET /sessions/:addr/log (its tenancy and scope),
+//   - the side-chat session through POST /launches (scope sessions:launch, the launch grant on the repo, the kill
+//     switch, the launch caps and audit: an app needs all of them, exactly as when it launches directly),
+//   - context refreshes to the side-chat session and "Send to main" through POST /msg: a plain msg (never urgent)
+//     through the normal message path. It never interrupts a running turn (a busy session gets it queued, after
+//     the turn); the first msg to an idle session right after the hub's primer may be delivered as "steer", sharing
+//     the primer's model call (delivery quirk hzmcqwpj).
+//
+// Placement is the workspace's host repo binding (bindingID, or the only one): a `checkout` launch of that repo
+// on that machine, placement `require`, `end.when: never`. Nothing derives from the source session's machine or
+// directory, so the side chat may run on another machine than its source. An unreachable machine shows as a
+// launch that waits (status `launching` with the launch's state and reason); no binding is 422 unsupported
+// {feature: "sideChatHost"}. The new session is a root session: its native parentID/rootID and the workspace's
+// supervision are untouched; the link to the source is the side-chat record only.
+//
+// "Send to main" is users only (the console confirms it; `confirmed: true` is required): apps that may message
+// sessions already use POST /msg themselves.
+import { WORKSPACE_SCOPES } from "../../protocol"
+import { agentAllows } from "../agent/actor"
+import { AGENT_ERROR_STATUS, AgentError, type AgentErrorCode } from "../agent/errors"
+import type { AgentEvents, EventInput } from "../agent/events"
+import { idempotencyKeyOf, RouteIdempotency } from "../agent/idempotency"
+import { launchedBy } from "../agent/launch-routes"
+import type { Launch } from "../agent/launch-store"
+import { TEXT_MAX } from "../agent/messages"
+import type { AgentContext, AgentRoute } from "../agent/routes"
+import type { Clock } from "../backend/types"
+import type { Store } from "../store"
+import { WORKSPACE_ROUTE_IDEMPOTENCY } from "./routes"
+import {
+  renderContext,
+  sideChatChangedEvent,
+  sideChatCreatedEvent,
+  sideChatID,
+  SideChatStore,
+  SNAPSHOT_SCAN_ROWS,
+  snapshotOf,
+  SOURCE_ID_MAX,
+  type StoredSideChat,
+} from "./sidechats"
+import type { WorkspaceStore } from "./store"
+import { AGENT_JSON_BODY_MAX, boundedText } from "../agent/body"
+
+const PREFIX = "/api/agent/workspaces"
+const NO_STORE = { "cache-control": "no-store" }
+const [READ_SCOPE, MANAGE_SCOPE] = WORKSPACE_SCOPES
+const READ = { scope: READ_SCOPE } as const
+const MANAGE = { scope: MANAGE_SCOPE } as const
+/** Users only. */
+const USERS = {} as const
+const SOURCE_ID = new RegExp(`^[!-~]{1,${SOURCE_ID_MAX}}$`)
+const STRING_FIELD = /^[!-~]{1,200}$/
+
+/** The existing routes a side chat goes through, as the caller (routePorts finds them in the route table). */
+export interface SideChatPorts {
+  readonly transcript?: AgentRoute
+  readonly launch?: AgentRoute
+  readonly message?: AgentRoute
+}
+
+/** The delegate routes in a route table (GET /sessions/:addr/log, POST /launches, POST /msg). */
+export function routePorts(routes: readonly AgentRoute[]): SideChatPorts {
+  const find = (method: string, path: string) => routes.find((r) => r.method === method && r.path === path)
+  const transcript = find("GET", "/api/agent/sessions/:addr/log")
+  const launch = find("POST", "/api/agent/launches")
+  const message = find("POST", "/api/agent/msg")
+  return { ...(transcript ? { transcript } : {}), ...(launch ? { launch } : {}), ...(message ? { message } : {}) }
+}
+
+/** What the routes read of the launch engine (tenant-scoped view of the side chat's own launch). */
+export interface SideChatLaunches {
+  view(userID: string, id: string): Promise<Launch | undefined>
+}
+
+export interface SideChatRoutesDeps {
+  readonly workspaces: Pick<WorkspaceStore, "require" | "bindings" | "state">
+  /** The records; one over the workspaces' StateStore when absent. */
+  readonly sideChats?: SideChatStore
+  readonly ports: SideChatPorts
+  /** The side chats' launches (status and the session they started); without it a side chat links never. */
+  readonly launches?: SideChatLaunches
+  /** When the hub last saw the source session change (its catalog), for the stale marker; unknown when absent. */
+  readonly sourceUpdatedAt?: (userID: string, sessionID: string) => number | undefined
+  readonly events?: Pick<AgentEvents, "append">
+  readonly audit?: Pick<Store, "audit">
+  readonly idempotency?: RouteIdempotency
+  readonly now?: Clock
+}
+
+const ok = (body: unknown, status = 200) => Response.json(body, { status, headers: NO_STORE })
+
+async function bodyOf(request: Request): Promise<Record<string, unknown>> {
+  const text = await boundedText(request, AGENT_JSON_BODY_MAX)
+  const raw = JSON.parse(text === "" ? "{}" : text) as unknown
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new AgentError("invalid", "Body must be a JSON object")
+  return raw as Record<string, unknown>
+}
+
+function only(body: Record<string, unknown>, allowed: readonly string[]): void {
+  for (const key of Object.keys(body)) if (!allowed.includes(key)) throw new AgentError("invalid", `unknown field ${/^[A-Za-z0-9_-]{1,40}$/.test(key) ? key : "(unprintable)"}`)
+}
+
+function expected(value: unknown): number {
+  if (value === undefined || value === null) throw new AgentError("invalid", "expectedRevision is required: the revision you read", { hint: "Read the side chat and send its revision" })
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new AgentError("invalid", "expectedRevision must be the revision you read")
+  return value
+}
+
+function optionalString(body: Record<string, unknown>, key: string): string | undefined {
+  const value = body[key]
+  if (value === undefined) return undefined
+  if (typeof value !== "string" || !STRING_FIELD.test(value)) throw new AgentError("invalid", `${key} must be 1–200 visible characters`)
+  return value
+}
+
+/** Apps: scopes beyond the route's own (the board's and members' rule, plus messages:read for copied text). */
+function appNeeds(context: AgentContext, scopes: readonly string[]): void {
+  const { actor } = context
+  if (actor.kind !== "app") return
+  const missing = scopes.filter((s) => !actor.scopes.includes(s))
+  if (missing.length) throw new AgentError("forbidden", `Side chats also need scope ${missing.join(" and ")}`)
+}
+const SHOWS_SESSIONS = ["sessions:read"]
+const COPIES_TEXT = ["sessions:read", "messages:read"]
+
+/** Calls an existing /api/agent route as the caller; its refusals and errors are the side chat's. */
+async function delegate(route: AgentRoute | undefined, feature: string, context: AgentContext, call: { readonly params: Record<string, string>; readonly search?: string; readonly body?: unknown }): Promise<Record<string, unknown>> {
+  if (!route) throw new AgentError("unsupported", `This hub cannot ${feature} for side chats`, { extra: { feature } })
+  if (!agentAllows(route.allow, context.actor)) throw new AgentError("forbidden", `This credential cannot use ${route.method} ${route.path} (needed to ${feature})`)
+  const path = route.path.replace(/:([a-z]+)/g, (_, key: string) => encodeURIComponent(call.params[key] ?? ""))
+  const url = new URL(`${path}${call.search ?? ""}`, context.url)
+  const request = new Request(url, {
+    method: route.method,
+    headers: { "content-type": "application/json" },
+    ...(call.body !== undefined ? { body: JSON.stringify(call.body) } : {}),
+    signal: context.request.signal,
+  })
+  const response = await route.handle({ ...context, request, url, params: call.params })
+  const body = (await response.json().catch(() => undefined)) as Record<string, unknown> | undefined
+  if (response.ok && body) return body
+  const { code, message, hint, ...extra } = (body?.error ?? {}) as Record<string, unknown>
+  const known = typeof code === "string" && code in AGENT_ERROR_STATUS
+  throw new AgentError(known ? (code as AgentErrorCode) : "internal", typeof message === "string" ? message : `Could not ${feature}`, { ...(typeof hint === "string" ? { hint } : {}), extra })
+}
+
+interface SourceInput {
+  readonly ids: string[]
+}
+
+function sourcesOf(value: unknown, max: number): SourceInput {
+  if (value === undefined) return { ids: [] }
+  if (!Array.isArray(value)) throw new AgentError("invalid", "sources must be a list of {kind, id}")
+  if (value.length > max) throw new AgentError("invalid", `A side chat quotes at most ${max} sources`, { extra: { limit: max } })
+  const ids: string[] = []
+  let artifact = false
+  for (const source of value) {
+    if (typeof source !== "object" || source === null || Array.isArray(source)) throw new AgentError("invalid", "sources must be a list of {kind, id}")
+    const { kind, id, ...rest } = source as Record<string, unknown>
+    if (Object.keys(rest).length) throw new AgentError("invalid", "A source is {kind, id}")
+    if (kind !== "message" && kind !== "artifact_revision") throw new AgentError("invalid", "A source kind is message or artifact_revision")
+    if (typeof id !== "string" || !SOURCE_ID.test(id)) throw new AgentError("invalid", `A source id is 1–${SOURCE_ID_MAX} visible characters`)
+    if (kind === "artifact_revision") artifact = true
+    if (ids.includes(id)) throw new AgentError("invalid", `Source ${id} is listed twice`)
+    ids.push(id)
+  }
+  if (artifact) throw new AgentError("unsupported", "Side chats quote session messages only in this version; artifact revisions are not supported yet", { extra: { feature: "sideChatArtifactSources" } })
+  return { ids }
+}
+
+type Status = "launching" | "ready" | "failed" | "unknown"
+
+export function sideChatRoutes(deps: SideChatRoutesDeps): AgentRoute[] {
+  const { workspaces, ports } = deps
+  const now = deps.now ?? Date.now
+  const sideChats = deps.sideChats ?? new SideChatStore({ state: workspaces.state, now })
+  const idempotency = deps.idempotency ?? new RouteIdempotency({ state: workspaces.state, collection: WORKSPACE_ROUTE_IDEMPOTENCY, now })
+  const limits = sideChats.limits
+
+  const report = (cause: unknown) => console.error(`[hub] side-chat event failed: ${cause instanceof Error ? cause.message : String(cause)}`)
+  async function changed(context: AgentContext, action: string, target: string, ...events: EventInput[]): Promise<void> {
+    await deps.audit?.audit({ actor: context.user.id, action, target, detail: context.actor.kind })
+    for (const event of events) await deps.events?.append(context.user.id, event).catch(report)
+  }
+
+  /** The source's newest transcript rows, read as the caller; the session ID the address resolved to. */
+  async function transcript(context: AgentContext, source: string): Promise<{ sessionID: string; rows: unknown[] }> {
+    const body = await delegate(ports.transcript, "read the source transcript", context, { params: { addr: source }, search: `?n=${SNAPSHOT_SCAN_ROWS}` })
+    return { sessionID: typeof body.sessionID === "string" ? body.sessionID : source, rows: Array.isArray(body.rows) ? body.rows : [] }
+  }
+
+  const send = (context: AgentContext, to: string, text: string) => delegate(ports.message, "send a message", context, { params: {}, body: { to, text } })
+
+  /** Links the side-chat session once its launch reports it; the record and its launch (when still known). */
+  async function resolved(context: AgentContext, chat: StoredSideChat): Promise<{ chat: StoredSideChat; launch?: Launch }> {
+    const launch = await deps.launches?.view(context.user.id, chat.launchID)
+    if (chat.sessionID || !launch?.sessionID) return { chat, ...(launch ? { launch } : {}) }
+    const linked = await sideChats.link(context.user.id, chat.id, launch.sessionID)
+    if (linked) await changed(context, "workspace.sidechat.link", chat.id, sideChatChangedEvent(linked, "sidechat_linked"))
+    return { chat: linked ?? (await sideChats.get(context.user.id, chat.id)) ?? chat, launch }
+  }
+
+  function view(context: AgentContext, chat: StoredSideChat, launch: Launch | undefined, full: boolean) {
+    const status: Status = chat.sessionID ? "ready" : launch ? (launch.state === "ended" ? "failed" : "launching") : deps.launches ? "failed" : "unknown"
+    const updatedAt = deps.sourceUpdatedAt?.(context.user.id, chat.sourceSessionID)
+    const { snapshot, ...rest } = chat
+    const summary = { generation: snapshot.generation, takenAt: snapshot.takenAt, mode: snapshot.mode, count: snapshot.items.length, bytes: snapshot.bytes, omitted: snapshot.omitted, ...(snapshot.sourceNewestAt !== undefined ? { sourceNewestAt: snapshot.sourceNewestAt } : {}) }
+    return {
+      ...rest,
+      snapshot: full ? snapshot : summary,
+      status,
+      ...(launch
+        ? { launch: { id: launch.id, state: launch.state, ...(launch.outcome ? { outcome: launch.outcome } : {}), ...(context.actor.kind === "user" || launch.by === launchedBy(context.actor) ? { reason: launch.reason } : {}) } }
+        : {}),
+      ...(updatedAt !== undefined ? { sourceUpdatedAt: updatedAt, stale: updatedAt > snapshot.takenAt } : {}),
+    }
+  }
+
+  async function active(context: AgentContext, workspaceID: string) {
+    const workspace = await workspaces.require(context.user.id, workspaceID)
+    if (workspace.state === "archived") throw new AgentError("invalid", `Workspace ${workspaceID} is archived`, { hint: "Restore it first" })
+    return workspace
+  }
+
+  async function bindingFor(userID: string, workspaceID: string, bindingID: string | undefined) {
+    const bindings = await workspaces.bindings(userID, workspaceID)
+    if (bindingID !== undefined) {
+      const binding = bindings.find((b) => b.id === bindingID)
+      if (!binding) throw new AgentError("not_found", `No binding ${bindingID} in workspace ${workspaceID}`)
+      return binding
+    }
+    if (bindings.length === 0) {
+      throw new AgentError("unsupported", "No machine can host a side chat for this workspace: it has no host repository binding", { hint: "Bind a repository on a machine first (POST /workspaces/:id/bindings)", extra: { feature: "sideChatHost" } })
+    }
+    if (bindings.length > 1) throw new AgentError("invalid", `bindingID is required: the workspace has ${bindings.length} host repository bindings`)
+    return bindings[0]!
+  }
+
+  async function createSideChat(context: AgentContext, workspaceID: string, body: Record<string, unknown>, key: string | undefined) {
+    const { user } = context
+    const source = typeof body.sourceSessionID === "string" && SOURCE_ID.test(body.sourceSessionID) ? body.sourceSessionID : undefined
+    if (!source) throw new AgentError("invalid", "sourceSessionID must be the source session's ID or address")
+    const { ids } = sourcesOf(body.sources, limits.sideChatContextItems)
+    const harness = optionalString(body, "harness") ?? "opencode"
+    const model = optionalString(body, "model")
+    const agent = optionalString(body, "agent")
+    await active(context, workspaceID)
+    const binding = await bindingFor(user.id, workspaceID, optionalString(body, "bindingID"))
+    const id = sideChatID(key === undefined ? undefined : `${user.id}\n${workspaceID}\n${key}`)
+    await sideChats.reserve(user.id, workspaceID, id)
+    try {
+      const read = await transcript(context, source)
+      const info = { sideChatID: id, workspaceID, sourceSessionID: read.sessionID }
+      const snapshot = snapshotOf(read.rows, { ids, limits }, info, now())
+      const launched = await delegate(ports.launch, "launch the side-chat session", context, {
+        params: {},
+        body: {
+          key: `sidechat:${id}`,
+          harness,
+          ...(model ? { model } : {}),
+          ...(agent ? { agent } : {}),
+          workspace: { repo: binding.repo, mode: "checkout" },
+          placement: { machine: binding.machineID, mode: "require" },
+          prompt: renderContext(info, snapshot),
+          labels: { "hub.sidechat": id, "hub.workspace": workspaceID },
+          end: { when: "never", cleanup: "keep" },
+        },
+      })
+      const launch = launched.launch as { id: string; sessionID?: string }
+      const { sideChat, created } = await sideChats.insert(user.id, {
+        id,
+        workspaceID,
+        sourceSessionID: read.sessionID,
+        launchID: launch.id,
+        ...(launch.sessionID ? { sessionID: launch.sessionID } : {}),
+        by: launchedBy(context.actor),
+        bindingID: binding.id,
+        machineID: binding.machineID,
+        harness,
+        snapshot,
+      })
+      if (created) await changed(context, "workspace.sidechat.create", sideChat.id, sideChatCreatedEvent(sideChat))
+      const current = await resolved(context, sideChat)
+      return { status: created ? 201 : 200, body: { sideChat: view(context, current.chat, current.launch, true) } }
+    } catch (cause) {
+      await sideChats.release(user.id, workspaceID, id).catch(report)
+      throw cause
+    }
+  }
+
+  const ws = (context: AgentContext) => context.params.id!
+
+  async function readOne(context: AgentContext, workspaceID: string | undefined) {
+    appNeeds(context, COPIES_TEXT)
+    if (workspaceID !== undefined) await workspaces.require(context.user.id, workspaceID)
+    const chat = await sideChats.require(context.user.id, workspaceID, context.params.chat!)
+    const current = await resolved(context, chat)
+    return ok({ sideChat: view(context, current.chat, current.launch, true) })
+  }
+
+  return [
+    {
+      method: "POST",
+      path: `${PREFIX}/:id/side-chats`,
+      allow: MANAGE,
+      async handle(context) {
+        appNeeds(context, COPIES_TEXT)
+        const body = await bodyOf(context.request)
+        only(body, ["sourceSessionID", "sources", "bindingID", "harness", "model", "agent"])
+        const key = idempotencyKeyOf(context.request)
+        return idempotency.run(context.user.id, `POST ${context.url.pathname}`, key ?? null, body, () => createSideChat(context, ws(context), body, key))
+      },
+    },
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/side-chats`,
+      allow: READ,
+      async handle(context) {
+        appNeeds(context, SHOWS_SESSIONS)
+        await workspaces.require(context.user.id, ws(context))
+        const raw = context.url.searchParams.get("limit")
+        const limit = raw === null ? undefined : /^[0-9]{1,6}$/.test(raw) ? Number(raw) : Number.NaN
+        const cursor = context.url.searchParams.get("cursor") || undefined
+        const page = await sideChats.list(context.user.id, ws(context), { ...(limit !== undefined ? { limit } : {}), ...(cursor ? { cursor } : {}) })
+        const items = []
+        for (const chat of page.items) {
+          const current = await resolved(context, chat)
+          items.push(view(context, current.chat, current.launch, false))
+        }
+        return ok({ items, ...(page.cursor ? { cursor: page.cursor } : {}) })
+      },
+    },
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/side-chats/:chat`,
+      allow: READ,
+      handle: (context) => readOne(context, ws(context)),
+    },
+    {
+      method: "GET",
+      path: "/api/agent/side-chats/:chat",
+      allow: READ,
+      handle: (context) => readOne(context, undefined),
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/:id/side-chats/:chat/refresh`,
+      allow: MANAGE,
+      async handle(context) {
+        appNeeds(context, COPIES_TEXT)
+        const body = await bodyOf(context.request)
+        only(body, ["expectedRevision"])
+        const revision = expected(body.expectedRevision)
+        const { user } = context
+        await active(context, ws(context))
+        const chat = await sideChats.require(user.id, ws(context), context.params.chat!)
+        if (chat.revision !== revision) throw new AgentError("conflict", "The side chat changed since you read it", { extra: { currentRevision: chat.revision } })
+        const read = await transcript(context, chat.sourceSessionID)
+        const info = { sideChatID: chat.id, workspaceID: chat.workspaceID, sourceSessionID: chat.sourceSessionID }
+        const ids = chat.snapshot.mode === "selected" ? chat.sources.map((s) => s.id) : []
+        const snapshot = snapshotOf(read.rows, { ids, limits, previous: chat.snapshot }, info, now())
+        const refreshed = await sideChats.refresh(user.id, ws(context), chat.id, revision, snapshot)
+        await changed(context, "workspace.sidechat.refresh", chat.id, sideChatChangedEvent(refreshed, "sidechat_refreshed"))
+        const current = await resolved(context, refreshed)
+        let delivery: Record<string, unknown> = { status: "not_started" }
+        if (current.chat.sessionID) {
+          try {
+            const sent = await send(context, current.chat.sessionID, renderContext(info, snapshot))
+            delivery = { status: "sent", ...sent }
+          } catch (cause) {
+            if (!(cause instanceof AgentError)) throw cause
+            delivery = { status: "failed", code: cause.code, message: cause.message }
+          }
+        }
+        return ok({ sideChat: view(context, current.chat, current.launch, true), delivery })
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/:id/side-chats/:chat/send`,
+      allow: USERS,
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        only(body, ["text", "confirmed"])
+        if (body.confirmed !== true) throw new AgentError("invalid", "Send to main needs confirmed: true (the user confirms the message)")
+        const header = `[From side chat ${context.params.chat!}]\n`
+        if (typeof body.text !== "string" || !body.text.trim()) throw new AgentError("invalid", "text must be a non-empty string")
+        if (header.length + body.text.length > TEXT_MAX) throw new AgentError("invalid", `text is longer than ${TEXT_MAX - header.length} characters`)
+        await workspaces.require(context.user.id, ws(context))
+        const chat = await sideChats.require(context.user.id, ws(context), context.params.chat!)
+        const sent = await send(context, chat.sourceSessionID, `[From side chat ${chat.id}]\n${body.text}`)
+        await deps.audit?.audit({ actor: context.user.id, action: "workspace.sidechat.send", target: chat.id, detail: context.actor.kind })
+        return ok({ sideChatID: chat.id, sent }, 201)
+      },
+    },
+  ]
+}