@kadi.build/core 0.0.1-alpha.1 → 0.0.1-alpha.11

package/dist/types/protocol.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Protocol Types Module
+ * ======================
+ *
+ * Re-exports protocol-related types for kadi-broker and other consumers.
+ * This provides a clean import path: @kadi.build/core/types/protocol
+ *
+ * @module types/protocol
+ */
+import type { NetworkId, ToolTag, KadiTool } from '../schemas/kadi-extensions.js';
+import type { AgentRole } from './config.js';
+export type { JsonRpcRequest, JsonRpcResponse, JsonRpcNotification, JsonRpcError, PendingRequest } from './broker.js';
+export type { NetworkId, ToolTag };
+export interface Provider {
+    agentId: string;
+    agentName?: string;
+    networks: NetworkId[];
+    tags?: ToolTag[];
+    displayName?: string;
+    lastSeen?: number;
+    registeredAt?: number;
+}
+export interface SystemSnapshot {
+    agents: Array<{
+        id: string;
+        name: string;
+        type: 'agent';
+        tools: string[];
+        networks: string[];
+        status: 'active' | 'disconnected';
+    }>;
+    networks: Array<{
+        id: string;
+        name: string;
+        type: 'network';
+        status: 'active';
+    }>;
+    connections: Array<{
+        from: string;
+        to: string;
+        status: 'connected' | 'disconnected';
+    }>;
+    timestamp: string;
+}
+export type { KadiTool as Tool };
+export type { AgentRole as SessionRole };
+export type QueueKind = 'direct' | 'fanout' | 'topic' | 'agent';
+//# sourceMappingURL=protocol.d.ts.map

package/dist/types/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/types/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAClF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,YAAY,EACV,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACf,MAAM,aAAa,CAAC;AAGrB,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AAGnC,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,SAAS,EAAE,CAAC;IACtB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAGD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,KAAK,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,OAAO,CAAC;QACd,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,MAAM,EAAE,QAAQ,GAAG,cAAc,CAAC;KACnC,CAAC,CAAC;IACH,QAAQ,EAAE,KAAK,CAAC;QACd,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,SAAS,CAAC;QAChB,MAAM,EAAE,QAAQ,CAAC;KAClB,CAAC,CAAC;IACH,WAAW,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,WAAW,GAAG,cAAc,CAAC;KACtC,CAAC,CAAC;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAGD,YAAY,EAAE,QAAQ,IAAI,IAAI,EAAE,CAAC;AAGjC,YAAY,EAAE,SAAS,IAAI,WAAW,EAAE,CAAC;AAGzC,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC"}

package/dist/types/protocol.js

@@ -0,0 +1,11 @@
+/**
+ * Protocol Types Module
+ * ======================
+ *
+ * Re-exports protocol-related types for kadi-broker and other consumers.
+ * This provides a clean import path: @kadi.build/core/types/protocol
+ *
+ * @module types/protocol
+ */
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/types/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/types/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/types/tools.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Tool Types (MCP-Based)
+ * ========================
+ *
+ * Type definitions for tool registration, handlers, and schemas using the
+ * Model Context Protocol (MCP) standard.
+ *
+ * **Breaking Change (v2.0.0)**:
+ * - Replaced Zod schemas with MCP JSON Schemas
+ * - Full MCP compliance with KADI extensions
+ * - See migration guide for upgrading from v1.x
+ *
+ * @module types/tools
+ */
+export type { KadiTool, KadiToolResult, ToolDefinition, ToolHandler, RegisteredTool, ToolTag, NetworkId, ToolDiscoveryQuery, ToolDiscoveryResult } from '../schemas/index.js';
+export type { McpTool, McpCallToolResult, ToolAnnotations, ListToolsRequest, ListToolsResult, CallToolRequest, ToolListChangedNotification } from '../schemas/index.js';
+/**
+ * Tool invocation result
+ *
+ * Extended version of MCP CallToolResult with KADI-specific metadata.
+ *
+ * @template T - Result data type
+ */
+export interface ToolInvocationResult<T = unknown> {
+    /**
+     * Whether the invocation succeeded
+     */
+    success: boolean;
+    /**
+     * The result data if successful
+     */
+    data?: T;
+    /**
+     * Error information if failed
+     */
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    /**
+     * Execution metadata
+     */
+    metadata?: {
+        /**
+         * Execution time in milliseconds
+         */
+        executionTime?: number;
+        /**
+         * Timestamp when execution started
+         */
+        timestamp?: number;
+        /**
+         * Agent that executed the tool
+         */
+        agentId?: string;
+        /**
+         * Network the tool was executed on
+         */
+        networkId?: string;
+        /**
+         * Whether result was cached
+         */
+        cacheHit?: boolean;
+    };
+}
+//# sourceMappingURL=tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/types/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,YAAY,EACV,QAAQ,EACR,cAAc,EACd,cAAc,EACd,WAAW,EACX,cAAc,EACd,OAAO,EACP,SAAS,EACT,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,qBAAqB,CAAC;AAG7B,YAAY,EACV,OAAO,EACP,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,2BAA2B,EAC5B,MAAM,qBAAqB,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,OAAO;IAC/C;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,IAAI,CAAC,EAAE,CAAC,CAAC;IAET;;OAEG;IACH,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IAEF;;OAEG;IACH,QAAQ,CAAC,EAAE;QACT;;WAEG;QACH,aAAa,CAAC,EAAE,MAAM,CAAC;QAEvB;;WAEG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;QAEnB;;WAEG;QACH,OAAO,CAAC,EAAE,MAAM,CAAC;QAEjB;;WAEG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;QAEnB;;WAEG;QACH,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;CACH"}

package/dist/types/tools.js

@@ -0,0 +1,16 @@
+/**
+ * Tool Types (MCP-Based)
+ * ========================
+ *
+ * Type definitions for tool registration, handlers, and schemas using the
+ * Model Context Protocol (MCP) standard.
+ *
+ * **Breaking Change (v2.0.0)**:
+ * - Replaced Zod schemas with MCP JSON Schemas
+ * - Full MCP compliance with KADI extensions
+ * - See migration guide for upgrading from v1.x
+ *
+ * @module types/tools
+ */
+export {};
+//# sourceMappingURL=tools.js.map

package/dist/types/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/types/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/types/transport.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Transport Types
+ *
+ * Type definitions for ability transports.
+ * Transports enable loading and communicating with abilities across different protocols.
+ */
+import type { EventEmitter } from 'events';
+/**
+ * Ability Transport Interface
+ *
+ * All transports (Native, Stdio, Broker) must implement this interface.
+ * This provides a uniform way to load and communicate with abilities
+ * regardless of their deployment location or protocol.
+ *
+ * @example
+ * ```typescript
+ * class MyTransport implements AbilityTransport {
+ *   async connect() { / * ... * / }
+ *   async invoke(method, params) { / * ... * / }
+ *   getMethods() { / * ... * / }
+ *   async disconnect() { / * ... * / }
+ * }
+ * ```
+ */
+export interface AbilityTransport extends EventEmitter {
+    /**
+     * Establish connection to the ability
+     *
+     * - Native: Load the module from disk
+     * - Stdio: Spawn the child process
+     * - Broker: Connect to WebSocket and authenticate
+     *
+     * @throws {Error} If connection fails
+     */
+    connect(): Promise<void>;
+    /**
+     * Invoke a method on the connected ability
+     *
+     * @template TInput - Input parameter type
+     * @template TOutput - Return value type
+     *
+     * @param method - Method name to invoke
+     * @param params - Parameters to pass
+     * @returns Promise resolving to the method result
+     *
+     * @throws {Error} If method doesn't exist or invocation fails
+     */
+    invoke<TInput = unknown, TOutput = unknown>(method: string, params: TInput): Promise<TOutput>;
+    /**
+     * Get list of available methods on this ability
+     *
+     * @returns Array of method names
+     */
+    getMethods(): string[];
+    /**
+     * Disconnect and cleanup resources
+     *
+     * - Native: Cleanup module references
+     * - Stdio: Terminate child process
+     * - Broker: Close WebSocket connection
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Get schema for a specific method (optional)
+     *
+     * @param method - Method name
+     * @returns Method schema if available
+     */
+    getMethodSchema?(method: string): MethodSchema | undefined;
+    /**
+     * Publish an event from the ability (optional)
+     *
+     * @param eventName - Event name
+     * @param data - Event data
+     */
+    publishEvent?(eventName: string, data: unknown): void;
+}
+/**
+ * Method schema definition
+ */
+export interface MethodSchema {
+    /**
+     * Description of what the method does
+     */
+    description?: string;
+    /**
+     * Input schema (JSON Schema)
+     */
+    inputSchema?: Record<string, unknown>;
+    /**
+     * Output schema (JSON Schema)
+     */
+    outputSchema?: Record<string, unknown>;
+    /**
+     * Example usage
+     */
+    examples?: Array<{
+        input: unknown;
+        output: unknown;
+    }>;
+}
+/**
+ * Base transport configuration options
+ */
+export interface TransportOptions {
+    /**
+     * Ability name
+     */
+    abilityName: string;
+    /**
+     * Ability version (optional)
+     */
+    abilityVersion?: string;
+    /**
+     * Timeout for method invocations in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+}
+/**
+ * Native transport options (in-process loading)
+ */
+export interface NativeTransportOptions extends TransportOptions {
+    /**
+     * Path to ability directory
+     */
+    abilityPath: string;
+    /**
+     * Entry point file (relative to abilityPath)
+     * @default 'index.js'
+     */
+    entryPoint?: string;
+}
+/**
+ * Stdio transport options (child process)
+ */
+export interface StdioTransportOptions extends TransportOptions {
+    /**
+     * Path to ability directory
+     */
+    abilityPath: string;
+    /**
+     * Command to execute
+     * @default 'node'
+     */
+    command?: string;
+    /**
+     * Command arguments
+     * @default ['index.js']
+     */
+    args?: string[];
+    /**
+     * Environment variables to pass
+     */
+    env?: Record<string, string>;
+    /**
+     * Working directory
+     */
+    cwd?: string;
+}
+/**
+ * Broker transport options (remote ability)
+ */
+export interface BrokerTransportOptions extends TransportOptions {
+    /**
+     * Broker URL
+     */
+    brokerUrl: string;
+    /**
+     * Broker name identifier
+     */
+    brokerName?: string;
+    /**
+     * Networks to search for the ability
+     */
+    networks?: string[];
+    /**
+     * Authentication token
+     */
+    authToken?: string;
+}
+/**
+ * Message transport interface (low-level)
+ *
+ * This is for the underlying message-passing layer (WebSocket, stdio streams, etc.)
+ * Distinct from AbilityTransport which is higher-level.
+ */
+export interface MessageTransport extends EventEmitter {
+    /**
+     * Connect to the message transport
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the message transport
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Send raw data
+     */
+    send(data: Buffer | string): Promise<void>;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+}
+/**
+ * Transport discovery result
+ */
+export interface TransportDiscoveryResult {
+    /**
+     * Available methods
+     */
+    methods: string[];
+    /**
+     * Method schemas
+     */
+    schemas?: Map<string, MethodSchema>;
+    /**
+     * Ability metadata
+     */
+    metadata?: {
+        name: string;
+        version?: string;
+        description?: string;
+    };
+}
+/**
+ * Stdio message framing
+ */
+export interface StdioFrame {
+    /**
+     * Message length
+     */
+    length: number;
+    /**
+     * Message content (JSON)
+     */
+    content: unknown;
+}
+/**
+ * Stdio protocol message types
+ */
+export declare enum StdioMessageType {
+    DISCOVER = "__kadi_discover",
+    INVOKE = "__kadi_invoke",
+    RESULT = "__kadi_result",
+    ERROR = "__kadi_error",
+    EVENT = "__kadi_event"
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/types/transport.d.ts.map

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

package/dist/types/transport.js

@@ -0,0 +1,18 @@
+/**
+ * Transport Types
+ *
+ * Type definitions for ability transports.
+ * Transports enable loading and communicating with abilities across different protocols.
+ */
+/**
+ * Stdio protocol message types
+ */
+export var StdioMessageType;
+(function (StdioMessageType) {
+    StdioMessageType["DISCOVER"] = "__kadi_discover";
+    StdioMessageType["INVOKE"] = "__kadi_invoke";
+    StdioMessageType["RESULT"] = "__kadi_result";
+    StdioMessageType["ERROR"] = "__kadi_error";
+    StdioMessageType["EVENT"] = "__kadi_event";
+})(StdioMessageType || (StdioMessageType = {}));
+//# sourceMappingURL=transport.js.map

package/dist/types/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/types/transport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgRH;;GAEG;AACH,MAAM,CAAN,IAAY,gBAMX;AAND,WAAY,gBAAgB;IAC1B,gDAA4B,CAAA;IAC5B,4CAAwB,CAAA;IACxB,4CAAwB,CAAA;IACxB,0CAAsB,CAAA;IACtB,0CAAsB,CAAA;AACxB,CAAC,EANW,gBAAgB,KAAhB,gBAAgB,QAM3B"}

package/dist/types/zod-tools.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Type definitions for Zod-based tool registration
+ *
+ * This module provides TypeScript types for registering tools using Zod schemas
+ * instead of manual JSON Schema definitions. This approach provides:
+ * - Single source of truth (Zod schema)
+ * - Automatic TypeScript type inference
+ * - Runtime validation with excellent error messages
+ * - Significantly less boilerplate code
+ *
+ * @module types/zod-tools
+ */
+import type { z } from 'zod';
+import type { KadiTool, ToolHandler } from './tools.js';
+/**
+ * Tool configuration using Zod schemas
+ *
+ * This interface allows developers to define tools using Zod schemas
+ * for input and output validation. The schemas are automatically converted
+ * to MCP-compliant JSON Schema at registration time.
+ *
+ * @typeParam TInput - Zod schema type for tool input
+ * @typeParam TOutput - Zod schema type for tool output
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const config: ZodToolConfig = {
+ *   name: 'add',
+ *   description: 'Add two numbers',
+ *   version: '1.0.0',
+ *   input: z.object({
+ *     a: z.number().describe('First number'),
+ *     b: z.number().describe('Second number')
+ *   }),
+ *   output: z.object({
+ *     result: z.number().describe('Sum of a and b')
+ *   }),
+ *   handler: async ({ a, b }) => ({ result: a + b })
+ * };
+ * ```
+ */
+export interface ZodToolConfig<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny> {
+    /**
+     * Tool name
+     *
+     * Must be unique within the client. Used for tool discovery and invocation.
+     * Recommended format: lowercase, hyphen-separated (e.g., 'deploy-to-akash')
+     */
+    name: string;
+    /**
+     * Human-readable description
+     *
+     * Displayed in tool lists and helps LLMs understand when to use this tool.
+     * Should be clear and concise (1-2 sentences).
+     */
+    description?: string;
+    /**
+     * Display title for the tool
+     *
+     * Optional short title shown in UIs. If not provided, uses `name`.
+     */
+    title?: string;
+    /**
+     * Semantic version
+     *
+     * Format: MAJOR.MINOR.PATCH (e.g., "1.0.0", "2.3.1")
+     * Follows semver specification: https://semver.org/
+     */
+    version?: string;
+    /**
+     * Routing tags
+     *
+     * Tags provide hints for intelligent tool selection and routing.
+     * Examples:
+     * - Performance: 'cpu-intensive', 'memory-heavy', 'gpu-required'
+     * - Execution: 'batch', 'real-time', 'async'
+     * - Domain: 'math', 'crypto', 'file-ops', 'network'
+     */
+    tags?: string[];
+    /**
+     * Network availability
+     *
+     * Networks this tool is available on. Tools can be scoped to specific
+     * networks for isolation and organization.
+     * If not specified, defaults to ['global'].
+     */
+    networks?: string[];
+    /**
+     * Input schema (Zod)
+     *
+     * Zod schema defining the structure and validation rules for tool input.
+     * Will be automatically converted to MCP-compliant JSON Schema.
+     *
+     * @example
+     * ```typescript
+     * input: z.object({
+     *   name: z.string().min(1).describe('User name'),
+     *   age: z.number().int().positive().optional()
+     * })
+     * ```
+     */
+    input: TInput;
+    /**
+     * Output schema (Zod)
+     *
+     * Zod schema defining the structure and validation rules for tool output.
+     * Will be automatically converted to MCP-compliant JSON Schema.
+     * Output validation is optional but recommended for debugging.
+     *
+     * @example
+     * ```typescript
+     * output: z.object({
+     *   success: z.boolean(),
+     *   message: z.string()
+     * })
+     * ```
+     */
+    output: TOutput;
+    /**
+     * Tool handler function
+     *
+     * Implements the tool's logic. Receives validated input (typed automatically
+     * from `input` schema) and must return output matching `output` schema.
+     *
+     * Input validation happens automatically before handler is called.
+     * Output validation happens automatically after handler returns (if output schema provided).
+     *
+     * @param params - Validated input matching `input` schema type
+     * @returns Result matching `output` schema type
+     *
+     * @example
+     * ```typescript
+     * handler: async (params) => {
+     *   // params is fully typed based on input schema!
+     *   const result = await someOperation(params.name);
+     *   return { success: true, message: result };
+     * }
+     * ```
+     */
+    handler: (params: z.infer<TInput>) => Promise<z.infer<TOutput>> | z.infer<TOutput>;
+}
+/**
+ * Result of createTool() - ready to register with KadiClient
+ *
+ * This interface represents a tool that has been created from Zod schemas
+ * and converted to the standard KadiTool format. It includes both:
+ * - The tool definition (with JSON Schema)
+ * - The wrapped handler (with auto-validation)
+ *
+ * @typeParam TInput - Inferred TypeScript type from input Zod schema
+ * @typeParam TOutput - Inferred TypeScript type from output Zod schema
+ *
+ * @example
+ * ```typescript
+ * const tool = createTool(config);
+ * client.registerTool(tool.definition, tool.handler);
+ *
+ * // Or with destructuring:
+ * const { definition, handler } = createTool(config);
+ * client.registerTool(definition, handler);
+ * ```
+ */
+export interface ZodToolResult<TInput = unknown, TOutput = unknown> {
+    /**
+     * Tool definition with JSON Schema
+     *
+     * Contains the tool metadata with input/output schemas converted to
+     * MCP-compliant JSON Schema. Ready to pass to `client.registerTool()`.
+     */
+    definition: KadiTool;
+    /**
+     * Tool handler with automatic validation
+     *
+     * Wrapper around the original handler that:
+     * 1. Validates input using Zod (throws ZodError if invalid)
+     * 2. Calls original handler
+     * 3. Validates output using Zod (throws ZodError if invalid)
+     *
+     * The handler is ready to pass to `client.registerTool()`.
+     */
+    handler: ToolHandler<TInput, TOutput>;
+    /**
+     * Original Zod input schema
+     *
+     * Preserved for reference and advanced use cases (e.g., custom validation,
+     * schema introspection, documentation generation).
+     */
+    inputSchema: z.ZodTypeAny;
+    /**
+     * Original Zod output schema
+     *
+     * Preserved for reference and advanced use cases.
+     */
+    outputSchema: z.ZodTypeAny;
+}
+//# sourceMappingURL=zod-tools.d.ts.map

package/dist/types/zod-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-tools.d.ts","sourceRoot":"","sources":["../../src/types/zod-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,aAAa,CAC5B,MAAM,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,EAC1C,OAAO,SAAS,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU;IAE3C;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;;;;;;;;;;;;OAaG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;;;;;;;;OAcG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,EAAE,CACP,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,KACpB,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;CACnD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,aAAa,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAChE;;;;;OAKG;IACH,UAAU,EAAE,QAAQ,CAAC;IAErB;;;;;;;;;OASG;IACH,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEtC;;;;;OAKG;IACH,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC;IAE1B;;;;OAIG;IACH,YAAY,EAAE,CAAC,CAAC,UAAU,CAAC;CAC5B"}

package/dist/types/zod-tools.js

@@ -0,0 +1,14 @@
+/**
+ * Type definitions for Zod-based tool registration
+ *
+ * This module provides TypeScript types for registering tools using Zod schemas
+ * instead of manual JSON Schema definitions. This approach provides:
+ * - Single source of truth (Zod schema)
+ * - Automatic TypeScript type inference
+ * - Runtime validation with excellent error messages
+ * - Significantly less boilerplate code
+ *
+ * @module types/zod-tools
+ */
+export {};
+//# sourceMappingURL=zod-tools.js.map

package/dist/types/zod-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-tools.js","sourceRoot":"","sources":["../../src/types/zod-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}