@huynle/hub 0.11.0 → 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,9 +19,18 @@ export const TEAM_LIMITS = {
   sessionsPerRole: 16,
   /** Open intake items per team. */
   openIntakePerTeam: 500,
-  hopLimit: 100,
+  /** 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. */
@@ -57,6 +66,9 @@ export interface TeamDefinition extends Revisioned {
   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

package/packages/runtime-openshell/package.json

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

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-sdk",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "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/app-front.ts

@@ -383,8 +383,8 @@ export interface AppConversation {
 export interface AppDecisions {
   /** The Decisions this app may answer (`state: "open"` for the waiting ones), newest first. */
   list(options?: Signal & { readonly state?: DecisionState }): Promise<{ decisions: Decision[] }>
-  /** Answers one with a once-off option or text; the first answer wins (410 gone after). */
-  answer(id: string, answer: Signal & { readonly option?: string; readonly text?: string }): Promise<DecisionAnswered>
+  /** Answers one with a once-off option, picks (one option per choice group) or text; the first answer wins (410 gone after). */
+  answer(id: string, answer: Signal & { readonly option?: string; readonly text?: string; readonly picks?: Readonly<Record<string, string>> }): Promise<DecisionAnswered>
 }
 
 export function speechApi(hub: AppFrontTransport): AppSpeech {

package/packages/sdk/src/ask-fields.ts

@@ -0,0 +1,76 @@
+// (DC-4) The Decision fields an agent tool sends with an ask to @me (the OpenCode hub tool, the MCP ask tool): their
+// JSON Schema properties and a shape check of a tool call's arguments. The hub validates the values (ids, sizes,
+// one recommendation per group, choices xor options; non-@me asks are 400); this only refuses wrong types early.
+import type { AskOptions } from "./client.ts"
+import type { DecisionKind, DecisionTier, DecisionUrgency } from "./types.ts"
+
+const URGENCIES: readonly DecisionUrgency[] = ["low", "normal", "high"]
+const TIERS: readonly DecisionTier[] = ["confirm", "tap"]
+const KINDS: readonly DecisionKind[] = ["question", "plan", "merge", "release"]
+
+/** JSON Schema properties of the ask @me Decision fields. */
+export const DECISION_ASK_PROPERTIES = {
+  options: {
+    type: "array",
+    items: { type: "object", properties: { id: { type: "string" }, label: { type: "string" }, safe: { type: "boolean" } }, required: ["id", "label"] },
+    description: "ask @me: buttons the user taps, [{id, label, safe?}] (at most 8; id: lowercase letters, digits, - or _).",
+  },
+  recommendation: {
+    type: "object",
+    properties: { option: { type: "string" }, why: { type: "string" } },
+    required: ["option"],
+    description: "ask @me: the option you recommend ({option: an option id, why}).",
+  },
+  urgency: { type: "string", enum: [...URGENCIES], description: "ask @me: low, normal (default) or high." },
+  tier: { type: "string", enum: [...TIERS], description: "ask @me: confirm (default: any of the user's devices) or tap (only the signed-in console)." },
+  kind: { type: "string", enum: [...KINDS], description: "ask @me: what it is about: question (default), plan, merge or release." },
+  choices: {
+    type: "array",
+    items: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        label: { type: "string" },
+        options: { type: "array", items: { type: "object", properties: { id: { type: "string" }, label: { type: "string" }, recommended: { type: "boolean" } }, required: ["id", "label"] } },
+      },
+      required: ["id", "label", "options"],
+    },
+    description: 'ask @me: several points in one ask, instead of options: [{id: "D1", label, options: [{id, label, recommended?}]}], 1–12 groups of 2–6 options, at most one recommended each; the user picks one option per group and you get one "D1: label [a]" line per group.',
+  },
+} as const
+
+export const DECISION_ASK_FIELDS = Object.keys(DECISION_ASK_PROPERTIES) as readonly (keyof typeof DECISION_ASK_PROPERTIES)[]
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/**
+ * The Decision fields of a tool call's arguments (only those given), shape-checked. Throws an Error naming the field
+ * for a wrong type; the hub checks the values.
+ */
+export function decisionAskFields(args: Readonly<Record<string, unknown>>): Partial<AskOptions> {
+  const out: Record<string, unknown> = {}
+  const { options, recommendation, urgency, tier, kind, choices } = args
+  const objects = (value: unknown, field: string, shape: string) => {
+    if (!Array.isArray(value) || !value.every(isObject)) throw new Error(`"${field}" must be a list of ${shape}`)
+    return value
+  }
+  if (options !== undefined) out.options = objects(options, "options", "{id, label, safe?}")
+  if (recommendation !== undefined) {
+    if (!isObject(recommendation) || typeof recommendation.option !== "string") throw new Error(`"recommendation" must be {option, why?}`)
+    out.recommendation = recommendation
+  }
+  const oneOf = (value: unknown, field: string, allowed: readonly string[]) => {
+    if (value === undefined) return
+    if (typeof value !== "string" || !allowed.includes(value)) throw new Error(`"${field}" is one of ${allowed.join(", ")}`)
+    out[field] = value
+  }
+  oneOf(urgency, "urgency", URGENCIES)
+  oneOf(tier, "tier", TIERS)
+  oneOf(kind, "kind", KINDS)
+  if (choices !== undefined) {
+    const shape = "{id, label, options: [{id, label, recommended?}]}"
+    for (const group of objects(choices, "choices", shape)) objects(group.options, "choices", shape)
+    out.choices = choices
+  }
+  return out as Partial<AskOptions>
+}