lavs-runtime 0.1.0

package/dist/script-executor.js

@@ -0,0 +1,314 @@
+"use strict";
+/**
+ * LAVS Script Executor
+ *
+ * Executes script handlers with proper input/output handling and security.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScriptExecutor = void 0;
+const child_process_1 = require("child_process");
+const types_1 = require("./types");
+class ScriptExecutor {
+    /**
+     * Execute a script handler
+     * @param handler - Script handler configuration
+     * @param input - Input data to pass to script
+     * @param context - Execution context with permissions
+     * @returns Script output (parsed as JSON)
+     */
+    async execute(handler, input, context) {
+        const startTime = Date.now();
+        console.log(`[LAVS] Executing script for ${context.endpointId}`, {
+            command: handler.command,
+            args: handler.args,
+            input: handler.input,
+        });
+        try {
+            // 1. Prepare command and arguments
+            const { command, args = [] } = handler;
+            const resolvedArgs = this.resolveArgs(args, input);
+            // 2. Prepare environment variables
+            const processEnv = this.buildEnvironment(handler, input, context);
+            // 3. Determine timeout
+            const timeout = handler.timeout || context.timeout || 30000;
+            // 4. Spawn process
+            const proc = (0, child_process_1.spawn)(command, resolvedArgs, {
+                cwd: handler.cwd || context.workdir,
+                env: processEnv,
+                timeout,
+                stdio: ['pipe', 'pipe', 'pipe'], // stdin, stdout, stderr
+            });
+            // 5. Send input to stdin if needed
+            if (handler.input === 'stdin' && input) {
+                try {
+                    proc.stdin.write(JSON.stringify(input));
+                    proc.stdin.end();
+                }
+                catch (e) {
+                    console.error(`[LAVS] Failed to write to stdin:`, e);
+                }
+            }
+            // 6. Capture output and wait for completion
+            const result = await this.captureOutput(proc, timeout, context.endpointId);
+            const duration = Date.now() - startTime;
+            console.log(`[LAVS] Script completed in ${duration}ms`, {
+                endpointId: context.endpointId,
+                exitCode: result.exitCode,
+            });
+            // 7. Handle non-zero exit code
+            if (result.exitCode !== 0) {
+                throw new types_1.LAVSError(types_1.LAVSErrorCode.HandlerError, `Script exited with code ${result.exitCode}`, {
+                    exitCode: result.exitCode,
+                    stderr: result.stderr,
+                    stdout: result.stdout,
+                });
+            }
+            // 8. Parse output as JSON
+            return this.parseOutput(result.stdout, result.stderr);
+        }
+        catch (error) {
+            if (error instanceof types_1.LAVSError) {
+                throw error;
+            }
+            // Handle timeout
+            if (error.code === 'ETIMEDOUT' || error.killed) {
+                throw new types_1.LAVSError(types_1.LAVSErrorCode.Timeout, `Script execution timeout after ${handler.timeout || context.timeout || 30000}ms`);
+            }
+            // Handle spawn errors
+            throw new types_1.LAVSError(types_1.LAVSErrorCode.HandlerError, `Script execution failed: ${error.message}`, { cause: error });
+        }
+    }
+    /**
+     * Resolve argument templates with input values
+     * Replaces {{path.to.value}} with actual values from input
+     */
+    resolveArgs(args, input) {
+        if (!input)
+            return args;
+        return args.map((arg) => {
+            return arg.replace(/\{\{([^}]+)\}\}/g, (_, path) => {
+                const value = this.getValueByPath(input, path);
+                return value != null ? String(value) : '';
+            });
+        });
+    }
+    /**
+     * Get value from nested object by dot path
+     * e.g., "user.name" from { user: { name: "Alice" } } => "Alice"
+     * Protects against prototype pollution by blocking __proto__, constructor, prototype keys.
+     */
+    getValueByPath(obj, path) {
+        // Block prototype pollution attacks
+        const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+        const keys = path.split('.');
+        let current = obj;
+        for (const key of keys) {
+            if (current == null)
+                return undefined;
+            if (BLOCKED_KEYS.has(key))
+                return undefined;
+            if (typeof current !== 'object')
+                return undefined;
+            current = current[key];
+        }
+        return current;
+    }
+    /**
+     * Build environment variables for script execution
+     */
+    buildEnvironment(handler, input, context) {
+        const env = {
+            // Inherit base environment (filtered for security)
+            ...this.getBaseEnvironment(),
+            // LAVS context variables
+            LAVS_AGENT_ID: context.agentId,
+            LAVS_ENDPOINT_ID: context.endpointId,
+            // Handler-specific env vars (declared by manifest author)
+            ...(handler.env || {}),
+            // Context env vars (e.g. LAVS_PROJECT_PATH)
+            ...(context.env || {}),
+        };
+        // If input mode is 'env', flatten input object to env vars
+        if (handler.input === 'env' && input) {
+            Object.assign(env, this.inputToEnv(input));
+        }
+        // Final safety pass: remove any sensitive vars that might have leaked through
+        return this.filterSensitiveVars(env);
+    }
+    /**
+     * Sensitive environment variable patterns (case-insensitive match).
+     * These keywords in variable names indicate potentially sensitive data.
+     */
+    static SENSITIVE_PATTERNS = [
+        'SECRET',
+        'TOKEN',
+        'PASSWORD',
+        'PASSWD',
+        'CREDENTIAL',
+        'PRIVATE_KEY',
+        'API_KEY',
+        'APIKEY',
+        'ACCESS_KEY',
+        'AUTH',
+    ];
+    /**
+     * Whitelist of variable names that are safe even if they match sensitive patterns.
+     * For example, LAVS variables or NODE_ENV.
+     */
+    static SAFE_OVERRIDES = new Set([
+        'LAVS_AGENT_ID',
+        'LAVS_ENDPOINT_ID',
+        'LAVS_PROJECT_PATH',
+        'NODE_ENV',
+    ]);
+    /**
+     * Filter out environment variables that match sensitive patterns.
+     * Variables explicitly declared in handler.env are preserved (they are
+     * intentionally set by the manifest author), but inherited vars from
+     * process.env that match sensitive patterns are removed.
+     *
+     * @param env - Environment variables to filter
+     * @returns Filtered environment variables
+     */
+    filterSensitiveVars(env) {
+        const filtered = {};
+        for (const [key, value] of Object.entries(env)) {
+            // Always allow safe overrides
+            if (ScriptExecutor.SAFE_OVERRIDES.has(key)) {
+                filtered[key] = value;
+                continue;
+            }
+            // Check if variable name matches any sensitive pattern
+            const upperKey = key.toUpperCase();
+            const isSensitive = ScriptExecutor.SENSITIVE_PATTERNS.some((pattern) => upperKey.includes(pattern));
+            if (!isSensitive) {
+                filtered[key] = value;
+            }
+        }
+        return filtered;
+    }
+    /**
+     * Get base environment variables (filtered for security)
+     * Only include safe variables, exclude sensitive ones
+     */
+    getBaseEnvironment() {
+        const env = {};
+        // Whitelist of safe env vars to inherit
+        const safeVars = [
+            'PATH',
+            'HOME',
+            'USER',
+            'LANG',
+            'LC_ALL',
+            'TZ',
+            'NODE_ENV',
+            'SHELL',
+            'TMPDIR',
+            'TERM',
+        ];
+        for (const key of safeVars) {
+            if (process.env[key]) {
+                env[key] = process.env[key];
+            }
+        }
+        return env;
+    }
+    /**
+     * Convert input object to environment variables
+     * Flattens nested objects with underscore notation
+     */
+    inputToEnv(input, prefix = '') {
+        const env = {};
+        for (const [key, value] of Object.entries(input)) {
+            const envKey = prefix ? `${prefix}_${key}` : key;
+            if (value == null) {
+                continue;
+            }
+            else if (typeof value === 'object' && !Array.isArray(value)) {
+                // Recursively flatten nested objects
+                Object.assign(env, this.inputToEnv(value, envKey.toUpperCase()));
+            }
+            else {
+                // Convert to string
+                env[envKey.toUpperCase()] = String(value);
+            }
+        }
+        return env;
+    }
+    /**
+     * Capture stdout/stderr from process and wait for completion
+     */
+    async captureOutput(proc, timeout, endpointId) {
+        let stdout = '';
+        let stderr = '';
+        // Collect stdout
+        proc.stdout?.on('data', (data) => {
+            stdout += data.toString();
+        });
+        // Collect stderr (and log it)
+        proc.stderr?.on('data', (data) => {
+            const text = data.toString();
+            stderr += text;
+            console.log(`[LAVS:${endpointId}] stderr:`, text);
+        });
+        // Wait for process to exit
+        return new Promise((resolve, reject) => {
+            let timeoutHandle = null;
+            // Set timeout
+            timeoutHandle = setTimeout(() => {
+                proc.kill('SIGTERM');
+                // Give it 5 seconds to terminate gracefully, then force kill
+                setTimeout(() => proc.kill('SIGKILL'), 5000);
+                reject(new types_1.LAVSError(types_1.LAVSErrorCode.Timeout, `Script execution timeout after ${timeout}ms`));
+            }, timeout);
+            proc.on('exit', (code) => {
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
+                resolve({
+                    stdout,
+                    stderr,
+                    exitCode: code || 0,
+                });
+            });
+            proc.on('error', (error) => {
+                if (timeoutHandle)
+                    clearTimeout(timeoutHandle);
+                reject(error);
+            });
+        });
+    }
+    /**
+     * Parse script output as JSON
+     */
+    parseOutput(stdout, stderr) {
+        const trimmed = stdout.trim();
+        // Handle empty output
+        if (!trimmed) {
+            return null;
+        }
+        // Try to parse as JSON
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch (e) {
+            // If not valid JSON, try to extract JSON from output
+            // Look for first { or [ and last } or ]
+            const jsonMatch = trimmed.match(/(\{[\s\S]*\}|\[[\s\S]*\])/);
+            if (jsonMatch) {
+                try {
+                    return JSON.parse(jsonMatch[1]);
+                }
+                catch (e2) {
+                    // Fall through to error
+                }
+            }
+            throw new types_1.LAVSError(types_1.LAVSErrorCode.HandlerError, 'Script output is not valid JSON', {
+                stdout: trimmed,
+                stderr,
+                parseError: e.message,
+            });
+        }
+    }
+}
+exports.ScriptExecutor = ScriptExecutor;
+//# sourceMappingURL=script-executor.js.map

package/dist/script-executor.js.map

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

package/dist/subscription-manager.d.ts

@@ -0,0 +1,106 @@
+/**
+ * LAVS Subscription Manager
+ *
+ * Manages real-time subscriptions for LAVS endpoints.
+ * Uses Server-Sent Events (SSE) as the transport layer.
+ *
+ * Protocol flow:
+ * 1. Client opens SSE connection: GET /api/agents/:agentId/lavs/:endpoint/subscribe
+ * 2. Server sends events when data changes
+ * 3. Client or server can close the connection
+ */
+/**
+ * Minimal writable response interface for SSE.
+ * Compatible with express.Response, http.ServerResponse, etc.
+ */
+export interface SSEResponse {
+    writeHead(statusCode: number, headers: Record<string, string>): void;
+    write(chunk: string): boolean;
+    end(): void;
+    on(event: string, listener: (...args: any[]) => void): void;
+    writableEnded: boolean;
+}
+/**
+ * Event data to push to subscribers
+ */
+export interface SubscriptionEvent {
+    type: string;
+    data?: unknown;
+    timestamp?: string;
+}
+/**
+ * Configuration for the subscription manager
+ */
+interface SubscriptionManagerOptions {
+    /** Maximum number of concurrent subscriptions (default: 100) */
+    maxSubscriptions?: number;
+    /** Heartbeat interval in ms to keep connections alive (default: 30000) */
+    heartbeatIntervalMs?: number;
+}
+/**
+ * LAVS Subscription Manager - manages SSE-based subscriptions
+ */
+export declare class SubscriptionManager {
+    private subscriptions;
+    private readonly maxSubscriptions;
+    private heartbeatTimer;
+    constructor(options?: SubscriptionManagerOptions);
+    /**
+     * Send heartbeat to all subscriptions. Removes stale connections.
+     */
+    private sendHeartbeats;
+    /**
+     * Stop the heartbeat timer (for graceful shutdown / tests)
+     */
+    destroy(): void;
+    /**
+     * Create a new subscription.
+     *
+     * @param agentId - Agent identifier
+     * @param endpointId - Endpoint identifier (must be a subscription endpoint)
+     * @param res - Express response object (will be held open for SSE)
+     * @returns Subscription ID
+     * @throws Error if max subscriptions limit is reached
+     */
+    subscribe(agentId: string, endpointId: string, res: SSEResponse): string;
+    /**
+     * Remove a subscription
+     */
+    unsubscribe(subscriptionId: string): boolean;
+    /**
+     * Push an event to all subscribers of a specific agent+endpoint.
+     *
+     * @param agentId - Agent identifier
+     * @param endpointId - Endpoint identifier
+     * @param event - Event data to push
+     * @returns Number of subscribers notified
+     */
+    publish(agentId: string, endpointId: string, event: SubscriptionEvent): number;
+    /**
+     * Push an event to all subscribers of a specific agent (any endpoint).
+     *
+     * @param agentId - Agent identifier
+     * @param event - Event data to push
+     * @returns Number of subscribers notified
+     */
+    publishToAgent(agentId: string, event: SubscriptionEvent): number;
+    /**
+     * Get count of active subscriptions
+     */
+    getActiveCount(): number;
+    /**
+     * Get active subscriptions for an agent
+     */
+    getSubscriptionsForAgent(agentId: string): {
+        id: string;
+        endpointId: string;
+        createdAt: number;
+    }[];
+    /**
+     * Send an SSE event to a response stream
+     */
+    private sendSSE;
+}
+export declare const subscriptionManager: SubscriptionManager;
+export {};
+//# sourceMappingURL=subscription-manager.d.ts.map

package/dist/subscription-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-manager.d.ts","sourceRoot":"","sources":["../src/subscription-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IACrE,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,GAAG,IAAI,IAAI,CAAC;IACZ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC5D,aAAa,EAAE,OAAO,CAAC;CACxB;AAaD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,UAAU,0BAA0B;IAClC,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,aAAa,CAAwC;IAC7D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,cAAc,CAA+C;gBAEzD,OAAO,GAAE,0BAA+B;IAYpD;;OAEG;IACH,OAAO,CAAC,cAAc;IAetB;;OAEG;IACH,OAAO,IAAI,IAAI;IAWf;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM;IAwDxE;;OAEG;IACH,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAgC5C;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,MAAM;IA2B9E;;;;;;OAMG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,MAAM;IA0BjE;;OAEG;IACH,cAAc,IAAI,MAAM;IAIxB;;OAEG;IACH,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE;IAclG;;OAEG;IACH,OAAO,CAAC,OAAO;CAYhB;AAGD,eAAO,MAAM,mBAAmB,qBAA4B,CAAC"}