limen-ai 1.0.0

package/dist/substrate/adapters/capability_registry.js

@@ -0,0 +1,196 @@
+/**
+ * Capability Adapter Registry implementation.
+ * S ref: §25.3 (Capability Adapters), I-12 (Tool Sandboxing), I-22 (Capability Immutability)
+ *
+ * Phase: 2 (Execution Substrate)
+ * Implements: Registry of 7 capability types with per-adapter sandbox configuration,
+ *             validation, and sandboxed execution. Capabilities are immutable once
+ *             registered for a mission (I-22).
+ *
+ * Seven capability types per specification:
+ *   web_search, web_fetch, code_execute, data_query, file_read, file_write, api_call
+ *
+ * Invariants enforced: I-12 (sandbox), I-22 (immutable capabilities)
+ * Failure modes defended: FM-09 (unauthorized tool execution)
+ *
+ * SYNC interface. All methods return Result<T>.
+ */
+// ─── Error Constructors ───
+function err(code, message, spec) {
+    return { ok: false, error: { code, message, spec } };
+}
+function ok(value) {
+    return { ok: true, value };
+}
+// ─── Constants ───
+/** §25.3: The seven capability types defined in the specification */
+const ALL_CAPABILITY_TYPES = Object.freeze([
+    'web_search',
+    'web_fetch',
+    'code_execute',
+    'data_query',
+    'file_read',
+    'file_write',
+    'api_call',
+]);
+/** Default resource limits for sandbox (I-12) */
+const DEFAULT_RESOURCE_LIMITS = Object.freeze({
+    maxOldGenerationSizeMb: 128,
+    maxYoungGenerationSizeMb: 32,
+    codeRangeSizeMb: 16,
+});
+/** Default sandbox configurations per capability type */
+function getDefaultSandboxConfig(type) {
+    switch (type) {
+        case 'web_search':
+            return {
+                type,
+                allowedPaths: [],
+                networkAllowed: true,
+                maxExecutionMs: 30000,
+                resourceLimits: DEFAULT_RESOURCE_LIMITS,
+            };
+        case 'web_fetch':
+            return {
+                type,
+                allowedPaths: [],
+                networkAllowed: true,
+                maxExecutionMs: 30000,
+                resourceLimits: DEFAULT_RESOURCE_LIMITS,
+            };
+        case 'code_execute':
+            return {
+                type,
+                allowedPaths: [], // Will be scoped to workspaceDir at runtime
+                networkAllowed: false,
+                maxExecutionMs: 60000,
+                resourceLimits: DEFAULT_RESOURCE_LIMITS,
+            };
+        case 'data_query':
+            return {
+                type,
+                allowedPaths: [],
+                networkAllowed: false,
+                maxExecutionMs: 30000,
+                resourceLimits: DEFAULT_RESOURCE_LIMITS,
+            };
+        case 'file_read':
+            return {
+                type,
+                allowedPaths: [], // Scoped to workspaceDir at runtime
+                networkAllowed: false,
+                maxExecutionMs: 10000,
+                resourceLimits: DEFAULT_RESOURCE_LIMITS,
+            };
+        case 'file_write':
+            return {
+                type,
+                allowedPaths: [], // Scoped to workspaceDir at runtime
+                networkAllowed: false,
+                maxExecutionMs: 10000,
+                resourceLimits: DEFAULT_RESOURCE_LIMITS,
+            };
+        case 'api_call':
+            return {
+                type,
+                allowedPaths: [],
+                networkAllowed: true,
+                maxExecutionMs: 30000,
+                resourceLimits: DEFAULT_RESOURCE_LIMITS,
+            };
+    }
+}
+// ─── Capability Adapter Registry Factory ───
+/**
+ * Create a CapabilityAdapterRegistry implementation.
+ * S ref: §25.3, C-07 (Object.freeze)
+ *
+ * Adapters are registered with sandbox configurations.
+ * Execution validates the requested capability, applies sandbox rules,
+ * and dispatches to the adapter implementation.
+ */
+export function createCapabilityAdapterRegistry() {
+    /** In-memory adapter registrations */
+    const registrations = new Map();
+    // Register default adapters for all 7 types
+    for (const type of ALL_CAPABILITY_TYPES) {
+        registrations.set(type, {
+            type,
+            version: '1.0.0',
+            sandboxConfig: getDefaultSandboxConfig(type),
+        });
+    }
+    /**
+     * §25.3: Execute a capability in sandbox.
+     * FM-09: Validates capability type is registered.
+     * I-12: Execution within sandbox constraints.
+     */
+    function execute(_conn, _ctx, request) {
+        // F-02: Input validation -- workspaceDir must be non-empty and not contain '..'
+        if (!request.workspaceDir || request.workspaceDir.trim() === '') {
+            return err('INVALID_INPUT', 'workspaceDir must be a non-empty string', '§25.3/I-12');
+        }
+        if (request.workspaceDir.includes('..')) {
+            return err('INVALID_INPUT', 'workspaceDir must not contain path traversal sequences (..)', '§25.3/I-12');
+        }
+        // FM-09: Validate the capability type is supported
+        if (!ALL_CAPABILITY_TYPES.includes(request.type)) {
+            return err('CAPABILITY_NOT_FOUND', `Unknown capability type: ${request.type}`, '§25.3/FM-09');
+        }
+        const registration = registrations.get(request.type);
+        if (!registration) {
+            return err('CAPABILITY_NOT_REGISTERED', `Capability ${request.type} not registered`, '§25.3');
+        }
+        // I-12: Validate timeout within sandbox limits
+        const sandbox = registration.sandboxConfig;
+        // I-12: Timeout is capped to sandbox limit at dispatch time
+        // FM-09: Network access validation happens at sandbox boundary
+        void sandbox.maxExecutionMs; // Used at dispatch time for timeout enforcement
+        // CF-008: Capability execution sandbox not yet implemented.
+        // I-12 requires worker_threads with resource limits. Until the sandbox
+        // is implemented (Phase 5), ALL execution requests are rejected with
+        // SANDBOX_VIOLATION to prevent uncontrolled code execution.
+        // This is the fail-closed default — no accidental code execution path exists.
+        return err('SANDBOX_VIOLATION', `Capability execution sandbox not available. Type '${request.type}' cannot be executed until worker_threads sandbox is implemented.`, '§25.3/I-12/FM-09');
+    }
+    /** §25.3: Validate an adapter registration */
+    function validateRegistration(registration) {
+        // Validate capability type
+        if (!ALL_CAPABILITY_TYPES.includes(registration.type)) {
+            return err('INVALID_CAPABILITY_TYPE', `Unknown capability type: ${registration.type}`, '§25.3');
+        }
+        // Validate version format
+        if (!registration.version || registration.version.trim() === '') {
+            return err('INVALID_ADAPTER_VERSION', 'Adapter version is required', '§25.3');
+        }
+        // Validate sandbox config
+        const sandbox = registration.sandboxConfig;
+        if (sandbox.maxExecutionMs <= 0) {
+            return err('INVALID_SANDBOX_CONFIG', 'maxExecutionMs must be positive', 'I-12');
+        }
+        if (sandbox.resourceLimits.maxOldGenerationSizeMb < 1) {
+            return err('INVALID_SANDBOX_CONFIG', 'maxOldGenerationSizeMb must be >= 1', 'I-12');
+        }
+        return ok(undefined);
+    }
+    /** §25.3: Get all supported capability types */
+    function getSupportedCapabilities() {
+        return ok(ALL_CAPABILITY_TYPES);
+    }
+    /** §25.3: Get sandbox config for a capability type */
+    function getSandboxConfig(type) {
+        const registration = registrations.get(type);
+        if (!registration) {
+            return err('CAPABILITY_NOT_REGISTERED', `Capability ${type} not registered`, '§25.3');
+        }
+        return ok(registration.sandboxConfig);
+    }
+    const registry = {
+        execute,
+        validateRegistration,
+        getSupportedCapabilities,
+        getSandboxConfig,
+    };
+    return Object.freeze(registry);
+}
+//# sourceMappingURL=capability_registry.js.map

package/dist/substrate/adapters/capability_registry.js.map

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

package/dist/substrate/gateway/llm_gateway.d.ts

@@ -0,0 +1,68 @@
+/**
+ * LLM Gateway implementation.
+ * S ref: §25.4 (LLM Gateway), DL-1 (Provider Routing), I-04 (Provider Independence)
+ *
+ * Phase: 2 (Execution Substrate)
+ * Implements: Provider-independent LLM gateway with circuit breaker pattern,
+ *             4-state health tracking, cost accounting, retry logic, and streaming.
+ *             This is the ONLY async interface in the substrate (FPD-1/SD-02).
+ *
+ * Invariants enforced: I-01 (no SDK deps), I-03 (audit), I-04 (provider independence),
+ *                      I-05 (transactional), I-25 (deterministic replay logging)
+ * Failure modes defended: FM-02 (cost explosion), FM-06 (provider dependency),
+ *                         FM-12 (failover cascade)
+ *
+ * ASYNC interface. request() and requestStream() return Promise<Result<T>>.
+ * All other methods are SYNC returning Result<T>.
+ */
+import type { DatabaseConnection } from '../../kernel/interfaces/index.js';
+import type { Result, AuditCreateInput } from '../../kernel/interfaces/index.js';
+import type { TimeProvider } from '../../kernel/interfaces/time.js';
+import type { TransportEngine, ProviderAdapter } from '../transport/transport_types.js';
+/**
+ * Minimal audit dependency. Uses only the append method to keep coupling lightweight.
+ * S ref: I-03 (every state mutation and its audit entry in same transaction)
+ */
+interface AuditDep {
+    append(conn: DatabaseConnection, input: AuditCreateInput): Result<unknown>;
+}
+/**
+ * Transport dependency — when provided, the gateway delegates HTTP calls to
+ * the transport engine + provider adapter pair.
+ * S ref: §25.4 Phase 5A integration
+ */
+interface TransportDep {
+    readonly engine: TransportEngine;
+    readonly adapters: ReadonlyMap<string, ProviderAdapter>;
+}
+import type { LlmGateway } from '../interfaces/substrate.js';
+/**
+ * CF-010: Optional encryption for sensitive data at rest.
+ * When provided, request/response bodies in core_llm_request_log are encrypted.
+ * S ref: I-11 (encryption at rest), I-25 (deterministic replay — still works with decryption)
+ */
+interface EncryptionDep {
+    encrypt(plaintext: string): string;
+    decrypt(ciphertext: string): string;
+}
+/**
+ * Create an LlmGateway implementation.
+ * S ref: §25.4, C-07 (Object.freeze)
+ *
+ * Provider routing follows DL-1:
+ *   1. Capability filter (model supports requested capability)
+ *   2. Health filter (only healthy/degraded providers)
+ *   3. Strategy sort (lowest cost, then lowest latency)
+ *   4. Circuit breaker check
+ *
+ * All requests are logged to core_llm_request_log for I-25 replay.
+ * CF-010: When encryption is provided, request/response bodies are encrypted before storage.
+ */
+export declare function createLlmGateway(audit?: AuditDep, encryption?: EncryptionDep, time?: TimeProvider, transport?: TransportDep): LlmGateway;
+/**
+ * Exported for internal substrate use: record provider success/failure.
+ * Called by the actual HTTP transport layer when it processes responses.
+ */
+export declare function updateProviderHealth(conn: DatabaseConnection, providerId: string, success: boolean, latencyMs: number, errorMessage?: string, time?: TimeProvider): void;
+export {};
+//# sourceMappingURL=llm_gateway.d.ts.map

package/dist/substrate/gateway/llm_gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm_gateway.d.ts","sourceRoot":"","sources":["../../../src/substrate/gateway/llm_gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,KAAK,EACV,MAAM,EAIN,gBAAgB,EACjB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAIhB,MAAM,iCAAiC,CAAC;AAEzC;;;GAGG;AACH,UAAU,QAAQ;IAChB,MAAM,CAAC,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;CAC5E;AAED;;;;GAIG;AACH,UAAU,YAAY;IACpB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACzD;AAED,OAAO,KAAK,EACV,UAAU,EASX,MAAM,4BAA4B,CAAC;AAsBpC;;;;GAIG;AACH,UAAU,aAAa;IACrB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;CACrC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,YAAY,GAAG,UAAU,CAmdxI;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,kBAAkB,EACxB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,YAAY,GAClB,IAAI,CAmDN"}