@makaio/framework 1.0.0-dev-1781022866275 → 1.0.0-dev-1781023871421

package/dist/index-CLpjm52M.d.mts

@@ -0,0 +1,183 @@
+import { MakaioContext } from "@makaio/framework/core";
+import { IMakaioBus } from "@makaio/framework/bus";
+import { AnyToolDefinition, FILE_ACCESS_RULES_KEY as FILE_ACCESS_RULES_KEY$1, FileAccessRuleProvider, FileAccessRuleProvider as FileAccessRuleProvider$1, FileAccessRules, ToolExecutionContext, ToolInfo, ToolResult, Toolset, extractToolFilePath as extractToolFilePath$1 } from "@makaio/framework/tools";
+import { ContributionProcessor } from "@makaio/framework/kernel";
+
+//#region services/core/src/tools/types.d.ts
+/**
+ * Options for creating a ToolRegistry instance.
+ */
+interface ToolRegistryOptions {
+  /** Bus instance (defaults to global MakaioBus) */
+  bus?: IMakaioBus;
+  /** Priority for bus handlers (default 0) */
+  handlerPriority?: number;
+  /** Policy provider for toolset access control (SEAM) */
+  policyProvider?: ToolsetPolicyProvider;
+  /**
+   * Provider for filesystem access rules (.makaioignore + allowedDirectories).
+   * Called by execute() before dispatching to filesystem tools.
+   * SEAM: MVP reads .makaioignore files. Phase 2 composes WebUI rules.
+   */
+  fileAccessRuleProvider?: FileAccessRuleProvider;
+}
+/** Filter options for listing tools. */
+interface ListToolsFilter {
+  /** Filter by toolset name */
+  toolsetName?: string;
+  /** Adapter ID for policy-based filtering (falls back if adapterName not provided) */
+  adapterId?: string;
+  /** Adapter name for policy-based filtering (preferred over adapterId) */
+  adapterName?: string;
+}
+/** Toolset info returned from listToolsets. */
+interface ToolsetInfo {
+  name: string;
+  description: string;
+  version: string;
+  toolCount: number;
+  configSchema?: Record<string, unknown>;
+}
+/** Combined tools and toolsets listing result. */
+interface ToolsWithToolsetsResult {
+  tools: ToolInfo[];
+  toolsets: ToolsetInfo[];
+}
+/** Policy configuration for a toolset. */
+interface ToolsetPolicy {
+  /** Adapters allowed to use this toolset (empty = all allowed) */
+  allowedAdapters?: string[];
+  /** Tools disabled within this toolset */
+  disabledTools?: string[];
+}
+/**
+ * Provider function that returns policy for a given toolset.
+ * SEAM: Implement in runtime to read from settings storage.
+ */
+type ToolsetPolicyProvider = (toolsetName: string) => Promise<ToolsetPolicy | null>;
+/** Options for tool execution. */
+interface ExecuteOptions {
+  contextOverrides?: Partial<MakaioContext> & Partial<ToolExecutionContext>;
+  adapterId?: string;
+  adapterName?: string;
+}
+//#endregion
+//#region services/core/src/tools/tool-registry.d.ts
+/**
+ * Central registry for tools and toolsets.
+ * Manages registration, lookup, and execution with bus integration.
+ * Emits lifecycle events (registered, started, completed, error) for observability.
+ * Emits `registryChanged` with a monotonically increasing revision whenever the set of
+ * registered toolsets changes, allowing consumers to invalidate stale tool lists.
+ */
+declare class ToolRegistry {
+  private readonly bus;
+  private readonly toolsets;
+  private readonly tools;
+  private readonly cleanupHandlers;
+  private readonly handlerPriority;
+  private readonly policyProvider?;
+  private readonly fileAccessRuleProvider?;
+  private revision;
+  /**
+   * Creates a new ToolRegistry with optional configuration.
+   * @param options - Registry configuration options
+   */
+  constructor(options?: ToolRegistryOptions);
+  /** Registers RPC handlers for tool.list and tool.execute on the bus. */
+  private registerHandlers;
+  /**
+   * Registers a toolset. All tools are indexed by name. Emits `tool.registered` event.
+   * @param toolset - Toolset to register
+   */
+  register(toolset: Toolset): Promise<void>;
+  /**
+   * Deregisters a toolset and all its tools. Emits `tool.registryChanged` event.
+   * @param toolsetName - Name of the toolset to deregister
+   * @throws Error if the toolset is not registered
+   */
+  deregister(toolsetName: string): Promise<void>;
+  /**
+   * Emit a monotonic registryChanged event for toolset lifecycle updates.
+   * @param reason - Change reason enum.
+   * @param toolsetName - Affected toolset.
+   */
+  private emitRegistryChanged;
+  /**
+   * Executes a tool by name with the given input.
+   *
+   * Validates input against the tool's schema, enforces policy, executes the tool,
+   * and emits lifecycle events (started, completed/error). Constraints are enriched
+   * with file access rules before the tool receives its context.
+   * @param toolName - Name of the tool to execute
+   * @param input - Input data (validated against tool's inputSchema)
+   * @param options - Optional execution options (context overrides, adapter identity)
+   * @returns Tool execution result (success with data or failure with error)
+   */
+  execute(toolName: string, input: unknown, options?: ExecuteOptions): Promise<ToolResult<unknown>>;
+  /**
+   * Builds a ToolExecutionContext from execute options, enriching constraints
+   * with file access rules when a provider is configured.
+   * @param options - Execution options with optional context overrides
+   * @param effectiveAdapterIdentity - Canonical adapter identity for this execution
+   * @returns Fully populated ToolExecutionContext
+   */
+  private buildExecutionContext;
+  /**
+   * Check policy for tool execution. Returns ToolFailure if denied, null if allowed.
+   * @param toolsetName - Toolset name for policy lookup
+   * @param toolName - Tool name to check
+   * @param adapterId - Adapter ID for allowedAdapters check
+   * @param adapterName - Adapter name for allowedAdapters check
+   * @returns ToolFailure if denied, null if allowed
+   */
+  private checkPolicy;
+  /**
+   * Lists all registered tools with optional filtering.
+   * @param filter - Optional filter criteria
+   * @returns Array of tool information
+   */
+  listTools(filter?: ListToolsFilter): ToolInfo[];
+  /**
+   * Lists all registered toolsets with metadata including configSchema as JSON Schema.
+   * @returns Array of toolset information
+   */
+  listToolsets(): ToolsetInfo[];
+  /**
+   * Lists tools and toolsets with optional filtering. Applies policy filtering when adapterName is provided.
+   * @param filter - Optional filter criteria
+   * @returns Object containing tools array and toolsets array
+   */
+  listToolsWithToolsets(filter?: ListToolsFilter): Promise<ToolsWithToolsetsResult>;
+  /**
+   * Gets a tool definition by name.
+   * @param name - Tool name to look up
+   * @returns Tool definition or undefined if not found
+   */
+  getTool(name: string): AnyToolDefinition | undefined;
+  /**
+   * Gets a toolset by name.
+   * @param name - Toolset name to look up
+   * @returns Toolset or undefined if not found
+   */
+  getToolset(name: string): Toolset | undefined;
+  /** Cleans up registry resources. Unsubscribes all bus handlers. */
+  dispose(): void;
+  /**
+   * Destroy this registry — alias for {@link dispose} to satisfy the package
+   * service lifecycle contract.
+   */
+  destroy(): void;
+}
+//#endregion
+//#region services/core/src/tools/tool-contribution-processor.d.ts
+/**
+ * Create a framework-owned processor for `MakaioExtension.tools`.
+ *
+ * Toolsets are registered sequentially so failures have deterministic rollback.
+ * Missing ToolRegistry is a hard composition error.
+ * @returns Awaited contribution processor for tool contributions.
+ */
+declare function createToolContributionProcessor(): ContributionProcessor;
+//#endregion
+export { createToolContributionProcessor as a, ToolRegistryOptions as c, ToolsetPolicy as d, ToolsetPolicyProvider as f, extractToolFilePath$1 as i, ToolsWithToolsetsResult as l, FileAccessRuleProvider$1 as n, ToolRegistry as o, FileAccessRules as r, ListToolsFilter as s, FILE_ACCESS_RULES_KEY$1 as t, ToolsetInfo as u };