twinclaw 1.1.1 → 1.1.2

package/dist/services/device-pairing.js

@@ -0,0 +1,378 @@
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { logThought } from '../utils/logger.js';
+const CODE_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+const CODE_LENGTH = 8;
+const DEFAULT_CODE_TTL_MS = 5 * 60 * 1000; // 5 minutes for device pairing
+const DEFAULT_MAX_PENDING = 5;
+const DEFAULT_CAPABILITIES = {
+    camera: false,
+    screen: false,
+    location: false,
+    commands: true,
+    notifications: true,
+    sensors: false,
+};
+/**
+ * Device pairing service for managing paired nodes/devices.
+ *
+ * Allows controlling paired devices for:
+ * - Camera capture
+ * - Screen capture
+ * - Location tracking
+ * - Command execution
+ * - Notifications
+ */
+export class DevicePairingService {
+    #credentialsDir;
+    #codeTtlMs;
+    #maxPending;
+    #devices = new Map();
+    #pendingRequests = new Map();
+    constructor(options = {}) {
+        this.#credentialsDir = options.credentialsDir
+            ? path.resolve(options.credentialsDir)
+            : path.resolve('memory', 'devices');
+        this.#codeTtlMs = options.codeTtlMs ?? DEFAULT_CODE_TTL_MS;
+        this.#maxPending = options.maxPendingPerChannel ?? DEFAULT_MAX_PENDING;
+        // Load existing devices
+        this.#loadDevices();
+    }
+    /**
+     * Generate a pairing request for a new device
+     */
+    requestPairing(deviceId, publicKey, platform, clientId, clientMode, displayName) {
+        // Check if device already paired
+        if (this.#devices.has(deviceId)) {
+            throw new Error(`Device ${deviceId} is already paired`);
+        }
+        // Check pending limit
+        if (this.#pendingRequests.size >= this.#maxPending) {
+            throw new Error('Maximum pending pairing requests reached');
+        }
+        // Generate code
+        const code = this.#generateCode();
+        const now = Date.now();
+        const expiresAt = new Date(now + this.#codeTtlMs).toISOString();
+        const request = {
+            deviceId,
+            displayName,
+            publicKey,
+            platform,
+            clientId,
+            clientMode,
+            requestedAt: new Date(now).toISOString(),
+            expiresAt,
+            code,
+        };
+        this.#pendingRequests.set(code, request);
+        this.#savePendingRequests();
+        return { code, expiresAt };
+    }
+    /**
+     * Approve a pairing request with the code
+     */
+    approve(code) {
+        const request = this.#pendingRequests.get(code.toUpperCase());
+        if (!request) {
+            throw new Error('Invalid or expired pairing code');
+        }
+        // Check if expired
+        if (Date.parse(request.expiresAt) < Date.now()) {
+            this.#pendingRequests.delete(code.toUpperCase());
+            this.#savePendingRequests();
+            throw new Error('Pairing code has expired');
+        }
+        // Determine roles and scopes based on client mode
+        const { roles, scopes, capabilities } = this.#deriveAccess(request);
+        // Create the device
+        const device = {
+            deviceId: request.deviceId,
+            displayName: request.displayName,
+            publicKey: request.publicKey,
+            platform: request.platform,
+            clientId: request.clientId,
+            clientMode: request.clientMode,
+            roles,
+            scopes,
+            capabilities,
+            status: 'paired',
+            pairedAt: new Date().toISOString(),
+            createdAt: new Date().toISOString(),
+        };
+        // Store and cleanup
+        this.#devices.set(device.deviceId, device);
+        this.#pendingRequests.delete(code.toUpperCase());
+        this.#saveDevices();
+        this.#savePendingRequests();
+        logThought(`[DevicePairing] Device ${device.deviceId} paired successfully`);
+        return device;
+    }
+    /**
+     * Derive roles, scopes, and capabilities from client mode
+     */
+    #deriveAccess(request) {
+        const clientMode = request.clientMode;
+        switch (clientMode) {
+            case 'webchat':
+                return {
+                    roles: ['operator'],
+                    scopes: ['operator.admin', 'operator.pairing'],
+                    capabilities: { ...DEFAULT_CAPABILITIES, commands: true },
+                };
+            case 'sensor':
+                return {
+                    roles: ['sensor'],
+                    scopes: ['sensor.read'],
+                    capabilities: {
+                        camera: true,
+                        location: true,
+                        sensors: true,
+                        notifications: false,
+                        commands: false,
+                        screen: false,
+                    },
+                };
+            case 'actuator':
+                return {
+                    roles: ['actuator'],
+                    scopes: ['actuator.execute'],
+                    capabilities: {
+                        commands: true,
+                        notifications: true,
+                        camera: false,
+                        location: false,
+                        sensors: false,
+                        screen: false,
+                    },
+                };
+            case 'backend':
+            default:
+                return {
+                    roles: ['controller'],
+                    scopes: ['controller.admin', 'controller.pairing', 'controller.execute'],
+                    capabilities: DEFAULT_CAPABILITIES,
+                };
+        }
+    }
+    /**
+     * Get a device by ID
+     */
+    get(deviceId) {
+        return this.#devices.get(deviceId);
+    }
+    /**
+     * List all paired devices
+     */
+    list() {
+        return Array.from(this.#devices.values());
+    }
+    /**
+     * List devices by status
+     */
+    listByStatus(status) {
+        return this.list().filter(d => d.status === status);
+    }
+    /**
+     * Update device status
+     */
+    updateStatus(deviceId, status) {
+        const device = this.#devices.get(deviceId);
+        if (!device)
+            return false;
+        device.status = status;
+        if (status === 'paired') {
+            device.lastSeenAt = new Date().toISOString();
+        }
+        this.#saveDevices();
+        return true;
+    }
+    /**
+     * Revoke a device pairing
+     */
+    revoke(deviceId) {
+        const device = this.#devices.get(deviceId);
+        if (!device)
+            return false;
+        device.status = 'revoked';
+        this.#saveDevices();
+        logThought(`[DevicePairing] Device ${deviceId} revoked`);
+        return true;
+    }
+    /**
+     * Execute a command on a device
+     */
+    async executeCommand(deviceId, command, args) {
+        const device = this.#devices.get(deviceId);
+        if (!device) {
+            return { success: false, error: 'Device not found' };
+        }
+        if (device.status !== 'paired') {
+            return { success: false, error: 'Device is not paired' };
+        }
+        if (!device.capabilities.commands) {
+            return { success: false, error: 'Device does not support command execution' };
+        }
+        // Check scope
+        if (!device.scopes.includes('controller.execute') && !device.scopes.includes('operator.admin')) {
+            return { success: false, error: 'Device does not have execute scope' };
+        }
+        // In a real implementation, this would send the command to the device
+        // via WebSocket, HTTP, or another mechanism
+        logThought(`[DevicePairing] Would execute command on ${deviceId}: ${command}`);
+        return {
+            success: true,
+            output: `Command ${command} would be executed on device ${device.displayName || deviceId}`,
+        };
+    }
+    /**
+     * Request camera capture from a device
+     */
+    async captureCamera(deviceId) {
+        const device = this.#devices.get(deviceId);
+        if (!device) {
+            return { success: false, error: 'Device not found' };
+        }
+        if (!device.capabilities.camera) {
+            return { success: false, error: 'Device does not have camera capability' };
+        }
+        logThought(`[DevicePairing] Would request camera capture from ${deviceId}`);
+        return {
+            success: true,
+            imageUrl: `Device ${device.displayName || deviceId} would capture and send image`,
+        };
+    }
+    /**
+     * Request screen capture from a device
+     */
+    async captureScreen(deviceId) {
+        const device = this.#devices.get(deviceId);
+        if (!device) {
+            return { success: false, error: 'Device not found' };
+        }
+        if (!device.capabilities.screen) {
+            return { success: false, error: 'Device does not have screen capture capability' };
+        }
+        logThought(`[DevicePairing] Would request screen capture from ${deviceId}`);
+        return {
+            success: true,
+            imageUrl: `Device ${device.displayName || deviceId} would capture and send screen`,
+        };
+    }
+    /**
+     * Request location from a device
+     */
+    async getLocation(deviceId) {
+        const device = this.#devices.get(deviceId);
+        if (!device) {
+            return { success: false, error: 'Device not found' };
+        }
+        if (!device.capabilities.location) {
+            return { success: false, error: 'Device does not have location capability' };
+        }
+        logThought(`[DevicePairing] Would request location from ${deviceId}`);
+        return {
+            success: true,
+            location: { lat: 0, lng: 0 }, // Placeholder
+        };
+    }
+    /**
+     * Generate a unique pairing code
+     */
+    #generateCode() {
+        const bytes = randomBytes(CODE_LENGTH);
+        let code = '';
+        for (let i = 0; i < CODE_LENGTH; i++) {
+            const index = bytes[i] % CODE_ALPHABET.length;
+            code += CODE_ALPHABET[index];
+        }
+        return code;
+    }
+    /**
+     * Load devices from disk
+     */
+    #loadDevices() {
+        try {
+            const filePath = path.join(this.#credentialsDir, 'paired.json');
+            if (!fs.existsSync(filePath))
+                return;
+            const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+            for (const [id, device] of Object.entries(data)) {
+                this.#devices.set(id, device);
+            }
+        }
+        catch (err) {
+            console.warn('[DevicePairing] Failed to load devices:', err);
+        }
+    }
+    /**
+     * Save devices to disk
+     */
+    #saveDevices() {
+        try {
+            const filePath = path.join(this.#credentialsDir, 'paired.json');
+            const dir = path.dirname(filePath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            const data = {};
+            for (const [id, device] of this.#devices) {
+                data[id] = device;
+            }
+            fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+        }
+        catch (err) {
+            console.error('[DevicePairing] Failed to save devices:', err);
+        }
+    }
+    /**
+     * Load pending requests from disk
+     */
+    #loadPendingRequests() {
+        try {
+            const filePath = path.join(this.#credentialsDir, 'pending.json');
+            if (!fs.existsSync(filePath))
+                return;
+            const data = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+            if (Array.isArray(data)) {
+                for (const request of data) {
+                    // Only load non-expired requests
+                    if (Date.parse(request.expiresAt) > Date.now()) {
+                        this.#pendingRequests.set(request.code, request);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            console.warn('[DevicePairing] Failed to load pending requests:', err);
+        }
+    }
+    /**
+     * Save pending requests to disk
+     */
+    #savePendingRequests() {
+        try {
+            const filePath = path.join(this.#credentialsDir, 'pending.json');
+            const dir = path.dirname(filePath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            const data = Array.from(this.#pendingRequests.values());
+            fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+        }
+        catch (err) {
+            console.error('[DevicePairing] Failed to save pending requests:', err);
+        }
+    }
+}
+let devicePairingServiceSingleton = null;
+export function getDevicePairingService() {
+    if (!devicePairingServiceSingleton) {
+        devicePairingServiceSingleton = new DevicePairingService();
+    }
+    return devicePairingServiceSingleton;
+}
+export function resetDevicePairingService() {
+    devicePairingServiceSingleton = null;
+}

package/dist/services/hooks.js

@@ -0,0 +1,130 @@
+import { readConfig } from '../config/json-config.js';
+import { logThought } from '../utils/logger.js';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import path from 'path';
+import { getWorkspaceDir } from '../config/workspace.js';
+class HooksService {
+    #hooks = new Map();
+    #workspaceDir = '';
+    async initialize() {
+        this.#workspaceDir = getWorkspaceDir();
+        try {
+            const config = await readConfig();
+            const hooksConfig = config.hooks || {};
+            for (const [eventName, entries] of Object.entries(hooksConfig)) {
+                const event = eventName;
+                if (Array.isArray(entries)) {
+                    this.#hooks.set(event, entries);
+                }
+            }
+            await this.#ensureHooksDir();
+            await this.runHook('boot', { event: 'boot', timestamp: new Date().toISOString() });
+            void logThought(`[Hooks] Initialized with ${this.#hooks.size} event types.`);
+        }
+        catch (err) {
+            console.warn('[Hooks] Failed to initialize hooks system:', err);
+        }
+    }
+    async #ensureHooksDir() {
+        const hooksDir = path.join(this.#workspaceDir, 'hooks');
+        if (!existsSync(hooksDir)) {
+            await mkdir(hooksDir, { recursive: true });
+        }
+        const bootScript = path.join(hooksDir, 'boot.md');
+        if (!existsSync(bootScript)) {
+            await writeFile(bootScript, '# TwinClaw Boot Hook\n\nWrite your boot initialization script here.\n', 'utf-8');
+        }
+    }
+    async runHook(event, context) {
+        const hooks = this.#hooks.get(event) || [];
+        const results = [];
+        for (const hook of hooks) {
+            if (!hook.enabled)
+                continue;
+            try {
+                let output;
+                if (hook.script) {
+                    output = await this.#runScript(hook.script, context);
+                }
+                else if (hook.command) {
+                    output = await this.#runCommand(hook.command, context);
+                }
+                results.push({ success: true, output });
+                void logThought(`[Hooks] Executed ${hook.name} for ${event}: ${output?.slice(0, 50) || 'no output'}`);
+            }
+            catch (err) {
+                const error = err instanceof Error ? err.message : String(err);
+                results.push({ success: false, error });
+                void logThought(`[Hooks] Hook ${hook.name} failed for ${event}: ${error}`);
+            }
+        }
+        return results;
+    }
+    async #runScript(scriptPath, context) {
+        const fullPath = path.isAbsolute(scriptPath)
+            ? scriptPath
+            : path.join(this.#workspaceDir, 'hooks', scriptPath);
+        const content = await readFile(fullPath, 'utf-8');
+        return content;
+    }
+    async #runCommand(command, context) {
+        const { exec } = await import('child_process');
+        return new Promise((resolve, reject) => {
+            const env = {
+                ...process.env,
+                TWINCLAW_EVENT: context.event,
+                TWINCLAW_TIMESTAMP: context.timestamp,
+                TWINCLAW_SESSION_ID: context.sessionId || '',
+            };
+            exec(command, { env }, (error, stdout, stderr) => {
+                if (error) {
+                    reject(new Error(stderr || error.message));
+                }
+                else {
+                    resolve(stdout);
+                }
+            });
+        });
+    }
+    async shutdown() {
+        await this.runHook('shutdown', { event: 'shutdown', timestamp: new Date().toISOString() });
+        void logThought('[Hooks] Shutdown complete.');
+    }
+    getHooks(event) {
+        return this.#hooks.get(event) || [];
+    }
+    async registerHook(event, hook) {
+        const hooks = this.#hooks.get(event) || [];
+        hooks.push(hook);
+        this.#hooks.set(event, hooks);
+    }
+    async unregisterHook(event, hookName) {
+        const hooks = this.#hooks.get(event) || [];
+        const filtered = hooks.filter(h => h.name !== hookName);
+        this.#hooks.set(event, filtered);
+    }
+    async toggleHook(event, hookName, enabled) {
+        const hooks = this.#hooks.get(event) || [];
+        const hook = hooks.find(h => h.name === hookName);
+        if (hook) {
+            hook.enabled = enabled;
+        }
+    }
+}
+let hooksService = null;
+export function getHooksService() {
+    if (!hooksService) {
+        hooksService = new HooksService();
+    }
+    return hooksService;
+}
+export async function initializeHooks() {
+    const service = getHooksService();
+    await service.initialize();
+}
+export async function shutdownHooks() {
+    if (hooksService) {
+        await hooksService.shutdown();
+    }
+}

package/dist/services/job-scheduler.js

@@ -1,10 +1,12 @@
 import cron from 'node-cron';
 import { logThought } from '../utils/logger.js';
+import fs from 'node:fs';
+import path from 'node:path';
 /**
  * Centralized job scheduler for TwinClaw's proactive execution layer.
  *
  * Wraps `node-cron` to manage multiple named, repeating background jobs
- * with event emission, error isolation, and runtime inspection.
+ * with event emission, error isolation, runtime inspection, and persistence.
  *
  * Usage:
  * ```ts
@@ -16,11 +18,21 @@ import { logThought } from '../utils/logger.js';
  *   handler: async () => { … },
  * });
  * scheduler.startAll();
+ *
+ * // Jobs are persisted to disk and restored on restart
  * ```
  */
 export class JobScheduler {
     #jobs = new Map();
     #listeners = new Map();
+    #persistencePath;
+    /**
+     * @param persistenceDir - Directory to store job persistence files
+     */
+    constructor(persistenceDir) {
+        this.#persistencePath = path.resolve(persistenceDir || './memory', 'scheduler-jobs.json');
+        this.#loadPersistedJobs();
+    }
     /** Register a new repeating job. Throws if a job with the same ID already exists. */
     register(config) {
         if (this.#jobs.has(config.id)) {
@@ -41,6 +53,8 @@ export class JobScheduler {
         if (autoStart) {
             this.#startJob(entry);
         }
+        // Persist job configuration
+        this.#persistJobs();
     }
     /** Unregister and stop a job by ID. */
     unregister(jobId) {
@@ -71,6 +85,14 @@ export class JobScheduler {
             entry.status = 'stopped';
         }
     }
+    /** Run a specific job immediately (outside of its cron schedule). */
+    async runNow(jobId) {
+        const entry = this.#jobs.get(jobId);
+        if (!entry) {
+            throw new Error(`[JobScheduler] Job '${jobId}' is not registered.`);
+        }
+        await this.#executeJob(entry);
+    }
     /** Start all registered jobs that are not currently running. */
     startAll() {
         for (const entry of this.#jobs.values()) {
@@ -130,6 +152,64 @@ export class JobScheduler {
             set?.delete(listener);
         };
     }
+    /**
+     * Schedule a one-time job to run after a delay (for reminders).
+     * @param id - Unique job identifier
+     * @param delayMs - Delay in milliseconds
+     * @param handler - Function to execute
+     * @param description - Optional description
+     */
+    scheduleOnce(id, delayMs, handler, description) {
+        if (this.#jobs.has(id)) {
+            throw new Error(`[JobScheduler] Job '${id}' is already registered.`);
+        }
+        // Convert to cron-like format for one-time execution
+        const entry = {
+            config: {
+                id,
+                cronExpression: 'once', // Special marker for one-time jobs
+                description: description || `One-time job: ${id}`,
+                handler,
+                autoStart: true,
+            },
+            task: null,
+            status: 'idle',
+            lastRunAt: null,
+            lastError: null,
+        };
+        this.#jobs.set(id, entry);
+        // Schedule the one-time execution
+        setTimeout(async () => {
+            entry.status = 'running';
+            this.#emit({ type: 'job:start', jobId: id, timestamp: new Date() });
+            try {
+                await handler();
+                entry.status = 'idle';
+                this.#emit({ type: 'job:done', jobId: id, timestamp: new Date() });
+            }
+            catch (err) {
+                entry.status = 'error';
+                entry.lastError = err instanceof Error ? err.message : String(err);
+                this.#emit({ type: 'job:error', jobId: id, timestamp: new Date(), error: entry.lastError });
+            }
+            // Remove one-time job after execution
+            this.#jobs.delete(id);
+            this.#persistJobs();
+        }, delayMs);
+        this.#persistJobs();
+    }
+    /**
+     * Schedule a reminder job (convenience method)
+     * @param id - Unique job identifier
+     * @param delayMs - Delay in milliseconds
+     * @param message - Reminder message to send
+     * @param onReminder - Callback to execute when reminder fires
+     */
+    scheduleReminder(id, delayMs, message, onReminder) {
+        this.scheduleOnce(id, delayMs, async () => {
+            await onReminder(message);
+        }, `Reminder: ${message}`);
+    }
     // ── Private Helpers ────────────────────────────────────────────────────────
     #startJob(entry) {
         if (entry.task)
@@ -139,6 +219,58 @@ export class JobScheduler {
         });
         entry.status = 'idle';
     }
+    /** Load persisted jobs from disk */
+    #loadPersistedJobs() {
+        try {
+            if (!fs.existsSync(this.#persistencePath)) {
+                return;
+            }
+            const data = fs.readFileSync(this.#persistencePath, 'utf8');
+            const persisted = JSON.parse(data);
+            if (!persisted.jobs || !Array.isArray(persisted.jobs)) {
+                return;
+            }
+            for (const job of persisted.jobs) {
+                // Only restore jobs that should auto-start
+                if (job.autoStart !== false) {
+                    // Recreate the job config (without handler)
+                    // Handlers need to be re-registered by the caller
+                    console.log(`[JobScheduler] Found persisted job: ${job.id}`);
+                }
+            }
+            logThought(`[JobScheduler] Loaded ${persisted.jobs?.length || 0} persisted jobs`);
+        }
+        catch (err) {
+            console.warn('[JobScheduler] Failed to load persisted jobs:', err);
+        }
+    }
+    /** Save jobs to disk */
+    #persistJobs() {
+        try {
+            const jobsData = Array.from(this.#jobs.values()).map(entry => ({
+                id: entry.config.id,
+                cronExpression: entry.config.cronExpression,
+                description: entry.config.description,
+                autoStart: entry.config.autoStart,
+                status: entry.status,
+                lastRunAt: entry.lastRunAt?.toISOString(),
+                lastError: entry.lastError,
+            }));
+            const data = {
+                version: 1,
+                savedAt: new Date().toISOString(),
+                jobs: jobsData,
+            };
+            const dir = path.dirname(this.#persistencePath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.writeFileSync(this.#persistencePath, JSON.stringify(data, null, 2));
+        }
+        catch (err) {
+            console.warn('[JobScheduler] Failed to persist jobs:', err);
+        }
+    }
     async #executeJob(entry) {
         const { config } = entry;
         entry.status = 'running';