@agentshouse/kit 0.0.1 → 0.1.0-alpha.1

package/package.json

@@ -1,7 +1,37 @@
 {
   "name": "@agentshouse/kit",
-  "version": "0.0.1",
-  "description": "House Kit. Placeholder that reserves the name; real releases come from agentshouse/kit's publish workflow.",
+  "version": "0.1.0-alpha.1",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/agentshouse/kit.git" }
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentshouse/kit.git"
+  },
+  "private": false,
+  "type": "module",
+  "bin": {
+    "kit": "bin/kit.js"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.5.0",
+    "@agentshouse/mdmodel": "0.1.0-alpha.12",
+    "yaml": "2.9.1",
+    "zod": "4.6.5"
+  },
+  "packageManager": "npm@11.19.0",
+  "engines": {
+    "node": "24.21.0",
+    "npm": "11.19.0"
+  },
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": "24.21.0",
+      "onFail": "error"
+    },
+    "packageManager": {
+      "name": "npm",
+      "version": "11.19.0",
+      "onFail": "error"
+    }
+  }
 }

package/src/acp.js

@@ -0,0 +1,99 @@
+import { Readable, Writable } from "node:stream";
+import { client, ndJsonStream, RequestError } from "@agentclientprotocol/sdk";
+import {
+  ACP_CLIENT_INFO,
+  ADAPTER_EXIT_GRACE_MS,
+  ELICITATION_CREATE,
+  REQUEST_PERMISSION,
+  SESSION_UPDATE,
+} from "./contract.js";
+import { KitRefusal } from "./refusal.js";
+
+function observedStream(adapter, observed) {
+  const framed = ndJsonStream(Writable.toWeb(adapter.stdin), Readable.toWeb(adapter.stdout));
+  const writer = framed.writable.getWriter();
+  return {
+    readable: framed.readable,
+    writable: new WritableStream({
+      write: (message) => {
+        if (message?.method === "initialize") observed.initialize = message.params;
+        return writer.write(message);
+      },
+      close: () => writer.close(),
+      abort: (reason) => writer.abort(reason),
+    }),
+  };
+}
+
+export function acpClient(adapter, handlers) {
+  const app = client({ name: ACP_CLIENT_INFO.name });
+  if (handlers.onPermission !== undefined) {
+    app.onRequest(REQUEST_PERMISSION, ({ params }) => handlers.onPermission(params));
+  }
+  if (handlers.onElicitation !== undefined) {
+    app.onRequest(ELICITATION_CREATE, ({ params, requestId }) =>
+      handlers.onElicitation({ id: requestId, params }),
+    );
+  }
+  if (handlers.onNativeQuestion !== undefined) {
+    app.onRequest(
+      "x.ai/ask_user_question",
+      (value) => value,
+      ({ params, requestId }) => handlers.onNativeQuestion({ id: requestId, params }),
+    );
+  }
+  app.onNotification(SESSION_UPDATE, ({ params }) => handlers.onUpdate(params));
+
+  const observed = { initialize: null };
+  let failure = null;
+  let announce;
+  const stopped = new Promise((resolve) => {
+    announce = resolve;
+  });
+  const fail = (refusal) => {
+    failure ??= refusal;
+    announce(failure);
+  };
+  adapter.on("error", () => fail(new KitRefusal("kit_adapter_unavailable")));
+  adapter.on("close", (status) => fail(new KitRefusal("kit_adapter_exited", `${status}`)));
+  adapter.stdin.on("error", () => undefined);
+  const connection = app.connect(observedStream(adapter, observed));
+
+  async function refusalFor(error) {
+    if (error instanceof RequestError) {
+      const refusal = new KitRefusal("kit_adapter_failed", error.message);
+      refusal.protocolCode = error.code;
+      return refusal;
+    }
+    if (failure !== null) return failure;
+    let grace;
+    try {
+      return await Promise.race([
+        stopped,
+        new Promise((resolve) => {
+          grace = setTimeout(
+            () => resolve(new KitRefusal("kit_adapter_failed", "adapter channel closed")),
+            ADAPTER_EXIT_GRACE_MS,
+          ).unref();
+        }),
+      ]);
+    } finally {
+      clearTimeout(grace);
+    }
+  }
+
+  return {
+    declaration: () => observed.initialize,
+    cancel(params) {
+      return connection.agent.notify("session/cancel", params);
+    },
+    async request(method, params) {
+      if (failure !== null) throw failure;
+      try {
+        return await connection.agent.request(method, params);
+      } catch (error) {
+        throw await refusalFor(error);
+      }
+    },
+  };
+}

package/src/adapter-mcp.js

@@ -0,0 +1,44 @@
+import { COMMAND_ADAPTER_INITIALIZE_TIMEOUT_MS, MCP_PROTOCOL_VERSION } from "./contract.js";
+import { bridgeCall } from "./mcp.js";
+import { KitRefusal } from "./refusal.js";
+
+function readableDiscovery(discovery) {
+  const identity = discovery?._meta?.["io.modelcontextprotocol/serverInfo"];
+  return Array.isArray(discovery?.supportedVersions) &&
+    discovery.supportedVersions.includes(MCP_PROTOCOL_VERSION) &&
+    typeof discovery.capabilities === "object" && discovery.capabilities !== null &&
+    !Array.isArray(discovery.capabilities) &&
+    typeof identity?.name === "string" && typeof identity?.version === "string" &&
+    (discovery.instructions === undefined || typeof discovery.instructions === "string");
+}
+
+async function commandHouseReply(bridge, request) {
+  const deadline = AbortSignal.timeout(COMMAND_ADAPTER_INITIALIZE_TIMEOUT_MS);
+  try {
+    return await bridgeCall(bridge, request, deadline);
+  } catch (refusal) {
+    if (deadline.aborted) throw new KitRefusal("kit_mcp_discovery_timeout");
+    throw refusal;
+  }
+}
+
+export async function commandHouseInstructions(bridge) {
+  const frame = await commandHouseReply(bridge, { method: "server/discover", params: {} });
+  if (frame.error !== undefined || !readableDiscovery(frame.result) || !frame.result.instructions?.trim()) {
+    throw new KitRefusal("kit_mcp_discovery_unreadable");
+  }
+  return frame.result.instructions;
+}
+
+export async function commandHouseRequest(bridge) {
+  const frame = await commandHouseReply(bridge, { method: "tools/call", params: { name: "session_get_request", arguments: {} } });
+  if (frame.error !== undefined || frame.result?.isError === true) throw new KitRefusal("kit_run_input_unreadable");
+  try {
+    const content = frame.result.content;
+    const input = JSON.parse(content.find((item) => item.type === "text").text);
+    if (typeof input !== "object" || input === null || Array.isArray(input)) throw new Error();
+    return input;
+  } catch {
+    throw new KitRefusal("kit_run_input_unreadable");
+  }
+}

package/src/adapter.js

@@ -0,0 +1,252 @@
+import { spawn } from "node:child_process";
+import { delimiter } from "node:path";
+import { fileURLToPath } from "node:url";
+import { acpClient } from "./acp.js";
+import { inheritedEnvironment, withoutHouseCredentials } from "./command.js";
+import {
+  ACP_AUTH_REQUIRED,
+  ACP_CLIENT_CAPABILITIES,
+  ACP_CLIENT_INFO,
+  ADAPTER_CONTRACTS,
+  ADAPTER_KINDS,
+  BRIDGE_NONCE_ENVIRONMENT,
+  BRIDGE_SOCKET_ENVIRONMENT,
+  COMMAND_ADAPTER_INITIALIZE_TIMEOUT_MS,
+  COMMAND_ADAPTER_SESSION_TIMEOUT_MS,
+  WORKER_INHERITED_ENVIRONMENT,
+} from "./contract.js";
+import { KitRefusal } from "./refusal.js";
+
+const HOUSE_CLI_HOME = fileURLToPath(new URL("session-bin", import.meta.url));
+
+function requiredAdapter(contract) {
+  return (
+    `requires ${contract.release.package} ${contract.release.minimum} or a later ` +
+    `${contract.release.minimum.split(".")[0]}.x release ` +
+    `for ${contract.kind} contract ${contract.version}`
+  );
+}
+
+function contractMismatch(contract, location = null) {
+  const required =
+    contract === undefined
+      ? `this Kit compiles ${ADAPTER_KINDS.join(" and ")}`
+      : requiredAdapter(contract);
+  return new KitRefusal(
+    "kit_adapter_contract_mismatch",
+    location === null ? required : `${required}; ${location}`,
+  );
+}
+
+export function releaseOrder(left, right) {
+  const parts = (release) => release.split(".").map((part) => Number(part));
+  const [leftParts, rightParts] = [parts(left), parts(right)];
+  for (let position = 0; position < 3; position += 1) {
+    const difference = (leftParts[position] ?? 0) - (rightParts[position] ?? 0);
+    if (difference !== 0) return difference < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+export function servedRelease(release, minimum) {
+  if (typeof release !== "string" || !/^\d+\.\d+\.\d+$/.test(release)) return false;
+  return (
+    releaseOrder(release, minimum) >= 0 &&
+    release.split(".")[0] === minimum.split(".")[0]
+  );
+}
+
+export function adapterContract(kind) {
+  return Object.hasOwn(ADAPTER_CONTRACTS, kind) ? ADAPTER_CONTRACTS[kind] : undefined;
+}
+
+export function compiledContract(kind, location = null) {
+  const contract = adapterContract(kind);
+  if (contract === undefined) throw contractMismatch(undefined, location);
+  return contract;
+}
+
+function sameDescriptor(declared, contract) {
+  if (typeof declared !== "object" || declared === null || Array.isArray(declared)) return false;
+  const named = Object.keys(declared);
+  if (named.length !== 3) return false;
+  const kinds = declared.field_kinds;
+  if (!Array.isArray(kinds) || kinds.length !== contract.capabilities.field_kinds.length) {
+    return false;
+  }
+  if (kinds.some((kind, position) => kind !== contract.capabilities.field_kinds[position])) {
+    return false;
+  }
+  if (declared.decline !== contract.capabilities.decline) return false;
+  const reasons = declared.stop_reasons;
+  if (typeof reasons !== "object" || reasons === null || Array.isArray(reasons)) return false;
+  const namedReasons = Object.keys(contract.capabilities.stop_reasons);
+  if (Object.keys(reasons).length !== namedReasons.length) return false;
+  return namedReasons.every((reason) => reasons[reason] === contract.capabilities.stop_reasons[reason]);
+}
+
+export function assertAcquiredCommandAdapter(adapter) {
+  const contract = adapterContract(adapter?.kind);
+  if (contract === undefined) throw contractMismatch(undefined);
+  if (adapter.contract_version !== contract.version) throw contractMismatch(contract);
+  if (!sameDescriptor(adapter.capabilities, contract)) throw contractMismatch(contract);
+  return { kind: contract.kind, contractVersion: contract.version };
+}
+
+function houseCli(bridge, path) {
+  return {
+    PATH: [HOUSE_CLI_HOME, path].filter(Boolean).join(delimiter),
+    [BRIDGE_SOCKET_ENVIRONMENT]: bridge.socket,
+    [BRIDGE_NONCE_ENVIRONMENT]: bridge.nonce,
+  };
+}
+
+export function startCommandAdapter(start, bridge = null) {
+  const environment = {
+    ...inheritedEnvironment(WORKER_INHERITED_ENVIRONMENT),
+    ...withoutHouseCredentials(start.environment),
+  };
+  return spawn(start.command[0], [...start.command.slice(1), ...start.arguments], {
+    cwd: start.workingDirectory,
+    env: bridge === null ? environment : { ...environment, ...houseCli(bridge, environment.PATH) },
+    stdio: ["pipe", "pipe", "inherit"],
+  });
+}
+
+function declaredElicitation(declaration) {
+  const capabilities = declaration?.clientCapabilities;
+  return (
+    capabilities?.fs?.readTextFile === false &&
+    capabilities?.fs?.writeTextFile === false &&
+    capabilities?.terminal === false &&
+    typeof capabilities?.elicitation?.form === "object" &&
+    capabilities.elicitation.form !== null &&
+    capabilities.elicitation.url === undefined
+  );
+}
+
+function assertInitialization(contract, initialized, declaration) {
+  if (!declaredElicitation(declaration)) throw contractMismatch(contract, "initialize declaration");
+  if (initialized?.protocolVersion !== contract.protocol) throw contractMismatch(contract);
+  const identity = contract.identity;
+  const release =
+    identity.agentInfo !== undefined
+      ? initialized?.agentInfo?.name === identity.agentInfo && initialized.agentInfo.version
+      : initialized?._meta?.[identity.initializeMeta] === true &&
+        initialized._meta[identity.versionMeta];
+  if (!servedRelease(release, contract.release.minimum)) {
+    throw contractMismatch(contract);
+  }
+  if (contract.sessionLoad && initialized?.agentCapabilities?.loadSession !== true) {
+    throw contractMismatch(contract);
+  }
+}
+
+export async function initializeCommandAdapter(adapter, contract, handlers) {
+  const acp = acpClient(adapter, handlers);
+  const initialized = await acp.request("initialize", {
+    protocolVersion: contract.protocol,
+    clientCapabilities: ACP_CLIENT_CAPABILITIES,
+    clientInfo: ACP_CLIENT_INFO,
+  });
+  assertInitialization(contract, initialized, acp.declaration());
+  return { acp, initialized };
+}
+
+export function stopCommandAdapter(adapter) {
+  adapter.stdin.end();
+  adapter.kill("SIGTERM");
+}
+
+async function within(promise, timeoutMs, expired) {
+  let deadline;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        deadline = setTimeout(() => reject(expired), timeoutMs);
+      }),
+    ]);
+  } finally {
+    clearTimeout(deadline);
+  }
+}
+
+async function initializedWithin(adapter, contract, initializeTimeoutMs, location) {
+  try {
+    return await within(
+      initializeCommandAdapter(adapter, contract, { onUpdate: () => undefined }),
+      initializeTimeoutMs,
+      contractMismatch(contract, location),
+    );
+  } catch {
+    throw contractMismatch(contract, location);
+  }
+}
+
+export async function verifyCommandAdapter(
+  start,
+  contract,
+  initializeTimeoutMs = COMMAND_ADAPTER_INITIALIZE_TIMEOUT_MS,
+  location = null,
+) {
+  const adapter = startCommandAdapter(start);
+  try {
+    return (await initializedWithin(adapter, contract, initializeTimeoutMs, location)).initialized;
+  } finally {
+    stopCommandAdapter(adapter);
+  }
+}
+
+export function openedSession(opened) {
+  const sessionId = opened?.sessionId;
+  return typeof sessionId === "string" && sessionId.length > 0 && sessionId.length <= 512
+    ? sessionId
+    : null;
+}
+
+function offeredValues(configOptions, id, contract, location) {
+  if (id === null) return [];
+  const option = configOptions.find((candidate) => candidate?.id === id);
+  if (option?.type !== "select") return [];
+  if (!Array.isArray(option.options)) throw contractMismatch(contract, location);
+  const values = option.options.flatMap((entry) =>
+    Array.isArray(entry?.options) ? entry.options : [entry],
+  );
+  if (values.some((entry) => typeof entry?.value !== "string" || typeof entry?.name !== "string")) {
+    throw contractMismatch(contract, location);
+  }
+  return values.map((entry) => ({ value: entry.value, name: entry.name }));
+}
+
+export async function offeredSessionOptions(start, contract, deadlines, location = null) {
+  const adapter = startCommandAdapter(start);
+  try {
+    const { acp } = await initializedWithin(
+      adapter,
+      contract,
+      deadlines.initialize ?? COMMAND_ADAPTER_INITIALIZE_TIMEOUT_MS,
+      location,
+    );
+    let opened;
+    try {
+      opened = await within(
+        acp.request("session/new", { cwd: start.workingDirectory, mcpServers: [] }),
+        deadlines.session ?? COMMAND_ADAPTER_SESSION_TIMEOUT_MS,
+        contractMismatch(contract, location),
+      );
+    } catch (refusal) {
+      if (refusal instanceof KitRefusal && refusal.protocolCode === ACP_AUTH_REQUIRED) return null;
+      throw contractMismatch(contract, location);
+    }
+    if (openedSession(opened) === null) throw contractMismatch(contract, location);
+    const configOptions = opened.configOptions ?? [];
+    if (!Array.isArray(configOptions)) throw contractMismatch(contract, location);
+    return {
+      model: offeredValues(configOptions, contract.sessionConfig.model, contract, location),
+      effort: offeredValues(configOptions, contract.sessionConfig.effort, contract, location),
+    };
+  } finally {
+    stopCommandAdapter(adapter);
+  }
+}

package/src/agent-logins.js

@@ -0,0 +1,65 @@
+const TERMINAL_ESCAPE = /\u001b\[[0-9;?]*[A-Za-z]/gu;
+const HTTPS_URL = /https:\/\/[^\s\u001b]+/u;
+
+function plain(output) {
+  return output.replace(TERMINAL_ESCAPE, "");
+}
+
+export const CODEX_DEVICE_CODE = Object.freeze({
+  ceremony(output) {
+    const shown = plain(output);
+    const code = /one-time code[^\n]*\n[^\S\n]*([A-Z0-9]+(?:-[A-Z0-9]+)+)[^\S\n]*\n/u.exec(shown);
+    const url = HTTPS_URL.exec(shown);
+    if (code === null || url === null) return null;
+    return {
+      steps: [
+        { kind: "visit", label: "Open the Codex device page and sign in with ChatGPT", url: url[0] },
+        { kind: "show", label: "Enter this one-time code on that page", text: code[1] },
+      ],
+    };
+  },
+  input: () => null,
+  rejected: () => false,
+});
+
+export const CLAUDE_PASTED_CODE = Object.freeze({
+  ceremony(output) {
+    const shown = plain(output);
+    if (!shown.includes("Paste code here")) return null;
+    const url = HTTPS_URL.exec(shown);
+    if (url === null) return null;
+    return {
+      steps: [
+        { kind: "visit", label: "Sign in to Claude and authorize Claude Code", url: url[0] },
+        {
+          kind: "collect",
+          label: "Authentication code",
+          name: "code",
+          description: "After you authorize, the Claude page shows an authentication code. Copy the whole code and paste it here.",
+        },
+      ],
+    };
+  },
+  input: (collected) => `${collected.code}\n`,
+  rejected: (answered) => plain(answered).includes("Invalid code."),
+});
+
+export const GROK_DEVICE_CODE = Object.freeze({
+  ceremony(output) {
+    const shown = plain(output);
+    if (!shown.includes("Waiting for authorization")) return null;
+    const url = HTTPS_URL.exec(shown);
+    const code = /(?:Confirm this code in your browser|Then enter this code):\s*([A-Z0-9-]+)/u.exec(
+      shown,
+    );
+    if (url === null || code === null) return null;
+    return {
+      steps: [
+        { kind: "visit", label: "Open Grok and sign in", url: url[0] },
+        { kind: "show", label: "Confirm this one-time code on that page", text: code[1] },
+      ],
+    };
+  },
+  input: () => null,
+  rejected: () => false,
+});