@agentshouse/kit 0.0.1 → 0.1.0-alpha.1

package/src/login.js

@@ -0,0 +1,274 @@
+import { createHash, randomBytes } from "node:crypto";
+import { access, readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { KIT_CREDENTIAL } from "./contract.js";
+import { launchBase, prepareLaunchBase } from "./directory.js";
+import { houseRequest } from "./house.js";
+import { KitRefusal } from "./refusal.js";
+import { writeText } from "./state.js";
+
+const ENVIRONMENT =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function verifier() {
+  return randomBytes(32).toString("base64url");
+}
+
+function challenge(value) {
+  return createHash("sha256").update(value).digest("base64url");
+}
+
+async function waitFor(promise, signal) {
+  if (signal === undefined) return promise;
+  if (signal.aborted) throw new KitRefusal("kit_command_cancelled");
+  let cancel;
+  const cancellation = new Promise((_, reject) => {
+    cancel = () => reject(new KitRefusal("kit_command_cancelled"));
+    signal.addEventListener("abort", cancel, { once: true });
+  });
+  try {
+    return await Promise.race([promise, cancellation]);
+  } catch (error) {
+    if (signal.aborted) throw new KitRefusal("kit_command_cancelled");
+    throw error;
+  } finally {
+    signal.removeEventListener("abort", cancel);
+  }
+}
+
+async function request(options, dependencies, path, body) {
+  return waitFor(
+    houseRequest(options.house, null, path, body, dependencies, options.signal),
+    options.signal,
+  );
+}
+
+function startedLogin(value) {
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    typeof value.start_url !== "string" ||
+    !URL.canParse(value.start_url)
+  ) {
+    throw new KitRefusal("kit_login_rejected");
+  }
+  return { startUrl: value.start_url };
+}
+
+function exchangedCredential(value, retained) {
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    typeof value.credential !== "string" ||
+    !KIT_CREDENTIAL.test(value.credential) ||
+    typeof value.environment !== "string" ||
+    !ENVIRONMENT.test(value.environment) ||
+    (retained !== null && value.environment !== retained)
+  ) {
+    throw new KitRefusal("kit_login_rejected");
+  }
+  return { credential: value.credential, environment: value.environment };
+}
+
+export const ENROLLMENT_USAGE =
+  "kit login [--house <url>] [--environment <uuid>] [--manual]";
+
+export async function storedEnvironment(directory) {
+  let value;
+  try {
+    value = (await readFile(join(directory, "environment"), "utf8")).trim();
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw new KitRefusal("kit_environment_invalid", error.code ?? "unreadable");
+  }
+  if (!ENVIRONMENT.test(value)) throw new KitRefusal("kit_environment_invalid", "stored Environment id is malformed");
+  return value;
+}
+
+async function storedCredentialPresent(directory) {
+  try {
+    await access(join(directory, "credential"));
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw new KitRefusal("kit_environment_invalid", error.code ?? "unreadable credential");
+  }
+}
+
+function houseOrigin(value) {
+  if (typeof value !== "string" || !URL.canParse(value)) {
+    throw new KitRefusal("kit_house_invalid", "House origin is malformed");
+  }
+  const origin = new URL(value);
+  if (origin.origin !== value || !(origin.protocol === "https:" ||
+    (origin.protocol === "http:" && ["127.0.0.1", "localhost"].includes(origin.hostname)))) {
+    throw new KitRefusal("kit_house_invalid", "House origin is malformed");
+  }
+  return value;
+}
+
+export async function storedHouse(directory, firstLogin = false, requested = undefined) {
+  let value;
+  try {
+    value = (await readFile(join(directory, "house"), "utf8")).trim();
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      if ((firstLogin || requested !== undefined) &&
+        await storedEnvironment(directory) === null && !await storedCredentialPresent(directory)) {
+        return houseOrigin(requested ?? "https://agents.house");
+      }
+    }
+    throw new KitRefusal("kit_house_invalid", error.code ?? "unreadable");
+  }
+  houseOrigin(value);
+  if (requested !== undefined && requested !== value) {
+    throw new KitRefusal("kit_house_mismatch", "this Environment is bound to another House origin");
+  }
+  return value;
+}
+
+export function enrollmentAct(options, retained, host) {
+  if (options.label !== undefined || (options.environment !== undefined && !ENVIRONMENT.test(options.environment))) {
+    throw new KitRefusal("kit_login_rejected", ENROLLMENT_USAGE);
+  }
+  const environment = options.environment ?? retained;
+  if (environment === null) {
+    if (typeof host !== "string" || host.trim() === "") {
+      throw new KitRefusal("kit_login_rejected", "computer hostname is empty");
+    }
+    return { retained: null, body: { act: "new_environment", label: host } };
+  }
+  return {
+    retained: environment,
+    body: { act: "existing_environment", environment_id: environment },
+  };
+}
+
+export async function login(options, dependencies = {}) {
+  const open = dependencies.open ?? openBrowser;
+  const readCode = dependencies.readCode ?? manualCode;
+  const write = dependencies.write ?? ((line) => stdout.write(`${line}\n`));
+  const codeVerifier = verifier();
+  const retained = await storedEnvironment(options.directory);
+  if (retained === null && options.environment === undefined &&
+    await storedCredentialPresent(options.directory)) {
+    throw new KitRefusal("kit_environment_invalid", "credential exists without its Environment id");
+  }
+  const act = enrollmentAct(options, retained,
+    options.hostname ?? dependencies.hostname?.() ?? hostname());
+  const body = {
+    ...act.body,
+    code_challenge: challenge(codeVerifier),
+    presentation: options.presentation,
+    ...(options.loopbackUri ? { loopback_uri: options.loopbackUri } : {}),
+  };
+  const started = startedLogin(await request(options, dependencies, "/kit", body));
+  if (options.presentation === "manual" || options.hostBrowser === true) {
+    write(`Open ${started.startUrl}`);
+  } else {
+    await waitFor(Promise.resolve().then(() => open(started.startUrl)), options.signal);
+  }
+  const code = await waitFor(Promise.resolve().then(() => readCode(options.signal)), options.signal);
+  let settled;
+  try {
+    settled = await request(options, dependencies, "/kit/token", {
+      code,
+      code_verifier: codeVerifier,
+    });
+  } catch (error) {
+    if (error instanceof KitRefusal && error.code === "kit_house_unavailable") {
+      throw new KitRefusal(
+        "kit_credential_not_installed",
+        "House did not answer the exchange, so no credential was installed; " +
+          "run kit login again for this Environment to obtain a fresh owner-authorized credential",
+      );
+    }
+    throw error;
+  }
+  const exchanged = exchangedCredential(settled, act.retained);
+  await writeText(join(options.directory, "environment"), `${exchanged.environment}\n`);
+  await writeText(join(options.directory, "house"), `${options.house}\n`);
+  await writeText(
+    join(options.directory, "credential"),
+    `${exchanged.credential}\n`,
+  );
+  write(
+    act.retained === null
+      ? `House Kit Environment ${exchanged.environment} connected.`
+      : `House Kit Environment ${exchanged.environment} reconnected.`,
+  );
+  return { environment: exchanged.environment };
+}
+
+export async function loopback() {
+  const server = createServer();
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const address = server.address();
+  const code = new Promise((resolve, reject) => {
+    server.once("request", (request, response) => {
+      const received = new URL(
+        request.url ?? "/",
+        `http://127.0.0.1:${address.port}`,
+      ).searchParams.get("code");
+      response.writeHead(received ? 200 : 400, {
+        "content-type": "text/plain; charset=utf-8",
+      });
+      response.end(
+        received
+          ? "House Kit connected. You can close this window.\n"
+          : "Login failed.\n",
+      );
+      server.close();
+      if (received) resolve(received);
+      else reject(new KitRefusal("kit_login_rejected"));
+    });
+  });
+  return {
+    uri: `http://127.0.0.1:${address.port}/callback`,
+    code: () => code,
+    close: () => new Promise((resolve) => server.close(() => resolve())),
+  };
+}
+
+export async function manualCode(signal) {
+  const terminal = createInterface({ input: stdin, output: stdout });
+  try {
+    return (await terminal.question("One-time code: ", { signal })).trim();
+  } finally {
+    terminal.close();
+  }
+}
+
+export async function openBrowser(url) {
+  const command =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "cmd"
+        : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  const child = spawn(command, args, { detached: true, stdio: "ignore" });
+  child.unref();
+}
+
+export async function connectHouse(options, dependencies = {}) {
+  await prepareLaunchBase(launchBase(dependencies));
+  if (options.presentation === "manual") return login(options, dependencies);
+  const callback = await loopback();
+  try {
+    return await login(
+      { ...options, presentation: "loopback", loopbackUri: callback.uri },
+      { ...dependencies, readCode: callback.code },
+    );
+  } finally {
+    await callback.close().catch(() => undefined);
+  }
+}

package/src/mcp.js

@@ -0,0 +1,71 @@
+import { randomUUID } from "node:crypto";
+import { bridgePeer } from "./peer.js";
+import { KitRefusal } from "./refusal.js";
+
+export function workerMcpPeer(options) {
+  const client = randomUUID();
+  const pending = new Map();
+  let bridge = null;
+  const peer = bridgePeer({
+    socket: options.socket,
+    nonce: options.nonce,
+    role: "mcp",
+    retryInitial: true,
+    hello: () => ({ client, bridge: [...pending.values()].find((request) => request.bridge !== null)?.bridge ?? null }),
+    greeted: (frame) => {
+      if (frame.type !== "ready" || typeof frame.bridge !== "string") return false;
+      if ([...pending.values()].some((request) => request.bridge !== null && request.bridge !== frame.bridge)) return false;
+      bridge = frame.bridge;
+      for (const retained of pending.values()) peer.send(retained.message);
+      return true;
+    },
+    onSend: (frame) => {
+      const retained = pending.get(frame.delivery);
+      if (frame.type === "mcp" && retained !== undefined) retained.bridge = bridge;
+    },
+    onFrame: (frame) => {
+      if (frame.type !== "mcp") {
+        options.onClosed?.(frame);
+        return;
+      }
+      if (pending.delete(frame.delivery) && frame.frame !== null) options.onFrame(frame.frame);
+      peer.send({ type: "ack", delivery: frame.delivery });
+    },
+  });
+  return {
+    open: peer.open,
+    refused: peer.refused,
+    send(frame) {
+      const delivery = randomUUID();
+      const retained = { type: "mcp", delivery, frame: structuredClone(frame) };
+      pending.set(delivery, { message: retained, bridge: null });
+      peer.send(retained);
+    },
+    end() {
+      pending.clear();
+      return peer.end();
+    },
+  };
+}
+
+export async function bridgeCall(bridge, request, signal = undefined) {
+  let accept;
+  let refuse;
+  const response = new Promise((resolve, reject) => { accept = resolve; refuse = reject; });
+  const peer = workerMcpPeer({
+    socket: bridge.socket,
+    nonce: bridge.nonce,
+    onFrame: accept,
+    onClosed: () => refuse(new KitRefusal("kit_bridge_refused")),
+  });
+  signal?.addEventListener("abort", () => refuse(signal.reason), { once: true });
+  void peer.open().then((greeting) => {
+    if (greeting?.type !== "ready") refuse(new KitRefusal("kit_bridge_refused"));
+    else peer.send({ jsonrpc: "2.0", id: 1, ...request });
+  }, refuse);
+  try {
+    return await Promise.race([response, peer.refused]);
+  } finally {
+    await peer.end();
+  }
+}

package/src/migrator.js

@@ -0,0 +1,248 @@
+import { lstat, readdir, readFile, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { basename, join, resolve } from "node:path";
+import { runCommand } from "./command.js";
+import {
+  MIGRATOR_ATTACHMENTS_HOME,
+  MIGRATOR_ATTACHMENTS_MAX,
+  MIGRATOR_CATEGORY,
+  MIGRATOR_CONTENT_HOME,
+  MIGRATOR_CONTRACT,
+  MIGRATOR_DOWNLOAD_OUTCOMES,
+  MIGRATOR_MANIFEST,
+  MIGRATOR_MODEL_HOME,
+  MIGRATOR_OUTPUT_MAX_BYTES,
+} from "./contract.js";
+import { declarationReader } from "./declaration.js";
+import { KitRefusal } from "./refusal.js";
+
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const MARKDOWN = /\.md$/;
+const NUL = "\u0000";
+
+const { refuse, closed, text, optionalText, filled } = declarationReader(
+  "kit_migrator_manifest_invalid",
+);
+
+function packageRefusal(code, detail) {
+  return new KitRefusal(code, detail);
+}
+
+function relativePath(value, declaration) {
+  const path = text(value, declaration, 2048);
+  const segments = path.split("/");
+  if (segments.some((segment) => !SEGMENT.test(segment))) refuse(declaration);
+  return path;
+}
+
+function attachmentOf(value, position) {
+  const declaration = `attachments[${position}]`;
+  const entry = closed(
+    value,
+    ["path", "source", "name", "media_type", "download", "failure", "referrers"],
+    declaration,
+  );
+  if (!MIGRATOR_DOWNLOAD_OUTCOMES.includes(entry.download)) refuse(`${declaration}.download`);
+  const downloaded = entry.download === "downloaded";
+  if (downloaded === (entry.failure !== undefined)) refuse(`${declaration}.failure`);
+  if (downloaded !== (entry.path !== undefined)) refuse(`${declaration}.path`);
+  const referrers = filled(entry.referrers, `${declaration}.referrers`).map((referrer, index) =>
+    relativePath(referrer, `${declaration}.referrers[${index}]`),
+  );
+  if (referrers.some((referrer) => !MARKDOWN.test(referrer))) {
+    refuse(`${declaration}.referrers`);
+  }
+  const path = downloaded ? relativePath(entry.path, `${declaration}.path`) : null;
+  return {
+    path,
+    source: text(entry.source, `${declaration}.source`, 2048),
+    name:
+      optionalText(entry.name, `${declaration}.name`, 255) ??
+      (path === null ? null : basename(path)),
+    mediaType: optionalText(entry.media_type, `${declaration}.media_type`, 255),
+    download: entry.download,
+    failure: optionalText(entry.failure, `${declaration}.failure`, 255),
+    referrers,
+  };
+}
+
+export function parseManifest(document) {
+  const declared = closed(
+    document,
+    ["contract", "category", "migrator", "attachments"],
+    "manifest",
+  );
+  if (declared.contract !== MIGRATOR_CONTRACT) refuse("manifest.contract");
+  if (declared.category !== MIGRATOR_CATEGORY) refuse("manifest.category");
+  const attachments = declared.attachments === undefined ? [] : declared.attachments;
+  if (!Array.isArray(attachments) || attachments.length > MIGRATOR_ATTACHMENTS_MAX) {
+    refuse("manifest.attachments");
+  }
+  const parsed = attachments.map((entry, position) => attachmentOf(entry, position));
+  const paths = parsed.flatMap((entry) => (entry.path === null ? [] : [entry.path]));
+  if (new Set(paths).size !== paths.length) refuse("manifest.attachments");
+  return {
+    contract: declared.contract,
+    category: declared.category,
+    migrator: text(declared.migrator, "manifest.migrator", 128),
+    attachments: parsed,
+  };
+}
+
+async function listTree(root, prefix = "") {
+  let entries;
+  try {
+    if (!(await lstat(join(root, prefix))).isDirectory()) {
+      throw packageRefusal("kit_migrator_package_invalid", prefix || root);
+    }
+    entries = await readdir(join(root, prefix), { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  const found = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    const relative = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (!SEGMENT.test(entry.name)) {
+      throw packageRefusal("kit_migrator_package_invalid", relative);
+    }
+    if (entry.isDirectory()) {
+      found.push(...(await listTree(root, relative)));
+      continue;
+    }
+    if (!entry.isFile()) throw packageRefusal("kit_migrator_package_invalid", relative);
+    found.push(relative);
+  }
+  return found;
+}
+
+async function readTextTree(root, home) {
+  const files = {};
+  for (const relative of await listTree(join(root, home))) {
+    let content;
+    try {
+      content = new TextDecoder("utf-8", { fatal: true }).decode(await readFile(join(root, home, relative)));
+    } catch {
+      throw packageRefusal("kit_migrator_binary_content", `${home}/${relative}`);
+    }
+    if (content.includes(NUL)) {
+      throw packageRefusal("kit_migrator_binary_content", `${home}/${relative}`);
+    }
+    files[relative] = content;
+  }
+  return files;
+}
+
+async function readAttachments(root, manifest) {
+  const declared = new Map(
+    manifest.attachments.flatMap((entry) => (entry.path === null ? [] : [[entry.path, entry]])),
+  );
+  const held = new Map();
+  for (const relative of await listTree(join(root, MIGRATOR_ATTACHMENTS_HOME))) {
+    if (!declared.has(relative)) {
+      throw packageRefusal("kit_migrator_attachment_undeclared", relative);
+    }
+    const absolute = join(root, MIGRATOR_ATTACHMENTS_HOME, relative);
+    const bytes = await readFile(absolute);
+    held.set(relative, {
+      path: relative,
+      file: absolute,
+      bytes: bytes.length,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+    });
+  }
+  for (const relative of declared.keys()) {
+    if (!held.has(relative)) throw packageRefusal("kit_migrator_attachment_missing", relative);
+  }
+  return held;
+}
+
+export async function readMigratorPackage(directory) {
+  const root = resolve(directory);
+  let document;
+  try {
+    document = JSON.parse(await readFile(join(root, MIGRATOR_MANIFEST), "utf8"));
+  } catch {
+    throw packageRefusal("kit_migrator_manifest_unreadable", MIGRATOR_MANIFEST);
+  }
+  const manifest = parseManifest(document);
+  if ((await listTree(root)).some((path) => path === "content/MIGRATION.md")) {
+    throw packageRefusal("kit_migrator_report_reserved", "content/MIGRATION.md");
+  }
+  const content = await readTextTree(root, MIGRATOR_CONTENT_HOME);
+  if (Object.keys(content).length === 0) {
+    throw packageRefusal("kit_migrator_content_empty", MIGRATOR_CONTENT_HOME);
+  }
+  for (const relative of Object.keys(content)) {
+    if (relative === "types" || relative.startsWith("types/")) {
+      throw packageRefusal("kit_migrator_types_alias", `${MIGRATOR_CONTENT_HOME}/${relative}`);
+    }
+    if (relative.split("/").includes("_provenance")) {
+      throw packageRefusal(
+        "kit_migrator_provenance_refused",
+        `${MIGRATOR_CONTENT_HOME}/${relative}`,
+      );
+    }
+    if (!MARKDOWN.test(relative)) {
+      throw packageRefusal("kit_migrator_content_invalid", `${MIGRATOR_CONTENT_HOME}/${relative}`);
+    }
+  }
+  const model = await readTextTree(root, MIGRATOR_MODEL_HOME);
+  for (const relative of Object.keys(model)) {
+    if (relative.includes("/") || !MARKDOWN.test(relative)) {
+      throw packageRefusal("kit_migrator_model_invalid", `${MIGRATOR_MODEL_HOME}/${relative}`);
+    }
+  }
+  for (const entry of manifest.attachments) {
+    for (const referrer of entry.referrers) {
+      if (content[referrer] === undefined) {
+        throw packageRefusal("kit_migrator_referrer_unknown", referrer);
+      }
+    }
+  }
+  return {
+    root,
+    manifest,
+    model,
+    content,
+    attachments: await readAttachments(root, manifest),
+  };
+}
+
+export function migratorRequest(declaration, directory) {
+  return `${JSON.stringify({
+    contract: MIGRATOR_CONTRACT,
+    migrator: declaration.id,
+    package: directory,
+  })}\n`;
+}
+
+export async function emitMigratorPackage(declaration, options) {
+  const directory = resolve(options.package);
+  if (await lstat(directory).catch(() => null)) {
+    throw packageRefusal("kit_migrator_output_exists", directory);
+  }
+  let run;
+  try {
+    run = await runCommand({
+      command: declaration.command,
+      environment: options.environment,
+      stdin: migratorRequest(declaration, directory),
+      timeoutMs: declaration.timeoutMs,
+      outputMaxBytes: MIGRATOR_OUTPUT_MAX_BYTES,
+      signal: options.signal,
+    });
+  } catch (error) {
+    throw new KitRefusal(error instanceof KitRefusal ? error.code : "kit_migrator_failed");
+  }
+  if (run.status !== 0) throw new KitRefusal("kit_migrator_failed", `${run.status}`);
+  const emitted = await stat(directory).catch(() => null);
+  if (emitted === null || !emitted.isDirectory()) {
+    throw packageRefusal("kit_migrator_package_missing", directory);
+  }
+  const held = await readMigratorPackage(directory);
+  if (held.manifest.migrator !== declaration.id) {
+    throw packageRefusal("kit_migrator_identity_mismatch", declaration.id);
+  }
+  return directory;
+}