chainlesschain 0.166.38 → 0.166.40

package/src/lib/evolution/governed-skill-synthesis-process-grader.js

@@ -0,0 +1,444 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { types as utilTypes } from "node:util";
+
+import executionBroker, {
+  SANDBOX_BOUNDARIES,
+} from "../process-execution-broker/index.js";
+import { BUILT_IN_PROVIDERS } from "../llm-providers.js";
+
+export const GOVERNED_SKILL_SYNTHESIS_PROCESS_GRADER_SCHEMA =
+  "chainlesschain.governed-skill-synthesis-process-grader/v2";
+
+const WORKER = fileURLToPath(
+  new URL(
+    "./governed-skill-synthesis-process-grader-worker.mjs",
+    import.meta.url,
+  ),
+);
+const CREDENTIAL_RESOLVER = fileURLToPath(
+  new URL(
+    "../process-execution-broker/credential-transport.js",
+    import.meta.url,
+  ),
+);
+const PROCESS_GRADERS = new WeakMap();
+const OPTION_KEYS = new Set([
+  "apiKey",
+  "baseUrl",
+  "maxTokens",
+  "memoryLimitMb",
+  "model",
+  "provider",
+  "timeoutMs",
+]);
+const MAX_MESSAGES = 8;
+const MAX_PROMPT_BYTES = 64 * 1024;
+const MAX_OUTPUT_BYTES = 96 * 1024;
+const REQUIRED_SANDBOX_BOUNDARIES = Object.freeze([
+  SANDBOX_BOUNDARIES.PRIVILEGE_REDUCTION,
+  SANDBOX_BOUNDARIES.PROCESS_TREE,
+  SANDBOX_BOUNDARIES.RESOURCE_LIMITS,
+]);
+
+function sha256(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+function plainRecord(value, label, allowedKeys) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    utilTypes.isProxy(value) ||
+    Object.getPrototypeOf(value) !== Object.prototype
+  ) {
+    throw new TypeError(`${label} must be a plain object`);
+  }
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (
+      typeof key !== "string" ||
+      !allowedKeys.has(key) ||
+      !descriptor ||
+      !("value" in descriptor) ||
+      !descriptor.enumerable
+    ) {
+      throw new TypeError(`${label} contains unsupported fields`);
+    }
+  }
+  return value;
+}
+
+function boundedString(value, label, maximum) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > maximum ||
+    value.trim() !== value ||
+    value.includes("\0")
+  ) {
+    throw new TypeError(`${label} must be a non-empty bounded string`);
+  }
+  return value;
+}
+
+function boundedText(value, label, maximum) {
+  if (
+    typeof value !== "string" ||
+    value.trim().length === 0 ||
+    value.length > maximum ||
+    value.includes("\0")
+  ) {
+    throw new TypeError(`${label} must be non-empty bounded text`);
+  }
+  return value;
+}
+
+function boundedInteger(value, label, minimum, maximum) {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new TypeError(`${label} must be from ${minimum} to ${maximum}`);
+  }
+  return value;
+}
+
+function normalizeBaseUrl(provider, value) {
+  const expected = BUILT_IN_PROVIDERS[provider]?.baseUrl;
+  if (!expected) throw new TypeError("process grader provider is unsupported");
+  let actual;
+  try {
+    actual = new URL(value || expected);
+  } catch {
+    throw new TypeError("process grader baseUrl is invalid");
+  }
+  if (
+    actual.protocol !== "https:" ||
+    actual.username ||
+    actual.password ||
+    actual.search ||
+    actual.hash ||
+    actual.href.replace(/\/$/u, "") !==
+      new URL(expected).href.replace(/\/$/u, "")
+  ) {
+    throw new TypeError(
+      "process grader baseUrl must match the credential-free built-in endpoint",
+    );
+  }
+  return actual.href.replace(/\/$/u, "");
+}
+
+function normalizeMessages(value) {
+  if (
+    !Array.isArray(value) ||
+    utilTypes.isProxy(value) ||
+    value.length === 0 ||
+    value.length > MAX_MESSAGES
+  ) {
+    throw new TypeError("process grader messages are invalid");
+  }
+  let bytes = 0;
+  const result = value.map((message, index) => {
+    plainRecord(
+      message,
+      `process grader message ${index}`,
+      new Set(["content", "role"]),
+    );
+    if (!["assistant", "system", "user"].includes(message.role)) {
+      throw new TypeError(`process grader message ${index} role is invalid`);
+    }
+    const content = boundedText(
+      message.content,
+      `process grader message ${index} content`,
+      MAX_PROMPT_BYTES,
+    );
+    bytes += Buffer.byteLength(content, "utf8");
+    return { role: message.role, content };
+  });
+  if (bytes > MAX_PROMPT_BYTES) {
+    throw new TypeError("process grader prompt exceeds 65536 bytes");
+  }
+  return result;
+}
+
+function artifactSnapshot(target, label, maximumBytes) {
+  const stat = fs.lstatSync(target);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) {
+    throw new Error(`${label} is not a single-link regular file`);
+  }
+  const physical = fs.realpathSync.native(target);
+  const bytes = fs.readFileSync(physical);
+  if (bytes.length === 0 || bytes.length > maximumBytes) {
+    throw new Error(`${label} size is invalid`);
+  }
+  return Object.freeze({
+    physical,
+    digest: sha256(bytes),
+    size: bytes.length,
+  });
+}
+
+function executionSnapshot() {
+  return Object.freeze({
+    worker: artifactSnapshot(WORKER, "process grader worker", 128 * 1024),
+    credentialResolver: artifactSnapshot(
+      CREDENTIAL_RESOLVER,
+      "process grader credential resolver",
+      128 * 1024,
+    ),
+  });
+}
+
+function executionSnapshotMatches(left, right) {
+  return ["worker", "credentialResolver"].every(
+    (name) =>
+      left[name].physical === right[name].physical &&
+      left[name].digest === right[name].digest &&
+      left[name].size === right[name].size,
+  );
+}
+
+function minimalProcessEnvironment() {
+  if (process.platform !== "win32") return Object.freeze({});
+  const environment = {};
+  for (const key of ["SystemRoot", "WINDIR", "TEMP", "TMP"]) {
+    const value = process.env[key];
+    if (
+      typeof value === "string" &&
+      value.length > 0 &&
+      value.length <= 32 * 1024 &&
+      !value.includes("\0")
+    ) {
+      environment[key] = value;
+    }
+  }
+  if (!environment.SystemRoot && !environment.WINDIR) {
+    throw new Error("Windows process grader requires a system root");
+  }
+  return Object.freeze(environment);
+}
+
+function runProcess({
+  apiKey,
+  baseUrl,
+  input,
+  snapshot,
+  timeoutMs,
+  memoryLimitMb,
+}) {
+  return new Promise((resolve, reject) => {
+    const child = executionBroker.spawn(
+      process.execPath,
+      [
+        `--max-old-space-size=${memoryLimitMb}`,
+        ...(process.platform === "win32"
+          ? []
+          : [
+              "--experimental-permission",
+              `--allow-fs-read=${snapshot.worker.physical}`,
+              `--allow-fs-read=${snapshot.credentialResolver.physical}`,
+            ]),
+        snapshot.worker.physical,
+      ],
+      {
+        cwd: path.dirname(snapshot.worker.physical),
+        env: {
+          ...minimalProcessEnvironment(),
+          VOLCENGINE_API_KEY: apiKey,
+        },
+        credentialTargetHost: new URL(baseUrl).hostname,
+        credentialTtlMs: Math.min(timeoutMs + 5_000, 125_000),
+        credentialMaxUses: 1,
+        policy: "allow",
+        requirePersistentAudit: true,
+        sandboxPolicy: {
+          profile: "network-only",
+          requiredBoundaries: REQUIRED_SANDBOX_BOUNDARIES,
+        },
+        shell: false,
+        windowsHide: true,
+        stdio: ["pipe", "pipe", "pipe"],
+        origin: "governed-skill-synthesis-process-grader",
+        reason:
+          "Run the bounded learning synthesis grader in a killable process",
+      },
+    );
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let terminalError = null;
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      callback(value);
+    };
+    const timer = setTimeout(() => {
+      terminalError = new Error(
+        `learning synthesis process grader timed out after ${timeoutMs}ms`,
+      );
+      terminalError.code = "LEARNING_SYNTHESIS_PROCESS_GRADER_TIMEOUT";
+      child.kill("SIGKILL");
+    }, timeoutMs);
+    timer.unref?.();
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString("utf8");
+      if (Buffer.byteLength(stdout, "utf8") > MAX_OUTPUT_BYTES) {
+        terminalError = new Error("process grader stdout exceeded its bound");
+        child.kill("SIGKILL");
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+      if (Buffer.byteLength(stderr, "utf8") > MAX_OUTPUT_BYTES) {
+        terminalError = new Error("process grader stderr exceeded its bound");
+        child.kill("SIGKILL");
+      }
+    });
+    child.once("error", (error) => finish(reject, error));
+    child.once("close", (code, signal) => {
+      if (terminalError) return finish(reject, terminalError);
+      if (code !== 0) {
+        return finish(
+          reject,
+          new Error(
+            `learning synthesis process grader exited ${code ?? "null"}/${signal ?? "none"}: ${stderr.slice(0, 256)}`,
+          ),
+        );
+      }
+      try {
+        const lines = stdout.trimEnd().split("\n");
+        if (lines.length !== 1) throw new Error("multiple output records");
+        const message = JSON.parse(lines[0]);
+        plainRecord(
+          message,
+          "process grader output",
+          new Set(["content", "ok"]),
+        );
+        if (message.ok !== true) throw new Error("grader output was not ok");
+        const content = boundedText(
+          message.content,
+          "process grader output content",
+          64 * 1024,
+        );
+        finish(resolve, content);
+      } catch (cause) {
+        finish(
+          reject,
+          new Error("learning synthesis process grader output is invalid", {
+            cause,
+          }),
+        );
+      }
+    });
+    child.stdin.once("error", (error) => {
+      terminalError ??= error;
+    });
+    child.stdin.end(JSON.stringify(input));
+  });
+}
+
+export function createGovernedSkillSynthesisProcessGrader(options = {}) {
+  plainRecord(options, "process grader options", OPTION_KEYS);
+  const provider = boundedString(
+    options.provider,
+    "process grader provider",
+    64,
+  );
+  if (provider !== "volcengine") {
+    throw new TypeError("process grader currently requires volcengine");
+  }
+  const model = boundedString(
+    options.model || BUILT_IN_PROVIDERS[provider].models[0],
+    "process grader model",
+    256,
+  );
+  const apiKey = boundedString(
+    options.apiKey,
+    "process grader credential",
+    16 * 1024,
+  );
+  const baseUrl = normalizeBaseUrl(provider, options.baseUrl);
+  const timeoutMs = boundedInteger(
+    options.timeoutMs ?? 30_000,
+    "process grader timeoutMs",
+    1_000,
+    120_000,
+  );
+  const maxTokens = boundedInteger(
+    options.maxTokens ?? 2_048,
+    "process grader maxTokens",
+    128,
+    4_096,
+  );
+  const memoryLimitMb = boundedInteger(
+    options.memoryLimitMb ?? 128,
+    "process grader memoryLimitMb",
+    32,
+    512,
+  );
+  const credentialTargetHost = new URL(baseUrl).hostname;
+  const credentialTtlMs = Math.min(timeoutMs + 5_000, 125_000);
+  const snapshot = executionSnapshot();
+  const descriptor = Object.freeze({
+    schema: GOVERNED_SKILL_SYNTHESIS_PROCESS_GRADER_SCHEMA,
+    isolation: "process",
+    provider,
+    model,
+    workerArtifactDigest: snapshot.worker.digest,
+    credentialResolverArtifactDigest: snapshot.credentialResolver.digest,
+    inheritedEnvironment: false,
+    credentialDelivery: "single-use-broker-reference",
+    credentialTargetHost,
+    credentialMaxUses: 1,
+    credentialTtlMs,
+    hardDeadlineEnforced: true,
+    sandboxProfile: "network-only",
+    requiredSandboxBoundaries: REQUIRED_SANDBOX_BOUNDARIES,
+    persistentProcessAuditRequired: true,
+  });
+  const port = async (messages) => {
+    const current = executionSnapshot();
+    if (!executionSnapshotMatches(current, snapshot)) {
+      throw new Error(
+        "process grader worker or credential resolver changed after construction",
+      );
+    }
+    const content = await runProcess({
+      snapshot,
+      timeoutMs,
+      memoryLimitMb,
+      apiKey,
+      baseUrl,
+      input: {
+        schema: "chainlesschain.skill-synthesis-process-grader-request/v2",
+        provider,
+        model,
+        baseUrl,
+        maxTokens,
+        timeoutMs,
+        messages: normalizeMessages(messages),
+      },
+    });
+    const after = executionSnapshot();
+    if (!executionSnapshotMatches(after, snapshot)) {
+      throw new Error(
+        "process grader worker or credential resolver changed during execution",
+      );
+    }
+    return content;
+  };
+  Object.freeze(port);
+  PROCESS_GRADERS.set(port, descriptor);
+  return port;
+}
+
+export function isGovernedSkillSynthesisProcessGrader(value) {
+  return PROCESS_GRADERS.has(value);
+}
+
+export function getGovernedSkillSynthesisProcessGraderDescriptor(value) {
+  const descriptor = PROCESS_GRADERS.get(value);
+  return descriptor ? Object.freeze(structuredClone(descriptor)) : null;
+}

package/src/lib/evolution/governed-skill-synthesis-provider-chat.js

@@ -0,0 +1,220 @@
+import { types as utilTypes } from "node:util";
+
+import { createChatFn } from "../cowork-adapter.js";
+import { BUILT_IN_PROVIDERS } from "../llm-providers.js";
+
+const PORTS = new WeakSet();
+const OPTION_KEYS = new Set([
+  "apiKey",
+  "baseUrl",
+  "maxTokens",
+  "model",
+  "provider",
+  "timeoutMs",
+]);
+const MESSAGE_ROLES = new Set(["assistant", "system", "user"]);
+const MAX_MESSAGES = 8;
+const MAX_PROMPT_BYTES = 64 * 1024;
+
+function plainDataRecord(value, label, allowedKeys) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    utilTypes.isProxy(value) ||
+    (Object.getPrototypeOf(value) !== Object.prototype &&
+      Object.getPrototypeOf(value) !== null)
+  ) {
+    throw new TypeError(`${label} must be a plain object`);
+  }
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (
+      typeof key !== "string" ||
+      !allowedKeys.has(key) ||
+      !descriptor ||
+      !("value" in descriptor) ||
+      !descriptor.enumerable
+    ) {
+      throw new TypeError(`${label} contains unsupported fields`);
+    }
+  }
+  return value;
+}
+
+function boundedString(value, label, maximum) {
+  if (
+    typeof value !== "string" ||
+    value.length === 0 ||
+    value.length > maximum ||
+    value.trim() !== value ||
+    value.includes("\0")
+  ) {
+    throw new TypeError(`${label} must be a non-empty bounded string`);
+  }
+  return value;
+}
+
+function boundedContent(value, label, maximum) {
+  if (
+    typeof value !== "string" ||
+    value.trim().length === 0 ||
+    value.length > maximum ||
+    value.includes("\0")
+  ) {
+    throw new TypeError(`${label} must be non-empty bounded text`);
+  }
+  return value;
+}
+
+function boundedInteger(value, label, minimum, maximum) {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new TypeError(
+      `${label} must be an integer from ${minimum} to ${maximum}`,
+    );
+  }
+  return value;
+}
+
+function normalizeBaseUrl(provider, value) {
+  const providerDefinition = BUILT_IN_PROVIDERS[provider];
+  const baseUrl = value || providerDefinition.baseUrl;
+  let parsed;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    throw new TypeError("learning synthesis provider baseUrl is invalid");
+  }
+  if (
+    parsed.protocol !== "https:" ||
+    parsed.username ||
+    parsed.password ||
+    parsed.search ||
+    parsed.hash
+  ) {
+    throw new TypeError(
+      "learning synthesis cloud provider baseUrl must be credential-free HTTPS",
+    );
+  }
+  const expected = new URL(providerDefinition.baseUrl);
+  const normalized = parsed.href.replace(/\/$/u, "");
+  const expectedNormalized = expected.href.replace(/\/$/u, "");
+  if (normalized !== expectedNormalized) {
+    throw new TypeError(
+      "learning synthesis provider baseUrl must match the built-in provider endpoint",
+    );
+  }
+  return normalized;
+}
+
+function normalizeMessages(messages) {
+  if (
+    !Array.isArray(messages) ||
+    utilTypes.isProxy(messages) ||
+    messages.length === 0 ||
+    messages.length > MAX_MESSAGES
+  ) {
+    throw new TypeError(
+      `learning synthesis messages must contain 1 to ${MAX_MESSAGES} entries`,
+    );
+  }
+  let bytes = 0;
+  const normalized = messages.map((message, index) => {
+    plainDataRecord(
+      message,
+      `learning synthesis message ${index}`,
+      new Set(["content", "role"]),
+    );
+    if (!MESSAGE_ROLES.has(message.role)) {
+      throw new TypeError(
+        `learning synthesis message ${index} role is invalid`,
+      );
+    }
+    const content = boundedContent(
+      message.content,
+      `learning synthesis message ${index} content`,
+      MAX_PROMPT_BYTES,
+    );
+    bytes += Buffer.byteLength(content, "utf8");
+    return Object.freeze({ role: message.role, content });
+  });
+  if (bytes > MAX_PROMPT_BYTES) {
+    throw new TypeError(
+      `learning synthesis prompt exceeds ${MAX_PROMPT_BYTES} bytes`,
+    );
+  }
+  return Object.freeze(normalized);
+}
+
+/**
+ * Create the narrow provider egress used by a signed learning deployment.
+ * Credentials stay in the closure and are never exposed on the returned port.
+ */
+export function createGovernedSkillSynthesisProviderChat(options = {}) {
+  plainDataRecord(options, "learning synthesis provider options", OPTION_KEYS);
+  const provider = boundedString(
+    options.provider,
+    "learning synthesis provider",
+    64,
+  );
+  if (provider === "ollama" || !Object.hasOwn(BUILT_IN_PROVIDERS, provider)) {
+    throw new TypeError(
+      "learning synthesis provider must be a supported cloud provider",
+    );
+  }
+  const model = boundedString(
+    options.model || BUILT_IN_PROVIDERS[provider].models[0],
+    "learning synthesis model",
+    256,
+  );
+  const apiKey = boundedString(
+    options.apiKey,
+    "learning synthesis provider credential",
+    16 * 1024,
+  );
+  const baseUrl = normalizeBaseUrl(provider, options.baseUrl);
+  const timeoutMs = boundedInteger(
+    options.timeoutMs ?? 30_000,
+    "learning synthesis provider timeoutMs",
+    1_000,
+    120_000,
+  );
+  const maxTokens = boundedInteger(
+    options.maxTokens ?? 2_048,
+    "learning synthesis provider maxTokens",
+    128,
+    4_096,
+  );
+  const chat = createChatFn({ provider, model, baseUrl, apiKey });
+
+  const port = async (messages) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    timer.unref?.();
+    try {
+      return await chat(normalizeMessages(messages), {
+        maxTokens,
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        const timeout = new Error(
+          `learning synthesis provider timed out after ${timeoutMs}ms`,
+          { cause: error },
+        );
+        timeout.code = "LEARNING_SYNTHESIS_PROVIDER_TIMEOUT";
+        throw timeout;
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  Object.freeze(port);
+  PORTS.add(port);
+  return port;
+}
+
+export function isGovernedSkillSynthesisProviderChat(value) {
+  return PORTS.has(value);
+}