@huynle/hub 0.8.1 → 0.8.3

package/packages/cli/src/team-intake-mcp.ts

@@ -5,6 +5,7 @@
 // sessions submit under team policy and, in the team's entry role, report status.
 import { sanitizeText } from "../../sdk/src/envelope.ts"
 import { reportIntakeStatus, TEAM_INTAKE_STATUS_INPUTS, type TeamIntake, type TeamIntakeApi, type TeamIntakePriority, type TeamIntakeStatus, type TeamIntakeStatusInput } from "../../sdk/src/team-intake.ts"
+import { ToolArgError } from "./tool-args"
 
 type Args = Record<string, unknown>
 
@@ -29,24 +30,24 @@ const UPDATES: readonly TeamIntakeStatusInput[] = TEAM_INTAKE_STATUS_INPUTS
 
 const need = (args: Args, key: string): string => {
   const value = args[key]
-  if (typeof value !== "string" || !value.trim()) throw new Error(`"${key}" is required (a non-empty string)`)
+  if (typeof value !== "string" || !value.trim()) throw new ToolArgError(`"${key}" is required (a non-empty string)`)
   return value
 }
 const optional = (args: Args, key: string): string | undefined => {
   const value = args[key]
   if (value === undefined || value === null) return undefined
-  if (typeof value !== "string") throw new Error(`"${key}" must be a string`)
+  if (typeof value !== "string") throw new ToolArgError(`"${key}" must be a string`)
   return value.trim() ? value : undefined
 }
 const strings = (args: Args, key: string): string[] | undefined => {
   const value = args[key]
   if (value === undefined || value === null) return undefined
-  if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) throw new Error(`"${key}" must be a list of strings`)
+  if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) throw new ToolArgError(`"${key}" must be a list of strings`)
   return value
 }
 const oneOf = <T extends string>(args: Args, key: string, allowed: readonly T[]): T | undefined => {
   const value = optional(args, key)
-  if (value !== undefined && !allowed.includes(value as T)) throw new Error(`"${key}" must be one of ${allowed.join(", ")}`)
+  if (value !== undefined && !allowed.includes(value as T)) throw new ToolArgError(`"${key}" must be one of ${allowed.join(", ")}`)
   return value as T | undefined
 }
 
@@ -55,7 +56,7 @@ function dueOf(args: Args): number | undefined {
   const value = args.due
   if (value === undefined || value === null || value === "") return undefined
   const ms = typeof value === "number" ? value : typeof value === "string" ? Date.parse(value) : Number.NaN
-  if (!Number.isSafeInteger(ms) || ms <= 0) throw new Error(`"due" must be an ISO date/time or epoch milliseconds`)
+  if (!Number.isSafeInteger(ms) || ms <= 0) throw new ToolArgError(`"due" must be an ISO date/time or epoch milliseconds`)
   return ms
 }
 
@@ -146,10 +147,10 @@ export const teamIntakeTools: readonly TeamIntakeTool[] = [
     idempotent: true,
     run: async (hub, args, signal) => {
       const status = oneOf(args, "status", UPDATES)
-      if (!status) throw new Error(`"status" is required: one of ${UPDATES.join(", ")}`)
+      if (!status) throw new ToolArgError(`"status" is required: one of ${UPDATES.join(", ")}`)
       const expectedRevision = args.expectedRevision
       if (expectedRevision !== undefined && expectedRevision !== null && (typeof expectedRevision !== "number" || !Number.isSafeInteger(expectedRevision) || expectedRevision < 0))
-        throw new Error(`"expectedRevision" must be the revision you read (or left out)`)
+        throw new ToolArgError(`"expectedRevision" must be the revision you read (or left out)`)
       const reason = optional(args, "reason")
       const { intake, assignment } = await reportIntakeStatus(hub.teams, need(args, "team"), need(args, "intake"), { status, ...(typeof expectedRevision === "number" ? { expectedRevision } : {}), ...(reason ? { reason } : {}) }, { signal })
       return `${intake.id} is ${intake.status}${intake.progress ? ` (${intake.progress})` : ""}, revision ${intake.revision}${assignment ? `; assignment ${assignment.id} ${assignment.status}` : ""}`

package/packages/cli/src/teams-mcp.ts

@@ -10,6 +10,7 @@
 // the default destructiveHint. Changes of existing records send expectedRevision, so repeating one is idempotent.
 // Decision answers and grant administration stay console-only: there is no tool for them here.
 import { sanitizeText } from "../../sdk/src/envelope.ts"
+import { ToolArgError } from "./tool-args"
 import type { LaunchSpec } from "../../sdk/src/types.ts"
 import type { Team, TeamDraft, TeamEdge, TeamPatch, TeamRole, TeamRoster, Teams, TeamSpec } from "../../sdk/src/teams.ts"
 
@@ -116,7 +117,7 @@ const LAUNCH = {
 } as const
 const SCOPES = "App tokens need scope teams:read (reads) or teams:manage (changes); seats, status and staffing also need sessions:read. Session tokens read only teams they are seated in and never change definitions. Team roles confer no authority."
 
-class ArgError extends Error {}
+const ArgError = ToolArgError
 
 const need = (args: Args, key: string): string => {
   const value = args[key]

package/packages/cli/src/tool-args.ts

@@ -0,0 +1,6 @@
+// (R-04) The one error class for a bad MCP tool argument. Every tool family (mcp.ts, teams-mcp.ts,
+// team-intake-mcp.ts, artifacts-mcp.ts, artifact-jobs-mcp.ts, profiles-mcp.ts, watchlist.ts) throws it, and mcp.ts
+// answers it as `invalid: …` (an isError result), never `<tool> failed: …`.
+
+/** A bad tool argument: mcp.ts answers it as `invalid: <message>`. */
+export class ToolArgError extends Error {}

package/packages/cli/src/watchlist.ts

@@ -4,6 +4,7 @@
 // act token (show and the verbs). Other session tokens get not found (exit 3).
 import { sanitizeLabel } from "../../sdk/src/envelope.ts"
 import type { Concierge, WatchlistChanged, WatchlistConfig, WatchlistUpdate, WatchlistView } from "../../sdk/src/index.ts"
+import { ToolArgError } from "./tool-args"
 
 type Args = Record<string, unknown>
 
@@ -52,13 +53,13 @@ const STRINGS = { type: "array", items: { type: "string" } } as const
 
 const need = (args: Args, key: string): string => {
   const value = args[key]
-  if (typeof value !== "string" || !value.trim()) throw new Error(`"${key}" is required (a non-empty string)`)
+  if (typeof value !== "string" || !value.trim()) throw new ToolArgError(`"${key}" is required (a non-empty string)`)
   return value
 }
 const flag = (args: Args, key: string, fallback: boolean): boolean => {
   const value = args[key]
   if (value === undefined || value === null) return fallback
-  if (typeof value !== "boolean") throw new Error(`"${key}" must be true or false`)
+  if (typeof value !== "boolean") throw new ToolArgError(`"${key}" must be true or false`)
   return value
 }
 
@@ -92,9 +93,9 @@ export const watchlistTools: readonly WatchlistTool[] = [
     organizes: true,
     run: async (hub, args, signal) => {
       const expected = args.expectedRevision
-      if (typeof expected !== "number" || !Number.isSafeInteger(expected) || expected < 0) throw new Error(`"expectedRevision" is required (the revision you read)`)
+      if (typeof expected !== "number" || !Number.isSafeInteger(expected) || expected < 0) throw new ToolArgError(`"expectedRevision" is required (the revision you read)`)
       const unknown = Object.keys(args).filter((k) => k !== "expectedRevision" && !(UPDATE_FIELDS as readonly string[]).includes(k))
-      if (unknown.length) throw new Error(`Unknown argument${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${safe(k).slice(0, 40)}"`).join(", ")}: use ${UPDATE_FIELDS.join(", ")} and expectedRevision`)
+      if (unknown.length) throw new ToolArgError(`Unknown argument${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${safe(k).slice(0, 40)}"`).join(", ")}: use ${UPDATE_FIELDS.join(", ")} and expectedRevision`)
       const patch: Record<string, unknown> = {}
       for (const field of UPDATE_FIELDS) if (args[field] !== undefined && args[field] !== null) patch[field] = args[field]
       const r = await hub.concierge.watchlist.update(patch as WatchlistUpdate, expected, { signal })

package/packages/codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-codex",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "private": true,
   "description": "The Codex app-server spoke: attaches to Codex's app-server (its own over stdio, and the shared daemon's socket when present), and the `hub codex` wrapper (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-node",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "private": true,
   "description": "`hub node`: the per-machine daemon that prepares, collects and cleans up launch workspaces (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/preset/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-preset",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "private": true,
   "description": "The preset spoke: drives a harness without a spoke of its own through a terminal pane (tmux), described by a data-only preset; official presets in presets/ (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-protocol",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "private": true,
   "description": "Hub ↔ spoke wire protocol (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/src/concierge.ts

@@ -98,7 +98,10 @@ export const CONCIERGE_LIMITS = {
 
 // ---- Session context (CON-04, spoke feature "sessionContext") ----
 
-/** The keys of the parts a session context carries, appended to the session's system prompt in this order. */
+/**
+ * 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).
+ */
 export const SESSION_CONTEXT_KEYS = ["instructions", "board", "notes"] as const
 export type SessionContextKey = (typeof SESSION_CONTEXT_KEYS)[number]
 

package/packages/protocol/src/embedded-media.ts

@@ -0,0 +1,59 @@
+/**
+ * (M1) Embedded media in tool-call details. Harnesses keep tool screenshots inside the tool output: OpenCode 2.2.3 as
+ * `data:` URLs (`read` of a PNG, MCP image results), MCP and Claude Code as raw base64 image parts. A tool-call
+ * detail shows none of these bytes: each is replaced by a short placeholder naming its type and approximate size,
+ * e.g. "[image/png, 1.2 MB — not shown]", so the rest of the detail (input, text output) fits the detail limit and
+ * no image bytes travel to the console. Inline media display is a separate, later feature.
+ */
+
+/** A base64 `data:` URL: optional mime, optional parameters, then the payload. */
+const DATA_URL = /data:([\w.+-]+\/[\w.+-]+)?((?:;[\w.+-]+=[^;,\s"'<>]*)*);base64,([A-Za-z0-9+/_-]+={0,2})/gi
+const BASE64 = /^[A-Za-z0-9+/_-]+={0,2}$/
+const MIME_KEYS = ["mime", "mimeType", "media_type", "mediaType"] as const
+
+/** The approximate decoded size of `length` base64 characters, for people ("10 B", "900 KB", "1.2 MB"). */
+function sizeOf(base64: string): string {
+  const padding = base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0
+  const bytes = Math.max(0, Math.floor((base64.length * 3) / 4) - padding)
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+/** The placeholder shown instead of embedded bytes. */
+export function mediaPlaceholder(mime: string | undefined, base64: string): string {
+  return `[${mime || "data"}, ${sizeOf(base64)} — not shown]`
+}
+
+function redactText(text: string): string {
+  if (!text.includes("base64,")) return text
+  return text.replace(DATA_URL, (_match, mime: string | undefined, _params: string, data: string) => mediaPlaceholder(mime?.toLowerCase(), data))
+}
+
+/** The mime of an object that carries raw base64 image bytes in `data`, else undefined. */
+function rawImageMime(object: Record<string, unknown>): string | undefined {
+  if (typeof object.data !== "string" || !BASE64.test(object.data)) return undefined
+  const mime = MIME_KEYS.map((key) => object[key]).find((value): value is string => typeof value === "string")
+  if (mime?.toLowerCase().startsWith("image/")) return mime.toLowerCase()
+  if (object.type === "image" || object.type === "base64") return mime || "image"
+  return undefined
+}
+
+/**
+ * A copy of `value` (JSON-like) with every embedded base64 payload replaced by a placeholder: `data:…;base64,…` URLs
+ * in any string, and raw base64 `data` of image parts. Everything else is kept as it is; `value` is not changed.
+ */
+export function redactEmbeddedMedia<T>(value: T): T {
+  return redact(value) as T
+}
+
+function redact(value: unknown): unknown {
+  if (typeof value === "string") return redactText(value)
+  if (Array.isArray(value)) return value.map(redact)
+  if (!value || typeof value !== "object") return value
+  const object = value as Record<string, unknown>
+  const mime = rawImageMime(object)
+  const out: Record<string, unknown> = {}
+  for (const [key, item] of Object.entries(object)) out[key] = key === "data" && mime ? mediaPlaceholder(mime, item as string) : redact(item)
+  return out
+}

package/packages/protocol/src/index.ts

@@ -31,8 +31,10 @@ export * from "./hub-workspace.ts"
 export * from "./concierge.ts"
 export * from "./profiles.ts"
 export * from "./artifacts.ts"
+export * from "./embedded-media.ts"
 export * from "./teams.ts"
 export * from "./graph.ts"
+export * from "./voice-recording.ts"
 export { HUB_URL_MAX_CHARS, isHubURL, MAX_FRAME, MAX_RETRY_AFTER_MS }
 
 export const PROTOCOL_VERSION = 1
@@ -93,7 +95,8 @@ export interface AvailableModel {
  * A timeline page. Forward mode (`cursor`): oldest rows first, `cursor` for the next newer page. Newest-first
  * mode (`order: "desc"` or `before`): the newest rows (before `before`) in chronological order, `older` for the
  * page before them. Both cursors are opaque. Items are the spoke's rows (src/spoke/timeline.ts TimelineItem); newer
- * spokes add optional `pos` (ordering position), `callID`, `childSessionID`, `title` and `ordinal`.
+ * spokes add optional `pos` (ordering position), `callID`, `childSessionID`, `title`, `ordinal` and, on error rows,
+ * `declined` (a denied permission stopped the turn).
  */
 export interface TimelinePage {
   readonly items: readonly unknown[]
@@ -154,6 +157,14 @@ export interface SessionInfo {
    * Older hubs ignore it.
    */
   readonly revert?: SessionRevertInfo
+  /**
+   * The latest revert committed in this session as this process saw it (feature "revert"): the history from
+   * `messageID` on was removed. Hub message rows (agent messages the session sent or got) from `from` (the reverted
+   * message's time, when known) until `until` (when the revert was staged; later ones were held for after it) belonged
+   * to that history: the hub keeps the window and leaves them out. `at` (commit time) changes with every commit.
+   * Older hubs ignore it.
+   */
+  readonly revertCommitted?: RevertCommitted
   /**
    * (CON-04, feature "sessionContext") Sessions the hub gave a locked context (the Concierge): the agent the spoke
    * last saw the session run on, and the context revision it holds now (absent: none, e.g. after a restart). The hub
@@ -192,6 +203,21 @@ export interface SessionRevertInfo {
   /** Restored files (at most REVERT_FILES_MAX). */
   readonly files: readonly RevertFile[]
   readonly filesTotal: number
+  /** When this process saw it staged (epoch ms; optional, older spokes send none). */
+  readonly stagedAt?: number
+}
+
+/** A committed revert's removed window (SessionInfo.revertCommitted). */
+export interface RevertCommitted {
+  readonly messageID: string
+  readonly from?: number
+  readonly until: number
+  readonly at: number
+}
+
+/** A committed revert's window as a spoke reports it. */
+export function isRevertCommitted(v: unknown): v is RevertCommitted {
+  return isObj(v) && nonEmpty(v.messageID) && v.messageID.length <= 300 && (v.from === undefined || num(v.from)) && num(v.until) && num(v.at)
 }
 
 /** An attachment of a user message, by its position in the message's files (fetched through timelineFile). */
@@ -421,8 +447,10 @@ export const IMPLIED_OPENCODE_FEATURES = [
  * a revert of a session from one of its user messages (revertPreview, revert, revertRestore, revertCommit ops) and
  * reports a staged one as SessionInfo.revert. Announced only when the spoke's harness can (OpenCode: a process that
  * reaches its own server).
+ * "dismissError": it forgets a session's last run failure when the user dismisses it (dismissError op), so a
+ * reconnect does not seed it again.
  */
-const OPTIONAL_SPOKE_FEATURES = [...IMPLIED_OPENCODE_FEATURES, "autoName", "sessionTokens", "deliver", "hubPrompt", "permissionMessage", "actTokens", "launch", "fork", "revert"] as const
+const OPTIONAL_SPOKE_FEATURES = [...IMPLIED_OPENCODE_FEATURES, "autoName", "sessionTokens", "deliver", "hubPrompt", "permissionMessage", "actTokens", "launch", "fork", "revert", "dismissError"] as const
 
 /**
  * The core ops. An OpenCode spoke serves them all without announcing them; a spoke of another harness announces
@@ -675,6 +703,8 @@ export type ServerRequest =
   | { readonly op: "revertRestore"; readonly sessionID: string }
   /** Make a staged revert permanent: the hidden messages are removed (feature "revert"). */
   | { readonly op: "revertCommit"; readonly sessionID: string }
+  /** Forget the session's last run failure: the user dismissed it (feature "dismissError"). */
+  | { readonly op: "dismissError"; readonly sessionID: string }
 
 /**
  * The feature a spoke must serve (spokeFeatures) for the hub to send `op`: the op itself for a core op (CORE_OPS,
@@ -813,6 +843,8 @@ export interface ResultFor {
   revert: { readonly revert: SessionRevertInfo; readonly text: string; readonly attachments: readonly MessageAttachment[] }
   revertRestore: Record<string, never>
   revertCommit: Record<string, never>
+  /** `dismissed`: the spoke had a failure of the session to forget. */
+  dismissError: { readonly dismissed: boolean }
 }
 
 // ---------- both directions ----------
@@ -829,8 +861,29 @@ export interface Res {
   readonly ok: boolean
   readonly result?: unknown
   readonly error?: string
+  /**
+   * A refusal's kind, so the hub need not match `error` texts (optional and additive: older hubs ignore it, older
+   * spokes send none). See RES_ERROR_CODES; a peer may send codes the other does not know (they are ignored).
+   */
+  readonly code?: string
 }
 
+/**
+ * Refusal codes a spoke puts on `{ok: false}` answers: "busy" (the session runs, e.g. a revert while a turn is
+ * running; the hub answers 409 busy) and "not_found" (the session, or the message an op names, is not there; 404).
+ */
+export const RES_ERROR_CODES = ["busy", "not_found"] as const
+export type ResErrorCode = (typeof RES_ERROR_CODES)[number]
+/** Longest `code` a res frame carries. */
+export const RES_CODE_MAX = 40
+
+/** The spoke's refusal of a revert while the session runs (code "busy"). */
+export const REVERT_BUSY = "The session is working; wait for it to finish (or stop it) before reverting"
+/** The spoke's refusal of a restore or commit while the session runs (code "busy"). */
+export const REVERT_END_BUSY = "The session is working; wait for it to finish (or stop it) before restoring or committing the revert"
+/** A fork or revert naming a message that is not one of the session's user messages (code "not_found"). */
+export const NOT_A_USER_MESSAGE = "Not a user message of this session"
+
 export interface Bye {
   readonly t: "bye"
   readonly reason: string
@@ -915,6 +968,7 @@ function isSession(v: unknown): v is SessionInfo {
     (v.open === undefined || typeof v.open === "boolean") &&
     (v.terminal === undefined || isTerminal(v.terminal)) &&
     (v.revert === undefined || isSessionRevert(v.revert)) &&
+    (v.revertCommitted === undefined || isRevertCommitted(v.revertCommitted)) &&
     (v.agent === undefined || (nonEmpty(v.agent) && v.agent.length <= AGENT_NAME_MAX)) &&
     (v.contextRevision === undefined || (Number.isSafeInteger(v.contextRevision) && (v.contextRevision as number) >= 0)) &&
     (v.locked === undefined || v.locked === true)
@@ -948,7 +1002,8 @@ export function isSessionRevert(v: unknown): v is SessionRevertInfo {
     v.files.length <= REVERT_FILES_MAX &&
     v.files.every(isRevertFile) &&
     count(v.filesTotal) &&
-    (v.filesTotal as number) >= v.files.length
+    (v.filesTotal as number) >= v.files.length &&
+    (v.stagedAt === undefined || num(v.stagedAt))
   )
 }
 
@@ -1157,6 +1212,7 @@ function isServerRequest(v: unknown): v is ServerRequest {
       return nonEmpty(v.sessionID) && nonEmpty(v.messageID) && v.messageID.length <= 300 && typeof v.files === "boolean"
     case "revertRestore":
     case "revertCommit":
+    case "dismissError":
       return nonEmpty(v.sessionID)
     default:
       return false
@@ -1187,8 +1243,11 @@ export function parseSpokeMessage(raw: string | Buffer): SpokeMessage | undefine
         (m.launchID === undefined || (str(m.launchID) && ID.test(m.launchID)))
         ? (m as unknown as Hello)
         : undefined
-    case "sessions":
-      return Array.isArray(m.sessions) && m.sessions.every(isSession) ? (m as unknown as Sessions) : undefined
+    case "sessions": {
+      if (!Array.isArray(m.sessions)) return undefined
+      const sessions = m.sessions.map(lenientSession)
+      return sessions.every(isSession) ? ({ ...m, sessions } as unknown as Sessions) : undefined
+    }
     case "terminals":
       return m.herdr === undefined || isHerdrInfo(m.herdr) ? (m as unknown as Terminals) : undefined
     case "event":
@@ -1198,7 +1257,7 @@ export function parseSpokeMessage(raw: string | Buffer): SpokeMessage | undefine
     case "req":
       return nonEmpty(m.id) && isSpokeRequest(m.req) ? (m as unknown as Req<SpokeRequest>) : undefined
     case "res":
-      return isRes(m) ? (m as unknown as Res) : undefined
+      return isRes(m) ? lenientRes(m) : undefined
     case "bye":
       return isBye(m) ? (m as unknown as Bye) : undefined
     default:
@@ -1206,6 +1265,32 @@ export function parseSpokeMessage(raw: string | Buffer): SpokeMessage | undefine
   }
 }
 
+/** A res frame without an invalid `code` (over-long, empty or not a string): ignored, as for older peers. */
+function lenientRes(m: Record<string, unknown>): Res {
+  if (m.code === undefined || (nonEmpty(m.code) && m.code.length <= RES_CODE_MAX)) return m as unknown as Res
+  const { code: _dropped, ...rest } = m
+  return rest as unknown as Res
+}
+
+/**
+ * A reported session without malformed additive revert fields (`revertCommitted`, `revert.stagedAt`): they are
+ * dropped (older hubs ignore them too), never failing the whole sessions frame.
+ */
+function lenientSession(v: unknown): unknown {
+  if (!isObj(v)) return v
+  let out: Record<string, unknown> = v
+  if (out.revertCommitted !== undefined && !isRevertCommitted(out.revertCommitted)) {
+    const { revertCommitted: _dropped, ...rest } = out
+    out = rest
+  }
+  const revert = out.revert
+  if (isObj(revert) && revert.stagedAt !== undefined && !num(revert.stagedAt)) {
+    const { stagedAt: _dropped, ...rest } = revert
+    out = { ...out, revert: rest }
+  }
+  return out
+}
+
 /** Parses a frame received by the spoke. Returns undefined for anything invalid. */
 export function parseServerMessage(raw: string | Buffer): ServerMessage | undefined {
   const m = parse(raw)
@@ -1216,7 +1301,7 @@ export function parseServerMessage(raw: string | Buffer): ServerMessage | undefi
     case "req":
       return nonEmpty(m.id) && isServerRequest(m.req) ? (m as unknown as Req<ServerRequest>) : undefined
     case "res":
-      return isRes(m) ? (m as unknown as Res) : undefined
+      return isRes(m) ? lenientRes(m) : undefined
     case "bye":
       return isBye(m) ? (m as unknown as Bye) : undefined
     default:

package/packages/protocol/src/voice-recording.ts

@@ -0,0 +1,107 @@
+export const RECORDING_FORMAT = "hub-voice-recording" as const
+export const RECORDING_FORMAT_VERSION = 1
+export const RECORDING_AUDIO_TYPE = "audio/wav"              // 16 kHz mono PCM16, exactly as sent to STT
+export const RECORDING_PAGE_TYPE = "application/x-ndjson"    // event pages (blobs)
+export const RECORDING_MEDIA_TYPES = [RECORDING_AUDIO_TYPE, RECORDING_PAGE_TYPE] as const
+export const RECORDING_HEADER = "x-hub-recording"            // on /api/transcribe and /api/speak: the recording ID
+export const RECORDING_SEGMENT_HEADER = "x-hub-segment"      // on /api/transcribe: the segment number
+export const RECORDING_REF_HEADER = "x-hub-tts-ref"          // on /api/speak: "<messageID>:<ordinal>:<seq>:<i>"
+export const RECORDING_AUDIO_RESULT_HEADER = "x-hub-recording-audio" // transcribe answer: RecordingAudioResult
+
+export const RECORDING_LIMITS = {
+  retentionMs: 7 * 24 * 3_600_000,
+  userBytes: 500 * 1024 * 1024,         // audio + event pages, all of a user's recordings
+  recordingBytes: 150 * 1024 * 1024,    // one recording (≈ 80 min of speech)
+  segmentBytes: 2 * 1024 * 1024,        // one WAV (60.3 s at 16 kHz = 1,929,644 B)
+  segmentsPerRecording: 5_000,
+  eventsPerBatch: 200,
+  batchBytes: 256 * 1024,
+  keepaliveBatchBytes: 60 * 1024,       // fetch keepalive's 64 KiB budget, with headroom
+  eventsPerRecording: 50_000,
+  eventBytesPerRecording: 32 * 1024 * 1024,
+  recordingsStored: 200,                // per user
+  activePerUser: 4,
+  maxDurationMs: 4 * 3_600_000,         // then the hub ends it ("max_duration"); the console starts the next one
+  idleEndMs: 10 * 60_000,               // no event and conversation off: the sweep ends it ("stale")
+  sweepMs: 15 * 60_000,
+  textChars: 2_000, utteranceChars: 4_000, replyChars: 32_000, messageChars: 300,
+  consoleBufferEvents: 2_000, flushMs: 5_000, flushEvents: 100,
+  hubFlushMs: 2_000, hubFlushEvents: 100,
+} as const
+
+export interface RecordingSettings {
+  readonly enabled: boolean        // default false
+  readonly revision: number
+  readonly updatedAt?: number
+}
+
+export type RecordingKind = "voice" | "concierge"
+export type RecordingState = "active" | "ended" | "deleting"
+export type RecordingEndReason = "stopped" | "conversation_off" | "disabled" | "max_duration" | "stale" | "limit" | "superseded" | "session_deleted"
+export type RecordingAudioResult = "stored" | "skipped-cap" | "failed" | "off"
+
+export interface RecordingClient {           // sent by the console at start; all optional, bounded labels
+  readonly app?: string                      // console version
+  readonly platform?: string                 // ≤ 60 chars, e.g. "android-chrome", "ios-safari", "desktop-chrome"
+  readonly detector?: "silero" | "energy"
+  readonly sensitivity?: "low" | "normal" | "high"
+  readonly cues?: boolean
+  readonly background?: boolean
+  readonly streaming?: boolean               // MediaSource playback
+  readonly timings?: Readonly<Record<string, number>> // VOICE_TIMINGS at start
+}
+
+export interface RecordingSummary {
+  readonly id: string                        // "rec_" + 20 base32 chars
+  readonly kind: RecordingKind
+  readonly sessionID: string
+  readonly sessionTitle?: string             // ≤ 80, at start (the user's own session)
+  readonly deviceID: string
+  readonly deviceName?: string
+  readonly state: RecordingState
+  readonly startedAt: number                 // hub epoch ms
+  readonly endedAt?: number
+  readonly endReason?: RecordingEndReason
+  readonly expiresAt: number                 // startedAt + retentionMs
+  readonly bytes: number                     // audio + pages
+  readonly segments: number                  // stored audio segments
+  readonly events: number
+  readonly audio: boolean                    // false once a cap stopped audio
+  readonly redactions: number
+}
+
+export interface RecordingUsage { readonly bytes: number; readonly recordings: number; readonly capBytes: number }
+
+export interface RecordingAnchor { readonly perf: number; readonly epoch: number } // performance.now() and Date.now() at the same moment
+
+/** Console → hub (POST …/events). `seq` from 1, gapless per recording; `t` = performance.now() (ms). */
+export interface ConsoleEvent { readonly seq: number; readonly t: number; readonly kind: ConsoleEventKind; readonly [field: string]: unknown }
+export type ConsoleEventKind =
+  | "state" | "detector" | "speech.start" | "speech.end" | "segment.closed" | "stt.sent" | "stt.received"
+  | "utterance.held" | "utterance.merged" | "utterance.sent" | "utterance.accepted" | "utterance.failed" | "utterance.command"
+  | "heard" | "say.received" | "tts.sentence.queued" | "tts.request" | "tts.first.byte" | "tts.sentence.played"
+  | "tts.sentence.ended" | "barge.in" | "cue.played" | "mic" | "control" | "turn.timing" | "decision.voice"
+  | "clock.sync" | "error"
+export type HubEventKind =
+  | "recording.started" | "recording.ended" | "conversation" | "stt.request" | "stt.result" | "tts.synth"
+  | "utterance.received" | "utterance.delivered" | "turn.started" | "first.token" | "say.sent" | "reply.full"
+  | "turn.ended" | "tool" | "interrupt" | "wake.arrived" | "concierge.tool" | "decision.opened" | "decision.answered"
+  | "cap.reached" | "error"
+
+/** As stored and exported (events.jsonl). */
+export interface RecordingEvent {
+  readonly v: 1
+  readonly src: "console" | "hub"
+  readonly kind: ConsoleEventKind | HubEventKind
+  readonly seq?: number          // console events
+  readonly id?: string           // hub events: "<podTag>.<n>", unique per recording
+  readonly t?: number            // console: page clock (performance.now ms)
+  readonly at?: number           // hub: hub epoch ms (also on console events: when the hub received the batch)
+  readonly ts?: number           // export only: aligned hub-epoch ms (see Clocks)
+  readonly redacted?: readonly string[] // credential kinds removed from this event's text
+  readonly truncated?: true
+  readonly [field: string]: unknown
+}
+
+/** A spoken sentence's identity: its say and its index among splitSentences(say.text). */
+export interface TtsRef { readonly messageID: string; readonly ordinal: number; readonly seq?: number; readonly i: number }

package/packages/protocol/src/wire.ts

@@ -17,6 +17,7 @@ export const featureList = (v: unknown): v is string[] => Array.isArray(v) && v.
 /** Control (C0, C1), format (bidi, zero-width, BOM) and line/paragraph separator characters. */
 export const UNSAFE_CHARS = /[\p{Cc}\p{Cf}\u2028\u2029]/u
 
+/** A res frame (an optional `code` is not checked here: an invalid one is dropped, never fatal; see parse). */
 export const isResFrame = (v: Record<string, unknown>): boolean => nonEmpty(v.id) && typeof v.ok === "boolean" && (v.error === undefined || str(v.error))
 /** Longest reconnect delay a bye's retryAfterMs may ask for (5 minutes). */
 export const MAX_RETRY_AFTER_MS = 300_000

package/packages/runtime-openshell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-openshell",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "private": true,
   "description": "The `openshell` runtime of `hub node`: launches in NVIDIA OpenShell sandboxes, driven through the openshell CLI (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/runtime-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-sdk",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "private": true,
   "description": "The Runtime interface `hub node` runtimes implement (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-sdk",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "private": true,
   "description": "Typed client for the hub's /api/agent (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/sdk/src/client.ts

@@ -320,6 +320,8 @@ export interface ActOptions extends CallOptions {
 export interface ApproveOptions extends ActOptions {
   /** Approve for good (OpenCode saves the rule); agents need a grant with allowAlways. */
   readonly always?: boolean
+  /** (R-03) The Concierge advises approving: only then does its escalation Decision recommend approve. */
+  readonly recommend?: boolean
 }
 
 export interface PromptOptions extends ActOptions {
@@ -688,7 +690,7 @@ export class HubClient {
 
   /** Approves a pending permission request in a session's tree. */
   approve(addr: string, requestID: string, options: ApproveOptions = {}): Promise<Approved> {
-    const body = { requestID, ...(options.always ? { always: true } : {}), ...whyField(options) }
+    const body = { requestID, ...(options.always ? { always: true } : {}), ...(options.recommend ? { recommend: true } : {}), ...whyField(options) }
     return this.call("POST", `${AGENT}/sessions/${segment(addr)}/approve`, { body, ...signalOf(options) })
   }
 

package/packages/spoke-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-spoke-sdk",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "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/connection.ts

@@ -11,6 +11,7 @@ import {
   type ServerRequest,
   type SpokeMessage,
   type SpokeRequest,
+  type ResErrorCode,
   type Welcome,
 } from "../../protocol/src/index.ts"
 
@@ -67,6 +68,17 @@ const defaultSocket = (url: string, headers: Record<string, string>): SocketLike
 
 const message = (cause: unknown) => (cause instanceof Error ? cause.message : String(cause))
 
+/** An op's refusal with a protocol code (Res.code, RES_ERROR_CODES): the hub maps it without matching the text. */
+export class CodedError extends Error {
+  constructor(
+    message: string,
+    readonly code: ResErrorCode,
+  ) {
+    super(message)
+    this.name = "CodedError"
+  }
+}
+
 interface Pending {
   resolve: (value: unknown) => void
   reject: (error: Error) => void
@@ -245,7 +257,7 @@ export class SpokeConnection {
     try {
       reply = { t: "res", id, ok: true, result: await this.options.handle(req) }
     } catch (cause) {
-      reply = { t: "res", id, ok: false, error: message(cause) }
+      reply = { t: "res", id, ok: false, error: message(cause), ...(cause instanceof CodedError ? { code: cause.code } : {}) }
     }
     this.send(reply)
   }