@huynle/hub 0.9.2 → 0.10.1

package/packages/sdk/src/app-front.ts

@@ -0,0 +1,524 @@
+// The app front (docs/app-front.md; contract docs/plans/2026-11-08-app-front-contracts.md) for an app's SERVER (a
+// BFF): connect (OAuth 2.1-style code + PKCE for a confidential client: the authorize URL, the callback checks, the
+// code exchange, refresh and revoke, and ConnectionTokens, a per-connection token keeper whose refresh is
+// single-flight), speech (transcribe, speak), conversation (the stream as an async iterator that resumes,
+// conversation on/off, utterances, interrupt; typed turns are hub.prompt), and the app's Decisions (the answerable
+// list, answer). Tokens never belong in a browser: the hub sends no CORS headers, and the app's page talks to the
+// app's own server only.
+//
+// The wire types mirror packages/protocol (app-front.ts and schema/app-front/v1.schema.json); the SDK imports nothing
+// outside its package.
+import { HubError, HubTransportError } from "./errors.ts"
+import { SseParser } from "./sse.ts"
+import type { Decision, DecisionAnswered, DecisionState } from "./types.ts"
+
+const AGENT = "/api/agent"
+
+interface Signal {
+  readonly signal?: AbortSignal
+}
+
+/** The part of fetch the connect helpers use. */
+type Fetch = (input: string, init: RequestInit) => Promise<Response>
+
+const sig = (options: Signal = {}) => (options.signal ? { signal: options.signal } : {})
+const seg = (value: string) => encodeURIComponent(value).replace(/%40/g, "@")
+
+// ---------- connect ----------
+
+/** POST /connect/token's answer. */
+export interface TokenResponse {
+  readonly access_token: string
+  readonly token_type: "Bearer"
+  /** Seconds (3600). */
+  readonly expires_in: number
+  readonly refresh_token: string
+  /** The granted scopes, space-separated. */
+  readonly scope: string
+  /** The app is `app:<connection_id>` on the hub, stable across refreshes and re-consent. */
+  readonly connection_id: string
+}
+
+/** A connection's current token pair, as an app keeps it (exactly one per connection). */
+export interface ConnectionPair {
+  readonly accessToken: string
+  readonly refreshToken: string
+  /** Epoch ms when the access token expires. */
+  readonly expiresAt: number
+  readonly scopes: readonly string[]
+  readonly connectionID: string
+}
+
+/** The pair a token response gives, from `now`. */
+export const pairOf = (token: TokenResponse, now = Date.now()): ConnectionPair => ({
+  accessToken: token.access_token,
+  refreshToken: token.refresh_token,
+  expiresAt: now + token.expires_in * 1000,
+  scopes: token.scope.split(" ").filter(Boolean),
+  connectionID: token.connection_id,
+})
+
+/**
+ * An OAuth error: from /connect/token or /connect/revoke ({error, error_description}, with the HTTP status), or a
+ * callback the app must refuse (status 0: invalid_state, invalid_issuer, the hub's redirect error), or not_connected.
+ */
+export class HubOAuthError extends Error {
+  override readonly name = "HubOAuthError"
+  constructor(
+    readonly status: number,
+    /** invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope, temporarily_unavailable, … */
+    readonly error: string,
+    readonly description?: string,
+    /** Seconds (Retry-After of a 429). */
+    readonly retryAfter?: number,
+  ) {
+    super(description ? `${error}: ${description}` : error)
+  }
+}
+
+/** A PKCE pair: keep `verifier` on the server for the exchange, send `challenge` (S256) in the authorize URL. */
+export async function pkcePair(): Promise<{ readonly verifier: string; readonly challenge: string }> {
+  const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)))
+  return { verifier, challenge: await pkceChallenge(verifier) }
+}
+
+/** base64url(SHA-256(verifier)). */
+export async function pkceChallenge(verifier: string): Promise<string> {
+  return base64url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))))
+}
+
+/** An unguessable `state` (or any random token), 32 base64url characters. */
+export const randomState = (): string => base64url(crypto.getRandomValues(new Uint8Array(24)))
+
+function base64url(bytes: Uint8Array): string {
+  let text = ""
+  for (const b of bytes) text += String.fromCharCode(b)
+  return btoa(text).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}
+
+export interface HubConnectOptions {
+  /** The hub's base URL (also the issuer: the callback's `iss` must be it). */
+  readonly url: string
+  readonly clientID: string
+  /** The client secret (hcs_…): server-side only. */
+  readonly clientSecret: string
+  /** The redirect URI exactly as registered. */
+  readonly redirectURI: string
+  readonly fetch?: Fetch
+}
+
+/** The app server's side of connect: the authorize URL, the callback, the code exchange, refresh and revoke. */
+export class HubConnect {
+  /** The hub's URL without a trailing slash (the issuer). */
+  readonly url: string
+  readonly #options: HubConnectOptions
+  readonly #fetch: Fetch
+
+  constructor(options: HubConnectOptions) {
+    this.url = options.url.replace(/\/+$/, "")
+    this.#options = options
+    this.#fetch = options.fetch ?? ((input, init) => fetch(input, init))
+  }
+
+  /** Where to send the user's browser (every parameter the hub requires; `challenge` from pkcePair). */
+  authorizeURL(input: { readonly scopes: readonly string[]; readonly state: string; readonly challenge: string }): string {
+    const query = new URLSearchParams({
+      response_type: "code",
+      client_id: this.#options.clientID,
+      redirect_uri: this.#options.redirectURI,
+      scope: input.scopes.join(" "),
+      state: input.state,
+      code_challenge: input.challenge,
+      code_challenge_method: "S256",
+    })
+    return `${this.url}/connect/authorize?${query}`
+  }
+
+  /**
+   * The callback's query, checked: `state` must be the one you sent and `iss` this hub (RFC 9207). Answers the code,
+   * or throws a HubOAuthError (status 0) with the hub's `error` (access_denied, invalid_scope, …) or the mismatch.
+   */
+  callback(query: URLSearchParams, expectedState: string): string {
+    if (query.get("state") !== expectedState) throw new HubOAuthError(0, "invalid_state", "state does not match")
+    const iss = query.get("iss")
+    if (iss === null || iss.replace(/\/+$/, "") !== this.url) throw new HubOAuthError(0, "invalid_issuer", "iss is not this hub")
+    const error = query.get("error")
+    if (error) throw new HubOAuthError(0, error, query.get("error_description") ?? undefined)
+    const code = query.get("code")
+    if (!code) throw new HubOAuthError(0, "invalid_request", "no code")
+    return code
+  }
+
+  /** code + verifier → the connection's first pair. */
+  exchange(code: string, verifier: string, options: Signal = {}): Promise<TokenResponse> {
+    return this.#token({ grant_type: "authorization_code", code, redirect_uri: this.#options.redirectURI, code_verifier: verifier }, options)
+  }
+
+  /**
+   * A new pair for a refresh token (the presented one is spent; `scope` may only narrow). Serialise refreshes per
+   * connection and store the new pair before using it: presenting an older refresh token revokes the connection
+   * (ConnectionTokens does both).
+   */
+  refresh(refreshToken: string, options: Signal & { readonly scope?: readonly string[] } = {}): Promise<TokenResponse> {
+    return this.#token({ grant_type: "refresh_token", refresh_token: refreshToken, ...(options.scope ? { scope: options.scope.join(" ") } : {}) }, options)
+  }
+
+  /** Ends the whole connection (either token works; RFC 7009: 200 also for an unknown token). */
+  async revoke(token: string, options: Signal = {}): Promise<void> {
+    await this.#post("/connect/revoke", { token }, options)
+  }
+
+  async #token(form: Record<string, string>, options: Signal): Promise<TokenResponse> {
+    return (await (await this.#post("/connect/token", form, options)).json()) as TokenResponse
+  }
+
+  async #post(pathname: string, form: Record<string, string>, options: Signal): Promise<Response> {
+    const basic = btoa(`${encodeURIComponent(this.#options.clientID)}:${encodeURIComponent(this.#options.clientSecret)}`)
+    let response: Response | undefined
+    try {
+      response = await this.#fetch(`${this.url}${pathname}`, {
+        method: "POST",
+        headers: { authorization: `Basic ${basic}`, "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+        body: new URLSearchParams(form).toString(),
+        redirect: "manual",
+        ...sig(options),
+      })
+    } catch (cause) {
+      if (options.signal?.aborted) throw cause
+      throw new HubTransportError("unreachable", `cannot reach ${this.url} (${cause instanceof Error ? cause.message : String(cause)})`, { cause })
+    }
+    if (response.ok) return response
+    const body = (await response.json().catch(() => undefined)) as { error?: unknown; error_description?: unknown } | undefined
+    if (typeof body?.error !== "string") throw new HubTransportError("http", `HTTP ${response.status} from ${this.url}${pathname}`, { status: response.status })
+    const retry = Number(response.headers.get("retry-after"))
+    throw new HubOAuthError(response.status, body.error, typeof body.error_description === "string" ? body.error_description : undefined, Number.isFinite(retry) && retry > 0 ? retry : undefined)
+  }
+}
+
+/** Where an app keeps each connection's one current pair (share one store between the app's instances). */
+export interface TokenStore {
+  get(key: string): ConnectionPair | undefined | Promise<ConnectionPair | undefined>
+  set(key: string, pair: ConnectionPair): void | Promise<void>
+  delete(key: string): void | Promise<void>
+}
+
+/** A TokenStore in memory (one process). */
+export class MemoryTokenStore implements TokenStore {
+  readonly #pairs = new Map<string, ConnectionPair>()
+  get(key: string): ConnectionPair | undefined {
+    return this.#pairs.get(key)
+  }
+  set(key: string, pair: ConnectionPair): void {
+    this.#pairs.set(key, pair)
+  }
+  delete(key: string): void {
+    this.#pairs.delete(key)
+  }
+}
+
+export interface ConnectionTokensOptions {
+  readonly connect: HubConnect
+  readonly store: TokenStore
+  /** Refresh this long before the access token expires (default 60 s). */
+  readonly skewMs?: number
+  readonly now?: () => number
+}
+
+/**
+ * Keeps each connection's pair (under your own key, e.g. your user's ID) and refreshes it single-flight: parallel
+ * callers of one key share one refresh, and the new pair is stored before anyone uses it. A connection the hub ended
+ * (refresh answers invalid_grant) is dropped from the store and the error thrown: the user connects again.
+ * This serialises within one process; an app running several instances needs one shared store AND a lock around the
+ * refresh in it (two instances refreshing with their own copy of the pair revoke the connection).
+ */
+export class ConnectionTokens {
+  readonly #options: ConnectionTokensOptions
+  readonly #inflight = new Map<string, Promise<ConnectionPair>>()
+
+  constructor(options: ConnectionTokensOptions) {
+    this.#options = options
+  }
+
+  #now(): number {
+    return this.#options.now?.() ?? Date.now()
+  }
+
+  /** Stores the first pair of a connection (after HubConnect.exchange), replacing any older one. */
+  async save(key: string, token: TokenResponse): Promise<ConnectionPair> {
+    const pair = pairOf(token, this.#now())
+    await this.#options.store.set(key, pair)
+    return pair
+  }
+
+  /** The current pair, or undefined when the key has no connection. */
+  async pair(key: string): Promise<ConnectionPair | undefined> {
+    return this.#options.store.get(key)
+  }
+
+  /** A usable access token: refreshed first (single-flight) when it expires within the skew. */
+  async access(key: string): Promise<string> {
+    const pair = await this.#options.store.get(key)
+    if (!pair) throw notConnected()
+    if (pair.expiresAt - (this.#options.skewMs ?? 60_000) > this.#now()) return pair.accessToken
+    return (await this.refresh(key, pair.accessToken)).accessToken
+  }
+
+  /**
+   * Refreshes now (e.g. after a 401 token_expired). Pass the access token that failed: when the stored pair already
+   * holds another one (someone refreshed meanwhile), that pair is answered without a new refresh.
+   */
+  refresh(key: string, failedAccess?: string): Promise<ConnectionPair> {
+    const running = this.#inflight.get(key)
+    if (running) return running
+    const run = (async () => {
+      const pair = await this.#options.store.get(key)
+      if (!pair) throw notConnected()
+      if (failedAccess !== undefined && pair.accessToken !== failedAccess) return pair
+      try {
+        const next = pairOf(await this.#options.connect.refresh(pair.refreshToken), this.#now())
+        await this.#options.store.set(key, next)
+        return next
+      } catch (cause) {
+        if (cause instanceof HubOAuthError && cause.error === "invalid_grant") await this.#options.store.delete(key)
+        throw cause
+      }
+    })().finally(() => this.#inflight.delete(key))
+    this.#inflight.set(key, run)
+    return run
+  }
+
+  /**
+   * Disconnects: revokes the connection on the hub, then forgets the pair. When the hub cannot be reached or refuses
+   * (other than invalid_token: already gone), the pair is kept and the error thrown, so the app can try again.
+   */
+  async revoke(key: string): Promise<void> {
+    const pair = await this.#options.store.get(key)
+    if (!pair) return
+    try {
+      await this.#options.connect.revoke(pair.refreshToken)
+    } catch (cause) {
+      if (!(cause instanceof HubOAuthError && (cause.error === "invalid_token" || cause.error === "invalid_grant"))) throw cause
+    }
+    await this.#options.store.delete(key)
+  }
+}
+
+const notConnected = () => new HubOAuthError(0, "not_connected", "no connection under this key")
+
+// ---------- speech, conversation, Decisions (HubClient with an app token) ----------
+
+export type AppSessionState = "idle" | "working" | "blocked" | "error"
+export type AppStreamEndReason = "token_expired" | "revoked" | "grant" | "gone" | "slow"
+
+/** The stream's frames (contract §5.2; closed allowlists on the wire). Their `text` is model output: untrusted. */
+export type AppStreamFrame =
+  | { readonly type: "ready"; readonly at: number; readonly sessionID: string; readonly status: AppSessionState; readonly conversation: { readonly on: boolean; readonly front?: boolean } }
+  | { readonly type: "delta"; readonly sessionID: string; readonly messageID?: string; readonly ordinal?: number; readonly text: string }
+  | { readonly type: "say"; readonly sessionID: string; readonly messageID: string; readonly ordinal: number; readonly seq?: number; readonly text: string }
+  | { readonly type: "heard"; readonly sessionID: string; readonly inboxID: string }
+  | { readonly type: "status"; readonly sessionID: string; readonly state: AppSessionState; readonly blockers: number; readonly since?: number }
+  | { readonly type: "conversation"; readonly sessionID: string; readonly on: boolean; readonly front?: boolean; readonly reason?: "front_failed" }
+  | { readonly type: "reset"; readonly at: number; readonly refresh: readonly ("log" | "status" | "conversation" | "decisions")[] }
+  | { readonly type: "end"; readonly at: number; readonly reason: AppStreamEndReason }
+
+/** One frame and its resume cursor (`id:`), when the hub sent one. */
+export interface AppStreamItem {
+  readonly frame: AppStreamFrame
+  readonly cursor?: string
+}
+
+export interface AppStreamOptions extends Signal {
+  /** Resume after this cursor (sent as Last-Event-ID). */
+  readonly cursor?: string
+  /**
+   * Reconnect with the last cursor when the stream drops without `end` (a draining hub, a network break) or ends
+   * with `slow` or `token_expired` (the latter helps only with a token function on the client that refreshes); those
+   * `end` frames are then not yielded. Default true. With false, every `end` is yielded and the iterator stops.
+   * `end` revoked, grant or gone always ends it (yielded last).
+   */
+  readonly resume?: boolean
+  /**
+   * Reconnects in a row without progress before giving up (default 5): then a `stream` HubTransportError ("gave up
+   * after N reconnects", the last failure as its cause). Progress is a frame other than `ready`.
+   */
+  readonly maxReconnects?: number
+  /**
+   * The first reconnect's wait (default 1000 ms); it doubles with every miss in a row, up to maxReconnectDelayMs, and
+   * each wait is jittered to between half and all of it. A 429's or 503's `retryAfter` is waited at least.
+   */
+  readonly reconnectDelayMs?: number
+  /** The longest backoff wait (default 30 000 ms). */
+  readonly maxReconnectDelayMs?: number
+}
+
+const RESUMABLE: ReadonlySet<string> = new Set<AppStreamEndReason>(["slow", "token_expired"])
+
+/** What the app-front verbs need of the client (HubClient). */
+export interface AppFrontTransport {
+  request(method: string, pathname: string, options?: { readonly query?: Readonly<Record<string, string | number | boolean | undefined>>; readonly body?: unknown; readonly raw?: { readonly body: BodyInit; readonly contentType: string }; readonly signal?: AbortSignal; readonly headers?: Readonly<Record<string, string>> }): Promise<Response>
+  call<T = unknown>(method: string, pathname: string, options?: { readonly query?: Readonly<Record<string, string | number | boolean | undefined>>; readonly body?: unknown; readonly signal?: AbortSignal }): Promise<T>
+}
+
+/** hub.speech (speech:use): the user's own speech provider; quotas per credential (429 rate_limited). */
+export interface AppSpeech {
+  /** Raw audio (typed `type`, else the Blob's type, else audio/webm) → its transcript. */
+  transcribe(audio: Blob | ArrayBuffer | Uint8Array, options?: Signal & { readonly type?: string }): Promise<{ text: string }>
+  /** Text (1–800 characters once speakable) → audio/mpeg, streamed as the provider streams. */
+  speak(text: string, options?: Signal): Promise<ReadableStream<Uint8Array>>
+}
+
+/** hub.conversation (conversation:read for the stream, conversation:write + a prompt grant for the writes). */
+export interface AppConversation {
+  /** GET …/stream as frames; resumes by default (AppStreamOptions). Throws the HubError of a refusal (404, 429, …). */
+  stream(addr: string, options?: AppStreamOptions): AsyncGenerator<AppStreamItem, void, undefined>
+  /** Conversation mode on/off; `front: true` asks for the voice front (the answer says whether one runs). */
+  set(addr: string, on: boolean, options?: Signal & { readonly front?: boolean }): Promise<{ on: boolean; agent?: string; front?: boolean }>
+  /** A spoken turn (1–4000 characters) to the session, or to its voice front while one is active. */
+  utterance(addr: string, text: string, options?: Signal): Promise<{ inboxID: string }>
+  /** Barge-in: stops the front's turn (or the session's, without a front). */
+  interrupt(addr: string, options?: Signal): Promise<void>
+}
+
+/** hub.appDecisions (decisions:answer): the confirm-tier Decisions of the app's own sessions. */
+export interface AppDecisions {
+  /** The Decisions this app may answer (`state: "open"` for the waiting ones), newest first. */
+  list(options?: Signal & { readonly state?: DecisionState }): Promise<{ decisions: Decision[] }>
+  /** Answers one with a once-off option or text; the first answer wins (410 gone after). */
+  answer(id: string, answer: Signal & { readonly option?: string; readonly text?: string }): Promise<DecisionAnswered>
+}
+
+export function speechApi(hub: AppFrontTransport): AppSpeech {
+  return {
+    async transcribe(audio, options = {}) {
+      const type = options.type ?? (audio instanceof Blob && audio.type ? audio.type : "audio/webm")
+      const response = await hub.request("POST", `${AGENT}/speech/transcribe`, { raw: { body: audio as BodyInit, contentType: type }, ...sig(options) })
+      return (await response.json()) as { text: string }
+    },
+    async speak(text, options = {}) {
+      const response = await hub.request("POST", `${AGENT}/speech/speak`, { body: { text }, ...sig(options) })
+      if (!response.body) throw new HubTransportError("bad_response", "the hub sent no audio")
+      return response.body
+    },
+  }
+}
+
+export function conversationApi(hub: AppFrontTransport): AppConversation {
+  const at = (addr: string, verb: string) => `${AGENT}/sessions/${seg(addr)}/${verb}`
+  return {
+    set: (addr, on, options = {}) => hub.call("POST", at(addr, "conversation"), { body: options.front === undefined ? { on } : { on, front: options.front }, ...sig(options) }),
+    utterance: (addr, text, options = {}) => hub.call("POST", at(addr, "utterance"), { body: { text }, ...sig(options) }),
+    interrupt: async (addr, options = {}) => {
+      await hub.request("POST", at(addr, "interrupt"), sig(options))
+    },
+    stream: (addr, options = {}) => streamFrames(hub, at(addr, "stream"), options),
+  }
+}
+
+export function appDecisionsApi(hub: AppFrontTransport): AppDecisions {
+  return {
+    list: (options = {}) => hub.call("GET", `${AGENT}/decisions`, { query: { answerable: 1, state: options.state }, ...sig(options) }),
+    answer: (id, answer) => {
+      const { signal: _signal, ...body } = answer
+      return hub.call("POST", `${AGENT}/decisions/${seg(id)}/answer`, { body, ...sig(answer) })
+    },
+  }
+}
+
+/**
+ * Whether a reconnect that failed with `cause` is worth another try: the network, the hub's 5xx (no envelope or
+ * offline/busy/internal) and 429. Never 401/403/404 or any other refusal.
+ */
+function retryable(cause: unknown): boolean {
+  if (cause instanceof HubError) return cause.status === 429 || cause.status >= 500
+  if (cause instanceof HubTransportError) return cause.kind === "unreachable" || cause.kind === "stream" || (cause.kind === "http" && (cause.status === undefined || cause.status === 429 || cause.status >= 500))
+  return false
+}
+
+const wait = (ms: number, signal?: AbortSignal) =>
+  new Promise<void>((resolve) => {
+    if (signal?.aborted) return resolve()
+    const done = () => {
+      clearTimeout(timer)
+      signal?.removeEventListener("abort", done)
+      resolve()
+    }
+    const timer = setTimeout(done, ms)
+    signal?.addEventListener("abort", done, { once: true })
+  })
+
+async function* streamFrames(hub: AppFrontTransport, pathname: string, options: AppStreamOptions): AsyncGenerator<AppStreamItem, void, undefined> {
+  const resume = options.resume ?? true
+  const maxReconnects = options.maxReconnects ?? 5
+  const base = options.reconnectDelayMs ?? 1000
+  const cap = options.maxReconnectDelayMs ?? 30_000
+  let cursor = options.cursor
+  /** Reconnects in a row without progress. */
+  let misses = 0
+  let lastFailure: unknown
+  let retryAfterMs = 0
+  for (let attempt = 0; ; attempt++) {
+    if (options.signal?.aborted) return
+    let response: Response | undefined
+    try {
+      response = await hub.request("GET", pathname, { headers: { accept: "text/event-stream", ...(cursor ? { "last-event-id": cursor } : {}) }, ...sig(options) })
+    } catch (cause) {
+      // The first connect reports every failure; a reconnect retries the network, 5xx and 429.
+      if (attempt === 0 || options.signal?.aborted || !retryable(cause)) throw cause
+      lastFailure = cause
+      retryAfterMs = cause instanceof HubError && cause.retryAfter !== undefined ? cause.retryAfter * 1000 : 0
+    }
+    if (response) {
+      retryAfterMs = 0
+      if (!response.body) throw new HubTransportError("bad_response", "the hub sent no stream")
+      const reader = response.body.getReader()
+      const stop = () => void reader.cancel().catch(() => {})
+      options.signal?.addEventListener("abort", stop, { once: true })
+      const parser = new SseParser()
+      const decoder = new TextDecoder()
+      lastFailure = undefined
+      try {
+        read: for (;;) {
+          let chunk: Awaited<ReturnType<typeof reader.read>>
+          try {
+            chunk = await reader.read()
+          } catch (cause) {
+            lastFailure = cause
+            break // a broken connection: resume
+          }
+          if (chunk.done || options.signal?.aborted) break
+          for (const event of parser.push(decoder.decode(chunk.value, { stream: true }))) {
+            if (event.id) cursor = event.id
+            if (event.event !== "message") continue
+            let frame: AppStreamFrame
+            try {
+              frame = JSON.parse(event.data) as AppStreamFrame
+            } catch {
+              continue
+            }
+            if (frame.type === "end") {
+              if (resume && RESUMABLE.has(frame.reason)) {
+                lastFailure = new HubTransportError("stream", `the stream ended (${frame.reason})`)
+                break read
+              }
+              yield { frame }
+              return
+            }
+            // `ready` alone is no progress: a hub that answers ready and drops must not loop forever.
+            if (frame.type !== "ready") misses = 0
+            yield cursor ? { frame, cursor } : { frame }
+            if (options.signal?.aborted) return
+          }
+        }
+      } finally {
+        options.signal?.removeEventListener("abort", stop)
+        stop()
+      }
+      if (options.signal?.aborted || !resume) return
+    }
+    if (++misses > maxReconnects) {
+      throw new HubTransportError("stream", `the conversation stream gave up after ${maxReconnects} reconnects${lastFailure instanceof Error ? ` (${lastFailure.message})` : ""}`, { cause: lastFailure })
+    }
+    const backoff = Math.min(cap, base * 2 ** (misses - 1))
+    await wait(Math.max(retryAfterMs, backoff * (0.5 + Math.random() * 0.5)), options.signal)
+  }
+}

package/packages/sdk/src/client.ts

@@ -5,6 +5,7 @@ import { sseEvents } from "./sse.ts"
 import { type Artifacts, artifactsApi } from "./artifacts.ts"
 import { type Teams, teamsApi } from "./teams.ts"
 import { type Concierge, conciergeApi } from "./concierge.ts"
+import { type AppConversation, type AppDecisions, type AppSpeech, appDecisionsApi, conversationApi, speechApi } from "./app-front.ts"
 import type {
   Approved,
   AppTokenView,
@@ -53,6 +54,8 @@ import type {
   Whoami,
   WebhookDelivery,
   WebhookView,
+  SubscribeInput,
+  SubscriptionView,
   ProfileAssignment,
   ProfileContent,
   ProfileCreated,
@@ -115,8 +118,11 @@ export type Fetch = (input: string, init: RequestInit) => Promise<Response>
 export interface HubClientOptions {
   /** The hub's base URL, e.g. https://hub.example.com. */
   readonly url: string
-  /** A session token (HUB_SESSION_TOKEN), an app token or a device token. */
-  readonly token: string
+  /**
+   * A session token (HUB_SESSION_TOKEN), an app token or a device token; or a function asked before every request
+   * (a connected app's access token that its server refreshes, e.g. `() => tokens.access(userID)`).
+   */
+  readonly token: string | (() => string | Promise<string>)
   /** Defaults to the global fetch. */
   readonly fetch?: Fetch
 }
@@ -360,7 +366,7 @@ export class HubClient {
   /** The URL as given (used in messages). */
   readonly url: string
   readonly #base: string
-  readonly #token: string
+  readonly #token: string | (() => string | Promise<string>)
   readonly #fetch: Fetch
 
   /** Launches (design §6.1): create, list, get, stop. */
@@ -437,6 +443,12 @@ export class HubClient {
   readonly teams: Teams = teamsApi(this)
   /** Concierge (CON-01): its watchlist (get, update, watch/unwatch, mute/unmute). */
   readonly concierge: Concierge = conciergeApi(this)
+  /** (App front) Speech with the user's provider (speech:use): transcribe, speak. */
+  readonly speech: AppSpeech = speechApi(this)
+  /** (App front) Conversation with one of the app's sessions: the stream, conversation on/off, utterance, interrupt. */
+  readonly conversation: AppConversation = conversationApi(this)
+  /** (App front) The confirm-tier Decisions of the app's own sessions (decisions:answer): list, answer. */
+  readonly appDecisions: AppDecisions = appDecisionsApi(this)
 
   constructor(options: HubClientOptions) {
     this.url = options.url
@@ -448,7 +460,8 @@ export class HubClient {
   /** Sends a request; resolves the response when OK, else throws HubError / HubTransportError. */
   async request(method: string, pathname: string, options: RequestOptions = {}): Promise<Response> {
     const target = `${pathname}${queryString(options.query)}`
-    const headers: Record<string, string> = { ...options.headers, authorization: `Bearer ${this.#token}`, accept: "application/json" }
+    const token = typeof this.#token === "string" ? this.#token : await this.#token()
+    const headers: Record<string, string> = { ...options.headers, authorization: `Bearer ${token}`, accept: "application/json" }
     if (options.body !== undefined) headers["content-type"] = "application/json"
     if (options.raw) headers["content-type"] = options.raw.contentType
     let response: Response
@@ -568,6 +581,26 @@ export class HubClient {
     return this.call("DELETE", `${AGENT}/webhooks/${segment(id)}`, signalOf(options))
   }
 
+  // Session subscriptions (decision 74qawely): a session hears its targets' events as batched hub messages.
+
+  /** POST /api/agent/subscriptions (a session token subscribes itself; users and apps name the subscriber). */
+  subscribe(input: SubscribeInput, options: CallOptions = {}): Promise<{ subscription: SubscriptionView }> {
+    return this.call("POST", `${AGENT}/subscriptions`, { body: input, ...signalOf(options) })
+  }
+
+  /** The caller's subscriptions; `session`: what that session subscribes to and what subscribes to it. */
+  subscriptions(options: CallOptions & { readonly session?: string } = {}): Promise<{ subscriptions: SubscriptionView[] }> {
+    return this.call("GET", `${AGENT}/subscriptions`, { query: { session: options.session }, ...signalOf(options) })
+  }
+
+  subscription(id: string, options: CallOptions = {}): Promise<{ subscription: SubscriptionView }> {
+    return this.call("GET", `${AGENT}/subscriptions/${segment(id)}`, signalOf(options))
+  }
+
+  unsubscribe(id: string, options: CallOptions = {}): Promise<void> {
+    return this.call("DELETE", `${AGENT}/subscriptions/${segment(id)}`, signalOf(options))
+  }
+
   // Organization (sessions:manage).
 
   setArchived(addr: string, archived: boolean, options: CallOptions = {}): Promise<Archived> {

package/packages/sdk/src/envelope.ts

@@ -81,6 +81,12 @@ function escapeBody(text: string): string {
     .join("\n")
 }
 
+/** Hub parties whose messages are notices: nothing reads a reply to them (session subscriptions). */
+export const NOTICE_ONLY_APPS: ReadonlySet<string> = new Set(["subscriptions"])
+
+/** Whether a sender's messages take no reply (a reply to one is refused). */
+export const noticeOnly = (from: Party): boolean => from.kind === "app" && NOTICE_ONLY_APPS.has(from.tokenID)
+
 /** The text a recipient session sees for a message. */
 export function renderEnvelope(input: EnvelopeInput): string {
   const { id, kind } = input
@@ -89,8 +95,9 @@ export function renderEnvelope(input: EnvelopeInput): string {
     kind === "reply" || kind === "decline" ? `to you · re ${sanitizeLabel(input.replyTo ?? "")}` : to.startsWith("@@") ? `to ${to} → you` : "to you"
   const header = `[hub] ${kind} from ${partyLabel(input.from)} ${target} · ${stamp(input.at)} · ${id}`
   const boundary = `----- ${id} -----`
-  const hint =
-    kind === "ask"
+  const hint = noticeOnly(input.from)
+    ? "↩ a notice: no reply needed (hub unsubscribe <sub_…> stops it)"
+    : kind === "ask"
       ? `↩ hub reply ${id} "…" · hub decline ${id} --why "…"${input.expiresAt === undefined ? "" : ` · expires ${stamp(input.expiresAt)}`}`
       : `↩ hub reply ${id} "…"`
   return [header, boundary, escapeBody(input.text), boundary, hint].join("\n")

package/packages/sdk/src/errors.ts

@@ -21,6 +21,7 @@ export type ErrorCode =
   | "paused"
   | "rate_limited"
   | "internal"
+  | "upstream_failed"
   | "offline"
   | "busy"
   | (string & {})

package/packages/sdk/src/index.ts

@@ -2,6 +2,7 @@
 // errors (HubError, HubTransportError), the answer types, the SSE parser of the watch stream, and the pure
 // envelope renderer/sanitiser and address parser shared with the hub, launches, and webhook verification.
 export * from "./address.ts"
+export * from "./app-front.ts"
 export * from "./artifacts.ts"
 export * from "./artifact-jobs.ts"
 export * from "./team-intake.ts"