lavs-runtime 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# lavs-runtime
+
+Server-side runtime for the **LAVS (Local Agent View Service)** protocol.
+
+Provides manifest loading, JSON Schema validation, handler execution (script & function), permission checking, rate limiting, subscription management, and AI tool generation.
+
+## Install
+
+```bash
+npm install lavs-runtime
+```
+
+## Usage
+
+```typescript
+import {
+  ManifestLoader,
+  LAVSValidator,
+  ScriptExecutor,
+  PermissionChecker,
+  LAVSToolGenerator,
+} from 'lavs-runtime';
+
+// Load and validate a LAVS manifest
+const loader = new ManifestLoader();
+const manifest = await loader.load('./lavs.json');
+
+const validator = new LAVSValidator();
+const result = validator.validateManifest(manifest);
+
+if (result.valid) {
+  // Execute a script handler
+  const executor = new ScriptExecutor();
+  const output = await executor.execute(manifest.endpoints[0].handler, {
+    endpointId: 'getData',
+    agentId: 'my-agent',
+    workdir: process.cwd(),
+    permissions: manifest.permissions ?? {},
+  });
+}
+```
+
+### Generate AI Tools from Manifest
+
+```typescript
+const generator = new LAVSToolGenerator();
+const tools = generator.generate(manifest);
+
+// tools can be passed to Claude or other LLM APIs
+for (const tool of tools) {
+  console.log(tool.name, tool.description);
+}
+```
+
+## Core Modules
+
+| Module | Description |
+|--------|-------------|
+| `ManifestLoader` | Load and parse `lavs.json` manifests |
+| `LAVSValidator` | Validate manifests and endpoint I/O against JSON Schema |
+| `ScriptExecutor` | Execute script handlers (node, python, etc.) |
+| `FunctionExecutor` | Execute JS/TS function handlers |
+| `PermissionChecker` | Enforce file access and execution permissions |
+| `LAVSRateLimiter` | Rate limiting for endpoint calls |
+| `SubscriptionManager` | SSE-based real-time subscriptions |
+| `LAVSToolGenerator` | Generate Claude-compatible tool definitions |
+
+## Related Packages
+
+- [`lavs-types`](https://www.npmjs.com/package/lavs-types) — Protocol type definitions
+- [`lavs-client`](https://www.npmjs.com/package/lavs-client) — Client SDK for frontend applications
+
+## License
+
+MIT

package/dist/function-executor.d.ts

@@ -0,0 +1,26 @@
+/**
+ * LAVS Function Executor
+ *
+ * Executes function handlers by dynamically importing JS/TS modules
+ * and calling exported functions.
+ */
+import { FunctionHandler, ExecutionContext } from './types';
+/**
+ * LAVS Function Executor - executes function handlers from JS modules
+ */
+export declare class FunctionExecutor {
+    /**
+     * Execute a function handler
+     *
+     * @param handler - Function handler configuration (module path + function name)
+     * @param input - Input data to pass to the function
+     * @param context - Execution context with permissions
+     * @returns Function return value
+     */
+    execute(handler: FunctionHandler, input: unknown, context: ExecutionContext): Promise<unknown>;
+    /**
+     * Execute a function with a timeout
+     */
+    private executeWithTimeout;
+}
+//# sourceMappingURL=function-executor.d.ts.map

package/dist/function-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-executor.d.ts","sourceRoot":"","sources":["../src/function-executor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,eAAe,EACf,gBAAgB,EAGjB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;;OAOG;IACG,OAAO,CACX,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,OAAO,CAAC;IA0DnB;;OAEG;YACW,kBAAkB;CA0BjC"}

package/dist/function-executor.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * LAVS Function Executor
+ *
+ * Executes function handlers by dynamically importing JS/TS modules
+ * and calling exported functions.
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FunctionExecutor = void 0;
+const types_1 = require("./types");
+/**
+ * LAVS Function Executor - executes function handlers from JS modules
+ */
+class FunctionExecutor {
+    /**
+     * Execute a function handler
+     *
+     * @param handler - Function handler configuration (module path + function name)
+     * @param input - Input data to pass to the function
+     * @param context - Execution context with permissions
+     * @returns Function return value
+     */
+    async execute(handler, input, context) {
+        const startTime = Date.now();
+        console.log(`[LAVS] Executing function for ${context.endpointId}`, {
+            module: handler.module,
+            function: handler.function,
+        });
+        try {
+            // 1. Dynamically import the module
+            let mod;
+            try {
+                mod = await Promise.resolve(`${handler.module}`).then(s => __importStar(require(s)));
+            }
+            catch (importError) {
+                const message = importError instanceof Error ? importError.message : String(importError);
+                throw new types_1.LAVSError(types_1.LAVSErrorCode.HandlerError, `Failed to import module '${handler.module}': ${message}`);
+            }
+            // 2. Find the function
+            const fn = mod[handler.function];
+            if (typeof fn !== 'function') {
+                throw new types_1.LAVSError(types_1.LAVSErrorCode.HandlerError, `Function '${handler.function}' not found or not a function in module '${handler.module}'`);
+            }
+            // 3. Execute with timeout
+            const timeout = context.timeout || context.permissions.maxExecutionTime || 30000;
+            const result = await this.executeWithTimeout(fn, input, context, timeout);
+            const duration = Date.now() - startTime;
+            console.log(`[LAVS] Function completed in ${duration}ms`, {
+                endpointId: context.endpointId,
+            });
+            return result;
+        }
+        catch (error) {
+            if (error instanceof types_1.LAVSError) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw new types_1.LAVSError(types_1.LAVSErrorCode.HandlerError, `Function execution failed: ${message}`, { cause: error });
+        }
+    }
+    /**
+     * Execute a function with a timeout
+     */
+    async executeWithTimeout(fn, input, context, timeout) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new types_1.LAVSError(types_1.LAVSErrorCode.Timeout, `Function execution timeout after ${timeout}ms`));
+            }, timeout);
+            // Call the function - pass both input and context
+            Promise.resolve(fn(input, context))
+                .then((result) => {
+                clearTimeout(timer);
+                resolve(result);
+            })
+                .catch((error) => {
+                clearTimeout(timer);
+                reject(error);
+            });
+        });
+    }
+}
+exports.FunctionExecutor = FunctionExecutor;
+//# sourceMappingURL=function-executor.js.map

package/dist/function-executor.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * LAVS Runtime - Server-side SDK
+ *
+ * Re-exports all core runtime modules for convenient importing.
+ *
+ * @example
+ * ```typescript
+ * import { ManifestLoader, LAVSValidator, ScriptExecutor } from '@lavs/runtime';
+ * ```
+ */
+export type { LAVSManifest, Endpoint, Handler, ScriptHandler, FunctionHandler, HTTPHandler, MCPHandler, Schema, JSONSchema, TypeDefinitions, ViewConfig, ComponentSource, Permissions, ExecutionContext, } from './types';
+export { LAVSError, LAVSErrorCode } from './types';
+export { ManifestLoader } from './loader';
+export { LAVSValidator } from './validator';
+export type { ValidationResult, ValidationError } from './validator';
+export { ScriptExecutor } from './script-executor';
+export { FunctionExecutor } from './function-executor';
+export { PermissionChecker } from './permission-checker';
+export { LAVSRateLimiter } from './rate-limiter';
+export type { RateLimitConfig, RateLimitResult } from './rate-limiter';
+export { SubscriptionManager, subscriptionManager } from './subscription-manager';
+export type { SubscriptionEvent, SSEResponse } from './subscription-manager';
+export { LAVSToolGenerator } from './tool-generator';
+export type { ClaudeTool, ToolExecutor, GeneratedTool } from './tool-generator';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,YAAY,EACV,YAAY,EACZ,QAAQ,EACR,OAAO,EACP,aAAa,EACb,eAAe,EACf,WAAW,EACX,UAAU,EACV,MAAM,EACN,UAAU,EACV,eAAe,EACf,UAAU,EACV,eAAe,EACf,WAAW,EACX,gBAAgB,GACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGnD,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAClF,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * LAVS Runtime - Server-side SDK
+ *
+ * Re-exports all core runtime modules for convenient importing.
+ *
+ * @example
+ * ```typescript
+ * import { ManifestLoader, LAVSValidator, ScriptExecutor } from '@lavs/runtime';
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LAVSToolGenerator = exports.subscriptionManager = exports.SubscriptionManager = exports.LAVSRateLimiter = exports.PermissionChecker = exports.FunctionExecutor = exports.ScriptExecutor = exports.LAVSValidator = exports.ManifestLoader = exports.LAVSErrorCode = exports.LAVSError = void 0;
+var types_1 = require("./types");
+Object.defineProperty(exports, "LAVSError", { enumerable: true, get: function () { return types_1.LAVSError; } });
+Object.defineProperty(exports, "LAVSErrorCode", { enumerable: true, get: function () { return types_1.LAVSErrorCode; } });
+// Core modules
+var loader_1 = require("./loader");
+Object.defineProperty(exports, "ManifestLoader", { enumerable: true, get: function () { return loader_1.ManifestLoader; } });
+var validator_1 = require("./validator");
+Object.defineProperty(exports, "LAVSValidator", { enumerable: true, get: function () { return validator_1.LAVSValidator; } });
+var script_executor_1 = require("./script-executor");
+Object.defineProperty(exports, "ScriptExecutor", { enumerable: true, get: function () { return script_executor_1.ScriptExecutor; } });
+var function_executor_1 = require("./function-executor");
+Object.defineProperty(exports, "FunctionExecutor", { enumerable: true, get: function () { return function_executor_1.FunctionExecutor; } });
+var permission_checker_1 = require("./permission-checker");
+Object.defineProperty(exports, "PermissionChecker", { enumerable: true, get: function () { return permission_checker_1.PermissionChecker; } });
+var rate_limiter_1 = require("./rate-limiter");
+Object.defineProperty(exports, "LAVSRateLimiter", { enumerable: true, get: function () { return rate_limiter_1.LAVSRateLimiter; } });
+var subscription_manager_1 = require("./subscription-manager");
+Object.defineProperty(exports, "SubscriptionManager", { enumerable: true, get: function () { return subscription_manager_1.SubscriptionManager; } });
+Object.defineProperty(exports, "subscriptionManager", { enumerable: true, get: function () { return subscription_manager_1.subscriptionManager; } });
+var tool_generator_1 = require("./tool-generator");
+Object.defineProperty(exports, "LAVSToolGenerator", { enumerable: true, get: function () { return tool_generator_1.LAVSToolGenerator; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAmBH,iCAAmD;AAA1C,kGAAA,SAAS,OAAA;AAAE,sGAAA,aAAa,OAAA;AAEjC,eAAe;AACf,mCAA0C;AAAjC,wGAAA,cAAc,OAAA;AACvB,yCAA4C;AAAnC,0GAAA,aAAa,OAAA;AAEtB,qDAAmD;AAA1C,iHAAA,cAAc,OAAA;AACvB,yDAAuD;AAA9C,qHAAA,gBAAgB,OAAA;AACzB,2DAAyD;AAAhD,uHAAA,iBAAiB,OAAA;AAC1B,+CAAiD;AAAxC,+GAAA,eAAe,OAAA;AAExB,+DAAkF;AAAzE,2HAAA,mBAAmB,OAAA;AAAE,2HAAA,mBAAmB,OAAA;AAEjD,mDAAqD;AAA5C,mHAAA,iBAAiB,OAAA"}

package/dist/loader.d.ts

@@ -0,0 +1,37 @@
+/**
+ * LAVS Manifest Loader
+ *
+ * Loads and validates lavs.json configuration files.
+ */
+import { LAVSManifest } from './types';
+export declare class ManifestLoader {
+    /**
+     * Load LAVS manifest from file
+     * @param manifestPath - Path to lavs.json
+     * @returns Parsed and validated manifest with resolved paths
+     */
+    load(manifestPath: string): Promise<LAVSManifest>;
+    /**
+     * Validate manifest structure and required fields
+     */
+    private validateManifest;
+    /**
+     * Validate individual endpoint definition
+     */
+    private validateEndpoint;
+    /**
+     * Validate handler configuration
+     */
+    private validateHandler;
+    /**
+     * Resolve relative paths in manifest to absolute paths
+     * This makes the manifest portable and allows scripts to use relative paths
+     */
+    private resolvePaths;
+    /**
+     * Check if a command looks like a relative script path
+     * e.g., "scripts/handler.js", "./handler.py", "handler.sh"
+     */
+    private isRelativeScriptPath;
+}
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,YAAY,EAA4D,MAAM,SAAS,CAAC;AAEjG,qBAAa,cAAc;IACzB;;;;OAIG;IACG,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA+CvD;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA4CxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAyBxB;;OAEG;IACH,OAAO,CAAC,eAAe;IA6DvB;;;OAGG;IACH,OAAO,CAAC,YAAY;IA2CpB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;CAa7B"}

package/dist/loader.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * LAVS Manifest Loader
+ *
+ * Loads and validates lavs.json configuration files.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ManifestLoader = void 0;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const types_1 = require("./types");
+class ManifestLoader {
+    /**
+     * Load LAVS manifest from file
+     * @param manifestPath - Path to lavs.json
+     * @returns Parsed and validated manifest with resolved paths
+     */
+    async load(manifestPath) {
+        try {
+            // 1. Check if file exists
+            const exists = await promises_1.default.access(manifestPath).then(() => true).catch(() => false);
+            if (!exists) {
+                throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, `Manifest file not found: ${manifestPath}`);
+            }
+            // 2. Read file
+            const content = await promises_1.default.readFile(manifestPath, 'utf-8');
+            // 3. Parse JSON
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                throw new types_1.LAVSError(types_1.LAVSErrorCode.ParseError, `Invalid JSON in manifest: ${message}`, { cause: e });
+            }
+            // 4. Basic validation
+            this.validateManifest(parsed);
+            // 5. Resolve relative paths
+            const manifest = this.resolvePaths(parsed, manifestPath);
+            return manifest;
+        }
+        catch (error) {
+            if (error instanceof types_1.LAVSError) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            throw new types_1.LAVSError(types_1.LAVSErrorCode.InternalError, `Failed to load manifest: ${message}`, { cause: error });
+        }
+    }
+    /**
+     * Validate manifest structure and required fields
+     */
+    validateManifest(manifest) {
+        // Check required top-level fields
+        if (!manifest.lavs) {
+            throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, 'Missing required field: lavs');
+        }
+        if (!manifest.name) {
+            throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, 'Missing required field: name');
+        }
+        if (!manifest.version) {
+            throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, 'Missing required field: version');
+        }
+        if (!Array.isArray(manifest.endpoints)) {
+            throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, 'Missing or invalid field: endpoints (must be array)');
+        }
+        // Validate each endpoint + uniqueness check
+        const seenIds = new Set();
+        for (const endpoint of manifest.endpoints) {
+            this.validateEndpoint(endpoint);
+            if (seenIds.has(endpoint.id)) {
+                throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, `Duplicate endpoint ID: '${endpoint.id}'. Endpoint IDs must be unique.`);
+            }
+            seenIds.add(endpoint.id);
+        }
+    }
+    /**
+     * Validate individual endpoint definition
+     */
+    validateEndpoint(endpoint) {
+        if (!endpoint.id) {
+            throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, 'Endpoint missing required field: id');
+        }
+        if (!endpoint.method || !['query', 'mutation', 'subscription'].includes(endpoint.method)) {
+            throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, `Invalid endpoint method: ${endpoint.method} (must be query, mutation, or subscription)`);
+        }
+        if (!endpoint.handler) {
+            throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, `Endpoint ${endpoint.id} missing required field: handler`);
+        }
+        this.validateHandler(endpoint.handler, endpoint.id);
+    }
+    /**
+     * Validate handler configuration
+     */
+    validateHandler(handler, endpointId) {
+        if (!handler.type) {
+            throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, `Handler for ${endpointId} missing required field: type`);
+        }
+        const validTypes = ['script', 'function', 'http', 'mcp'];
+        if (!validTypes.includes(handler.type)) {
+            throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, `Invalid handler type: ${handler.type} (must be one of: ${validTypes.join(', ')})`);
+        }
+        // Type-specific validation
+        if (handler.type === 'script') {
+            if (!handler.command) {
+                throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, `Script handler for ${endpointId} missing required field: command`);
+            }
+            if (handler.input && !['args', 'stdin', 'env'].includes(handler.input)) {
+                throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, `Invalid script input mode: ${handler.input} (must be args, stdin, or env)`);
+            }
+        }
+        if (handler.type === 'function') {
+            if (!handler.module || !handler.function) {
+                throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, `Function handler for ${endpointId} missing required fields: module, function`);
+            }
+        }
+        if (handler.type === 'http') {
+            if (!handler.url || !handler.method) {
+                throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, `HTTP handler for ${endpointId} missing required fields: url, method`);
+            }
+        }
+        if (handler.type === 'mcp') {
+            if (!handler.server || !handler.tool) {
+                throw new types_1.LAVSError(types_1.LAVSErrorCode.InvalidRequest, `MCP handler for ${endpointId} missing required fields: server, tool`);
+            }
+        }
+    }
+    /**
+     * Resolve relative paths in manifest to absolute paths
+     * This makes the manifest portable and allows scripts to use relative paths
+     */
+    resolvePaths(manifest, manifestPath) {
+        const basedir = path_1.default.dirname(manifestPath);
+        // Clone to avoid mutations
+        const resolved = JSON.parse(JSON.stringify(manifest));
+        // Resolve endpoint handlers
+        for (const endpoint of resolved.endpoints) {
+            const handler = endpoint.handler;
+            if (handler.type === 'script') {
+                // Resolve script command path if it looks like a relative file path
+                // (has .js, .py, etc. extension and doesn't start with /)
+                const cmd = handler.command;
+                if (this.isRelativeScriptPath(cmd)) {
+                    handler.command = path_1.default.resolve(basedir, cmd);
+                }
+                // Resolve cwd if specified
+                if (handler.cwd && !path_1.default.isAbsolute(handler.cwd)) {
+                    handler.cwd = path_1.default.resolve(basedir, handler.cwd);
+                }
+            }
+            if (handler.type === 'function') {
+                // Resolve module path
+                if (!path_1.default.isAbsolute(handler.module)) {
+                    handler.module = path_1.default.resolve(basedir, handler.module);
+                }
+            }
+        }
+        // Resolve view component paths
+        if (resolved.view?.component?.type === 'local') {
+            const comp = resolved.view.component;
+            if (!path_1.default.isAbsolute(comp.path)) {
+                comp.path = path_1.default.resolve(basedir, comp.path);
+            }
+        }
+        return resolved;
+    }
+    /**
+     * Check if a command looks like a relative script path
+     * e.g., "scripts/handler.js", "./handler.py", "handler.sh"
+     */
+    isRelativeScriptPath(cmd) {
+        // If starts with ./ or ../, definitely relative
+        if (cmd.startsWith('./') || cmd.startsWith('../')) {
+            return true;
+        }
+        // If has path separators and common script extensions
+        const scriptExtensions = ['.js', '.ts', '.py', '.sh', '.rb', '.php'];
+        const hasExtension = scriptExtensions.some(ext => cmd.endsWith(ext));
+        const hasPathSep = cmd.includes('/');
+        return hasExtension && (hasPathSep || !cmd.includes(' '));
+    }
+}
+exports.ManifestLoader = ManifestLoader;
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

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

package/dist/permission-checker.d.ts

@@ -0,0 +1,86 @@
+/**
+ * LAVS Permission Checker
+ *
+ * Enforces permission constraints declared in LAVS manifests.
+ *
+ * ## Enforcement Model
+ *
+ * LAVS permissions have two enforcement levels:
+ *
+ * | Permission       | Level    | What is checked                                |
+ * |-----------------|----------|------------------------------------------------|
+ * | Path traversal  | ENFORCED | Handler cwd and command paths are validated     |
+ * | fileAccess      | ADVISORY | Glob pattern matching at dispatch time;         |
+ * |                 |          | NOT intercepted at OS/syscall level during      |
+ * |                 |          | script execution. Scripts can still access       |
+ * |                 |          | files the process has OS-level permission for.   |
+ * | networkAccess   | ADVISORY | Declared for auditing; not enforced at runtime. |
+ * |                 |          | Use OS-level isolation (nsjail, Docker) for     |
+ * |                 |          | strict enforcement.                              |
+ * | maxExecTime     | ENFORCED | Handler killed via SIGTERM/SIGKILL on timeout.  |
+ * | maxMemory       | ADVISORY | Not enforced in current runtime.                |
+ *
+ * Future: Consider OS-level sandboxing for fileAccess and networkAccess.
+ */
+import { Permissions, ScriptHandler } from './types';
+/**
+ * LAVS Permission Checker - enforces manifest-declared security constraints
+ */
+export declare class PermissionChecker {
+    /**
+     * Merge manifest-level and endpoint-level permissions.
+     * Endpoint-level permissions take precedence over manifest-level.
+     *
+     * @param manifestPermissions - Manifest-level permissions (defaults)
+     * @param endpointPermissions - Endpoint-level permissions (overrides)
+     * @returns Merged permissions object
+     */
+    mergePermissions(manifestPermissions?: Permissions, endpointPermissions?: Permissions): Permissions;
+    /**
+     * Check if a target path is within the allowed base directory.
+     * Prevents path traversal attacks (e.g., ../../etc/passwd).
+     *
+     * @param targetPath - The path to check (absolute or relative)
+     * @param allowedBase - The allowed base directory (absolute)
+     * @throws LAVSError with code PermissionDenied if path is outside allowed base
+     */
+    checkPathTraversal(targetPath: string, allowedBase: string): void;
+    /**
+     * Check if a handler's working directory is within the allowed base.
+     *
+     * @param handler - Script handler with optional cwd
+     * @param agentDir - Agent directory (the allowed base)
+     * @throws LAVSError with code PermissionDenied if cwd is outside agent directory
+     */
+    checkHandlerCwd(handler: ScriptHandler, agentDir: string): void;
+    /**
+     * Check if file access patterns allow a given path.
+     * Uses glob matching against permissions.fileAccess patterns.
+     *
+     * @param filePath - The file path to check (relative to agent dir)
+     * @param permissions - Permission constraints including fileAccess patterns
+     * @returns true if access is allowed, false otherwise
+     */
+    checkFileAccess(filePath: string, permissions: Permissions): boolean;
+    /**
+     * Get the effective execution timeout for a handler.
+     * Priority: handler.timeout > permissions.maxExecutionTime > default (30000ms)
+     *
+     * @param handler - Script handler with optional timeout
+     * @param permissions - Permission constraints with optional maxExecutionTime
+     * @param defaultTimeout - Default timeout in milliseconds (default: 30000)
+     * @returns Effective timeout in milliseconds
+     */
+    getEffectiveTimeout(handler: ScriptHandler, permissions: Permissions, defaultTimeout?: number): number;
+    /**
+     * Run all permission checks for a script handler execution.
+     * This is a convenience method that combines multiple checks.
+     *
+     * @param handler - Script handler configuration
+     * @param permissions - Merged permissions
+     * @param agentDir - Agent base directory
+     * @throws LAVSError if any permission check fails
+     */
+    assertAllowed(handler: ScriptHandler, permissions: Permissions, agentDir: string): void;
+}
+//# sourceMappingURL=permission-checker.d.ts.map

package/dist/permission-checker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-checker.d.ts","sourceRoot":"","sources":["../src/permission-checker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,EACL,WAAW,EACX,aAAa,EAGd,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;OAOG;IACH,gBAAgB,CACd,mBAAmB,CAAC,EAAE,WAAW,EACjC,mBAAmB,CAAC,EAAE,WAAW,GAChC,WAAW;IAmBd;;;;;;;OAOG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAcjE;;;;;;OAMG;IACH,eAAe,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQ/D;;;;;;;OAOG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO;IA+BpE;;;;;;;;OAQG;IACH,mBAAmB,CACjB,OAAO,EAAE,aAAa,EACtB,WAAW,EAAE,WAAW,EACxB,cAAc,GAAE,MAAc,GAC7B,MAAM;IAkBT;;;;;;;;OAQG;IACH,aAAa,CACX,OAAO,EAAE,aAAa,EACtB,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,MAAM,GACf,IAAI;CAYR"}