@ultimat3/action 22.9.1 → 22.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/action",
-  "version": "22.9.1",
+  "version": "22.10.0",
   "description": "The action primitive: one declaration projected to route, OpenAPI, client, MCP tool, job handle, tests",
   "license": "MIT",
   "type": "module",
@@ -34,11 +34,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/cache": "22.9.1",
-    "@ultimat3/core": "22.9.1",
-    "@ultimat3/entity": "22.9.1",
-    "@ultimat3/http": "22.9.1",
-    "@ultimat3/policy": "22.9.1",
-    "@ultimat3/schema": "22.9.1"
+    "@ultimat3/cache": "22.10.0",
+    "@ultimat3/core": "22.10.0",
+    "@ultimat3/entity": "22.10.0",
+    "@ultimat3/http": "22.10.0",
+    "@ultimat3/policy": "22.10.0",
+    "@ultimat3/schema": "22.10.0"
   }
 }

package/src/action.ts

@@ -63,6 +63,33 @@ export interface ActionMcp {
    * actor's admin permissions) hands `@ultimat3/mcp` a predicate instead.
    */
   readonly visibleTo?: readonly string[];
+  /**
+   * The tool's display name in an MCP client's UI (`title`, MCP 2025-06-18). Contract text, like
+   * `description`. Omitted: none is published and the client shows the tool name.
+   */
+  readonly title?: string;
+  /**
+   * MCP tool annotations, overriding what `@ultimat3/mcp` derives key by key. An action derives
+   * `readOnlyHint: false`, `destructiveHint: true` and `idempotentHint` from `idempotent`. Hints for
+   * a client's confirmation UI — the policy decides every call whatever they say.
+   *
+   * ```ts
+   * mcp: { expose: true, annotations: { destructiveHint: false, openWorldHint: true } },
+   * ```
+   */
+  readonly annotations?: McpAnnotationHints;
+}
+
+/**
+ * MCP's four tool hints, as the spec spells them. Declared here (tier 3) and in `@ultimat3/query`
+ * because `@ultimat3/mcp` (tier 4) is the reader and cannot be imported; its `McpToolAnnotations`
+ * is the same shape.
+ */
+export interface McpAnnotationHints {
+  readonly readOnlyHint?: boolean;
+  readonly destructiveHint?: boolean;
+  readonly idempotentHint?: boolean;
+  readonly openWorldHint?: boolean;
 }
 
 export interface ActionRateLimit {

package/src/errors.ts

@@ -6,6 +6,7 @@
  */
 import {
   assertNever,
+  deniedCallerFix,
   ERROR_DOCS_URL,
   hasErrorCode,
   registerErrorCodes,
@@ -136,6 +137,7 @@ export class ActionDeniedError extends UltimateError {
       code,
       cause: `${action} denied: ${denialReason(denial)}`,
       fix: `x policy explain ${action} --json   # shows which clause decided and why`,
+      callerFix: deniedCallerFix(),
     });
     this.denial = denial;
   }
@@ -203,11 +205,25 @@ export class InputInvalidError extends UltimateError {
    * `formatIssues` here would pull that package's whole barrel into every browser bundle holding
    * the typed client.
    */
-  constructor(name: string, detail: string, issues?: readonly ValidationIssue[]) {
+  constructor(
+    name: string,
+    detail: string,
+    issues?: readonly ValidationIssue[],
+    /**
+     * What `name` names, in the cause: `'action'` (the default), or `'tool'` when `@ultimat3/mcp`
+     * refuses arguments against a tool's published schema — a query's or a meta tool's, not only an
+     * action's.
+     */
+    subject: 'action' | 'tool' = 'action',
+  ) {
     super({
       code: 'X_INPUT_INVALID',
-      cause: `input for action "${name}" failed validation: ${detail}`,
+      cause: `input for ${subject} "${name}" failed validation: ${detail}`,
       fix: `x actions describe ${name} --json  # prints the expected input schema`,
+      // A remote caller holds the published schema — the MCP `inputSchema`, the OpenAPI request
+      // body — and cannot run `x actions describe`.
+      callerFix:
+        'correct the fields named in cause to match the published input schema (the tool inputSchema, or the OpenAPI request body) and send again — the same input is refused the same way',
       ...(issues === undefined ? {} : { meta: { issues } }),
     });
     this.issues = issues;

package/src/index.ts

@@ -54,6 +54,7 @@ export type {
   ActionRowArgs,
   AnyAction,
   InvokeOptions,
+  McpAnnotationHints,
   McpDescriptorMeta,
 } from './action';
 export { action, describeAction, isAction } from './action';