@opencxh/domain 1.264.5 → 1.265.1

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

@@ -45,7 +45,20 @@ export interface ToolCatalogEntry {
     surface?: "interactive";
     /** 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";
 }
+/**
+ * How an action can be taken back. Reads the fail-safe default in one place, so no caller has to
+ * remember that absent means irreversible.
+ *
+ * A **read** is `"idempotent"` by construction: it changed nothing, so there is nothing to
+ * 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";
 /**
  * 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
@@ -199,6 +212,41 @@ export interface AiToolDescriptor extends AiTool {
      * whichever one its description matched. See `tools/mode.ts` in the ai app.
      */
     produces?: "draft";
+    /**
+     * Can this be taken back, and how?
+     *
+     * The question a rule engine forces: one badly written rule does not touch one conversation
+     * but forty, and "undo this run" then has to say honestly what it can and cannot put back.
+     * This generalises `DocumentOperation.undoable`, which already carries the idea for document
+     * edits — *"'I changed it, undo if you disagree' is a promise that has to hold."*
+     *
+     * - `"self"` — **the same call with the previous value undoes it** (status, assignee, an
+     *   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.
+     * - `"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.
+     * - `"idempotent"` — running it again is the repair (a sync landing). Replay, never reverse.
+     *
+     * **Absent means `"none"`.** The same fail-safe-by-absence as {@link AiToolDescriptor.effect},
+     * and for the same reason. Guessing wrong this way costs a button that stays grey; the other
+     * way it costs a promise that breaks.
+     *
+     * **What `"self"` demands before you declare it, and why nothing does yet.** Replaying the
+     * previous value only works if the tool can express *every* previous value — including "there
+     * was nothing here". Today several cannot: `update_interaction` does
+     * `if (assignedUserId) patch.assignedUserId = …`, so an empty string is falsy and an
+     * assignment cannot be taken back; the same shape as the older scar where `null` never
+     * survives the invoke transport and clearing a field needs an explicit clear-list. So a tool
+     * 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";
 }
 /**
  * Body of `POST /provider/ai-tools/invoke`. Replaces five inline structural types (the caller in

package/dist/platform/tool-reversible.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

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