@dexto/core 1.7.2 → 1.8.0

package/dist/tools/errors.cjs

@@ -137,26 +137,26 @@ class ToolError {
     );
   }
   /**
-   * Confirmation handler missing
+   * Approval handler missing
    */
-  static confirmationHandlerMissing(toolName) {
+  static approvalHandlerMissing(toolName) {
     return new import_DextoRuntimeError.DextoRuntimeError(
-      import_error_codes.ToolErrorCode.CONFIRMATION_HANDLER_MISSING,
+      import_error_codes.ToolErrorCode.APPROVAL_HANDLER_MISSING,
       import_types.ErrorScope.TOOLS,
       import_types.ErrorType.SYSTEM,
-      `Confirmation handler missing for tool '${toolName}'`,
+      `Approval handler missing for tool '${toolName}'`,
       { toolName }
     );
   }
   /**
-   * Confirmation timeout
+   * Approval timeout
    */
-  static confirmationTimeout(toolName, timeoutMs, sessionId) {
+  static approvalTimeout(toolName, timeoutMs, sessionId) {
     return new import_DextoRuntimeError.DextoRuntimeError(
-      import_error_codes.ToolErrorCode.CONFIRMATION_TIMEOUT,
+      import_error_codes.ToolErrorCode.APPROVAL_TIMEOUT,
       import_types.ErrorScope.TOOLS,
       import_types.ErrorType.TIMEOUT,
-      `Tool '${toolName}' confirmation timed out after ${timeoutMs}ms`,
+      `Tool '${toolName}' approval timed out after ${timeoutMs}ms`,
       { toolName, timeoutMs, sessionId }
     );
   }
@@ -185,14 +185,14 @@ class ToolError {
     );
   }
   /**
-   * Confirmation cancelled
+   * Approval cancelled
    */
-  static confirmationCancelled(toolName, reason) {
+  static approvalCancelled(toolName, reason) {
     return new import_DextoRuntimeError.DextoRuntimeError(
-      import_error_codes.ToolErrorCode.CONFIRMATION_CANCELLED,
+      import_error_codes.ToolErrorCode.APPROVAL_CANCELLED,
       import_types.ErrorScope.TOOLS,
       import_types.ErrorType.USER,
-      `Tool confirmation for '${toolName}' was cancelled: ${reason}`,
+      `Tool approval for '${toolName}' was cancelled: ${reason}`,
       { toolName, reason }
     );
   }

package/dist/tools/errors.d.ts

@@ -72,15 +72,15 @@ export declare class ToolError {
         sessionId: string | undefined;
     }>;
     /**
-     * Confirmation handler missing
+     * Approval handler missing
      */
-    static confirmationHandlerMissing(toolName: string): DextoRuntimeError<{
+    static approvalHandlerMissing(toolName: string): DextoRuntimeError<{
         toolName: string;
     }>;
     /**
-     * Confirmation timeout
+     * Approval timeout
      */
-    static confirmationTimeout(toolName: string, timeoutMs: number, sessionId?: string): DextoRuntimeError<{
+    static approvalTimeout(toolName: string, timeoutMs: number, sessionId?: string): DextoRuntimeError<{
         toolName: string;
         timeoutMs: number;
         sessionId: string | undefined;
@@ -97,9 +97,9 @@ export declare class ToolError {
      */
     static configInvalid(message: string): DextoRuntimeError<{}>;
     /**
-     * Confirmation cancelled
+     * Approval cancelled
      */
-    static confirmationCancelled(toolName: string, reason: string): DextoRuntimeError<{
+    static approvalCancelled(toolName: string, reason: string): DextoRuntimeError<{
         toolName: string;
         reason: string;
     }>;

package/dist/tools/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/tools/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAInE;;;GAGG;AACH,qBAAa,SAAS;IAClB;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM;;;IAUhC;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;;;;;IAU3E;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;;;;;IAajF;;;;OAIG;IACH,MAAM,CAAC,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;;;;IAWlE;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;;;;;IAc/E;;;;OAIG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;IAU3F;;;OAGG;IACH,MAAM,CAAC,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;;;;;IAelE;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;;;;IAUxD;;OAEG;IACH,MAAM,CAAC,0BAA0B,CAAC,QAAQ,EAAE,MAAM;;;IAUlD;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;;;;;IAUlF;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;;;;IAUnD;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM;IAUpC;;OAEG;IACH,MAAM,CAAC,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;;;;IAU7D;;OAEG;IACH,MAAM,CAAC,eAAe,CAClB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EAAE,EACzB,OAAO,EAAE,MAAM,GAChB,iBAAiB,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAcrE;;OAEG;IACH,MAAM,CAAC,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,iBAAiB;IAW1F;;OAEG;IACH,MAAM,CAAC,kCAAkC,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB;CAU7E"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/tools/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAInE;;;GAGG;AACH,qBAAa,SAAS;IAClB;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM;;;IAUhC;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;;;;;IAU3E;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;;;;;IAajF;;;;OAIG;IACH,MAAM,CAAC,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;;;;IAWlE;;OAEG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;;;;;IAc/E;;;;OAIG;IACH,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;IAU3F;;;OAGG;IACH,MAAM,CAAC,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;;;;;IAelE;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;;;;IAUxD;;OAEG;IACH,MAAM,CAAC,sBAAsB,CAAC,QAAQ,EAAE,MAAM;;;IAU9C;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;;;;;IAU9E;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;;;;IAUnD;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM;IAUpC;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;;;;IAUzD;;OAEG;IACH,MAAM,CAAC,eAAe,CAClB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EAAE,EACzB,OAAO,EAAE,MAAM,GAChB,iBAAiB,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAcrE;;OAEG;IACH,MAAM,CAAC,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,GAAG,iBAAiB;IAW1F;;OAEG;IACH,MAAM,CAAC,kCAAkC,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB;CAU7E"}

package/dist/tools/errors.js

@@ -1,4 +1,4 @@
-import "../chunk-PTJYTZNU.js";
+import "../chunk-C6A6W6XS.js";
 import { DextoRuntimeError } from "../errors/DextoRuntimeError.js";
 import { ErrorScope, ErrorType } from "../errors/types.js";
 import { ToolErrorCode } from "./error-codes.js";
@@ -115,26 +115,26 @@ class ToolError {
     );
   }
   /**
-   * Confirmation handler missing
+   * Approval handler missing
    */
-  static confirmationHandlerMissing(toolName) {
+  static approvalHandlerMissing(toolName) {
     return new DextoRuntimeError(
-      ToolErrorCode.CONFIRMATION_HANDLER_MISSING,
+      ToolErrorCode.APPROVAL_HANDLER_MISSING,
       ErrorScope.TOOLS,
       ErrorType.SYSTEM,
-      `Confirmation handler missing for tool '${toolName}'`,
+      `Approval handler missing for tool '${toolName}'`,
       { toolName }
     );
   }
   /**
-   * Confirmation timeout
+   * Approval timeout
    */
-  static confirmationTimeout(toolName, timeoutMs, sessionId) {
+  static approvalTimeout(toolName, timeoutMs, sessionId) {
     return new DextoRuntimeError(
-      ToolErrorCode.CONFIRMATION_TIMEOUT,
+      ToolErrorCode.APPROVAL_TIMEOUT,
       ErrorScope.TOOLS,
       ErrorType.TIMEOUT,
-      `Tool '${toolName}' confirmation timed out after ${timeoutMs}ms`,
+      `Tool '${toolName}' approval timed out after ${timeoutMs}ms`,
       { toolName, timeoutMs, sessionId }
     );
   }
@@ -163,14 +163,14 @@ class ToolError {
     );
   }
   /**
-   * Confirmation cancelled
+   * Approval cancelled
    */
-  static confirmationCancelled(toolName, reason) {
+  static approvalCancelled(toolName, reason) {
     return new DextoRuntimeError(
-      ToolErrorCode.CONFIRMATION_CANCELLED,
+      ToolErrorCode.APPROVAL_CANCELLED,
       ErrorScope.TOOLS,
       ErrorType.USER,
-      `Tool confirmation for '${toolName}' was cancelled: ${reason}`,
+      `Tool approval for '${toolName}' was cancelled: ${reason}`,
       { toolName, reason }
     );
   }

package/dist/tools/index.cjs

@@ -19,6 +19,7 @@ var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "defau
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var tools_exports = {};
 __export(tools_exports, {
+  SessionToolPreferencesSchema: () => import_session_tool_preferences_store.SessionToolPreferencesSchema,
   ToolError: () => import_errors.ToolError,
   ToolErrorCode: () => import_error_codes.ToolErrorCode,
   ToolManager: () => import_tool_manager.ToolManager,
@@ -27,6 +28,7 @@ __export(tools_exports, {
 module.exports = __toCommonJS(tools_exports);
 __reExport(tools_exports, require("./types.js"), module.exports);
 var import_define_tool = require("./define-tool.js");
+var import_session_tool_preferences_store = require("./session-tool-preferences-store.js");
 __reExport(tools_exports, require("./display-types.js"), module.exports);
 __reExport(tools_exports, require("./schemas.js"), module.exports);
 __reExport(tools_exports, require("./presentation.js"), module.exports);
@@ -35,6 +37,7 @@ var import_error_codes = require("./error-codes.js");
 var import_tool_manager = require("./tool-manager.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  SessionToolPreferencesSchema,
   ToolError,
   ToolErrorCode,
   ToolManager,

package/dist/tools/index.d.ts

@@ -6,6 +6,8 @@
  */
 export * from './types.js';
 export { defineTool } from './define-tool.js';
+export { SessionToolPreferencesSchema } from './session-tool-preferences-store.js';
+export type { SessionToolPreferences } from './session-tool-preferences-store.js';
 export * from './display-types.js';
 export * from './schemas.js';
 export * from './presentation.js';
@@ -13,4 +15,5 @@ export type { ToolCallMetadata, ToolCallMetaWrapper } from './tool-call-metadata
 export { ToolError } from './errors.js';
 export { ToolErrorCode } from './error-codes.js';
 export { ToolManager, type ToolExecutionContextFactory } from './tool-manager.js';
+export type { ExecutableToolCall, RecordedToolApproval, ToolApprovalDecisionApplication, ToolApprovalRecordIdentity, ApprovalRequiredPreparedToolCall, PreparedToolCall, PrepareToolCallInput, } from './tool-manager.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,YAAY,CAAC;AAG3B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,cAAc,oBAAoB,CAAC;AAGnC,cAAc,cAAc,CAAC;AAG7B,cAAc,mBAAmB,CAAC;AAClC,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAGrF,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,OAAO,EAAE,WAAW,EAAE,KAAK,2BAA2B,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,YAAY,CAAC;AAG3B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,4BAA4B,EAAE,MAAM,qCAAqC,CAAC;AACnF,YAAY,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAGlF,cAAc,oBAAoB,CAAC;AAGnC,cAAc,cAAc,CAAC;AAG7B,cAAc,mBAAmB,CAAC;AAClC,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAGrF,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,OAAO,EAAE,WAAW,EAAE,KAAK,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAClF,YAAY,EACR,kBAAkB,EAClB,oBAAoB,EACpB,+BAA+B,EAC/B,0BAA0B,EAC1B,gCAAgC,EAChC,gBAAgB,EAChB,oBAAoB,GACvB,MAAM,mBAAmB,CAAC"}

package/dist/tools/index.js

@@ -1,6 +1,7 @@
-import "../chunk-PTJYTZNU.js";
+import "../chunk-C6A6W6XS.js";
 export * from "./types.js";
 import { defineTool } from "./define-tool.js";
+import { SessionToolPreferencesSchema } from "./session-tool-preferences-store.js";
 export * from "./display-types.js";
 export * from "./schemas.js";
 export * from "./presentation.js";
@@ -8,6 +9,7 @@ import { ToolError } from "./errors.js";
 import { ToolErrorCode } from "./error-codes.js";
 import { ToolManager } from "./tool-manager.js";
 export {
+  SessionToolPreferencesSchema,
   ToolError,
   ToolErrorCode,
   ToolManager,

package/dist/tools/pattern-utils.js

@@ -1,4 +1,4 @@
-import "../chunk-PTJYTZNU.js";
+import "../chunk-C6A6W6XS.js";
 function patternCovers(storedPattern, targetPatternKey) {
   if (storedPattern === targetPatternKey) return true;
   const storedBase = storedPattern.endsWith(" *") ? storedPattern.slice(0, -2) : storedPattern;

package/dist/tools/presentation/tool-presentation.cjs

@@ -0,0 +1,182 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var tool_presentation_exports = {};
+__export(tool_presentation_exports, {
+  ToolPresentation: () => ToolPresentation
+});
+module.exports = __toCommonJS(tool_presentation_exports);
+var import_errors = require("../../errors/index.js");
+var import_error_codes = require("../error-codes.js");
+const MCP_TOOL_PREFIX = "mcp--";
+class ToolPresentation {
+  constructor(getLocalTool, validateLocalToolArgs, buildToolExecutionContext, logger) {
+    this.getLocalTool = getLocalTool;
+    this.validateLocalToolArgs = validateLocalToolArgs;
+    this.buildToolExecutionContext = buildToolExecutionContext;
+    this.logger = logger;
+  }
+  buildGenericSnapshot(toolName) {
+    const isMcp = toolName.startsWith(MCP_TOOL_PREFIX);
+    const fallbackTitle = isMcp ? this.titleCaseMcpToolName(toolName) : this.toTitleCase(toolName);
+    const snapshot = {
+      version: 1,
+      source: {
+        type: isMcp ? "mcp" : "local"
+      },
+      header: {
+        title: fallbackTitle
+      }
+    };
+    if (snapshot.source?.type === "mcp") {
+      const actualToolName = toolName.substring(MCP_TOOL_PREFIX.length);
+      const parts = actualToolName.split("--");
+      if (parts.length >= 2 && parts[0]) {
+        snapshot.source.mcpServerName = parts[0];
+      }
+    }
+    return snapshot;
+  }
+  snapshotForToolCallEvent(input) {
+    const fallback = this.buildGenericSnapshot(input.toolName);
+    if (input.toolName.startsWith(MCP_TOOL_PREFIX)) {
+      return fallback;
+    }
+    const presentation = this.getLocalTool(input.toolName)?.presentation;
+    if (!presentation?.describeHeader && !presentation?.describeArgs) {
+      return fallback;
+    }
+    try {
+      const validatedArgs = this.validateLocalToolArgs(input.toolName, input.args);
+      const context = this.buildToolExecutionContext(input);
+      let nextSnapshot = fallback;
+      const header = presentation.describeHeader?.(validatedArgs, context);
+      if (!isPromiseLike(header) && header) {
+        nextSnapshot = {
+          ...nextSnapshot,
+          header: { ...nextSnapshot.header, ...header }
+        };
+      }
+      const argsPresentation = presentation.describeArgs?.(validatedArgs, context);
+      if (!isPromiseLike(argsPresentation) && argsPresentation) {
+        nextSnapshot = {
+          ...nextSnapshot,
+          args: argsPresentation
+        };
+      }
+      return nextSnapshot;
+    } catch (error) {
+      this.logger.debug(
+        `Tool presentation snapshot generation failed for '${input.toolName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+      return fallback;
+    }
+  }
+  async snapshotForCall(input) {
+    const fallback = this.buildGenericSnapshot(input.toolName);
+    if (input.toolName.startsWith(MCP_TOOL_PREFIX)) {
+      return fallback;
+    }
+    const presentation = this.getLocalTool(input.toolName)?.presentation;
+    if (!presentation?.describeHeader && !presentation?.describeArgs) {
+      return fallback;
+    }
+    try {
+      const context = this.buildToolExecutionContext(input);
+      const describedHeader = presentation.describeHeader ? await Promise.resolve(presentation.describeHeader(input.args, context)) : null;
+      const describedArgs = presentation.describeArgs ? await Promise.resolve(presentation.describeArgs(input.args, context)) : null;
+      return {
+        ...fallback,
+        ...describedHeader ? { header: { ...fallback.header, ...describedHeader } } : {},
+        ...describedArgs ? { args: describedArgs } : {}
+      };
+    } catch (error) {
+      this.logger.debug(
+        `Tool presentation snapshot generation failed for '${input.toolName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+      return fallback;
+    }
+  }
+  async augmentWithResult(input) {
+    if (input.toolName.startsWith(MCP_TOOL_PREFIX)) {
+      return input.snapshot;
+    }
+    const describeResult = this.getLocalTool(input.toolName)?.presentation?.describeResult;
+    if (!describeResult) {
+      return input.snapshot;
+    }
+    try {
+      const context = this.buildToolExecutionContext(input);
+      const resultPresentation = await Promise.resolve(
+        describeResult(input.result, input.args, context)
+      );
+      if (!resultPresentation) {
+        return input.snapshot;
+      }
+      return {
+        ...input.snapshot,
+        result: resultPresentation
+      };
+    } catch (error) {
+      this.logger.debug(
+        `Tool result presentation snapshot generation failed for '${input.toolName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+      return input.snapshot;
+    }
+  }
+  async preview(input) {
+    if (input.toolName.startsWith(MCP_TOOL_PREFIX)) {
+      return void 0;
+    }
+    const preview = this.getLocalTool(input.toolName)?.presentation?.preview;
+    if (!preview) {
+      return void 0;
+    }
+    try {
+      const context = this.buildToolExecutionContext(input);
+      const displayPreview = await Promise.resolve(preview(input.args, context));
+      this.logger.debug(`Generated preview for ${input.toolName}`);
+      return displayPreview ?? void 0;
+    } catch (error) {
+      if (error instanceof import_errors.DextoRuntimeError && error.code === import_error_codes.ToolErrorCode.VALIDATION_FAILED) {
+        this.logger.debug(`Validation failed for ${input.toolName}: ${error.message}`);
+        throw error;
+      }
+      this.logger.debug(
+        `Tool preview generation failed for '${input.toolName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+      return void 0;
+    }
+  }
+  titleCaseMcpToolName(toolName) {
+    const actualToolName = toolName.substring(MCP_TOOL_PREFIX.length);
+    const parts = actualToolName.split("--");
+    const toolPart = parts.length >= 2 ? parts.slice(1).join("--") : actualToolName;
+    return this.toTitleCase(toolPart);
+  }
+  toTitleCase(name) {
+    return name.replace(/[_-]+/g, " ").split(" ").filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+  }
+}
+function isPromiseLike(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ToolPresentation
+});

package/dist/tools/presentation/tool-presentation.d.ts

@@ -0,0 +1,51 @@
+import type { Logger } from '../../logger/v2/types.js';
+import type { AgentRunContext } from '../../runtime/run-context.js';
+import type { Tool, ToolExecutionContext, ToolPresentationSnapshotV1 } from '../types.js';
+import type { ToolDisplayData } from '../display-types.js';
+type BuildToolExecutionContext = (options: {
+    sessionId?: string | undefined;
+    toolCallId?: string | undefined;
+    runContext?: AgentRunContext | undefined;
+}) => ToolExecutionContext;
+export declare class ToolPresentation {
+    private readonly getLocalTool;
+    private readonly validateLocalToolArgs;
+    private readonly buildToolExecutionContext;
+    private readonly logger;
+    constructor(getLocalTool: (toolName: string) => Tool | undefined, validateLocalToolArgs: (toolName: string, args: Record<string, unknown>) => Record<string, unknown>, buildToolExecutionContext: BuildToolExecutionContext, logger: Logger);
+    buildGenericSnapshot(toolName: string): ToolPresentationSnapshotV1;
+    snapshotForToolCallEvent(input: {
+        toolName: string;
+        args: Record<string, unknown>;
+        toolCallId: string;
+        sessionId?: string | undefined;
+        runContext?: AgentRunContext | undefined;
+    }): ToolPresentationSnapshotV1;
+    snapshotForCall(input: {
+        toolName: string;
+        args: Record<string, unknown>;
+        toolCallId: string;
+        sessionId?: string | undefined;
+        runContext?: AgentRunContext | undefined;
+    }): Promise<ToolPresentationSnapshotV1>;
+    augmentWithResult(input: {
+        toolName: string;
+        snapshot: ToolPresentationSnapshotV1;
+        result: unknown;
+        args: Record<string, unknown>;
+        toolCallId: string;
+        sessionId?: string | undefined;
+        runContext?: AgentRunContext | undefined;
+    }): Promise<ToolPresentationSnapshotV1>;
+    preview(input: {
+        toolName: string;
+        args: Record<string, unknown>;
+        toolCallId: string;
+        sessionId?: string | undefined;
+        runContext?: AgentRunContext | undefined;
+    }): Promise<ToolDisplayData | undefined>;
+    private titleCaseMcpToolName;
+    private toTitleCase;
+}
+export {};
+//# sourceMappingURL=tool-presentation.d.ts.map

package/dist/tools/presentation/tool-presentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-presentation.d.ts","sourceRoot":"","sources":["../../../src/tools/presentation/tool-presentation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEpE,OAAO,KAAK,EAAE,IAAI,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAI3D,KAAK,yBAAyB,GAAG,CAAC,OAAO,EAAE;IACvC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,UAAU,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;CAC5C,KAAK,oBAAoB,CAAC;AAE3B,qBAAa,gBAAgB;IAErB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,qBAAqB;IAItC,OAAO,CAAC,QAAQ,CAAC,yBAAyB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM;gBANN,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,SAAS,EACpD,qBAAqB,EAAE,CACpC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACX,yBAAyB,EAAE,yBAAyB,EACpD,MAAM,EAAE,MAAM;IAGnC,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,0BAA0B;IA2BlE,wBAAwB,CAAC,KAAK,EAAE;QAC5B,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9B,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC/B,UAAU,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;KAC5C,GAAG,0BAA0B;IA4CxB,eAAe,CAAC,KAAK,EAAE;QACzB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9B,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC/B,UAAU,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;KAC5C,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAoCjC,iBAAiB,CAAC,KAAK,EAAE;QAC3B,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,0BAA0B,CAAC;QACrC,MAAM,EAAE,OAAO,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9B,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC/B,UAAU,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;KAC5C,GAAG,OAAO,CAAC,0BAA0B,CAAC;IAgCjC,OAAO,CAAC,KAAK,EAAE;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9B,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC/B,UAAU,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;KAC5C,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAgCxC,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,WAAW;CAQtB"}

package/dist/tools/presentation/tool-presentation.js

@@ -0,0 +1,159 @@
+import "../../chunk-C6A6W6XS.js";
+import { DextoRuntimeError } from "../../errors/index.js";
+import { ToolErrorCode } from "../error-codes.js";
+const MCP_TOOL_PREFIX = "mcp--";
+class ToolPresentation {
+  constructor(getLocalTool, validateLocalToolArgs, buildToolExecutionContext, logger) {
+    this.getLocalTool = getLocalTool;
+    this.validateLocalToolArgs = validateLocalToolArgs;
+    this.buildToolExecutionContext = buildToolExecutionContext;
+    this.logger = logger;
+  }
+  buildGenericSnapshot(toolName) {
+    const isMcp = toolName.startsWith(MCP_TOOL_PREFIX);
+    const fallbackTitle = isMcp ? this.titleCaseMcpToolName(toolName) : this.toTitleCase(toolName);
+    const snapshot = {
+      version: 1,
+      source: {
+        type: isMcp ? "mcp" : "local"
+      },
+      header: {
+        title: fallbackTitle
+      }
+    };
+    if (snapshot.source?.type === "mcp") {
+      const actualToolName = toolName.substring(MCP_TOOL_PREFIX.length);
+      const parts = actualToolName.split("--");
+      if (parts.length >= 2 && parts[0]) {
+        snapshot.source.mcpServerName = parts[0];
+      }
+    }
+    return snapshot;
+  }
+  snapshotForToolCallEvent(input) {
+    const fallback = this.buildGenericSnapshot(input.toolName);
+    if (input.toolName.startsWith(MCP_TOOL_PREFIX)) {
+      return fallback;
+    }
+    const presentation = this.getLocalTool(input.toolName)?.presentation;
+    if (!presentation?.describeHeader && !presentation?.describeArgs) {
+      return fallback;
+    }
+    try {
+      const validatedArgs = this.validateLocalToolArgs(input.toolName, input.args);
+      const context = this.buildToolExecutionContext(input);
+      let nextSnapshot = fallback;
+      const header = presentation.describeHeader?.(validatedArgs, context);
+      if (!isPromiseLike(header) && header) {
+        nextSnapshot = {
+          ...nextSnapshot,
+          header: { ...nextSnapshot.header, ...header }
+        };
+      }
+      const argsPresentation = presentation.describeArgs?.(validatedArgs, context);
+      if (!isPromiseLike(argsPresentation) && argsPresentation) {
+        nextSnapshot = {
+          ...nextSnapshot,
+          args: argsPresentation
+        };
+      }
+      return nextSnapshot;
+    } catch (error) {
+      this.logger.debug(
+        `Tool presentation snapshot generation failed for '${input.toolName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+      return fallback;
+    }
+  }
+  async snapshotForCall(input) {
+    const fallback = this.buildGenericSnapshot(input.toolName);
+    if (input.toolName.startsWith(MCP_TOOL_PREFIX)) {
+      return fallback;
+    }
+    const presentation = this.getLocalTool(input.toolName)?.presentation;
+    if (!presentation?.describeHeader && !presentation?.describeArgs) {
+      return fallback;
+    }
+    try {
+      const context = this.buildToolExecutionContext(input);
+      const describedHeader = presentation.describeHeader ? await Promise.resolve(presentation.describeHeader(input.args, context)) : null;
+      const describedArgs = presentation.describeArgs ? await Promise.resolve(presentation.describeArgs(input.args, context)) : null;
+      return {
+        ...fallback,
+        ...describedHeader ? { header: { ...fallback.header, ...describedHeader } } : {},
+        ...describedArgs ? { args: describedArgs } : {}
+      };
+    } catch (error) {
+      this.logger.debug(
+        `Tool presentation snapshot generation failed for '${input.toolName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+      return fallback;
+    }
+  }
+  async augmentWithResult(input) {
+    if (input.toolName.startsWith(MCP_TOOL_PREFIX)) {
+      return input.snapshot;
+    }
+    const describeResult = this.getLocalTool(input.toolName)?.presentation?.describeResult;
+    if (!describeResult) {
+      return input.snapshot;
+    }
+    try {
+      const context = this.buildToolExecutionContext(input);
+      const resultPresentation = await Promise.resolve(
+        describeResult(input.result, input.args, context)
+      );
+      if (!resultPresentation) {
+        return input.snapshot;
+      }
+      return {
+        ...input.snapshot,
+        result: resultPresentation
+      };
+    } catch (error) {
+      this.logger.debug(
+        `Tool result presentation snapshot generation failed for '${input.toolName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+      return input.snapshot;
+    }
+  }
+  async preview(input) {
+    if (input.toolName.startsWith(MCP_TOOL_PREFIX)) {
+      return void 0;
+    }
+    const preview = this.getLocalTool(input.toolName)?.presentation?.preview;
+    if (!preview) {
+      return void 0;
+    }
+    try {
+      const context = this.buildToolExecutionContext(input);
+      const displayPreview = await Promise.resolve(preview(input.args, context));
+      this.logger.debug(`Generated preview for ${input.toolName}`);
+      return displayPreview ?? void 0;
+    } catch (error) {
+      if (error instanceof DextoRuntimeError && error.code === ToolErrorCode.VALIDATION_FAILED) {
+        this.logger.debug(`Validation failed for ${input.toolName}: ${error.message}`);
+        throw error;
+      }
+      this.logger.debug(
+        `Tool preview generation failed for '${input.toolName}': ${error instanceof Error ? error.message : String(error)}`
+      );
+      return void 0;
+    }
+  }
+  titleCaseMcpToolName(toolName) {
+    const actualToolName = toolName.substring(MCP_TOOL_PREFIX.length);
+    const parts = actualToolName.split("--");
+    const toolPart = parts.length >= 2 ? parts.slice(1).join("--") : actualToolName;
+    return this.toTitleCase(toolPart);
+  }
+  toTitleCase(name) {
+    return name.replace(/[_-]+/g, " ").split(" ").filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+  }
+}
+function isPromiseLike(value) {
+  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+export {
+  ToolPresentation
+};

package/dist/tools/presentation.js

@@ -1,4 +1,4 @@
-import "../chunk-PTJYTZNU.js";
+import "../chunk-C6A6W6XS.js";
 function createLocalToolCallHeader(options) {
   return {
     title: options.title,