@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/scripts/generate-run-schemas.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import TJS from "typescript-json-schema";
+import { Ajv } from "ajv";
+import standaloneCode from "ajv/dist/standalone/index.js";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function stableDefinitionNames(definitions) {
+  // TJS uses TypeScript display names; NodeNext import qualifiers include the checkout path.
+  // Normalize identifiers only, preserving the module suffix and every schema value.
+  // TJS also strips spaces from display names, including spaces in that qualifier.
+  const prefix = `import(${JSON.stringify(`${root}/`).slice(0, -1)}`.replaceAll(" ", "");
+  const names = Object.fromEntries(
+    Object.keys(definitions).map((name) => [name, name.replaceAll(prefix, 'import("')]),
+  );
+  if (new Set(Object.values(names)).size !== Object.keys(names).length) {
+    throw new Error("Canonical schema definition names collide after path normalization.");
+  }
+  return names;
+}
+
+function stableSchema(schema, names, refs) {
+  if (typeof schema === "boolean") {
+    return schema;
+  }
+  const result = { ...schema };
+  if (typeof schema.$ref === "string" && Object.hasOwn(refs, schema.$ref)) {
+    result.$ref = refs[schema.$ref];
+  }
+  for (const key of ["definitions", "properties", "patternProperties", "dependencies"]) {
+    if (schema[key] !== undefined) {
+      result[key] = Object.fromEntries(
+        Object.entries(schema[key]).map(([name, value]) => [
+          key === "definitions" ? (names[name] ?? name) : name,
+          Array.isArray(value) ? value : stableSchema(value, names, refs),
+        ]),
+      );
+    }
+  }
+  for (const key of [
+    "items",
+    "additionalItems",
+    "additionalProperties",
+    "contains",
+    "propertyNames",
+    "if",
+    "then",
+    "else",
+    "not",
+    "allOf",
+    "anyOf",
+    "oneOf",
+  ]) {
+    const value = schema[key];
+    if (value !== undefined) {
+      result[key] = Array.isArray(value)
+        ? value.map((entry) => stableSchema(entry, names, refs))
+        : stableSchema(value, names, refs);
+    }
+  }
+  return result;
+}
+
+function normalizeDefinitionPaths(schema) {
+  const names = stableDefinitionNames(schema.definitions);
+  const refs = Object.fromEntries(
+    Object.entries(names).map(([name, stable]) => [
+      `#/definitions/${encodeURIComponent(name)}`,
+      `#/definitions/${encodeURIComponent(stable)}`,
+    ]),
+  );
+  return stableSchema(schema, names, refs);
+}
+
+function standaloneValidators(schema, names) {
+  const validator = new Ajv({
+    strict: false,
+    allErrors: true,
+    strictNumbers: true,
+    inlineRefs: false,
+    code: { esm: true, source: true },
+  });
+  validator.addSchema(schema, "run");
+  const refs = Object.fromEntries(
+    names.map((name) => [
+      name,
+      name === "SupervisorQuestionView"
+        ? "run#/definitions/SupervisorQuestionView/properties/revival"
+        : `run#/definitions/${name}`,
+    ]),
+  );
+  for (const [name, ref] of Object.entries(refs)) {
+    validator.addSchema({ $ref: ref }, name);
+  }
+  return `// Generated by scripts/generate-run-schemas.mjs; do not edit.\n${standaloneCode(validator, Object.fromEntries(names.map((name) => [name, name])))}\n`;
+}
+
+function validatorDeclarations(names) {
+  const types = {
+    SubagentRunConfig: "SubagentRunConfig",
+    NativeFinalizationConfig: "NativeFinalizationConfig",
+    NativeFinalizationEvent: "NativeFinalizationEvent",
+    SupervisorQuestionView: 'NonNullable<Run.SupervisorQuestionView["revival"]>',
+  };
+  return [
+    "// Generated by scripts/generate-run-schemas.mjs; do not edit.",
+    'import type { ValidateFunction } from "ajv";',
+    'import type * as Run from "../src/shared/types.ts";',
+    'import type { SubagentRunConfig } from "../src/runs/background/runner-config.ts";',
+    'import type { NativeFinalizationConfig, NativeFinalizationEvent } from "../src/runs/shared/native-finalization-types.ts";',
+    ...names.map(
+      (name) => `export const ${name}: ValidateFunction<${types[name] ?? `Run.${name}`}>;`,
+    ),
+    "",
+  ].join("\n");
+}
+
+function publishArtifact(target, content, mode) {
+  if (mode !== "--check") {
+    fs.writeFileSync(target, content);
+    return;
+  }
+  if (fs.readFileSync(target, "utf8") !== content) {
+    throw new Error(`Stale ${path.basename(target)}. Run node scripts/generate-run-schemas.mjs.`);
+  }
+}
+
+const mode = process.argv[2];
+if (mode === "--help" || mode === "-h") {
+  console.log(
+    "Usage: node scripts/generate-run-schemas.mjs [--check]\nGenerate runtime JSON schemas and standalone validators from canonical persisted run types.\nExamples:\n  node scripts/generate-run-schemas.mjs\n  node scripts/generate-run-schemas.mjs --check",
+  );
+} else {
+  if (mode !== undefined && mode !== "--check") {
+    throw new Error(`Unknown argument: ${mode}`);
+  }
+  const inputs = [
+    "src/shared/types/async.ts",
+    "src/shared/types/owned-runs.ts",
+    "src/shared/types/questions.ts",
+    "src/shared/types/history.ts",
+    "src/shared/types/details.ts",
+    "src/runs/background/runner-config.ts",
+    "src/runs/shared/native-finalization-types.ts",
+  ].map((file) => path.join(root, file));
+  const program = TJS.getProgramFromFiles(
+    inputs,
+    {
+      strict: true,
+      noImplicitReturns: true,
+      skipLibCheck: true,
+      target: "ESNext",
+      lib: ["ESNext"],
+      module: "NodeNext",
+      moduleResolution: "NodeNext",
+      allowImportingTsExtensions: true,
+      resolveJsonModule: true,
+    },
+    root,
+  );
+  const generator = TJS.buildGenerator(program, {
+    required: true,
+    aliasRef: true,
+    defaultNumberType: "number",
+  });
+  if (generator === null) {
+    throw new Error("Canonical run types could not be compiled for schema generation.");
+  }
+  const names = [
+    "AsyncStatus",
+    "AsyncResultFile",
+    "ForegroundResumeRun",
+    "OwnedRun",
+    "AsyncStartedEvent",
+    "ControlEvent",
+    "SupervisorRunContract",
+    "SupervisorQuestion",
+    "QuestionAnswer",
+    "QuestionDelivery",
+    "SupervisorQuestionView",
+    "HistoryRunRow",
+    "HistoryRunPage",
+    "HistoryPage",
+    "HistorySearchPage",
+    "HistoryIndexStatus",
+    "HistoryEntry",
+    "HistoryResult",
+    "Details",
+    "SubagentExecutionResult",
+    "SubagentRunConfig",
+    "NativeFinalizationConfig",
+    "NativeFinalizationEvent",
+  ];
+  const schema = normalizeDefinitionPaths(generator.getSchemaForSymbols(names));
+  const artifacts = {
+    "src/runs/background/schemas/RunContracts.json": `${JSON.stringify(schema, null, 2)}\n`,
+    "generated/RunValidators.js": standaloneValidators(schema, names),
+    "generated/RunValidators.d.ts": validatorDeclarations(names),
+  };
+  fs.mkdirSync(path.join(root, "generated"), { recursive: true });
+  for (const [name, content] of Object.entries(artifacts)) {
+    publishArtifact(path.join(root, name), content, mode);
+  }
+  console.log(
+    `${mode === "--check" ? "Verified" : "Generated"} ${names.length} canonical run schemas and standalone validators.`,
+  );
+}

package/scripts/intercom-bridge-credentials.mjs

@@ -1,10 +1,26 @@
 #!/usr/bin/env node
 import { execFileSync } from "node:child_process";
 import { randomBytes, X509Certificate } from "node:crypto";
-import { lstatSync, mkdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
+import {
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  rmdirSync,
+  writeFileSync,
+} from "node:fs";
 import { resolve, join } from "node:path";
 import { parseArgs } from "node:util";
 
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
 function help() {
   console.log(`Usage: node scripts/intercom-bridge-credentials.mjs <init|issue|revoke> DIR [NAME] [--cwd PATH]
 
@@ -31,8 +47,12 @@ Never transfer ca.key or server.key to the remote host.`);
 
 function privatePath(path, directory = false) {
   const st = lstatSync(path);
-  if (st.isSymbolicLink() || !(directory ? st.isDirectory() : st.isFile()) ||
-      st.uid !== process.getuid() || (st.mode & 0o077)) {
+  if (
+    st.isSymbolicLink() ||
+    !(directory ? st.isDirectory() : st.isFile()) ||
+    st.uid !== process.getuid() ||
+    st.mode & 0o077
+  ) {
     throw new Error(`Expected an owned, private ${directory ? "directory" : "file"}: ${path}`);
   }
 }
@@ -48,7 +68,10 @@ function atomicConfig(path, config) {
 }
 
 function openssl(...args) {
-  execFileSync(process.env.OPENSSL || "openssl", args, { stdio: ["ignore", "pipe", "pipe"], timeout: 30000 });
+  execFileSync(process.env.OPENSSL || "openssl", args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 30000,
+  });
 }
 
 function key(path) {
@@ -64,27 +87,85 @@ function issueCertificate(dir, stem, name, server = false) {
   key(keyPath);
   try {
     openssl("req", "-new", "-key", keyPath, "-subj", `/CN=${name}`, "-out", csrPath);
-    writeFileSync(extPath, `basicConstraints=critical,CA:FALSE\nkeyUsage=critical,digitalSignature\nextendedKeyUsage=${server ? "serverAuth" : "clientAuth"}\n${server ? "subjectAltName=DNS:localhost,IP:127.0.0.1\n" : ""}`, { mode: 0o600, flag: "wx" });
-    openssl("x509", "-req", "-in", csrPath, "-CA", join(dir, "ca.crt"), "-CAkey", join(dir, "ca.key"),
-      "-set_serial", `0x${randomBytes(16).toString("hex")}`, "-days", server ? "365" : "7", "-sha256", "-extfile", extPath, "-out", certPath);
+    writeFileSync(
+      extPath,
+      `basicConstraints=critical,CA:FALSE\nkeyUsage=critical,digitalSignature\nextendedKeyUsage=${server ? "serverAuth" : "clientAuth"}\n${server ? "subjectAltName=DNS:localhost,IP:127.0.0.1\n" : ""}`,
+      { mode: 0o600, flag: "wx" },
+    );
+    openssl(
+      "x509",
+      "-req",
+      "-in",
+      csrPath,
+      "-CA",
+      join(dir, "ca.crt"),
+      "-CAkey",
+      join(dir, "ca.key"),
+      "-set_serial",
+      `0x${randomBytes(16).toString("hex")}`,
+      "-days",
+      server ? "365" : "7",
+      "-sha256",
+      "-extfile",
+      extPath,
+      "-out",
+      certPath,
+    );
   } finally {
     rmSync(csrPath, { force: true });
     rmSync(extPath, { force: true });
   }
   const cert = new X509Certificate(readFileSync(certPath));
-  return { cert: certPath, key: keyPath, fingerprint256: cert.fingerprint256, expires: cert.validTo };
+  return {
+    cert: certPath,
+    key: keyPath,
+    fingerprint256: cert.fingerprint256,
+    expires: cert.validTo,
+  };
+}
+
+function readConfig(path) {
+  const config = JSON.parse(readFileSync(path, "utf8"));
+  if (!isRecord(config) || !Array.isArray(config.clients) || typeof config.ca !== "string") {
+    throw new Error("Invalid clients allowlist.");
+  }
+  const clients = config.clients.map((client) => {
+    if (
+      !isRecord(client) ||
+      typeof client.name !== "string" ||
+      typeof client.cwd !== "string" ||
+      typeof client.fingerprint256 !== "string"
+    ) {
+      throw new Error("Invalid client identity.");
+    }
+    return { ...client, name: client.name, cwd: client.cwd, fingerprint256: client.fingerprint256 };
+  });
+  return { ...config, ca: config.ca, clients };
 }
 
 let args;
 try {
-  args = parseArgs({ allowPositionals: true, options: { help: { type: "boolean", short: "h" }, cwd: { type: "string" } } });
-  if (args.values.help) { help(); process.exit(0); }
+  args = parseArgs({
+    allowPositionals: true,
+    options: { help: { type: "boolean", short: "h" }, cwd: { type: "string" } },
+  });
+  if (args.values.help) {
+    help();
+    process.exit(0);
+  }
   const [action, dir, name] = args.positionals;
-  if (!["init", "issue", "revoke"].includes(action) || !dir || args.positionals.length > 3 ||
-      (action !== "init" && !name) || (name && !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name)) ||
-      (action === "revoke" && args.values.cwd)) throw new Error("Invalid arguments; use --help.");
+  if (
+    !["init", "issue", "revoke"].includes(action) ||
+    !dir ||
+    args.positionals.length > 3 ||
+    (action !== "init" && !name) ||
+    (name && !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name)) ||
+    (action === "revoke" && args.values.cwd)
+  ) {
+    throw new Error("Invalid arguments; use --help.");
+  }
 } catch (error) {
-  console.error(error.message);
+  console.error(errorMessage(error));
   process.exit(2);
 }
 
@@ -96,44 +177,90 @@ try {
   const name = suppliedName || "grok-bot";
   const configPath = join(dir, "config.json");
   let config;
-  if (action === "init") mkdirSync(dir, { mode: 0o700 }); // Never overwrite a CA.
+  if (action === "init") {
+    // Never overwrite a CA.
+    mkdirSync(dir, { mode: 0o700 });
+  }
   privatePath(dir, true);
   const lockPath = join(dir, ".credentials.lock");
-  try { mkdirSync(lockPath, { mode: 0o700 }); }
-  catch (error) {
-    if (error.code === "EEXIST") throw new Error(`Another credential command holds ${lockPath}; inspect its owner before retrying.`);
+  try {
+    mkdirSync(lockPath, { mode: 0o700 });
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+      throw new Error(
+        `Another credential command holds ${lockPath}; inspect its owner before retrying.`,
+        { cause: error },
+      );
+    }
     throw error;
   }
   lock = lockPath;
   writeFileSync(join(lock, "owner"), `${process.pid}\n`, { mode: 0o600, flag: "wx" });
   if (action === "init") {
     key(join(dir, "ca.key"));
-    openssl("req", "-new", "-x509", "-key", join(dir, "ca.key"), "-days", "3650", "-sha256", "-subj", "/CN=Pi Intercom Bridge CA",
-      "-addext", "basicConstraints=critical,CA:TRUE,pathlen:0", "-addext", "keyUsage=critical,keyCertSign,cRLSign", "-out", join(dir, "ca.crt"));
+    openssl(
+      "req",
+      "-new",
+      "-x509",
+      "-key",
+      join(dir, "ca.key"),
+      "-days",
+      "3650",
+      "-sha256",
+      "-subj",
+      "/CN=Pi Intercom Bridge CA",
+      "-addext",
+      "basicConstraints=critical,CA:TRUE,pathlen:0",
+      "-addext",
+      "keyUsage=critical,keyCertSign,cRLSign",
+      "-out",
+      join(dir, "ca.crt"),
+    );
     const server = issueCertificate(dir, "server", "localhost", true);
-    config = { port: 9443, ca: join(dir, "ca.crt"), cert: server.cert, key: server.key, clients: [] };
+    config = {
+      port: 9443,
+      ca: join(dir, "ca.crt"),
+      cert: server.cert,
+      key: server.key,
+      clients: [],
+    };
   } else {
     privatePath(dir, true);
     privatePath(configPath);
-    config = JSON.parse(readFileSync(configPath, "utf8"));
-    if (!Array.isArray(config.clients)) throw new Error("Invalid clients allowlist.");
+    config = readConfig(configPath);
   }
   if (action === "revoke") {
-    if (!config.clients.some((client) => client.name === name)) throw new Error(`No authorized client named ${name}.`);
+    if (!config.clients.some((client) => client.name === name)) {
+      throw new Error(`No authorized client named ${name}.`);
+    }
     config.clients = config.clients.filter((client) => client.name !== name);
     atomicConfig(configPath, config);
-    console.log(JSON.stringify({ revoked: name, config: configPath, next: "Send SIGHUP to the helper PID." }));
+    console.log(
+      JSON.stringify({ revoked: name, config: configPath, next: "Send SIGHUP to the helper PID." }),
+    );
   } else {
     privatePath(join(dir, "ca.key"));
     const credential = issueCertificate(dir, `${name}-${randomBytes(8).toString("hex")}`, name);
     const previous = config.clients.find((client) => client.name === name);
     config.clients = config.clients.filter((client) => client.name !== name);
-    config.clients.push({ fingerprint256: credential.fingerprint256, name, cwd: resolve(args.values.cwd || previous?.cwd || process.cwd()) });
+    config.clients.push({
+      fingerprint256: credential.fingerprint256,
+      name,
+      cwd: resolve(args.values.cwd || previous?.cwd || process.cwd()),
+    });
     atomicConfig(configPath, config);
-    console.log(JSON.stringify({ name, ...credential, ca: config.ca, config: configPath, next: "Transfer only client cert/key and ca.crt; reload helper allowlist with SIGHUP." }));
+    console.log(
+      JSON.stringify({
+        name,
+        ...credential,
+        ca: config.ca,
+        config: configPath,
+        next: "Transfer only client cert/key and ca.crt; reload helper allowlist with SIGHUP.",
+      }),
+    );
   }
 } catch (error) {
-  console.error(error.message);
+  console.error(errorMessage(error));
   process.exitCode = 1;
 } finally {
   if (lock) {