@easynet/agent-tool-hub 1.0.6

package/dist/index.d.ts

@@ -0,0 +1,552 @@
+import { T as ToolSpec, E as ExecContext, a as Evidence, b as ToolRegistry, c as ToolAdapter, S as SkillDefinition, d as SkillFrontmatter, e as SkillResource, f as ToolKind, C as Capability, g as CostHints, h as ToolHubInitOptions } from './toolhub-runtime-CQkP4QVW.js';
+export { A as AnyToolEvent, B as BudgetConfig, i as BudgetManager, j as BudgetOptions, k as ComfyUIAdapter, l as ComfyUIAdapterOptions, m as ComfyUIHistoryEntry, n as ComfyUIHttpClient, o as ComfyUIQueueResponse, p as CoreAdapter, q as CoreToolContext, r as CoreToolHandler, s as CoreToolResult, t as CoreToolsConfig, u as CoreToolsUserConfig, v as CounterValue, D as DEFAULT_CORE_TOOLS_CONFIG, w as DebugOptions, x as EventListener, y as EventLog, H as HistogramValue, z as HttpClient, I as InvokeOptions, J as JobCompletedEvent, F as JobFailedEvent, G as JobSubmittedEvent, L as LangChainAdapter, K as LangChainAdapterOptions, M as LangChainToolLike, N as LogEntry, O as LogLevel, P as Logger, Q as MCPAdapter, R as MCPAdapterOptions, U as MCPCallResult, V as MCPClientLike, W as MCPToolDefinition, X as Metrics, Y as N8nAdapter, Z as N8nAdapterOptions, _ as N8nInvokeMode, $ as N8nLocalAdapter, a0 as N8nLocalAdapterOptions, a1 as PTCRuntime, a2 as PTCRuntimeConfig, a3 as PolicyCheckResult, a4 as PolicyConfig, a5 as PolicyDeniedError, a6 as PolicyDeniedEvent, a7 as PolicyEngine, a8 as ResolvedDebugOptions, a9 as RetryEvent, aa as SchemaValidationError, ab as SchemaValidator, ac as SkillAdapter, ad as SkillAdapterOptions, ae as SkillContext, af as SkillHandler, ag as SkillInstructionResult, ah as SkillInvocationContext, ai as SkillManifestError, aj as SkillOutput, ak as Span, al as SpanEvent, am as ToolCalledEvent, an as ToolDescription, ao as ToolError, ap as ToolEvent, aq as ToolEventType, ar as ToolHub, as as ToolIntent, at as ToolMetadata, au as ToolResult, av as ToolResultEvent, aw as ToolSearchQuery, ax as Tracing, ay as ValidationResult, az as createAgentToolHub, aA as createLogger, aB as createToolHub, aC as createToolHubAndInitFromConfig, aD as registerCoreTools, aE as sanitizeForLog, aF as summarizeForLog, aG as validateFrontmatter } from './toolhub-runtime-CQkP4QVW.js';
+import '@easynet/n8n-local';
+import 'ajv';
+import 'cockatiel';
+
+/**
+ * Retry configuration.
+ */
+interface RetryOptions {
+    /** Maximum number of retries (default: 2) */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff (default: 1000) */
+    baseDelayMs?: number;
+    /** Maximum delay in ms (default: 10000) */
+    maxDelayMs?: number;
+    /** Jitter factor 0-1 (default: 0.1) */
+    jitter?: number;
+    /** Error filter: return true to retry, false to abort */
+    shouldRetry?: (error: Error) => boolean;
+    /** Callback on each retry attempt */
+    onRetry?: (error: Error, attempt: number) => void;
+}
+/**
+ * Determine if an error is retryable.
+ */
+declare function isRetryable(error: unknown): boolean;
+/**
+ * Execute a function with retry logic using exponential backoff.
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Create a tagged error with a kind field for retry classification.
+ */
+declare function createTaggedError(kind: string, message: string, details?: unknown): Error & {
+    kind: string;
+    details?: unknown;
+};
+
+/**
+ * Options for building evidence from a tool invocation.
+ */
+interface BuildEvidenceOptions {
+    spec: ToolSpec;
+    args: unknown;
+    result: unknown;
+    raw?: unknown;
+    ctx: ExecContext;
+    durationMs?: number;
+}
+/**
+ * Build evidence records from a tool invocation result.
+ */
+declare function buildEvidence(options: BuildEvidenceOptions): Evidence[];
+
+/**
+ * Discovery source configuration.
+ */
+interface DiscoverySource {
+    /** Unique identifier for this source */
+    id: string;
+    /** The adapter that supports listTools() */
+    adapter: ToolAdapter;
+    /** Refresh interval in ms (0 = manual only) */
+    refreshIntervalMs?: number;
+    /** Whether to auto-discover on startup */
+    autoDiscover?: boolean;
+}
+/**
+ * Discovery manager that pulls tool specs from adapters
+ * and registers them into the ToolRegistry.
+ */
+declare class Discovery {
+    private readonly sources;
+    private readonly timers;
+    private readonly registry;
+    private readonly lastRefresh;
+    private readonly discoveredTools;
+    constructor(registry: ToolRegistry);
+    /**
+     * Add a discovery source.
+     */
+    addSource(source: DiscoverySource): void;
+    /**
+     * Remove a discovery source and its registered tools.
+     */
+    removeSource(id: string): void;
+    /**
+     * Refresh tools from a specific source (or all sources).
+     */
+    refresh(sourceId?: string): Promise<ToolSpec[]>;
+    /**
+     * Get the last refresh timestamp for a source.
+     */
+    getLastRefresh(sourceId: string): number | undefined;
+    /**
+     * Get all registered source IDs.
+     */
+    getSources(): string[];
+    /**
+     * Stop all refresh timers.
+     */
+    dispose(): void;
+    private refreshSource;
+}
+
+/**
+ * Job status in the lifecycle.
+ */
+type JobStatus = "queued" | "running" | "completed" | "failed";
+/**
+ * A job record representing an async tool invocation.
+ */
+interface Job {
+    jobId: string;
+    toolName: string;
+    requestId: string;
+    taskId: string;
+    status: JobStatus;
+    createdAt: number;
+    updatedAt: number;
+    result?: unknown;
+    error?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for submitting a job.
+ */
+interface SubmitJobOptions {
+    toolName: string;
+    requestId: string;
+    taskId: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Job store interface for pluggable backends.
+ */
+interface JobStore {
+    set(jobId: string, job: Job): Promise<void>;
+    get(jobId: string): Promise<Job | undefined>;
+    list(filter?: {
+        toolName?: string;
+        status?: JobStatus;
+    }): Promise<Job[]>;
+    delete(jobId: string): Promise<void>;
+}
+/**
+ * In-memory job store (default, for PoC and testing).
+ */
+declare class InMemoryJobStore implements JobStore {
+    private readonly jobs;
+    set(jobId: string, job: Job): Promise<void>;
+    get(jobId: string): Promise<Job | undefined>;
+    list(filter?: {
+        toolName?: string;
+        status?: JobStatus;
+    }): Promise<Job[]>;
+    delete(jobId: string): Promise<void>;
+    get size(): number;
+    clear(): void;
+}
+/**
+ * Async Job Manager: unified async task handling for tools.
+ * Provides submit/poll/getResult pattern.
+ */
+declare class AsyncJobManager {
+    private readonly store;
+    private readonly emitter;
+    private readonly ttlMs;
+    private cleanupTimer?;
+    constructor(options?: {
+        store?: JobStore;
+        ttlMs?: number;
+    });
+    /**
+     * Submit a new async job.
+     */
+    submit(options: SubmitJobOptions): Promise<Job>;
+    /**
+     * Update job status to running.
+     */
+    markRunning(jobId: string): Promise<Job | undefined>;
+    /**
+     * Complete a job with a result.
+     */
+    complete(jobId: string, result: unknown): Promise<Job | undefined>;
+    /**
+     * Fail a job with an error message.
+     */
+    fail(jobId: string, error: string): Promise<Job | undefined>;
+    /**
+     * Get current job status.
+     */
+    getStatus(jobId: string): Promise<JobStatus | undefined>;
+    /**
+     * Get the full job record.
+     */
+    getJob(jobId: string): Promise<Job | undefined>;
+    /**
+     * Get the result of a completed job.
+     */
+    getResult(jobId: string): Promise<unknown | undefined>;
+    /**
+     * List jobs with optional filter.
+     */
+    list(filter?: {
+        toolName?: string;
+        status?: JobStatus;
+    }): Promise<Job[]>;
+    /**
+     * Subscribe to job events.
+     */
+    on(event: "submitted" | "running" | "completed" | "failed", listener: (job: Job) => void): () => void;
+    /**
+     * Stop cleanup timer.
+     */
+    dispose(): void;
+    private startCleanup;
+    private cleanup;
+}
+
+/**
+ * Parse a SKILL.md file into its constituent parts:
+ * - YAML frontmatter (metadata)
+ * - Markdown body (instructions)
+ *
+ * Supports the standard YAML frontmatter format:
+ * ```
+ * ---
+ * name: my-skill
+ * description: Does something useful
+ * ---
+ *
+ * # Instructions here...
+ * ```
+ */
+declare function parseSkillMd(content: string, filePath: string): {
+    frontmatter: SkillFrontmatter;
+    instructions: string;
+};
+/**
+ * Scan a skill directory for bundled resource files (Level 3).
+ * Recursively finds all files except SKILL.md and tool.json.
+ */
+declare function scanSkillResources(dirPath: string): Promise<SkillResource[]>;
+/**
+ * Load and parse a complete skill from a directory containing SKILL.md.
+ * Returns the full SkillDefinition with all three progressive disclosure levels.
+ */
+declare function loadSkillDefinition(dirPath: string): Promise<SkillDefinition>;
+
+/**
+ * Resolve an input path to an absolute path within the sandbox.
+ * Throws PATH_OUTSIDE_SANDBOX if the resolved path escapes the sandbox root.
+ *
+ * For existing files: uses realpath to resolve symlinks.
+ * For non-existing files (write targets): resolves the parent directory.
+ */
+declare function resolveSandboxedPath(inputPath: string, sandboxRoot: string): Promise<string>;
+
+/**
+ * Validate a URL against allowed hosts and blocked CIDRs.
+ * Prevents SSRF by checking both hostname allowlist and resolved IP addresses.
+ *
+ * @throws HTTP_DISALLOWED_HOST if the URL is blocked
+ */
+declare function validateUrl(url: string, allowedHosts: string[], blockedCidrs: string[]): Promise<URL>;
+/**
+ * Check if an IPv4 address falls within any blocked CIDR range.
+ */
+declare function isIpInBlockedCidrs(ip: string, cidrs: string[]): boolean;
+
+declare const readTextSpec: ToolSpec;
+
+declare const writeTextSpec: ToolSpec;
+
+declare const listDirSpec: ToolSpec;
+
+declare const searchTextSpec: ToolSpec;
+
+declare const sha256Spec: ToolSpec;
+
+declare const deletePathSpec: ToolSpec;
+
+declare const fetchTextSpec: ToolSpec;
+
+declare const fetchJsonSpec: ToolSpec;
+
+declare const downloadFileSpec: ToolSpec;
+
+declare const headSpec: ToolSpec;
+
+declare const jsonSelectSpec: ToolSpec;
+
+declare const truncateSpec: ToolSpec;
+
+declare const hashTextSpec: ToolSpec;
+
+declare const nowSpec: ToolSpec;
+
+declare const templateRenderSpec: ToolSpec;
+
+/**
+ * Cursor-compatible MCP server configuration.
+ * Supports command-based (stdio) and URL-based (SSE/HTTP) servers.
+ */
+interface MCPServerConfig {
+    /** Command to spawn the MCP server process */
+    command?: string;
+    /** Arguments for the command */
+    args?: string[];
+    /** Environment variables for the spawned process */
+    env?: Record<string, string>;
+    /** SSE/HTTP URL for remote MCP server */
+    url?: string;
+}
+/**
+ * Discoverable tool kinds (subset of ToolKind that can be directory-discovered).
+ */
+type DiscoverableKind = Extract<ToolKind, "mcp" | "langchain" | "skill" | "n8n">;
+/**
+ * Tool manifest read from tool.json or inferred from conventional files.
+ */
+interface ToolManifest {
+    /** Tool kind — determines which loader and adapter handle this tool */
+    kind: DiscoverableKind;
+    /** Tool name override (default: "<namespace>/<dirname>") */
+    name?: string;
+    /** Semver version (default: "1.0.0") */
+    version?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Searchable tags */
+    tags?: string[];
+    /** Required capabilities for PolicyEngine gating */
+    capabilities?: Capability[];
+    /** Cost hints for routing/budgeting */
+    costHints?: CostHints;
+    /**
+     * Entry point file relative to tool directory.
+     * Defaults per kind:
+     *   mcp → "mcp.json"
+     *   langchain → "index" (or all *.js/*.mjs files when inside a "langchain" folder)
+     *   skill → "handler"
+     *   n8n → "workflow.json"
+     */
+    entryPoint?: string;
+    /** JSON Schema for input validation */
+    inputSchema?: object;
+    /** JSON Schema for output validation */
+    outputSchema?: object;
+    /** Whether this tool is enabled (default: true). Set false to skip. */
+    enabled?: boolean;
+}
+/**
+ * Configuration for the DirectoryScanner.
+ */
+interface DirectoryScannerOptions {
+    /** One or more root directories to scan for tool subdirectories */
+    roots: Array<string | {
+        path: string;
+        namespace?: string;
+    }>;
+    /** Namespace prefix for discovered tool names (default: "dir") */
+    namespace?: string;
+    /** File extensions to try for JS/TS entry points (default: [".js", ".mjs"]) */
+    extensions?: string[];
+    /** Callback for non-fatal errors during scan (tool dir path, error) */
+    onError?: (toolDir: string, error: Error) => void;
+}
+/**
+ * Result from loading a single tool directory.
+ */
+interface LoadedTool {
+    /** The parsed manifest */
+    manifest: ToolManifest;
+    /** Absolute path to the tool directory */
+    dirPath: string;
+    /** Loaded implementation (LangChainToolLike instance or SkillHandler function) */
+    impl?: unknown;
+    /** For MCP tools: the parsed server config from mcp.json */
+    mcpConfig?: MCPServerConfig;
+    /** For n8n tools: the parsed workflow definition */
+    workflowDef?: unknown;
+    /** For Skill tools: the parsed SKILL.md definition with progressive disclosure levels */
+    skillDefinition?: SkillDefinition;
+}
+
+/**
+ * Scans filesystem directories for tool definitions.
+ * A tool can be declared via tool.json or inferred from conventional files
+ * (SKILL.md, workflow.json, mcp.json, or an index entry point).
+ */
+declare class DirectoryScanner {
+    private readonly roots;
+    private readonly extensions;
+    private readonly onError?;
+    constructor(options: DirectoryScannerOptions);
+    /**
+     * Scan all root directories and return discovered ToolSpecs.
+     * Errors in individual tool directories are reported via onError
+     * and do not prevent other tools from loading.
+     */
+    scan(): Promise<ToolSpec[]>;
+    private scanRoot;
+    /**
+     * Recursively scan directories for tool definitions.
+     * Directories can be detected via tool.json or inferred markers.
+     */
+    private scanRecursive;
+    private loadToolDir;
+    private inferManifest;
+    private fileExists;
+    private hasEntryPoint;
+    private hasLangchainFiles;
+    private listLangchainEntryFiles;
+    private loadByKind;
+    private loadLangChainTools;
+    private toToolSpec;
+}
+
+/**
+ * A ToolAdapter that discovers tools from filesystem directories.
+ * Used as the adapter within a DiscoverySource for the Discovery system.
+ *
+ * Note: This adapter's invoke() is not called directly. Discovered tools
+ * retain their original kind (mcp/langchain/skill/n8n) and are invoked
+ * by the kind-specific adapter registered on PTCRuntime.
+ */
+declare class DirectoryToolAdapter implements ToolAdapter {
+    readonly kind: "mcp";
+    private readonly scanner;
+    constructor(options: DirectoryScannerOptions);
+    /**
+     * Scan directories and return discovered tool specs.
+     * Called by Discovery.refresh().
+     */
+    listTools(): Promise<ToolSpec[]>;
+    /**
+     * Not used — actual invocation routes through kind-specific adapters.
+     */
+    invoke(_spec: ToolSpec, _args: unknown, _ctx: ExecContext): Promise<{
+        result: unknown;
+    }>;
+    /**
+     * Get the underlying scanner for direct usage.
+     */
+    getScanner(): DirectoryScanner;
+}
+/**
+ * Options for creating a directory discovery source.
+ */
+interface DirectoryDiscoveryOptions extends DirectoryScannerOptions {
+    /** Refresh interval in ms (0 = manual only, default: 0) */
+    refreshIntervalMs?: number;
+    /** Whether to auto-discover on startup (default: true) */
+    autoDiscover?: boolean;
+}
+/**
+ * Factory: create a DiscoverySource for directory-based tool discovery.
+ *
+ * Usage:
+ * ```ts
+ * const discovery = new Discovery(registry);
+ * discovery.addSource(
+ *   createDirectoryDiscoverySource("local-tools", {
+ *     roots: ["/path/to/tools"],
+ *     namespace: "local",
+ *     refreshIntervalMs: 60_000,
+ *     autoDiscover: true,
+ *   })
+ * );
+ * ```
+ */
+declare function createDirectoryDiscoverySource(id: string, options: DirectoryDiscoveryOptions): DiscoverySource;
+
+/**
+ * Connection info for an MCP server.
+ */
+interface MCPConnectionInfo {
+    /** Transport type: "url" for SSE/HTTP, "stdio" for command-based */
+    type: "url" | "stdio";
+    /** SSE/HTTP URL (when type="url") */
+    url?: string;
+    /** Command to spawn (when type="stdio") */
+    command?: string;
+    /** Command arguments (when type="stdio") */
+    args?: string[];
+    /** Environment variables (when type="stdio") */
+    env?: Record<string, string>;
+}
+/**
+ * Manages MCP server connection information extracted from directory discovery.
+ *
+ * This class provides connection configuration for MCP servers discovered
+ * from mcp.json files. The actual MCP client creation and lifecycle management
+ * is the consumer's responsibility (using @modelcontextprotocol/sdk or similar).
+ *
+ * Usage:
+ * ```ts
+ * const manager = new MCPProcessManager();
+ * const info = manager.getConnectionInfo("my-tool", mcpConfig);
+ * if (info.type === "stdio") {
+ *   // Spawn process with info.command, info.args, info.env
+ * } else {
+ *   // Connect SSE client to info.url
+ * }
+ * ```
+ */
+declare class MCPProcessManager {
+    private readonly connections;
+    /**
+     * Get connection info for an MCP tool based on its config.
+     * Caches the result by tool name.
+     */
+    getConnectionInfo(toolName: string, config: MCPServerConfig): MCPConnectionInfo;
+    /**
+     * Remove cached connection info for a tool.
+     */
+    remove(toolName: string): boolean;
+    /**
+     * Get all registered tool names.
+     */
+    getToolNames(): string[];
+    /**
+     * Clear all cached connection info.
+     */
+    dispose(): void;
+}
+
+/**
+ * Error thrown during directory-based tool discovery.
+ */
+declare class DiscoveryError extends Error {
+    /** Absolute path to the tool directory that caused the error */
+    readonly toolDir: string;
+    /** Phase in which the error occurred */
+    readonly phase: "manifest" | "load" | "validate";
+    /** The underlying cause */
+    readonly cause?: Error;
+    constructor(toolDir: string, phase: "manifest" | "load" | "validate", message: string, cause?: Error);
+}
+
+interface ToolHubConfigLoadResult {
+    configPath: string;
+    rawConfig: unknown;
+    options: ToolHubInitOptions;
+}
+declare function mapToolHubConfig(raw: unknown, configDir: string): ToolHubInitOptions;
+declare function loadToolHubConfig(configPath: string): Promise<ToolHubConfigLoadResult>;
+
+export { AsyncJobManager, type BuildEvidenceOptions, Capability, CostHints, type DirectoryDiscoveryOptions, DirectoryScanner, type DirectoryScannerOptions, DirectoryToolAdapter, type DiscoverableKind, Discovery, DiscoveryError, type DiscoverySource, Evidence, ExecContext, InMemoryJobStore, type Job, type JobStatus, type JobStore, type LoadedTool, type MCPConnectionInfo, MCPProcessManager, type MCPServerConfig, type RetryOptions, SkillDefinition, SkillFrontmatter, SkillResource, type SubmitJobOptions, ToolAdapter, type ToolHubConfigLoadResult, ToolHubInitOptions, ToolKind, type ToolManifest, ToolRegistry, ToolSpec, buildEvidence, createDirectoryDiscoverySource, createTaggedError, deletePathSpec, downloadFileSpec, fetchJsonSpec, fetchTextSpec, hashTextSpec, headSpec, isIpInBlockedCidrs, isRetryable, jsonSelectSpec, listDirSpec, loadSkillDefinition, loadToolHubConfig, mapToolHubConfig, nowSpec, parseSkillMd, readTextSpec, resolveSandboxedPath, scanSkillResources, searchTextSpec, sha256Spec, templateRenderSpec, truncateSpec, validateUrl, withRetry, writeTextSpec };