@huynle/hub 0.8.1 → 0.8.2

package/packages/cli/src/artifact-jobs-mcp.ts

@@ -7,6 +7,7 @@
 // (+ artifacts:read) for an app token. Content never travels in requests or job listings, only in the context.
 import type { ArtifactJob, ArtifactJobContext, ArtifactJobKind, ArtifactJobRequest } from "../../sdk/src/artifact-jobs.ts"
 import type { Artifacts } from "../../sdk/src/artifacts.ts"
+import { ToolArgError } from "./tool-args"
 
 /** UTF-8 bytes of the inline proposal text one tool call may carry. */
 export const MCP_JOB_TEXT_BYTES = 256 * 1024
@@ -33,27 +34,27 @@ const KINDS: readonly ArtifactJobKind[] = ["ask", "propose-edit", "run-action"]
 
 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 integer = (args: Args, key: string): number => {
   const value = args[key]
-  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`"${key}" is required (a whole number)`)
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new ToolArgError(`"${key}" is required (a whole number)`)
   return value
 }
 
 function handlerOf(args: Args): ArtifactJobRequest["handler"] {
   const session = optional(args, "session")
   const machine = optional(args, "machine")
-  if (session && machine) throw new Error('give either "session" (an existing session) or "machine" + "repo" (a new handler session), not both')
+  if (session && machine) throw new ToolArgError('give either "session" (an existing session) or "machine" + "repo" (a new handler session), not both')
   if (session) return { session }
-  if (!machine) throw new Error('"machine" and "repo" are required to launch a handler session (or name an existing one with "session")')
+  if (!machine) throw new ToolArgError('"machine" and "repo" are required to launch a handler session (or name an existing one with "session")')
   const repo = need(args, "repo")
   const harness = optional(args, "harness")
   const model = optional(args, "model")
@@ -114,7 +115,7 @@ export const artifactJobTools: readonly ArtifactJobTool[] = [
     readOnly: false,
     run: async (hub, args, signal) => {
       const kind = optional(args, "kind") as ArtifactJobKind | undefined
-      if (kind && !KINDS.includes(kind)) throw new Error(`"kind" must be one of ${KINDS.join(", ")}`)
+      if (kind && !KINDS.includes(kind)) throw new ToolArgError(`"kind" must be one of ${KINDS.join(", ")}`)
       const action = optional(args, "action")
       const apply = optional(args, "apply") as "manual" | "auto" | undefined
       const key = optional(args, "key")
@@ -181,10 +182,10 @@ export const artifactJobTools: readonly ArtifactJobTool[] = [
       const error = optional(args, "error")
       const answer = optional(args, "answer")
       const text = args.text
-      if (text !== undefined && typeof text !== "string") throw new Error('"text" must be a string')
-      if (typeof text === "string" && Buffer.byteLength(text, "utf8") > MCP_JOB_TEXT_BYTES) throw new Error(`"text" is larger than ${MCP_JOB_TEXT_BYTES} bytes`)
+      if (text !== undefined && typeof text !== "string") throw new ToolArgError('"text" must be a string')
+      if (typeof text === "string" && Buffer.byteLength(text, "utf8") > MCP_JOB_TEXT_BYTES) throw new ToolArgError(`"text" is larger than ${MCP_JOB_TEXT_BYTES} bytes`)
       const keep = args.keep
-      if (keep !== undefined && (!Array.isArray(keep) || !keep.every((k) => typeof k === "string"))) throw new Error('"keep" must be a list of paths')
+      if (keep !== undefined && (!Array.isArray(keep) || !keep.every((k) => typeof k === "string"))) throw new ToolArgError('"keep" must be a list of paths')
       const path = optional(args, "path")
       const entry = optional(args, "entry")
       const result = error

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

@@ -5,6 +5,7 @@
 // tool ever reads local files). Needs scope artifacts:read / artifacts:write for an app token; sessions create and
 // read workspace-shared artifacts only (revising stays with the user in v1).
 import type { Artifact, ArtifactKind, ArtifactRevision, Artifacts, BlobRef } from "../../sdk/src/artifacts.ts"
+import { ToolArgError } from "./tool-args"
 
 /** UTF-8 bytes of inline text one tool call may carry (bigger content: stage it, then pass `blobs`). */
 export const MCP_INLINE_TEXT_BYTES = 256 * 1024
@@ -45,24 +46,24 @@ const FILE_ARGS = {
 
 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
 }
 
 /** The files of a publish/revise: inline text and/or blob references (one of them required). */
 function files(args: Args, kind: ArtifactKind | undefined): { blobs?: BlobRef[]; upload?: { mediaType: string; data: string; path?: string }[]; entry?: string } {
   const text = args.text
-  if (text !== undefined && typeof text !== "string") throw new Error('"text" must be a string')
+  if (text !== undefined && typeof text !== "string") throw new ToolArgError('"text" must be a string')
   const blobs = args.blobs
-  if (blobs !== undefined && (!Array.isArray(blobs) || !blobs.every((b) => typeof b === "object" && b !== null))) throw new Error('"blobs" must be a list of blob references')
-  if (text === undefined && (blobs === undefined || blobs.length === 0)) throw new Error('give text or blobs (stage bigger content first and pass its reference)')
-  if (text !== undefined && Buffer.byteLength(text, "utf8") > MCP_INLINE_TEXT_BYTES) throw new Error(`text is larger than ${MCP_INLINE_TEXT_BYTES} bytes: stage it with uploadBlob and pass blobs`)
+  if (blobs !== undefined && (!Array.isArray(blobs) || !blobs.every((b) => typeof b === "object" && b !== null))) throw new ToolArgError('"blobs" must be a list of blob references')
+  if (text === undefined && (blobs === undefined || blobs.length === 0)) throw new ToolArgError('give text or blobs (stage bigger content first and pass its reference)')
+  if (text !== undefined && Buffer.byteLength(text, "utf8") > MCP_INLINE_TEXT_BYTES) throw new ToolArgError(`text is larger than ${MCP_INLINE_TEXT_BYTES} bytes: stage it with uploadBlob and pass blobs`)
   const path = optional(args, "path")
   const entry = optional(args, "entry")
   const mediaType = optional(args, "mediaType") ?? (kind && DEFAULT_MEDIA[kind]) ?? "text/plain"
@@ -126,7 +127,7 @@ export const artifactTools: readonly ArtifactTool[] = [
     run: async (hub, args, signal) => {
       const title = need(args, "title")
       const kind = need(args, "kind") as ArtifactKind
-      if (!KINDS.includes(kind)) throw new Error(`"kind" must be one of ${KINDS.join(", ")}`)
+      if (!KINDS.includes(kind)) throw new ToolArgError(`"kind" must be one of ${KINDS.join(", ")}`)
       const body = files(args, kind)
       const description = optional(args, "description")
       const visibility = optional(args, "visibility") as "private" | "workspace" | undefined

package/packages/cli/src/mcp.ts

@@ -26,7 +26,8 @@ import { artifactTools } from "./artifacts-mcp"
 import { artifactJobTools } from "./artifact-jobs-mcp"
 import { teamIntakeTools } from "./team-intake-mcp"
 import { teamTools } from "./teams-mcp"
-import { ProfileArgError, profileLifecycleTools } from "./profiles-mcp"
+import { profileLifecycleTools } from "./profiles-mcp"
+import { ToolArgError } from "./tool-args"
 import { watchlistTools } from "./watchlist"
 
 /** The protocol revisions the server speaks, newest first: a client's supported one is echoed, else the newest. */
@@ -48,7 +49,7 @@ type Id = string | number | null
 type Args = Record<string, unknown>
 
 /** A bad tool argument (an isError result, not a protocol error). */
-class ArgError extends Error {}
+const ArgError = ToolArgError
 
 const need = (args: Args, key: string): string => {
   const value = args[key]
@@ -1143,7 +1144,7 @@ export function createMcpServer(options: McpServerOptions): McpServer {
       return controller.signal.aborted ? undefined : ok(id, toolResult(clean(text, token), false))
     } catch (cause) {
       if (controller.signal.aborted) return undefined // cancelled: no answer (MCP cancellation)
-      const text = cause instanceof ArgError || cause instanceof ProfileArgError ? `invalid: ${cause.message}` : cause instanceof CliError ? errorText(cause) : `${tool.name} failed: ${cause instanceof Error ? cause.message : String(cause)}`
+      const text = cause instanceof ToolArgError ? `invalid: ${cause.message}` : cause instanceof CliError ? errorText(cause) : `${tool.name} failed: ${cause instanceof Error ? cause.message : String(cause)}`
       return ok(id, toolResult(clean(text, token), true))
     } finally {
       if (inFlight.get(key(id)) === controller) inFlight.delete(key(id))

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

@@ -14,6 +14,7 @@
 // version can be restored with fromVersion); archive/restore (no new versions or pins) and pins (applied to a running
 // session) keep the default destructiveHint. Changes send expectedRevision, so repeating one is idempotent.
 import { sanitizeText } from "../../sdk/src/envelope.ts"
+import { ToolArgError } from "./tool-args"
 import type { Profiles } from "../../sdk/src/client.ts"
 import type { ProfileCommand, ProfileContent, ProfileSkill, ProfileVersionSummary, ProfileView } from "../../sdk/src/types.ts"
 
@@ -53,9 +54,8 @@ const META_FIELDS = {
 } as const
 const SCOPES = "App tokens need scope profiles:read (reads) or profiles:manage (changes; profile_version_create with content fields and the skill/command set/remove tools read the latest version first, so they also need profiles:read); pins need profiles:assign and sessions:read (an app also needs a prompt grant on the session). Session tokens never change profiles. A profile confers no authority."
 
-/** A bad tool argument: mcp.ts answers it as `invalid: …` (an isError result). */
-export class ProfileArgError extends Error {}
-const ArgError = ProfileArgError
+/** A bad tool argument: mcp.ts answers it as `invalid: …` (an isError result; tool-args.ts). */
+const ArgError = ToolArgError
 
 const need = (args: Args, key: string): string => {
   const value = args[key]

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.2",
   "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.2",
   "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.2",
   "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.2",
   "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,6 +31,7 @@ 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 { HUB_URL_MAX_CHARS, isHubURL, MAX_FRAME, MAX_RETRY_AFTER_MS }
@@ -93,7 +94,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 +156,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 +202,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). */
@@ -829,8 +854,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 +961,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 +995,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))
   )
 }
 
@@ -1187,8 +1235,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 +1249,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 +1257,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 +1293,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/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.2",
   "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.2",
   "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.2",
   "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.2",
   "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",