@breign/db-schemas 0.1.56 → 0.1.57

package/dist/types/conversation.d.ts

@@ -1,19 +1,81 @@
 import { ChatMessageRoleUio } from '@breign/client';
+import type { ToolCallApprovalScope } from './pending-tool-call';
+import type { ToolAction, ToolResult } from './tool-result';
 export type ConversationMessageReaction = 'positive' | 'negative';
-export type ConversationAttachment = {
+export type ConversationAttachmentStatus = 'TO_UPLOAD' | 'PROCESSING' | 'PROCESSED' | 'ERROR';
+export type ConversationAttachmentErrorCode = 'ATTACHMENT_TOO_LARGE';
+/**
+ * Pièce jointe documentaire. `processed` dit où son contenu a fini : recopié tel quel dans le
+ * stockage, ou indexé dans un vector store — les deux formes n'ont rien en commun, d'où l'union.
+ */
+export type ConversationFileAttachment = {
+    type: 'file';
     id: string;
-    type: string;
     name: string;
     mimeType: string;
     ext: string;
     size: number;
     key: string;
-    status: 'TO_UPLOAD' | 'PROCESSING' | 'PROCESSED' | 'ERROR';
+    status: ConversationAttachmentStatus;
+    errorCode?: ConversationAttachmentErrorCode;
+    estimatedTokens?: number;
+    maxTokens?: number;
     /** Run the OCR pre-pass before parsing this attachment to Markdown */
     ocr?: boolean;
+    processed?: {
+        type: 'file';
+        key: string;
+        content?: string;
+    } | {
+        type: 'indexed';
+        index: string;
+        backend: 'weaviate' | 'qdrant';
+        fileId: string;
+        sourceKey: string;
+        indexedAt: string;
+        invalidatedAt?: string;
+    };
+};
+export type ConversationImageAttachment = {
+    type: 'image';
+    id: string;
+    name: string;
+    mimeType: string;
+    ext: string;
+    size: number;
+    key: string;
     url?: string;
+    status: ConversationAttachmentStatus;
     inlineDataUrl?: string;
-    processed?: Record<string, unknown>;
+};
+/** Discriminée par `type` : une image ne passe pas par le parsing documentaire. */
+export type ConversationAttachment = ConversationFileAttachment | ConversationImageAttachment;
+/**
+ * Une décision d'autorisation prise pendant ce message : quel outil, sur quoi, par qui, quand.
+ *
+ * Portée par le MESSAGE et pas seulement par l'appel d'outil qui a posé la question, parce que
+ * c'est l'historique qui doit la montrer : la conversation se relit telle quelle, sans aller
+ * chercher les appels différés un par un. Un accord ponctuel n'existant nulle part ailleurs — il
+ * n'écrit aucune ligne d'autorisation permanente — c'est ici sa seule trace durable.
+ *
+ * Délibérément à côté de `toolResults` et non dedans : `toolResults` est **rejoué au modèle** à
+ * chaque tour (`OUTILS: …`). Un accord `once` y figurant ferait croire au modèle, deux tours plus
+ * tard, qu'il a encore un droit qui a expiré — et c'est exactement le malentendu que la portée
+ * `once` existe pour éviter.
+ */
+export type ConversationMessageApproval = {
+    /** L'outil dont un usage a été soumis à autorisation. Dit aussi de quelle famille il s'agit. */
+    tool: string;
+    /** Les refus sont conservés : une décision de ne pas autoriser se relit autant qu'un accord. */
+    granted: boolean;
+    /** Ce qui a été accordé — ou, sur un refus, ce qui avait été demandé. Jamais l'URL complète. */
+    resource: string;
+    /** Absent sur un refus, qui n'accorde rien et n'a donc pas de portée. */
+    scope?: ToolCallApprovalScope;
+    /** Nom ou e-mail de la personne qui a décidé, figé à cet instant. */
+    approvedBy?: string;
+    /** Quand la décision a été prise, ISO. */
+    at: string;
 };
 export type ConversationMessage = {
     id: string;
@@ -29,8 +91,10 @@ export type ConversationMessage = {
             toolName?: string;
             params?: string;
         };
-        result?: Record<string, unknown>;
+        result?: ToolResult;
     }[];
+    /** Décisions d'autorisation prises pendant ce message. Voir ConversationMessageApproval. */
+    approvals?: ConversationMessageApproval[];
     suggestions?: {
         id: string;
         text: string;
@@ -42,9 +106,14 @@ export type ConversationMessage = {
     flowNodeRequirementsCheckReason?: string;
     flowNodeIterations?: number;
     timestamp: string;
-    actions?: Record<string, unknown>[];
+    actions?: ToolAction[];
     attachments?: ConversationAttachment[];
-    status?: 'generating' | 'completed' | 'error' | 'tool_calling' | 'moderated';
+    /**
+     * `waiting_client` : le tour s'est arrêté sur un outil que le client doit exécuter ou autoriser.
+     * Ni terminé ni en erreur — le message repartira en `generating` quand le résultat sera remonté.
+     * Les appels en attente eux-mêmes se lisent par message (voir `PendingToolCall`).
+     */
+    status?: 'generating' | 'completed' | 'error' | 'tool_calling' | 'moderated' | 'waiting_client';
     toolCall?: {
         name: string;
         stepIndex: number;

package/dist/types/index.d.ts

@@ -10,6 +10,7 @@ export * from './flow';
 export * from './flow-editor';
 export * from './knowledge';
 export * from './organization';
+export * from './pending-tool-call';
 export * from './permissions';
 export * from './role';
 export * from './scheduled-task';
@@ -17,5 +18,7 @@ export * from './scheduled-task-run';
 export * from './skill';
 export * from './speech-to-text';
 export * from './tool';
+export * from './tool-approval';
+export * from './tool-result';
 export * from './user';
 export * from './workspace-file';

package/dist/types/index.js

@@ -26,6 +26,7 @@ __exportStar(require("./flow"), exports);
 __exportStar(require("./flow-editor"), exports);
 __exportStar(require("./knowledge"), exports);
 __exportStar(require("./organization"), exports);
+__exportStar(require("./pending-tool-call"), exports);
 __exportStar(require("./permissions"), exports);
 __exportStar(require("./role"), exports);
 __exportStar(require("./scheduled-task"), exports);
@@ -33,5 +34,7 @@ __exportStar(require("./scheduled-task-run"), exports);
 __exportStar(require("./skill"), exports);
 __exportStar(require("./speech-to-text"), exports);
 __exportStar(require("./tool"), exports);
+__exportStar(require("./tool-approval"), exports);
+__exportStar(require("./tool-result"), exports);
 __exportStar(require("./user"), exports);
 __exportStar(require("./workspace-file"), exports);

package/dist/types/pending-tool-call.d.ts

@@ -0,0 +1,82 @@
+import type { ToolResult } from './tool-result';
+export type PendingToolCallStatus = 'pending' | 'completed' | 'failed' | 'refused' | 'expired';
+/** Les statuts qu'un client peut poser : `pending` et `expired` sont au serveur seul. */
+export type PendingToolCallResolution = Exclude<PendingToolCallStatus, 'pending' | 'expired'>;
+/**
+ * Jusqu'où porte un « oui » donné sur une demande d'autorisation.
+ *
+ * `once` = la réponse suspendue, et rien après : **aucune ligne n'est écrite dans `ToolApproval`**,
+ * et la même demande est reposée au message suivant. `agentUser` = cet agent, pour cet utilisateur,
+ * dans toutes ses conversations, jusqu'à révocation — là une ligne existe.
+ *
+ * Volontairement distinct de `ToolApprovalScopeKind` : celui-ci nomme des portées de STOCKAGE, et
+ * `once` n'en est pas une. Les confondre reviendrait à admettre qu'un accord ponctuel puisse être
+ * stocké, ce qui est exactement ce qu'il ne doit pas être.
+ */
+export type ToolCallApprovalScope = 'once' | 'agentUser';
+/**
+ * Ce qu'un « oui » a accordé, porté par l'appel d'outil qui a posé la question.
+ *
+ * Deux rôles, et c'est voulu. C'est la TRACE d'une décision — qui, quoi, jusqu'où — que l'écran de
+ * conversation réaffiche, et qui reste lisible que le droit permanent ait été créé ou non : avec
+ * `once` il n'y en a jamais eu, avec `agentUser` il a pu être révoqué depuis. Et pour la portée
+ * `once` c'est **le droit lui-même**, qui n'existe nulle part ailleurs : le tour de reprise le relit
+ * ici. D'où la borne — un appel appartient à un message assistant, donc un accord ponctuel ne peut
+ * pas survivre à ce message.
+ *
+ * C'est ici et pas dans `ToolApproval` parce que la question posée est propre à UNE conversation,
+ * alors que `ToolApproval` décrit un droit permanent attaché à un agent et à un utilisateur.
+ */
+export type ToolCallApproval = {
+    scope: ToolCallApprovalScope;
+    /**
+     * Ce qui est accordé, préfixé par sa famille exactement comme `ToolApproval.resourceKey` — `url:`
+     * une adresse, `cmd:` une commande exacte, `glob:` un motif. Un seul analyseur pour les deux, et
+     * une adresse approuvée ne peut jamais satisfaire une commande.
+     */
+    resourceKey: string;
+    /**
+     * Nom ou e-mail de la personne qui a cliqué, figé à cet instant plutôt que joint plus tard : la
+     * trace doit rester lisible après son départ de l'organisation. Absent quand l'appelant n'a pas
+     * d'identité.
+     */
+    approvedBy?: string;
+};
+/**
+ * Un appel d'outil que le serveur ne résout pas lui-même. Le tour est clos dès sa création et la
+ * réponse du client relance un tour de reprise : un appel non résolu ne retient rien. Générique —
+ * `tool` le nomme, `arguments` porte ce que le modèle a passé.
+ *
+ * Le lien avec la conversation va d'ici vers le message (`chatId` + `messageId`), jamais l'inverse :
+ * le message ne porte que le statut `waiting_client`, et les appels se lisent par message.
+ */
+export type PendingToolCall = {
+    id: string;
+    tool: string;
+    userId: string;
+    chatId?: string;
+    /** Message assistant suspendu : celui que le tour de reprise complétera. */
+    messageId?: string;
+    /** Device visé, à titre informatif : l'autorisation passe par la conversation. */
+    deviceId?: string;
+    status: PendingToolCallStatus;
+    arguments?: Record<string, unknown>;
+    /**
+     * Ce que la reprise écrit dans la conversation à la place des `arguments` bruts. Le tour de reprise
+     * injecte `Outil : <tool>(<arguments>)` dans l'historique **persisté**, rejoué à chaque tour : un
+     * argument portant un secret y resterait indéfiniment. Absent ⇒ repli sur les `arguments`.
+     */
+    displaySummary?: string;
+    result?: ToolResult;
+    /**
+     * Écrit à la résolution, sur les seuls appels d'approbation et seulement quand la réponse est un
+     * accord. Posé dans la même écriture que le statut : pour une portée `once` il EST le droit, donc
+     * un appel passé à `completed` sans lui relancerait le tour sans rien accorder.
+     */
+    approval?: ToolCallApproval;
+    error?: string;
+    createdAt: Date;
+    updatedAt: Date;
+    /** Échéance optionnelle, posée outil par outil : un outil sans TTL n'expire jamais. */
+    expiresAt?: Date;
+};

package/dist/types/pending-tool-call.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/tool-approval.d.ts

@@ -0,0 +1,63 @@
+/**
+ * User approval of one operation the agent's sandbox asked permission for.
+ *
+ * Two families exist, both belonging to `Bash_exec`: an address its curl may reach, and a python
+ * command it may run. When such a call is not already granted, the conversation turn is suspended
+ * and the user is asked. A "yes" is stored here ONLY when the user chose to stop being asked: a
+ * one-off "allow this once" grants the suspended turn and writes nothing, so every row in this
+ * table is a standing right, not a trace of a past decision. That trace lives on the tool call —
+ * see `ToolCallApproval`, which is where a one-off is recorded and where it stays confined.
+ *
+ * Three invariants make this table safe to read on the hot path:
+ *
+ * - **It can only intersect, never widen.** An approval unlocks an operation of a tool the agent
+ *   already has, behind the server lock and the per-agent switch. An agent with no sandbox gains
+ *   nothing because the user approved something elsewhere.
+ * - **`resourceKey` is normalised, and carries its family as a prefix.** A URL prefix, a glob or an
+ *   exact command line — never raw arguments, so a secret passed next to the approved value is not
+ *   persisted here. The prefix is what stops an approved address from authorising a command: the
+ *   full arguments live only in the tool call that produced the approval.
+ * - **A row is a personal consent, and `userId` says whose.** Nobody can approve on someone else's
+ *   behalf: the resolution route refuses a caller who is not the person the question was asked of,
+ *   so the person the right applies to and the person who granted it are the same by construction.
+ *   One column carries both, and it is what the management routes key on.
+ *
+ * Revoking one deletes its row: there is no state a revoked approval could be in, so nothing on the
+ * read path has to filter it out.
+ *
+ * Shared with agent-tasks through this package even though agent-tasks asks nobody: the type
+ * belongs with the other storage models.
+ */
+export type ToolApprovalScopeKind = 'agentUser' | 'user';
+export type ToolApproval = {
+    id: string;
+    /**
+     * British spelling "organisationId" — aligned with Agent.organisationId (domain + Mongo
+     * storage). In PostgreSQL the COLUMN is organizationId ("z"), mapped inside the PG adapter.
+     * It leads every key: an approval never crosses an organisation boundary.
+     */
+    organisationId: string;
+    /**
+     * `agentUser` is the only one written. `user` is kept readable but nothing writes it — see
+     * `agentApprovalScope` in brain-api, the single place that builds a stored scope.
+     */
+    scopeKind: ToolApprovalScopeKind;
+    /**
+     * Scope folded into a single string, so unicity is a plain unique index. PostgreSQL treats two
+     * NULLs as distinct, so a unique index over nullable discriminator columns would not constrain
+     * anything — same reason `workspaceSessionKey` exists.
+     */
+    scopeKey: string;
+    /** Set for the 'agentUser' scope. Absent on 'user', which holds for every agent. */
+    agentId?: string;
+    /** Whose consent it is. Never empty: an approval always belongs to one person. */
+    userId: string;
+    /** The tool as the model calls it. Part of the key: two tools never share an approval. */
+    toolName: string;
+    /**
+     * What a "yes" grants, prefixed by its family: `url:` an origin plus an optional first path
+     * segment, `glob:` a pattern covering a site, `cmd:` one exact command line.
+     */
+    resourceKey: string;
+    createdAt: string;
+};

package/dist/types/tool-approval.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/tool-result.d.ts

@@ -0,0 +1,19 @@
+import type { ConversationAttachment } from './conversation';
+/**
+ * Ce qu'un outil renvoie au tour de conversation. Copie structurelle de `ToolResult` /
+ * `ToolAction` de brain-api (`src/shared/init-tools.ts`), qui reste la définition de référence :
+ * ce paquet ne dépend pas de brain-api, mais les modèles de stockage qui portent un résultat
+ * d'outil — un message de conversation, un appel d'outil en attente — ont besoin de sa forme.
+ */
+export type ToolAction = {
+    code: string;
+} & Record<string, unknown>;
+export type ToolResult = {
+    text: string;
+    attachments?: ConversationAttachment[];
+    askConfirmation?: boolean;
+    confirmationLink?: string;
+    actions?: ToolAction[];
+    /** Clôt le tour sans réponse finale : le client doit résoudre l'appel avant qu'il reprenne. */
+    suspendTurn?: boolean;
+};

package/dist/types/tool-result.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breign/db-schemas",
-  "version": "0.1.56",
+  "version": "0.1.57",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {

package/src/types/conversation.ts

@@ -1,21 +1,90 @@
 import { ChatMessageRoleUio } from '@breign/client';
+import type { ToolCallApprovalScope } from './pending-tool-call';
+import type { ToolAction, ToolResult } from './tool-result';
 
 export type ConversationMessageReaction = 'positive' | 'negative';
 
-export type ConversationAttachment = {
+export type ConversationAttachmentStatus = 'TO_UPLOAD' | 'PROCESSING' | 'PROCESSED' | 'ERROR';
+
+export type ConversationAttachmentErrorCode = 'ATTACHMENT_TOO_LARGE';
+
+/**
+ * Pièce jointe documentaire. `processed` dit où son contenu a fini : recopié tel quel dans le
+ * stockage, ou indexé dans un vector store — les deux formes n'ont rien en commun, d'où l'union.
+ */
+export type ConversationFileAttachment = {
+  type: 'file';
   id: string;
-  type: string;
   name: string;
   mimeType: string;
   ext: string;
   size: number;
   key: string;
-  status: 'TO_UPLOAD' | 'PROCESSING' | 'PROCESSED' | 'ERROR';
+  status: ConversationAttachmentStatus;
+  errorCode?: ConversationAttachmentErrorCode;
+  estimatedTokens?: number;
+  maxTokens?: number;
   /** Run the OCR pre-pass before parsing this attachment to Markdown */
   ocr?: boolean;
+  processed?:
+    | {
+        type: 'file';
+        key: string;
+        content?: string;
+      }
+    | {
+        type: 'indexed';
+        index: string;
+        backend: 'weaviate' | 'qdrant';
+        fileId: string;
+        sourceKey: string;
+        indexedAt: string;
+        invalidatedAt?: string;
+      };
+};
+
+export type ConversationImageAttachment = {
+  type: 'image';
+  id: string;
+  name: string;
+  mimeType: string;
+  ext: string;
+  size: number;
+  key: string;
   url?: string;
+  status: ConversationAttachmentStatus;
   inlineDataUrl?: string;
-  processed?: Record<string, unknown>;
+};
+
+/** Discriminée par `type` : une image ne passe pas par le parsing documentaire. */
+export type ConversationAttachment = ConversationFileAttachment | ConversationImageAttachment;
+
+/**
+ * Une décision d'autorisation prise pendant ce message : quel outil, sur quoi, par qui, quand.
+ *
+ * Portée par le MESSAGE et pas seulement par l'appel d'outil qui a posé la question, parce que
+ * c'est l'historique qui doit la montrer : la conversation se relit telle quelle, sans aller
+ * chercher les appels différés un par un. Un accord ponctuel n'existant nulle part ailleurs — il
+ * n'écrit aucune ligne d'autorisation permanente — c'est ici sa seule trace durable.
+ *
+ * Délibérément à côté de `toolResults` et non dedans : `toolResults` est **rejoué au modèle** à
+ * chaque tour (`OUTILS: …`). Un accord `once` y figurant ferait croire au modèle, deux tours plus
+ * tard, qu'il a encore un droit qui a expiré — et c'est exactement le malentendu que la portée
+ * `once` existe pour éviter.
+ */
+export type ConversationMessageApproval = {
+  /** L'outil dont un usage a été soumis à autorisation. Dit aussi de quelle famille il s'agit. */
+  tool: string;
+  /** Les refus sont conservés : une décision de ne pas autoriser se relit autant qu'un accord. */
+  granted: boolean;
+  /** Ce qui a été accordé — ou, sur un refus, ce qui avait été demandé. Jamais l'URL complète. */
+  resource: string;
+  /** Absent sur un refus, qui n'accorde rien et n'a donc pas de portée. */
+  scope?: ToolCallApprovalScope;
+  /** Nom ou e-mail de la personne qui a décidé, figé à cet instant. */
+  approvedBy?: string;
+  /** Quand la décision a été prise, ISO. */
+  at: string;
 };
 
 export type ConversationMessage = {
@@ -28,8 +97,10 @@ export type ConversationMessage = {
   confirmationLink?: string;
   toolResults?: {
     tool: { tool: string; toolName?: string; params?: string };
-    result?: Record<string, unknown>;
+    result?: ToolResult;
   }[];
+  /** Décisions d'autorisation prises pendant ce message. Voir ConversationMessageApproval. */
+  approvals?: ConversationMessageApproval[];
   suggestions?: {
     id: string;
     text: string;
@@ -41,9 +112,14 @@ export type ConversationMessage = {
   flowNodeRequirementsCheckReason?: string;
   flowNodeIterations?: number;
   timestamp: string;
-  actions?: Record<string, unknown>[];
+  actions?: ToolAction[];
   attachments?: ConversationAttachment[];
-  status?: 'generating' | 'completed' | 'error' | 'tool_calling' | 'moderated';
+  /**
+   * `waiting_client` : le tour s'est arrêté sur un outil que le client doit exécuter ou autoriser.
+   * Ni terminé ni en erreur — le message repartira en `generating` quand le résultat sera remonté.
+   * Les appels en attente eux-mêmes se lisent par message (voir `PendingToolCall`).
+   */
+  status?: 'generating' | 'completed' | 'error' | 'tool_calling' | 'moderated' | 'waiting_client';
   toolCall?: { name: string; stepIndex: number };
   error?: {
     code: string;

package/src/types/index.ts

@@ -10,6 +10,7 @@ export * from './flow';
 export * from './flow-editor';
 export * from './knowledge';
 export * from './organization';
+export * from './pending-tool-call';
 export * from './permissions';
 export * from './role';
 export * from './scheduled-task';
@@ -17,5 +18,7 @@ export * from './scheduled-task-run';
 export * from './skill';
 export * from './speech-to-text';
 export * from './tool';
+export * from './tool-approval';
+export * from './tool-result';
 export * from './user';
 export * from './workspace-file';

package/src/types/pending-tool-call.ts

@@ -0,0 +1,87 @@
+import type { ToolResult } from './tool-result';
+
+export type PendingToolCallStatus = 'pending' | 'completed' | 'failed' | 'refused' | 'expired';
+
+/** Les statuts qu'un client peut poser : `pending` et `expired` sont au serveur seul. */
+export type PendingToolCallResolution = Exclude<PendingToolCallStatus, 'pending' | 'expired'>;
+
+/**
+ * Jusqu'où porte un « oui » donné sur une demande d'autorisation.
+ *
+ * `once` = la réponse suspendue, et rien après : **aucune ligne n'est écrite dans `ToolApproval`**,
+ * et la même demande est reposée au message suivant. `agentUser` = cet agent, pour cet utilisateur,
+ * dans toutes ses conversations, jusqu'à révocation — là une ligne existe.
+ *
+ * Volontairement distinct de `ToolApprovalScopeKind` : celui-ci nomme des portées de STOCKAGE, et
+ * `once` n'en est pas une. Les confondre reviendrait à admettre qu'un accord ponctuel puisse être
+ * stocké, ce qui est exactement ce qu'il ne doit pas être.
+ */
+export type ToolCallApprovalScope = 'once' | 'agentUser';
+
+/**
+ * Ce qu'un « oui » a accordé, porté par l'appel d'outil qui a posé la question.
+ *
+ * Deux rôles, et c'est voulu. C'est la TRACE d'une décision — qui, quoi, jusqu'où — que l'écran de
+ * conversation réaffiche, et qui reste lisible que le droit permanent ait été créé ou non : avec
+ * `once` il n'y en a jamais eu, avec `agentUser` il a pu être révoqué depuis. Et pour la portée
+ * `once` c'est **le droit lui-même**, qui n'existe nulle part ailleurs : le tour de reprise le relit
+ * ici. D'où la borne — un appel appartient à un message assistant, donc un accord ponctuel ne peut
+ * pas survivre à ce message.
+ *
+ * C'est ici et pas dans `ToolApproval` parce que la question posée est propre à UNE conversation,
+ * alors que `ToolApproval` décrit un droit permanent attaché à un agent et à un utilisateur.
+ */
+export type ToolCallApproval = {
+  scope: ToolCallApprovalScope;
+  /**
+   * Ce qui est accordé, préfixé par sa famille exactement comme `ToolApproval.resourceKey` — `url:`
+   * une adresse, `cmd:` une commande exacte, `glob:` un motif. Un seul analyseur pour les deux, et
+   * une adresse approuvée ne peut jamais satisfaire une commande.
+   */
+  resourceKey: string;
+  /**
+   * Nom ou e-mail de la personne qui a cliqué, figé à cet instant plutôt que joint plus tard : la
+   * trace doit rester lisible après son départ de l'organisation. Absent quand l'appelant n'a pas
+   * d'identité.
+   */
+  approvedBy?: string;
+};
+
+/**
+ * Un appel d'outil que le serveur ne résout pas lui-même. Le tour est clos dès sa création et la
+ * réponse du client relance un tour de reprise : un appel non résolu ne retient rien. Générique —
+ * `tool` le nomme, `arguments` porte ce que le modèle a passé.
+ *
+ * Le lien avec la conversation va d'ici vers le message (`chatId` + `messageId`), jamais l'inverse :
+ * le message ne porte que le statut `waiting_client`, et les appels se lisent par message.
+ */
+export type PendingToolCall = {
+  id: string;
+  tool: string;
+  userId: string;
+  chatId?: string;
+  /** Message assistant suspendu : celui que le tour de reprise complétera. */
+  messageId?: string;
+  /** Device visé, à titre informatif : l'autorisation passe par la conversation. */
+  deviceId?: string;
+  status: PendingToolCallStatus;
+  arguments?: Record<string, unknown>;
+  /**
+   * Ce que la reprise écrit dans la conversation à la place des `arguments` bruts. Le tour de reprise
+   * injecte `Outil : <tool>(<arguments>)` dans l'historique **persisté**, rejoué à chaque tour : un
+   * argument portant un secret y resterait indéfiniment. Absent ⇒ repli sur les `arguments`.
+   */
+  displaySummary?: string;
+  result?: ToolResult;
+  /**
+   * Écrit à la résolution, sur les seuls appels d'approbation et seulement quand la réponse est un
+   * accord. Posé dans la même écriture que le statut : pour une portée `once` il EST le droit, donc
+   * un appel passé à `completed` sans lui relancerait le tour sans rien accorder.
+   */
+  approval?: ToolCallApproval;
+  error?: string;
+  createdAt: Date;
+  updatedAt: Date;
+  /** Échéance optionnelle, posée outil par outil : un outil sans TTL n'expire jamais. */
+  expiresAt?: Date;
+};

package/src/types/tool-approval.ts

@@ -0,0 +1,64 @@
+/**
+ * User approval of one operation the agent's sandbox asked permission for.
+ *
+ * Two families exist, both belonging to `Bash_exec`: an address its curl may reach, and a python
+ * command it may run. When such a call is not already granted, the conversation turn is suspended
+ * and the user is asked. A "yes" is stored here ONLY when the user chose to stop being asked: a
+ * one-off "allow this once" grants the suspended turn and writes nothing, so every row in this
+ * table is a standing right, not a trace of a past decision. That trace lives on the tool call —
+ * see `ToolCallApproval`, which is where a one-off is recorded and where it stays confined.
+ *
+ * Three invariants make this table safe to read on the hot path:
+ *
+ * - **It can only intersect, never widen.** An approval unlocks an operation of a tool the agent
+ *   already has, behind the server lock and the per-agent switch. An agent with no sandbox gains
+ *   nothing because the user approved something elsewhere.
+ * - **`resourceKey` is normalised, and carries its family as a prefix.** A URL prefix, a glob or an
+ *   exact command line — never raw arguments, so a secret passed next to the approved value is not
+ *   persisted here. The prefix is what stops an approved address from authorising a command: the
+ *   full arguments live only in the tool call that produced the approval.
+ * - **A row is a personal consent, and `userId` says whose.** Nobody can approve on someone else's
+ *   behalf: the resolution route refuses a caller who is not the person the question was asked of,
+ *   so the person the right applies to and the person who granted it are the same by construction.
+ *   One column carries both, and it is what the management routes key on.
+ *
+ * Revoking one deletes its row: there is no state a revoked approval could be in, so nothing on the
+ * read path has to filter it out.
+ *
+ * Shared with agent-tasks through this package even though agent-tasks asks nobody: the type
+ * belongs with the other storage models.
+ */
+export type ToolApprovalScopeKind = 'agentUser' | 'user';
+
+export type ToolApproval = {
+  id: string;
+  /**
+   * British spelling "organisationId" — aligned with Agent.organisationId (domain + Mongo
+   * storage). In PostgreSQL the COLUMN is organizationId ("z"), mapped inside the PG adapter.
+   * It leads every key: an approval never crosses an organisation boundary.
+   */
+  organisationId: string;
+  /**
+   * `agentUser` is the only one written. `user` is kept readable but nothing writes it — see
+   * `agentApprovalScope` in brain-api, the single place that builds a stored scope.
+   */
+  scopeKind: ToolApprovalScopeKind;
+  /**
+   * Scope folded into a single string, so unicity is a plain unique index. PostgreSQL treats two
+   * NULLs as distinct, so a unique index over nullable discriminator columns would not constrain
+   * anything — same reason `workspaceSessionKey` exists.
+   */
+  scopeKey: string;
+  /** Set for the 'agentUser' scope. Absent on 'user', which holds for every agent. */
+  agentId?: string;
+  /** Whose consent it is. Never empty: an approval always belongs to one person. */
+  userId: string;
+  /** The tool as the model calls it. Part of the key: two tools never share an approval. */
+  toolName: string;
+  /**
+   * What a "yes" grants, prefixed by its family: `url:` an origin plus an optional first path
+   * segment, `glob:` a pattern covering a site, `cmd:` one exact command line.
+   */
+  resourceKey: string;
+  createdAt: string;
+};

package/src/types/tool-result.ts

@@ -0,0 +1,21 @@
+import type { ConversationAttachment } from './conversation';
+
+/**
+ * Ce qu'un outil renvoie au tour de conversation. Copie structurelle de `ToolResult` /
+ * `ToolAction` de brain-api (`src/shared/init-tools.ts`), qui reste la définition de référence :
+ * ce paquet ne dépend pas de brain-api, mais les modèles de stockage qui portent un résultat
+ * d'outil — un message de conversation, un appel d'outil en attente — ont besoin de sa forme.
+ */
+export type ToolAction = {
+  code: string;
+} & Record<string, unknown>;
+
+export type ToolResult = {
+  text: string;
+  attachments?: ConversationAttachment[];
+  askConfirmation?: boolean;
+  confirmationLink?: string;
+  actions?: ToolAction[];
+  /** Clôt le tour sans réponse finale : le client doit résoudre l'appel avant qu'il reprenne. */
+  suspendTurn?: boolean;
+};