@tetherto/mdk-ui-agent 0.0.0 → 0.12.1

package/src/core/markdown.ts

@@ -0,0 +1,52 @@
+/**
+ * Two text repairs applied before an answer is rendered as markdown.
+ *
+ * Both exist because the model decides its own output format and nothing in the
+ * charter constrains it: the panel has to read whatever comes back.
+ */
+
+/** Opening fence of a whole-answer wrapper: ```markdown / ```md, nothing else on the line. */
+const MARKDOWN_FENCE_OPEN = /^`{3,}\s*(?:markdown|md)\s*$/i
+/** Any closing fence line. */
+const FENCE_CLOSE = /^`{3,}\s*$/
+
+/**
+ * Unwraps an answer the model wrapped entirely in a ```markdown fence.
+ *
+ * A common quirk: asked for a formatted answer, the model returns the formatted
+ * answer inside a fence, and the panel renders the whole reply as one code block
+ * — table syntax, bullets and all. Only the whole-answer case is unwrapped, and
+ * only when the fence actually closes at the end: an ordinary code fence, an
+ * unclosed fence mid-stream, and a fence with prose after it are all left alone.
+ */
+export function unwrapWholeAnswerFence(text: string): string {
+  const lines = text.trim().split('\n')
+  const first = lines[0]
+  if (lines.length < 2 || first === undefined || !MARKDOWN_FENCE_OPEN.test(first)) return text
+
+  // Paired with the last fence line, which is a whole-answer wrapper only if it is
+  // also the final line: an unclosed fence, or one with prose after it, is not.
+  const last = lines[lines.length - 1]
+  if (last === undefined || !FENCE_CLOSE.test(last)) return text
+
+  return lines.slice(1, -1).join('\n')
+}
+
+/**
+ * Cuts `text` to roughly `max` characters, on the last paragraph or line break
+ * before the limit.
+ *
+ * Slicing markdown at an arbitrary character can split a fence or a table row and
+ * make the preview render as something the answer never said, so the cut lands on
+ * a block boundary where there is one within reach.
+ */
+export function clipToBoundary(text: string, max: number): string {
+  if (text.length <= max) return text
+
+  const head = text.slice(0, max)
+  const paragraph = head.lastIndexOf('\n\n')
+  const line = head.lastIndexOf('\n')
+  const cut = paragraph > max / 2 ? paragraph : line > max / 2 ? line : max
+
+  return head.slice(0, cut).trimEnd()
+}

package/src/core/prose.ts

@@ -0,0 +1,78 @@
+/**
+ * Detects a tool call that leaked into the answer.
+ *
+ * The agent loop is prompt-based, not native function calling: the model is told
+ * to reply with only `{"tool": "<name>", "args": { ... }}`, and
+ * `backend/core/agent/src/loop.js` decides prose-vs-tool-call from the first
+ * non-whitespace character being `{`. A model that wraps its JSON in a ```json
+ * fence therefore leads with a backtick, is classified as prose, and the raw
+ * tool call is streamed to the operator as if it were the answer. Measured at
+ * roughly one read in eight against `gemma3:4b` — common enough to handle.
+ *
+ * Rendering that verbatim is the single most confusing failure mode in the
+ * stack, so it is detected and labelled instead.
+ */
+
+const FENCE = /^```[a-z]*\s*|\n?```$/gi
+
+/**
+ * The first balanced JSON object in `text`, string-aware so a brace inside a
+ * string literal does not close it. Mirrors `extractJsonObject` in the producer.
+ */
+function extractJsonObject(text: string): string | null {
+  const start = text.indexOf('{')
+  if (start === -1) return null
+
+  let depth = 0
+  let inString = false
+  let escaped = false
+
+  for (let index = start; index < text.length; index += 1) {
+    const char = text[index]
+    if (inString) {
+      if (escaped) escaped = false
+      else if (char === '\\') escaped = true
+      else if (char === '"') inString = false
+      continue
+    }
+    if (char === '"') {
+      inString = true
+      continue
+    }
+    if (char === '{') depth += 1
+    else if (char === '}') {
+      depth -= 1
+      if (depth === 0) return text.slice(start, index + 1)
+    }
+  }
+  return null
+}
+
+export type LeakedToolCall = { tool: string, args: Record<string, unknown> }
+
+/**
+ * Returns the leaked call when `text` is nothing but a tool call, else null.
+ *
+ * Deliberately strict: the JSON must be the whole message once code fences are
+ * stripped. A genuine answer that merely quotes some JSON keeps rendering as
+ * prose.
+ */
+export function parseLeakedToolCall(text: string): LeakedToolCall | null {
+  const stripped = text.trim().replace(FENCE, '').trim()
+  if (!stripped.startsWith('{')) return null
+
+  const raw = extractJsonObject(stripped)
+  if (raw === null || raw !== stripped) return null
+
+  try {
+    const parsed = JSON.parse(raw) as { tool?: unknown, args?: unknown }
+    if (typeof parsed.tool !== 'string') return null
+    const args
+      = typeof parsed.args === 'object' && parsed.args !== null
+        ? (parsed.args as Record<string, unknown>)
+        : {}
+    return { tool: parsed.tool, args }
+  } catch {
+    return null
+  }
+}

package/src/core/small-talk.ts

@@ -0,0 +1,45 @@
+/**
+ * Was an operator message conversation rather than a question about the fleet?
+ *
+ * This exists for one caller: whether an answer is worth marking as having used no tools. The
+ * marker is there to catch an answer that should have consulted the fleet and did not — and
+ * against a greeting, a thank-you, or "what can you do", calling nothing was the right move, so
+ * every one of those was carrying a warning about a failure that had not happened.
+ *
+ * Deliberately asymmetric. All three gates below must agree before a message counts as small
+ * talk, and any fleet word vetoes it outright, because the two mistakes are not equal: missing a
+ * greeting costs one redundant marker, while reading a fleet question as small talk hides exactly
+ * the warning the marker exists to give.
+ */
+
+/** Openers where the greeting *is* the message — nothing is being asked of the fleet. */
+const CONVERSATIONAL = [
+  /^(?:hi|hey|hello|yo|hiya|howdy|greetings|good (?:morning|afternoon|evening|day))\b/,
+  /^(?:how are you|how's it going|what's up|sup)\b/,
+  /^(?:thanks|thank you|thx|ty|cheers|nice|great|cool|awesome|perfect|got it|ok|okay|sure|sorry|never mind|nvm)\b/,
+  /^(?:bye|goodbye|see you|see ya|later)\b/,
+  /^(?:who are you|what are you|what can you do|what do you do|can you help|help)\b/,
+]
+
+/**
+ * Words that make a message about the fleet however it opens, so "hey, list the miners" is not
+ * small talk. Kept to unambiguous terms: "up" and "down" are fleet state but also "what's up".
+ */
+const FLEET_TERMS
+  = /\b(?:device|devices|miner|miners|asic|asics|rig|rigs|worker|workers|site|container|containers|pool|pools|sensor|sensors|powermeter|powermeters|power meter|hashrate|hash rate|temperature|telemetry|fleet|rank|reboot|restart|offline|online|status|list|show|count)\b/
+
+/** Past this, a message is doing more than saying hello, whatever it opened with. */
+const MAX_WORDS = 6
+
+export function isSmallTalk(text: string): boolean {
+  const normalized = text
+    .toLowerCase()
+    .replaceAll('’', '\'') // a typographic apostrophe still spells "what's"
+    .trim()
+
+  if (normalized.length === 0) return false
+  if (FLEET_TERMS.test(normalized)) return false
+  if (normalized.split(/\s+/).length > MAX_WORDS) return false
+
+  return CONVERSATIONAL.some((pattern) => pattern.test(normalized))
+}

package/src/core/sse.ts

@@ -0,0 +1,269 @@
+/**
+ * SSE reading for the agent message route.
+ *
+ * `EventSource` is unusable here: the message is a POST body and `EventSource`
+ * is GET-only. So this is `fetch` + a body-stream reader, which is also what the
+ * producer's own docs prescribe.
+ *
+ * The gateway writes `event: <type>\ndata: <json>\n\n` and nothing else — no
+ * `id:`, no `retry:`, and no heartbeat comment frames. The `event:` line is
+ * redundant (`data.type` carries the same value) so only `data:` is parsed. The
+ * rest of the parser is nonetheless written against the spec rather than against
+ * that one producer: CRLF line endings and multi-line `data:` are both legal, and
+ * a proxy that rewrites line endings would otherwise silently end every turn as a
+ * truncation.
+ */
+
+import type { WireEvent } from './events'
+import { EVENT, isTerminal, isWireEvent } from './events'
+
+/** A blank line ends a frame; either line ending is legal (spec §7). */
+const FRAME_SEPARATOR = /\r?\n\r?\n/
+const LINE_SEPARATOR = /\r?\n/
+const DATA_PREFIX = 'data:'
+
+/** Synthesized locally, never sent by the gateway. See `readAgentStream`. */
+export const ERR_STREAM_TRUNCATED = 'ERR_AGENT_STREAM_TRUNCATED'
+/** Synthesized locally: the socket stayed open but nothing arrived. See `readAgentStream`. */
+export const ERR_STREAM_IDLE = 'ERR_AGENT_STREAM_IDLE'
+
+/**
+ * How long a turn may say nothing between events before the connection is
+ * assumed lost.
+ *
+ * The gateway sends no heartbeats, so silence is the only symptom of a wedged
+ * agent, a half-closed proxy or a laptop resumed from sleep. Once events are
+ * flowing, 30s of nothing is already far outside what a working turn does: the
+ * producer emits a frame per token.
+ */
+export const STREAM_IDLE_TIMEOUT_MS = 30_000
+
+/**
+ * The same limit before the first event, which is a different wait entirely.
+ *
+ * Nothing is emitted until the producer's first model call returns a routing
+ * decision, and a local model may think for a long time before it answers a
+ * single character: measured against a 4B thinking model on this hardware, the
+ * first event arrived at 61s. Held to the producer's own per-call budget
+ * (`REQUEST_TIMEOUT_MS`, 120s in backend/core/agent/src/constants.js) so a turn
+ * the server is still legitimately working on is never abandoned here first —
+ * whatever the model does, the server gives up before this does and says why.
+ */
+export const FIRST_EVENT_IDLE_TIMEOUT_MS = 120_000
+
+/**
+ * The same limit while an approval is outstanding, where silence is legitimate:
+ * the producer is waiting on a human, and only auto-rejects after its own
+ * `agent.approvalTimeoutMs`. Five minutes is that default plus room to spare, so
+ * the stream is never given up on before the server itself would have resumed it.
+ */
+export const APPROVAL_IDLE_TIMEOUT_MS = 300_000
+
+/** Thrown out of `readFrames` when the deadline expires; converted to an event above. */
+export class StreamIdleError extends Error {
+  constructor() {
+    super(ERR_STREAM_IDLE)
+    this.name = 'StreamIdleError'
+  }
+}
+
+export type ReadFramesOptions = {
+  /**
+   * Milliseconds of silence tolerated before the next read is given up on, read
+   * fresh before every read so the caller can widen it mid-stream. `0` disables
+   * the deadline.
+   */
+  idleTimeoutMs?: () => number
+}
+
+/**
+ * Pulls the `data:` payload out of one frame.
+ *
+ * A frame may carry several `data:` lines, which the spec joins with newlines;
+ * anything else (`event:`, `id:`, a `:` comment) is ignored. Returns null for a
+ * frame with no data at all.
+ */
+export function parseFrame(frame: string): unknown {
+  const data = frame
+    .split(LINE_SEPARATOR)
+    .filter((line) => line.startsWith(DATA_PREFIX))
+    .map((line) => line.slice(DATA_PREFIX.length).trim())
+
+  if (data.length === 0) return null
+
+  try {
+    return JSON.parse(data.join('\n'))
+  } catch {
+    // A frame we cannot parse is indistinguishable from an event type we do not
+    // know about, and invariant 5 says ignore those rather than throw.
+    return null
+  }
+}
+
+const IDLE = Symbol('idle')
+
+/**
+ * One `read()`, given up on after `timeoutMs` of silence.
+ *
+ * The abandoned read is left attached to a rejection handler on purpose: the
+ * caller's `finally` cancels the reader straight after, and an unobserved
+ * rejection from a read parked on a socket we just cancelled would surface as a
+ * global unhandled rejection.
+ */
+async function readWithDeadline(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  timeoutMs: number,
+): Promise<ReadableStreamReadResult<Uint8Array> | typeof IDLE> {
+  const read = reader.read()
+  if (timeoutMs <= 0) return read
+  read.catch(() => {})
+
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    return await Promise.race([
+      read,
+      new Promise<typeof IDLE>((resolve) => {
+        timer = setTimeout(() => resolve(IDLE), timeoutMs)
+      }),
+    ])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Yields each decoded `data:` payload, in order, as frames arrive.
+ *
+ * The abort signal is handled here rather than left to `fetch`. Aborting a fetch
+ * whose headers have already arrived is only specified to error the body stream
+ * — cancelling the reader is what actually unblocks a `read()` that is parked
+ * waiting for the next token, which is where an abort almost always lands.
+ */
+export async function* readFrames(
+  stream: ReadableStream<Uint8Array>,
+  signal?: AbortSignal,
+  options: ReadFramesOptions = {},
+): AsyncGenerator<unknown> {
+  const reader = stream.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+
+  const cancel = () => {
+    reader.cancel().catch(() => {
+      // Already closed or errored; there is nothing left to release.
+    })
+  }
+
+  if (signal?.aborted) cancel()
+  signal?.addEventListener('abort', cancel, { once: true })
+
+  const drain = function* (): Generator<unknown> {
+    for (;;) {
+      const match = FRAME_SEPARATOR.exec(buffer)
+      if (!match) return
+      const frame = buffer.slice(0, match.index)
+      buffer = buffer.slice(match.index + match[0].length)
+      const payload = parseFrame(frame)
+      if (payload !== null) yield payload
+    }
+  }
+
+  try {
+    for (;;) {
+      const outcome = await readWithDeadline(reader, options.idleTimeoutMs?.() ?? 0)
+      if (outcome === IDLE) throw new StreamIdleError()
+
+      const { value, done } = outcome
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+      yield* drain()
+    }
+
+    // Flush whatever the decoder was holding from an incomplete multibyte
+    // sequence, then the final frame if it arrived without its blank line.
+    buffer += decoder.decode()
+    yield* drain()
+    const tail = parseFrame(buffer)
+    if (tail !== null) yield tail
+  } finally {
+    signal?.removeEventListener('abort', cancel)
+    cancel()
+  }
+}
+
+export type ReadAgentStreamOptions = {
+  /** Silence tolerated between events. Defaults to {@link STREAM_IDLE_TIMEOUT_MS}; `0` disables it. */
+  idleTimeoutMs?: number
+  /** Silence tolerated while an approval is outstanding. Defaults to {@link APPROVAL_IDLE_TIMEOUT_MS}. */
+  approvalIdleTimeoutMs?: number
+  /** Silence tolerated before the first event. Defaults to {@link FIRST_EVENT_IDLE_TIMEOUT_MS}. */
+  firstEventIdleTimeoutMs?: number
+}
+
+/**
+ * Turns a live response into the guaranteed-well-formed event sequence the rest
+ * of the package is written against. Four contract obligations live here:
+ *
+ * 1. Unknown or malformed events are dropped, not thrown on (invariant 5).
+ * 2. Nothing is emitted after the terminal event (invariant 1), so a
+ *    misbehaving producer cannot reopen a finished turn.
+ * 3. Every stream ends with exactly one terminal event. The gateway's stream
+ *    route calls `rep.hijack()`, so a failure after the headers are sent just
+ *    closes the socket — no `error` frame, no `done`. Left alone that reads as a
+ *    turn that never finishes, so an EOF with no terminal event is converted
+ *    into one here. An abort is excluded: the operator stopping the turn is not
+ *    a failure, and nothing should be reported back to them as one.
+ * 4. A socket that stays open but stops delivering ends the same way. Without
+ *    that, a consumer awaiting the next event parks forever and the panel stays
+ *    busy until the page is reloaded. The deadline is per phase, because how much
+ *    silence is normal is not constant across a turn: wide before the first event
+ *    (the model is still thinking), wide again while an approval is outstanding
+ *    (the producer is waiting on a human), narrow in between.
+ */
+export async function* readAgentStream(
+  stream: ReadableStream<Uint8Array>,
+  signal?: AbortSignal,
+  options: ReadAgentStreamOptions = {},
+): AsyncGenerator<WireEvent> {
+  const streamingTimeout = options.idleTimeoutMs ?? STREAM_IDLE_TIMEOUT_MS
+  const approvalTimeout = options.approvalIdleTimeoutMs ?? APPROVAL_IDLE_TIMEOUT_MS
+  const firstEventTimeout = options.firstEventIdleTimeoutMs ?? FIRST_EVENT_IDLE_TIMEOUT_MS
+
+  let terminalSeen = false
+  let awaitingApproval = false
+  let seenAnyEvent = false
+  let idle = false
+
+  const idleTimeoutMs = () => {
+    if (streamingTimeout <= 0) return 0
+    if (awaitingApproval) return approvalTimeout
+    if (!seenAnyEvent) return firstEventTimeout
+    return streamingTimeout
+  }
+
+  try {
+    for await (const payload of readFrames(stream, signal, { idleTimeoutMs })) {
+      if (!isWireEvent(payload)) continue
+      if (terminalSeen) continue
+      seenAnyEvent = true
+      // An approval pauses the producer; its result is what releases it.
+      if (payload.type === EVENT.PENDING_APPROVAL) awaitingApproval = true
+      if (payload.type === EVENT.TOOL_RESULT) awaitingApproval = false
+      if (isTerminal(payload)) terminalSeen = true
+      yield payload
+    }
+  } catch (error) {
+    if (!(error instanceof StreamIdleError)) throw error
+    idle = true
+  }
+
+  if (!terminalSeen && !signal?.aborted) {
+    yield {
+      type: EVENT.ERROR,
+      error: idle ? ERR_STREAM_IDLE : ERR_STREAM_TRUNCATED,
+      turnId: '',
+      seq: Number.MAX_SAFE_INTEGER,
+      ts: 0,
+    }
+  }
+}

package/src/core/tool-label.ts

@@ -0,0 +1,33 @@
+/**
+ * Human labels for tool chips.
+ *
+ * Tools are supplied by whichever MCP server the operator points the agent at,
+ * so no name can be hardcoded here — `summarize_site` and `get_device` happen to
+ * come from the reference site tools, but another deployment ships another set
+ * entirely. Callers pass a `toolLabels` map for the names they know; everything
+ * else falls back to a readable form of the identifier.
+ */
+
+export type ToolLabels = Record<string, string>
+
+/** `summarize_site` -> `Summarize site`. */
+export function humanizeToolName(name: string): string {
+  const words = name
+    .replaceAll(/[_-]+/g, ' ')
+    .replaceAll(/([a-z\d])([A-Z])/g, '$1 $2')
+    .trim()
+  if (words.length === 0) return name
+  return words.charAt(0).toUpperCase() + words.slice(1).toLowerCase()
+}
+
+export function toolLabel(name: string, labels?: ToolLabels): string {
+  return labels?.[name] ?? humanizeToolName(name)
+}
+
+/** `420` -> `0.4s`, so a chip reads `Site status · 0.4s`. */
+export function formatDuration(durationMs: number | undefined): string | null {
+  if (durationMs === undefined || !Number.isFinite(durationMs)) return null
+  const seconds = durationMs / 1000
+  // Tenths stay readable up to a minute; past that the decimal is noise.
+  return seconds < 60 ? `${seconds.toFixed(1)}s` : `${Math.round(seconds)}s`
+}

package/src/core/transport.ts

@@ -0,0 +1,208 @@
+/**
+ * The four agent routes, as declared in `backend/apps/agent/mdk-plugin.json`.
+ *
+ *   POST   /agent/sessions                              -> { sessionId }
+ *   POST   /agent/sessions/:id/messages                 -> text/event-stream
+ *   POST   /agent/sessions/:id/approvals/:approvalId    -> { approvalId, approved }
+ *   DELETE /agent/sessions/:id                          -> { sessionId, deleted }
+ *
+ * Note the approval route is session-scoped. `backend/core/agent/docs/CONTRACT.md`
+ * documents it as `/agent/turns/{turnId}/approvals/{approvalId}`; that is stale —
+ * `turnId` appears in no URL.
+ *
+ * The gateway sends no CORS headers, and the stream route calls `rep.hijack()` so
+ * no CORS hook could decorate it even if one existed. Callers must be same-origin
+ * (served from `staticRootPath`) or proxied (`/agent` in the dev server).
+ */
+
+import type { WireEvent } from './events'
+import type { ReadAgentStreamOptions } from './sse'
+import { readAgentStream } from './sse'
+
+export const AGENT_ROUTE_PREFIX = '/agent'
+
+/** The `ERR_*` codes these routes can return. */
+export const AGENT_ERROR = {
+  SESSION_NOT_FOUND: 'ERR_AGENT_SESSION_NOT_FOUND',
+  TURN_ACTIVE: 'ERR_AGENT_TURN_ACTIVE',
+  TEXT_REQUIRED: 'ERR_AGENT_MESSAGE_TEXT_REQUIRED',
+  UNAVAILABLE: 'ERR_AGENT_UNAVAILABLE',
+  APPROVAL_NOT_FOUND: 'ERR_AGENT_APPROVAL_NOT_FOUND',
+} as const
+
+export type AgentErrorCode = (typeof AGENT_ERROR)[keyof typeof AGENT_ERROR]
+
+export type TokenSource = () => string | null | undefined | Promise<string | null | undefined>
+
+export type AgentTransportOptions = {
+  /** Gateway origin. Empty string means relative URLs — i.e. same-origin or proxied. */
+  baseUrl?: string
+  getToken?: TokenSource
+  /** Injected in tests; defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch
+}
+
+/** A gateway error carrying the `ERR_*` code the UI branches on. */
+export class AgentApiError extends Error {
+  readonly status: number
+  readonly code: string
+
+  constructor(status: number, code: string, message?: string) {
+    super(message ?? code)
+    this.name = 'AgentApiError'
+    this.status = status
+    this.code = code
+  }
+
+  is(code: AgentErrorCode): boolean {
+    return this.code === code
+  }
+}
+
+// Trimmed with a scan rather than /\/+$/: the regex backtracks quadratically on a long run
+// of trailing slashes, which CodeQL flags as a polynomial ReDoS (js/polynomial-redos).
+function stripTrailingSlashes(value: string): string {
+  let end = value.length
+  while (end > 0 && value[end - 1] === '/') end--
+  return value.slice(0, end)
+}
+
+function joinUrl(baseUrl: string | undefined, path: string): string {
+  if (!baseUrl) return path
+  return `${stripTrailingSlashes(baseUrl)}${path}`
+}
+
+async function buildHeaders(
+  options: AgentTransportOptions,
+  extra?: Record<string, string>,
+): Promise<Headers> {
+  const headers = new Headers(extra)
+  const token = await options.getToken?.()
+  if (token) headers.set('authorization', `Bearer ${token}`)
+  return headers
+}
+
+/**
+ * Both error body shapes, reduced to a code.
+ *
+ * Normal routes answer `{ statusCode, error, message }`; the streaming route
+ * answers `{ statusCode, message }` with no `error` key at all. Either way the
+ * `ERR_*` code is in `message`. `ERR_AGENT_UNAVAILABLE` additionally has its
+ * reason concatenated in (`"ERR_AGENT_UNAVAILABLE: config.agent missing"`), so
+ * the code is only the part before the colon.
+ */
+async function toApiError(response: Response): Promise<AgentApiError> {
+  let message = response.statusText
+  try {
+    const body = (await response.json()) as { message?: string }
+    if (typeof body?.message === 'string') message = body.message
+  } catch {
+    // Non-JSON body (or none). The status alone still identifies the failure.
+  }
+  const code = message.split(':')[0]?.trim() || `HTTP_${response.status}`
+  return new AgentApiError(response.status, code, message)
+}
+
+async function requestJson<T>(
+  path: string,
+  init: RequestInit,
+  options: AgentTransportOptions,
+): Promise<T> {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch
+  const response = await fetchImpl(joinUrl(options.baseUrl, path), init)
+  if (!response.ok) throw await toApiError(response)
+  return (await response.json()) as T
+}
+
+/** Identity comes from the token, so the request body is ignored by the gateway. */
+export async function createSession(options: AgentTransportOptions = {}): Promise<string> {
+  const headers = await buildHeaders(options, { 'content-type': 'application/json' })
+  const body = await requestJson<{ sessionId: string }>(
+    `${AGENT_ROUTE_PREFIX}/sessions`,
+    { method: 'POST', headers, body: '{}' },
+    options,
+  )
+  return body.sessionId
+}
+
+export async function deleteSession(
+  sessionId: string,
+  options: AgentTransportOptions = {},
+): Promise<void> {
+  const headers = await buildHeaders(options)
+  await requestJson(
+    `${AGENT_ROUTE_PREFIX}/sessions/${encodeURIComponent(sessionId)}`,
+    { method: 'DELETE', headers },
+    options,
+  )
+}
+
+/**
+ * Answers a paused approval. The decision travels on its own request while the
+ * message stream stays open — the stream resumes on its own once this lands.
+ *
+ * The gateway tests `approved === true`, so anything else is a rejection. It is
+ * passed through as a real boolean rather than coerced, to keep that explicit.
+ *
+ * A decision that arrives after the approval timed out, or a second decision for
+ * the same approval, is a 404 `ERR_AGENT_APPROVAL_NOT_FOUND` — the two are
+ * deliberately indistinguishable. Callers should treat it as "already settled",
+ * not as a failure.
+ */
+export async function decideApproval(
+  sessionId: string,
+  approvalId: string,
+  approved: boolean,
+  options: AgentTransportOptions = {},
+): Promise<void> {
+  const headers = await buildHeaders(options, { 'content-type': 'application/json' })
+  await requestJson(
+    `${AGENT_ROUTE_PREFIX}/sessions/${encodeURIComponent(sessionId)}`
+    + `/approvals/${encodeURIComponent(approvalId)}`,
+    { method: 'POST', headers, body: JSON.stringify({ approved }) },
+    options,
+  )
+}
+
+export type StreamTurnOptions = AgentTransportOptions & ReadAgentStreamOptions & {
+  signal?: AbortSignal
+}
+
+/**
+ * Sends one message and yields its events until the turn ends.
+ *
+ * Only one turn may be in flight per session; a second send while this is
+ * running — including while it is paused on an approval, since a paused turn
+ * still holds the session busy — throws `ERR_AGENT_TURN_ACTIVE`.
+ */
+export async function* streamTurn(
+  sessionId: string,
+  text: string,
+  options: StreamTurnOptions = {},
+): AsyncGenerator<WireEvent> {
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch
+  const headers = await buildHeaders(options, {
+    'content-type': 'application/json',
+    'accept': 'text/event-stream',
+  })
+
+  const response = await fetchImpl(
+    joinUrl(options.baseUrl, `${AGENT_ROUTE_PREFIX}/sessions/${encodeURIComponent(sessionId)}/messages`),
+    { method: 'POST', headers, body: JSON.stringify({ text }), signal: options.signal },
+  )
+
+  // 404 / 409 / 400 are all raised before the SSE headers go out, so they arrive
+  // as an ordinary JSON body rather than as an event on the stream.
+  if (!response.ok) throw await toApiError(response)
+  if (!response.body) throw new AgentApiError(response.status, 'ERR_AGENT_STREAM_EMPTY')
+
+  yield* readAgentStream(response.body, options.signal, {
+    ...(options.idleTimeoutMs === undefined ? {} : { idleTimeoutMs: options.idleTimeoutMs }),
+    ...(options.approvalIdleTimeoutMs === undefined
+      ? {}
+      : { approvalIdleTimeoutMs: options.approvalIdleTimeoutMs }),
+    ...(options.firstEventIdleTimeoutMs === undefined
+      ? {}
+      : { firstEventIdleTimeoutMs: options.firstEventIdleTimeoutMs }),
+  })
+}