@nexus-cortex/core 4.26.0

package/dist/interfaces/ToolExecutorRegistry.d.ts

@@ -0,0 +1,126 @@
+/**
+ * ToolExecutorRegistry Interface
+ *
+ * Abstracts tool definition and execution.
+ * The orchestrator uses this to resolve tool definitions, validate parameters,
+ * check permissions, and execute tool calls.
+ *
+ * Node.js impl: wraps ExecutorRegistry + BaseTool subclasses (child_process, fs, shell)
+ * Browser impl: host-provided tools (fetch, DOM APIs)
+ *
+ * @module interfaces/ToolExecutorRegistry
+ */
+import type { CanonicalContentBlock } from '@nexus-cortex/types';
+/**
+ * Tool execution result.
+ *
+ * Mirrors the existing ToolResult from executors/base/ToolResult.ts
+ * but defined here as an interface for the abstraction boundary.
+ */
+export interface ToolResult {
+    /** Content to send back to LLM (string or structured content blocks) */
+    llmContent: string | CanonicalContentBlock[];
+    /** Content to display to user (optional — falls back to llmContent) */
+    returnDisplay?: string;
+    /** Whether execution was successful */
+    success: boolean;
+    /** Error message if failed */
+    error?: string;
+    /** Execution metadata */
+    metadata?: {
+        executionTime?: number;
+        resourcesUsed?: {
+            files?: string[];
+            network?: string[];
+            commands?: string[];
+        };
+        [key: string]: any;
+    };
+}
+/**
+ * Tool call confirmation details — returned by tools that need user approval.
+ */
+export interface ToolCallConfirmationDetails {
+    /** Human-readable description of what the tool will do */
+    description: string;
+    /** Whether confirmation is required */
+    requiresConfirmation: boolean;
+    /** Severity level for UI display */
+    severity?: 'info' | 'warning' | 'danger';
+    /** Additional context for confirmation prompt */
+    context?: string;
+}
+/**
+ * Tool definition — schema describing a single tool's interface.
+ */
+export interface ToolDefinition {
+    /** Tool name (PascalCase canonical form) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** JSON Schema for parameters */
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, any>;
+        required?: string[];
+    };
+}
+/**
+ * Single tool executor — validates, confirms, and executes a tool.
+ */
+export interface ToolExecutor {
+    /** Tool name */
+    readonly name: string;
+    /**
+     * Validate tool parameters before execution.
+     *
+     * @param params - Tool input parameters
+     * @returns null if valid, error message string if invalid
+     */
+    validateParams(params: Record<string, any>): string | null;
+    /**
+     * Check if this tool call needs user confirmation.
+     *
+     * @param params - Tool input parameters
+     * @param signal - Abort signal for timeout enforcement
+     * @returns Confirmation details, or false if no confirmation needed
+     */
+    shouldConfirmExecute(params: Record<string, any>, signal: AbortSignal): Promise<ToolCallConfirmationDetails | false>;
+    /**
+     * Execute the tool.
+     *
+     * @param params - Tool input parameters
+     * @param signal - Abort signal for TOOL_TIMEOUT_MS enforcement
+     * @param updateOutput - Optional callback for streaming output updates
+     * @returns Execution result
+     */
+    execute(params: Record<string, any>, signal: AbortSignal, updateOutput?: (output: string) => void): Promise<ToolResult>;
+}
+/**
+ * Tool Executor Registry — resolves and executes tools.
+ */
+export interface ToolExecutorRegistry {
+    /**
+     * Get an executor for a specific tool.
+     *
+     * @param toolName - Tool name (PascalCase)
+     * @returns Tool executor or undefined if not registered
+     */
+    getExecutor(toolName: string): ToolExecutor | undefined;
+    /**
+     * Get all available tool definitions (for sending to AI providers).
+     *
+     * @returns Array of tool definitions with schemas
+     */
+    getAllTools(): ToolDefinition[];
+    /**
+     * Execute a tool call (convenience method that resolves executor + calls execute).
+     *
+     * @param toolName - Tool name
+     * @param params - Tool input parameters
+     * @param signal - Abort signal for timeout enforcement
+     * @returns Execution result
+     */
+    executeToolCall(toolName: string, params: Record<string, any>, signal: AbortSignal): Promise<ToolResult>;
+}
+//# sourceMappingURL=ToolExecutorRegistry.d.ts.map

package/dist/interfaces/ToolExecutorRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolExecutorRegistry.d.ts","sourceRoot":"","sources":["../../src/interfaces/ToolExecutorRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,UAAU,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAAC;IAC7C,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,QAAQ,CAAC,EAAE;QACT,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,aAAa,CAAC,EAAE;YACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;YACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;YACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;SACrB,CAAC;QACF,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,oBAAoB,EAAE,OAAO,CAAC;IAC9B,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;IACzC,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAChC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,gBAAgB;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;IAE3D;;;;;;OAMG;IACH,oBAAoB,CAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,2BAA2B,GAAG,KAAK,CAAC,CAAC;IAEhD;;;;;;;OAOG;IACH,OAAO,CACL,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,WAAW,EACnB,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GACtC,OAAO,CAAC,UAAU,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IAExD;;;;OAIG;IACH,WAAW,IAAI,cAAc,EAAE,CAAC;IAEhC;;;;;;;OAOG;IACH,eAAe,CACb,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,UAAU,CAAC,CAAC;CACxB"}

package/dist/interfaces/ToolExecutorRegistry.js

@@ -0,0 +1,14 @@
+/**
+ * ToolExecutorRegistry Interface
+ *
+ * Abstracts tool definition and execution.
+ * The orchestrator uses this to resolve tool definitions, validate parameters,
+ * check permissions, and execute tool calls.
+ *
+ * Node.js impl: wraps ExecutorRegistry + BaseTool subclasses (child_process, fs, shell)
+ * Browser impl: host-provided tools (fetch, DOM APIs)
+ *
+ * @module interfaces/ToolExecutorRegistry
+ */
+export {};
+//# sourceMappingURL=ToolExecutorRegistry.js.map

package/dist/interfaces/ToolExecutorRegistry.js.map

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

package/dist/interfaces/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Runtime-Agnostic Interfaces
+ *
+ * These 6 interfaces define the I/O boundary of the Cortex orchestrator.
+ * By abstracting these boundaries, the orchestrator can run in both
+ * Node.js (current) and browser (future) environments.
+ *
+ * Node.js implementations wrap existing services (APIClient, JSONLHistoryStore, etc.).
+ * Browser implementations use fetch(), IndexedDB, DOM APIs, etc.
+ *
+ * @module interfaces
+ */
+export type { APITransport, APIResponse, StreamChunk, StreamingResponse, PreparedRequest } from './APITransport.js';
+export type { HistoryStore, SessionInfo } from './HistoryStore.js';
+export type { CredentialResolver, CredentialResult, AuthMethod } from './CredentialResolver.js';
+export type { ConfigProvider } from './ConfigProvider.js';
+export type { ToolExecutorRegistry, ToolExecutor, ToolResult, ToolCallConfirmationDetails, ToolDefinition } from './ToolExecutorRegistry.js';
+export type { PermissionHandler, PermissionDecision, PermissionPolicy } from './PermissionHandler.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/interfaces/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interfaces/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpH,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACnE,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAChG,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,YAAY,EACV,oBAAoB,EACpB,YAAY,EACZ,UAAU,EACV,2BAA2B,EAC3B,cAAc,EACf,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,wBAAwB,CAAC"}

package/dist/interfaces/index.js

@@ -0,0 +1,14 @@
+/**
+ * Runtime-Agnostic Interfaces
+ *
+ * These 6 interfaces define the I/O boundary of the Cortex orchestrator.
+ * By abstracting these boundaries, the orchestrator can run in both
+ * Node.js (current) and browser (future) environments.
+ *
+ * Node.js implementations wrap existing services (APIClient, JSONLHistoryStore, etc.).
+ * Browser implementations use fetch(), IndexedDB, DOM APIs, etc.
+ *
+ * @module interfaces
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/interfaces/index.js.map

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

package/dist/mcp/McpClient.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Minimal MCP Client for Nexus Cortex
+ *
+ * Supports stdio and StreamableHTTP transports. No OAuth/auth complexity;
+ * HTTP servers can supply auth via static headers or rely on server-side
+ * auto-provisioning at connect time.
+ */
+import type { Tool, Resource, Prompt } from '@modelcontextprotocol/sdk/types.js';
+export type McpTransportType = 'stdio' | 'http';
+export interface McpReconnectionOptions {
+    /** Max attempts before the SDK gives up on a dropped SSE channel */
+    maxRetries: number;
+    /** Initial backoff in ms */
+    initialReconnectionDelay: number;
+    /** Maximum backoff in ms */
+    maxReconnectionDelay: number;
+    /** Multiplier applied between attempts */
+    reconnectionDelayGrowFactor: number;
+}
+export interface McpServerConfig {
+    /** Server name/identifier */
+    name: string;
+    /**
+     * Transport type. Defaults to 'http' when `url` is set, otherwise 'stdio'.
+     */
+    transport?: McpTransportType;
+    /** Command to execute (stdio transport) */
+    command?: string;
+    /** Command arguments (stdio transport) */
+    args?: string[];
+    /** Environment variables (stdio transport) */
+    env?: Record<string, string>;
+    /** Working directory (stdio transport) */
+    cwd?: string;
+    /** Server URL (http transport) */
+    url?: string;
+    /** Optional static HTTP headers (http transport) */
+    headers?: Record<string, string>;
+    /** Override reconnection backoff for the HTTP SSE channel */
+    reconnectionOptions?: McpReconnectionOptions;
+    /** Connection timeout in milliseconds */
+    timeout?: number;
+}
+export declare enum McpConnectionStatus {
+    DISCONNECTED = "disconnected",
+    CONNECTING = "connecting",
+    CONNECTED = "connected",
+    /** Transient stream drop; the SDK is auto-reconnecting, client still usable. */
+    RECONNECTING = "reconnecting",
+    DISCONNECTING = "disconnecting",
+    ERROR = "error"
+}
+/**
+ * Minimal MCP Client for connecting to and interacting with MCP servers
+ */
+export declare class McpClient {
+    private readonly config;
+    private readonly debugMode;
+    private client;
+    private transport;
+    private status;
+    private discoveredTools;
+    private discoveredResources;
+    private discoveredPrompts;
+    constructor(config: McpServerConfig, debugMode?: boolean);
+    /**
+     * Connect to the MCP server
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the MCP server
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Discover tools from the MCP server
+     */
+    discoverTools(): Promise<Tool[]>;
+    /**
+     * Discover resources from the MCP server
+     * Returns empty array if server doesn't support resources (Method not found -32601)
+     */
+    discoverResources(): Promise<Resource[]>;
+    /**
+     * Discover prompts from the MCP server
+     * Returns empty array if server doesn't support prompts (Method not found -32601)
+     */
+    discoverPrompts(): Promise<Prompt[]>;
+    /**
+     * Call a tool on the MCP server
+     */
+    callTool(toolName: string, args: Record<string, unknown>): Promise<any>;
+    /**
+     * Read a resource from the MCP server
+     */
+    readResource(uri: string): Promise<any>;
+    /**
+     * Get discovered tools
+     */
+    getDiscoveredTools(): Tool[];
+    /**
+     * Get discovered resources
+     */
+    getDiscoveredResources(): Resource[];
+    /**
+     * Get discovered prompts
+     */
+    getDiscoveredPrompts(): Prompt[];
+    /**
+     * Get connection status
+     */
+    getStatus(): McpConnectionStatus;
+    /**
+     * Check if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Return the reconnection options that will be (or were) supplied to the
+     * HTTP transport. Returns undefined for stdio transport. Useful for tests
+     * and operational introspection.
+     */
+    getReconnectionOptions(): McpReconnectionOptions | undefined;
+    private getResolvedReconnectionOptions;
+    /**
+     * Recoverable transport errors: transient SSE/network drops that the SDK's
+     * reconnection loop handles on its own. A terminal "Maximum reconnection
+     * attempts exceeded" is NOT recoverable and must surface as ERROR.
+     */
+    private isRecoverableStreamError;
+    /**
+     * Build an undici dispatcher with the response body-inactivity timeout
+     * disabled (bodyTimeout: 0), so a long-lived idle SSE stream is not
+     * terminated mid-session. Returns undefined when undici is unavailable
+     * (e.g. a non-Node runtime) — the transport then uses the default fetch and
+     * relies on the SDK's reconnection.
+     */
+    private createNoIdleTimeoutDispatcher;
+    /**
+     * Assert that the client is connected
+     */
+    private assertConnected;
+}
+//# sourceMappingURL=McpClient.d.ts.map

package/dist/mcp/McpClient.d.ts.map

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