@huynle/hub 0.10.1 → 0.11.1

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

@@ -0,0 +1,635 @@
+{
+  "paths": {
+    "/api/v1/decisions": {
+      "get": {
+        "operationId": "listDecisions",
+        "tags": ["decisions"],
+        "x-hub-access": "user",
+        "summary": "The user's Decisions",
+        "description": "What agents and apps asked the user (an ask to @me). Fails with 400 invalid for an unknown state.",
+        "parameters": [
+          {
+            "name": "state",
+            "in": "query",
+            "description": "Only Decisions in this state.",
+            "schema": {
+              "type": "string",
+              "enum": ["open", "answered", "expired", "closed"]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Newest first.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DecisionList"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/decisions/{id}": {
+      "get": {
+        "operationId": "getDecision",
+        "tags": ["decisions"],
+        "x-hub-access": "user",
+        "summary": "One Decision",
+        "description": "Fails with 404 not_found for an unknown ID or another user's.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The Decision's ID (dec_…).",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The Decision.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DecisionDetail"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/decisions/{id}/answer": {
+      "post": {
+        "operationId": "answerDecision",
+        "tags": ["decisions"],
+        "x-hub-access": "user",
+        "summary": "Answer a Decision",
+        "description": "An option (with an optional note in text), or text alone for a Decision without options. The first answer wins: later ones fail with 409 gone, as does an expired Decision. A tap-tier Decision is answered only from the signed-in console (the device cookie): with a device token it fails with 403 forbidden. Voice and text answers (via) are for confirm-tier Decisions the Concierge panel admits, and pick only once-off options (else 403 forbidden). Other failures: 400 invalid (no such option, no text), 404 not_found; a Decision whose action fails opens again.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "The Decision's ID (dec_…).",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DecisionAnswerRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The answered Decision and the reply the asker got.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AnsweredDecision"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "DecisionList": {
+        "type": "object",
+        "required": ["decisions"],
+        "properties": {
+          "decisions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/Decision"
+            }
+          }
+        }
+      },
+      "DecisionDetail": {
+        "type": "object",
+        "required": ["decision"],
+        "properties": {
+          "decision": {
+            "$ref": "#/components/schemas/Decision"
+          }
+        }
+      },
+      "AnsweredDecision": {
+        "type": "object",
+        "required": ["decision"],
+        "properties": {
+          "decision": {
+            "$ref": "#/components/schemas/Decision"
+          },
+          "reply": {
+            "$ref": "#/components/schemas/AgentMessage",
+            "description": "The user's reply to the ask (absent when the ask could not be replied to)."
+          }
+        }
+      },
+      "DecisionAnswerRequest": {
+        "type": "object",
+        "description": "An option, text, or both; for a Decision with choices, picks (one option per group), text, or both.",
+        "properties": {
+          "option": {
+            "type": "string",
+            "description": "The ID of the option picked."
+          },
+          "picks": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "A Decision with choices: the option picked in every group ({group: option}). Text alone is accepted instead."
+          },
+          "text": {
+            "type": "string",
+            "description": "A note with the option, or the answer of a Decision without options (at most 4000 characters)."
+          },
+          "via": {
+            "type": "string",
+            "enum": ["tap", "voice", "text"],
+            "description": "How the user answered (default tap). voice and text only in the Concierge panel."
+          }
+        }
+      },
+      "Decision": {
+        "type": "object",
+        "description": "A question an agent or app asked the user (an ask to @me).",
+        "required": ["id", "messageID", "from", "about", "question", "options", "urgency", "tier", "state", "at", "expiresAt"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "messageID": {
+            "type": "string",
+            "description": "The ask (to @me) that carries it."
+          },
+          "from": {
+            "$ref": "#/components/schemas/Party"
+          },
+          "about": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The sessions it concerns."
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "The session a notification opens (about[0])."
+          },
+          "question": {
+            "type": "string"
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/DecisionOption"
+            },
+            "description": "At most 8; none: the user answers with text."
+          },
+          "recommendation": {
+            "$ref": "#/components/schemas/DecisionRecommendation"
+          },
+          "choices": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/DecisionChoice"
+            },
+            "description": "Structured choices (1–12 groups), instead of options: the user picks one option in each group."
+          },
+          "kind": {
+            "type": "string",
+            "x-hub-known": ["question", "plan", "merge", "release"],
+            "description": "What it is about; absent: a question."
+          },
+          "urgency": {
+            "type": "string",
+            "x-hub-known": ["low", "normal", "high"]
+          },
+          "tier": {
+            "type": "string",
+            "x-hub-known": ["confirm", "tap"],
+            "description": "confirm: any of the user's signed-in devices answers; tap: only the signed-in console (the device cookie)."
+          },
+          "deadline": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When it times out, in epoch milliseconds."
+          },
+          "onTimeout": {
+            "type": "string",
+            "description": "The (safe) option picked at the deadline. Without one the Decision stays open and is escalated."
+          },
+          "state": {
+            "type": "string",
+            "x-hub-known": ["open", "answered", "expired", "closed"],
+            "description": "closed: it ended without an answer because what it asked about went away."
+          },
+          "at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When it was asked, in epoch milliseconds."
+          },
+          "expiresAt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When it expires with its ask, in epoch milliseconds."
+          },
+          "escalatedAt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "When it passed its deadline without an onTimeout (notified again), in epoch milliseconds."
+          },
+          "answer": {
+            "$ref": "#/components/schemas/DecisionAnswer"
+          },
+          "closed": {
+            "$ref": "#/components/schemas/DecisionClosed"
+          },
+          "action": {
+            "$ref": "#/components/schemas/DecisionAction"
+          },
+          "as": {
+            "type": "string",
+            "x-hub-known": ["concierge"],
+            "description": "concierge: asked by one of the user's Concierge sessions."
+          }
+        }
+      },
+      "DecisionOption": {
+        "type": "object",
+        "required": ["id", "label"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "safe": {
+            "type": "boolean",
+            "description": "onTimeout may pick only a safe option."
+          }
+        }
+      },
+      "DecisionChoice": {
+        "type": "object",
+        "required": ["id", "label", "options"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "The group's ID (1–8 letters, digits, - or _), e.g. D1."
+          },
+          "label": {
+            "type": "string"
+          },
+          "options": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/DecisionChoiceOption"
+            },
+            "description": "2–6 options."
+          }
+        }
+      },
+      "DecisionChoiceOption": {
+        "type": "object",
+        "required": ["id", "label"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "label": {
+            "type": "string"
+          },
+          "recommended": {
+            "type": "boolean",
+            "description": "The asker's recommendation (at most one per group)."
+          }
+        }
+      },
+      "DecisionRecommendation": {
+        "type": "object",
+        "required": ["option"],
+        "properties": {
+          "option": {
+            "type": "string",
+            "description": "An option's ID."
+          },
+          "why": {
+            "type": "string"
+          }
+        }
+      },
+      "DecisionAnswer": {
+        "type": "object",
+        "required": ["answeredBy", "at"],
+        "properties": {
+          "option": {
+            "type": "string"
+          },
+          "picks": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "A Decision with choices: the option picked in each group."
+          },
+          "text": {
+            "type": "string"
+          },
+          "answeredBy": {
+            "type": "string",
+            "x-hub-known": ["user", "timeout", "app"],
+            "description": "user; timeout: onTimeout picked it; app: an app answered a Decision of its own session."
+          },
+          "at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "In epoch milliseconds."
+          },
+          "deviceID": {
+            "type": "string",
+            "description": "The device the user answered from."
+          },
+          "via": {
+            "type": "string",
+            "x-hub-known": ["voice", "text"],
+            "description": "Absent: a tap."
+          },
+          "app": {
+            "type": "string",
+            "description": "answeredBy app: the app's party (app:<tokenID>)."
+          },
+          "appLabel": {
+            "type": "string",
+            "description": "answeredBy app: its label."
+          }
+        }
+      },
+      "DecisionClosed": {
+        "type": "object",
+        "description": "Why it closed without an answer.",
+        "required": ["at", "reason"],
+        "properties": {
+          "at": {
+            "type": "integer",
+            "format": "int64",
+            "description": "In epoch milliseconds."
+          },
+          "reason": {
+            "type": "string"
+          }
+        }
+      },
+      "DecisionAction": {
+        "description": "What answering does besides replying, set by the hub: an escalated permission request, a grant request, a Concierge proposal or a team's hop budget renewal.",
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/PermissionDecisionAction"
+          },
+          {
+            "$ref": "#/components/schemas/GrantDecisionAction"
+          },
+          {
+            "$ref": "#/components/schemas/ActDecisionAction"
+          },
+          {
+            "$ref": "#/components/schemas/TeamHopRenewDecisionAction"
+          },
+          {
+            "$ref": "#/components/schemas/TeamItemDecisionAction"
+          }
+        ],
+        "discriminator": {
+          "propertyName": "kind",
+          "mapping": {
+            "permission": "#/components/schemas/PermissionDecisionAction",
+            "grant": "#/components/schemas/GrantDecisionAction",
+            "act": "#/components/schemas/ActDecisionAction",
+            "teamHopRenew": "#/components/schemas/TeamHopRenewDecisionAction",
+            "teamItem": "#/components/schemas/TeamItemDecisionAction"
+          }
+        },
+        "x-hub-union": true
+      },
+      "PermissionDecisionAction": {
+        "type": "object",
+        "description": "An escalated permission request: the answer replies to it as the user.",
+        "required": ["kind", "requestID", "rootID", "sessionID", "always"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["permission"]
+          },
+          "requestID": {
+            "type": "string"
+          },
+          "rootID": {
+            "type": "string",
+            "description": "The tree the request is pending in."
+          },
+          "sessionID": {
+            "type": "string",
+            "description": "The session that asked."
+          },
+          "always": {
+            "type": "boolean",
+            "description": "The agent asked to approve it always."
+          },
+          "request": {
+            "$ref": "#/components/schemas/DecisionRequest"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Why the hub sent it to the user."
+          }
+        }
+      },
+      "GrantDecisionAction": {
+        "type": "object",
+        "description": "A grant an agent requested: approving creates it as the user.",
+        "required": ["kind", "requester", "grant"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["grant"]
+          },
+          "requester": {
+            "type": "string",
+            "description": "The requester's party key."
+          },
+          "grant": {
+            "$ref": "#/components/schemas/JsonValue",
+            "description": "The grant body requested (an object; described with the grants area)."
+          },
+          "managed": {
+            "type": "boolean",
+            "description": "The Concierge's own request."
+          }
+        }
+      },
+      "ActDecisionAction": {
+        "type": "object",
+        "description": "A Concierge proposal: go runs the verb as the user; hold does nothing.",
+        "required": ["kind", "verb", "target", "input"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["act"]
+          },
+          "verb": {
+            "type": "string",
+            "x-hub-known": ["stop", "deny", "prompt", "answer"]
+          },
+          "target": {
+            "type": "string",
+            "description": "The session it was proposed for."
+          },
+          "input": {
+            "$ref": "#/components/schemas/JsonValue",
+            "description": "The verb's input (an object: requestID, formID, answer, text)."
+          },
+          "request": {
+            "$ref": "#/components/schemas/DecisionRequest"
+          }
+        }
+      },
+      "TeamHopRenewDecisionAction": {
+        "type": "object",
+        "description": "Renewing a team's hop budget (tap only).",
+        "required": ["kind", "teamID"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["teamHopRenew"]
+          },
+          "teamID": {
+            "type": "string"
+          }
+        }
+      },
+      "TeamItemDecisionAction": {
+        "type": "object",
+        "description": "Extend or Stop one intake item that spent its budget or whose seat pair loops without progress (tap only, hub-created).",
+        "required": ["kind", "teamID", "item", "reason"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["teamItem"]
+          },
+          "teamID": {
+            "type": "string"
+          },
+          "item": {
+            "type": "string",
+            "description": "The intake item (itk_…)."
+          },
+          "reason": {
+            "type": "string",
+            "x-hub-known": ["budget", "loop"],
+            "description": "budget: the item spent its wake or time budget; loop: a seat pair loops without progress."
+          },
+          "pair": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "reason loop: the two seat sessions that loop, sorted."
+          }
+        }
+      },
+      "DecisionRequest": {
+        "type": "object",
+        "description": "A permission request as a Decision shows it.",
+        "required": ["action", "resources"],
+        "properties": {
+          "action": {
+            "type": "string"
+          },
+          "resources": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "At most 20, each at most 2000 characters."
+          },
+          "save": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The patterns an always would save."
+          },
+          "resourcesTotal": {
+            "type": "integer",
+            "format": "int32",
+            "description": "How many resources the request had, when more than were kept."
+          },
+          "savesTotal": {
+            "type": "integer",
+            "format": "int32",
+            "description": "How many save patterns it had, when more than were kept."
+          },
+          "cut": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/DecisionRequestCut"
+            },
+            "description": "Items that were shortened, with their full length."
+          },
+          "truncated": {
+            "type": "boolean",
+            "description": "The hub received the request already shortened."
+          }
+        }
+      },
+      "DecisionRequestCut": {
+        "type": "object",
+        "required": ["field", "index", "length"],
+        "properties": {
+          "field": {
+            "type": "string",
+            "x-hub-known": ["resources", "save"]
+          },
+          "index": {
+            "type": "integer",
+            "format": "int32"
+          },
+          "length": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Its full length."
+          }
+        }
+      }
+    }
+  }
+}