@makaio/framework 1.0.0-dev-1779046984397

package/dist/tools/index.d.mts

@@ -0,0 +1,825 @@
+import { z } from "zod";
+import { MakaioContext } from "@makaio/framework/core";
+import { IMakaioBus } from "@makaio/framework/bus";
+import { ToolAnnotations, ToolAnnotations as ToolAnnotations$1 } from "@makaio/framework/contracts";
+import * as zCore from "zod/v4/core";
+
+//#region packages/tools-core/src/types.d.ts
+/**
+ * Type alias for the bus interface used in tool execution contexts.
+ *
+ * Tools receive IMakaioBus instances for type-safe event communication.
+ * This ensures full type safety with typed subjects from `@makaio/contracts`.
+ */
+type BusLike = IMakaioBus;
+/**
+ * Extended execution context for tools that need session and bus access.
+ *
+ * Extends MakaioContext with optional sessionId and bus properties for tools
+ * that need to:
+ * - Correlate operations with a specific session (sessionId)
+ * - Emit events or make requests during execution (bus)
+ * @example
+ * ```typescript
+ * const result = await tool.execute(input, {
+ *   cwd: '/workspace',
+ *   env: { NODE_ENV: 'development' },
+ *   platform: 'posix',
+ *   sessionId: 'session-123',
+ *   bus: makaioBus,
+ * });
+ * ```
+ */
+interface ToolExecutionContext extends MakaioContext {
+  /**
+   * Session identifier for multi-session task correlation.
+   * Tools can use this to associate work with a specific session.
+   */
+  sessionId?: string;
+  /**
+   * Agent identifier for attribution (optional).
+   * Provided when tool execution is tied to a specific agent.
+   */
+  agentId?: string;
+  /**
+   * Adapter identifier for adapter-scoped runtime behavior.
+   * Provided when the caller knows the concrete runtime adapter instance.
+   */
+  adapterId?: string;
+  /**
+   * Adapter name for adapter-scoped runtime behavior.
+   * Preferred when the caller wants stable logical adapter identity.
+   */
+  adapterName?: string;
+  /**
+   * Turn identifier for attribution (optional).
+   * Provided when tool execution occurs within a specific turn.
+   */
+  turnId?: string;
+  /**
+   * Turn-scoped context contributed by PreUserMessage hooks.
+   * Toolsets can use this for session-bound execution metadata.
+   */
+  turnContext?: Record<string, unknown>;
+  /**
+   * Tool call ID for the current invocation.
+   * Provided when the tool is executed as part of a structured tool call
+   * (e.g., from an LLM response). Allows tools to correlate their execution
+   * with the originating tool call in the adapter.
+   */
+  toolCallId?: string;
+  /**
+   * Bus instance for event communication.
+   * Tools can use this to emit events (e.g., task.created, task.updated).
+   */
+  bus?: BusLike;
+}
+/**
+ * Tool metadata containing descriptive information.
+ */
+interface ToolMetadata {
+  /** Unique tool name (identifier) */
+  name: string;
+  /** Human-readable description */
+  description: string;
+  /** Optional behavior annotations */
+  annotations?: ToolAnnotations$1;
+}
+/**
+ * Structured error returned from failed tool executions.
+ */
+interface ToolError {
+  /** Error code for programmatic handling */
+  code: string;
+  /** Human-readable error message */
+  message: string;
+  /** Optional additional error context */
+  details?: unknown;
+}
+/**
+ * Successful tool execution result.
+ * @typeParam T - Type of the success data
+ */
+type ToolSuccess<T> = {
+  success: true;
+  data: T;
+};
+/**
+ * Failed tool execution result.
+ * Used for functions that always return an error (like toolError, errorToToolResult).
+ */
+type ToolFailure = {
+  success: false;
+  error: ToolError;
+};
+/**
+ * Discriminated union result type for tool executions.
+ * Always returns either success with data or failure with error.
+ * @typeParam T - Type of the success data
+ * @example
+ * ```typescript
+ * const result: ToolResult<string> = await tool.execute(input, context);
+ * if (result.success) {
+ *   console.debug(result.data); // string
+ * } else {
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
+type ToolResult<T> = ToolSuccess<T> | ToolFailure;
+/**
+ * Base tool definition interface with erased type parameters.
+ *
+ * Use this type for collections (arrays, records) where specific input/output
+ * types are not needed. For type-safe individual tools, use ToolDefinition.
+ */
+interface AnyToolDefinition {
+  /** Tool metadata (name, description, annotations) */
+  metadata: ToolMetadata;
+  /** Zod schema for input validation */
+  inputSchema: z.ZodTypeAny;
+  /** Zod schema for output validation */
+  outputSchema: z.ZodTypeAny;
+  /**
+   * Execute the tool with validated input.
+   * Method syntax enables bivariant checking, allowing ToolDefinition<T>
+   * to be assignable to AnyToolDefinition for use in collections.
+   * @param input - Validated input matching inputSchema
+   * @param context - Execution context with cwd, env, platform, sessionId, adapter identity, bus, etc.
+   * @returns Promise resolving to success with data or failure with error
+   */
+  execute(input: unknown, context: ToolExecutionContext): Promise<ToolResult<unknown>>;
+}
+/**
+ * Core tool definition interface.
+ *
+ * A tool is a pure function with validated input/output schemas.
+ * Tools receive a MakaioContext for execution environment information.
+ *
+ * For collections of tools (toolsets, arrays), use AnyToolDefinition which
+ * erases the type parameters to avoid TypeScript variance issues.
+ * @typeParam TInput - Zod schema for input validation
+ * @typeParam TOutput - Zod schema for output validation
+ * @example
+ * ```typescript
+ * const readFileTool: ToolDefinition<typeof ReadFileInputSchema, typeof ReadFileOutputSchema> = {
+ *   metadata: {
+ *     name: 'readFile',
+ *     description: 'Reads a file from the filesystem',
+ *     annotations: { readOnly: true },
+ *   },
+ *   inputSchema: ReadFileInputSchema,
+ *   outputSchema: ReadFileOutputSchema,
+ *   execute: async (input, context) => {
+ *     // Implementation...
+ *     return { success: true, data: content };
+ *   },
+ * };
+ * ```
+ */
+interface ToolDefinition<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny> {
+  /** Tool metadata (name, description, annotations) */
+  metadata: ToolMetadata;
+  /** Zod schema for input validation */
+  inputSchema: TInput;
+  /** Zod schema for output validation */
+  outputSchema: TOutput;
+  /**
+   * Execute the tool with validated input.
+   * Method syntax enables bivariant checking, allowing ToolDefinition<T>
+   * to be assignable to AnyToolDefinition for use in collections.
+   * @param input - Validated input matching inputSchema
+   * @param context - Execution context with cwd, env, platform, sessionId, adapter identity, bus, etc.
+   * @returns Promise resolving to success with data or failure with error
+   */
+  execute(input: z.infer<TInput>, context: ToolExecutionContext): Promise<ToolResult<z.infer<TOutput>>>;
+}
+/**
+ * Toolset metadata for grouping related tools.
+ */
+interface ToolsetMetadata {
+  /** Unique toolset name */
+  name: string;
+  /** Human-readable description */
+  description: string;
+  /** Semantic version string */
+  version: string;
+}
+/**
+ * A collection of related tools with shared metadata.
+ *
+ * Toolsets provide logical grouping and versioning for tools.
+ * Uses AnyToolDefinition to avoid TypeScript variance issues with
+ * heterogeneous tool collections.
+ * @typeParam TTools - Record type mapping tool names to definitions
+ * @example
+ * ```typescript
+ * const filesystemToolset: Toolset = {
+ *   metadata: {
+ *     name: 'filesystem',
+ *     description: 'File system operations',
+ *     version: '1.0.0',
+ *   },
+ *   tools: {
+ *     readFile: readFileTool,
+ *     writeFile: writeFileTool,
+ *   },
+ * };
+ * ```
+ */
+interface Toolset<TTools extends Record<string, AnyToolDefinition> = Record<string, AnyToolDefinition>> {
+  /** Toolset metadata */
+  metadata: ToolsetMetadata;
+  /** Map of tool names to definitions */
+  tools: TTools;
+  /** Optional Zod schema for toolset configuration (used for UI generation) */
+  configSchema?: z.ZodTypeAny;
+}
+/**
+ * Info structure returned from registry list operations.
+ * Includes inputSchema as JSON Schema for format conversion (e.g., OpenAI).
+ */
+interface ToolInfo {
+  /** Tool name */
+  name: string;
+  /** Tool description */
+  description: string;
+  /** Toolset this tool belongs to */
+  toolsetName: string;
+  /** Optional behavior annotations */
+  annotations?: ToolAnnotations$1;
+  /** JSON Schema for input parameters (for format conversion) */
+  inputSchema?: Record<string, unknown>;
+}
+//#endregion
+//#region packages/tools-core/src/errors.d.ts
+/**
+ * Standard error codes for tool execution failures.
+ * Use these codes for consistent error handling across tools.
+ */
+declare const ToolErrorCodes: {
+  /** Tool not found in registry */readonly TOOL_NOT_FOUND: "TOOL_NOT_FOUND"; /** Input validation failed against schema */
+  readonly VALIDATION_FAILED: "VALIDATION_FAILED"; /** Tool execution not permitted */
+  readonly PERMISSION_DENIED: "PERMISSION_DENIED"; /** Tool execution timed out */
+  readonly TIMEOUT: "TIMEOUT"; /** Tool was aborted via signal */
+  readonly ABORTED: "ABORTED"; /** Generic execution error */
+  readonly EXECUTION_ERROR: "EXECUTION_ERROR"; /** Tool returned invalid output */
+  readonly INVALID_OUTPUT: "INVALID_OUTPUT"; /** Required resource not found */
+  readonly RESOURCE_NOT_FOUND: "RESOURCE_NOT_FOUND"; /** Resource limit exceeded (e.g., max concurrent shells) */
+  readonly RESOURCE_EXHAUSTED: "RESOURCE_EXHAUSTED"; /** Internal tool error */
+  readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+type ToolErrorCode = (typeof ToolErrorCodes)[keyof typeof ToolErrorCodes];
+/**
+ * Error class for tool execution failures.
+ * Provides structured error information and conversion to ToolError format.
+ * @example
+ * ```typescript
+ * throw new ToolExecutionError(
+ *   ToolErrorCodes.VALIDATION_FAILED,
+ *   'Input path must be absolute',
+ *   { path: input.path }
+ * );
+ * ```
+ */
+declare class ToolExecutionError extends Error {
+  readonly code: string;
+  readonly details?: unknown | undefined;
+  /**
+   * Creates a new ToolExecutionError.
+   * @param code - Error code from ToolErrorCodes
+   * @param message - Human-readable error message
+   * @param details - Optional additional error context
+   */
+  constructor(code: string, message: string, details?: unknown | undefined);
+  /**
+   * Converts the error to a ToolError object for result formatting.
+   * @returns ToolError suitable for ToolResult
+   */
+  toToolError(): ToolError;
+}
+/**
+ * Creates a failed ToolResult from error parameters.
+ * @param code - Error code
+ * @param message - Error message
+ * @param details - Optional error details
+ * @returns Failed ToolResult with error information
+ * @example
+ * ```typescript
+ * if (!fileExists) {
+ *   return toolError(
+ *     ToolErrorCodes.RESOURCE_NOT_FOUND,
+ *     `File not found: ${path}`
+ *   );
+ * }
+ * ```
+ */
+declare function toolError(code: string, message: string, details?: unknown): ToolFailure;
+/**
+ * Creates a successful ToolResult with data.
+ * @typeParam T - Type of the success data
+ * @param data - Success data to wrap
+ * @returns Successful ToolResult with data
+ * @example
+ * ```typescript
+ * const content = await fs.readFile(path, 'utf-8');
+ * return toolSuccess({ content });
+ * ```
+ */
+declare function toolSuccess<T>(data: T): ToolSuccess<T>;
+/**
+ * Converts an unknown error to a ToolResult.
+ * Preserves ToolExecutionError details or wraps other errors.
+ * @param error - Error to convert
+ * @param defaultCode - Error code to use for non-ToolExecutionError
+ * @returns Failed ToolResult with error information
+ */
+declare function errorToToolResult(error: unknown, defaultCode?: string): ToolFailure;
+//#endregion
+//#region packages/tools-core/src/define-tool.d.ts
+/**
+ * Configuration object for defining a tool.
+ * Provides ergonomic API for creating ToolDefinition instances.
+ * @typeParam TInput - Zod schema type for input validation
+ * @typeParam TOutput - Zod schema type for output validation
+ */
+interface DefineToolConfig<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny> {
+  /** Unique tool name (identifier) */
+  name: string;
+  /** Human-readable description of what the tool does */
+  description: string;
+  /** Optional behavior annotations for consumers */
+  annotations?: ToolAnnotations$1;
+  /** Zod schema for input validation */
+  inputSchema: TInput;
+  /** Zod schema for output validation */
+  outputSchema: TOutput;
+  /**
+   * Tool execution function.
+   * @param input - Validated input matching inputSchema
+   * @param context - Execution context with cwd, env, platform, sessionId, bus, etc.
+   * @returns Promise resolving to success with data or failure with error
+   */
+  execute: (input: z.infer<TInput>, context: ToolExecutionContext) => Promise<ToolResult<z.infer<TOutput>>>;
+}
+/**
+ * Creates a ToolDefinition from a configuration object.
+ *
+ * Provides a clean builder API for defining tools with full type inference.
+ * The returned ToolDefinition can be used directly or registered with a toolset.
+ * @typeParam TInput - Zod schema type for input validation
+ * @typeParam TOutput - Zod schema type for output validation
+ * @param config - Tool configuration
+ * @returns Fully typed ToolDefinition
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { defineTool, toolSuccess, toolError, ToolErrorCodes } from '@makaio/framework/tools';
+ *
+ * const ReadFileInputSchema = z.object({
+ *   path: z.string().describe('File path to read'),
+ *   encoding: z.enum(['utf-8', 'base64']).default('utf-8'),
+ * });
+ *
+ * const ReadFileOutputSchema = z.object({
+ *   content: z.string(),
+ *   size: z.number(),
+ * });
+ *
+ * const readFileTool = defineTool({
+ *   name: 'readFile',
+ *   description: 'Reads a file from the filesystem',
+ *   annotations: { readOnly: true },
+ *   inputSchema: ReadFileInputSchema,
+ *   outputSchema: ReadFileOutputSchema,
+ *   execute: async (input, context) => {
+ *     const fullPath = path.resolve(context.cwd, input.path);
+ *
+ *     try {
+ *       const content = await fs.readFile(fullPath, input.encoding);
+ *       const stats = await fs.stat(fullPath);
+ *       return toolSuccess({ content, size: stats.size });
+ *     } catch (err) {
+ *       return toolError(
+ *         ToolErrorCodes.RESOURCE_NOT_FOUND,
+ *         `Failed to read file: ${fullPath}`
+ *       );
+ *     }
+ *   },
+ * });
+ * ```
+ */
+declare function defineTool<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny>(config: DefineToolConfig<TInput, TOutput>): ToolDefinition<TInput, TOutput>;
+//#endregion
+//#region packages/tools-core/src/define-toolset.d.ts
+/**
+ * Input type for tools parameter in defineToolset.
+ * Accepts a record, single tool, or array of tools for flexibility.
+ * Uses AnyToolDefinition to avoid TypeScript variance issues.
+ */
+type ToolsInput = Record<string, AnyToolDefinition> | AnyToolDefinition | AnyToolDefinition[];
+/**
+ * Configuration object for defining a toolset.
+ */
+interface DefineToolsetConfig<TTools extends ToolsInput> {
+  /** Unique toolset name */
+  name: string;
+  /** Human-readable description */
+  description: string;
+  /** Semantic version string */
+  version: string;
+  /**
+   * Tools to include in the toolset.
+   * Can be:
+   * - A record of named tools
+   * - A single tool (uses tool.metadata.name as key)
+   * - An array of tools (uses each tool.metadata.name as key)
+   */
+  tools: TTools;
+  /** Optional Zod schema for toolset configuration (used for UI generation) */
+  configSchema?: z.ZodTypeAny;
+}
+/**
+ * Extracts the Record type from various tools input formats.
+ * Used for type inference in defineToolset return type.
+ */
+type ExtractToolsRecord<T extends ToolsInput> = T extends Record<string, AnyToolDefinition> ? T : T extends AnyToolDefinition ? Record<string, AnyToolDefinition> : T extends AnyToolDefinition[] ? Record<string, AnyToolDefinition> : Record<string, AnyToolDefinition>;
+/**
+ * Creates a Toolset from a configuration object.
+ *
+ * Provides flexibility in how tools are specified:
+ * - As a record with explicit keys
+ * - As a single tool (uses tool name as key)
+ * - As an array of tools (uses each tool name as key)
+ * @typeParam TTools - Input tools type (record, single, or array)
+ * @param config - Toolset configuration
+ * @returns Toolset with normalized tools record
+ * @example
+ * ```typescript
+ * // With a record (explicit keys)
+ * const fsToolset = defineToolset({
+ *   name: 'filesystem',
+ *   description: 'File system operations',
+ *   version: '1.0.0',
+ *   tools: {
+ *     read: readFileTool,
+ *     write: writeFileTool,
+ *     delete: deleteFileTool,
+ *   },
+ * });
+ *
+ * // With a single tool
+ * const singleToolset = defineToolset({
+ *   name: 'echo',
+ *   description: 'Echo utility',
+ *   version: '1.0.0',
+ *   tools: echoTool,
+ * });
+ *
+ * // With an array
+ * const arrayToolset = defineToolset({
+ *   name: 'utilities',
+ *   description: 'Utility tools',
+ *   version: '1.0.0',
+ *   tools: [echoTool, sleepTool, dateTool],
+ * });
+ * ```
+ */
+declare function defineToolset<TTools extends ToolsInput>(config: DefineToolsetConfig<TTools>): Toolset<ExtractToolsRecord<TTools>>;
+//#endregion
+//#region packages/tools-core/src/export.d.ts
+type JSONSchema = zCore.JSONSchema.JSONSchema;
+/**
+ * MCP (Model Context Protocol) tool definition.
+ * @see https://spec.modelcontextprotocol.io/specification/server/tools/
+ */
+interface McpToolDefinition {
+  /** Tool name (unique identifier) */
+  name: string;
+  /** Human-readable description */
+  description: string;
+  /** JSON Schema for input parameters */
+  inputSchema: JSONSchema;
+  /**
+   * Optional annotations providing hints about tool behavior.
+   * MCP clients may use these to optimize tool usage.
+   */
+  annotations?: {
+    /** Tool only reads data, doesn't modify anything */readOnly?: boolean; /** Tool may permanently delete or modify data */
+    destructive?: boolean; /** Calling the tool multiple times with same input has same effect */
+    idempotent?: boolean; /** Execution may take a long time */
+    openWorldHint?: boolean;
+  };
+}
+/**
+ * OpenAI function calling definition.
+ * @see https://platform.openai.com/docs/guides/function-calling
+ */
+interface OpenAIFunctionDefinition {
+  /** Function name */
+  name: string;
+  /** Human-readable description */
+  description: string;
+  /** JSON Schema for function parameters */
+  parameters: JSONSchema;
+}
+/** Valid target formats for JSON Schema generation */
+type SchemaTarget = 'jsonSchema7' | 'jsonSchema2019-09' | 'openApi3' | 'openAi';
+/**
+ * Options for schema conversion.
+ */
+interface ExportOptions {
+  /**
+   * Target schema version.
+   * - 'jsonSchema7' (default): JSON Schema Draft-07
+   * - 'jsonSchema2019-09': JSON Schema 2019-09
+   * - 'openApi3': OpenAPI 3.0 compatible
+   * - 'openAi': OpenAI function calling compatible
+   */
+  schemaTarget?: SchemaTarget;
+  /**
+   * Whether to remove $schema property from output.
+   * Default is true for cleaner output.
+   */
+  removeSchema?: boolean;
+}
+/**
+ * Converts a ToolDefinition to MCP tool format.
+ * @param tool - Makaio tool definition
+ * @returns MCP-compatible tool definition
+ * @example
+ * ```typescript
+ * const mcpTool = toMcpTool(readFileTool);
+ * // Result:
+ * // {
+ * //   name: 'readFile',
+ * //   description: 'Reads a file from the filesystem',
+ * //   inputSchema: { type: 'object', properties: { path: { type: 'string' } }, ... },
+ * //   annotations: { readOnly: true }
+ * // }
+ * ```
+ */
+declare function toMcpTool(tool: AnyToolDefinition): McpToolDefinition;
+/**
+ * Converts a ToolDefinition to OpenAI function format.
+ * @param tool - Makaio tool definition
+ * @returns OpenAI-compatible function definition
+ * @example
+ * ```typescript
+ * const openAIFunc = toOpenAIFunction(readFileTool);
+ * // Result:
+ * // {
+ * //   name: 'readFile',
+ * //   description: 'Reads a file from the filesystem',
+ * //   parameters: { type: 'object', properties: { path: { type: 'string' } }, ... }
+ * // }
+ * ```
+ */
+declare function toOpenAIFunction(tool: AnyToolDefinition): OpenAIFunctionDefinition;
+/**
+ * Converts all tools in a Toolset to MCP format.
+ * @param toolset - Makaio toolset
+ * @returns Array of MCP-compatible tool definitions
+ * @example
+ * ```typescript
+ * const mcpTools = toolsetToMcpTools(filesystemToolset);
+ * // Returns array of MCP tool definitions for all tools in the toolset
+ * ```
+ */
+declare function toolsetToMcpTools(toolset: Toolset): McpToolDefinition[];
+/**
+ * Converts all tools in a Toolset to OpenAI function format.
+ * @param toolset - Makaio toolset
+ * @returns Array of OpenAI-compatible function definitions
+ * @example
+ * ```typescript
+ * const openAIFunctions = toolsetToOpenAIFunctions(filesystemToolset);
+ * // Returns array of OpenAI function definitions for all tools in the toolset
+ * ```
+ */
+declare function toolsetToOpenAIFunctions(toolset: Toolset): OpenAIFunctionDefinition[];
+//#endregion
+//#region packages/tools-core/src/memory-store.d.ts
+/**
+ * Generic memory store for managing working memory instances across sessions.
+ *
+ * Provides session-keyed isolation for state when tool instances are
+ * singleton in the registry.
+ *
+ * Type Parameters:
+ * - T: The working memory class type
+ * - TArgs: Constructor arguments for the working memory class
+ * @example
+ * ```typescript
+ * class MyMemoryStore extends MemoryStore<MyWorkingMemory, [string]> {
+ *   constructor() {
+ *     super((sessionId) => new MyWorkingMemory(sessionId));
+ *   }
+ * }
+ *
+ * const store = new MyMemoryStore();
+ * const memory = store.get('session-123');
+ * store.delete('session-123');
+ * ```
+ */
+declare class MemoryStore<T, TArgs extends unknown[]> {
+  private factory;
+  private sessions;
+  /**
+   * Creates a new memory store.
+   * @param factory - Factory function to create new memory instances
+   */
+  constructor(factory: (sessionId: string, ...args: TArgs) => T);
+  /**
+   * Gets or creates working memory for a session.
+   * Returns the same instance for the same sessionId.
+   * @param sessionId - Session identifier
+   * @param args - Additional arguments passed to the factory
+   * @returns Working memory instance for the session
+   */
+  get(sessionId: string, ...args: TArgs): T;
+  /**
+   * Checks if a session has working memory.
+   * @param sessionId - Session identifier
+   * @returns true if session exists
+   */
+  has(sessionId: string): boolean;
+  /**
+   * Deletes session memory (for cleanup on session close).
+   * @param sessionId - Session identifier
+   * @returns true if deleted, false if not found
+   */
+  delete(sessionId: string): boolean;
+  /**
+   * Iterates over all session memories.
+   * @returns Iterator of [sessionId, memory] pairs
+   */
+  entries(): IterableIterator<[string, T]>;
+  /**
+   * Returns all session IDs with active memory.
+   * @returns Array of session IDs
+   */
+  sessionIds(): string[];
+  /**
+   * Returns the number of sessions with active memory.
+   * @returns Session count
+   */
+  get size(): number;
+}
+//#endregion
+//#region packages/tools-core/src/tool-utils.d.ts
+/**
+ * Validates that sessionId is present in the context.
+ * @param context - Tool execution context
+ * @param entityName - Name of entity for error message (e.g., 'artifact', 'task')
+ * @returns Session ID if valid, or error result
+ */
+declare function validateSessionId(context: ToolExecutionContext, entityName?: string): {
+  valid: true;
+  sessionId: string;
+} | {
+  valid: false;
+  error: ToolResult<never>;
+};
+/**
+ * Emits an event on the bus if available.
+ *
+ * The subject must be a properly typed subject definition from a registered namespace.
+ * Type inference ensures the payload matches the subject's schema at compile time.
+ * @param context - Tool execution context
+ * @param subject - Typed subject definition from a registered namespace
+ * @param payload - Event payload matching the subject's schema
+ * @example
+ * ```typescript
+ * import { TaskSubjects } from '@makaio/tools-tasks/subjects';
+ *
+ * await emitEvent(context, TaskSubjects.created, {
+ *   taskId: '123',
+ *   title: 'Fix bug',
+ * });
+ * ```
+ */
+declare function emitEvent<S extends {
+  $meta: {
+    payload: unknown;
+  };
+}>(context: ToolExecutionContext, subject: S, payload: S['$meta']['payload']): Promise<void>;
+/**
+ * Operation handler function type for CRUD tools.
+ *
+ * Handler functions receive the operation-specific input, validated sessionId,
+ * and execution context.
+ *
+ * Type parameters:
+ * - TInput: The operation-specific input type (extracted from discriminated union)
+ * - TOutput: The tool's output type
+ */
+type OperationHandler<TInput, TOutput> = (input: TInput, sessionId: string, context: ToolExecutionContext) => Promise<ToolResult<TOutput>>;
+/**
+ * Handler map for discriminated union CRUD operations.
+ *
+ * Maps operation names (discriminator values) to their handler functions.
+ *
+ * Type parameters:
+ * - TInput: The full discriminated union input type
+ * - TOutput: The tool's output type
+ */
+type OperationHandlers<TInput extends {
+  op: string;
+}, TOutput> = { [K in TInput['op']]: OperationHandler<Extract<TInput, {
+  op: K;
+}>, TOutput> };
+/**
+ * Executes a CRUD tool operation with session validation and operation routing.
+ *
+ * This helper consolidates the common pattern of:
+ * 1. Validating sessionId from context
+ * 2. Routing to operation-specific handlers based on discriminated union
+ *
+ * The input type must be a discriminated union with an `op` field.
+ * Handler functions are provided in a map keyed by operation name.
+ *
+ * Type parameters:
+ * - TInput: Discriminated union input type with `op` field
+ * - TOutput: Tool output type
+ * @param input - The tool input with operation discriminator
+ * @param context - Tool execution context
+ * @param entityName - Entity name for validation error messages (e.g., 'task', 'artifact')
+ * @param handlers - Map of operation names to handler functions
+ * @returns Tool result from the appropriate operation handler
+ * @example
+ * ```typescript
+ * export const myTool = defineTool({
+ *   name: 'my_tool',
+ *   inputSchema: z.discriminatedUnion('op', [
+ *     z.object({ op: z.literal('create'), data: z.string() }),
+ *     z.object({ op: z.literal('list') }),
+ *   ]),
+ *   execute: async (input, context) => {
+ *     return executeCrudOperation(input, context, 'item', {
+ *       create: async (input, sessionId, context) => {
+ *         // Handle create...
+ *       },
+ *       list: async (input, sessionId, context) => {
+ *         // Handle list...
+ *       },
+ *     });
+ *   },
+ * });
+ * ```
+ */
+declare function executeCrudOperation<TInput extends {
+  op: string;
+}, TOutput>(input: TInput, context: ToolExecutionContext, entityName: string, handlers: OperationHandlers<TInput, TOutput>): Promise<ToolResult<TOutput>>;
+//#endregion
+//#region packages/tools-core/src/widen-tool.d.ts
+/**
+ * Widens a strongly-typed tool definition for use in heterogeneous collections.
+ *
+ * Tool definitions are invariant in their input/output generic parameters. This
+ * helper provides a single canonical widening point for `defineToolset({ tools: [...] })`
+ * call sites that need `AnyToolDefinition`.
+ * @param tool - Strongly-typed tool definition
+ * @returns The same tool typed as AnyToolDefinition
+ */
+declare function widenTool<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny>(tool: ToolDefinition<TInput, TOutput>): AnyToolDefinition;
+//#endregion
+//#region packages/tools-core/src/file-access.d.ts
+/**
+ * Compiled file access rules injected into tool execution context constraints.
+ */
+interface FileAccessRules {
+  /**
+   * Directory allow-list.
+   * - `undefined`: no directory restriction
+   * - `[]`: deny all filesystem paths
+   * - non-empty array: allow-list to these directories
+   */
+  readonly allowedDirectories?: readonly string[];
+  /**
+   * Sync predicate that returns true when the absolute path is denied.
+   * @param absolutePath - Normalized absolute path to test
+   */
+  readonly isDenied: (absolutePath: string) => boolean;
+}
+/**
+ * Provides filesystem access rules for a given working directory.
+ * @param cwd - Absolute working directory
+ * @param allowedDirectories - Directory allow-list from the active execution policy
+ */
+type FileAccessRuleProvider = (cwd: string, allowedDirectories?: readonly string[]) => Promise<FileAccessRules>;
+/** Constraints key for FileAccessRules in MakaioContext.constraints. */
+declare const FILE_ACCESS_RULES_KEY: "fileAccessRules";
+/**
+ * Extract the target file path from a filesystem tool call's arguments.
+ *
+ * Returns the resolved absolute path, or `null` if the tool is not a known
+ * filesystem tool or the args don't contain the expected path field.
+ * @param toolName - Name of the tool being called
+ * @param args - Tool arguments record
+ * @param cwd - Working directory to resolve relative paths against
+ * @returns Absolute path to the target file, or `null` if not applicable
+ */
+declare function extractToolFilePath(toolName: string | undefined, args: Record<string, unknown> | undefined, cwd: string): string | null;
+//#endregion
+export { type AnyToolDefinition, type BusLike, type DefineToolConfig, type DefineToolsetConfig, type ExportOptions, FILE_ACCESS_RULES_KEY, type FileAccessRuleProvider, type FileAccessRules, type McpToolDefinition, MemoryStore, type OpenAIFunctionDefinition, type ToolAnnotations, type ToolDefinition, type ToolError, type ToolErrorCode, ToolErrorCodes, type ToolExecutionContext, ToolExecutionError, type ToolFailure, type ToolInfo, type ToolMetadata, type ToolResult, type ToolSuccess, type Toolset, type ToolsetMetadata, defineTool, defineToolset, emitEvent, errorToToolResult, executeCrudOperation, extractToolFilePath, toMcpTool, toOpenAIFunction, toolError, toolSuccess, toolsetToMcpTools, toolsetToOpenAIFunctions, validateSessionId, widenTool };