@opencxh/domain 1.264.3 → 1.264.5

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.3",
+  "version": "1.264.5",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",