@huynle/hub 0.10.0 → 0.11.0

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-cli",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": true,
   "description": "The hub CLI (`hub` / `hubctl`) for agents and scripts (internal; bundled into @huynle/hub, not published on its own).",
   "license": "MIT",

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

@@ -0,0 +1,65 @@
+// MCP grant tools: the server owns authority. Requests use the existing tap Decision route; /mine never widens
+// the user-only grant administration routes. A user credential may create directly but has no /mine holder.
+import type { HubClient } from "../../sdk/src/client.ts"
+import type { GrantRequestSpec, GrantSpec } from "../../sdk/src/types.ts"
+import { grantError, grantText, grantsText, GRANT_USER_HINT, requestedText } from "./grants"
+import { CliError, EXIT } from "./http"
+import { ToolArgError } from "./tool-args"
+
+type Args = Record<string, unknown>
+export interface GrantTool {
+  readonly name: string
+  readonly description: string
+  readonly properties: Record<string, unknown>
+  readonly required?: readonly string[]
+  readonly readOnly: boolean
+  readonly organizes?: boolean
+  run(hub: HubClient, args: Args, signal: AbortSignal): Promise<string>
+}
+
+const STRING = { type: "string" } as const
+const GRANT = { type: "object", description: "The grant spec accepted by POST /api/agent/grants: holder (optional for a request), scope.projects, allow, permissions, allowAlways, maxActionsPerHour and expires. The server validates all fields.", additionalProperties: true } as const
+const need = (args: Args, key: string): string => {
+  if (typeof args[key] !== "string" || !(args[key] as string).trim()) throw new ToolArgError(`"${key}" is required (a non-empty string)`)
+  return args[key] as string
+}
+const spec = (args: Args): Record<string, unknown> => {
+  if (typeof args.grant !== "object" || args.grant === null || Array.isArray(args.grant)) throw new ToolArgError('"grant" is required (an object)')
+  return args.grant as Record<string, unknown>
+}
+
+export const grantTools: readonly GrantTool[] = [
+  {
+    name: "grant_request", description: "Ask the user for a grant: opens one tap Decision for @me (approve or deny). Sessions and apps with messages:send only; one open request and at most five per hour. Only the user's answer creates authority.",
+    properties: { grant: GRANT, why: STRING }, required: ["grant", "why"], readOnly: false,
+    run: async (hub, args, signal) => requestedText(await hub.requestGrant(spec(args) as GrantRequestSpec, need(args, "why"), { signal })),
+  },
+  {
+    name: "grant_list", description: "List grants (active, expired or revoked) whose holder is this session or app, including grants for roles it holds now. Apps need messages:read. A user credential has no holder: use the console or hub grant list for administration.",
+    properties: {}, readOnly: true,
+    run: async (hub, _args, signal) => grantsText((await hub.heldGrants({ signal })).grants),
+  },
+  {
+    name: "grant_show", description: "Show one grant only if this credential currently holds it. Apps need messages:read; another holder's ID answers not_found.",
+    properties: { id: STRING }, required: ["id"], readOnly: true,
+    run: async (hub, args, signal) => grantText((await hub.heldGrant(need(args, "id"), { signal })).grant),
+  },
+  {
+    name: "grant_revoke", description: "Irreversibly revoke a grant held by this session or app (including a held role shared with other holders). Apps need messages:send; another holder's ID answers not_found.",
+    properties: { id: STRING }, required: ["id"], readOnly: false,
+    run: async (hub, args, signal) => grantText((await hub.revokeHeldGrant(need(args, "id"), { signal })).grant),
+  },
+  {
+    name: "grant_create", description: `Create a grant directly ONLY with the user's device credential. Sessions and apps must use grant_request and wait for the user's tap. ${GRANT_USER_HINT}.`,
+    properties: { grant: GRANT }, required: ["grant"], readOnly: false,
+    run: async (hub, args, signal) => {
+      const actor = (await hub.whoami({ signal })).actor
+      if (actor.kind !== "user") throw new CliError(EXIT.forbidden, "only the user can create a grant, not a session or app", GRANT_USER_HINT)
+      try {
+        return grantText((await hub.createGrant(spec(args) as unknown as GrantSpec, { signal })).grant)
+      } catch (cause) {
+        throw grantError(cause)
+      }
+    },
+  },
+]

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

@@ -0,0 +1,49 @@
+// User-only MCP access to the existing console session-model route and owner-scoped machine/node snapshots.
+// No agent or app model-setting authority: the server's model route remains console user-only.
+import type { HubClient } from "../../sdk/src/client.ts"
+import { CliError, EXIT } from "./http"
+import { ToolArgError } from "./tool-args"
+
+type Args = Record<string, unknown>
+interface Tool {
+  readonly name: string
+  readonly description: string
+  readonly properties: Record<string, unknown>
+  readonly required?: readonly string[]
+  readonly readOnly: boolean
+  run(hub: HubClient, args: Args, signal: AbortSignal): Promise<string>
+}
+const STRING = { type: "string" } as const
+const need = (args: Args, key: string) => {
+  const v = args[key]
+  if (typeof v !== "string" || !v.trim()) throw new ToolArgError(`"${key}" is required (a non-empty string)`)
+  return v
+}
+const userOnly = async (hub: HubClient, signal: AbortSignal) => {
+  if ((await hub.whoami({ signal })).actor.kind !== "user") throw new CliError(EXIT.forbidden, "only the user can use this tool", "Use the user's device credential")
+}
+
+export const operationTools: readonly Tool[] = [
+  {
+    name: "session_model_set", description: "Set one existing session's model (providerID, modelID and optional variant), exactly as the console Model chip does. User device credential only; the console route checks ownership, catalog, availability and audit. An app or session cannot set it.",
+    properties: { session: STRING, model: { type: "object", properties: { providerID: STRING, modelID: STRING, variant: STRING }, required: ["providerID", "modelID"] } },
+    required: ["session", "model"], readOnly: false,
+    run: async (hub, args, signal) => {
+      await userOnly(hub, signal)
+      const model = args.model
+      if (typeof model !== "object" || model === null || Array.isArray(model)) throw new ToolArgError('"model" is required (providerID, modelID, variant?)')
+      const result = await hub.call<{ model: unknown }>("PUT", `/api/sessions/${encodeURIComponent(need(args, "session"))}/model`, { body: { model }, signal })
+      return JSON.stringify(result)
+    },
+  },
+  {
+    name: "machines", description: "The user's own enrolled machines, online status and processes. User device credential only; wraps GET /api/machines. No machine tokens or secrets.",
+    properties: {}, readOnly: true,
+    run: async (hub, _args, signal) => { await userOnly(hub, signal); return JSON.stringify(await hub.call("GET", "/api/machines", { signal })) },
+  },
+  {
+    name: "launch_nodes", description: "The user's connected launch nodes: machine, workspace roots, capacity/used/free slots, runtimes (harnesses) and labels. User device credential only; no tokens, connection IDs or mutation.",
+    properties: {}, readOnly: true,
+    run: async (hub, _args, signal) => { await userOnly(hub, signal); return JSON.stringify(await hub.call("GET", "/api/agent/launch-nodes", { signal })) },
+  },
+]

package/packages/cli/src/mcp.ts

@@ -25,8 +25,11 @@ import { launchedText, launchesText, launchText, stoppedLaunchText } from "./lau
 import { artifactTools } from "./artifacts-mcp"
 import { artifactJobTools } from "./artifact-jobs-mcp"
 import { teamIntakeTools } from "./team-intake-mcp"
+import { subscriptionTools } from "./subscriptions-mcp"
+import { operationTools } from "./mcp-operations"
 import { teamTools } from "./teams-mcp"
 import { profileLifecycleTools } from "./profiles-mcp"
+import { grantTools } from "./grants-mcp"
 import { ToolArgError } from "./tool-args"
 import { watchlistTools } from "./watchlist"
 
@@ -755,10 +758,13 @@ const TOOLS: readonly Tool[] = [
   ...webhookTools,
   ...profileTools,
   ...profileLifecycleTools,
+  ...grantTools,
   ...workspaceTools,
   ...artifactTools,
   ...artifactJobTools,
   ...teamIntakeTools,
+  ...subscriptionTools,
+  ...operationTools,
   ...teamTools,
   ...watchlistTools,
   {

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

@@ -0,0 +1,76 @@
+// MCP wrappers over the existing subscription routes; authorization and delivery caps remain on the server.
+import type { HubClient } from "../../sdk/src/client.ts"
+import type { SubscribeInput } from "../../sdk/src/types.ts"
+import { subscribedText, subscriptionsText } from "./subscriptions"
+import { ToolArgError } from "./tool-args"
+
+type Args = Record<string, unknown>
+export interface SubscriptionTool {
+  readonly name: string
+  readonly description: string
+  readonly properties: Record<string, unknown>
+  readonly required?: readonly string[]
+  readonly readOnly: boolean
+  readonly organizes?: boolean
+  run(hub: HubClient, args: Args, signal: AbortSignal): Promise<string>
+}
+const STRING = { type: "string" } as const
+const need = (args: Args, key: string): string => {
+  const value = args[key]
+  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 ToolArgError(`"${key}" must be a string`)
+  return value.trim() || undefined
+}
+const array = (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 ToolArgError(`"${key}" must be a list of strings`)
+  return value
+}
+const number = (args: Args, key: string, min: number, max: number): number | undefined => {
+  const value = args[key]
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) throw new ToolArgError(`"${key}" must be a whole number from ${min} to ${max}`)
+  return value
+}
+
+export const subscriptionTools: readonly SubscriptionTool[] = [
+  {
+    name: "subscribe", description: "Follow journal events for a subscriber session. A session subscribes itself; users and apps name subscriber. Apps need events:subscribe, sessions:read, relevant type scopes and messages:send unless silent. Hub checks visibility, rates and loops.",
+    properties: {
+      to: { type: ["string", "array"], items: STRING, description: "One or more session/role/team addresses, or children." },
+      subscriber: STRING, types: { type: "array", items: STRING }, delivery: { type: "string", enum: ["queue", "steer", "silent"] },
+      batch: { type: "number", description: "Seconds per batch (1–3600)." }, expires: { type: "number", description: "Seconds until expiry." },
+      maxPerHour: { type: "integer", minimum: 1, maximum: 120 }, note: STRING,
+    }, required: ["to"], readOnly: false,
+    run: async (hub, args, signal) => {
+      const to = typeof args.to === "string" && args.to.trim() ? args.to : array(args, "to")
+      if (!to || (Array.isArray(to) && !to.length)) throw new ToolArgError('"to" needs at least one address')
+      const delivery = optional(args, "delivery")
+      if (delivery && !["queue", "steer", "silent"].includes(delivery)) throw new ToolArgError('"delivery" is queue, steer or silent')
+      const subscriber = optional(args, "subscriber")
+      const types = array(args, "types")
+      const batch = number(args, "batch", 1, 3600)
+      const expires = number(args, "expires", 1, 30 * 86400)
+      const maxPerHour = number(args, "maxPerHour", 1, 120)
+      const note = optional(args, "note")
+      const input: SubscribeInput = { to, ...(subscriber ? { subscriber } : {}), ...(types ? { types } : {}), ...(delivery ? { delivery: delivery as SubscribeInput["delivery"] } : {}), ...(batch ? { batch } : {}), ...(expires ? { expires } : {}), ...(maxPerHour ? { maxPerHour } : {}), ...(note ? { note } : {}) }
+      return subscribedText(await hub.subscribe(input, { signal }))
+    },
+  },
+  {
+    name: "subscriptions", description: "List subscriptions visible to this credential (session: its own; app: created by it; user: all). Optional session filter; route enforces scopes and tenancy.",
+    properties: { session: STRING }, readOnly: true,
+    run: async (hub, args, signal) => subscriptionsText(await hub.subscriptions({ ...(optional(args, "session") ? { session: optional(args, "session") } : {}), signal })),
+  },
+  {
+    name: "unsubscribe", description: "Remove a subscription this credential owns. An unknown or another caller's ID answers not_found.",
+    properties: { id: STRING }, required: ["id"], readOnly: false, organizes: true,
+    run: async (hub, args, signal) => { const id = need(args, "id"); await hub.unsubscribe(id, { signal }); return `unsubscribed ${id}` },
+  },
+]

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

@@ -51,6 +51,7 @@ const SPEC_FIELDS = {
   title: { ...STRING, description: "1–120 characters." },
   description: STRING,
   mode: { type: "string", enum: ["open", "restricted"], description: "open: every member may msg/ask every other member. restricted: only the drawn paths (edges)." },
+  hopLimit: { type: "integer", minimum: 1, maximum: 100, description: "Agent-only wake hop limit between this team's seats; may not exceed the hub-wide agents.hopLimit. Unset uses the global limit." },
   roles: { type: "array", items: ROLE, description: "1–32 roles." },
   entryRole: { ...STRING, description: "The role that receives submitted work (e.g. pm) and supervises members." },
   edges: { type: "array", items: EDGE, description: "Communication paths between roles (restricted mode)." },
@@ -176,6 +177,7 @@ function specLines(spec: TeamSpec): string[] {
     `  ${r.name}${r.name === spec.entryRole ? " (entry)" : ""}${r.label ? `  "${one(r.label)}"` : ""}${r.externalContact ? "  external contact" : ""}${r.minMembers !== undefined || r.maxMembers !== undefined ? `  members ${r.minMembers ?? 0}–${r.maxMembers ?? 16}` : ""}${r.profile ? `  profile ${r.profile.profileID}${r.profile.version ? `@${r.profile.version}` : ""}` : ""}`
   return [
     `mode: ${spec.mode}${spec.mode === "open" ? " (every member may msg/ask every other)" : " (only the paths below)"}`,
+    ...(spec.hopLimit !== undefined ? [`hop limit: ${spec.hopLimit}`] : []),
     `entry role: ${spec.entryRole}`,
     "roles:",
     ...spec.roles.map(role),
@@ -196,7 +198,7 @@ function rosterLines(roster: TeamRoster): string[] {
     const flags = [r.vacant ? "vacant" : "", r.understaffed ? `understaffed (min ${r.minMembers})` : "", r.launching ? `${r.launching} launching` : ""].filter(Boolean)
     lines.push(`  ${r.role}${r.entry ? " (entry)" : ""}  ${r.seats.length}/${r.maxMembers}  ${r.online} online${flags.length ? `  ${flags.join(", ")}` : ""}`)
     for (const s of r.seats)
-      lines.push(`    ${s.staffing.id}  ${s.staffing.sessionID}  ${s.presence}  gen ${s.staffing.generation} r${s.staffing.revision}${s.profile ? `  profile ${s.profile.status}${s.profile.matches ? "" : " (mismatch)"}` : ""}`)
+      lines.push(`    ${s.staffing.id}  ${s.staffing.sessionID}  ${s.presence}${s.stalled ? `  stalled: ${s.stalled}` : ""}  gen ${s.staffing.generation} r${s.staffing.revision}${s.profile ? `  profile ${s.profile.status}${s.profile.matches ? "" : " (mismatch)"}` : ""}`)
   }
   const failed = roster.requests.filter((q) => q.state !== "staffed").slice(-5)
   for (const q of failed) lines.push(`  launch ${q.id}  ${q.role}  ${q.state}${q.reason ? `: ${one(q.reason)}` : ""}`)
@@ -347,7 +349,7 @@ export const teamTools: readonly TeamTool[] = [
       need(args, "name")
       need(args, "title")
       const key = optional(args, "idempotencyKey")
-      const spec = picked(args, ["name", "title", "description", "mode", "roles", "entryRole", "edges", "tags", "metadata", "projects"]) as unknown as TeamSpec
+      const spec = picked(args, ["name", "title", "description", "mode", "hopLimit", "roles", "entryRole", "edges", "tags", "metadata", "projects"]) as unknown as TeamSpec
       const { team, created } = await hub.teams.create({ ...spec, edges: spec.edges ?? [] }, { signal, ...(key ? { idempotencyKey: key } : {}) })
       return [`${created ? "created" : "already created (same key)"}: ${teamLine(team)}`, ...specLines(team)].join("\n")
     },
@@ -362,7 +364,7 @@ export const teamTools: readonly TeamTool[] = [
     idempotent: true,
     run: async (hub, args, signal) => {
       const expectedRevision = revision(args)
-      const patch = picked(args, ["title", "description", "mode", "roles", "entryRole", "edges", "tags", "metadata", "projects"]) as TeamPatch
+      const patch = picked(args, ["title", "description", "mode", "hopLimit", "roles", "entryRole", "edges", "tags", "metadata", "projects"]) as TeamPatch
       if (Object.keys(patch).length === 0) throw new ArgError("give at least one field to change")
       const id = need(args, "team")
       const { team } = await hub.teams.update(id, patch, expectedRevision, { signal })

package/packages/codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-codex",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "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.10.0",
+  "version": "0.11.0",
   "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.10.0",
+  "version": "0.11.0",
   "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.10.0",
+  "version": "0.11.0",
   "private": true,
   "description": "Hub ↔ spoke wire protocol (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/packages/protocol/src/index.ts

@@ -480,8 +480,10 @@ export const IMPLIED_OPENCODE_FEATURES = [
  * "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", "conciergeFront", "inboxCarried"] 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
@@ -700,6 +702,12 @@ export type ServerRequest =
   | { 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). */
@@ -920,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. */
@@ -1268,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) &&

package/packages/protocol/src/teams.ts

@@ -19,6 +19,7 @@ export const TEAM_LIMITS = {
   sessionsPerRole: 16,
   /** Open intake items per team. */
   openIntakePerTeam: 500,
+  hopLimit: 100,
 } as const
 
 export const TEAM_SCOPES = ["teams:read", "teams:manage", "teams:submit"] as const
@@ -54,6 +55,8 @@ export interface TeamDefinition extends Revisioned {
   readonly description?: string
   readonly state: RecordState
   readonly mode: TeamMode
+  /** Optional limit for messages between this team's seated sessions. */
+  readonly hopLimit?: number
   readonly roles: readonly TeamRole[]
   /** The intake role; receives submitted work and supervises members (via workspace supervision). */
   readonly entryRole: string
@@ -182,6 +185,7 @@ export function teamInputProblem(v: unknown): string | undefined {
   if (!isLabel(v.title)) return "title must be 1–120 characters of text"
   if (v.description !== undefined && !isText(v.description, DESCRIPTION_MAX)) return `description must be at most ${DESCRIPTION_MAX} characters`
   if (v.mode !== "open" && v.mode !== "restricted") return "mode must be open or restricted"
+  if (v.hopLimit !== undefined && (!Number.isSafeInteger(v.hopLimit) || (v.hopLimit as number) < 1 || (v.hopLimit as number) > TEAM_LIMITS.hopLimit)) return `hopLimit must be a whole number from 1 to ${TEAM_LIMITS.hopLimit}`
   if (!Array.isArray(v.roles) || v.roles.length === 0 || v.roles.length > TEAM_LIMITS.rolesPerTeam) return `roles must list 1–${TEAM_LIMITS.rolesPerTeam} roles`
   const names = new Set<string>()
   for (const role of v.roles) {

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

@@ -2,7 +2,8 @@ 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_REPLY_TYPE = "audio/mpeg"            // Developer mode: a reply sentence's TTS audio, as synthesized
+export const RECORDING_MEDIA_TYPES = [RECORDING_AUDIO_TYPE, RECORDING_PAGE_TYPE, RECORDING_REPLY_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>"
@@ -11,8 +12,12 @@ export const RECORDING_AUDIO_RESULT_HEADER = "x-hub-recording-audio" // transcri
  * Console kinds and values added after version 1, listed in the start answer (`features`): a console sends them only
  * to a hub that lists them (an older hub refuses a whole batch with an unknown kind or value).
  *   "turn.predict": the turn.predict kind and utterance.sent reasons "smart" / "smart-fallback" (Smart Turn).
+ *   "capture.v2": the kinds vad.near, vad.summary, stt.slow and mark, the utterance.command command "mark", and the
+ *     stt.received fields junkReason, held and speechMs (an older hub refuses an unknown field too).
+ *   "dev.v1": Developer mode's kinds vad.trace, audio.clip, device.info, resource.timing and console.log (sent only
+ *     when the start answer also says `developer: true`), and the clip upload route.
  */
-export const RECORDING_FEATURES = ["turn.predict"] as const
+export const RECORDING_FEATURES = ["turn.predict", "capture.v2", "dev.v1"] as const
 export type RecordingFeature = (typeof RECORDING_FEATURES)[number]
 
 export const RECORDING_LIMITS = {
@@ -36,8 +41,29 @@ export const RECORDING_LIMITS = {
   hubFlushMs: 2_000, hubFlushEvents: 100,
 } as const
 
+/**
+ * Developer mode (feature "dev.v1"): the extras' own limits. Their audio (clips, reply audio) counts against the same
+ * caps but stops first: never within the headroom kept for segments below the user's and the recording's caps.
+ */
+export const DEV_LIMITS = {
+  clipsPerRecording: 200,
+  clipPreMs: 3000,
+  clipPostMs: 2000,
+  clipBytes: 192 * 1024,                // 5 s at 16 kHz PCM16 = 160,044 B
+  /** At most one clip per this much time (console), the rest are not cut. */
+  clipGapMs: 2000,
+  repliesPerRecording: 2000,
+  replyBytes: 1024 * 1024,              // one sentence's MP3
+  userHeadroomBytes: 50 * 1024 * 1024,  // extras stop at userBytes − this; segments go on to userBytes
+  recordingHeadroomBytes: 15 * 1024 * 1024,
+  tracesPerMinute: 30,
+  logsPerMinute: 20,
+} as const
+
 export interface RecordingSettings {
   readonly enabled: boolean        // default false
+  /** Developer mode (implies enabled; turning recording off turns it off). Absent: off. */
+  readonly developer?: boolean
   readonly revision: number
   readonly updatedAt?: number
 }
@@ -75,6 +101,11 @@ export interface RecordingSummary {
   readonly events: number
   readonly audio: boolean                    // false once a cap stopped audio
   readonly redactions: number
+  /** Developer mode: this recording keeps the extras (until Developer mode is turned off). */
+  readonly developer?: true
+  /** Developer mode: audio clips and reply audio stored. */
+  readonly clips?: number
+  readonly replies?: number
 }
 
 export interface RecordingUsage { readonly bytes: number; readonly recordings: number; readonly capBytes: number }
@@ -90,11 +121,17 @@ export type ConsoleEventKind =
   | "tts.sentence.ended" | "barge.in" | "cue.played" | "mic" | "control" | "turn.timing" | "decision.voice"
   | "clock.sync" | "error"
   | "turn.predict" // feature "turn.predict"
+  | "vad.near" | "vad.summary" | "stt.slow" | "mark" // feature "capture.v2"
+  | "vad.trace" | "audio.clip" | "device.info" | "resource.timing" | "console.log" // feature "dev.v1" (Developer mode)
 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"
+  | "turn.detail" | "request" | "reply.audio" // Developer mode
+
+/** Console kinds of Developer mode: stored only in a developer recording. */
+export const DEV_CONSOLE_KINDS: readonly ConsoleEventKind[] = ["vad.trace", "audio.clip", "device.info", "resource.timing", "console.log"]
 
 /** As stored and exported (events.jsonl). */
 export interface RecordingEvent {

package/packages/runtime-openshell/image/entry.sh

@@ -29,7 +29,9 @@ poll="${HUB_POLL_INTERVAL:-0.5}"
 say() { echo "[hub-sandbox] $*" >&2; }
 
 mkdir -p "$hub"
-echo "$$" >"$hub/entry.pid"
+pid_file=$(mktemp "$hub/entry.pid.XXXXXX") || exit 1
+printf '%s\n' "$$" >"$pid_file"
+mv -f "$pid_file" "$hub/entry.pid"
 rm -f "$hub/exited"
 
 # 1. Wait for the start op.

package/packages/runtime-openshell/image/start.sh

@@ -20,5 +20,7 @@ else
   nohup "$here/hub-sandbox-entry" >>"$log" 2>&1 </dev/null &
 fi
 # The entry rewrites this with its own pid; written here too so a start right after sees it.
-echo "$!" >"$hub/entry.pid"
+pid_file=$(mktemp "$hub/entry.pid.XXXXXX") || exit 1
+printf '%s\n' "$!" >"$pid_file"
+mv -f "$pid_file" "$hub/entry.pid"
 echo "hub-sandbox: started (pid $!, log $log)"

package/packages/runtime-openshell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-runtime-openshell",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "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.10.0",
+  "version": "0.11.0",
   "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.10.0",
+  "version": "0.11.0",
   "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

@@ -780,6 +780,19 @@ export class HubClient {
     return this.call("GET", `${AGENT}/grants`, signalOf(options))
   }
 
+  /** Grants held by this session/app; a user credential has no holder. */
+  heldGrants(options: CallOptions = {}): Promise<{ grants: Grant[] }> {
+    return this.call("GET", `${AGENT}/grants/mine`, signalOf(options))
+  }
+
+  heldGrant(id: string, options: CallOptions = {}): Promise<{ grant: Grant }> {
+    return this.call("GET", `${AGENT}/grants/mine/${segment(id)}`, signalOf(options))
+  }
+
+  revokeHeldGrant(id: string, options: CallOptions = {}): Promise<{ grant: Grant }> {
+    return this.call("DELETE", `${AGENT}/grants/mine/${segment(id)}`, signalOf(options))
+  }
+
   grant(id: string, options: CallOptions = {}): Promise<{ grant: Grant }> {
     return this.call("GET", `${AGENT}/grants/${segment(id)}`, signalOf(options))
   }

package/packages/sdk/src/teams.ts

@@ -53,6 +53,7 @@ export interface TeamSpec {
   readonly title: string
   readonly description?: string
   readonly mode: TeamMode
+  readonly hopLimit?: number
   readonly roles: readonly TeamRole[]
   /** The intake role (e.g. the project manager): receives submitted work and supervises members. */
   readonly entryRole: string
@@ -149,6 +150,7 @@ export interface TeamWorkspaceLink {
 export interface TeamRosterSeat {
   readonly staffing: TeamStaffing
   readonly presence: TeamSessionPresence
+  readonly stalled?: "hop cap"
   readonly memberID?: string
   readonly supervisorMemberID?: string
   readonly profile?: {

package/packages/spoke-sdk/package.json

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

package/src/central/agent/decisions.ts

@@ -124,7 +124,13 @@ export function appAnswerRefusal(decision: Pick<Decision, "tier" | "action" | "a
 }
 
 /** What answering a Decision does besides replying: an escalated permission request (P3-T8) or a grant request (P3-T9). */
-export type DecisionAction = PermissionAction | GrantRequestAction | ActAction
+export type DecisionAction = PermissionAction | GrantRequestAction | ActAction | TeamHopRenewAction
+
+/** Hub-created, tap-only action: an agent cannot authorize a team's hop budget renewal. */
+export interface TeamHopRenewAction {
+  readonly kind: "teamHopRenew"
+  readonly teamID: string
+}
 
 /**
  * (CON-06) A Concierge proposal (concierge/proposals.ts): answering `go` runs the act verb on the target AS THE USER