@sidurijs/hands 1.0.0

package/dist/index.test.js

@@ -0,0 +1,407 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+const core_1 = require("@sidurijs/core");
+describe('DefaultHandsOrgan Adversarial Remediation Suite', () => {
+    const secretKey = 'test_hands_secret';
+    let engine;
+    let sampleContext;
+    beforeEach(() => {
+        engine = new core_1.ActionPolicyEngine({
+            secretKey,
+            defaultRiskLevel: 'LOW',
+        });
+        sampleContext = {
+            companionId: 'comp-1',
+            actor: {
+                actorId: 'user-1',
+                sessionId: 'sess-1',
+                authorizationRole: 'operator',
+                capabilities: ['tool:calc', 'tool:search', 'tool:complex'],
+                authenticated: true,
+            },
+            conversation: {
+                channel: 'direct',
+                correlationId: 'corr-1',
+            },
+        };
+    });
+    describe('P0 — Elimination of Hands Authorization Bypass', () => {
+        it('rejects execution when authorization is missing or undefined', async () => {
+            let executed = false;
+            const hands = new index_1.DefaultHandsOrgan({ secretKey });
+            hands.registerTool({
+                definition: { name: 'calc', inputSchema: {}, description: 'calc' },
+                execute: async () => { executed = true; return 42; },
+            });
+            const res = await hands.executeAction({ actionId: 'act-1', toolName: 'calc', parameters: {} }, undefined);
+            expect(res.success).toBe(false);
+            expect(res.lifecycle).toBe('REJECTED');
+            expect(res.error).toContain('Missing mandatory AuthorizationCapability');
+            expect(executed).toBe(false);
+        });
+        it('rejects forged { allowed: true } without valid policy signature', async () => {
+            let executed = false;
+            const hands = new index_1.DefaultHandsOrgan({ secretKey });
+            hands.registerTool({
+                definition: { name: 'admin_tool', inputSchema: {}, description: 'admin' },
+                execute: async () => { executed = true; return 'pwned'; },
+            });
+            const forgedCapability = {
+                executionId: 'exec-forged',
+                actionId: 'act-forged',
+                toolName: 'admin_tool',
+                providerId: 'builtin',
+                parametersHash: 'h_forged',
+                companionId: 'comp-1',
+                riskLevel: 'LOW',
+                issuedAt: new Date().toISOString(),
+                expiresAt: new Date(Date.now() + 60000).toISOString(),
+                allowed: true,
+                signature: 'fake_forged_sig',
+            };
+            const res = await hands.executeAction({ actionId: 'act-forged', toolName: 'admin_tool', parameters: {} }, forgedCapability);
+            expect(res.success).toBe(false);
+            expect(res.lifecycle).toBe('REJECTED');
+            expect(res.error).toContain('Invalid or forged AuthorizationCapability signature');
+            expect(executed).toBe(false);
+        });
+        it('rejects authorization with mismatched actionId, toolName, or parameter hash', async () => {
+            const hands = new index_1.DefaultHandsOrgan({ secretKey });
+            hands.registerTool({
+                definition: { name: 'search', inputSchema: {}, description: 'search' },
+                execute: async () => ({ results: [] }),
+            });
+            engine.registerToolDefinition({ name: 'search', inputSchema: {}, description: 'search', riskLevel: 'LOW' });
+            // Generate authentic capability for parameters { q: 'foo' }
+            const { capability } = await engine.evaluateAction({
+                actionId: 'act-auth-1',
+                toolName: 'search',
+                parameters: { q: 'foo' },
+                context: sampleContext,
+            });
+            expect(capability).toBeDefined();
+            // Attack: Mismatched parameters (tampered from 'foo' to 'malicious')
+            const tamperedRes = await hands.executeAction({ actionId: 'act-auth-1', toolName: 'search', parameters: { q: 'malicious' } }, capability);
+            expect(tamperedRes.success).toBe(false);
+            expect(tamperedRes.lifecycle).toBe('REJECTED');
+            expect(tamperedRes.error).toContain('Parameters hash mismatch');
+            // Attack: Mismatched actionId
+            const mismatchedActionRes = await hands.executeAction({ actionId: 'act-different-id', toolName: 'search', parameters: { q: 'foo' } }, capability);
+            expect(mismatchedActionRes.success).toBe(false);
+            expect(mismatchedActionRes.error).toContain('ActionId mismatch');
+        });
+        it('executes when authentic policy-issued AuthorizationCapability is presented', async () => {
+            let executed = false;
+            const hands = new index_1.DefaultHandsOrgan({ secretKey });
+            hands.registerTool({
+                definition: { name: 'search', inputSchema: {}, description: 'search' },
+                execute: async (p) => { executed = true; return { ok: true, query: p.q }; },
+            });
+            engine.registerToolDefinition({ name: 'search', inputSchema: {}, description: 'search', riskLevel: 'LOW' });
+            const action = {
+                actionId: 'act-legit-1',
+                toolName: 'search',
+                parameters: { q: 'hello' },
+                context: sampleContext,
+            };
+            const { capability } = await engine.evaluateAction(action);
+            expect(capability).toBeDefined();
+            const res = await hands.executeAction(action, capability);
+            expect(res.success).toBe(true);
+            expect(res.lifecycle).toBe('COMPLETED');
+            expect(executed).toBe(true);
+            expect(res.result.query).toBe('hello');
+        });
+        it('rejects tampered companionId, executionId, expiresAt, and cross-companion capability reuse', async () => {
+            const hands = new index_1.DefaultHandsOrgan({ secretKey });
+            hands.registerTool({
+                definition: { name: 'search', inputSchema: {}, description: 'search' },
+                execute: async () => ({ results: [] }),
+            });
+            engine.registerToolDefinition({ name: 'search', inputSchema: {}, description: 'search', riskLevel: 'LOW' });
+            const action = {
+                actionId: 'act-tamper-1',
+                toolName: 'search',
+                parameters: { q: 'secure' },
+                context: sampleContext,
+            };
+            const { capability } = await engine.evaluateAction(action);
+            expect(capability).toBeDefined();
+            // Tamper companionId
+            const tamperedCompanionCap = { ...capability, companionId: 'attacker-companion' };
+            const compRes = await hands.executeAction(action, tamperedCompanionCap);
+            expect(compRes.success).toBe(false);
+            expect(compRes.error).toContain('Invalid or forged AuthorizationCapability signature');
+            // Tamper executionId
+            const tamperedExecCap = { ...capability, executionId: 'exec-hijacked' };
+            const execRes = await hands.executeAction(action, tamperedExecCap);
+            expect(execRes.success).toBe(false);
+            expect(execRes.error).toContain('Invalid or forged AuthorizationCapability signature');
+            // Expired capability
+            const expiredCap = { ...capability, expiresAt: new Date(Date.now() - 1000).toISOString() };
+            const expRes = await hands.executeAction(action, expiredCap);
+            expect(expRes.success).toBe(false);
+            expect(expRes.error).toContain('Invalid or forged AuthorizationCapability signature');
+        });
+    });
+    describe('P1 — Recursive Schema Validation & Prototype Pollution Defense', () => {
+        let hands;
+        beforeEach(() => {
+            hands = new index_1.DefaultHandsOrgan({ secretKey });
+            hands.registerTool({
+                definition: {
+                    name: 'update_user',
+                    description: 'Update user',
+                    inputSchema: {
+                        type: 'object',
+                        required: ['user'],
+                        properties: {
+                            user: {
+                                type: 'object',
+                                required: ['id', 'role'],
+                                properties: {
+                                    id: { type: 'number' },
+                                    role: { type: 'string', enum: ['admin', 'operator', 'owner'] },
+                                },
+                            },
+                            tags: {
+                                type: 'array',
+                                items: {
+                                    type: 'object',
+                                    required: ['tagId'],
+                                    properties: {
+                                        tagId: { type: 'number' },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+                execute: async (p) => p,
+            });
+            engine.registerToolDefinition({
+                name: 'update_user',
+                description: 'Update user',
+                inputSchema: {},
+                riskLevel: 'LOW',
+            });
+        });
+        it('rejects invalid nested object types and missing nested required fields', async () => {
+            const invalidAction = {
+                actionId: 'act-nest-1',
+                toolName: 'update_user',
+                parameters: {
+                    user: { id: 'not-a-number', role: 'admin' }, // id should be number
+                },
+                context: sampleContext,
+            };
+            const { capability } = await engine.evaluateAction(invalidAction);
+            const res = await hands.executeAction(invalidAction, capability);
+            expect(res.success).toBe(false);
+            expect(res.lifecycle).toBe('REJECTED');
+            expect(res.error).toContain('user.id');
+            expect(res.error).toContain('expected type number');
+        });
+        it('rejects invalid array item types at specific index paths', async () => {
+            const invalidArrayAction = {
+                actionId: 'act-arr-1',
+                toolName: 'update_user',
+                parameters: {
+                    user: { id: 100, role: 'owner' },
+                    tags: [
+                        { tagId: 1 },
+                        { tagId: 'invalid-tag-id' }, // index 1 is invalid
+                    ],
+                },
+                context: sampleContext,
+            };
+            const { capability } = await engine.evaluateAction(invalidArrayAction);
+            const res = await hands.executeAction(invalidArrayAction, capability);
+            expect(res.success).toBe(false);
+            expect(res.lifecycle).toBe('REJECTED');
+            expect(res.error).toContain('tags[1].tagId');
+        });
+        it('detects and rejects prototype pollution attempts (__proto__, constructor, prototype)', async () => {
+            const parsedProtoPayload = JSON.parse('{"user":{"id":1,"role":"admin"},"__proto__":{"isAdmin":true}}');
+            const protoPollutionAction = {
+                actionId: 'act-proto-1',
+                toolName: 'update_user',
+                parameters: parsedProtoPayload,
+                context: sampleContext,
+            };
+            const { capability } = await engine.evaluateAction(protoPollutionAction);
+            const res = await hands.executeAction(protoPollutionAction, capability);
+            expect(res.success).toBe(false);
+            expect(res.lifecycle).toBe('REJECTED');
+            expect(res.error).toContain('Forbidden prototype pollution key "__proto__"');
+        });
+    });
+    describe('P1 — Idempotency and Concurrency Reservation', () => {
+        it('prevents concurrent duplicate execution with reservation conflict', async () => {
+            let resolveSlowTool;
+            const slowExecutionPromise = new Promise((r) => { resolveSlowTool = r; });
+            const hands = new index_1.DefaultHandsOrgan({ secretKey });
+            hands.registerTool({
+                definition: { name: 'long_task', inputSchema: {}, description: 'long task' },
+                execute: async () => slowExecutionPromise,
+            });
+            engine.registerToolDefinition({ name: 'long_task', inputSchema: {}, description: 'long task', riskLevel: 'LOW' });
+            const action = {
+                actionId: 'act-race-1',
+                toolName: 'long_task',
+                parameters: {},
+                context: sampleContext,
+                executionId: 'exec-concurrent-test-99',
+            };
+            const { capability } = await engine.evaluateAction(action);
+            // Start first execution (which stays EXECUTING)
+            const firstPromise = hands.executeAction(action, capability);
+            // Concurrently start second execution with same executionId
+            const secondRes = await hands.executeAction(action, capability);
+            expect(secondRes.success).toBe(false);
+            expect(secondRes.error).toContain('Concurrent execution');
+            // Finish first execution
+            resolveSlowTool({ done: true });
+            const firstRes = await firstPromise;
+            expect(firstRes.success).toBe(true);
+            expect(firstRes.lifecycle).toBe('COMPLETED');
+        });
+        it('deduplicates/returns cached result on replay of completed executionId', async () => {
+            let runCount = 0;
+            const hands = new index_1.DefaultHandsOrgan({ secretKey });
+            hands.registerTool({
+                definition: { name: 'idempotent_task', inputSchema: {}, description: 'idempotent' },
+                execute: async () => { runCount++; return { runCount, status: 'done' }; },
+            });
+            engine.registerToolDefinition({ name: 'idempotent_task', inputSchema: {}, description: 'idempotent', riskLevel: 'LOW' });
+            const action = {
+                actionId: 'act-idem-1',
+                toolName: 'idempotent_task',
+                parameters: { data: 'test' },
+                context: sampleContext,
+                executionId: 'exec-replay-test-101',
+            };
+            const { capability } = await engine.evaluateAction(action);
+            // First run
+            const res1 = await hands.executeAction(action, capability);
+            expect(res1.success).toBe(true);
+            expect(res1.lifecycle).toBe('COMPLETED');
+            expect(runCount).toBe(1);
+            // Replay run with identical capability
+            const res2 = await hands.executeAction(action, capability);
+            expect(res2.success).toBe(true);
+            expect(res2.lifecycle).toBe('COMPLETED');
+            expect(runCount).toBe(1); // Did not re-execute side effect!
+            expect(res2.result.status).toBe('done');
+        });
+        it('cancels the execution when timeout occurs even if caller supplies an external AbortSignal', async () => {
+            let abortedSignal = false;
+            const hands = new index_1.DefaultHandsOrgan({ secretKey });
+            hands.registerTool({
+                definition: { name: 'slow_task', inputSchema: {}, description: 'slow task', timeoutMs: 50 },
+                execute: async (_, signal) => {
+                    return new Promise((resolve, reject) => {
+                        signal?.addEventListener('abort', () => {
+                            abortedSignal = true;
+                            const err = new Error('aborted');
+                            err.name = 'AbortError';
+                            reject(err);
+                        });
+                    });
+                },
+            });
+            engine.registerToolDefinition({ name: 'slow_task', inputSchema: {}, description: 'slow task', riskLevel: 'LOW' });
+            const action = {
+                actionId: 'act-timeout-signal',
+                toolName: 'slow_task',
+                parameters: {},
+                context: sampleContext,
+                executionId: 'exec-timeout-signal-1',
+            };
+            const { capability } = await engine.evaluateAction(action);
+            const externalController = new AbortController();
+            const res = await hands.executeAction(action, capability, {
+                signal: externalController.signal,
+                timeoutMs: 30,
+            });
+            expect(res.success).toBe(false);
+            expect(res.lifecycle).toBe('TIMED_OUT');
+            expect(abortedSignal).toBe(true);
+        });
+        it('registers and executes audited Life DB tools with signed capability', async () => {
+            const mockKnowledge = {
+                entities: {
+                    saveEntity: jest.fn(async (ent) => ent),
+                },
+                events: {
+                    addEvent: jest.fn(async (ev) => ev),
+                },
+                schedule: {
+                    saveItem: jest.fn(async (sch) => sch),
+                },
+                tasks: {
+                    saveTask: jest.fn(async (tsk) => tsk),
+                },
+            };
+            const hands = new index_1.DefaultHandsOrgan({ secretKey, knowledge: mockKnowledge });
+            const tools = await hands.listTools();
+            expect(tools.length).toBeGreaterThanOrEqual(4);
+            for (const t of tools) {
+                engine.registerToolDefinition(t);
+            }
+            // Execute life:save_entity
+            const saveAction = {
+                actionId: 'act-save-ent-1',
+                toolName: 'life:save_entity',
+                parameters: {
+                    name: 'MacBook Pro',
+                    entityType: 'hardware',
+                    domain: 'workstation',
+                    properties: { ram: '64GB' },
+                },
+                context: sampleContext,
+                executionId: 'exec-save-ent-1',
+            };
+            const { capability: cap1 } = await engine.evaluateAction(saveAction);
+            expect(cap1).toBeDefined();
+            const res1 = await hands.executeAction(saveAction, cap1);
+            expect(res1.success).toBe(true);
+            expect(res1.lifecycle).toBe('COMPLETED');
+            expect(mockKnowledge.entities.saveEntity).toHaveBeenCalledTimes(1);
+            // Execute life:log_event
+            const logAction = {
+                actionId: 'act-log-evt-1',
+                toolName: 'life:log_event',
+                parameters: {
+                    stream: 'workout',
+                    metricValue: 10,
+                    metadata: { unit: 'km' },
+                },
+                context: sampleContext,
+                executionId: 'exec-log-evt-1',
+            };
+            const { capability: cap2 } = await engine.evaluateAction(logAction);
+            const res2 = await hands.executeAction(logAction, cap2);
+            expect(res2.success).toBe(true);
+            expect(res2.lifecycle).toBe('COMPLETED');
+            expect(mockKnowledge.events.addEvent).toHaveBeenCalledTimes(1);
+            // Execute life:update_task
+            const taskAction = {
+                actionId: 'act-task-1',
+                toolName: 'life:update_task',
+                parameters: {
+                    title: 'Implement Life DB Primitives',
+                    status: 'completed',
+                },
+                context: sampleContext,
+                executionId: 'exec-task-1',
+            };
+            const { capability: cap3 } = await engine.evaluateAction(taskAction);
+            const res3 = await hands.executeAction(taskAction, cap3);
+            expect(res3.success).toBe(true);
+            expect(res3.lifecycle).toBe('COMPLETED');
+            expect(mockKnowledge.tasks.saveTask).toHaveBeenCalledTimes(1);
+        });
+    });
+});

package/dist/life-tools.d.ts

@@ -0,0 +1,9 @@
+import { ToolHandler } from './index';
+export interface LifeToolsOptions {
+    companionId?: string;
+}
+/**
+ * Creates audited action tool handlers for mutating the sovereign Life Database
+ * in accordance with Siduri-X Action Policy and Truth Gate governance.
+ */
+export declare function createLifeTools(knowledge: any, options?: LifeToolsOptions): ToolHandler[];

package/dist/life-tools.js

@@ -0,0 +1,216 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLifeTools = createLifeTools;
+/**
+ * Creates audited action tool handlers for mutating the sovereign Life Database
+ * in accordance with Siduri-X Action Policy and Truth Gate governance.
+ */
+function createLifeTools(knowledge, options = {}) {
+    const getCompId = (params) => {
+        return params.companionId || options.companionId || 'default';
+    };
+    const handlers = [];
+    // 1. life:save_entity
+    const saveEntityDef = {
+        name: 'life:save_entity',
+        providerId: 'life',
+        description: 'Create or update an entity (item, contact, place, preference, hardware) in the sovereign Life DB',
+        riskLevel: 'LOW',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Optional unique entity ID' },
+                companionId: { type: 'string', description: 'Optional companion ID' },
+                name: { type: 'string', description: 'Entity name' },
+                entityType: { type: 'string', description: 'Entity type (e.g. inventory, contact, place, hardware)' },
+                domain: { type: 'string', description: 'Domain (e.g. gaming, work, personal, social)' },
+                properties: { type: 'object', description: 'Arbitrary entity properties/metadata' },
+            },
+            required: ['name'],
+        },
+    };
+    const saveEntityHandler = {
+        definition: saveEntityDef,
+        execute: async (parameters, _signal) => {
+            const compId = getCompId(parameters);
+            const name = String(parameters.name || 'Unnamed');
+            const entityType = String(parameters.entityType || 'entity');
+            const domain = String(parameters.domain || 'general');
+            const properties = parameters.properties || {};
+            const id = parameters.id || `ent-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+            if (knowledge.entities && typeof knowledge.entities.saveEntity === 'function') {
+                await knowledge.entities.saveEntity({
+                    id,
+                    companionId: compId,
+                    entityType,
+                    domain,
+                    name,
+                    properties,
+                    updatedAt: new Date().toISOString(),
+                });
+                return { success: true, id, entityType, name, domain };
+            }
+            else if (knowledge.inventory && typeof knowledge.inventory.saveItem === 'function') {
+                await knowledge.inventory.saveItem({
+                    id,
+                    companionId: compId,
+                    domain,
+                    entityName: name,
+                    properties,
+                    updatedAt: new Date().toISOString(),
+                });
+                return { success: true, id, name, domain };
+            }
+            throw new Error('Knowledge organ does not support saving entities or inventory');
+        },
+    };
+    handlers.push(saveEntityHandler);
+    // 2. life:log_event
+    const logEventDef = {
+        name: 'life:log_event',
+        providerId: 'life',
+        description: 'Log an event or metric to the sovereign Life DB time-series stream (finance, health, workout, habit)',
+        riskLevel: 'LOW',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Optional unique event ID' },
+                companionId: { type: 'string', description: 'Optional companion ID' },
+                stream: { type: 'string', description: 'Event stream name (finance, health, workout, habit, sleep)' },
+                metricValue: { type: 'number', description: 'Numerical metric (dollar amount, duration, weight, distance)' },
+                metadata: { type: 'object', description: 'Context metadata (category, currency, unit, notes)' },
+            },
+            required: ['stream'],
+        },
+    };
+    const logEventHandler = {
+        definition: logEventDef,
+        execute: async (parameters, _signal) => {
+            const compId = getCompId(parameters);
+            const stream = String(parameters.stream || 'telemetry');
+            const metricValue = typeof parameters.metricValue === 'number' ? parameters.metricValue : undefined;
+            const metadata = parameters.metadata || {};
+            const id = parameters.id || `evt-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+            const timestamp = parameters.timestamp || new Date().toISOString();
+            if (knowledge.events && typeof knowledge.events.addEvent === 'function') {
+                await knowledge.events.addEvent({
+                    id,
+                    companionId: compId,
+                    stream,
+                    timestamp,
+                    metricValue,
+                    metadata,
+                });
+                return { success: true, id, stream, metricValue, timestamp };
+            }
+            else if (stream === 'finance' && knowledge.finance && typeof knowledge.finance.addEntry === 'function') {
+                await knowledge.finance.addEntry({
+                    id,
+                    companionId: compId,
+                    category: metadata.category || 'general',
+                    amount: metricValue || 0,
+                    currency: metadata.currency || 'USD',
+                    timestamp,
+                    metadata,
+                });
+                return { success: true, id, stream: 'finance', amount: metricValue };
+            }
+            throw new Error('Knowledge organ does not support event logging');
+        },
+    };
+    handlers.push(logEventHandler);
+    // 3. life:upsert_schedule
+    const upsertScheduleDef = {
+        name: 'life:upsert_schedule',
+        providerId: 'life',
+        description: 'Add or update a schedule event or commitment in the sovereign Life DB',
+        riskLevel: 'LOW',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Optional unique schedule item ID' },
+                companionId: { type: 'string', description: 'Optional companion ID' },
+                title: { type: 'string', description: 'Event title' },
+                startTime: { type: 'string', description: 'Start time in ISO format' },
+                endTime: { type: 'string', description: 'Optional end time in ISO format' },
+                isRecurring: { type: 'boolean', description: 'Whether the event recurs' },
+                status: { type: 'string', description: 'Status (e.g. active, completed, cancelled)' },
+            },
+            required: ['title', 'startTime'],
+        },
+    };
+    const upsertScheduleHandler = {
+        definition: upsertScheduleDef,
+        execute: async (parameters, _signal) => {
+            const compId = getCompId(parameters);
+            const title = String(parameters.title || 'Untitled Event');
+            const startTime = String(parameters.startTime || new Date().toISOString());
+            const endTime = parameters.endTime ? String(parameters.endTime) : undefined;
+            const isRecurring = Boolean(parameters.isRecurring);
+            const status = String(parameters.status || 'active');
+            const id = parameters.id || `sch-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+            if (knowledge.schedule && typeof knowledge.schedule.saveItem === 'function') {
+                await knowledge.schedule.saveItem({
+                    id,
+                    companionId: compId,
+                    title,
+                    startTime,
+                    endTime,
+                    isRecurring,
+                    status,
+                });
+                return { success: true, id, title, startTime, status };
+            }
+            throw new Error('Knowledge organ does not support schedule management');
+        },
+    };
+    handlers.push(upsertScheduleHandler);
+    // 4. life:update_task
+    const updateTaskDef = {
+        name: 'life:update_task',
+        providerId: 'life',
+        description: 'Add, update, or complete a task, to-do, or goal in the sovereign Life DB',
+        riskLevel: 'LOW',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Optional unique task ID' },
+                companionId: { type: 'string', description: 'Optional companion ID' },
+                title: { type: 'string', description: 'Task title or goal description' },
+                status: { type: 'string', description: 'Status (backlog, in_progress, completed, cancelled)' },
+                priority: { type: 'number', description: 'Priority rank' },
+                targetDate: { type: 'string', description: 'Optional target due date' },
+                metadata: { type: 'object', description: 'Optional metadata' },
+            },
+            required: ['title'],
+        },
+    };
+    const updateTaskHandler = {
+        definition: updateTaskDef,
+        execute: async (parameters, _signal) => {
+            const compId = getCompId(parameters);
+            const title = String(parameters.title || 'Untitled Task');
+            const status = String(parameters.status || 'backlog');
+            const priority = typeof parameters.priority === 'number' ? parameters.priority : 0;
+            const targetDate = parameters.targetDate ? String(parameters.targetDate) : undefined;
+            const metadata = parameters.metadata || undefined;
+            const id = parameters.id || `tsk-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`;
+            if (knowledge.tasks && typeof knowledge.tasks.saveTask === 'function') {
+                await knowledge.tasks.saveTask({
+                    id,
+                    companionId: compId,
+                    title,
+                    status,
+                    priority,
+                    targetDate,
+                    metadata,
+                    updatedAt: new Date().toISOString(),
+                });
+                return { success: true, id, title, status, priority };
+            }
+            throw new Error('Knowledge organ does not support task management');
+        },
+    };
+    handlers.push(updateTaskHandler);
+    return handlers;
+}

package/dist/mcp-integration.test.d.ts

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