@mxf-dev/core 1.0.0 → 2.0.0

package/dist/protocols/mcp/ToolError.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/BradA1878/model-exchange-framework
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * ToolError.ts
+ *
+ * The single error type for MCP tool handlers.
+ *
+ * Before this existed, tool failures were encoded three different ways — a thrown
+ * Error, a `{ success: false }` object, or a result whose `data` happened to hold
+ * an `error` string — so callers could not tell a failure from a result. Handlers
+ * written with `defineTool` throw a ToolError; the factory turns it into one
+ * result envelope with `isError: true`.
+ *
+ * `code` is a stable, machine-readable classification. `message` is written for
+ * the model that will read it: say what failed and what to do next.
+ */
+/**
+ * Machine-readable failure classifications.
+ *
+ * These map to how a caller should react, not to where the failure happened:
+ * - INVALID_INPUT: arguments did not satisfy the tool's schema or its own checks.
+ *   The model should fix the arguments and retry.
+ * - NOT_FOUND: a referenced entity (task, plan, file, server) does not exist.
+ * - PERMISSION_DENIED: the operation was blocked by a security policy.
+ * - PRECONDITION_FAILED: the system is not in a state where this can run
+ *   (for example a required service is not initialized).
+ * - EXECUTION_FAILED: the tool ran but the underlying operation failed.
+ * - UPSTREAM_ERROR: a dependency the tool calls out to failed (external MCP
+ *   server, HTTP API, database).
+ * - NOT_IMPLEMENTED: the requested mode or option is not supported.
+ */
+export type ToolErrorCode = 'INVALID_INPUT' | 'NOT_FOUND' | 'PERMISSION_DENIED' | 'PRECONDITION_FAILED' | 'EXECUTION_FAILED' | 'UPSTREAM_ERROR' | 'NOT_IMPLEMENTED';
+/**
+ * Serialized form of a ToolError, carried as the `data` of an error envelope.
+ */
+export interface ToolErrorData {
+    /** Always true — lets a reader detect an error payload without shape sniffing */
+    error: true;
+    /** Stable classification */
+    code: ToolErrorCode;
+    /** Human/model-readable description of what failed */
+    message: string;
+    /** Name of the tool that failed */
+    tool?: string;
+    /** Structured, tool-specific context (never secrets) */
+    details?: Record<string, unknown>;
+}
+/**
+ * The error type thrown by tool handlers.
+ *
+ * Use the static constructors rather than `new ToolError(...)` where one fits —
+ * they keep codes consistent across the ~184 tools.
+ */
+export declare class ToolError extends Error {
+    /** Stable, machine-readable classification */
+    readonly code: ToolErrorCode;
+    /** Structured context for the caller. Must not contain secrets. */
+    readonly details?: Record<string, unknown>;
+    /**
+     * The original error, when this ToolError wraps one.
+     *
+     * Set as a plain property rather than through the ES2022 `Error(msg, { cause })`
+     * option, because the test tsconfig compiles against an older lib where that
+     * constructor overload does not exist.
+     */
+    readonly cause?: unknown;
+    /** Tool name, set by defineTool when the error passes through the factory */
+    toolName?: string;
+    constructor(code: ToolErrorCode, message: string, options?: {
+        details?: Record<string, unknown>;
+        cause?: unknown;
+    });
+    /** Arguments did not satisfy the schema or the handler's own checks. */
+    static invalidInput(message: string, details?: Record<string, unknown>): ToolError;
+    /** A referenced entity does not exist. */
+    static notFound(message: string, details?: Record<string, unknown>): ToolError;
+    /** Blocked by a security policy. */
+    static permissionDenied(message: string, details?: Record<string, unknown>): ToolError;
+    /** The system is not in a state where this operation can run. */
+    static preconditionFailed(message: string, details?: Record<string, unknown>): ToolError;
+    /** The tool ran but the underlying operation failed. */
+    static executionFailed(message: string, options?: {
+        details?: Record<string, unknown>;
+        cause?: unknown;
+    }): ToolError;
+    /** A dependency the tool calls out to failed. */
+    static upstream(message: string, options?: {
+        details?: Record<string, unknown>;
+        cause?: unknown;
+    }): ToolError;
+    /** The requested mode or option is not supported. */
+    static notImplemented(message: string, details?: Record<string, unknown>): ToolError;
+    /**
+     * Serialize to the payload carried in an error result envelope.
+     */
+    toData(): ToolErrorData;
+}
+/**
+ * Coerce any thrown value into a ToolError.
+ *
+ * A plain `throw new Error(...)` from a handler (or from a library it calls)
+ * becomes an EXECUTION_FAILED ToolError with the original attached as `cause`,
+ * so every failure leaves the factory in the same shape.
+ */
+export declare function toToolError(thrown: unknown): ToolError;
+//# sourceMappingURL=ToolError.d.ts.map

package/dist/protocols/mcp/ToolError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolError.d.ts","sourceRoot":"","sources":["../../../src/protocols/mcp/ToolError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,GACnB,eAAe,GACf,WAAW,GACX,mBAAmB,GACnB,qBAAqB,GACrB,kBAAkB,GAClB,gBAAgB,GAChB,iBAAiB,CAAC;AAExB;;GAEG;AACH,MAAM,WAAW,aAAa;IAC1B,iFAAiF;IACjF,KAAK,EAAE,IAAI,CAAC;IACZ,4BAA4B;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAChC,8CAA8C;IAC9C,SAAgB,IAAI,EAAE,aAAa,CAAC;IACpC,mEAAmE;IACnE,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClD;;;;;;OAMG;IACH,SAAgB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChC,6EAA6E;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;gBAGrB,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;IAapE,wEAAwE;WAC1D,YAAY,CACtB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,SAAS;IAIZ,0CAA0C;WAC5B,QAAQ,CAClB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,SAAS;IAIZ,oCAAoC;WACtB,gBAAgB,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,SAAS;IAIZ,iEAAiE;WACnD,kBAAkB,CAC5B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,SAAS;IAIZ,wDAAwD;WAC1C,eAAe,CACzB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GACjE,SAAS;IAIZ,iDAAiD;WACnC,QAAQ,CAClB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GACjE,SAAS;IAIZ,qDAAqD;WACvC,cAAc,CACxB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,SAAS;IAIZ;;OAEG;IACI,MAAM,IAAI,aAAa;CASjC;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAUtD"}

package/dist/protocols/mcp/ToolError.js

@@ -0,0 +1,108 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/BradA1878/model-exchange-framework
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+/**
+ * The error type thrown by tool handlers.
+ *
+ * Use the static constructors rather than `new ToolError(...)` where one fits —
+ * they keep codes consistent across the ~184 tools.
+ */
+export class ToolError extends Error {
+    /** Stable, machine-readable classification */
+    code;
+    /** Structured context for the caller. Must not contain secrets. */
+    details;
+    /**
+     * The original error, when this ToolError wraps one.
+     *
+     * Set as a plain property rather than through the ES2022 `Error(msg, { cause })`
+     * option, because the test tsconfig compiles against an older lib where that
+     * constructor overload does not exist.
+     */
+    cause;
+    /** Tool name, set by defineTool when the error passes through the factory */
+    toolName;
+    constructor(code, message, options) {
+        super(message);
+        this.name = 'ToolError';
+        this.code = code;
+        this.details = options?.details;
+        this.cause = options?.cause;
+        // Restore the prototype chain — required for `instanceof` to work when
+        // the compile target is ES5/ES2015 and Error is subclassed.
+        Object.setPrototypeOf(this, ToolError.prototype);
+    }
+    /** Arguments did not satisfy the schema or the handler's own checks. */
+    static invalidInput(message, details) {
+        return new ToolError('INVALID_INPUT', message, { details });
+    }
+    /** A referenced entity does not exist. */
+    static notFound(message, details) {
+        return new ToolError('NOT_FOUND', message, { details });
+    }
+    /** Blocked by a security policy. */
+    static permissionDenied(message, details) {
+        return new ToolError('PERMISSION_DENIED', message, { details });
+    }
+    /** The system is not in a state where this operation can run. */
+    static preconditionFailed(message, details) {
+        return new ToolError('PRECONDITION_FAILED', message, { details });
+    }
+    /** The tool ran but the underlying operation failed. */
+    static executionFailed(message, options) {
+        return new ToolError('EXECUTION_FAILED', message, options);
+    }
+    /** A dependency the tool calls out to failed. */
+    static upstream(message, options) {
+        return new ToolError('UPSTREAM_ERROR', message, options);
+    }
+    /** The requested mode or option is not supported. */
+    static notImplemented(message, details) {
+        return new ToolError('NOT_IMPLEMENTED', message, { details });
+    }
+    /**
+     * Serialize to the payload carried in an error result envelope.
+     */
+    toData() {
+        return {
+            error: true,
+            code: this.code,
+            message: this.message,
+            ...(this.toolName ? { tool: this.toolName } : {}),
+            ...(this.details ? { details: this.details } : {})
+        };
+    }
+}
+/**
+ * Coerce any thrown value into a ToolError.
+ *
+ * A plain `throw new Error(...)` from a handler (or from a library it calls)
+ * becomes an EXECUTION_FAILED ToolError with the original attached as `cause`,
+ * so every failure leaves the factory in the same shape.
+ */
+export function toToolError(thrown) {
+    if (thrown instanceof ToolError) {
+        return thrown;
+    }
+    if (thrown instanceof Error) {
+        return new ToolError('EXECUTION_FAILED', thrown.message, { cause: thrown });
+    }
+    return new ToolError('EXECUTION_FAILED', String(thrown), { cause: thrown });
+}
+//# sourceMappingURL=ToolError.js.map

package/dist/protocols/mcp/ToolError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolError.js","sourceRoot":"","sources":["../../../src/protocols/mcp/ToolError.ts"],"names":[],"mappings":"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"}

package/dist/protocols/mcp/converters/IFormatConverter.d.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**

package/dist/protocols/mcp/converters/IFormatConverter.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**

package/dist/protocols/mcp/converters/UnifiedMessageConverter.d.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**

package/dist/protocols/mcp/converters/UnifiedMessageConverter.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**

package/dist/protocols/mcp/converters/adapters/AnthropicMessageAdapter.d.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**

package/dist/protocols/mcp/converters/adapters/AnthropicMessageAdapter.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**

package/dist/protocols/mcp/converters/adapters/GeminiMessageAdapter.d.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**

package/dist/protocols/mcp/converters/adapters/GeminiMessageAdapter.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**

package/dist/protocols/mcp/converters/adapters/OpenAiMessageAdapter.d.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**

package/dist/protocols/mcp/converters/adapters/OpenAiMessageAdapter.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**

package/dist/protocols/mcp/converters/adapters/OpenRouterMessageAdapter.d.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**

package/dist/protocols/mcp/converters/adapters/OpenRouterMessageAdapter.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**

package/dist/protocols/mcp/converters/adapters/XaiMessageAdapter.d.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**

package/dist/protocols/mcp/converters/adapters/XaiMessageAdapter.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  *
  * @author Brad Anderson <BradA1878@pm.me>
- * @repository https://github.com/mxf-dev/mxf
+ * @repository https://github.com/BradA1878/model-exchange-framework
  * @documentation https://mxf-dev.github.io/mxf/
  */
 /**

package/dist/protocols/mcp/defineTool.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/BradA1878/model-exchange-framework
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+import { McpToolDefinition, McpToolHandlerResult, McpToolResultContent } from './McpServerTypes.js';
+import { McpToolExample } from './McpToolSchema.js';
+import { ToolErrorData } from './ToolError.js';
+/**
+ * The single result shape every `defineTool` tool returns.
+ *
+ * Extends the framework's McpToolHandlerResult, so these tools drop into the
+ * existing registries and socket paths unchanged, and adds the explicit
+ * `isError` flag those shapes were missing.
+ */
+export interface ToolResultEnvelope<TData = unknown> extends McpToolHandlerResult {
+    /** Result payload. `data` holds the tool's own output, or a ToolErrorData on failure. */
+    content: McpToolResultContent & {
+        data: TData | ToolErrorData;
+    };
+    /** True when the tool failed. Callers branch on this — never on payload shape. */
+    isError: boolean;
+    /** Execution metadata (tool name, timing, and the error code when isError). */
+    metadata: {
+        toolName: string;
+        executedAt: number;
+        durationMs: number;
+        /** Present only when isError is true */
+        errorCode?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Context handed to a tool's `run` function.
+ *
+ * agentId, channelId and requestId are always present — `defineTool` rejects the
+ * call before `run` is reached if any is missing, so `run` never has to check.
+ */
+export interface ToolRunContext {
+    /** Agent that invoked the tool. Always present. */
+    agentId: string;
+    /** Channel the invocation belongs to. Always present. */
+    channelId: string;
+    /** Correlation id for events and logs. Always present. */
+    requestId: string;
+    /** Any extra context the caller attached. */
+    data?: Record<string, unknown>;
+}
+/**
+ * Options accepted by {@link defineTool}.
+ */
+export interface DefineToolOptions<TInput, TOutput> {
+    /** Tool name exposed to the model. Must be unique across the whole tool set. */
+    name: string;
+    /**
+     * What the tool does, written for the model that decides whether to call it.
+     * This is prompt text: state the behavior plainly, and describe only what the
+     * implementation actually does.
+     */
+    description: string;
+    /** Category used for grouping and filtering. */
+    category: string;
+    /** JSON Schema for the tool's input. Enforced on every entry path. */
+    inputSchema: Record<string, any>;
+    /**
+     * The tool's behavior. Return the payload to send back; throw a ToolError to
+     * fail. Do not catch-and-wrap — the factory owns error handling.
+     */
+    run: (input: TInput, context: ToolRunContext) => Promise<TOutput> | TOutput;
+    /** Optional worked examples surfaced in tool documentation. */
+    examples?: McpToolExample[];
+    /** Where the tool may execute. Defaults to 'server'. */
+    executionSide?: 'server' | 'client' | 'either';
+    /** Whether the tool is enabled. Defaults to true. */
+    enabled?: boolean;
+    /** Extra metadata merged into the registered tool definition. */
+    metadata?: Record<string, any>;
+}
+/**
+ * A tool produced by {@link defineTool}.
+ *
+ * Structurally a McpToolDefinition, so it registers exactly like a hand-written
+ * tool, plus the `category` it was declared with.
+ */
+export interface DefinedMcpTool extends McpToolDefinition {
+    category: string;
+}
+/**
+ * Declare an MCP tool.
+ *
+ * @example
+ * export const gitStatusTool = defineTool({
+ *     name: 'git_status',
+ *     category: TOOL_CATEGORIES.VERSION_CONTROL,
+ *     description: 'Report staged, modified and untracked files by running `git status`.',
+ *     inputSchema: {
+ *         type: 'object',
+ *         properties: { workingDirectory: { type: 'string' } }
+ *     },
+ *     run: async (input, context) => {
+ *         const result = await runGit(['status'], input.workingDirectory);
+ *         if (result.exitCode !== 0) {
+ *             throw ToolError.executionFailed(`git status failed: ${result.stderr}`);
+ *         }
+ *         return { files: parse(result.stdout) };
+ *     }
+ * });
+ */
+export declare function defineTool<TInput = Record<string, any>, TOutput = unknown>(options: DefineToolOptions<TInput, TOutput>): DefinedMcpTool;
+/**
+ * Type guard: did this tool call fail?
+ *
+ * Use this instead of inspecting the payload. Results produced by `defineTool`
+ * always carry an explicit `isError`.
+ */
+export declare function isToolError(result: unknown): result is ToolResultEnvelope & {
+    isError: true;
+};
+//# sourceMappingURL=defineTool.d.ts.map

package/dist/protocols/mcp/defineTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineTool.d.ts","sourceRoot":"","sources":["../../../src/protocols/mcp/defineTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA+BH,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAa,aAAa,EAAe,MAAM,gBAAgB,CAAC;AAoCvE;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAAC,KAAK,GAAG,OAAO,CAAE,SAAQ,oBAAoB;IAC7E,yFAAyF;IACzF,OAAO,EAAE,oBAAoB,GAAG;QAAE,IAAI,EAAE,KAAK,GAAG,aAAa,CAAA;KAAE,CAAC;IAChE,kFAAkF;IAClF,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,QAAQ,EAAE;QACN,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,wCAAwC;QACxC,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KAC1B,CAAC;CACL;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC3B,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAAC,MAAM,EAAE,OAAO;IAC9C,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC;;;OAGG;IACH,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC5E,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;IAC5B,wDAAwD;IACxD,aAAa,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAC/C,qDAAqD;IACrD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,iBAAiB;IACrD,QAAQ,EAAE,MAAM,CAAC;CACpB;AAqBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,EACtE,OAAO,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5C,cAAc,CAyJhB;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,kBAAkB,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,CAO7F"}