@breign/client 1.0.138 → 1.0.139

package/dist/openapi.json

@@ -8054,6 +8054,206 @@
         "tags" : [ "metrics" ]
       }
     },
+    "/organizations/{organizationId}/tool-approvals" : {
+      "get" : {
+        "description" : "Returns the approvals the CALLER granted in this organisation, newest first. Revoking one deletes it, so every approval returned is a right in force — there is no expiry and no revoked state to filter out. Never another user's: an approval is a personal consent.",
+        "operationId" : "listToolApprovals",
+        "parameters" : [ {
+          "description" : "ID of the organization",
+          "in" : "path",
+          "name" : "organizationId",
+          "required" : true,
+          "schema" : {
+            "type" : "string"
+          }
+        }, {
+          "description" : "Restricts the listing to one agent: its own approvals plus the organisation-wide ones, which apply to it as well. Omitted, everything the caller granted in the organisation.",
+          "in" : "query",
+          "name" : "agentId",
+          "required" : false,
+          "schema" : {
+            "type" : "string"
+          }
+        } ],
+        "responses" : {
+          "200" : {
+            "content" : {
+              "application/json" : {
+                "schema" : {
+                  "$ref" : "#/components/schemas/ToolApprovalsResponse"
+                }
+              }
+            },
+            "description" : "Approvals granted by the caller"
+          },
+          "401" : {
+            "description" : "Unauthorized"
+          },
+          "403" : {
+            "description" : "Forbidden"
+          }
+        },
+        "summary" : "List the operations the caller has authorised",
+        "tags" : [ "organizations" ]
+      },
+      "post" : {
+        "description" : "Creates an approval without waiting for the agent to ask for one — preparing an agent rather than answering its questions. It widens no boundary: the value goes through the same validation as an in-conversation approval, the scope is the only one open (this agent, for the caller), and the author is the caller. Granting a value that is already granted returns the existing approval rather than a duplicate.",
+        "operationId" : "createToolApproval",
+        "parameters" : [ {
+          "description" : "ID of the organization",
+          "in" : "path",
+          "name" : "organizationId",
+          "required" : true,
+          "schema" : {
+            "type" : "string"
+          }
+        } ],
+        "requestBody" : {
+          "content" : {
+            "application/json" : {
+              "schema" : {
+                "$ref" : "#/components/schemas/createToolApproval_request"
+              }
+            }
+          },
+          "required" : true
+        },
+        "responses" : {
+          "201" : {
+            "content" : {
+              "application/json" : {
+                "schema" : {
+                  "$ref" : "#/components/schemas/ToolApproval"
+                }
+              }
+            },
+            "description" : "Approval granted"
+          },
+          "400" : {
+            "description" : "The value is not valid for that family"
+          },
+          "401" : {
+            "description" : "Unauthorized"
+          },
+          "403" : {
+            "description" : "Forbidden, or no access to that agent"
+          },
+          "404" : {
+            "description" : "No such agent in this organisation"
+          },
+          "503" : {
+            "description" : "Tool approvals are not configured on this deployment"
+          }
+        },
+        "summary" : "Grant an approval by hand",
+        "tags" : [ "organizations" ]
+      }
+    },
+    "/organizations/{organizationId}/tool-approvals/{approvalId}" : {
+      "delete" : {
+        "description" : "Takes back one approval the caller granted. The approval is deleted, and the agent asks again the next time it needs that operation. It takes effect on the agent's next turn.",
+        "operationId" : "revokeToolApproval",
+        "parameters" : [ {
+          "description" : "ID of the organization",
+          "in" : "path",
+          "name" : "organizationId",
+          "required" : true,
+          "schema" : {
+            "type" : "string"
+          }
+        }, {
+          "description" : "Identifier of the approval, as returned by the listing.",
+          "in" : "path",
+          "name" : "approvalId",
+          "required" : true,
+          "schema" : {
+            "type" : "string"
+          }
+        } ],
+        "responses" : {
+          "204" : {
+            "description" : "Approval revoked"
+          },
+          "401" : {
+            "description" : "Unauthorized"
+          },
+          "403" : {
+            "description" : "Forbidden"
+          },
+          "404" : {
+            "description" : "No such approval granted by the caller in this organisation"
+          },
+          "503" : {
+            "description" : "Tool approvals are not configured on this deployment"
+          }
+        },
+        "summary" : "Revoke an approval",
+        "tags" : [ "organizations" ]
+      },
+      "patch" : {
+        "description" : "Rewrites what one approval covers — widening an address into a pattern, or correcting a command. Only an approval the caller granted himself, and only its resource: the scope, the agent and the author never change. An approval cannot be created this way; a right only ever starts with a question the agent actually asked.",
+        "operationId" : "editToolApproval",
+        "parameters" : [ {
+          "description" : "ID of the organization",
+          "in" : "path",
+          "name" : "organizationId",
+          "required" : true,
+          "schema" : {
+            "type" : "string"
+          }
+        }, {
+          "description" : "Identifier of the approval, as returned by the listing.",
+          "in" : "path",
+          "name" : "approvalId",
+          "required" : true,
+          "schema" : {
+            "type" : "string"
+          }
+        } ],
+        "requestBody" : {
+          "content" : {
+            "application/json" : {
+              "schema" : {
+                "$ref" : "#/components/schemas/editToolApproval_request"
+              }
+            }
+          },
+          "required" : true
+        },
+        "responses" : {
+          "200" : {
+            "content" : {
+              "application/json" : {
+                "schema" : {
+                  "$ref" : "#/components/schemas/ToolApproval"
+                }
+              }
+            },
+            "description" : "Approval updated"
+          },
+          "400" : {
+            "description" : "The value is not valid for that family"
+          },
+          "401" : {
+            "description" : "Unauthorized"
+          },
+          "403" : {
+            "description" : "Forbidden"
+          },
+          "404" : {
+            "description" : "No such approval granted by the caller in this organisation"
+          },
+          "409" : {
+            "description" : "The caller already granted that exact value in the same scope"
+          },
+          "503" : {
+            "description" : "Tool approvals are not configured on this deployment"
+          }
+        },
+        "summary" : "Edit an approval the caller granted",
+        "tags" : [ "organizations" ]
+      }
+    },
     "/manifests" : {
       "get" : {
         "description" : "Retrieves manifests, filtered by user ID for non-admin users",
@@ -15491,12 +15691,13 @@
         "type" : "object"
       },
       "AgentSandboxNetworkConfiguration" : {
-        "description" : "Enables curl inside the sandbox. Without at least one entry in allowedUrlPrefixes the network stays cut. Private address ranges are always denied, server-side.",
+        "description" : "Enables curl inside the sandbox. allowedUrlPrefixes is optional and normally empty: an address that is not listed is submitted to the user, who allows or refuses it in the conversation. It only stays useful where nobody can be asked — an app or a widget — since the network is cut there without a pre-approved entry. Private address ranges are always denied, server-side.",
         "properties" : {
           "enabled" : {
             "type" : "boolean"
           },
           "allowedUrlPrefixes" : {
+            "description" : "Addresses that need no confirmation. Not editable from the agent settings screen: an empty list is the nominal setup, and what the user approves in conversation is stored separately and revoked from the organisation settings.",
             "items" : {
               "description" : "Full origin, path prefix allowed (e.g. https://api.exemple.com/v1/).",
               "type" : "string"
@@ -16690,6 +16891,12 @@
             },
             "type" : "array"
           },
+          "approvals" : {
+            "items" : {
+              "$ref" : "#/components/schemas/ConversationMessageApproval"
+            },
+            "type" : "array"
+          },
           "suggestions" : {
             "items" : {
               "$ref" : "#/components/schemas/Suggestion"
@@ -16802,6 +17009,40 @@
         "required" : [ "code" ],
         "type" : "object"
       },
+      "ConversationMessageApproval" : {
+        "additionalProperties" : false,
+        "description" : "One authorisation decision taken during this message: which tool, over what, by whom, when. Carried by the message so the history reads as it stands, with no extra request. For a decision granted once it is the only lasting trace there is — a one-off creates no standing approval. Deliberately beside toolResults rather than inside it: toolResults is replayed to the model every turn, and a one-off appearing there would later suggest a right that has expired.",
+        "properties" : {
+          "tool" : {
+            "description" : "The tool whose use was submitted for approval. It also says which family the decision belongs to: bash_network_approval an address, bash_python_approval a command.",
+            "type" : "string"
+          },
+          "granted" : {
+            "description" : "Refusals are kept too — deciding not to allow is worth reading back.",
+            "type" : "boolean"
+          },
+          "resource" : {
+            "description" : "What was granted, or on a refusal what had been asked for. An address is the prefix, never the full URL, which can carry a token.",
+            "example" : "https://api.exemple.com/v1",
+            "type" : "string"
+          },
+          "scope" : {
+            "description" : "How far the yes reached. once — this reply only, nothing stored, asked about again next time. agentUser — this agent, for this user, in every conversation, until revoked. Absent on a refusal, which grants nothing.",
+            "enum" : [ "once", "agentUser" ],
+            "type" : "string"
+          },
+          "approvedBy" : {
+            "description" : "Name or email of the person who decided, as it stood when they decided.",
+            "type" : "string"
+          },
+          "at" : {
+            "type" : "string"
+          }
+        },
+        "required" : [ "at", "granted", "resource", "tool" ],
+        "title" : "ConversationMessageApproval",
+        "type" : "object"
+      },
       "Suggestion" : {
         "properties" : {
           "id" : {
@@ -19514,6 +19755,61 @@
       "TotalRequests" : {
         "type" : "number"
       },
+      "ToolApprovalsResponse" : {
+        "additionalProperties" : false,
+        "properties" : {
+          "approvals" : {
+            "items" : {
+              "$ref" : "#/components/schemas/ToolApproval"
+            },
+            "type" : "array"
+          }
+        },
+        "required" : [ "approvals" ],
+        "title" : "ToolApprovalsResponse",
+        "type" : "object"
+      },
+      "ToolApproval" : {
+        "additionalProperties" : false,
+        "description" : "One operation the user has authorised an agent to perform. Two families share this shape: an address the agent sandbox may reach, and a python command it may run. An address is stored normalised — query string, fragment and credentials removed — so a token carried by the URL the user saw is not kept here; a command is stored as it was approved, since the command itself is what was judged.",
+        "properties" : {
+          "id" : {
+            "description" : "Identifier to revoke the approval with.",
+            "type" : "string"
+          },
+          "scopeKind" : {
+            "description" : "What the approval covers. agentUser — this agent, for this user, across all of their conversations — is the only scope stored today. user is still listed because rows stored under it remain in force and readable. A one-off \"allow once\" answer creates no row here at all: it is recorded on the tool call it answered, see ToolCallApproval.",
+            "enum" : [ "agentUser", "user" ],
+            "type" : "string"
+          },
+          "toolName" : {
+            "description" : "The tool the approval applies to. Approvals never cross tools.",
+            "example" : "Bash_exec",
+            "type" : "string"
+          },
+          "resourceKind" : {
+            "description" : "Which family the approval belongs to. url is an address the agent sandbox may reach; urlPattern is a glob covering a whole site, subdomains included; command is one exact command line it may run.",
+            "enum" : [ "url", "command", "urlPattern" ],
+            "type" : "string"
+          },
+          "resource" : {
+            "description" : "What is granted, in the family's own notation. A url is a PREFIX: it covers any path below it, with any query parameters. A urlPattern is a GLOB, not a regular expression: a star stands for any text up to the next slash, everything else is literal, the pattern covers the start of the address and is matched case-insensitively. It must start with https://, close its host with a slash, and end with a slash or a star. A command is matched exactly, whitespace aside — a command that differs at all is asked about again.",
+            "example" : "https://api.exemple.com/v1",
+            "type" : "string"
+          },
+          "agentId" : {
+            "description" : "Present on an agentUser-scoped approval.",
+            "type" : "string"
+          },
+          "createdAt" : {
+            "format" : "date-time",
+            "type" : "string"
+          }
+        },
+        "required" : [ "createdAt", "id", "resource", "resourceKind", "scopeKind", "toolName" ],
+        "title" : "ToolApproval",
+        "type" : "object"
+      },
       "Manifest" : {
         "additionalProperties" : true,
         "properties" : {
@@ -21304,14 +21600,14 @@
       },
       "ToolCall" : {
         "additionalProperties" : false,
-        "description" : "A tool call whose result does not come from the server. The conversation turn stays suspended until a client posts the result, or until expiresAt passes.",
+        "description" : "A tool call whose result does not come from the server. The conversation turn stays suspended until a client posts the result, or until expiresAt passes when the call carries one.",
         "properties" : {
           "callId" : {
             "description" : "Identifier to post the result to.",
             "type" : "string"
           },
           "tool" : {
-            "description" : "Name of the tool the model called.",
+            "description" : "Name of the tool the model called. Three values are produced by the server today. take_screenshot asks the client to capture the screen. bash_network_approval is an agent sandbox asking permission to reach an address: arguments carries url (the full address, to be shown as-is), urlPrefix (what a yes actually grants), origin, host and method. bash_python_approval is an agent sandbox asking permission to run a python command: arguments carries command, which is both what has to be shown in full and exactly what a yes grants — nothing ran, so a refusal leaves the sandbox untouched.",
             "type" : "string"
           },
           "status" : {
@@ -21340,12 +21636,12 @@
             "type" : "string"
           },
           "expiresAt" : {
-            "description" : "Past this point the call is expired and the conversation turn is released.",
+            "description" : "Optional, and set tool by tool: a call with no deadline never expires, and none of the tools produced today carries one. When present, past this point the call is expired and the conversation turn is released.",
             "format" : "date-time",
             "type" : "string"
           }
         },
-        "required" : [ "callId", "expiresAt", "status", "tool" ],
+        "required" : [ "callId", "status", "tool" ],
         "title" : "ToolCall",
         "type" : "object"
       },
@@ -21372,6 +21668,16 @@
           "error" : {
             "description" : "Failure detail, surfaced to the model when status is failed.",
             "type" : "string"
+          },
+          "approvalScope" : {
+            "description" : "Only read when resolving a bash_network_approval or bash_python_approval call with status completed: how far the approval reaches. once — the suspended reply and nothing after it, so the same request is asked about again next time — is the default, and nothing is stored. agentUser covers this agent, for this user, across all of their conversations, and is kept until revoked. Any other value is refused with a 400. Never widens what the agent is allowed to do: the server-side lock and the per-agent switch remain prerequisites. Only the user the question was asked of may answer it: an approval is a personal consent, so another caller — an admin included — gets a 403.",
+            "enum" : [ "once", "agentUser" ],
+            "type" : "string"
+          },
+          "approvalWidth" : {
+            "description" : "Only read when resolving a bash_network_approval call with status completed: how wide the approval is. prefix (the default) grants the prefix shown in the request — origin plus first path segment; origin grants the whole domain. Nothing narrower is offered: nobody can predict the paths an API will serve, and an approval that is too fine is paid for in repeated questions. The server recomputes both from the URL it recorded, so a client cannot submit a prefix of its own. Ignored on a bash_python_approval call, which has a single width: the exact command the server already recorded.",
+            "enum" : [ "prefix", "origin" ],
+            "type" : "string"
           }
         },
         "required" : [ "status" ],
@@ -22930,6 +23236,43 @@
         "required" : [ "success" ],
         "type" : "object"
       },
+      "createToolApproval_request" : {
+        "additionalProperties" : false,
+        "properties" : {
+          "agentId" : {
+            "description" : "The agent the approval is granted to. The caller must have access to it.",
+            "type" : "string"
+          },
+          "resourceKind" : {
+            "enum" : [ "url", "command", "urlPattern" ],
+            "type" : "string"
+          },
+          "resource" : {
+            "description" : "An address is re-normalised server-side (https only, no credentials, no ambiguous separators) and stored as a prefix; a pattern is a glob — a star stands for any text up to the next slash, everything else is literal — that must start with https://, close its host with a slash and end with a slash or a star; a command is stored exactly as written, whitespace normalised.",
+            "maxLength" : 1000,
+            "type" : "string"
+          }
+        },
+        "required" : [ "agentId", "resource", "resourceKind" ],
+        "type" : "object"
+      },
+      "editToolApproval_request" : {
+        "additionalProperties" : false,
+        "properties" : {
+          "resourceKind" : {
+            "description" : "The family the edited value belongs to. Changing it is allowed and is the point: an approved address becomes a pattern this way.",
+            "enum" : [ "url", "command", "urlPattern" ],
+            "type" : "string"
+          },
+          "resource" : {
+            "description" : "The new value. An address is re-normalised server-side (https only, no credentials, no ambiguous separators) and stored as a prefix; a pattern is a glob — a star stands for any text up to the next slash, everything else is literal — that must start with https://, close its host with a slash and end with a slash or a star; a command is stored exactly as written, whitespace normalised.",
+            "maxLength" : 1000,
+            "type" : "string"
+          }
+        },
+        "required" : [ "resource", "resourceKind" ],
+        "type" : "object"
+      },
       "patchKnowledgeBase_request" : {
         "properties" : {
           "name" : {
@@ -23899,6 +24242,12 @@
             },
             "type" : "array"
           },
+          "approvals" : {
+            "items" : {
+              "$ref" : "#/components/schemas/ConversationMessageApproval"
+            },
+            "type" : "array"
+          },
           "workspaceFiles" : {
             "items" : {
               "type" : "string"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breign/client",
-  "version": "1.0.138",
+  "version": "1.0.139",
   "main": "dist/index.js",
   "exports": {
     ".": "./dist/index.js",