@sidurijs/hands 1.0.0

package/README.md

@@ -0,0 +1,35 @@
+# @sidurijs/hands
+
+Hands Organ for Siduri: Model Context Protocol (MCP) server integration, tool execution, action lifecycle tracking, and cryptographic policy-driven action enforcement.
+
+## Features
+
+- **Model Context Protocol (MCP) Client**: Connects via Stdio, Server-Sent Events (SSE), or custom transports using `@modelcontextprotocol/sdk`.
+- **Dynamic Tool Discovery**: Queries `tools/list` on connected MCP servers and maps definitions into Siduri's tool registry.
+- **Cryptographic Capability Enforcement**: Verifies HMAC-signed `AuthorizationCapability` tokens before any tool execution can proceed.
+- **Idempotency & Concurrency Locks**: Backed by `ActionStore` to prevent duplicate concurrent or replayed side-effects.
+- **Recursive Schema Validation**: Enforces JSON Schema types and defends against prototype pollution attempts.
+- **Execution Lifecycle Management**: Enforces configurable timeouts and propagates AbortController cancellation signals.
+
+## Usage
+
+```typescript
+import { DefaultHandsOrgan } from '@sidurijs/hands';
+
+const hands = new DefaultHandsOrgan({
+  defaultTimeoutMs: 15000,
+  providers: [
+    {
+      serverName: 'filesystem',
+      command: 'npx',
+      args: ['-y', '@modelcontextprotocol/server-filesystem', '/path/to/dir']
+    }
+  ]
+});
+
+// Discovers tools dynamically from configured providers
+const tools = await hands.listTools();
+
+// Executes authorized tool intents with policy tokens
+const result = await hands.executeAction(actionIntent, authorizationCapability);
+```

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { HandsOrgan, ToolDefinition, ActionIntent, ActionExecutionResult, AuthorizationCapability, ToolExecutionOptions, ActionStore } from '@sidurijs/core';
+import { MCPClientProvider, MCPProviderConfig, MCPToolHandler } from './mcp-provider';
+import { createLifeTools, LifeToolsOptions } from './life-tools';
+export type ToolHandler = MCPToolHandler;
+export { MCPClientProvider, MCPProviderConfig, createLifeTools, LifeToolsOptions };
+export interface DefaultHandsOrganConfig {
+    providers?: MCPProviderConfig[];
+    defaultTimeoutMs?: number;
+    store?: ActionStore;
+    secretKey?: string;
+    knowledge?: any;
+}
+export declare class DefaultHandsOrgan implements HandsOrgan {
+    private readonly config;
+    private readonly toolRegistry;
+    private readonly providerTools;
+    private readonly mcpProviders;
+    private readonly defaultTimeoutMs;
+    private readonly store;
+    private readonly secretKey;
+    private initialized;
+    private initializePromise?;
+    constructor(config?: DefaultHandsOrganConfig);
+    addProvider(providerConfig: MCPProviderConfig): MCPClientProvider;
+    getProvider(serverName: string): MCPClientProvider | undefined;
+    initialize(): Promise<void>;
+    registerTool(handler: ToolHandler, providerId?: string): void;
+    unregisterTool(toolIdentifier: string): boolean;
+    listTools(): Promise<ToolDefinition[]>;
+    findHandler(toolIdentifier: string): ToolHandler | undefined;
+    executeAction(action: ActionIntent, authorization: AuthorizationCapability, options?: ToolExecutionOptions): Promise<ActionExecutionResult>;
+    close(): Promise<void>;
+}
+export declare function probeHandsHealth(context: {
+    config?: any;
+    env?: Record<string, string | undefined>;
+}): {
+    ok: boolean;
+    message?: string;
+};
+export * from './schema-validator';
+export * from './mcp-provider';

package/dist/index.js

@@ -0,0 +1,413 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultHandsOrgan = exports.createLifeTools = exports.MCPClientProvider = void 0;
+exports.probeHandsHealth = probeHandsHealth;
+const core_1 = require("@sidurijs/core");
+const schema_validator_1 = require("./schema-validator");
+const mcp_provider_1 = require("./mcp-provider");
+Object.defineProperty(exports, "MCPClientProvider", { enumerable: true, get: function () { return mcp_provider_1.MCPClientProvider; } });
+const life_tools_1 = require("./life-tools");
+Object.defineProperty(exports, "createLifeTools", { enumerable: true, get: function () { return life_tools_1.createLifeTools; } });
+class DefaultHandsOrgan {
+    config;
+    toolRegistry = new Map();
+    providerTools = new Map();
+    mcpProviders = new Map();
+    defaultTimeoutMs;
+    store;
+    secretKey;
+    initialized = false;
+    initializePromise;
+    constructor(config = {}) {
+        this.config = config;
+        this.defaultTimeoutMs = config.defaultTimeoutMs ?? 10_000;
+        this.store = config.store ?? new core_1.InMemoryActionStore();
+        this.secretKey = (0, core_1.getOrGenerateLocalActionPolicySecret)(config.secretKey);
+        if (config.knowledge) {
+            const lifeTools = (0, life_tools_1.createLifeTools)(config.knowledge);
+            for (const tool of lifeTools) {
+                this.registerTool(tool, 'life');
+            }
+        }
+        if (config.providers) {
+            for (const providerConfig of config.providers) {
+                this.addProvider(providerConfig);
+            }
+        }
+    }
+    addProvider(providerConfig) {
+        const provider = new mcp_provider_1.MCPClientProvider(providerConfig);
+        this.mcpProviders.set(providerConfig.serverName, provider);
+        // Register static tools immediately if supplied
+        if (providerConfig.tools) {
+            for (const tool of providerConfig.tools) {
+                this.registerTool(tool, providerConfig.serverName);
+            }
+        }
+        return provider;
+    }
+    getProvider(serverName) {
+        return this.mcpProviders.get(serverName);
+    }
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        if (this.initializePromise) {
+            return this.initializePromise;
+        }
+        this.initializePromise = (async () => {
+            for (const provider of this.mcpProviders.values()) {
+                try {
+                    const discovered = await provider.discoverTools();
+                    for (const handler of discovered) {
+                        this.registerTool(handler, provider.serverName);
+                    }
+                }
+                catch (err) {
+                    // Log or retain error, allow other providers to initialize
+                }
+            }
+            this.initialized = true;
+        })();
+        try {
+            await this.initializePromise;
+        }
+        finally {
+            this.initializePromise = undefined;
+        }
+    }
+    registerTool(handler, providerId) {
+        const effectiveProvider = providerId || handler.definition.providerId || 'builtin';
+        const toolName = handler.definition.name;
+        const qualifiedName = `${effectiveProvider}/${toolName}`;
+        this.providerTools.set(qualifiedName, handler);
+        this.toolRegistry.set(qualifiedName, handler);
+        if (!this.toolRegistry.has(toolName)) {
+            this.toolRegistry.set(toolName, handler);
+        }
+        else {
+            const existing = this.toolRegistry.get(toolName);
+            if (existing && existing !== handler) {
+                this.toolRegistry.delete(toolName);
+            }
+        }
+    }
+    unregisterTool(toolIdentifier) {
+        const deleted1 = this.toolRegistry.delete(toolIdentifier);
+        const deleted2 = this.providerTools.delete(toolIdentifier);
+        return deleted1 || deleted2;
+    }
+    async listTools() {
+        if (!this.initialized && this.mcpProviders.size > 0) {
+            await this.initialize();
+        }
+        return Array.from(this.providerTools.values()).map((handler) => handler.definition);
+    }
+    findHandler(toolIdentifier) {
+        return this.toolRegistry.get(toolIdentifier) || this.providerTools.get(toolIdentifier);
+    }
+    async executeAction(action, authorization, options) {
+        const startTime = Date.now();
+        const actionId = action?.actionId || 'unknown';
+        const toolName = action?.toolName || 'unknown';
+        // 1. Mandatory Authorization Capability Verification
+        if (!authorization) {
+            return {
+                actionId,
+                executionId: 'unauthorized',
+                toolName,
+                lifecycle: 'REJECTED',
+                success: false,
+                error: 'Execution rejected: Missing mandatory AuthorizationCapability from policy engine',
+                durationMs: Date.now() - startTime,
+            };
+        }
+        if (authorization.allowed !== true) {
+            return {
+                actionId,
+                executionId: authorization.executionId || 'unauthorized',
+                toolName,
+                lifecycle: 'REJECTED',
+                success: false,
+                error: 'Execution rejected: AuthorizationCapability is not allowed',
+                durationMs: Date.now() - startTime,
+            };
+        }
+        // Cryptographic Signature check
+        const isSignatureValid = (0, core_1.verifyCapabilitySignature)(authorization, this.secretKey);
+        if (!isSignatureValid) {
+            return {
+                actionId,
+                executionId: authorization.executionId || 'invalid_sig',
+                toolName,
+                lifecycle: 'REJECTED',
+                success: false,
+                error: 'Execution rejected: Invalid or forged AuthorizationCapability signature',
+                durationMs: Date.now() - startTime,
+            };
+        }
+        // Expiry check
+        if (authorization.expiresAt && new Date(authorization.expiresAt).getTime() <= Date.now()) {
+            return {
+                actionId,
+                executionId: authorization.executionId,
+                toolName,
+                lifecycle: 'REJECTED',
+                success: false,
+                error: 'Execution rejected: AuthorizationCapability has expired',
+                durationMs: Date.now() - startTime,
+            };
+        }
+        // Structural binding verification
+        if (authorization.actionId !== action.actionId) {
+            return {
+                actionId,
+                executionId: authorization.executionId,
+                toolName,
+                lifecycle: 'REJECTED',
+                success: false,
+                error: `Execution rejected: ActionId mismatch (authorized: "${authorization.actionId}", action: "${action.actionId}")`,
+                durationMs: Date.now() - startTime,
+            };
+        }
+        if (authorization.toolName !== action.toolName) {
+            return {
+                actionId,
+                executionId: authorization.executionId,
+                toolName,
+                lifecycle: 'REJECTED',
+                success: false,
+                error: `Execution rejected: ToolName mismatch (authorized: "${authorization.toolName}", action: "${action.toolName}")`,
+                durationMs: Date.now() - startTime,
+            };
+        }
+        const currentParamsHash = (0, core_1.computeParametersHash)(action.parameters);
+        if (authorization.parametersHash !== currentParamsHash) {
+            return {
+                actionId,
+                executionId: authorization.executionId,
+                toolName,
+                lifecycle: 'REJECTED',
+                success: false,
+                error: 'Execution rejected: Parameters hash mismatch between intent and authorization',
+                durationMs: Date.now() - startTime,
+            };
+        }
+        const executionId = authorization.executionId;
+        // 2. Concurrency-Safe Persistent Idempotency Reservation
+        const existingExecution = await this.store.getExecution(executionId);
+        if (existingExecution) {
+            if (existingExecution.lifecycle === 'COMPLETED') {
+                return {
+                    actionId,
+                    executionId,
+                    toolName,
+                    lifecycle: 'COMPLETED',
+                    success: true,
+                    result: existingExecution.result,
+                    durationMs: Date.now() - startTime,
+                };
+            }
+            else if (existingExecution.lifecycle === 'EXECUTING') {
+                return {
+                    actionId,
+                    executionId,
+                    toolName,
+                    lifecycle: 'FAILED',
+                    success: false,
+                    error: 'Concurrent execution already in progress for this executionId',
+                    durationMs: Date.now() - startTime,
+                };
+            }
+        }
+        const reservationSuccess = await this.store.reserveExecution({
+            executionId,
+            actionId,
+            toolName,
+            providerId: authorization.providerId,
+            parametersHash: currentParamsHash,
+            lifecycle: 'EXECUTING',
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+        });
+        if (!reservationSuccess) {
+            return {
+                actionId,
+                executionId,
+                toolName,
+                lifecycle: 'FAILED',
+                success: false,
+                error: 'Concurrent execution reservation conflict for executionId',
+                durationMs: Date.now() - startTime,
+            };
+        }
+        // Ensure initialization if needed before tool lookup
+        if (!this.initialized && this.mcpProviders.size > 0) {
+            await this.initialize();
+        }
+        // 3. Tool Lookup
+        const handler = this.findHandler(action.toolName);
+        if (!handler) {
+            const notFoundResult = {
+                actionId,
+                executionId,
+                toolName,
+                lifecycle: 'FAILED',
+                success: false,
+                error: `Tool "${action.toolName}" is not registered in Hands organ`,
+                durationMs: Date.now() - startTime,
+            };
+            await this.store.updateExecution({
+                executionId,
+                actionId,
+                toolName,
+                providerId: authorization.providerId,
+                parametersHash: currentParamsHash,
+                lifecycle: 'FAILED',
+                error: notFoundResult.error,
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+            });
+            return notFoundResult;
+        }
+        // 4. Recursive Input Schema Validation
+        const schemaValidation = (0, schema_validator_1.validateInputSchema)(handler.definition.inputSchema, action.parameters);
+        if (!schemaValidation.valid) {
+            const validationFailedResult = {
+                actionId,
+                executionId,
+                toolName,
+                lifecycle: 'REJECTED',
+                success: false,
+                error: `Parameter schema validation failed: ${schemaValidation.errors.join('; ')}`,
+                durationMs: Date.now() - startTime,
+            };
+            await this.store.updateExecution({
+                executionId,
+                actionId,
+                toolName,
+                providerId: authorization.providerId,
+                parametersHash: currentParamsHash,
+                lifecycle: 'REJECTED',
+                error: validationFailedResult.error,
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+            });
+            return validationFailedResult;
+        }
+        // 5. Execution with Timeout and Cancellation
+        const timeoutMs = options?.timeoutMs || handler.definition.timeoutMs || this.defaultTimeoutMs;
+        const controller = new AbortController();
+        if (options?.signal) {
+            if (options.signal.aborted) {
+                controller.abort(options.signal.reason);
+            }
+            else {
+                options.signal.addEventListener('abort', () => controller.abort(options.signal?.reason), { once: true });
+            }
+        }
+        const effectiveSignal = controller.signal;
+        let timeoutHandle;
+        const timeoutPromise = new Promise((_, reject) => {
+            timeoutHandle = setTimeout(() => {
+                controller.abort();
+                const err = new Error(`Tool execution timed out after ${timeoutMs}ms`);
+                err.isTimeout = true;
+                reject(err);
+            }, timeoutMs);
+        });
+        try {
+            const executionPromise = handler.execute(action.parameters, effectiveSignal);
+            const result = await Promise.race([executionPromise, timeoutPromise]);
+            clearTimeout(timeoutHandle);
+            const completedResult = {
+                actionId,
+                executionId,
+                toolName,
+                lifecycle: 'COMPLETED',
+                success: true,
+                result,
+                durationMs: Date.now() - startTime,
+            };
+            await this.store.updateExecution({
+                executionId,
+                actionId,
+                toolName,
+                providerId: authorization.providerId,
+                parametersHash: currentParamsHash,
+                lifecycle: 'COMPLETED',
+                result,
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+            });
+            return completedResult;
+        }
+        catch (err) {
+            clearTimeout(timeoutHandle);
+            const isTimeout = err?.isTimeout || err?.name === 'AbortError' || err?.message?.includes('timed out');
+            const lifecycleState = isTimeout
+                ? 'TIMED_OUT'
+                : effectiveSignal.aborted
+                    ? 'CANCELLED'
+                    : 'FAILED';
+            const failedResult = {
+                actionId,
+                executionId,
+                toolName,
+                lifecycle: lifecycleState,
+                success: false,
+                error: err?.message || 'Tool execution failed',
+                durationMs: Date.now() - startTime,
+            };
+            await this.store.updateExecution({
+                executionId,
+                actionId,
+                toolName,
+                providerId: authorization.providerId,
+                parametersHash: currentParamsHash,
+                lifecycle: lifecycleState,
+                error: failedResult.error,
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+            });
+            return failedResult;
+        }
+    }
+    async close() {
+        for (const provider of this.mcpProviders.values()) {
+            await provider.disconnect();
+        }
+        this.mcpProviders.clear();
+        this.toolRegistry.clear();
+        this.providerTools.clear();
+        this.initialized = false;
+    }
+}
+exports.DefaultHandsOrgan = DefaultHandsOrgan;
+function probeHandsHealth(context) {
+    const secret = context?.config?.secretKey || (context?.env !== undefined ? context.env.ACTION_POLICY_SECRET : process.env.ACTION_POLICY_SECRET);
+    if (!secret && process.env.NODE_ENV === 'production') {
+        return {
+            ok: false,
+            message: 'Missing ACTION_POLICY_SECRET in production environment.',
+        };
+    }
+    return { ok: true, message: 'Hands organ configured and operational' };
+}
+__exportStar(require("./schema-validator"), exports);
+__exportStar(require("./mcp-provider"), exports);

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};