@opencxh/domain 1.274.0 → 1.276.0

package/dist/platform/ai-tools.d.ts

@@ -6,6 +6,8 @@
  * from internal apps (via the "ai-tool" provider role) or external MCP servers —
  * both surface through the same {@link AiTool} shape.
  */
+/** The provider role an app declares to offer AI tools (`/provider/ai-tools/*`). */
+export declare const AI_TOOL_PROVIDER_GROUP = "ai-tool";
 /** JSON-Schema object describing a tool's arguments. */
 export interface AiToolParameterSchema {
     type: "object";
@@ -19,6 +21,12 @@ export interface AiTool {
     description: string;
     parameters: AiToolParameterSchema;
 }
+/** Does a tool change anything? Absent counts as write. */
+export type ToolAccess = "read" | "write";
+/** Does a write stay inside the organisation? Absent counts as outward. */
+export type ToolEffect = "internal" | "outward";
+/** Can a write be taken back? Absent counts as none. */
+export type ToolReversible = "self" | "none" | "idempotent";
 /**
  * One entry in the tool catalog: what is available in this organisation right now.
  *
@@ -34,9 +42,9 @@ export interface ToolCatalogEntry {
     /** JSON-Schema of the tool's arguments — drives the playbook builder's param form. */
     parameters: AiToolParameterSchema;
     /** read | write as the tool declares it; absent = unknown. */
-    access?: "read" | "write";
+    access?: ToolAccess;
     /** internal | outward as the tool declares it; absent = outward. */
-    effect?: "internal" | "outward";
+    effect?: ToolEffect;
     /**
      * `"interactive"` = needs a watching user. Carried so a builder can say that up front:
      * a playbook runs unattended, and such a tool reports success for something that lands
@@ -46,7 +54,9 @@ export interface ToolCatalogEntry {
     /** What it leaves for a human to finish. See {@link AiToolDescriptor.produces}. */
     produces?: "draft";
     /** Whether it can be taken back. See {@link AiToolDescriptor.reversible}. */
-    reversible?: "self" | "none" | "idempotent";
+    reversible?: ToolReversible;
+    /** The tool that takes it back. See {@link AiToolDescriptor.undoWith}. */
+    undoWith?: string;
 }
 /**
  * How an action can be taken back. Reads the fail-safe default in one place, so no caller has to
@@ -56,17 +66,17 @@ export interface ToolCatalogEntry {
  * reverse and running it again is free. Only writes have a real answer here.
  */
 export declare function toolReversible(tool: {
-    access?: "read" | "write";
-    reversible?: "self" | "none" | "idempotent";
-}): "self" | "none" | "idempotent";
+    access?: ToolAccess;
+    reversible?: ToolReversible;
+}): ToolReversible;
 /**
  * Can this tool reach outside the building? A read never does; an `effect: "internal"` write says
  * so itself. Everything else — including a tool that declares neither — counts as outward, so a
  * forgotten declaration costs a tool for the turn rather than quietly sending a mail.
  */
 export declare function isOutwardTool(tool: {
-    access?: "read" | "write";
-    effect?: "internal" | "outward";
+    access?: ToolAccess;
+    effect?: ToolEffect;
 }): boolean;
 /** A model's request to call a tool. */
 export interface AiToolCall {
@@ -137,6 +147,12 @@ export interface AiToolResult {
      * stored `AIMessage`, so the thread keeps its provenance without a new entity.
      */
     sources?: ToolSource[];
+    /**
+     * Subject fields this call set whose value the params do not say — a value the tool chose
+     * itself (`assign_least_loaded` picks the assignee). Without it a rule run cannot tell what it
+     * wrote, so neither the undo nor the outcome check could judge it.
+     */
+    wrote?: Record<string, unknown>;
 }
 /**
  * Stable key for "I have already shown this".
@@ -168,7 +184,7 @@ export declare function freshSources(sources: readonly ToolSource[], alreadyShow
  */
 export interface AiToolDescriptor extends AiTool {
     /** Does this tool mutate anything? Drives the suggest gate. Absent = unknown. */
-    access?: "read" | "write";
+    access?: ToolAccess;
     /**
      * The resource this tool works on, so a generic gate can authorize it:
      * `{ param: "interactionId", kind: "interaction" }` means "authorize
@@ -200,7 +216,7 @@ export interface AiToolDescriptor extends AiTool {
      * should not silently count as harmless. See `shouldDemoteAuto` in the playbook engine, which
      * decides the suggest downgrade on this.
      */
-    effect?: "internal" | "outward";
+    effect?: ToolEffect;
     /**
      * What this tool leaves behind for a human to finish. `"draft"` = it prepares something the
      * user reviews and sends (a reply draft), which is exactly the deliverable of an
@@ -224,10 +240,7 @@ export interface AiToolDescriptor extends AiTool {
      *   attribute, an SLA profile). The executor records what was there before; undo replays that
      *   through this same tool, and nothing else has to know anything.
      *
-     *   Deliberately narrow. `add_tag` is reversible too, but by a *different* tool
-     *   (`remove_tag`), and expressing that needs a second field naming the counter-action. That
-     *   field can arrive the day an undo actually wants it; until then such a tool stays on the
-     *   default and simply is not offered as undoable. Under-promising is the safe direction.
+     *   A tool undone by a *different* tool names it in {@link AiToolDescriptor.undoWith}.
      * - `"none"` — irreversible. A sent mail, a webhook, a row at a third party. The gate belongs
      *   *before* it; afterwards there is nothing to do but send a second message, and that is a
      *   human's decision, not an undo.
@@ -246,7 +259,13 @@ export interface AiToolDescriptor extends AiTool {
      * becomes `"self"` when its clear-semantics are fixed, not when someone decides it feels
      * reversible — which is exactly why the default is the careful one.
      */
-    reversible?: "self" | "none" | "idempotent";
+    reversible?: ToolReversible;
+    /**
+     * The bare name of the tool in this same app that puts back the previous values, when that is
+     * not this tool itself. `assign_least_loaded` chooses an assignee and cannot be told one, so its
+     * inverse is `update_interaction` with the assignee it replaced. Only read with `"self"`.
+     */
+    undoWith?: string;
 }
 /**
  * Body of `POST /provider/ai-tools/invoke`. Replaces five inline structural types (the caller in

package/dist/platform/permission.d.ts

@@ -18,8 +18,8 @@ export declare const APP_PERMISSIONS: {
     readonly "app-store": readonly ["app.publish", "app.read", "app.write", "setting.read", "setting.write"];
     readonly assist: readonly ["board.read"];
     readonly automations: readonly ["sync.read", "sync.write", "webhook.read", "webhook.write"];
-    readonly communication: readonly ["account.read", "account.write", "activity-type.read", "activity.read", "activity.write", "attachment.read", "attribute.read", "attribute.write", "calendar.read", "calendar.write", "channel.read", "channel.write", "custom-field.read", "custom-field.write", "folder.read", "folder.write", "inbox.read", "inbox.write", "interaction.read", "interaction.write", "reaction.read", "reaction.write", "reminder.read", "template.read", "template.write", "topic.read", "topic.write"];
-    readonly context: readonly ["kind.read", "kind.write", "memory.read", "memory.write"];
+    readonly communication: readonly ["account.read", "account.write", "activity-type.read", "activity.read", "activity.write", "attachment.read", "calendar.read", "calendar.write", "channel.read", "channel.write", "folder.read", "folder.write", "inbox.read", "inbox.write", "interaction.read", "interaction.write", "reminder.read", "template.read", "template.write"];
+    readonly context: readonly ["attribute.read", "attribute.write", "custom-field.read", "custom-field.write", "kind.read", "kind.write", "memory.read", "memory.write", "reaction.read", "reaction.write", "topic.read", "topic.write"];
     readonly crm: readonly ["company.read", "company.write", "contact.read", "contact.write"];
     readonly "eylo-voip": readonly ["account.read", "account.write", "callflow.read", "callflow.write", "channel.read", "channel.write", "contact.read", "contact.write", "device.read", "device.write", "group.read", "group.write", "interaction.read", "interaction.write", "media.read", "media.write", "menu.read", "menu.write", "phone-number.read", "phone-number.write", "recording.read", "recording.write", "sip.read", "temporal-rule.read", "temporal-rule.write", "user.read", "user.write", "vmbox.read", "vmbox.write", "webhook.read", "webhook.write"];
     readonly google: readonly ["account.read", "account.write", "contact.read"];

package/dist/platform/resource-source.d.ts

@@ -80,9 +80,23 @@ export interface ResourceSummary {
      */
     related?: string[];
 }
+/** How one kind reads wherever it is listed: a picker tab, a link row, a related group. */
+export interface ResourceKindInfo {
+    /** Already in the viewer's language: the owning app has the words, a consumer never does. */
+    label: string;
+    /** Lucide icon name (kebab-case), like `ResourceSummary.icon`. */
+    icon?: string;
+    /** Semantic tint for the icon, so one kind has one colour on every surface. */
+    tone?: "info" | "success" | "warning" | "danger" | "muted";
+}
 /** Answer to `resources.describe`: which kinds this app can search and resolve. */
 export interface ResourceSourceDescribe {
     kinds: string[];
+    /**
+     * Per kind this app **owns**: those in `kinds`, and any it owns without offering search (a
+     * dossier row can still carry them). Absent = consumers show the raw kind, the honest fallback.
+     */
+    info?: Record<string, ResourceKindInfo>;
 }
 /** Params for `resources.search`. */
 export interface ResourceSearchParams {
@@ -266,4 +280,9 @@ export interface ResourceReadRequest {
 export interface ResourceReadResponse {
     text: string;
     title?: string;
+    /**
+     * The row itself, for a caller that compares values rather than reads prose — the undo and
+     * the outcome check. Same authorization as the text, so one read serves both.
+     */
+    fields?: Record<string, unknown>;
 }

package/dist/platform/tool-verdict.d.ts

@@ -1,5 +1,7 @@
 import { Agent } from '../entities/agent/types';
 import { AssistantMode } from '../entities/ai-message/types';
+import { Autonomy } from '../entities/playbook/types';
+import { ToolCatalogEntry } from './ai-tools';
 /**
  * May this tool be offered to the model this turn — and if it writes, may it run?
  *
@@ -26,15 +28,10 @@ export type ToolVerdict =
 /** Offered, but a call is captured for approval instead of executed. */
  | "held";
 /** What a verdict is made of. The declared half of a tool plus where it came from. */
-export interface ToolFacts {
-    name: string;
-    access?: "read" | "write";
-    effect?: "internal" | "outward";
-    surface?: "interactive";
-    produces?: "draft";
+export type ToolFacts = Pick<ToolCatalogEntry, "name" | "access" | "effect" | "surface" | "produces"> & {
     /** Runs on the acting user's own connection (a personal MCP server). */
     personal?: boolean;
-}
+};
 export interface ToolVerdictContext {
     /**
      * Tool names the profile switched on. **`undefined` means no filter** — the catalog asks that
@@ -58,8 +55,8 @@ export interface ToolVerdictContext {
     mode?: AssistantMode;
     /** A read lane: nothing that writes, whatever else it declares. */
     readOnly?: boolean;
-    /** Is the approval gate on for this turn? Then writes are held instead of run. */
-    gate?: boolean;
+    /** The approval gate for this turn; absent means nothing is held (the interactive assistant). */
+    gate?: ToolGate;
     /**
      * The agent's mandate, when an agent runs this turn. It may call a tool a read that declares
      * itself a write, and vice versa — an admin's explicit choice about this colleague.
@@ -77,4 +74,20 @@ export interface ToolVerdictContext {
  * approval — which is why every descriptor should declare it.
  */
 export declare function isWriteTool(tool: ToolFacts, policy?: Agent["toolPolicy"]): boolean;
+/** What decides whether a write waits for a human. */
+export interface ToolGate {
+    /** The run's autonomy, after any step narrowed it. */
+    autonomy: Autonomy;
+    /**
+     * Tools an approval policy guards: these always ask, whatever the autonomy says. `"all"` when
+     * the policies could not be read — then every write asks, because nobody can say which not to.
+     */
+    guarded?: ReadonlySet<string> | "all";
+}
+/**
+ * Must a human sign this call before it runs? The one answer for a workflow's action step and an
+ * agent's tool call. Reads never ask; a guarded tool always does; then the autonomy decides, where
+ * `outward` asks only for what leaves the organisation.
+ */
+export declare function mustAsk(tool: ToolFacts, gate: ToolGate, policy?: Agent["toolPolicy"]): boolean;
 export declare function toolVerdict(tool: ToolFacts, ctx: ToolVerdictContext): ToolVerdict;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencxh/domain",
-  "version": "1.274.0",
+  "version": "1.276.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",