@huynle/hub 0.9.2 → 0.10.0

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"

package/packages/sdk/src/types.ts

@@ -368,7 +368,8 @@ export interface Decision {
   readonly at: number
   readonly expiresAt: number
   readonly escalatedAt?: number
-  readonly answer?: { readonly option?: string; readonly text?: string; readonly answeredBy: "user" | "timeout"; readonly at: number; readonly deviceID?: string }
+  /** answeredBy "app": an app answered it (`app`: its party `app:<id>`, `appLabel`: its label then). */
+  readonly answer?: { readonly option?: string; readonly text?: string; readonly answeredBy: "user" | "timeout" | "app"; readonly at: number; readonly deviceID?: string; readonly app?: string; readonly appLabel?: string }
   /** Why it closed without an answer (state closed). */
   readonly closed?: { readonly at: number; readonly reason: string }
 }
@@ -593,6 +594,43 @@ export interface WebhookDelivery {
   readonly last?: { readonly at: number; readonly status?: number; readonly error?: string }
 }
 
+/** A session subscription's target (decision 74qawely). */
+export type SubscriptionTarget =
+  | { readonly kind: "session"; readonly sessionID: string; readonly addr: string }
+  | { readonly kind: "role"; readonly addr: string }
+  | { readonly kind: "team"; readonly addr: string }
+  | { readonly kind: "children" }
+
+/** A session subscription as the hub shows it: the subscriber hears its targets' events as batched hub messages. */
+export interface SubscriptionView {
+  readonly id: string
+  readonly subscriber: string
+  readonly targets: readonly SubscriptionTarget[]
+  readonly types: readonly string[]
+  readonly delivery: "queue" | "steer" | "silent"
+  readonly batchMs: number
+  readonly maxPerHour: number
+  readonly expiresAt: number
+  readonly createdAt: number
+  /** user, ses:<id> or app:<token id>. */
+  readonly by: string
+  readonly note?: string
+  readonly pending: number
+  readonly stats: { readonly delivered: number; readonly dropped: number; readonly suppressed: number; readonly lastAt?: number }
+}
+
+/** POST /api/agent/subscriptions: batch and expires in seconds; subscriber required for users and apps. */
+export interface SubscribeInput {
+  readonly subscriber?: string
+  readonly to: string | readonly string[]
+  readonly types?: readonly string[]
+  readonly delivery?: "queue" | "steer" | "silent"
+  readonly batch?: number
+  readonly maxPerHour?: number
+  readonly expires?: number
+  readonly note?: string
+}
+
 /** A launch as the hub reports it (the spec with its defaults filled in). */
 export interface LaunchView {
   readonly id: string

package/packages/spoke-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-spoke-sdk",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "private": true,
   "description": "Harness-neutral spoke building blocks: hub connection, enrollment, tokens, idempotent deliver, prompt references, HarnessSpoke (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/spoke-sdk/src/delivery.ts

@@ -52,11 +52,17 @@ class Bounded<V> {
  * Who put each inbox item into a session, from OpenCode's session.inbox.enqueued events and the spoke's own
  * deliveries: a user item is the user's (typed, or sent from the phone), a synthetic item with hub metadata is
  * the hub's; anything else (OpenCode's own notes, compaction) has no origin.
+ *
+ * (Session findability) A user item with hub metadata but no messageID is a prompt the hub carried (the console's
+ * turn or steer, a Voice utterance, a launch's prompt): it stays the user's (it is a user turn: the hop chain starts
+ * over), and is also marked `carried`, so the hub never counts it again as a prompt typed in the terminal.
  */
 export class InboxOrigins {
   private readonly origins: Bounded<InboxOrigin>
+  private readonly carriedIDs: Bounded<true>
   constructor(max = 1000) {
     this.origins = new Bounded(max)
+    this.carriedIDs = new Bounded(max)
   }
 
   observe(event: { readonly type: string; readonly data?: unknown }): void {
@@ -67,7 +73,17 @@ export class InboxOrigins {
     const metadata = record(record(item.payload).metadata)
     // A hub message (hub metadata with its messageID) is never the user's, whatever item type OpenCode gives it.
     if (metadata.source === PROMPT_SOURCE && typeof metadata.messageID === "string" && (item.type === "synthetic" || item.type === "user")) this.origins.set(data.inboxID, "hub")
-    else if (item.type === "user") this.origins.set(data.inboxID, "user")
+    else if (item.type === "user") {
+      this.origins.set(data.inboxID, "user")
+      if (metadata.source === PROMPT_SOURCE) this.carriedIDs.set(data.inboxID, true)
+    }
+  }
+
+  /** Whether the item is a user prompt the hub carried; forgets it (read once, like take). */
+  carried(inboxID: string): boolean {
+    const carried = this.carriedIDs.get(inboxID) === true
+    this.carriedIDs.delete(inboxID)
+    return carried
   }
 
   /** Marks an inbox item the spoke delivered for the hub. */

package/packages/spoke-sdk/src/harness-spoke.ts

@@ -44,9 +44,10 @@ export type OpHandlers = { readonly [O in HandledOp]?: OpHandler<O> }
 export type DeliverRequest = Extract<ServerRequest, { op: "deliver" }>
 /**
  * Features that change how an op is served rather than adding one; each needs the op it modifies, except
- * "turnEvents" (the spoke reports every turn's end as the harness confirms it), which is about events, not an op.
+ * "turnEvents" (the spoke reports every turn's end as the harness confirms it) and "inboxCarried" (its user inbox
+ * items the hub carried are marked `carried: true`), which are about events, not an op.
  */
-export type ModifierFeature = "permissionMessage" | "launch" | "hubPrompt" | "turnEvents"
+export type ModifierFeature = "permissionMessage" | "launch" | "hubPrompt" | "turnEvents" | "inboxCarried"
 
 export interface HarnessSpokeOptions extends Omit<HarnessHelloOptions, "ops" | "features"> {
   readonly server: string
@@ -65,7 +66,7 @@ export interface HarnessSpokeOptions extends Omit<HarnessHelloOptions, "ops" | "
   readonly onState?: ConnectionOptions["onState"]
 }
 
-const MODIFIER_NEEDS: Record<ModifierFeature, string | null> = { permissionMessage: "permission", launch: "create", hubPrompt: "deliver", turnEvents: null }
+const MODIFIER_NEEDS: Record<ModifierFeature, string | null> = { permissionMessage: "permission", launch: "create", hubPrompt: "deliver", turnEvents: null, inboxCarried: null }
 const ALWAYS: readonly SpokeFeature[] = ["sessionTokens", "actTokens"]
 const CORE: readonly string[] = CORE_OPS
 

package/packages/voice-client/README.md

@@ -0,0 +1,146 @@
+# @huynle/hub-voice-client
+
+Hub's hands-free voice loop as a package: an always-on microphone with on-device speech detection (Silero VAD),
+optional end-of-turn detection (Smart Turn v3), speculative per-segment transcription, endpointing, voice commands
+("stop", "pause listening"), sentence-by-sentence speech of the agent's replies with barge-in, and progress cues
+(earcons and short phrases). The Hub console's Voice mode is built on it; other web apps can embed the same loop.
+
+Internal workspace package (`private`, not published on its own). The console imports it from source
+(`packages/voice-client/src`); an app that does not build it from source uses the standalone build (below).
+
+## The transport
+
+Everything the loop sends to or hears from its session goes through a `VoiceTransport`, the interface frozen by the
+app-front contract (`docs/plans/2026-11-08-app-front-contracts.md` §7, `packages/protocol/src/app-front.ts`):
+
+```ts
+interface VoiceTransport {
+  conversation(on: boolean, options?: { front?: boolean }): Promise<{ on: boolean; front?: boolean }>
+  utterance(text: string): Promise<{ inboxID: string }>
+  interrupt(): Promise<void>
+  transcribe(audio: Blob, options?: { signal?: AbortSignal }): Promise<{ text: string }>
+  speak(text: string, options?: { signal?: AbortSignal }): Promise<ReadableStream<Uint8Array>> // audio/mpeg
+  events(listener: (event: VoiceEvent) => void): () => void // say | heard | conversation | status | reset
+}
+```
+
+- **The package never holds a Hub token and never calls the Hub.** The console's transport
+  (`web/src/voice/console-transport.ts`) uses its cookie routes and SSE; an app's transport calls **its own server**,
+  which keeps the app's Hub credentials and proxies to `/api/agent/speech/*` and `/api/agent/sessions/:addr/*`
+  (contract §4, §5). **`appTransport({base})`** is that app transport, ready made (below).
+- `events` delivers the session's `say`, `heard` and `conversation` events (and, from an app stream, `status` and
+  `reset`: a `reset` drops the replies still to speak). `VoiceEvents` is a small multicast source for transports that
+  push events in.
+- A transport may accept more than the contract (`VoiceClientTransport`: a `keepalive` for the page-hide
+  `conversation(false)`, request `headers` for the recording plug-in, `agent` in the answer); every plain
+  `VoiceTransport` is accepted.
+
+### `appTransport`: the app's own server
+
+```ts
+import { appTransport } from "@huynle/hub-voice-client"
+const transport = appTransport({ base: `/hub/voice/sessions/${sessionID}`, onEnd: (reason) => console.log(reason) })
+```
+
+It calls six routes under `base` on the page's origin, with the page's own cookie (`credentials: "same-origin"`, or
+your `fetch`): `POST {base}/conversation {on, front?}`, `POST {base}/utterance {text}`, `POST {base}/interrupt`,
+`POST {base}/transcribe` (the raw audio, its type as `Content-Type`), `POST {base}/speak {text}` (audio/mpeg back) and
+`GET {base}/stream` (the hub's app stream, relayed as SSE). Your server proxies them to the hub with the user's token
+(the reference: `examples/app-front-bff`). `events` opens one relayed stream for all listeners, maps `say`, `heard`,
+`conversation`, `status` and `reset`, and resumes with `Last-Event-ID` after a drop or `end` `slow`/`token_expired`,
+with exponential backoff (jittered, capped; `reconnectDelayMs`, `maxReconnectDelayMs`). A stream that closes without
+progress counts as a failure; `end` `revoked`/`grant`/`gone`, a 4xx from your server, or `maxReconnects` (5)
+failures in a row stop it (`onEnd(reason)`, `unavailable` for the last). Refusals throw
+`AppTransportError {status, code?, retryAfter?}` (the hub's envelope passed through).
+
+### Your own transport
+
+```ts
+import { Conversation, VoiceEvents, sharedPlayer, unlockAudio } from "@huynle/hub-voice-client"
+
+const events = new VoiceEvents() // fed from your server's relay of the session's stream
+const transport = {
+  conversation: (on, o) => post(`/my/voice/conversation`, { on, ...o }),
+  utterance: (text) => post(`/my/voice/utterance`, { text }),
+  interrupt: () => post(`/my/voice/interrupt`, {}),
+  transcribe: async (audio) => (await fetch("/my/voice/transcribe", { method: "POST", body: audio })).json(),
+  speak: async (text, o) => (await fetch("/my/voice/speak", { method: "POST", body: JSON.stringify({ text }), signal: o?.signal })).body!,
+  events: (listener) => events.subscribe(listener),
+}
+unlockAudio() // inside the tap that starts Voice
+const conversation = new Conversation({ sessionID, transport, player: sharedPlayer(), ui, options: { front: () => true } })
+await conversation.start()
+```
+
+`ui` (`ConversationUI`) receives the loop's state, mic level, user and agent bubbles, notes and the turn timing.
+`VoiceController` and `VoiceNotifier` (one Voice session at a time, the "Voice mode on" notification) are optional
+app-level helpers.
+
+## Plug-ins (all optional)
+
+| Option | What | The console's |
+| --- | --- | --- |
+| `speakable` | rewrites a reply before it is split into sentences | spoken diagrams: Mermaid fences read as "a diagram" (`web/src/lib/mermaid.ts`) |
+| `voiceKey` | the TTS voice the cue cache and reply loudness are kept per | `GET /api/settings/speech` |
+| `recorder` (`ConversationRecorder`) | records every step of the conversation | Voice recording (REC-02, `web/src/voice/recorder.ts`) |
+| `workletURL` | the microphone AudioWorklet | `/vad-worklet.js` (the same file as `src/vad-worklet.js`) |
+
+**Recording uploads are off by default**: without a `recorder` nothing is recorded and no recording headers are sent.
+Speech settings, models and keys are never read or changed by the package (the console's settings pages do that).
+
+## Assets, workers and the standalone build
+
+`loadSilero()` and `loadSmartTurn()` start module workers (`silero-worker.ts`, `smart-turn-worker.ts`) that run
+onnxruntime-web's single-threaded wasm build (no SharedArrayBuffer, so no COOP/COEP headers) on the bundled models.
+They and the AudioWorklet are loaded with `new URL(…, import.meta.url)`, which Vite (and other bundlers that support
+the pattern) emits as hashed files; the models are `?url` imports in the workers.
+
+The package has no dependencies of its own: building it needs `onnxruntime-web` 1.23.2 (the root
+devDependencies' version), and a Vite-compatible bundler when built from source.
+
+`npm run build:voice-client` (root) builds `packages/voice-client/dist/` for apps that do not bundle the sources:
+
+- `index.js`: the package as one ES module (the exports of `src/index.ts`);
+- `assets/`: the two workers, onnxruntime-web's `.wasm` (12 MB, compresses to ~3 MB), the two `.onnx` models
+  (Silero VAD 2.3 MB, Smart Turn 8.7 MB) and the AudioWorklet, hashed and referenced relative to `index.js`;
+- `licenses/`: the models' licence files.
+
+Serve `dist/` from the page's own origin (module workers and worklets must be same-origin) and cache `assets/` for
+good (the names are content-hashed).
+
+## Content-Security-Policy for embedding apps
+
+The page's policy needs, beyond the app's usual sources:
+
+```
+worker-src 'self';         # the two module workers (same-origin files; blob: and data: are not needed)
+script-src 'self';         # the AudioWorklet module (addModule) and the package's chunks
+connect-src 'self';        # the workers fetch the .wasm and .onnx files; your transport calls your server
+media-src 'self' blob:;    # replies and cues play from blob: URLs (MediaSource or whole clips)
+```
+
+**wasm and workers.** onnxruntime-web compiles its wasm inside the workers. A worker runs under the policy sent with
+**its own script** (not the page's): when your server sends no CSP on `assets/*-worker-*.js` (the console's sends its
+policy with the HTML only), nothing more is needed. When it sends one on every response (many frameworks do), that
+policy must allow `script-src 'self' 'wasm-unsafe-eval'` and `connect-src 'self'`, or speech detection silently falls
+back to the energy detector and Smart Turn to the timers. Nothing is inlined, no `eval`, no CORS.
+
+The console's own policy is `src/central/csp.ts`; `web/e2e/voice-smart-turn.ts` and `web/e2e/voice-recording.ts` run the
+loop under it, enforced.
+
+## Licences
+
+The package is MIT (as Hub). The bundled models keep their own licences, shipped next to them and copied into the
+standalone build:
+
+- `src/vad/silero_vad.onnx`: Silero VAD v5, MIT (`src/vad/LICENSE`), https://github.com/snakers4/silero-vad
+- `src/turn/smart-turn-v3.2-cpu.onnx`: Pipecat Smart Turn v3.2 (int8), BSD-2-Clause (`src/turn/LICENSE`),
+  https://huggingface.co/pipecat-ai/smart-turn-v3
+
+## Tests
+
+`packages/voice-client/test`: the transport is the contract's type exactly, a plain contract transport drives a whole
+conversation, the package imports nothing outside itself (no `web/`, no `src/`, no other workspace package, no
+`solid-js`, no hard-coded `/api/` calls) and the models ship with their licences. The loop's behaviour tests are
+`test/web-*.test.ts` (through the console's adapters) and the browser e2e `web/e2e/voice-*.ts`.
+`npm run typecheck` includes `tsc -p packages/voice-client` (the package on its own).

package/packages/voice-client/src/vad/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-present Silero Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/central/agent/acting-routes.ts

@@ -7,12 +7,15 @@
 //   POST /api/agent/sessions/:addr/stop    {why?} (body optional)
 //
 // Users always; sessions only through their act token (allow.act; a shell token never acts); app tokens with
-// scope sessions:act. Answers 200 with the engine's result, never cached. Errors: invalid 400, needs_user /
+// scope sessions:act. (AF3) The prompt also admits conversation:write (typed turns of a conversation): such an app
+// token, without sessions:act, may prompt only its own sessions (`appSession`: 404 not_found for any other).
+// Answers 200 with the engine's result, never cached. Errors: invalid 400, needs_user /
 // forbidden 403 (needs_user carries `evaluation` and, once P3-T8 escalates, `decisionID`), not_found 404, gone 410,
 // unsupported 422, paused 423, rate_limited 429, offline 503.
 import { DELIVER_ID_MAX, DELIVERY_MODES, type DeliveryMode, type FormAnswer, formAnswerProblem, type PromptImage, promptImagesProblem } from "../../protocol"
 import type { Acting } from "./acting"
 import { AgentError } from "./errors"
+import type { AgentActor } from "./actor"
 import type { AgentRoute } from "./routes"
 import { AGENT_JSON_BODY_MAX, boundedText } from "./body"
 
@@ -20,6 +23,13 @@ import { AGENT_JSON_BODY_MAX, boundedText } from "./body"
 const PREFIX = "/api/agent/sessions/:addr"
 const NO_STORE = { "cache-control": "no-store" }
 const ACT = { act: true, scope: "sessions:act" } as const
+/** (AF3) Typed turns: sessions:act, or conversation:write for the app's own sessions. */
+const PROMPT = { act: true, scopes: ["sessions:act", "conversation:write"] } as const
+
+export interface ActingRouteOptions {
+  /** (AF3) Throws not_found unless the addressed session is the app's (contract §1.2). */
+  readonly appSession?: (actor: AgentActor, userID: string, addr: string) => Promise<unknown>
+}
 /** Longest `why`. */
 export const WHY_MAX = 1000
 
@@ -56,7 +66,7 @@ function flag(body: Body, key: string): boolean | undefined {
 
 const ok = (result: unknown) => Response.json(result, { headers: NO_STORE })
 
-export function actingRoutes(acting: Acting): AgentRoute[] {
+export function actingRoutes(acting: Acting, options: ActingRouteOptions = {}): AgentRoute[] {
   return [
     {
       method: "POST",
@@ -97,8 +107,12 @@ export function actingRoutes(acting: Acting): AgentRoute[] {
     {
       method: "POST",
       path: `${PREFIX}/prompt`,
-      allow: ACT,
+      allow: PROMPT,
       async handle({ request, params, actor, user }) {
+        if (actor.kind === "app" && !actor.scopes.includes("sessions:act")) {
+          if (!options.appSession) throw new AgentError("forbidden", "This credential cannot use this route")
+          await options.appSession(actor, user.id, params.addr!)
+        }
         const body = await bodyOf(request)
         if (typeof body.text !== "string") throw invalid("text must be a string")
         const delivery = body.delivery

package/src/central/agent/acting.ts

@@ -135,6 +135,8 @@ export const CONCIERGE_NO_GRANT_REASON = "No grant lets it approve here: the use
 export interface Caller {
   readonly actor: AgentActor
   readonly userID: string
+  /** (Concierge front hardening) Record the user actor's device on the audit entry (a relay by voice). */
+  readonly auditDevice?: boolean
 }
 
 export interface ApproveInput {
@@ -648,6 +650,7 @@ export class Acting {
         decision,
         ...(reason ? { reason } : {}),
         outcome,
+        ...(caller.auditDevice && actor.kind === "user" && actor.deviceID ? { deviceID: actor.deviceID } : {}),
       })
     try {
       if (actor.kind !== "user") {
@@ -664,8 +667,9 @@ export class Acting {
         acting.ensureActing(userID)
       }
       // (CON-13) What the spoke said when it refused, never a bare 500.
+      // (AF3 observation 2) An app never gets the spoke's words (paths, commands): a generic refusal; the hub logs them.
       const result = await plan.run(grant).catch((cause: unknown) => {
-        throw refusedBySession(cause)
+        throw refusedBySession(cause, { generic: actor.kind === "app" })
       })
       await record("allow", "ok", why)
       return result
@@ -818,11 +822,16 @@ const gone = () => new AgentError("gone", "Already answered, expired or ended")
 /**
  * (CON-13) The session's harness refused the act (OpenCode said why, e.g. "Unknown form field: Questions"): 400
  * invalid with its words (bounded, one line), never a 500 "Internal error" a model would repeat to the user. The
- * audit keeps it as allowed · failed. A disconnect stays offline; hub errors pass through.
+ * audit keeps it as allowed · failed. A disconnect stays offline; hub errors pass through. (AF3) `generic` (app actors):
+ * "The session refused it" only, to the app and in the audit; the spoke's words go to the hub's log.
  */
-export function refusedBySession(cause: unknown): unknown {
+export function refusedBySession(cause: unknown, options: { readonly generic?: boolean } = {}): unknown {
   if (cause instanceof AgentError || cause instanceof NeedsUser || cause instanceof BusyError) return cause
   if (cause instanceof SpokeError && /disconnected/i.test(cause.message)) return new AgentError("offline", "The session's spoke disconnected")
+  if (options.generic) {
+    console.warn(`[hub] an app's act was refused by the session: ${sanitizeText(cause instanceof Error ? cause.message : String(cause)).replace(/\s+/g, " ").trim().slice(0, 300)}`)
+    return new AgentError("invalid", "The session refused it", { extra: { refusedBy: "session" } })
+  }
   const said = sanitizeText(cause instanceof Error ? cause.message : String(cause)).replace(/\s+/g, " ").trim().slice(0, 300) || "no reason given"
   return new AgentError("invalid", `The session refused it: ${said}`, { extra: { refusedBy: "session" } })
 }

package/src/central/agent/actor.ts

@@ -40,6 +40,9 @@ export interface AppActor {
   readonly tokenID: string
   readonly scopes: readonly string[]
   readonly label?: string
+  /** (AF1) A connected app: its client (tokenID is then the connection ID, stable across refresh). */
+  readonly clientID?: string
+  readonly connection?: true
 }
 
 export type AgentActor = UserActor | SessionActor | AppActor
@@ -166,6 +169,8 @@ export interface AgentAllow {
   readonly session?: boolean
   /** App tokens holding this scope may call it. */
   readonly scope?: string
+  /** (AF3) App tokens holding any of these scopes may call it (the route narrows what each admits). */
+  readonly scopes?: readonly string[]
   /** Any app token may call it (introspection such as whoami). */
   readonly app?: boolean
   /**
@@ -188,6 +193,6 @@ export function agentAllows(allow: AgentAllow, actor: AgentActor): boolean {
     case "session":
       return allow.act === true ? canActAsSession(actor) : allow.session === true
     case "app":
-      return allow.app === true || (allow.scope !== undefined && actor.scopes.includes(allow.scope))
+      return allow.app === true || (allow.scope !== undefined && actor.scopes.includes(allow.scope)) || (allow.scopes?.some((scope) => actor.scopes.includes(scope)) ?? false)
   }
 }

package/src/central/agent/app-decisions.ts

@@ -0,0 +1,146 @@
+// Decisions from apps (AF4, docs/plans/2026-11-08-app-front-contracts.md §6; Hub decision w6lfbfaq 1; user decision
+// 2026-11-09): an app holding `decisions:answer` lists and answers confirm-tier Decisions of ITS sessions.
+//
+//   GET  /api/agent/decisions?answerable=1[&state=]   decisions:answer   {decisions}: only those this app may answer
+//   POST /api/agent/decisions/:id/answer {option?, text?}   decisions:answer   {decision} (answer.answeredBy "app")
+// The list shares its path with the asker's GET /api/agent/decisions (message-routes.ts), which hands `answerable`
+// requests here (`answerable`). Both are for app credentials only: the user answers on the console (/api/decisions),
+// sessions never answer Decisions.
+//
+// "The app's sessions" for Decisions (user decision 2026-11-09): the asker (`from`) is a SESSION that the app launched,
+// or that an active grant the app holds covers and whose verbs allow `answer` (a prompt-only grant does not imply
+// answering); subagents count with their root; a deleted session, a Concierge session and every other asker (another
+// session, an app, the user) read as unknown: 404 not_found, so IDs never leak. Re-checked on every request, so a grant
+// revoked or narrowed after the list refuses the answer. Then (Decisions.answerByApp): open (else 410 gone), confirm
+// tier with no action and not Concierge-asked (403 forbidden "This decision needs the user"), a once-off option (a
+// lasting one: 403), the kill switch (423 paused) and the version-checked settle: the first answer wins across the
+// console and every app (the later one: 410 gone). A body with `via` is 400 invalid (an app's answer is never the
+// user's tap, voice or text). The asker hears which app answered; the agent audit lists every attempt on an app's
+// session as `decision.answer` by app:<id> (unowned IDs are not audited: guessing cannot flood it). Failures carry the
+// hub's own words only (agentFailure: an internal error is a generic "Internal error").
+import type { Store } from "../store"
+import type { AppActor } from "./actor"
+import { auditOf } from "./acting"
+import type { ActingSwitch } from "./acting-switch"
+import type { AgentAudit, AuditDecision, AuditOutcome } from "./audit"
+import { AGENT_JSON_BODY_MAX, boundedText } from "./body"
+import { type AppSessionDeps, isAppSession, locateSession } from "./conversation"
+import { DECISION_STATES, type Decision, type DecisionState, type Decisions } from "./decisions"
+import { partyFromActor } from "./envelope"
+import { AgentError } from "./errors"
+import type { Message } from "./messages"
+import type { GrantVerb } from "./policy"
+import type { AgentContext, AgentRoute } from "./routes"
+
+// A literal: routes.ts imports this module.
+const PREFIX = "/api/agent/decisions"
+const NO_STORE = { "cache-control": "no-store" }
+
+/** The grant verbs that make a session an app's for Decisions (user decision 2026-11-09). */
+export const DECISION_VERBS: readonly GrantVerb[] = ["answer"]
+
+export interface AppDecisionDeps extends AppSessionDeps {
+  readonly decisions: Pick<Decisions, "list" | "answerByApp">
+  readonly acting: Pick<ActingSwitch, "ensureActing">
+  readonly audit: Pick<AgentAudit, "record">
+  readonly store: Pick<Store, "audit">
+  /** The asker's reply, to the message feed (watch streams, waiters). */
+  readonly publish?: (userID: string, message: Message) => void
+}
+
+const forbiddenFor = () => new AgentError("forbidden", "This route is for app credentials", { hint: "Answer Decisions in the console" })
+
+/** Per request: the app's ownership of Decisions' askers, reading grants and launches once. */
+function ownership(deps: AppSessionDeps, actor: AppActor, userID: string) {
+  let grants: ReturnType<AppSessionDeps["grants"]["list"]> | undefined
+  let launches: ReturnType<NonNullable<AppSessionDeps["launches"]>["list"]> | undefined
+  const cached: AppSessionDeps = {
+    ...deps,
+    grants: { list: (id: string) => (grants ??= deps.grants.list(id)) },
+    ...(deps.launches ? { launches: { list: (id: string) => (launches ??= deps.launches!.list(id)) } } : {}),
+  }
+  /** The asking session when it is the app's (Decisions), undefined otherwise. */
+  return async (decision: Decision): Promise<string | undefined> => {
+    if (decision.from.kind !== "session") return undefined
+    let target
+    try {
+      target = locateSession(cached, userID, decision.from.sessionID)
+    } catch (cause) {
+      if (cause instanceof AgentError && cause.code === "not_found") return undefined
+      throw cause
+    }
+    return (await isAppSession(cached, actor, userID, target, DECISION_VERBS)) ? target.sessionID : undefined
+  }
+}
+
+async function answerBody(request: Request): Promise<{ option?: string; text?: string }> {
+  const raw = await boundedText(request, AGENT_JSON_BODY_MAX)
+  const body: unknown = JSON.parse(raw)
+  if (typeof body !== "object" || body === null || Array.isArray(body)) throw new AgentError("invalid", "Body must be a JSON object")
+  const input = body as Record<string, unknown>
+  if ("via" in input) throw new AgentError("invalid", "An app's answer has no via", { hint: "Send {option} or {text}" })
+  for (const key of ["option", "text"] as const) {
+    if (input[key] !== undefined && typeof input[key] !== "string") throw new AgentError("invalid", `${key} must be a string`)
+  }
+  return { ...(typeof input.option === "string" ? { option: input.option } : {}), ...(typeof input.text === "string" ? { text: input.text } : {}) }
+}
+
+function stateQuery(raw: string | null): DecisionState | undefined {
+  if (raw === null || raw === "") return undefined
+  if (!DECISION_STATES.includes(raw as DecisionState)) throw new AgentError("invalid", `state is one of ${DECISION_STATES.join(", ")}`)
+  return raw as DecisionState
+}
+
+export function appDecisionRoutes(deps: AppDecisionDeps): { readonly answerable: (context: AgentContext) => Promise<Response>; readonly routes: AgentRoute[] } {
+  /** GET /api/agent/decisions?answerable=1: the Decisions this app may answer (any state unless `state`). */
+  async function answerable({ actor, user, url }: AgentContext): Promise<Response> {
+    if (actor.kind !== "app") throw forbiddenFor()
+    if (!actor.scopes.includes("decisions:answer")) throw new AgentError("forbidden", "This credential cannot use this route")
+    if (url.searchParams.get("answerable") !== "1") throw new AgentError("invalid", "answerable takes 1")
+    const state = stateQuery(url.searchParams.get("state"))
+    const owner = ownership(deps, actor, user.id)
+    const decisions: Decision[] = []
+    for (const decision of await deps.decisions.list(user.id, state ? { state } : {})) {
+      // The cheap rules first: only a confirm-tier Decision without an action that no Concierge asked.
+      if (decision.tier !== "confirm" || decision.action !== undefined || decision.as === "concierge") continue
+      if (await owner(decision)) decisions.push(decision)
+    }
+    return Response.json({ decisions }, { headers: NO_STORE })
+  }
+
+  return {
+    answerable,
+    routes: [
+      {
+        method: "POST",
+        path: `${PREFIX}/:id/answer`,
+        allow: { scope: "decisions:answer" },
+        async handle({ actor, user, request, params }) {
+          if (actor.kind !== "app") throw forbiddenFor()
+          const input = await answerBody(request)
+          const owner = ownership(deps, actor, user.id)
+          let sessionID: string | undefined
+          const record = (decision: AuditDecision, outcome: AuditOutcome, reason?: string) =>
+            deps.audit.record(user.id, { actor: partyFromActor(actor), verb: "decision.answer", target: { sessionID: sessionID! }, decision, ...(reason ? { reason } : {}), outcome })
+          try {
+            const answered = await deps.decisions.answerByApp(user.id, params.id!, input, { party: `app:${actor.tokenID}`, ...(actor.label ? { label: actor.label } : {}) }, {
+              owned: async (decision) => (sessionID = await owner(decision)) !== undefined,
+              ready: () => deps.acting.ensureActing(user.id),
+            })
+            if (answered.reply) deps.publish?.(user.id, answered.reply)
+            await record("allow", "ok", `Decision ${params.id!}`)
+            await deps.store.audit({ actor: user.id, action: "decision.answer", target: params.id!, detail: `app:${actor.tokenID} ${answered.decision.answer?.option ?? "text"}` })
+            return Response.json({ decision: answered.decision }, { headers: NO_STORE })
+          } catch (cause) {
+            // Only attempts on the app's own sessions' Decisions (unknown or foreign IDs are not audited).
+            if (sessionID !== undefined) {
+              const [decision, outcome] = cause instanceof AgentError && cause.code === "gone" ? (["allow", "gone"] as const) : auditOf(cause)
+              await record(decision, outcome, cause instanceof AgentError ? cause.message : undefined).catch((error: unknown) => console.error(`[hub] audit of an app's decision answer failed: ${(error as Error).message}`))
+            }
+            throw cause
+          }
+        },
+      },
+    ],
+  }
+}

package/src/central/agent/app-tokens.ts

@@ -18,9 +18,13 @@ import type { AgentRoute } from "./routes"
 /**
  * Scopes an app token may hold: reading sessions; sending (msg, ask, reply, decline, mute) and reading messages;
  * acting on sessions (approve, deny, answer, prompt, stop) and launching sessions (phase 4), each of which still
- * needs a grant held by the token (with the act verb, or `launch` covering the repo).
+ * needs a grant held by the token (with the act verb, or `launch` covering the repo); (AF2) `speech:use`: transcribe
+ * and speak with the user's speech provider (agent/speech-routes.ts); (AF3) `conversation:read` (the stream and log
+ * of the app's sessions) and `conversation:write` (conversation, utterance, interrupt and typed turns, each behind a
+ * prompt grant) (agent/conversation.ts); (AF4) `decisions:answer`: list and answer confirm-tier Decisions of the app's
+ * sessions (launched by it, or under a grant allowing answer) (agent/app-decisions.ts).
  */
-export const APP_SCOPES: readonly string[] = ["sessions:read", "sessions:manage", "messages:send", "messages:read", "sessions:act", "sessions:launch", "events:subscribe", "profiles:read", "profiles:manage", "profiles:assign", "workspaces:read", "workspaces:manage", "artifacts:read", "artifacts:write", "artifacts:ai", "teams:submit", "teams:read", "teams:manage"]
+export const APP_SCOPES: readonly string[] = ["sessions:read", "sessions:manage", "messages:send", "messages:read", "sessions:act", "sessions:launch", "events:subscribe", "profiles:read", "profiles:manage", "profiles:assign", "workspaces:read", "workspaces:manage", "artifacts:read", "artifacts:write", "artifacts:ai", "teams:submit", "teams:read", "teams:manage", "speech:use", "conversation:read", "conversation:write", "decisions:answer"]
 export const DEFAULT_APP_SCOPES: readonly string[] = ["sessions:read"]
 /** What `hub login` (the CLI login device code) asks for unless it asks for more: reading sessions and messaging. */
 export const DEFAULT_CLI_LOGIN_SCOPES: readonly string[] = ["sessions:read", "messages:send", "messages:read"]
@@ -115,7 +119,7 @@ export async function issueAppToken(store: Store, userID: string, input: { reado
 }
 
 /** POST, GET and DELETE /api/agent/app-tokens: user actors only. */
-export function appTokenRoutes(store: Store): AgentRoute[] {
+export function appTokenRoutes(store: Store, options: { readonly revoked?: (userID: string) => void } = {}): AgentRoute[] {
   return [
     {
       method: "POST",
@@ -146,6 +150,8 @@ export function appTokenRoutes(store: Store): AgentRoute[] {
         })
         if (!found) throw new AgentError("not_found", "No such app token")
         await store.audit({ actor: user.id, action: "app-token.revoke", target: id })
+        // (AF3) Its open streams end now, not at their next re-check.
+        options.revoked?.(user.id)
         return new Response(null, { status: 204, headers: NO_STORE })
       },
     },

package/src/central/agent/audit.ts

@@ -55,6 +55,8 @@ export interface AuditInput {
   readonly outcome: AuditOutcome
   /** (CON-06) Done by one of the user's Concierge sessions (current or past). */
   readonly as?: "concierge"
+  /** (Concierge front hardening) The user's device the act came from (a relay by voice), when the caller records it. */
+  readonly deviceID?: string
 }
 
 export interface AgentAuditEntry extends AuditInput {
@@ -141,6 +143,7 @@ export class AgentAudit {
       ...(reason ? { reason } : {}),
       outcome: input.outcome,
       ...(as ? { as } : {}),
+      ...(typeof input.deviceID === "string" && /^[A-Za-z0-9_-]{1,100}$/.test(input.deviceID) ? { deviceID: input.deviceID } : {}),
     }
     await state.put(userID, ENTRIES, keyOf(seq), entry)
     if (seq > this.limit) await state.delete(userID, ENTRIES, keyOf(seq - this.limit))