@huynle/hub 0.10.1 → 0.11.1

package/packages/protocol/schema/api/v1/session-actions.json

@@ -0,0 +1,660 @@
+{
+  "paths": {
+    "/api/v1/sessions/{session}/turn": {
+      "post": {
+        "operationId": "promptSession",
+        "tags": [
+          "session-actions"
+        ],
+        "x-hub-access": "session",
+        "summary": "Prompt a session",
+        "description": "Sends typed text (and images) to the session. While anything in the session's tree runs, the prompt is steered into the running work and the answer is 202 at once with `mode: \"steer\"`. Otherwise it starts a turn, and the request waits for the turn to end and answers 200 with its result (a turn may run for minutes; this request never times out on the hub, and a stop or interrupt ends it at once as `interrupted`). With `Prefer: respond-async`, a turn still running after a short accept window (1.5 s) is answered 202 `{mode: \"turn\"}` with `Preference-Applied: respond-async`; its result then comes on the live stream as a `turn` message `{type: \"turn\", sessionID, outcome, reply, message?}` (a failure there is `outcome: \"failed\"` with the error's message, or `timeout`), while the reply streams meanwhile; a turn that ends within the window, and every refusal, answers as without the header. Fails with 400 invalid (empty prompt, text over 100,000 characters, an image that is not acceptable), 409 conflict when no process of the session is connected, 409 conflict while another turn holds the session, 409 unsupported (with `feature` and `harness`) when the session's spoke does not serve the action, 502 upstream_failed when the spoke fails the turn and 504 timeout when the hub stops waiting for it.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID. A session of another user, or one the hub does not know, answers 404 not_found.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "Prefer",
+            "in": "header",
+            "required": false,
+            "description": "`respond-async`: do not wait for a long turn; answer 202 and send its result on the live stream (RFC 7240). Other preferences are ignored.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/TurnRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The turn ended: its result.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TurnResult"
+                }
+              }
+            }
+          },
+          "202": {
+            "description": "Accepted, not finished: steered into the running work (`mode: \"steer\"`, without the Prefer header too), or with `Prefer: respond-async` a turn still running (`mode: \"turn\"`, its result comes on the live stream).",
+            "headers": {
+              "Preference-Applied": {
+                "description": "`respond-async` when the turn was accepted to finish in the background; absent for a steer.",
+                "schema": {
+                  "type": "string"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/TurnAccepted"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}/interrupt": {
+      "post": {
+        "operationId": "interruptSession",
+        "tags": [
+          "session-actions"
+        ],
+        "x-hub-access": "session",
+        "summary": "Interrupt a session (barge-in)",
+        "description": "Interrupts the session's current work; while a voice front is active, the front is interrupted instead (barge-in), not the session's work. A turn request in flight ends at once as `interrupted`. The request has no body. Fails with 409 conflict when no process of the session is connected, 409 unsupported (with `feature` and `harness`) when the session's spoke does not serve the action and 502 upstream_failed when the spoke fails it.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID. A session of another user, or one the hub does not know, answers 404 not_found.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Interrupted."
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}/stop": {
+      "post": {
+        "operationId": "stopSession",
+        "tags": [
+          "session-actions"
+        ],
+        "x-hub-access": "session",
+        "summary": "Stop a session and its subagents",
+        "description": "Stops the session's work and the subagent sessions it runs. A turn request in flight ends at once as `interrupted`. The request has no body. Fails with 409 conflict when no process of the session is connected, 409 unsupported (with `feature` and `harness`) when the session's spoke does not serve the action and 502 upstream_failed when the spoke fails it.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID. A session of another user, or one the hub does not know, answers 404 not_found.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Stopped: what the spoke stopped.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/StopResult"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}/permission": {
+      "post": {
+        "operationId": "answerPermission",
+        "tags": [
+          "session-actions"
+        ],
+        "x-hub-access": "session",
+        "summary": "Answer a permission request",
+        "description": "Answers a pending permission request in the session's tree (a subagent's request is answered through its root session, the one in the path). Fails with 400 invalid for a missing request ID or an unknown decision, 409 gone when the request is not pending any more (answered elsewhere or expired), 409 unsupported (with `feature` and `harness`) when the session's spoke does not serve the action and 502 upstream_failed when the spoke fails it.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID. A session of another user, or one the hub does not know, answers 404 not_found.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PermissionAnswer"
+              }
+            }
+          }
+        },
+        "responses": {
+          "204": {
+            "description": "Answered."
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}/form": {
+      "post": {
+        "operationId": "answerForm",
+        "tags": [
+          "session-actions"
+        ],
+        "x-hub-access": "session",
+        "summary": "Answer or cancel a form (a question)",
+        "description": "Answers a pending form of the session's tree, or cancels it: send `answer` or `cancel: true`, never both. Fails with 400 invalid (no form ID, both or neither, an answer that is not acceptable), 409 gone when the form is not pending any more, 409 unsupported (with `feature` and `harness`) when the session's spoke does not serve the action and 502 upstream_failed when the spoke fails it.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID. A session of another user, or one the hub does not know, answers 404 not_found.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/FormSubmission"
+              }
+            }
+          }
+        },
+        "responses": {
+          "204": {
+            "description": "Answered or cancelled."
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}/expose": {
+      "post": {
+        "operationId": "exposeSession",
+        "tags": [
+          "session-actions"
+        ],
+        "x-hub-access": "session",
+        "summary": "Turn Voice on or off for a session",
+        "description": "Enables or disables Voice (speech and conversation mode) for the session, through a process that reports it (its machine's background service first). Allowed while Voice is off. Fails with 400 invalid without a boolean `on`, 404 not_found when no connected process can do it, and 502 upstream_failed when the spoke fails it.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID. A session of another user, or one the hub does not know, answers 404 not_found.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ExposeRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Whether Voice is on now.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ExposeResult"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}/conversation": {
+      "post": {
+        "operationId": "setConversation",
+        "tags": [
+          "session-actions"
+        ],
+        "x-hub-access": "session",
+        "summary": "Turn conversation mode on or off",
+        "description": "Conversation mode (hands-free Voice) on or off for the session. When turned on, the session's spoke may put a voice front in front of it (a separate session that talks with the user and relays to this one): it is asked for unless `front: false`. The live stream reports the change. Answers 403 not_exposed while Voice is off for the session (it is listed for discovery only; POST …/expose turns Voice on). Fails with 400 invalid (no boolean `on`, a `front` that is not a boolean), 409 conflict when no process of the session is connected and 502 upstream_failed when the spoke fails it.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID. A session of another user, or one the hub does not know, answers 404 not_found.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ConversationRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The mode now.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConversationState"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}/utterance": {
+      "post": {
+        "operationId": "sendUtterance",
+        "tags": [
+          "session-actions"
+        ],
+        "x-hub-access": "session",
+        "summary": "Say something to a session (conversation mode)",
+        "description": "Steers what the user said into the session (allowed while it is busy; while a voice front is active, to the front, which relays it) and answers at once. The utterance is tracked: when the session takes it, the live stream says so (a `heard` message with the inbox ID). Answers 403 not_exposed while Voice is off for the session (it is listed for discovery only; POST …/expose turns Voice on). Fails with 400 invalid (empty, or over 4,000 characters after trimming), 409 conflict when no process of the session is connected, 409 unsupported (with `feature` and `harness`) when the session's spoke does not serve the action and 502 upstream_failed when the spoke fails it.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID. A session of another user, or one the hub does not know, answers 404 not_found.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UtteranceRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "Accepted: the inbox ID of the utterance.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UtteranceAccepted"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    },
+    "/api/v1/sessions/{session}/presence": {
+      "post": {
+        "operationId": "setSessionPresence",
+        "tags": [
+          "session-actions"
+        ],
+        "x-hub-access": "session",
+        "summary": "Say whether this device shows the session",
+        "description": "Whether the session is on this device's screen now: while a device shows a session (or another of its tree), the hub sends no push notification for what it says. Send it when that changes and again every 30 seconds while visible; a report counts for 45 seconds. Allowed while Voice is off. Fails with 400 invalid without a boolean `visible`.",
+        "parameters": [
+          {
+            "name": "session",
+            "in": "path",
+            "required": true,
+            "description": "The session's ID. A session of another user, or one the hub does not know, answers 404 not_found.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PresenceRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "204": {
+            "description": "Recorded."
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "TurnRequest": {
+        "type": "object",
+        "required": [
+          "text"
+        ],
+        "properties": {
+          "text": {
+            "type": "string",
+            "description": "The prompt, at most 100,000 characters after trimming. May be empty only when images are attached."
+          },
+          "images": {
+            "type": "array",
+            "maxItems": 4,
+            "description": "Images to attach, at most 4. An empty list is the same as none.",
+            "items": {
+              "$ref": "#/components/schemas/PromptImage"
+            }
+          }
+        }
+      },
+      "PromptImage": {
+        "type": "object",
+        "required": [
+          "mime",
+          "data"
+        ],
+        "description": "An image attached to a prompt. Each at most 512 KB decoded, together at most 750,000 base64 characters; the bytes must be of the declared type.",
+        "properties": {
+          "mime": {
+            "type": "string",
+            "enum": [
+              "image/png",
+              "image/jpeg",
+              "image/webp",
+              "image/gif"
+            ]
+          },
+          "data": {
+            "type": "string",
+            "description": "The image's bytes, canonical base64 (padded, no line breaks)."
+          },
+          "name": {
+            "type": "string",
+            "maxLength": 200,
+            "description": "The file name, for display."
+          }
+        }
+      },
+      "TurnResult": {
+        "type": "object",
+        "required": [
+          "outcome",
+          "reply"
+        ],
+        "properties": {
+          "outcome": {
+            "type": "string",
+            "description": "succeeded; failed or interrupted (with `message`); timeout: the harness stopped waiting (the reply so far).",
+            "x-hub-known": [
+              "succeeded",
+              "failed",
+              "interrupted",
+              "timeout"
+            ]
+          },
+          "reply": {
+            "type": "string",
+            "description": "The turn's reply text, possibly partial or empty."
+          },
+          "message": {
+            "type": "string",
+            "description": "Why it failed or was interrupted (\"Stopped\" for a stop or interrupt through the hub)."
+          }
+        }
+      },
+      "TurnAccepted": {
+        "type": "object",
+        "required": [
+          "mode"
+        ],
+        "properties": {
+          "mode": {
+            "type": "string",
+            "description": "steer: the prompt went into the running work (`inboxID`). turn: a new turn runs in the background (Prefer: respond-async); its result comes on the live stream.",
+            "x-hub-known": [
+              "steer",
+              "turn"
+            ]
+          },
+          "inboxID": {
+            "type": "string",
+            "description": "steer: the steered input's ID."
+          }
+        }
+      },
+      "StopResult": {
+        "type": "object",
+        "required": [
+          "stopped"
+        ],
+        "properties": {
+          "stopped": {
+            "type": "array",
+            "description": "The IDs of the sessions stopped (the session and its subagents).",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "PermissionAnswer": {
+        "type": "object",
+        "required": [
+          "requestID",
+          "decision"
+        ],
+        "properties": {
+          "requestID": {
+            "type": "string",
+            "description": "The permission blocker's ID."
+          },
+          "decision": {
+            "type": "string",
+            "enum": [
+              "once",
+              "always",
+              "reject"
+            ],
+            "description": "once: allow this time. always: allow this and the same kind of request from now on. reject: refuse."
+          }
+        }
+      },
+      "FormSubmission": {
+        "type": "object",
+        "required": [
+          "formID"
+        ],
+        "properties": {
+          "formID": {
+            "type": "string",
+            "maxLength": 300,
+            "description": "The form blocker's ID, 1 to 300 characters."
+          },
+          "answer": {
+            "type": "object",
+            "maxProperties": 50,
+            "description": "Field key (1 to 300 characters) → value, at most 50 fields. A value by the field's type: string → text, number and integer → a number, boolean → true or false, multiselect → a list of texts (at most 100); external fields take no value. Texts at most 20,000 characters each. Anything else (an object, null) is refused. Required unless `cancel` is true.",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/JsonValue"
+            }
+          },
+          "cancel": {
+            "type": "boolean",
+            "description": "true: dismiss the form instead of answering it (send no `answer`)."
+          }
+        }
+      },
+      "ExposeRequest": {
+        "type": "object",
+        "required": [
+          "on"
+        ],
+        "properties": {
+          "on": {
+            "type": "boolean"
+          }
+        }
+      },
+      "ExposeResult": {
+        "type": "object",
+        "required": [
+          "exposed"
+        ],
+        "properties": {
+          "exposed": {
+            "type": "boolean",
+            "description": "Whether Voice is on for the session now."
+          }
+        }
+      },
+      "ConversationRequest": {
+        "type": "object",
+        "required": [
+          "on"
+        ],
+        "properties": {
+          "on": {
+            "type": "boolean"
+          },
+          "front": {
+            "type": "boolean",
+            "description": "false: no voice front (this device opted out). Absent or true: a front when the session's spoke serves one."
+          }
+        }
+      },
+      "ConversationState": {
+        "type": "object",
+        "required": [
+          "on"
+        ],
+        "properties": {
+          "on": {
+            "type": "boolean"
+          },
+          "agent": {
+            "type": "string",
+            "description": "The session's agent, as its spoke reports it."
+          },
+          "front": {
+            "type": "boolean",
+            "description": "Whether a voice front is in front of the session now. Present when a front was asked for, and when turning off a session that had one."
+          }
+        }
+      },
+      "UtteranceRequest": {
+        "type": "object",
+        "required": [
+          "text"
+        ],
+        "properties": {
+          "text": {
+            "type": "string",
+            "description": "What the user said, at most 4,000 characters after trimming."
+          }
+        }
+      },
+      "UtteranceAccepted": {
+        "type": "object",
+        "required": [
+          "inboxID"
+        ],
+        "properties": {
+          "inboxID": {
+            "type": "string",
+            "description": "The utterance's inbox ID, as the live stream's `heard` message names it."
+          }
+        }
+      },
+      "PresenceRequest": {
+        "type": "object",
+        "required": [
+          "visible"
+        ],
+        "properties": {
+          "visible": {
+            "type": "boolean",
+            "description": "Whether this device shows the session now."
+          }
+        }
+      }
+    }
+  }
+}