@huynle/hub 0.10.1 → 0.11.1

package/packages/protocol/schema/api/v1/unspecified.json

@@ -0,0 +1,282 @@
+[
+  "DELETE /api/admin/devices/:id",
+  "DELETE /api/admin/machines/:id",
+  "DELETE /api/agent/app-clients/:id",
+  "DELETE /api/agent/app-tokens/:id",
+  "DELETE /api/agent/artifact-host/:cap",
+  "DELETE /api/agent/artifacts/:id",
+  "DELETE /api/agent/connections/:id",
+  "DELETE /api/agent/grants/:id",
+  "DELETE /api/agent/grants/mine/:id",
+  "DELETE /api/agent/launches/:id",
+  "DELETE /api/agent/sessions/:addr/profile",
+  "DELETE /api/agent/subscriptions/:id",
+  "DELETE /api/agent/teams/:id/draft",
+  "DELETE /api/agent/teams/:id/draft/edges",
+  "DELETE /api/agent/teams/:id/draft/roles/:role",
+  "DELETE /api/agent/teams/:id/staffing/:staffing",
+  "DELETE /api/agent/webhooks/:id",
+  "DELETE /api/agent/workspaces/:id/bindings",
+  "DELETE /api/agent/workspaces/:id/members/:member",
+  "DELETE /api/machines/:machine",
+  "DELETE /api/recordings",
+  "DELETE /api/recordings/:id",
+  "GET /api/activity/mine",
+  "GET /api/admin/agents/acting",
+  "GET /api/admin/audit",
+  "GET /api/admin/machines",
+  "GET /api/admin/users",
+  "GET /api/agent/acting",
+  "GET /api/agent/agent-limits",
+  "GET /api/agent/app-clients",
+  "GET /api/agent/app-tokens",
+  "GET /api/agent/artifacts",
+  "GET /api/agent/artifacts/:id",
+  "GET /api/agent/artifacts/:id/jobs",
+  "GET /api/agent/artifacts/:id/jobs/:job",
+  "GET /api/agent/artifacts/:id/jobs/:job/context",
+  "GET /api/agent/artifacts/:id/jobs/:job/proposal",
+  "GET /api/agent/artifacts/:id/revisions",
+  "GET /api/agent/artifacts/:id/revisions/:rev",
+  "GET /api/agent/artifacts/:id/revisions/:rev/blobs/:hash",
+  "GET /api/agent/audit",
+  "GET /api/agent/concierge",
+  "GET /api/agent/concierge/arm",
+  "GET /api/agent/concierge/board",
+  "GET /api/agent/concierge/decisions",
+  "GET /api/agent/concierge/decisions/:id",
+  "GET /api/agent/concierge/machines/:id/models",
+  "GET /api/agent/concierge/notes",
+  "GET /api/agent/concierge/sessions/:addr/forms/:form",
+  "GET /api/agent/concierge/watchlist",
+  "GET /api/agent/connections",
+  "GET /api/agent/decisions",
+  "GET /api/agent/decisions/:id",
+  "GET /api/agent/events",
+  "GET /api/agent/grants",
+  "GET /api/agent/grants/:id",
+  "GET /api/agent/grants/mine",
+  "GET /api/agent/grants/mine/:id",
+  "GET /api/agent/graph",
+  "GET /api/agent/graph/edges/:id",
+  "GET /api/agent/graph/nodes/:id",
+  "GET /api/agent/inbox",
+  "GET /api/agent/launch-nodes",
+  "GET /api/agent/launches",
+  "GET /api/agent/launches/:id",
+  "GET /api/agent/messages/:id",
+  "GET /api/agent/messaging",
+  "GET /api/agent/profiles",
+  "GET /api/agent/profiles/:id",
+  "GET /api/agent/profiles/:id/usage",
+  "GET /api/agent/profiles/:id/versions",
+  "GET /api/agent/profiles/:id/versions/:version",
+  "GET /api/agent/profiles/:id/versions/:version/skills/:name",
+  "GET /api/agent/sessions",
+  "GET /api/agent/sessions/:addr",
+  "GET /api/agent/sessions/:addr/context-cards",
+  "GET /api/agent/sessions/:addr/intent",
+  "GET /api/agent/sessions/:addr/log",
+  "GET /api/agent/sessions/:addr/profile",
+  "GET /api/agent/sessions/:addr/profile/skills/:name",
+  "GET /api/agent/sessions/:addr/stream",
+  "GET /api/agent/side-chats/:chat",
+  "GET /api/agent/status",
+  "GET /api/agent/subscriptions",
+  "GET /api/agent/subscriptions/:id",
+  "GET /api/agent/team-settings",
+  "GET /api/agent/teams",
+  "GET /api/agent/teams/:id",
+  "GET /api/agent/teams/:id/diff",
+  "GET /api/agent/teams/:id/draft",
+  "GET /api/agent/teams/:id/intake",
+  "GET /api/agent/teams/:id/intake/:intake",
+  "GET /api/agent/teams/:id/roster",
+  "GET /api/agent/teams/:id/staffing",
+  "GET /api/agent/teams/:id/status",
+  "GET /api/agent/teams/:id/versions",
+  "GET /api/agent/teams/:id/versions/:version",
+  "GET /api/agent/watch",
+  "GET /api/agent/webhooks",
+  "GET /api/agent/webhooks/:id",
+  "GET /api/agent/who",
+  "GET /api/agent/whoami",
+  "GET /api/agent/workspaces",
+  "GET /api/agent/workspaces/:id",
+  "GET /api/agent/workspaces/:id/assignments",
+  "GET /api/agent/workspaces/:id/assignments/:assignment",
+  "GET /api/agent/workspaces/:id/bindings",
+  "GET /api/agent/workspaces/:id/board",
+  "GET /api/agent/workspaces/:id/checkpoints",
+  "GET /api/agent/workspaces/:id/master",
+  "GET /api/agent/workspaces/:id/members",
+  "GET /api/agent/workspaces/:id/side-chats",
+  "GET /api/agent/workspaces/:id/side-chats/:chat",
+  "GET /api/agent/workspaces/:id/supervision",
+  "GET /api/cli-logins/:code",
+  "GET /api/connect/flows/:flow",
+  "GET /api/context-cards/primary",
+  "GET /api/enrollments",
+  "GET /api/intents/mine",
+  "GET /api/media/remote",
+  "GET /api/media/unfurl",
+  "GET /api/push/key",
+  "GET /api/push/prefs",
+  "GET /api/recordings",
+  "GET /api/recordings/:id",
+  "GET /api/recordings/:id/clips/:n",
+  "GET /api/recordings/:id/export",
+  "GET /api/recordings/:id/replies/:n",
+  "GET /api/recordings/:id/segments/:n",
+  "GET /api/recordings/export",
+  "GET /api/sessions/:session/context",
+  "GET /api/sessions/:session/context-cards",
+  "GET /api/sessions/:session/diff",
+  "GET /api/sessions/:session/model-prefs",
+  "GET /api/sessions/:session/models",
+  "GET /api/sessions/:session/revert/preview",
+  "GET /api/sessions/:session/summary",
+  "GET /api/settings/agent-limits",
+  "GET /api/settings/context-cards",
+  "GET /api/settings/media",
+  "GET /api/settings/recording",
+  "GET /api/settings/speech/default",
+  "GET /api/settings/speech/models",
+  "GET /api/teams/:id/hops",
+  "PATCH /api/agent/app-clients/:id",
+  "PATCH /api/agent/artifacts/:id",
+  "PATCH /api/agent/profiles/:id",
+  "PATCH /api/agent/teams/:id",
+  "PATCH /api/agent/workspaces/:id",
+  "PATCH /api/agent/workspaces/:id/assignments/:assignment",
+  "PATCH /api/agent/workspaces/:id/members/:member",
+  "POST /api/agent/app-clients",
+  "POST /api/agent/app-clients/:id/secret",
+  "POST /api/agent/app-tokens",
+  "POST /api/agent/artifacts",
+  "POST /api/agent/artifacts/:id/archive",
+  "POST /api/agent/artifacts/:id/jobs",
+  "POST /api/agent/artifacts/:id/jobs/:job/apply",
+  "POST /api/agent/artifacts/:id/jobs/:job/cancel",
+  "POST /api/agent/artifacts/:id/jobs/:job/result",
+  "POST /api/agent/artifacts/:id/keep",
+  "POST /api/agent/artifacts/:id/revisions",
+  "POST /api/agent/artifacts/:id/revisions/:rev/host",
+  "POST /api/agent/artifacts/:id/unarchive",
+  "POST /api/agent/artifacts/blobs",
+  "POST /api/agent/ask",
+  "POST /api/agent/concierge/arm",
+  "POST /api/agent/concierge/disable",
+  "POST /api/agent/concierge/enable",
+  "POST /api/agent/concierge/grant-requests",
+  "POST /api/agent/concierge/proposals",
+  "POST /api/agent/concierge/restart",
+  "POST /api/agent/concierge/watchlist/mute",
+  "POST /api/agent/concierge/watchlist/unmute",
+  "POST /api/agent/concierge/watchlist/unwatch",
+  "POST /api/agent/concierge/watchlist/watch",
+  "POST /api/agent/decisions/:id/answer",
+  "POST /api/agent/decline",
+  "POST /api/agent/grants",
+  "POST /api/agent/grants/requests",
+  "POST /api/agent/launches",
+  "POST /api/agent/msg",
+  "POST /api/agent/mute",
+  "POST /api/agent/name",
+  "POST /api/agent/profiles",
+  "POST /api/agent/profiles/:id/versions",
+  "POST /api/agent/profiles/:id/versions/:version/commands/:name/render",
+  "POST /api/agent/profiles/import",
+  "POST /api/agent/reply",
+  "POST /api/agent/roles/claim",
+  "POST /api/agent/roles/release",
+  "POST /api/agent/sessions/:addr/answer",
+  "POST /api/agent/sessions/:addr/approve",
+  "POST /api/agent/sessions/:addr/conversation",
+  "POST /api/agent/sessions/:addr/deny",
+  "POST /api/agent/sessions/:addr/interrupt",
+  "POST /api/agent/sessions/:addr/profile/commands/:name/render",
+  "POST /api/agent/sessions/:addr/prompt",
+  "POST /api/agent/sessions/:addr/stop",
+  "POST /api/agent/sessions/:addr/utterance",
+  "POST /api/agent/sessions/archive-inactive",
+  "POST /api/agent/speech/speak",
+  "POST /api/agent/speech/transcribe",
+  "POST /api/agent/subscriptions",
+  "POST /api/agent/teams",
+  "POST /api/agent/teams/:id/archive",
+  "POST /api/agent/teams/:id/intake",
+  "POST /api/agent/teams/:id/intake/:intake/status",
+  "POST /api/agent/teams/:id/pause",
+  "POST /api/agent/teams/:id/publish",
+  "POST /api/agent/teams/:id/restore",
+  "POST /api/agent/teams/:id/resume",
+  "POST /api/agent/teams/:id/staffing/:staffing/replace",
+  "POST /api/agent/teams/:id/staffing/launch",
+  "POST /api/agent/unmute",
+  "POST /api/agent/webhooks",
+  "POST /api/agent/workspaces",
+  "POST /api/agent/workspaces/:id/archive",
+  "POST /api/agent/workspaces/:id/assignments",
+  "POST /api/agent/workspaces/:id/bindings",
+  "POST /api/agent/workspaces/:id/checkpoints",
+  "POST /api/agent/workspaces/:id/master",
+  "POST /api/agent/workspaces/:id/members",
+  "POST /api/agent/workspaces/:id/restore",
+  "POST /api/agent/workspaces/:id/side-chats",
+  "POST /api/agent/workspaces/:id/side-chats/:chat/refresh",
+  "POST /api/agent/workspaces/:id/side-chats/:chat/send",
+  "POST /api/cli-logins/:code/approve",
+  "POST /api/cli-logins/:code/deny",
+  "POST /api/connect/flows/:flow/approve",
+  "POST /api/connect/flows/:flow/deny",
+  "POST /api/enrollments/:code/approve",
+  "POST /api/enrollments/:code/deny",
+  "POST /api/machines/:machine/sessions",
+  "POST /api/push/subscribe",
+  "POST /api/push/test",
+  "POST /api/push/unsubscribe",
+  "POST /api/recordings",
+  "POST /api/recordings/:id/end",
+  "POST /api/recordings/:id/events",
+  "POST /api/sessions/:session/context-cards/:provider/refresh",
+  "POST /api/sessions/:session/error/dismiss",
+  "POST /api/sessions/:session/fork",
+  "POST /api/sessions/:session/previews",
+  "POST /api/sessions/:session/rename",
+  "POST /api/sessions/:session/revert",
+  "POST /api/sessions/:session/revert/commit",
+  "POST /api/sessions/:session/revert/restore",
+  "POST /api/settings/speech/test",
+  "POST /api/teams/:id/renew",
+  "PUT /api/admin/agents/acting",
+  "PUT /api/admin/users/:id",
+  "PUT /api/agent/acting",
+  "PUT /api/agent/artifacts/:id/visibility",
+  "PUT /api/agent/concierge/notes",
+  "PUT /api/agent/concierge/settings",
+  "PUT /api/agent/concierge/watchlist",
+  "PUT /api/agent/grants/:id",
+  "PUT /api/agent/messaging",
+  "PUT /api/agent/sessions/:addr/archive",
+  "PUT /api/agent/sessions/:addr/intent",
+  "PUT /api/agent/sessions/:addr/pin",
+  "PUT /api/agent/sessions/:addr/profile",
+  "PUT /api/agent/team-settings",
+  "PUT /api/agent/teams/:id/draft/edges",
+  "PUT /api/agent/teams/:id/draft/roles/:role",
+  "PUT /api/agent/teams/:id/staffing",
+  "PUT /api/agent/workspaces/:id/supervision",
+  "PUT /api/push/mute",
+  "PUT /api/push/prefs",
+  "PUT /api/recordings/:id/clips/:n",
+  "PUT /api/recordings/:id/segments/:n",
+  "PUT /api/sessions/:session/model",
+  "PUT /api/sessions/:session/model-prefs",
+  "PUT /api/settings/agent-limits",
+  "PUT /api/settings/context-cards",
+  "PUT /api/settings/media",
+  "PUT /api/settings/recording",
+  "PUT /api/settings/speech",
+  "PUT /api/settings/speech/default"
+]

package/packages/protocol/schema/app-delivery/v1.schema.json

@@ -99,7 +99,10 @@
       "description": "How a message reached its recipient session (Delivery in src/central/agent/messages.ts). `expired`: pending past PENDING_MS or (H2) past its notAfter; never delivered (see expiredReason).",
       "enum": ["steer", "turn", "queued", "retained", "pending", "dropped", "expired"]
     },
-    "WakeSkip": { "enum": ["wake_false", "subagent", "hop_cap", "budget"] },
+    "WakeSkip": {
+      "description": "Why delivery did not wake. item_budget and item_loop were added by team-autonomy phase 2; clients must treat an unknown value as delivered, not woken.",
+      "enum": ["wake_false", "subagent", "hop_cap", "budget", "item_budget", "item_loop"]
+    },
     "Message": {
       "type": "object",
       "required": ["id", "kind", "from", "to", "recipient", "text", "state", "at", "hop"],
@@ -138,7 +141,7 @@
       }
     },
     "AskRequest": {
-      "description": "POST /api/agent/ask (scope messages:send). Optional header Idempotency-Key (H1, per sender). expiresIn and wait are seconds (wait at most 60, never with all). The Decision fields (options … about) are for asks to @me only.",
+      "description": "POST /api/agent/ask (scope messages:send). Optional header Idempotency-Key (H1, per sender). expiresIn and wait are seconds (wait at most 60, never with all). The Decision fields (options … about, choices, kind) are for asks to @me only. (DC-1) choices and options are exclusive.",
       "type": "object",
       "required": ["to", "text"],
       "additionalProperties": false,
@@ -156,6 +159,8 @@
           "items": { "type": "object", "required": ["id", "label"], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "safe": { "type": "boolean" } } }
         },
         "recommendation": { "type": "object", "required": ["option"], "properties": { "option": { "type": "string" }, "why": { "type": "string" } } },
+        "choices": { "type": "array", "minItems": 1, "maxItems": 12, "items": { "$ref": "#/$defs/DecisionChoice" } },
+        "kind": { "$ref": "#/$defs/DecisionKind" },
         "urgency": { "$ref": "#/$defs/DecisionUrgency" },
         "tier": { "$ref": "#/$defs/DecisionTier" },
         "deadline": { "type": "number", "minimum": 0 },
@@ -171,7 +176,8 @@
         "message": { "$ref": "#/$defs/Message" },
         "delivery": { "$ref": "#/$defs/MessageDelivery" },
         "woke": { "type": "boolean" },
-        "wakeSkipped": { "$ref": "#/$defs/WakeSkip" }
+        "wakeSkipped": { "$ref": "#/$defs/WakeSkip" },
+        "wakeLimit": { "type": "number", "minimum": 1, "description": "Effective hop cap, wake budget or item wake budget when the hub provides one." }
       }
     },
     "SentAll": {
@@ -214,6 +220,8 @@
           "items": { "type": "object", "required": ["id", "label"], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "safe": { "const": true } } }
         },
         "recommendation": { "type": "object", "required": ["option"], "properties": { "option": { "type": "string" }, "why": { "type": "string" } } },
+        "choices": { "type": "array", "items": { "$ref": "#/$defs/DecisionChoice" } },
+        "kind": { "$ref": "#/$defs/DecisionKind" },
         "urgency": { "$ref": "#/$defs/DecisionUrgency" },
         "tier": { "$ref": "#/$defs/DecisionTier" },
         "deadline": { "$ref": "#/$defs/EpochMs" },
@@ -226,9 +234,37 @@
           "type": "object",
           "required": ["answeredBy", "at"],
           "description": "answeredBy: user (the console), timeout (the safe onTimeout option), or (AF4, app-front contract §6) app: an app holding decisions:answer answered a confirm-tier Decision of its own session; then `app` is its party (app:<tokenID>) and `appLabel` its label.",
-          "properties": { "option": { "type": "string" }, "text": { "type": "string" }, "answeredBy": { "enum": ["user", "timeout", "app"] }, "at": { "$ref": "#/$defs/EpochMs" }, "app": { "type": "string", "pattern": "^app:[0-9a-f]{16}$" }, "appLabel": { "type": "string" } }
+          "properties": {
+            "option": { "type": "string" },
+            "picks": { "description": "(DC-1) A choices Decision: the option picked in each group.", "type": "object", "additionalProperties": { "type": "string" } },
+            "text": { "type": "string" },
+            "answeredBy": { "enum": ["user", "timeout", "app"] },
+            "at": { "$ref": "#/$defs/EpochMs" },
+            "deviceID": { "type": "string" },
+            "via": { "enum": ["voice", "text"] },
+            "app": { "type": "string", "pattern": "^app:[0-9a-f]{16}$" },
+            "appLabel": { "type": "string" }
+          }
         },
-        "closed": { "type": "object", "required": ["at", "reason"], "properties": { "at": { "$ref": "#/$defs/EpochMs" }, "reason": { "type": "string" } } }
+        "closed": { "type": "object", "required": ["at", "reason"], "properties": { "at": { "$ref": "#/$defs/EpochMs" }, "reason": { "type": "string" } } },
+        "action": { "description": "Set by the hub only (an escalated permission, a grant request, a Concierge proposal, a team hop renewal): its kind and subject.", "type": "object", "required": ["kind"], "properties": { "kind": { "type": "string" } } },
+        "as": { "description": "concierge: asked by one of the user's Concierge sessions.", "const": "concierge" }
+      }
+    },
+    "DecisionKind": { "description": "(DC-1) What an ask is about (absent: a question).", "enum": ["question", "plan", "merge", "release"] },
+    "DecisionChoice": {
+      "description": "(DC-1) One point of a structured ask to @me: 2–6 options, at most one recommended. The answer picks one option per group.",
+      "type": "object",
+      "required": ["id", "label", "options"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,8}$" },
+        "label": { "type": "string", "minLength": 1 },
+        "options": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 6,
+          "items": { "type": "object", "required": ["id", "label"], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "recommended": { "type": "boolean" } } }
+        }
       }
     },
 
@@ -418,6 +454,18 @@
         "lastError": { "type": "string" },
         "updatedAt": { "$ref": "#/$defs/EpochMs" },
         "routedAt": { "$ref": "#/$defs/EpochMs" },
+        "startedAt": { "$ref": "#/$defs/EpochMs", "description": "First active work; pauses and blocked time continue counting against wall-clock budget." },
+        "parentItem": { "type": "string", "description": "Optional root item of a session-submitted child; old stored rows omit this field." },
+        "usage": {
+          "type": "object", "required": ["wakes", "hours", "generation", "budget"], "additionalProperties": false,
+          "properties": {
+            "wakes": { "type": "integer", "minimum": 0 }, "hours": { "type": "number", "minimum": 0 },
+            "generation": { "type": "integer", "minimum": 1 },
+            "chargedTo": { "type": "string" },
+            "budget": { "type": "object", "required": ["wakes", "hours"], "additionalProperties": false,
+              "properties": { "wakes": { "type": "integer", "minimum": 1 }, "hours": { "type": "integer", "minimum": 1 } } }
+          }
+        },
         "closedAt": { "$ref": "#/$defs/EpochMs" },
         "notAfter": { "description": "(H4) As submitted.", "$ref": "#/$defs/EpochMs" }
       }
@@ -459,6 +507,20 @@
       }
     },
 
+    "TeamItemBudgetExhaustedSubject": {
+      "description": "Journal-only team.item_budget.exhausted; webhook subscriptions cannot select this type.",
+      "type": "object", "required": ["teamID"], "additionalProperties": false,
+      "properties": { "teamID": { "type": "string" }, "intakeID": { "type": "string" } }
+    },
+    "TeamItemBudgetExhaustedData": {
+      "description": "One exhaustion per item/reason/generation or once per unattributed pool's rolling 24 h; flat and text-free.",
+      "type": "object", "required": ["scope", "reason", "limit", "usageWakes", "usageHours"], "additionalProperties": false,
+      "properties": {
+        "scope": { "enum": ["item", "pool"] }, "reason": { "enum": ["wakes", "hours"] },
+        "limit": { "type": "number", "minimum": 1 }, "usageWakes": { "type": "integer", "minimum": 0 }, "usageHours": { "type": "number", "minimum": 0 }
+      }
+    },
+
     "LaunchChangedSubject": {
       "type": "object",
       "required": ["launchID"],

package/packages/protocol/schema/app-front/v1.schema.json

@@ -394,17 +394,21 @@
 
     "AnswerableTier": { "description": "(AF4) APP_ANSWERABLE_TIERS: the only tier an app answers (decision w6lfbfaq 1).", "enum": ["confirm"] },
     "DecisionAnswerRequest": {
-      "description": "(AF4) POST /api/agent/decisions/:id/answer (decisions:answer): an option (and an optional note) or text for a Decision without options. No `via`.",
+      "description": "(AF4) POST /api/agent/decisions/:id/answer (decisions:answer): an option (and an optional note) or text for a Decision without options. (DC-1) A choices Decision: picks, one option per group (and an optional note), or text alone. No `via`.",
       "type": "object",
       "additionalProperties": false,
       "minProperties": 1,
-      "properties": { "option": { "type": "string", "minLength": 1, "maxLength": 64 }, "text": { "type": "string", "minLength": 1, "maxLength": 4000 } }
+      "properties": {
+        "option": { "type": "string", "minLength": 1, "maxLength": 64 },
+        "picks": { "type": "object", "minProperties": 1, "maxProperties": 12, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 64 } },
+        "text": { "type": "string", "minLength": 1, "maxLength": 4000 }
+      }
     },
     "AppDecisionAnswer": {
       "description": "(AF4) Decision.answer when an app answered: answeredBy app, the app's party and (when it has one) its label.",
       "type": "object",
       "required": ["answeredBy", "app", "at"],
-      "properties": { "answeredBy": { "const": "app" }, "app": { "type": "string", "pattern": "^app:[0-9a-f]{16}$" }, "appLabel": { "type": "string" }, "option": { "type": "string" }, "text": { "type": "string" }, "at": { "$ref": "#/$defs/EpochMs" } }
+      "properties": { "answeredBy": { "const": "app" }, "app": { "type": "string", "pattern": "^app:[0-9a-f]{16}$" }, "appLabel": { "type": "string" }, "option": { "type": "string" }, "picks": { "type": "object", "additionalProperties": { "type": "string" } }, "text": { "type": "string" }, "at": { "$ref": "#/$defs/EpochMs" } }
     }
   }
 }

package/packages/protocol/src/api-v1.ts

@@ -0,0 +1,8 @@
+// The versioned HTTP API (docs/plans/2026-11-12-api-v1-contract-and-native-app-design.md): what native apps and
+// other clients build against. Pure: names shared by the hub, the spec tooling and the tests.
+
+/**
+ * Every route of the hub's console and agent tables also answers under this prefix: `/api/v1/<rest>` is
+ * `/api/<rest>`, with one error envelope (`{error: {code, message, ...}}`). v1 changes only by addition.
+ */
+export const API_V1_PREFIX = "/api/v1"

package/packages/protocol/src/index.ts

@@ -14,6 +14,7 @@
 // preset.ts (the harness preset schema), webhook.ts (webhook signature format), wire.ts (shared frame primitives).
 // Workspaces/artifacts/teams contracts (HWA-02, docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md):
 // contracts.ts (shared IDs, limits, revisions), hub-workspace.ts, profiles.ts, artifacts.ts, teams.ts, graph.ts.
+// The versioned HTTP API (docs/plans/2026-11-12-api-v1-contract-and-native-app-design.md): api-v1.ts.
 // All are re-exported here.
 
 import { featureList, HUB_URL_MAX_CHARS, ID, isByeFrame as isBye, isHubURL, isObj, isResFrame as isRes, isWelcomeFrame, MAX_FRAME, MAX_RETRY_AFTER_MS, nonEmpty, num, parseFrame as parse, str, token, UNSAFE_CHARS } from "./wire.ts"
@@ -43,6 +44,7 @@ export * from "./teams.ts"
 export * from "./graph.ts"
 export * from "./voice-recording.ts"
 export * from "./app-front.ts"
+export * from "./api-v1.ts"
 export { HUB_URL_MAX_CHARS, isHubURL, MAX_FRAME, MAX_RETRY_AFTER_MS }
 
 export const PROTOCOL_VERSION = 1

package/packages/protocol/src/teams.ts

@@ -19,8 +19,18 @@ export const TEAM_LIMITS = {
   sessionsPerRole: 16,
   /** Open intake items per team. */
   openIntakePerTeam: 500,
+  /** The absolute bound of any hop limit (HOP_ABSOLUTE_MAX); the hub checks team limits against its live ceiling. */
+  hopLimit: 10_000,
 } as const
 
+/**
+ * (HC-1) The largest hop limit or ceiling a hub accepts: about 10 days of continuous agent-only traffic at the rate
+ * #hub-dev measured (~40 hops/h). Past that a cap bounds nothing; "no cap" would be its own decision.
+ */
+export const HOP_ABSOLUTE_MAX = 10_000
+/** (HC-1) The hub's hop ceiling when neither hub.json nor the console sets one. */
+export const HOP_CEILING_DEFAULT = 100
+
 export const TEAM_SCOPES = ["teams:read", "teams:manage", "teams:submit"] as const
 
 /** "open": every member may msg/ask every other member (two-way). "restricted": only the drawn edges. */
@@ -54,6 +64,11 @@ 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
+  /** Optional per-team overrides of the hub-wide item budget and no-progress loop threshold. */
+  readonly itemBudget?: { readonly wakes: number; readonly hours: number }
+  readonly loop?: { readonly messages: number; readonly windowMinutes: number }
   readonly roles: readonly TeamRole[]
   /** The intake role; receives submitted work and supervises members (via workspace supervision). */
   readonly entryRole: string
@@ -182,6 +197,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.1",
+  "version": "0.11.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.10.1",
+  "version": "0.11.1",
   "private": true,
   "description": "The Runtime interface `hub node` runtimes implement (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",