@thyn-ai/sqai 0.1.2 → 0.1.3

package/dist/index.d.cts

@@ -140,12 +140,29 @@ interface RuntimeStatus {
     platform: string;
     managed: boolean;
 }
+/** A runtime bundle resolved for a specific module filter (build-on-provision). */
+interface FilteredBundle {
+    url: string;
+    sha256: string;
+    version: string;
+    cacheKey: string;
+}
 interface ProvisionerOptions {
     contract: CapabilityContract;
     autoInstall: boolean;
+    /**
+     * Build-on-provision: the developer's module filter. All 4,762 functions are
+     * available in the contract; only the selected modules are compiled + installed.
+     * Empty/undefined → the default pinned bundle (contract.runtime_bundle).
+     */
+    runtimeModules?: string[];
+    /** Build service that compiles a bundle for an exact filter (POST /v1/runtime/build). */
+    buildServiceUrl?: string;
     /** Injection points for tests. */
     runtimeFactory?: (config?: MojoRuntimeConfig) => MojoRuntime;
     downloadBundle?: (url: string, destination: string) => Promise<void>;
+    /** Resolve a filtered bundle (default: POST to buildServiceUrl). Test injection. */
+    resolveFilteredBundle?: (modules: string[], platformKey: string) => Promise<FilteredBundle>;
     /** Bundle cache directory (default: OS user cache — runtimeCacheDir()). */
     cacheDir?: string;
     /** Trust-root overrides (default: the embedded trust root). */
@@ -171,6 +188,27 @@ declare class RuntimeProvisioner {
     stop(): Promise<void>;
     private newRuntime;
     private cacheDir;
+    /** Normalized module filter (sorted, unique, non-empty) or null for the default bundle. */
+    private filterModules;
+    /** Ask the build service to compile + sign a bundle for exactly these modules. */
+    private resolveFilteredBundle;
+    /**
+     * The filter's cache key, computed IDENTICALLY to the build service
+     * (sha256("mods|platform|version")[:20], mods = sorted+unique, comma-joined).
+     * Lets the reuse fast-path find an already-running filtered daemon without a
+     * build-service round-trip. The build service's returned key is authoritative
+     * for install; this only has to match for the reuse optimization to hit.
+     */
+    private localCacheKey;
+    /**
+     * Deterministic per-filter daemon endpoint so a filtered runtime never collides
+     * with the default (or another filter's) daemon on the shared default socket.
+     */
+    private filterEndpoint;
+    private static readonly DAEMON_ENDPOINT_ENV;
+    /** Point the about-to-be-spawned daemon at a filter-specific socket/port/dir. */
+    private applyDaemonEndpointEnv;
+    private restoreEnv;
     private doEnsure;
     private provisionError;
     private wrapVerificationError;
@@ -179,7 +217,7 @@ declare class RuntimeProvisioner {
     private verifiedInstallOrNull;
     private acquireLock;
     private lockIsStale;
-    /** Serialize installers on `<cacheDir>/<version>.lock`; returns the verified install. */
+    /** Serialize installers on `<cacheDir>/<installKey>.lock`; returns the verified install. */
     private ensureInstalled;
     /** Holder-of-the-lock path: download → verify → extract → atomic rename. */
     private downloadVerifyExtract;
@@ -384,6 +422,15 @@ interface SqaiConfig {
     timeout?: number;
     maxRetries?: number;
     resultStore?: ResultStoreConfig;
+    /**
+     * Build-on-provision module filter. All 4,762 functions are available in the
+     * contract; set this to install only the modules you use. The build service
+     * compiles + signs a bundle for exactly this set (cached by filter-hash).
+     * Omit for the default pinned bundle. Env: SQAI_RUNTIME_MODULES (comma-separated).
+     */
+    runtimeModules?: string[];
+    /** Build service endpoint for filtered bundles. Env: SQAI_BUILD_SERVICE_URL. */
+    buildServiceUrl?: string;
     /** BYO substrate (tests). */
     runtime?: Runtime;
     /** BYO computation dispatch target (tests / custom self-hosted engines). */

package/dist/index.d.ts

@@ -140,12 +140,29 @@ interface RuntimeStatus {
     platform: string;
     managed: boolean;
 }
+/** A runtime bundle resolved for a specific module filter (build-on-provision). */
+interface FilteredBundle {
+    url: string;
+    sha256: string;
+    version: string;
+    cacheKey: string;
+}
 interface ProvisionerOptions {
     contract: CapabilityContract;
     autoInstall: boolean;
+    /**
+     * Build-on-provision: the developer's module filter. All 4,762 functions are
+     * available in the contract; only the selected modules are compiled + installed.
+     * Empty/undefined → the default pinned bundle (contract.runtime_bundle).
+     */
+    runtimeModules?: string[];
+    /** Build service that compiles a bundle for an exact filter (POST /v1/runtime/build). */
+    buildServiceUrl?: string;
     /** Injection points for tests. */
     runtimeFactory?: (config?: MojoRuntimeConfig) => MojoRuntime;
     downloadBundle?: (url: string, destination: string) => Promise<void>;
+    /** Resolve a filtered bundle (default: POST to buildServiceUrl). Test injection. */
+    resolveFilteredBundle?: (modules: string[], platformKey: string) => Promise<FilteredBundle>;
     /** Bundle cache directory (default: OS user cache — runtimeCacheDir()). */
     cacheDir?: string;
     /** Trust-root overrides (default: the embedded trust root). */
@@ -171,6 +188,27 @@ declare class RuntimeProvisioner {
     stop(): Promise<void>;
     private newRuntime;
     private cacheDir;
+    /** Normalized module filter (sorted, unique, non-empty) or null for the default bundle. */
+    private filterModules;
+    /** Ask the build service to compile + sign a bundle for exactly these modules. */
+    private resolveFilteredBundle;
+    /**
+     * The filter's cache key, computed IDENTICALLY to the build service
+     * (sha256("mods|platform|version")[:20], mods = sorted+unique, comma-joined).
+     * Lets the reuse fast-path find an already-running filtered daemon without a
+     * build-service round-trip. The build service's returned key is authoritative
+     * for install; this only has to match for the reuse optimization to hit.
+     */
+    private localCacheKey;
+    /**
+     * Deterministic per-filter daemon endpoint so a filtered runtime never collides
+     * with the default (or another filter's) daemon on the shared default socket.
+     */
+    private filterEndpoint;
+    private static readonly DAEMON_ENDPOINT_ENV;
+    /** Point the about-to-be-spawned daemon at a filter-specific socket/port/dir. */
+    private applyDaemonEndpointEnv;
+    private restoreEnv;
     private doEnsure;
     private provisionError;
     private wrapVerificationError;
@@ -179,7 +217,7 @@ declare class RuntimeProvisioner {
     private verifiedInstallOrNull;
     private acquireLock;
     private lockIsStale;
-    /** Serialize installers on `<cacheDir>/<version>.lock`; returns the verified install. */
+    /** Serialize installers on `<cacheDir>/<installKey>.lock`; returns the verified install. */
     private ensureInstalled;
     /** Holder-of-the-lock path: download → verify → extract → atomic rename. */
     private downloadVerifyExtract;
@@ -384,6 +422,15 @@ interface SqaiConfig {
     timeout?: number;
     maxRetries?: number;
     resultStore?: ResultStoreConfig;
+    /**
+     * Build-on-provision module filter. All 4,762 functions are available in the
+     * contract; set this to install only the modules you use. The build service
+     * compiles + signs a bundle for exactly this set (cached by filter-hash).
+     * Omit for the default pinned bundle. Env: SQAI_RUNTIME_MODULES (comma-separated).
+     */
+    runtimeModules?: string[];
+    /** Build service endpoint for filtered bundles. Env: SQAI_BUILD_SERVICE_URL. */
+    buildServiceUrl?: string;
     /** BYO substrate (tests). */
     runtime?: Runtime;
     /** BYO computation dispatch target (tests / custom self-hosted engines). */

package/dist/index.js

@@ -134,11 +134,15 @@ function fromAlgentaError(error) {
 }
 
 // src/env.ts
+var DEFAULT_BUILD_SERVICE_URL = "https://sqai-buildservice.fly.dev";
 function readEnv(env = process.env) {
   const apiKey = (env.SQAI_API_KEY ?? "").trim() || void 0;
   const engineUrl = (env.SQAI_ENGINE_URL ?? "").trim() || void 0;
   const autoInstall = (env.SQAI_RUNTIME_AUTO_INSTALL ?? "").trim() !== "0";
-  return { apiKey, engineUrl, autoInstall };
+  const modulesRaw = (env.SQAI_RUNTIME_MODULES ?? "").split(",").map((m) => m.trim()).filter((m) => m.length > 0);
+  const runtimeModules = modulesRaw.length > 0 ? modulesRaw : void 0;
+  const buildServiceUrl = (env.SQAI_BUILD_SERVICE_URL ?? "").trim() || DEFAULT_BUILD_SERVICE_URL;
+  return { apiKey, engineUrl, autoInstall, runtimeModules, buildServiceUrl };
 }
 function inferMode(explicit, resolved) {
   if (explicit) {
@@ -314,7 +318,7 @@ var ResultStore = class {
 import { homedir, platform as osPlatform, arch as osArch } from "os";
 import { join as join2 } from "path";
 import { createWriteStream, promises as fs2 } from "fs";
-import { randomBytes as randomBytes2 } from "crypto";
+import { createHash as createHash3, randomBytes as randomBytes2 } from "crypto";
 import { Readable } from "stream";
 import { pipeline } from "stream/promises";
 import { MojoRuntime } from "algenta-sdk";
@@ -990,7 +994,7 @@ async function removeQuietly(path) {
   } catch {
   }
 }
-var RuntimeProvisioner = class {
+var RuntimeProvisioner = class _RuntimeProvisioner {
   options;
   trustRoot;
   runtime = null;
@@ -1050,8 +1054,110 @@ var RuntimeProvisioner = class {
   cacheDir() {
     return this.options.cacheDir ?? runtimeCacheDir();
   }
+  /** Normalized module filter (sorted, unique, non-empty) or null for the default bundle. */
+  filterModules() {
+    const mods = (this.options.runtimeModules ?? []).map((m) => m.trim()).filter((m) => m.length > 0);
+    if (mods.length === 0) {
+      return null;
+    }
+    return Array.from(new Set(mods)).sort();
+  }
+  /** Ask the build service to compile + sign a bundle for exactly these modules. */
+  async resolveFilteredBundle(modules, platformKey) {
+    if (this.options.resolveFilteredBundle) {
+      return this.options.resolveFilteredBundle(modules, platformKey);
+    }
+    const base = this.options.buildServiceUrl;
+    if (!base) {
+      throw new SqaiError(
+        "runtime_provision_failed",
+        "runtimeModules was set but no build service is configured. Set SQAI_BUILD_SERVICE_URL to a build-on-provision endpoint, or omit runtimeModules to use the default bundle.",
+        { details: { reason: "no_build_service", modules } }
+      );
+    }
+    let response;
+    try {
+      response = await fetch(`${base.replace(/\/$/, "")}/v1/runtime/build`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ modules, platform: platformKey })
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new SqaiError(
+        "runtime_provision_failed",
+        `Build service request failed: ${message}`,
+        { retryable: true, details: { reason: "build_service_unreachable", modules } }
+      );
+    }
+    if (!response.ok) {
+      throw new SqaiError(
+        "runtime_provision_failed",
+        `Build service returned HTTP ${response.status} for the requested filter.`,
+        { retryable: response.status >= 500, details: { reason: "build_failed", modules } }
+      );
+    }
+    const body = await response.json();
+    return {
+      url: body.url,
+      sha256: body.sha256,
+      version: body.version ?? this.options.contract.runtime_bundle.version,
+      cacheKey: body.cache_key
+    };
+  }
+  /**
+   * The filter's cache key, computed IDENTICALLY to the build service
+   * (sha256("mods|platform|version")[:20], mods = sorted+unique, comma-joined).
+   * Lets the reuse fast-path find an already-running filtered daemon without a
+   * build-service round-trip. The build service's returned key is authoritative
+   * for install; this only has to match for the reuse optimization to hit.
+   */
+  localCacheKey(modules, platformKey) {
+    const canonical = modules.join(",");
+    const version = this.options.contract.runtime_bundle.version;
+    return createHash3("sha256").update(`${canonical}|${platformKey}|${version}`).digest("hex").slice(0, 20);
+  }
+  /**
+   * Deterministic per-filter daemon endpoint so a filtered runtime never collides
+   * with the default (or another filter's) daemon on the shared default socket.
+   */
+  filterEndpoint(cacheKey) {
+    const seed = parseInt(cacheKey.slice(0, 6), 16) || 0;
+    const port = 50100 + seed % 800;
+    return { sock: join2(this.cacheDir(), `${cacheKey}.sock`), tcp: `127.0.0.1:${port}` };
+  }
+  static DAEMON_ENDPOINT_ENV = [
+    "ALGENTA_DAEMON_SOCK",
+    "ALGENTA_DAEMON_TCP",
+    "ALGENTA_MOJO_SOCK",
+    "ALGENTA_RUNTIME_DIR"
+  ];
+  /** Point the about-to-be-spawned daemon at a filter-specific socket/port/dir. */
+  applyDaemonEndpointEnv(endpoint, installDir) {
+    const saved = {};
+    for (const key of _RuntimeProvisioner.DAEMON_ENDPOINT_ENV) {
+      saved[key] = process.env[key];
+    }
+    process.env.ALGENTA_DAEMON_SOCK = endpoint.sock;
+    process.env.ALGENTA_DAEMON_TCP = endpoint.tcp;
+    process.env.ALGENTA_MOJO_SOCK = `${endpoint.sock}.worker`;
+    process.env.ALGENTA_RUNTIME_DIR = join2(installDir, ".runtime");
+    return saved;
+  }
+  restoreEnv(saved) {
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === void 0) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  }
   async doEnsure() {
-    const runtime = this.newRuntime();
+    const platformKey = currentPlatformKey();
+    const filter = this.filterModules();
+    const probeEndpoint = filter ? this.filterEndpoint(this.localCacheKey(filter, platformKey)) : void 0;
+    const runtime = this.newRuntime(probeEndpoint ? { tcpAddress: probeEndpoint.tcp } : void 0);
     try {
       const health = await runtime.health();
       if (health.runtime_available) {
@@ -1060,40 +1166,54 @@ var RuntimeProvisioner = class {
       }
     } catch {
     }
-    const platformKey = currentPlatformKey();
-    const bundle = this.options.contract.runtime_bundle;
-    const platformBundle = bundle.platforms[platformKey];
-    if (!platformBundle) {
-      const supported = Object.keys(bundle.platforms);
-      throw new SqaiError(
-        "unsupported_platform",
-        supported.length === 0 ? "No managed runtime bundle is published yet for any platform. Start a local Algenta runtime daemon, or set SQAI_ENGINE_URL / SQAI_API_KEY to use a hosted engine." : `No managed runtime bundle is published for '${platformKey}'.`,
-        { details: { platform: platformKey, supported } }
-      );
+    let version;
+    let installKey;
+    let platformBundle;
+    let endpoint;
+    if (filter) {
+      const resolved = await this.resolveFilteredBundle(filter, platformKey);
+      version = resolved.version;
+      installKey = `filtered-${resolved.cacheKey}`;
+      platformBundle = { url: resolved.url, sha256: resolved.sha256 };
+      endpoint = this.filterEndpoint(resolved.cacheKey);
+    } else {
+      const bundle = this.options.contract.runtime_bundle;
+      const pinned = bundle.platforms[platformKey];
+      if (!pinned) {
+        const supported = Object.keys(bundle.platforms);
+        throw new SqaiError(
+          "unsupported_platform",
+          supported.length === 0 ? "No managed runtime bundle is published yet for any platform. Start a local Algenta runtime daemon, or set SQAI_ENGINE_URL / SQAI_API_KEY to use a hosted engine." : `No managed runtime bundle is published for '${platformKey}'.`,
+          { details: { platform: platformKey, supported } }
+        );
+      }
+      version = bundle.version;
+      installKey = version;
+      platformBundle = pinned;
     }
     if (!this.options.autoInstall) {
       throw new SqaiError(
         "runtime_provision_failed",
         "Automatic runtime installation is disabled (SQAI_RUNTIME_AUTO_INSTALL=0). Install manually with `sqai runtime install` or `sqai runtime install --from-file`.",
-        { details: { platform: platformKey, version: bundle.version } }
+        { details: { platform: platformKey, version } }
       );
     }
-    if (compareRuntimeVersions(bundle.version, this.trustRoot.minAcceptedRuntimeVersion) < 0) {
+    if (compareRuntimeVersions(version, this.trustRoot.minAcceptedRuntimeVersion) < 0) {
       throw new SqaiError(
         "runtime_provision_failed",
-        `Managed runtime ${bundle.version} is below the minimum accepted runtime version ${this.trustRoot.minAcceptedRuntimeVersion} (rollback protection).`,
+        `Managed runtime ${version} is below the minimum accepted runtime version ${this.trustRoot.minAcceptedRuntimeVersion} (rollback protection).`,
         {
           details: {
             reason: "rollback_protected",
             platform: platformKey,
-            version: bundle.version,
+            version,
             min_accepted_version: this.trustRoot.minAcceptedRuntimeVersion
           }
         }
       );
     }
-    const installed = await this.ensureInstalled(platformKey, bundle.version, platformBundle);
-    return this.spawnInstalled(platformKey, installed);
+    const installed = await this.ensureInstalled(platformKey, version, platformBundle, installKey);
+    return this.spawnInstalled(platformKey, installed, endpoint);
   }
   provisionError(reason, message, platformKey, version, extra = {}, retryable = false) {
     return new SqaiError("runtime_provision_failed", message, {
@@ -1135,8 +1255,8 @@ var RuntimeProvisioner = class {
     };
   }
   /** Verify an existing install if present; returns null when absent/invalid. */
-  async verifiedInstallOrNull(platformKey, version, removeOnFailure) {
-    const installDir = join2(this.cacheDir(), version);
+  async verifiedInstallOrNull(platformKey, version, removeOnFailure, installKey = version) {
+    const installDir = join2(this.cacheDir(), installKey);
     try {
       await fs2.access(join2(installDir, MANIFEST_NAME));
     } catch {
@@ -1187,15 +1307,15 @@ var RuntimeProvisioner = class {
       return true;
     }
   }
-  /** Serialize installers on `<cacheDir>/<version>.lock`; returns the verified install. */
-  async ensureInstalled(platformKey, version, platformBundle) {
+  /** Serialize installers on `<cacheDir>/<installKey>.lock`; returns the verified install. */
+  async ensureInstalled(platformKey, version, platformBundle, installKey = version) {
     const cacheDir = this.cacheDir();
     await fs2.mkdir(cacheDir, { recursive: true });
-    const existing = await this.verifiedInstallOrNull(platformKey, version, true);
+    const existing = await this.verifiedInstallOrNull(platformKey, version, true, installKey);
     if (existing) {
       return existing;
     }
-    const lockPath = join2(cacheDir, `${version}.lock`);
+    const lockPath = join2(cacheDir, `${installKey}.lock`);
     const waitTimeoutMs = this.options.lockWaitTimeoutMs ?? LOCK_WAIT_TIMEOUT_MS;
     const pollIntervalMs = this.options.lockPollIntervalMs ?? LOCK_POLL_INTERVAL_MS;
     const deadline = Date.now() + waitTimeoutMs;
@@ -1207,12 +1327,12 @@ var RuntimeProvisioner = class {
         await removeQuietly(lockPath);
         continue;
       }
-      const finished = await this.verifiedInstallOrNull(platformKey, version, false);
+      const finished = await this.verifiedInstallOrNull(platformKey, version, false, installKey);
       if (finished) {
         return finished;
       }
       if (Date.now() >= deadline) {
-        const lastChance = await this.verifiedInstallOrNull(platformKey, version, false);
+        const lastChance = await this.verifiedInstallOrNull(platformKey, version, false, installKey);
         if (lastChance) {
           return lastChance;
         }
@@ -1221,29 +1341,29 @@ var RuntimeProvisioner = class {
           `Another installer holds the runtime install lock for ${version} and did not finish within ${Math.round(waitTimeoutMs / 1e3)}s. Retry, or remove the stale lock from the runtime cache directory.`,
           platformKey,
           version,
-          { lock_file: `${version}.lock` },
+          { lock_file: `${installKey}.lock` },
           true
         );
       }
       await sleep(pollIntervalMs);
     }
     try {
-      const raced = await this.verifiedInstallOrNull(platformKey, version, false);
+      const raced = await this.verifiedInstallOrNull(platformKey, version, false, installKey);
       if (raced) {
         return raced;
       }
-      return await this.downloadVerifyExtract(platformKey, version, platformBundle);
+      return await this.downloadVerifyExtract(platformKey, version, platformBundle, installKey);
     } finally {
       await removeQuietly(lockPath);
     }
   }
   /** Holder-of-the-lock path: download → verify → extract → atomic rename. */
-  async downloadVerifyExtract(platformKey, version, platformBundle) {
+  async downloadVerifyExtract(platformKey, version, platformBundle, installKey = version) {
     const cacheDir = this.cacheDir();
     const token = randomBytes2(6).toString("hex");
     const tarballPath = join2(cacheDir, `tmp-${token}.tgz`);
     const extractDir = join2(cacheDir, `tmp-${token}`);
-    const installDir = join2(cacheDir, version);
+    const installDir = join2(cacheDir, installKey);
     const url = resolveBundleUrl(platformBundle.url, version, platformKey);
     try {
       const download = this.options.downloadBundle ?? defaultDownloadBundle;
@@ -1290,7 +1410,7 @@ var RuntimeProvisioner = class {
       try {
         await fs2.rename(extractDir, installDir);
       } catch (error) {
-        const raced = await this.verifiedInstallOrNull(platformKey, version, false);
+        const raced = await this.verifiedInstallOrNull(platformKey, version, false, installKey);
         if (raced) {
           return raced;
         }
@@ -1309,7 +1429,7 @@ var RuntimeProvisioner = class {
     }
   }
   /** Spawn the installed bundle's daemon through MojoRuntime autoStart. */
-  async spawnInstalled(platformKey, installed) {
+  async spawnInstalled(platformKey, installed, endpoint) {
     const version = installed.manifest.runtime_bundle_version;
     let entryRelative;
     try {
@@ -1322,7 +1442,10 @@ var RuntimeProvisioner = class {
       "start",
       "--foreground"
     ];
-    const managed = this.newRuntime({ autoStart: true, daemonCommand });
+    const managed = this.newRuntime(
+      endpoint ? { autoStart: true, daemonCommand, tcpAddress: endpoint.tcp } : { autoStart: true, daemonCommand }
+    );
+    const savedEnv = endpoint ? this.applyDaemonEndpointEnv(endpoint, installed.installDir) : null;
     try {
       const health = await managed.health();
       if (!health.runtime_available) {
@@ -1346,6 +1469,10 @@ var RuntimeProvisioner = class {
         version,
         { daemon_entry: entryRelative }
       );
+    } finally {
+      if (savedEnv) {
+        this.restoreEnv(savedEnv);
+      }
     }
     try {
       await fs2.writeFile(
@@ -1612,7 +1739,9 @@ var SQAI = class {
     this.resultStore = new ResultStore(config.resultStore);
     this.provisioner = new RuntimeProvisioner({
       contract: this.contractIndex.contract,
-      autoInstall: env.autoInstall
+      autoInstall: env.autoInstall,
+      runtimeModules: config.runtimeModules ?? env.runtimeModules,
+      buildServiceUrl: config.buildServiceUrl ?? env.buildServiceUrl
     });
     if (config.runtime) {
       this.rawRuntime = config.runtime;