@huynle/hub 0.9.2 → 0.10.1

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,15 @@ 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.
+ * "setModel": it sets the session's own model (setModel op) the way the harness keeps it for every later turn of
+ * that session (OpenCode: session.switchModel, stored on the session), whoever prompts it next.
  */
-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", "setModel"] as const
 
 /**
  * The core ops. An OpenCode spoke serves them all without announcing them; a spoke of another harness announces
@@ -503,11 +519,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 +565,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,18 +691,23 @@ 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 }
+  /**
+   * (feature "setModel") Set the session's own model: every later turn of the session runs on it, whoever prompts it
+   * (the console, the terminal, a voice relay). One of the session's catalog models (models op); no variant: the
+   * model's default. The Voice model (setModelPrefs) is separate and never changes it.
+   */
+  | { readonly op: "setModel"; readonly sessionID: string; readonly model: ModelSelection }
   | { 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 }
   /** One image attached to a user message (its position in the message's files). */
@@ -750,6 +787,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 +807,8 @@ export function featureForOp(op: ServerRequest["op"]): SpokeFeature {
       return "revert"
     case "removeFront":
       return "voiceFront"
+    case "frontUpdate":
+      return "conciergeFront"
     default:
       return op
   }
@@ -831,10 +875,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
 }
@@ -871,6 +928,8 @@ export interface ResultFor {
   models: { readonly models: readonly AvailableModel[] }
   modelPrefs: { readonly prefs: SessionModelPrefs; readonly defaults: SessionModelPrefs }
   setModelPrefs: { readonly prefs: SessionModelPrefs; readonly defaults: SessionModelPrefs }
+  /** `model`: the session's model now (source "chosen"). */
+  setModel: { readonly model: SessionModel }
   timeline: TimelinePage
   timelinePart: { readonly detail: unknown }
   /** No `file` when the message has no image at that index; `tooLarge` when its bytes would not fit in a frame. */
@@ -896,6 +955,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 +1183,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
 }
 
@@ -1212,6 +1278,8 @@ function isServerRequest(v: unknown): v is ServerRequest {
         (v.worker === undefined || v.worker === null || isModelSelection(v.worker)) &&
         (v.voice !== undefined || v.worker !== undefined)
       )
+    case "setModel":
+      return nonEmpty(v.sessionID) && isModelSelection(v.model)
     case "timeline":
       return (
         nonEmpty(v.sessionID) &&
@@ -1272,6 +1340,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
   }

package/packages/runtime-openshell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-openshell",
-  "version": "0.9.2",
+  "version": "0.10.1",
   "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.9.2",
+  "version": "0.10.1",
   "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.9.2",
+  "version": "0.10.1",
   "private": true,
   "description": "Typed client for the hub's /api/agent (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",