qlogicagent 0.5.2 → 0.6.0

package/dist/types/skills/tools/mcp-client-types.d.ts

@@ -0,0 +1,269 @@
+/** Supported MCP transport types */
+export type McpTransportType = "stdio" | "sse" | "http" | "ws" | "in-process";
+/** Stdio transport configuration */
+export interface McpStdioConfig {
+    type: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+}
+/** SSE transport configuration */
+export interface McpSseConfig {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+    /** OAuth config for auth-required SSE servers */
+    oauth?: McpOAuthConfig;
+}
+/** Streamable HTTP transport configuration (MCP 2025-03-26) */
+export interface McpHttpConfig {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+    /** OAuth config for auth-required HTTP servers */
+    oauth?: McpOAuthConfig;
+}
+/** WebSocket transport configuration */
+export interface McpWsConfig {
+    type: "ws";
+    url: string;
+    headers?: Record<string, string>;
+}
+/** In-process transport (bundled MCP servers) */
+export interface McpInProcessConfig {
+    type: "in-process";
+    /** Module identifier to load */
+    moduleId: string;
+    /** Init args passed to the in-process server */
+    initArgs?: Record<string, unknown>;
+}
+/** Union of all transport configurations */
+export type McpServerConfig = McpStdioConfig | McpSseConfig | McpHttpConfig | McpWsConfig | McpInProcessConfig;
+/** OAuth configuration for remote MCP servers */
+export interface McpOAuthConfig {
+    /** Client ID (or URL-based client_id per CIMD/SEP-991) */
+    clientId?: string;
+    /** Client secret (optional, for confidential clients) */
+    clientSecret?: string;
+    /** Override authorization endpoint (otherwise discovered via RFC 8414) */
+    authorizationEndpoint?: string;
+    /** Override token endpoint */
+    tokenEndpoint?: string;
+    /** Requested scopes */
+    scopes?: string[];
+    /** Fixed callback port (otherwise picks random available port) */
+    callbackPort?: number;
+    /** Audience for token exchange (RFC 8693) */
+    audience?: string;
+}
+/** OAuth token set */
+export interface McpOAuthTokens {
+    accessToken: string;
+    tokenType: string;
+    refreshToken?: string;
+    expiresAt?: number;
+    scope?: string;
+}
+/** Authentication state of a server */
+export type McpAuthState = {
+    status: "authenticated";
+    tokens: McpOAuthTokens;
+} | {
+    status: "needs-auth";
+    authUrl?: string;
+    message?: string;
+} | {
+    status: "refreshing";
+} | {
+    status: "step-up-required";
+    scope: string;
+    authUrl?: string;
+} | {
+    status: "not-applicable";
+};
+/** Server connection status */
+export type McpConnectionStatus = "connected" | "connecting" | "disconnected" | "failed" | "needs-auth" | "disabled";
+/** Server capabilities (as reported by initialize) */
+export interface McpServerCapabilities {
+    tools?: {
+        listChanged?: boolean;
+    };
+    resources?: {
+        subscribe?: boolean;
+        listChanged?: boolean;
+    };
+    prompts?: {
+        listChanged?: boolean;
+    };
+    logging?: Record<string, unknown>;
+    experimental?: Record<string, unknown>;
+}
+/** Full server connection state */
+export interface McpServerState {
+    name: string;
+    config: McpServerConfig;
+    status: McpConnectionStatus;
+    capabilities?: McpServerCapabilities;
+    serverVersion?: string;
+    serverInstructions?: string;
+    error?: string;
+    /** Timestamp of last successful connection */
+    connectedAt?: number;
+    /** Number of reconnect attempts since last disconnect */
+    reconnectAttempts?: number;
+}
+/**
+ * An MCP tool definition as reported by tools/list.
+ * The host converts these into PortableTool entries for the LLM.
+ */
+export interface McpExternalTool {
+    /** Tool name on the MCP server (original) */
+    name: string;
+    /** Tool description */
+    description?: string;
+    /** JSON Schema for input parameters */
+    inputSchema?: Record<string, unknown>;
+    /** Annotations from the server (readOnlyHint, destructiveHint, etc.) */
+    annotations?: McpToolAnnotations;
+}
+/** Tool behavior annotations (MCP 2025-03-26 spec) */
+export interface McpToolAnnotations {
+    /** Hints that the tool performs only reads */
+    readOnlyHint?: boolean;
+    /** Hints that the tool may be destructive */
+    destructiveHint?: boolean;
+    /** Hints that the tool is idempotent */
+    idempotentHint?: boolean;
+    /** Hints about concurrency safety */
+    openWorldHint?: boolean;
+    /** Human-readable title for UI display */
+    title?: string;
+}
+/**
+ * Prefixed tool name format: mcp__{normalizedServer}__{normalizedTool}
+ * This ensures no collisions with built-in tools.
+ */
+export interface McpToolIdentifier {
+    serverName: string;
+    toolName: string;
+    /** Full prefixed name: mcp__{server}__{tool} */
+    prefixedName: string;
+}
+/**
+ * Notification payload when a server's tool list changes.
+ * The host should re-fetch tools/list and hot-swap the tool set.
+ */
+export interface McpToolsChangedEvent {
+    serverName: string;
+    /** Previous tool names (for diff-based cleanup) */
+    previousTools: string[];
+    /** Updated tool list */
+    currentTools: McpExternalTool[];
+}
+/** MCP Resource definition */
+export interface McpResourceDefinition {
+    uri: string;
+    name: string;
+    mimeType?: string;
+    description?: string;
+    /** Size in bytes (if known) */
+    size?: number;
+}
+/** Resource template (parameterized URI) */
+export interface McpResourceTemplate {
+    uriTemplate: string;
+    name: string;
+    mimeType?: string;
+    description?: string;
+}
+/** Content of a read resource */
+export interface McpResourceContentItem {
+    uri: string;
+    mimeType?: string;
+    /** Text content (mutually exclusive with blob) */
+    text?: string;
+    /** Base64-encoded binary (mutually exclusive with text) */
+    blob?: string;
+}
+/** Persisted resource content (after binary blob handling) */
+export interface McpPersistedResourceContent {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    /** Path where binary was saved to disk */
+    blobSavedTo?: string;
+    /** Size of persisted binary in bytes */
+    blobSize?: number;
+}
+/** MCP Prompt definition from prompts/list */
+export interface McpPromptDefinition {
+    name: string;
+    description?: string;
+    arguments?: McpPromptArgument[];
+}
+/** Argument for an MCP prompt */
+export interface McpPromptArgument {
+    name: string;
+    description?: string;
+    required?: boolean;
+}
+/** Result of prompts/get — prompt content messages */
+export interface McpPromptMessage {
+    role: "user" | "assistant";
+    content: McpPromptContent;
+}
+export type McpPromptContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | {
+    type: "resource";
+    resource: {
+        uri: string;
+        text?: string;
+        blob?: string;
+        mimeType?: string;
+    };
+};
+/** MCP Elicitation request (server asks user for input) */
+export interface McpElicitRequest {
+    message: string;
+    requestedSchema?: Record<string, unknown>;
+}
+/** Elicitation response */
+export interface McpElicitResult {
+    action: "accept" | "deny" | "cancel";
+    content?: Record<string, unknown>;
+}
+export type McpLogLevel = "debug" | "info" | "warning" | "error" | "critical";
+export interface McpLogEntry {
+    serverName: string;
+    level: McpLogLevel;
+    logger?: string;
+    data: unknown;
+    timestamp: number;
+}
+export declare const MCP_CONNECTION_TIMEOUT_MS = 30000;
+export declare const MCP_REQUEST_TIMEOUT_MS = 60000;
+export declare const MCP_TOOL_CALL_TIMEOUT_MS = 100000;
+export declare const MCP_MAX_RECONNECT_ATTEMPTS = 5;
+export declare const MCP_RECONNECT_BASE_DELAY_MS = 1000;
+export declare const MCP_RECONNECT_MAX_DELAY_MS = 30000;
+export declare const MCP_MAX_DESCRIPTION_LENGTH = 2048;
+export declare const MCP_AUTH_CACHE_TTL_MS: number;
+export declare const MCP_BATCH_SIZE_LOCAL = 3;
+export declare const MCP_BATCH_SIZE_REMOTE = 20;
+/** Normalize a name for use in the prefixed tool name format */
+export declare function normalizeNameForMcp(name: string): string;
+/** Build a prefixed tool name: mcp__{server}__{tool} */
+export declare function buildMcpToolName(serverName: string, toolName: string): string;
+/** Get the prefix for a server (for batch removal) */
+export declare function getMcpServerPrefix(serverName: string): string;
+/** Parse a prefixed tool name back into server + tool */
+export declare function parseMcpToolName(prefixedName: string): McpToolIdentifier | null;
+/** Check if a tool name is an MCP-injected tool */
+export declare function isMcpToolName(name: string): boolean;

package/dist/types/skills/tools/mcp-resource-tools.d.ts

@@ -0,0 +1,14 @@
+import type { PortableTool } from "../portable-tool.js";
+import type { McpManager } from "../mcp/mcp-manager.js";
+export interface ListMcpResourcesParams {
+    /** Filter by MCP server name (optional — omit to list from all servers) */
+    server?: string;
+}
+export declare function createListMcpResourcesTool(getMcpManager: () => McpManager | null): PortableTool<ListMcpResourcesParams>;
+export interface ReadMcpResourceParams {
+    /** MCP server name */
+    server: string;
+    /** Resource URI to read */
+    uri: string;
+}
+export declare function createReadMcpResourceTool(getMcpManager: () => McpManager | null): PortableTool<ReadMcpResourceParams>;

package/dist/types/skills/tools/mcp-tool.d.ts

@@ -0,0 +1,249 @@
+import type { PortableTool } from "../portable-tool.js";
+import type { McpServerConfig, McpConnectionStatus, McpServerCapabilities, McpToolAnnotations, McpToolsChangedEvent, McpPromptDefinition, McpPromptMessage, McpElicitResult, McpAuthState, McpLogEntry, McpLogLevel } from "./mcp-client-types.js";
+export type { McpServerConfig, McpStdioConfig, McpSseConfig, McpHttpConfig, McpWsConfig, McpInProcessConfig, McpServerState, McpConnectionStatus, McpServerCapabilities, McpExternalTool, McpToolAnnotations, McpToolIdentifier, McpToolsChangedEvent, McpResourceDefinition, McpResourceTemplate, McpPersistedResourceContent, McpResourceContentItem, McpPromptDefinition, McpPromptArgument, McpPromptMessage, McpPromptContent, McpElicitResult, McpElicitRequest, McpOAuthConfig, McpOAuthTokens, McpAuthState, McpLogEntry, McpLogLevel, McpTransportType, } from "./mcp-client-types.js";
+export { normalizeNameForMcp, buildMcpToolName, getMcpServerPrefix, parseMcpToolName, isMcpToolName, MCP_CONNECTION_TIMEOUT_MS, MCP_REQUEST_TIMEOUT_MS, MCP_TOOL_CALL_TIMEOUT_MS, MCP_MAX_RECONNECT_ATTEMPTS, MCP_MAX_DESCRIPTION_LENGTH, } from "./mcp-client-types.js";
+export declare const MCP_TOOL_NAME: "mcp";
+export type McpAction = "list_servers" | "list_tools" | "call_tool" | "list_resources" | "read_resource" | "list_prompts" | "get_prompt" | "authenticate" | "manage_server";
+export interface McpToolParams {
+    action: McpAction;
+    /** Server name (required for most actions) */
+    server?: string;
+    /** Tool name on the MCP server (for call_tool) */
+    toolName?: string;
+    /** Arguments for the MCP tool call or prompt arguments */
+    arguments?: Record<string, unknown>;
+    /** Resource URI (for read_resource) */
+    uri?: string;
+    /** Prompt name (for get_prompt) */
+    promptName?: string;
+    /** Server management sub-action */
+    manageAction?: McpManageAction;
+    /** Server config (for manage_server add) */
+    config?: McpServerConfig;
+}
+export type McpManageAction = "add" | "remove" | "restart" | "health_check" | "enable" | "disable";
+export declare const MCP_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["list_servers", "list_tools", "call_tool", "list_resources", "read_resource", "list_prompts", "get_prompt", "authenticate", "manage_server"];
+            readonly description: string;
+        };
+        readonly server: {
+            readonly type: "string";
+            readonly description: "MCP server name. Required for all actions except list_servers.";
+        };
+        readonly toolName: {
+            readonly type: "string";
+            readonly description: "Tool name on the MCP server. Required for call_tool.";
+        };
+        readonly arguments: {
+            readonly type: "object";
+            readonly description: "Arguments for the tool call or prompt. Used with call_tool and get_prompt.";
+        };
+        readonly uri: {
+            readonly type: "string";
+            readonly description: "Resource URI. Required for read_resource.";
+        };
+        readonly promptName: {
+            readonly type: "string";
+            readonly description: "Prompt name. Required for get_prompt.";
+        };
+        readonly manageAction: {
+            readonly type: "string";
+            readonly enum: readonly ["add", "remove", "restart", "health_check", "enable", "disable"];
+            readonly description: "Sub-action for manage_server.";
+        };
+        readonly config: {
+            readonly type: "object";
+            readonly description: "Server configuration. Required for manage_server add.";
+        };
+    };
+    readonly required: readonly ["action"];
+};
+export interface McpServer {
+    name: string;
+    status: McpConnectionStatus;
+    transport: string;
+    toolCount: number;
+    resourceCount: number;
+    promptCount: number;
+    capabilities?: McpServerCapabilities;
+    serverVersion?: string;
+    error?: string;
+    connectedAt?: number;
+}
+export interface McpToolInfo {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    annotations?: McpToolAnnotations;
+    /** Prefixed name used in tool list */
+    prefixedName?: string;
+}
+export interface McpResource {
+    uri: string;
+    name: string;
+    mimeType?: string;
+    description?: string;
+    server?: string;
+}
+export interface McpResourceContent {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    blobSavedTo?: string;
+    blobSize?: number;
+}
+export interface McpCallResult {
+    success: boolean;
+    content?: string;
+    error?: string;
+    isError?: boolean;
+    /** Structured content blocks (images, resources) */
+    contentBlocks?: Array<{
+        type: "text" | "image" | "resource";
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+}
+export interface McpAuthResult {
+    status: "auth_url" | "already_authenticated" | "unsupported" | "step_up_required" | "error";
+    authUrl?: string;
+    message?: string;
+    /** Required scopes for step-up auth */
+    requiredScopes?: string[];
+}
+export interface McpPromptResult {
+    description?: string;
+    messages: McpPromptMessage[];
+}
+export interface McpManageResult {
+    success: boolean;
+    message: string;
+    /** Updated server state after the operation */
+    serverState?: McpServer;
+}
+/**
+ * Host-provided MCP client backend — full lifecycle management.
+ *
+ * Implements the complete MCP client SDK contract:
+ * - Transport abstraction (stdio/SSE/HTTP/WS/in-process)
+ * - Connection lifecycle (connect/disconnect/reconnect/health)
+ * - OAuth authentication with PKCE + token refresh
+ * - Dynamic tool injection (tools/list_changed notification)
+ * - Resource management with binary blob persistence
+ * - Prompt support
+ * - Server configuration CRUD
+ */
+export interface McpToolDeps {
+    /** List all configured MCP servers with full state */
+    listServers(): Promise<McpServer[]>;
+    /**
+     * List tools from a specific server.
+     * Results are cached; invalidated on tools/list_changed notification.
+     */
+    listTools(server: string): Promise<McpToolInfo[]>;
+    /**
+     * Call a tool on an MCP server.
+     * Handles: connection ensure → permission check → execute → parse result.
+     */
+    callTool(server: string, toolName: string, args?: Record<string, unknown>, signal?: AbortSignal): Promise<McpCallResult>;
+    /**
+     * List resources from a server (or all servers if not specified).
+     * Uses LRU cache; invalidated on resources/list_changed.
+     */
+    listResources(server?: string): Promise<McpResource[]>;
+    /**
+     * Read a specific resource by URI.
+     * Handles binary blob persistence: base64 → disk file → returns path.
+     */
+    readResource(server: string, uri: string): Promise<McpResourceContent[]>;
+    /**
+     * List prompts available from a server.
+     * Prompts are reusable templates that servers expose.
+     */
+    listPrompts?(server: string): Promise<McpPromptDefinition[]>;
+    /**
+     * Get a specific prompt with arguments expanded.
+     * Returns the prompt messages ready for injection into conversation.
+     */
+    getPrompt?(server: string, promptName: string, args?: Record<string, string>): Promise<McpPromptResult>;
+    /**
+     * Initiate OAuth authentication with a server.
+     * Supports: PKCE flow, token refresh, step-up auth.
+     *
+     * For stdio servers: returns "not_applicable".
+     * For SSE/HTTP servers: returns auth_url or triggers silent auth.
+     */
+    authenticate(server: string): Promise<McpAuthResult>;
+    /**
+     * Check current auth state of a server (without initiating a flow).
+     * Optional — host may not track auth state for all servers.
+     */
+    getAuthState?(server: string): Promise<McpAuthState>;
+    /**
+     * Add a new MCP server configuration.
+     * Optionally auto-connects after adding.
+     */
+    addServer?(name: string, config: McpServerConfig): Promise<McpManageResult>;
+    /**
+     * Remove an MCP server (disconnect + delete config).
+     * Also removes all injected tools with the server's prefix.
+     */
+    removeServer?(name: string): Promise<McpManageResult>;
+    /**
+     * Restart (disconnect + reconnect) a server.
+     * Clears caches and re-fetches tools/resources/prompts.
+     */
+    restartServer?(name: string): Promise<McpManageResult>;
+    /**
+     * Health check a server's connection.
+     * Returns the updated server state with latency info.
+     */
+    healthCheck?(server: string): Promise<McpManageResult>;
+    /**
+     * Enable/disable a server (disabled servers don't auto-connect).
+     */
+    setServerEnabled?(name: string, enabled: boolean): Promise<McpManageResult>;
+    /**
+     * Register a callback for when a server's tool list changes.
+     * The host calls this when it receives tools/list_changed notifications.
+     *
+     * The callback receives the event with previous and current tool lists,
+     * enabling the orchestration layer to hot-swap injected tools.
+     */
+    onToolsChanged?(callback: (event: McpToolsChangedEvent) => void): void;
+    /**
+     * Get all currently injected MCP tools across all servers.
+     * Returns the flattened list of tools with their prefixed names.
+     */
+    getInjectedTools?(): Promise<McpToolInfo[]>;
+    /**
+     * Handle an elicitation request from an MCP server.
+     * The server asks the user for input/consent; the host presents UI.
+     * Optional — defaults to deny if not implemented.
+     */
+    handleElicitation?(server: string, message: string, schema?: Record<string, unknown>): Promise<McpElicitResult>;
+    /**
+     * Get recent log entries from MCP servers.
+     * Optional — useful for debugging server-side issues.
+     */
+    getServerLogs?(server: string, level?: McpLogLevel, limit?: number): Promise<McpLogEntry[]>;
+}
+export declare function createMcpTool(deps: McpToolDeps): PortableTool<McpToolParams>;
+export interface McpAuthProxyDeps {
+    /** Initiate OAuth for the specified server */
+    authenticate(server: string): Promise<McpAuthResult>;
+    /** Optional callback after successful auth — e.g. reconnect, refresh tools */
+    onAuthComplete?(server: string): Promise<void>;
+}
+/**
+ * Create a dynamic per-server authentication proxy tool.
+ * One instance per unauthenticated MCP server.
+ *
+ * Tool name follows CC convention: `mcp__<normalizedServer>__authenticate`
+ */
+export declare function createMcpAuthProxy(serverName: string, deps: McpAuthProxyDeps): PortableTool<Record<string, never>>;

package/dist/types/skills/tools/monitor-tool.d.ts

@@ -0,0 +1,113 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const MONITOR_TOOL_NAME: "monitor";
+/** The kind of event source the agent can monitor. */
+export type MonitorSource = "process" | "file" | "task" | "custom";
+export type MonitorAction = "start" | "stop" | "list";
+export interface MonitorToolParams {
+    action: MonitorAction;
+    /** Required for start/stop — identifies the monitor instance. */
+    monitorId?: string;
+    /** Required for start — what kind of event source to watch. */
+    source?: MonitorSource;
+    /** Required for start — selector for the target (pid, path, taskId, custom key). */
+    target?: string;
+    /** Optional for start — conditions that should trigger wake-up. */
+    conditions?: MonitorCondition[];
+    /** Optional for start — max time to monitor in seconds before auto-stop. */
+    timeoutSeconds?: number;
+}
+export interface MonitorCondition {
+    /** What to check: exit code, stdout pattern, file modification, task status. */
+    type: "exit" | "output_match" | "file_changed" | "task_status";
+    /** Pattern or value to match (regex for output_match, status name for task_status). */
+    value?: string;
+}
+export declare const MONITOR_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["start", "stop", "list"];
+            readonly description: "Action to perform: start a new monitor, stop an existing one, or list active monitors.";
+        };
+        readonly monitorId: {
+            readonly type: "string";
+            readonly description: "Identifier for the monitor instance. Required for start/stop.";
+        };
+        readonly source: {
+            readonly type: "string";
+            readonly enum: readonly ["process", "file", "task", "custom"];
+            readonly description: "Type of event source to watch.";
+        };
+        readonly target: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly conditions: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly type: {
+                        readonly type: "string";
+                        readonly enum: readonly ["exit", "output_match", "file_changed", "task_status"];
+                    };
+                    readonly value: {
+                        readonly type: "string";
+                    };
+                };
+                readonly required: readonly ["type"];
+            };
+            readonly description: "Conditions that trigger a wake-up notification.";
+        };
+        readonly timeoutSeconds: {
+            readonly type: "number";
+            readonly description: "Auto-stop after this many seconds (default: 3600).";
+            readonly minimum: 1;
+            readonly maximum: 86400;
+        };
+    };
+    readonly required: readonly ["action"];
+};
+/** Info about an active monitor. */
+export interface MonitorInfo {
+    monitorId: string;
+    source: MonitorSource;
+    target: string;
+    conditions: MonitorCondition[];
+    startedAt: number;
+    timeoutSeconds: number;
+    /** Events received so far. */
+    eventCount: number;
+}
+/** Result of monitor operations. */
+export interface MonitorResult {
+    action: MonitorAction;
+    success: boolean;
+    monitorId?: string;
+    monitors?: MonitorInfo[];
+    error?: string;
+}
+/**
+ * Runtime dependencies injected by the host.
+ *
+ * The host is responsible for:
+ * 1. Actually watching the event source (polling, inotify, process hooks, etc.)
+ * 2. Delivering notifications back to the agent loop (via tick or wake-up)
+ * 3. Cleaning up monitors when they time out or are stopped.
+ */
+export interface MonitorToolDeps {
+    /** Start monitoring a target. Returns the created monitor info. */
+    startMonitor(params: {
+        monitorId: string;
+        source: MonitorSource;
+        target: string;
+        conditions: MonitorCondition[];
+        timeoutSeconds: number;
+    }): Promise<MonitorResult>;
+    /** Stop an active monitor. */
+    stopMonitor(monitorId: string): Promise<MonitorResult>;
+    /** List all active monitors for this session. */
+    listMonitors(): Promise<MonitorInfo[]>;
+}
+export declare function createMonitorTool(deps: MonitorToolDeps): PortableTool<MonitorToolParams>;