@huynle/hub 0.9.1 → 0.10.0

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

@@ -0,0 +1,293 @@
+// The app-front contract (AF0, docs/plans/2026-11-08-app-front-contracts.md; schema
+// packages/protocol/schema/app-front/v1.schema.json): what an external app (a server-side BFF) uses to make Hub its
+// AI layer — connect with consent (AF1), speech (AF2), a conversation stream (AF3), answering its own sessions'
+// confirm-tier Decisions (AF4) and the voice-client transport (AF5/AF6). Pure: names, units, limits, codes and the
+// few rules both the hub and apps need (redirect URIs, the scope parameter, PKCE shapes, token formats). Nothing
+// here is specific to any one app (Hub decision kvtvodrn); user answers in Hub decisions w6lfbfaq and nixct956.
+
+/** Version of the app-front contract and its schema; additive changes keep 1. */
+export const APP_FRONT_VERSION = 1
+
+// ---------- scopes and features ----------
+
+/** The scopes the app front adds to APP_SCOPES (src/central/agent/app-tokens.ts), each shipped by its AF task. */
+export const APP_FRONT_SCOPES = ["speech:use", "conversation:read", "conversation:write", "decisions:answer"] as const
+export type AppFrontScope = (typeof APP_FRONT_SCOPES)[number]
+
+/** `/.well-known/hub` `features` flags: a hub lists one only once the task that ships it is merged. */
+export const APP_FRONT_FEATURES = ["app-connect", "app-speech", "app-conversation", "app-decisions"] as const
+export type AppFrontFeature = (typeof APP_FRONT_FEATURES)[number]
+
+/** The task that ships each flag, and the scope that flag brings (app-connect brings none: it is the flow). */
+export const APP_FRONT_FEATURE_TASK: Readonly<Record<AppFrontFeature, { readonly task: string; readonly scopes: readonly AppFrontScope[] }>> = {
+  "app-connect": { task: "AF1", scopes: [] },
+  "app-speech": { task: "AF2", scopes: ["speech:use"] },
+  "app-conversation": { task: "AF3", scopes: ["conversation:read", "conversation:write"] },
+  "app-decisions": { task: "AF4", scopes: ["decisions:answer"] },
+}
+
+/**
+ * What this source tree ships. Each AF task flips its flag in the same commit that ships it (the schema test then
+ * expects the hub to advertise it and its routes to answer); until then the feature is contract-only.
+ */
+export const APP_FRONT_SHIPPED: Readonly<Record<AppFrontFeature, boolean>> = {
+  "app-connect": true,
+  "app-speech": true,
+  "app-conversation": true,
+  "app-decisions": true,
+}
+
+// ---------- connect (AF1): OAuth 2.1-style authorization code + PKCE ----------
+
+/** Endpoints of the connect flow. `/connect/*` and the metadata are top level (never behind the console gate). */
+export const CONNECT_PATHS = {
+  /** RFC 8414 authorization server metadata (public). */
+  metadata: "/.well-known/oauth-authorization-server",
+  /** GET, browser: validates the request, opens a flow, redirects to the consent page. */
+  authorize: "/connect/authorize",
+  /** The console's consent page (signed-in user). */
+  consentPage: "/connect/consent/:flow",
+  /** POST, app server (form-encoded, client authentication): code → tokens, refresh → tokens. */
+  token: "/connect/token",
+  /** POST, app server (RFC 7009): ends the connection the token belongs to. */
+  revoke: "/connect/revoke",
+  /** Console routes behind the gate (cookie, same origin): read, approve, deny a flow. */
+  flow: "/api/connect/flows/:flow",
+  flowApprove: "/api/connect/flows/:flow/approve",
+  flowDeny: "/api/connect/flows/:flow/deny",
+  /** /api/agent, user actors only: registered clients (admins write) and the user's connections. */
+  clients: "/api/agent/app-clients",
+  client: "/api/agent/app-clients/:id",
+  clientSecret: "/api/agent/app-clients/:id/secret",
+  connections: "/api/agent/connections",
+  connection: "/api/agent/connections/:id",
+} as const
+
+/** Token and ID prefixes ("hc": hub connect). Hand-made app tokens keep `hat_` (unchanged, never expire). */
+export const CONNECT_PREFIXES = {
+  clientID: "hcl_",
+  clientSecret: "hcs_",
+  flow: "hcf_",
+  code: "hco_",
+  access: "hca_",
+  refresh: "hcr_",
+} as const
+
+/** Anchored formats; secrets are 32 random bytes in base64url (43 characters). Connection IDs are 16 hex. */
+export const CONNECT_TOKEN_PATTERNS = {
+  clientID: /^hcl_[0-9a-f]{16}$/,
+  clientSecret: /^hcs_[A-Za-z0-9_-]{43}$/,
+  flow: /^hcf_[0-9a-f]{24}$/,
+  code: /^hco_[A-Za-z0-9_-]{43}$/,
+  access: /^hca_([0-9a-f]{16})_[A-Za-z0-9_-]{43}$/,
+  refresh: /^hcr_([0-9a-f]{16})_[A-Za-z0-9_-]{43}$/,
+  connectionID: /^[0-9a-f]{16}$/,
+} as const
+
+/** Lifetimes (ms). */
+export const ACCESS_TOKEN_TTL_MS = 60 * 60_000
+/** Sliding: every refresh issues a refresh token valid this long from then; unused this long, the connection lapses. */
+export const REFRESH_TOKEN_IDLE_MS = 30 * 24 * 60 * 60_000
+export const AUTHORIZATION_CODE_TTL_MS = 60_000
+/**
+ * After a refresh, presenting the just-rotated refresh token again this long answers the same new pair (a lost answer
+ * can be retried); after it, that is reuse and revokes the connection (Hub decision nixct956 3).
+ */
+export const REFRESH_GRACE_MS = 30_000
+/** From authorize to approve/deny (like CLI_LOGIN_TTL_MS). */
+export const CONNECT_FLOW_TTL_MS = 10 * 60_000
+
+export const CONNECT_LIMITS = {
+  /** Hub-wide (admin-registered) clients per hub. */
+  clients: 50,
+  /** Personal clients per user (decision nixct956 5). */
+  personalClientsPerUser: 10,
+  redirectURIsPerClient: 10,
+  clientNameMax: 100,
+  /** `state` is opaque to the hub and echoed back. */
+  stateMax: 1024,
+  /** Connections per user (one per client). */
+  connectionsPerUser: 50,
+  /** Authorize requests per client and client address a minute (an open flow is cheap but bounded). */
+  authorizePerMinute: 20,
+  /** Authenticated token-endpoint requests per client and minute. */
+  tokenPerMinute: 60,
+  /**
+   * Failed client authentications per client and client address a minute; beyond, that address's failures get 429
+   * (a caller with the right secret is never refused for them).
+   */
+  failedClientAuthPerMinute: 10,
+} as const
+
+/**
+ * Who may use a registered client (Hub decision nixct956 5): `hub` (hub-wide, admin-registered: every user of the hub
+ * may connect) or `user` (personal: only the user who registered it sees and uses it).
+ */
+export const CLIENT_AUDIENCES = ["hub", "user"] as const
+export type ClientAudience = (typeof CLIENT_AUDIENCES)[number]
+
+export const CODE_CHALLENGE_METHODS = ["S256"] as const
+export const RESPONSE_TYPES = ["code"] as const
+export const GRANT_TYPES = ["authorization_code", "refresh_token"] as const
+export const TOKEN_ENDPOINT_AUTH_METHODS = ["client_secret_basic", "client_secret_post"] as const
+
+/** RFC 6749 §4.1.2.1 errors the authorize endpoint redirects with (only once client_id and redirect_uri are valid). */
+export const AUTHORIZE_ERRORS = ["invalid_request", "unauthorized_client", "access_denied", "unsupported_response_type", "invalid_scope", "server_error", "temporarily_unavailable"] as const
+/** RFC 6749 §5.2 errors of the token endpoint, with their HTTP status (`temporarily_unavailable` 429: rate limit). */
+export const TOKEN_ERROR_STATUS = {
+  invalid_request: 400,
+  invalid_client: 401,
+  invalid_grant: 400,
+  unauthorized_client: 400,
+  unsupported_grant_type: 400,
+  invalid_scope: 400,
+  temporarily_unavailable: 429,
+} as const
+export type TokenError = keyof typeof TOKEN_ERROR_STATUS
+
+// ---------- speech (AF2) ----------
+
+export const SPEECH_PATHS = { transcribe: "/api/agent/speech/transcribe", speak: "/api/agent/speech/speak" } as const
+
+/** Per app credential (a connection, or a hand-made token): 429 rate_limited with retryAfter beyond these. */
+export const SPEECH_RATE_LIMITS = {
+  transcribe: { perMinute: 20, perHour: 300 },
+  speak: { perMinute: 60, perHour: 1000, charsPerHour: 100_000 },
+} as const
+
+// ---------- conversation (AF3) ----------
+
+export const CONVERSATION_PATHS = {
+  stream: "/api/agent/sessions/:addr/stream",
+  conversation: "/api/agent/sessions/:addr/conversation",
+  utterance: "/api/agent/sessions/:addr/utterance",
+  interrupt: "/api/agent/sessions/:addr/interrupt",
+  /** Typed turns: the existing act prompt, also admitted with conversation:write. */
+  turn: "/api/agent/sessions/:addr/prompt",
+  /** Re-read after a reset: the existing log, also admitted with conversation:read for the app's sessions. */
+  log: "/api/agent/sessions/:addr/log",
+} as const
+
+export const APP_STREAM_FRAME_TYPES = ["ready", "delta", "say", "heard", "status", "conversation", "reset", "end"] as const
+export type AppStreamFrameType = (typeof APP_STREAM_FRAME_TYPES)[number]
+
+/** Why the hub ended an app stream (the last frame, `end`). */
+export const APP_STREAM_END_REASONS = ["token_expired", "revoked", "grant", "gone", "slow"] as const
+export type AppStreamEndReason = (typeof APP_STREAM_END_REASONS)[number]
+
+/** What a `reset` frame asks the app to re-read. */
+export const APP_STREAM_REFRESH = ["log", "status", "conversation", "decisions"] as const
+
+export const APP_STREAM_LIMITS = {
+  heartbeatMs: 20_000,
+  /** Draining: `retry:` sent before the stream ends. */
+  retryMs: 2_000,
+  /** How often an open stream re-checks its credential, grant and session (and ends with `end`). */
+  recheckMs: 30_000,
+  /** Unsent bytes a slow reader may hold before the hub ends the stream (`end` reason slow). */
+  bufferMaxBytes: 1 << 20,
+  /** Concurrent streams per app credential, and per user over all apps (429 rate_limited beyond). */
+  streamsPerApp: 4,
+  streamsPerUser: 20,
+} as const
+
+// ---------- decisions (AF4) ----------
+
+export const DECISION_PATHS = { list: "/api/agent/decisions", answer: "/api/agent/decisions/:id/answer" } as const
+/** The only tier an app answers (decision w6lfbfaq 1). */
+export const APP_ANSWERABLE_TIERS = ["confirm"] as const
+
+// ---------- voice-client transport (AF5 interface, AF6 app adapter) ----------
+
+/** What the voice loop hears about its session (the app stream's frames it uses). */
+export type VoiceEvent =
+  | { 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: "conversation"; readonly sessionID: string; readonly on: boolean; readonly front?: boolean; readonly reason?: "front_failed" }
+  | { readonly type: "status"; readonly sessionID: string; readonly state: "idle" | "working" | "blocked" | "error" }
+  | { readonly type: "reset" }
+
+/**
+ * The transport the voice loop (packages/voice-client) talks through. The console implements it with its cookie
+ * routes; an app implements it against its own server, which calls the AF2/AF3 routes with its token. The package
+ * never holds a hub token and never calls the hub itself.
+ */
+export interface VoiceTransport {
+  /** Conversation mode on/off for the session (front: the voice front). */
+  conversation(on: boolean, options?: { readonly front?: boolean }): Promise<{ readonly on: boolean; readonly front?: boolean }>
+  /** A final transcript, to the session (or its front). */
+  utterance(text: string): Promise<{ readonly inboxID: string }>
+  /** Barge-in: stops the front (or the session's turn). */
+  interrupt(): Promise<void>
+  transcribe(audio: Blob, options?: { readonly signal?: AbortSignal }): Promise<{ readonly text: string }>
+  /** audio/mpeg, streamed when the provider streams. */
+  speak(text: string, options?: { readonly signal?: AbortSignal }): Promise<ReadableStream<Uint8Array>>
+  /** Subscribes to the session's voice events; returns the unsubscribe. */
+  events(listener: (event: VoiceEvent) => void): () => void
+}
+
+// ---------- rules ----------
+
+export const REDIRECT_URI_MAX = 2048
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "[::1]", "localhost"])
+
+/**
+ * Why `uri` cannot be a registered redirect URI, or undefined: an absolute https URL (http only on a loopback host),
+ * at most REDIRECT_URI_MAX characters, without user info, fragment, wildcard or surrounding whitespace.
+ */
+export function redirectUriProblem(uri: unknown): string | undefined {
+  if (typeof uri !== "string" || uri === "") return "a redirect URI is a non-empty string"
+  if (uri.length > REDIRECT_URI_MAX) return `a redirect URI is at most ${REDIRECT_URI_MAX} characters`
+  if (uri.trim() !== uri || /\s/.test(uri)) return "a redirect URI has no whitespace"
+  if (uri.includes("*")) return "a redirect URI has no wildcard"
+  let url: URL
+  try {
+    url = new URL(uri)
+  } catch {
+    return "a redirect URI is an absolute URL"
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return "a redirect URI uses https (http only on a loopback host)"
+  if (url.protocol === "http:" && !LOOPBACK_HOSTS.has(url.hostname)) return "http is allowed only on a loopback host (127.0.0.1, [::1], localhost)"
+  if (url.username || url.password) return "a redirect URI has no user info"
+  if (uri.includes("#")) return "a redirect URI has no fragment"
+  return undefined
+}
+
+/** Exact string comparison against the registered URIs (no normalisation of any kind). */
+export function redirectUriMatches(registered: readonly string[], uri: unknown): boolean {
+  return typeof uri === "string" && registered.includes(uri)
+}
+
+/** The OAuth `scope` parameter: scopes separated by single spaces, each known; duplicates dropped, order kept. */
+export function parseScopeParam(value: unknown, known: readonly string[]): { scopes: string[] } | { problem: string } {
+  if (typeof value !== "string" || value === "") return { problem: "scope lists at least one scope" }
+  const parts = value.split(" ")
+  if (parts.some((part) => part === "")) return { problem: "scope separates scopes with single spaces" }
+  const unknown = parts.find((part) => !known.includes(part))
+  if (unknown !== undefined) return { problem: `unknown scope: ${unknown.slice(0, 64)}` }
+  return { scopes: [...new Set(parts)] }
+}
+
+const VERIFIER = /^[A-Za-z0-9._~-]{43,128}$/
+const CHALLENGE = /^[A-Za-z0-9_-]{43}$/
+
+/** RFC 7636 §4.1: 43–128 unreserved characters. */
+export function pkceVerifierProblem(verifier: unknown): string | undefined {
+  return typeof verifier === "string" && VERIFIER.test(verifier) ? undefined : "code_verifier is 43–128 characters of A-Z a-z 0-9 - . _ ~"
+}
+
+/** S256 only: the challenge is base64url(SHA-256(verifier)) without padding (43 characters). */
+export function pkceChallengeProblem(challenge: unknown, method: unknown): string | undefined {
+  if (method !== "S256") return "code_challenge_method must be S256"
+  return typeof challenge === "string" && CHALLENGE.test(challenge) ? undefined : "code_challenge is 43 base64url characters"
+}
+
+/** A connected app's access or refresh token, with the connection it belongs to; anything else undefined. */
+export function parseConnectToken(token: unknown): { kind: "access" | "refresh"; connectionID: string } | undefined {
+  if (typeof token !== "string") return undefined
+  const access = CONNECT_TOKEN_PATTERNS.access.exec(token)
+  if (access) return { kind: "access", connectionID: access[1]! }
+  const refresh = CONNECT_TOKEN_PATTERNS.refresh.exec(token)
+  if (refresh) return { kind: "refresh", connectionID: refresh[1]! }
+  return undefined
+}

package/packages/protocol/src/concierge.ts

@@ -101,8 +101,10 @@ export const CONCIERGE_LIMITS = {
 /**
  * The keys of the parts a session context carries. The spoke appends instructions then notes to the session's system
  * prompt (stable between turns) and sends the board after the conversation (it changes: V-01, the prompt cache).
+ * "frontBoard" (voice front P2, sent only to spokes announcing "conciergeFront"): the compact board for the
+ * Concierge's voice front; never part of the Concierge's own prompt.
  */
-export const SESSION_CONTEXT_KEYS = ["instructions", "board", "notes"] as const
+export const SESSION_CONTEXT_KEYS = ["instructions", "board", "notes", "frontBoard"] as const
 export type SessionContextKey = (typeof SESSION_CONTEXT_KEYS)[number]
 
 export const SESSION_CONTEXT_LIMITS = { partChars: 40_000, denyGlobs: 50, globChars: 100, allowTools: 50 } as const
@@ -272,6 +274,11 @@ export interface ConciergeBoardSession {
   readonly project?: string
   /** Machine name (sanitised label). */
   readonly machine?: string
+  /**
+   * (Concierge grant requests) The verbs an active @@concierge grant allows in this session's project folder (the
+   * acting engine's grant lookup for the current Concierge; [] = none). Absent: unknown (no Concierge, no folder).
+   */
+  readonly projectGrant?: readonly string[]
   readonly state: ConciergeBoardState
   /** When the current state began, as far as the hub knows (activity, last result, or lastSeen when offline). */
   readonly since?: number
@@ -283,6 +290,8 @@ export interface ConciergeBoardSession {
   readonly intent?: { readonly text: string; readonly source: IntentSource }
   /** The non-placeholder title (at most 80 characters), untrusted; only when there is no intent. */
   readonly title?: string
+  /** The primary context card's headline (at most 90 characters), untrusted: where the work stands (docs/context-cards.md). */
+  readonly pickup?: string
   readonly lastResult?: { readonly at: number; readonly outcome: ConciergeResultOutcome }
   readonly reasons: readonly WatchReason[]
 }

package/packages/protocol/src/context-cards.ts

@@ -0,0 +1,59 @@
+// Context cards (decision 9604b0a1, docs/context-cards.md): short, auto-updated cards beside a session that help
+// the user and the Concierge pick its work back up. Each card comes from a PROVIDER (the hub's registry, e.g.
+// `pickup`, `changes`); one provider is primary: its headline is the session list's second line. Shared by the
+// hub (src/central/context-cards) and the console (web/src/core/context-cards-core.ts).
+
+/** What makes a provider run: a turn ended, the session went blocked, the user came back, the leader's sweep, a refresh. */
+export const CONTEXT_CARD_TRIGGERS = ["turn-end", "blocked", "user-return", "sweep", "manual"] as const
+export type ContextCardTrigger = (typeof CONTEXT_CARD_TRIGGERS)[number]
+
+/** Bounds of a stored card (characters, code points). */
+export const CONTEXT_CARD_LIMITS = {
+  title: 60,
+  headline: 90,
+  body: 400,
+  fields: 6,
+  fieldLabel: 24,
+  fieldValue: 120,
+  model: 100,
+} as const
+
+export interface ContextCardField {
+  readonly label: string
+  readonly value: string
+}
+
+export interface ContextCard {
+  /** The provider's id (`pickup`, `changes`, …). */
+  readonly provider: string
+  readonly sessionID: string
+  /** The card's title ("Pick up where you left off"). */
+  readonly title: string
+  /** One line (≤ 90 characters): the primary card's is the session list's second line. */
+  readonly headline: string
+  /** Markdown-lite text (≤ 400 characters; may be empty). Untrusted: render as text. */
+  readonly body: string
+  readonly fields?: readonly ContextCardField[]
+  /** Epoch ms. */
+  readonly generatedAt: number
+  /** The model that wrote it (model providers only). */
+  readonly model?: string
+  /** Hash of the inputs it was made from (unchanged inputs are not regenerated). */
+  readonly inputsHash: string
+  /** The provider's version when it was made. */
+  readonly version: number
+  readonly trigger: ContextCardTrigger
+  /** The inputs it was made from (an offline spoke's weaker inputs never replace a richer card). */
+  readonly basis?: readonly string[]
+  /** The primary card (its headline is the list's second line). */
+  readonly primary?: true
+}
+
+/** A provider as clients see it. */
+export interface ContextCardProviderInfo {
+  readonly id: string
+  readonly label: string
+  readonly primary: boolean
+  /** It calls the context card model (needs it configured, counts against the daily budget). */
+  readonly usesModel: boolean
+}

package/packages/protocol/src/credentials.ts

@@ -1,9 +1,16 @@
 // Literal credentials in free text (tokens, keys, private keys): found, or replaced with "[redacted: <kind>]". Voice
 // recordings scrub every text field with it; spoken and pushed failure reasons and voice-front wakes do too.
 
+/**
+ * A private key block of any type (PEM, OpenSSH, encrypted, PGP): BEGIN through END; without an END (a cut text), the
+ * header, the base64 chunks after it on the same line (after spaces or a literal "\n", as in JSON or env strings) and
+ * the key-material lines after it. Prose after a bare header ("… KEY----- and …") is kept.
+ */
+const PRIVATE_KEY = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----(?:[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----|(?:(?:[ \t]+|\\n)[A-Za-z0-9+/=]{8,})*(?:\r?\n[A-Za-z0-9+/=:,. -]*)*)/
+
 /** Distinctive credential formats; prose about secrets ("set API_KEY=…") is not matched. */
 export const CREDENTIALS: readonly (readonly [string, RegExp])[] = [
-  ["private key", /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+  ["private key", PRIVATE_KEY],
   ["hub app token", /\bhat_[0-9a-f]{16}_[A-Za-z0-9_-]{43,}/],
   ["github token", /\bgh[pousr]_[A-Za-z0-9]{36,}/],
   ["github token", /\bgithub_pat_[A-Za-z0-9_]{22,}/],
@@ -15,6 +22,31 @@ export const CREDENTIALS: readonly (readonly [string, RegExp])[] = [
   ["bearer token", /\b[Bb]earer\s+[A-Za-z0-9._~+/=-]{20,}/],
 ]
 
+/** Names whose value is a secret: ending in password, passwd, pwd, passphrase, secret, token, api key, or AWS key names. */
+const NAME = String.raw`[A-Za-z0-9_.-]*(?:password|passwd|pwd|passphrase|secret|token|api[_-]?key|secret_?access_?key|access_?key_?id)`
+/** Between a name and its value: an optional closing quote, then = or :. */
+const SEP = String.raw`["']?\s*[:=]\s*`
+/** Placeholder values in docs and prose ("API_KEY=your-key-here", "<token>", "…", "xxx", "changeme") are not secrets. */
+const PLACEHOLDER = String.raw`(?!(?:your[-_ ]|<|\.\.\.|…|x{3,}(?![A-Za-z0-9])|\*{3,}|changeme|example|placeholder)[^\s"']*(?:["'\s&;,<>]|$))`
+
+/**
+ * Secrets by context, redacted by redactCredentials after CREDENTIALS (the name stays, the value goes):
+ *   aws secret key: a 40-character key after aws_secret_access_key / aws_secret_key / secret_access_key (any case)
+ *   url password:   scheme://user:<password>@host (the user may be empty; the password may hold "/"; a port is not one)
+ *   authorization:  the credentials after Authorization: Basic | Bearer | Token | Digest
+ *   secret:         <name>=value, <name>: value and "<name>": "value" (NAME, any case, e.g. GITHUB_TOKEN, client_secret,
+ *                   OPENAI_API_KEY, apiKey, SecretAccessKey, SessionToken, AccessKeyId); a quoted value goes whole
+ *                   (spaces, commas, semicolons included), an unquoted one runs to whitespace, a quote or & ; , < >;
+ *                   placeholders (your-…, <…>, …, xxx, ***, changeme, example, placeholder) are left alone
+ */
+const CONTEXTUAL: readonly (readonly [string, RegExp, string])[] = [
+  ["aws secret key", /\b((?:aws_)?secret(?:_access)?_key["']?\s*[:=]\s*["']?)(?!\[redacted)[A-Za-z0-9/+=]{40}(?![A-Za-z0-9/+=])/gi, "$1[redacted: aws secret key]"],
+  ["url password", /\b([a-z][a-z0-9+.-]*:\/\/[^\s:@/]*:)(?!\[redacted)(?!\d+(?:[/?#\s]|$))[^\s@]+(@)/gi, "$1[redacted: url password]$2"],
+  ["authorization", /\b(authorization["']?\s*[:=]\s*["']?(?:basic|bearer|token|digest)\s+)(?!\[redacted)[^\s"',;]+/gi, "$1[redacted: authorization]"],
+  ["secret", new RegExp(String.raw`\b(${NAME}${SEP})(["'])(?!\[redacted)${PLACEHOLDER}(?:(?!\2)[^\\\n]|\\.)*\2`, "gi"), "$1$2[redacted: secret]$2"],
+  ["secret", new RegExp(String.raw`\b(${NAME}${SEP})(?!["'\[])${PLACEHOLDER}(?=[^\s"'&;,<>]*[A-Za-z0-9])[^\s"'&;,<>]+`, "gi"), "$1[redacted: secret]"],
+]
+
 /** The kind of literal credential in a text, or undefined. */
 export function credentialFinding(text: string): string | undefined {
   for (const [kind, pattern] of CREDENTIALS) if (pattern.test(text)) return kind
@@ -22,7 +54,7 @@ export function credentialFinding(text: string): string | undefined {
 }
 
 /**
- * (REC-01) Replaces every literal credential in a text with `[redacted: <kind>]` (the CREDENTIALS table, applied
+ * (REC-01) Replaces every literal credential (CREDENTIALS, then the CONTEXTUAL secrets: names kept, values replaced) in a text with `[redacted: <kind>]` (the CREDENTIALS table, applied
  * globally) and lists the kinds removed, each once, in table order. Voice recordings scrub every text field with it.
  */
 export function redactCredentials(text: string): { text: string; kinds: string[] } {
@@ -34,5 +66,10 @@ export function redactCredentials(text: string): { text: string; kinds: string[]
     if (next !== out && !kinds.includes(kind)) kinds.push(kind)
     out = next
   }
+  for (const [kind, pattern, replacement] of CONTEXTUAL) {
+    const next = out.replace(pattern, replacement)
+    if (next !== out && !kinds.includes(kind)) kinds.push(kind)
+    out = next
+  }
   return { text: out, kinds }
 }

package/packages/protocol/src/index.ts

@@ -34,6 +34,7 @@ export * from "./hub-workspace.ts"
 export * from "./concierge.ts"
 export * from "./profiles.ts"
 export * from "./artifacts.ts"
+export * from "./context-cards.ts"
 export * from "./embedded-media.ts"
 export * from "./media.ts"
 export * from "./media-allowlist.ts"
@@ -41,6 +42,7 @@ export * from "./preview-bundle.ts"
 export * from "./teams.ts"
 export * from "./graph.ts"
 export * from "./voice-recording.ts"
+export * from "./app-front.ts"
 export { HUB_URL_MAX_CHARS, isHubURL, MAX_FRAME, MAX_RETRY_AFTER_MS }
 
 export const PROTOCOL_VERSION = 1
@@ -84,7 +86,9 @@ export interface ModelSelection {
 }
 
 export interface SessionModelPrefs {
+  /** The voice front's model for this session. */
   readonly voice?: ModelSelection
+  /** Obsolete (the removed voice agent's worker model): older hubs and spokes still send it; it is ignored. */
   readonly worker?: ModelSelection
 }
 
@@ -323,11 +327,16 @@ export const FORWARDED_EVENTS: ReadonlySet<string> = new Set([
 export const INBOX_ORIGINS = ["user", "hub"] as const
 export type InboxOrigin = (typeof INBOX_ORIGINS)[number]
 
-/** `session.inbox.delivered` data as forwarded. `origin` is optional: older spokes do not send it. */
+/**
+ * `session.inbox.delivered` data as forwarded. `origin` is optional: older spokes do not send it. `carried` (feature
+ * "inboxCarried"): a user item the hub carried itself (a console turn or steer, a Voice utterance, a launch's prompt),
+ * never a prompt typed in the terminal.
+ */
 export interface InboxDeliveredData {
   readonly sessionID: string
   readonly inboxID: string
   readonly origin?: InboxOrigin
+  readonly carried?: true
 }
 
 /**
@@ -466,8 +475,13 @@ export const IMPLIED_OPENCODE_FEATURES = [
  * carry media refs (user files' `ref`, tool and assistant rows' `media`).
  * "previewBundle": it answers previewBundle (preview-bundle.ts): a local HTML page an assistant message names and the
  * files it refers to, under the media path policy, paged under the frame limit.
+ * "conciergeFront" (voice front P2): it puts a voice front in front of a locked (Concierge) session when the hub asks
+ * with `front`, serves frontUpdate, and takes the session-context part "frontBoard" (the front's compact board).
+ * "inboxCarried": its session.inbox.delivered marks a user item the hub carried (`carried: true`), so every other
+ * user item is a prompt typed in the terminal. Spokes of harnesses that report the hub's prompts as origin "hub"
+ * need not announce it.
  */
-const OPTIONAL_SPOKE_FEATURES = [...IMPLIED_OPENCODE_FEATURES, "autoName", "sessionTokens", "deliver", "hubPrompt", "permissionMessage", "actTokens", "launch", "fork", "revert", "dismissError", "timelineMedia", PREVIEW_BUNDLE_FEATURE, "voiceFront"] as const
+const OPTIONAL_SPOKE_FEATURES = [...IMPLIED_OPENCODE_FEATURES, "autoName", "sessionTokens", "deliver", "hubPrompt", "permissionMessage", "actTokens", "launch", "fork", "revert", "dismissError", "timelineMedia", PREVIEW_BUNDLE_FEATURE, "voiceFront", "conciergeFront", "inboxCarried"] as const
 
 /**
  * The core ops. An OpenCode spoke serves them all without announcing them; a spoke of another harness announces
@@ -503,11 +517,12 @@ export const SPOKE_FEATURES: readonly SpokeFeature[] = [...OPTIONAL_SPOKE_FEATUR
  * "pendingReplay": the hub takes a re-announced permission.asked / form.created (after a spoke reconnects) without
  * notifying again, and honours `unlisted: true` on form.cancelled / permission.replied (only that process stops
  * holding it). Spokes re-send permissions the hub was told already only to a hub that announces it.
+ * "frontRelay" (voice front P2): it serves the spoke request relayToSession (a Concierge front's relay_to_session).
  */
-export const KNOWN_HUB_FEATURES = ["harness", "messaging", "nodes", "launches", "pendingReplay"] as const
+export const KNOWN_HUB_FEATURES = ["harness", "messaging", "nodes", "launches", "pendingReplay", "frontRelay"] as const
 export type HubFeature = (typeof KNOWN_HUB_FEATURES)[number]
 /** What this hub announces ("launches": the /api/agent/launches routes). */
-export const HUB_FEATURES: readonly HubFeature[] = ["harness", "messaging", "nodes", "launches", "pendingReplay"]
+export const HUB_FEATURES: readonly HubFeature[] = ["harness", "messaging", "nodes", "launches", "pendingReplay", "frontRelay"]
 
 /** A spoke's harness, version and evidence level; a hello without `harness` is an OpenCode native spoke. */
 export function helloHarness(hello: Hello): { readonly harness: string; readonly harnessVersion: string; readonly evidence: EvidenceLevel | "unknown" } {
@@ -548,6 +563,21 @@ export type SpokeRequest =
   /** A one-time sign-in link to a session's page, or to the home page without a session. */
   /** `voice`: land on the session with Voice mode starting (`?voice=1`). */
   | { readonly op: "openLink"; readonly sessionID?: string; readonly voice?: boolean }
+  /**
+   * (hub feature "frontRelay", voice front P2) A Concierge front's relay_to_session: the user's spoken request, as a
+   * message to `session` (@name or session ID), one of the user's own sessions. The hub checks the front, the
+   * utterance it answers and the target; a refusal is ok:false with the reason the front reads. The hub delivers the
+   * user's own words (its record of the utterance), never `text`: `text` is the front's short note, sent along only
+   * when every content word in it is one the user said. `previous` (a redirect, "no, the other one"): the user's
+   * utterance before this one goes first. `confirm` (guard tuning): one retry after the hub's soft refusal of a question
+   * with a work verb, for the same utterance and session.
+   */
+  | { readonly op: "relayToSession"; readonly frontID: string; readonly session: string; readonly text: string; readonly previous?: boolean; readonly confirm?: boolean }
+
+/** The longest relay text (as an utterance). */
+export const RELAY_TEXT_MAX = 4000
+/** The longest front update text. */
+export const FRONT_UPDATE_MAX = 8000
 
 // ---------- server → spoke ----------
 
@@ -659,17 +689,16 @@ export type ServerRequest =
   /** One changed file's patch in the session's directory. */
   | { readonly op: "diff"; readonly sessionID: string; readonly file: string }
   /**
-   * Switch the session to the voice orchestrator agent (on) or back to its previous agent (off). `front` (feature
-   * "voiceFront", sent only to spokes that list it): leave the session's agent and model untouched and put a hidden
-   * voice-front session in front of it instead (docs/plans/2026-11-06-voice-front-p1-contract.md).
-   */
-  /**
-   * `front` (feature "voiceFront"): put a hidden voice front in front of the session. `frontID`: the front the hub
-   * knows for it (a resend to a restarted spoke): re-linked if it still exists, instead of creating another.
+   * Conversation (Voice) mode on or off. The session's agent and model are never switched (older spokes switched it
+   * to a "voice" agent). `front` (feature "voiceFront", sent only to spokes that list it): put a hidden voice front in
+   * front of the session (docs/plans/2026-11-06-voice-front-p1-contract.md); without it, or when no front can be made,
+   * the hub talks to the session itself and its turns are voice-styled. `frontID`: the front the hub knows for it (a
+   * resend to a restarted spoke): re-linked if it still exists, instead of creating another.
    */
   | { readonly op: "conversation"; readonly sessionID: string; readonly on: boolean; readonly front?: boolean; readonly frontID?: string }
   | { readonly op: "models"; readonly sessionID: string }
   | { readonly op: "modelPrefs"; readonly sessionID: string }
+  /** `worker` is obsolete: older hubs send it, current spokes ignore it. */
   | { readonly op: "setModelPrefs"; readonly sessionID: string; readonly voice?: ModelSelection | null; readonly worker?: ModelSelection | null }
   | { readonly op: "timeline"; readonly sessionID: string; readonly limit?: number; readonly cursor?: string; readonly order?: "asc" | "desc"; readonly before?: string }
   | { readonly op: "timelinePart"; readonly sessionID: string; readonly messageID: string; readonly partID: string }
@@ -750,6 +779,11 @@ export type ServerRequest =
   | { readonly op: "removeFront"; readonly sessionID: string }
   /** Forget the session's last run failure: the user dismissed it (feature "dismissError"). */
   | { readonly op: "dismissError"; readonly sessionID: string }
+  /**
+   * (feature "conciergeFront", voice front P2) An update for the voice front of `sessionID` (the Concierge session)
+   * about a session it relayed to: queued as its next wake. `finished`: a successful turn end.
+   */
+  | { readonly op: "frontUpdate"; readonly sessionID: string; readonly text: string; readonly finished?: boolean }
 
 /**
  * The feature a spoke must serve (spokeFeatures) for the hub to send `op`: the op itself for a core op (CORE_OPS,
@@ -765,6 +799,8 @@ export function featureForOp(op: ServerRequest["op"]): SpokeFeature {
       return "revert"
     case "removeFront":
       return "voiceFront"
+    case "frontUpdate":
+      return "conciergeFront"
     default:
       return op
   }
@@ -831,10 +867,23 @@ export interface FilePatch extends ChangedFile {
 }
 
 /** Right-rail data for a session; each part is absent when OpenCode could not provide it. */
+/**
+ * The model a session runs on, as its spoke knows it (the console's model chip). Voice never changes it: the voice
+ * front is a separate session. `name` from the model catalog; `variant` only when explicit. `source`: `chosen`, the
+ * model selected for the session; `reply`, nothing selected, the model its latest reply ran on (the default resolved);
+ * `default`, nothing selected and no reply yet, the default model.
+ */
+export interface SessionModel extends ModelSelection {
+  readonly name?: string
+  readonly source: "chosen" | "reply" | "default"
+}
+
 export interface SessionSummary {
   readonly directory: string
   readonly branch?: string
   readonly context?: ContextUsage
+  /** The model the session runs on (absent when nothing is known, or from older spokes). */
+  readonly model?: SessionModel
   readonly mcp?: readonly McpStatus[]
   readonly changes?: SessionChanges
 }
@@ -896,6 +945,10 @@ export interface ResultFor {
   /** `dismissed`: the spoke had a failure of the session to forget. */
   dismissError: { readonly dismissed: boolean }
   removeFront: { readonly removed: boolean }
+  /** `queued`: false when the session has no linked front in this process. */
+  frontUpdate: { readonly queued: boolean }
+  /** The session the relay reached, its title, and how: steered into its running turn, or a new turn. */
+  relayToSession: { readonly sessionID: string; readonly title?: string; readonly mode: "steer" | "turn" }
 }
 
 // ---------- both directions ----------
@@ -1120,6 +1173,9 @@ function isSpokeRequest(v: unknown): v is SpokeRequest {
   if (v.op === "pairCode") return true
   if (v.op === "handoff") return nonEmpty(v.sessionID)
   if (v.op === "openLink") return (v.sessionID === undefined || nonEmpty(v.sessionID)) && (v.voice === undefined || typeof v.voice === "boolean")
+  if (v.op === "relayToSession") {
+    return nonEmpty(v.frontID) && v.frontID.length <= 300 && nonEmpty(v.session) && v.session.length <= 300 && str(v.text) && v.text.trim().length > 0 && v.text.length <= RELAY_TEXT_MAX && (v.previous === undefined || typeof v.previous === "boolean") && (v.confirm === undefined || typeof v.confirm === "boolean")
+  }
   return false
 }
 
@@ -1272,6 +1328,8 @@ function isServerRequest(v: unknown): v is ServerRequest {
     case "dismissError":
     case "removeFront":
       return nonEmpty(v.sessionID)
+    case "frontUpdate":
+      return nonEmpty(v.sessionID) && str(v.text) && v.text.trim().length > 0 && v.text.length <= FRONT_UPDATE_MAX && (v.finished === undefined || typeof v.finished === "boolean")
     default:
       return false
   }