@opencxh/domain 1.264.4 → 1.265.0

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/dist/platform/tool-verdict.d.ts

@@ -0,0 +1,80 @@
+import { Agent } from '../entities/agent/types';
+import { AssistantMode } from '../entities/ai-message/types';
+/**
+ * May this tool be offered to the model this turn — and if it writes, may it run?
+ *
+ * **One function for the layers that used to be five files.** "Why could it not do that" was
+ * answered by `collectTools` (the profile filter), `buildToolRuntime` (the unattended filter),
+ * `resolveToolset` (procedure and mode narrowing), `gate.ts` (the suggest gate) and
+ * `mode.ts` — each with its own copy of "what counts as a write" and its own idea of the order.
+ * They had already drifted once: only the autonomous path could hold a write, only the
+ * interactive one could pin a tool.
+ *
+ * Pure and per-tool on purpose: every one of these rules is about a single tool, and a reader
+ * chasing a missing tool should be able to run this in their head.
+ *
+ * What stays outside: the **scope gate** at the receiving app
+ * (`platform-api/ai-tool/registerAiToolProvider`, which authorises `<kind>:<id>` against the
+ * acting identity). That belongs to the receiver, not to the caller, and it is the one layer a
+ * caller must not be able to answer for itself.
+ */
+export type ToolVerdict = 
+/** Not offered to the model at all. */
+"hidden"
+/** Offered, and it runs. */
+ | "free"
+/** 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";
+    /** 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
+     * way, and it is the difference between "this profile enabled nothing" (an empty set, nothing
+     * passes) and "do not filter".
+     */
+    allowed?: ReadonlySet<string>;
+    /** Whether the acting user's own connections take part. Default `"off"`. */
+    personalTools?: "off" | "allow";
+    /** A procedure's narrowing. Narrows only — a name not already allowed does not come back. */
+    narrow?: ReadonlySet<string>;
+    /**
+     * Is a person watching this turn?
+     *
+     * `false` hides personal tools and anything delivering to a client surface: an unattended run
+     * has nobody to deliver to, and a tool reporting success for something that lands nowhere is
+     * worse than a missing tool.
+     */
+    attended: boolean;
+    /** Interactive only: what the user said this turn is for. Narrows. */
+    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 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.
+     */
+    policy?: Agent["toolPolicy"];
+}
+/**
+ * Does this tool mutate anything? **The mandate decides, then the tool, then the safe default.**
+ *
+ *   `policy` → `access` → "write"
+ *
+ * The agent's policy sits deliberately on top: that is an admin's explicit statement about what
+ * this colleague may do unsupervised, and it may be stricter than what the tool says about
+ * itself. Without `access`, "unknown = write" applies and a read tool would ask for needless
+ * approval — which is why every descriptor should declare it.
+ */
+export declare function isWriteTool(tool: ToolFacts, policy?: Agent["toolPolicy"]): boolean;
+export declare function toolVerdict(tool: ToolFacts, ctx: ToolVerdictContext): ToolVerdict;

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

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

package/package.json

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