@agentshouse/kit 0.0.1 → 0.1.0-alpha.10

package/src/blocks.js

@@ -0,0 +1,156 @@
+import {
+  ASSISTANT_BLOCKS_MAX,
+  ASSISTANT_TABLE_COLUMNS_MAX,
+  ASSISTANT_TEXT_MAX_BYTES,
+} from "./contract.js";
+
+const HEADING = /^(#{1,6})\s+(.+)$/;
+const BULLET = /^ {0,3}[-*+]\s+(.+)$/;
+const ORDERED = /^ {0,3}\d{1,9}[.)]\s+(.+)$/;
+const TABLE_ROW = /^\s*\|.*\|\s*$/;
+const TABLE_RULE = /^\s*\|(\s*:?-+:?\s*\|)+\s*$/;
+const FENCE = /^```(.*)$/;
+const FORMULA = "$$";
+
+function cellsOf(line) {
+  return line
+    .trim()
+    .replace(/^\|/, "")
+    .replace(/\|$/, "")
+    .split("|")
+    .map((cell) => cell.trim());
+}
+
+function tableAt(lines, start) {
+  if (!TABLE_ROW.test(lines[start]) || !TABLE_RULE.test(lines[start + 1] ?? "")) return null;
+  const headers = cellsOf(lines[start]);
+  if (headers.length === 0 || headers.length > ASSISTANT_TABLE_COLUMNS_MAX) return null;
+  if (headers.some((header) => header === "")) return null;
+  if (cellsOf(lines[start + 1]).length !== headers.length) return null;
+  const rows = [];
+  let index = start + 2;
+  while (index < lines.length && TABLE_ROW.test(lines[index])) {
+    const cells = cellsOf(lines[index]);
+    if (cells.length !== headers.length || cells.some((cell) => cell === "")) return null;
+    rows.push(cells);
+    index += 1;
+  }
+  if (rows.length === 0) return null;
+  return { block: { type: "table", headers, rows }, next: index };
+}
+
+function fencedAt(lines, start, fence) {
+  let index = start + 1;
+  const body = [];
+  while (index < lines.length && lines[index].trim() !== fence) {
+    body.push(lines[index]);
+    index += 1;
+  }
+  return { body, next: index < lines.length ? index + 1 : index };
+}
+
+function listAt(lines, start, ordered) {
+  const pattern = ordered ? ORDERED : BULLET;
+  const items = [];
+  let index = start;
+  while (index < lines.length) {
+    const item = pattern.exec(lines[index]);
+    if (item === null) break;
+    const named = item[1].trim();
+    if (named !== "") items.push(named);
+    index += 1;
+  }
+  if (items.length === 0) return null;
+  return { block: { type: "list", ordered, items }, next: index };
+}
+
+export function assistantBlocks(text) {
+  if (typeof text !== "string") return null;
+  const lines = text.split("\n");
+  const blocks = [];
+  let paragraph = [];
+  const endParagraph = () => {
+    const joined = paragraph.join("\n").trim();
+    paragraph = [];
+    if (joined !== "") blocks.push({ type: "paragraph", text: joined });
+  };
+  let index = 0;
+  while (index < lines.length) {
+    const line = lines[index];
+    if (line.trim() === "") {
+      endParagraph();
+      index += 1;
+      continue;
+    }
+    const fence = FENCE.exec(line.trim());
+    if (fence !== null) {
+      endParagraph();
+      const code = fencedAt(lines, index, "```");
+      const body = code.body.join("\n");
+      const language = fence[1].trim();
+      if (body.trim() !== "") {
+        blocks.push({ type: "code", language: language === "" ? null : language, text: body });
+      }
+      index = code.next;
+      continue;
+    }
+    if (line.trim() === FORMULA) {
+      endParagraph();
+      const formula = fencedAt(lines, index, FORMULA);
+      const expression = formula.body.join("\n").trim();
+      if (expression !== "") blocks.push({ type: "formula", expression });
+      index = formula.next;
+      continue;
+    }
+    const heading = HEADING.exec(line);
+    if (heading !== null) {
+      endParagraph();
+      const named = heading[2].trim();
+      if (named !== "") blocks.push({ type: "heading", level: heading[1].length, text: named });
+      index += 1;
+      continue;
+    }
+    const table = tableAt(lines, index);
+    if (table !== null) {
+      endParagraph();
+      blocks.push(table.block);
+      index = table.next;
+      continue;
+    }
+    const list = BULLET.test(line)
+      ? listAt(lines, index, false)
+      : ORDERED.test(line)
+        ? listAt(lines, index, true)
+        : null;
+    if (list !== null) {
+      endParagraph();
+      blocks.push(list.block);
+      index = list.next;
+      continue;
+    }
+    paragraph.push(line);
+    index += 1;
+  }
+  endParagraph();
+  if (blocks.length === 0) return null;
+  if (blocks.length <= ASSISTANT_BLOCKS_MAX) return blocks;
+  const whole = text.trim();
+  return whole === "" ? null : [{ type: "paragraph", text: whole }];
+}
+
+export function blocksText(blocks) {
+  return blocks
+    .map((block) => {
+      if (block.type === "formula") return block.expression;
+      if (block.type === "list") return block.items.join("\n");
+      if (block.type === "table") {
+        return [block.headers, ...block.rows].map((row) => row.join("\t")).join("\n");
+      }
+      return block.text;
+    })
+    .join("\n\n");
+}
+
+export function withinAssistantBound(text) {
+  return Buffer.byteLength(text, "utf8") <= ASSISTANT_TEXT_MAX_BYTES;
+}

package/src/bridge.js

@@ -0,0 +1,449 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, rm } from "node:fs/promises";
+import { createServer } from "node:net";
+import { dirname } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { readFrames, writeFrame } from "./channel.js";
+import {
+  AGENT_OPERATION_META,
+  BRIDGE_RECONNECT_MAX_MS,
+  BRIDGE_RECONNECT_MS,
+  KIT_CONTRACT_VERSION,
+  MCP_CLIENT_CAPABILITIES_META,
+  MCP_CLIENT_INFO_META,
+  MCP_PROTOCOL_VERSION,
+  MCP_PROTOCOL_VERSION_META,
+  TURN_OUTCOMES,
+} from "./contract.js";
+import { operationId } from "./operation.js";
+import { houseFailed } from "./refusal.js";
+
+function bridgedFrame(request, operation) {
+  if (typeof request.method !== "string") return request;
+  const params = typeof request.params === "object" && request.params !== null ? request.params : {};
+  const declared = typeof params._meta === "object" && params._meta !== null ? params._meta : {};
+  const meta = {
+    [MCP_PROTOCOL_VERSION_META]: MCP_PROTOCOL_VERSION,
+    [MCP_CLIENT_INFO_META]: { name: "house-kit", version: KIT_CONTRACT_VERSION },
+    [MCP_CLIENT_CAPABILITIES_META]: {},
+    ...declared,
+  };
+  delete meta[AGENT_OPERATION_META];
+  if (operation !== null) meta[AGENT_OPERATION_META] = operation;
+  return { ...request, params: { ...params, _meta: meta } };
+}
+
+function calledTool(request) {
+  if (request.method !== "tools/call") return null;
+  const name = request.params?.name;
+  return typeof name === "string" ? name : null;
+}
+
+export async function openBridge(options) {
+  await mkdir(dirname(options.socket), { recursive: true, mode: 0o700 });
+  await rm(options.socket, { force: true });
+  const state = {
+    assistant: [],
+    stop: null,
+    failure: null,
+    launcher: null,
+    closed: false,
+    questions: new Map(),
+    interrupts: new Set(),
+  };
+  const connections = new Set();
+  const clients = new Map();
+  const incarnation = randomUUID();
+  const mutates = options.mutates ?? (() => false);
+  const lifetime = new AbortController();
+  const signal = options.signal === undefined
+    ? lifetime.signal
+    : AbortSignal.any([lifetime.signal, options.signal]);
+  let depart;
+  const departed = new Promise((resolve) => {
+    depart = resolve;
+  });
+  const endSession = () => {
+    lifetime.abort();
+    depart();
+  };
+  options.signal?.addEventListener("abort", endSession, { once: true });
+  if (options.signal?.aborted) endSession();
+
+  function deliverAnswer(pending) {
+    if (state.launcher === null || pending.answer === undefined) return;
+    writeFrame(state.launcher, { type: "answered", delivery: pending.delivery, ...pending.answer });
+  }
+
+  function unsupportedQuestion(pending) {
+    state.questions.delete(pending.delivery);
+    pending.answer = { unsupported: true };
+    deliverAnswer(pending);
+  }
+
+  async function admitQuestion(pending) {
+    if (typeof options.question !== "function") {
+      unsupportedQuestion(pending);
+      return;
+    }
+    let backoff = BRIDGE_RECONNECT_MS;
+    while (!signal.aborted) {
+      try {
+        const admitted = await options.question(pending.form, signal);
+        if (signal.aborted) return;
+        pending.interaction = admitted.interaction;
+        if (admitted.state === "settled") {
+          unsupportedQuestion(pending);
+          return;
+        }
+        if (pending.ceremony !== null) await relaySecretInput(pending);
+        return;
+      } catch (refusal) {
+        if (signal.aborted) return;
+        if (houseFailed(refusal)) {
+          try {
+            await delay(backoff, undefined, { signal });
+          } catch {
+            return;
+          }
+          backoff = Math.min(backoff * 2, BRIDGE_RECONNECT_MAX_MS);
+          continue;
+        }
+        unsupportedQuestion(pending);
+        return;
+      }
+    }
+  }
+
+  async function relaySecretInput(pending) {
+    if (typeof options.secret !== "function") {
+      unsupportedQuestion(pending);
+      return;
+    }
+    let backoff = BRIDGE_RECONNECT_MS;
+    while (!signal.aborted && state.questions.get(pending.delivery) === pending) {
+      let relayed;
+      try {
+        relayed = await options.secret(pending.interaction, pending.ceremony, signal);
+        backoff = BRIDGE_RECONNECT_MS;
+      } catch (refusal) {
+        if (signal.aborted) return;
+        if (!houseFailed(refusal)) {
+          unsupportedQuestion(pending);
+          return;
+        }
+        try {
+          await delay(backoff, undefined, { signal });
+        } catch {
+          return;
+        }
+        backoff = Math.min(backoff * 2, BRIDGE_RECONNECT_MAX_MS);
+        continue;
+      }
+      if (signal.aborted) return;
+      if (relayed.collected === null) continue;
+      pending.answer = {
+        interaction: pending.interaction,
+        provider_turn: pending.form.provider_turn,
+        correlation: pending.form.correlation,
+        response: { action: "accept", content: relayed.collected },
+      };
+      deliverAnswer(pending);
+      return;
+    }
+  }
+
+  function asked(frame) {
+    if (
+      typeof frame.delivery !== "string" ||
+      typeof frame.form !== "object" ||
+      frame.form === null
+    ) {
+      return;
+    }
+    const held = state.questions.get(frame.delivery);
+    if (held !== undefined) {
+      deliverAnswer(held);
+      return;
+    }
+    const pending = {
+      delivery: frame.delivery,
+      form: frame.form,
+      ceremony: frame.ceremony ?? null,
+      interaction: null,
+      answer: undefined,
+    };
+    state.questions.set(frame.delivery, pending);
+    void admitQuestion(pending);
+  }
+
+  function applied(frame) {
+    const pending = state.questions.get(frame.delivery);
+    if (pending === undefined) return;
+    state.questions.delete(frame.delivery);
+    if (pending.interaction === null || typeof options.settle !== "function") return;
+    void options.settle(pending.interaction, frame.outcome === "expired" ? "expired" : "resolved").catch((refusal) => {
+      if (!signal.aborted) throw refusal;
+    });
+  }
+
+  function fromLauncher(frame) {
+    if (frame.type === "question") {
+      asked(frame);
+      return;
+    }
+    if (frame.type === "question_applied" && typeof frame.delivery === "string") {
+      applied(frame);
+      return;
+    }
+    if (frame.type === "assistant" && typeof frame.text === "string") {
+      state.assistant.push(frame.text);
+      return;
+    }
+    if (frame.type === "draft") {
+      if (typeof frame.text === "string" && frame.text !== "") options.draft?.(frame.text);
+      return;
+    }
+    if (
+      frame.type === "plan" &&
+      typeof frame.provider_turn === "string" &&
+      Array.isArray(frame.steps) &&
+      typeof frame.terminal === "boolean"
+    ) {
+      void options.plan?.({
+        provider_turn: frame.provider_turn,
+        steps: frame.steps,
+        terminal: frame.terminal,
+      });
+      return;
+    }
+    if (
+      frame.type === "interrupt_applied" &&
+      typeof frame.interrupt === "string" &&
+      ["interrupted", "nothing_to_interrupt"].includes(frame.outcome) &&
+      state.interrupts.has(frame.interrupt)
+    ) {
+      const reported = options.interrupt?.(frame.interrupt, frame.outcome);
+      if (reported === undefined) state.interrupts.delete(frame.interrupt);
+      else void Promise.resolve(reported).finally(() => state.interrupts.delete(frame.interrupt));
+      return;
+    }
+    if (frame.type === "turn_ended") {
+      state.stop = {
+        providerContinuation: frame.provider_continuation === true,
+        providerSessionId: typeof frame.provider_session_id === "string" && frame.provider_session_id.length > 0 && frame.provider_session_id.length <= 512 ? frame.provider_session_id : null,
+        stopOutcome: TURN_OUTCOMES.includes(frame.stop_outcome) ? frame.stop_outcome : null,
+      };
+      return;
+    }
+    if (frame.type === "failed") {
+      state.failure ??= {
+        code: typeof frame.code === "string" ? frame.code : "kit_adapter_failed",
+        detail: typeof frame.detail === "string" ? frame.detail : null,
+      };
+      return;
+    }
+    if (frame.type === "exiting") endSession();
+  }
+
+  function deliver(client, pending) {
+    if (client.connection === null || pending.answer === undefined) return;
+    writeFrame(client.connection, {
+      type: "mcp",
+      delivery: pending.delivery,
+      frame: pending.answer,
+    });
+  }
+
+  async function forward(client, pending, mutation) {
+    let backoff = BRIDGE_RECONNECT_MS;
+    while (!signal.aborted) {
+      try {
+        if (!(await options.alive())) {
+          endSession();
+          return;
+        }
+        if (signal.aborted) return;
+        const answer = await options.forward(JSON.parse(pending.request), signal);
+        if (signal.aborted) return;
+        pending.answer = answer;
+        deliver(client, pending);
+        return;
+      } catch (refusal) {
+        if (signal.aborted) return;
+        if (mutation && houseFailed(refusal)) {
+          try {
+            await delay(backoff, undefined, { signal });
+          } catch {
+            return;
+          }
+          backoff = Math.min(backoff * 2, BRIDGE_RECONNECT_MAX_MS);
+          continue;
+        }
+        pending.answer = pending.id === undefined ? null : {
+          jsonrpc: "2.0",
+          id: pending.id,
+          error: { code: -32000, message: refusal.code ?? "kit_house_unavailable" },
+        };
+        deliver(client, pending);
+        return;
+      }
+    }
+  }
+
+  function fromMcp(client, connection, frame) {
+    if (client.connection !== connection) return;
+    if (frame.type === "ack") {
+      const pending = client.pending.get(frame.delivery);
+      if (pending?.answer === undefined) return;
+      client.pending.delete(frame.delivery);
+      return;
+    }
+    if (
+      frame.type !== "mcp" || typeof frame.delivery !== "string" ||
+      typeof frame.frame !== "object" || frame.frame === null
+    ) {
+      connection.destroy();
+      return;
+    }
+    const original = JSON.stringify(frame.frame);
+    const retained = client.pending.get(frame.delivery);
+    if (retained !== undefined) {
+      if (retained.original !== original) {
+        connection.destroy();
+        return;
+      }
+      deliver(client, retained);
+      return;
+    }
+    if (signal.aborted) {
+      writeFrame(connection, { type: "closed", code: "kit_bridge_unavailable" });
+      connection.end();
+      return;
+    }
+    const request = frame.frame;
+    const tool = calledTool(request);
+    const operation = tool !== null && mutates(tool) ? operationId() : null;
+    const pending = {
+      delivery: frame.delivery,
+      id: request.id,
+      original,
+      request: JSON.stringify(bridgedFrame(request, operation)),
+      answer: undefined,
+    };
+    client.pending.set(frame.delivery, pending);
+    void forward(client, pending, operation !== null);
+  }
+
+  function admit(peer, connection, frame) {
+    if (
+      frame.type !== "hello" ||
+      frame.nonce !== options.nonce ||
+      (frame.role !== "launcher" && frame.role !== "mcp") ||
+      (frame.role === "launcher" && state.launcher !== null) ||
+      (frame.role === "mcp" && (
+        typeof frame.client !== "string" ||
+        (frame.bridge !== null && frame.bridge !== incarnation)
+      ))
+    ) {
+      writeFrame(connection, { type: "refused", code: "kit_bridge_unauthorized" });
+      connection.destroy();
+      return;
+    }
+    peer.role = frame.role;
+    if (frame.role !== "launcher") {
+      let client = clients.get(frame.client);
+      if (client === undefined) {
+        client = { connection: null, pending: new Map() };
+        clients.set(frame.client, client);
+      }
+      client.connection?.destroy();
+      client.connection = connection;
+      peer.client = client;
+      peer.name = frame.client;
+      writeFrame(connection, { type: "ready", bridge: incarnation });
+      for (const pending of client.pending.values()) deliver(client, pending);
+      return;
+    }
+    state.launcher = connection;
+    if (frame.adapter_session === true || options.start === undefined) {
+      writeFrame(connection, { type: "resumed" });
+      return;
+    }
+    writeFrame(connection, { type: "start", ...options.start });
+  }
+
+  const server = createServer((connection) => {
+    const peer = { role: null };
+    connections.add(connection);
+    connection.on("error", () => connection.destroy());
+    connection.on("close", () => {
+      connections.delete(connection);
+      if (state.launcher === connection) state.launcher = null;
+      if (peer.client?.connection !== connection) return;
+      peer.client.connection = null;
+      if (peer.client.pending.size === 0) clients.delete(peer.name);
+    });
+    readFrames(connection, {
+      onFrame: (frame) => {
+        if (peer.role === null) {
+          admit(peer, connection, frame);
+          return;
+        }
+        if (peer.role === "mcp") fromMcp(peer.client, connection, frame);
+        else fromLauncher(frame);
+      },
+      onRefusal: () => connection.destroy(),
+    });
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(options.socket, resolve);
+  });
+  await chmod(options.socket, 0o600);
+
+  return {
+    departed,
+    interrupt(command) {
+      if (state.launcher === null || state.stop !== null) return false;
+      if (state.interrupts.has(command.interrupt)) return true;
+      state.interrupts.add(command.interrupt);
+      writeFrame(state.launcher, { type: "interrupt", interrupt: command.interrupt });
+      return true;
+    },
+    answered(command) {
+      for (const pending of state.questions.values()) {
+        if (pending.interaction !== command.interaction) continue;
+        pending.answer = {
+          interaction: command.interaction,
+          provider_turn: command.providerTurn,
+          correlation: command.correlation,
+          response: command.response,
+        };
+        deliverAnswer(pending);
+        return true;
+      }
+      return false;
+    },
+    unsettledInteractions: () =>
+      [...state.questions.values()]
+        .map((pending) => pending.interaction)
+        .filter((interaction) => interaction !== null),
+    assistant: () => [...state.assistant],
+    stop: () => state.stop,
+    failure: () => state.failure,
+    stopRecovery: () => lifetime.abort(),
+    async close() {
+      if (state.closed) return;
+      state.closed = true;
+      endSession();
+      options.signal?.removeEventListener("abort", endSession);
+      for (const connection of connections) connection.destroy();
+      connections.clear();
+      clients.clear();
+      await new Promise((resolve) => server.close(resolve));
+      await rm(options.socket, { force: true });
+    },
+  };
+}

package/src/bytes.js

@@ -0,0 +1,89 @@
+import {
+  BYTE_GRANT_OPERATION_HEADER,
+  BYTE_GRANT_POST_BYTES_MAX,
+} from "./contract.js";
+import { houseRefusal, KitRefusal, throwHouseAnswer } from "./refusal.js";
+
+function cancelled(signal, error) {
+  return signal?.aborted === true || error?.name === "AbortError";
+}
+
+function redirected(status) {
+  return status >= 300 && status < 400;
+}
+
+async function downloadBody(response, signal) {
+  const chunks = [];
+  let size = 0;
+  try {
+    for await (const chunk of response.body ?? []) {
+      if (cancelled(signal)) throw new KitRefusal("kit_command_cancelled");
+      size += chunk.length;
+      if (size > BYTE_GRANT_POST_BYTES_MAX) throw new KitRefusal("original_bytes_exceeded");
+      chunks.push(chunk);
+    }
+  } catch (error) {
+    if (cancelled(signal, error)) throw new KitRefusal("kit_command_cancelled");
+    if (error instanceof KitRefusal) throw error;
+    throw new KitRefusal("kit_house_unavailable");
+  }
+  if (cancelled(signal)) throw new KitRefusal("kit_command_cancelled");
+  return Buffer.concat(chunks, size);
+}
+
+export async function transferBytes(request, dependencies = {}) {
+  if (request.method !== "GET" && request.method !== "POST") {
+    throw new KitRefusal("kit_byte_method_invalid", request.method);
+  }
+  if (typeof request.url !== "string" || request.url.length === 0) {
+    throw new KitRefusal("kit_byte_url_invalid");
+  }
+  if (typeof request.operation !== "string" || request.operation.length === 0) {
+    throw new KitRefusal("kit_byte_operation_invalid");
+  }
+  if (request.method === "POST") {
+    if (!Buffer.isBuffer(request.body)) throw new KitRefusal("kit_byte_body_invalid");
+    if (request.body.length > BYTE_GRANT_POST_BYTES_MAX) {
+      throw new KitRefusal("original_bytes_exceeded");
+    }
+  }
+  const fetcher = dependencies.fetch ?? fetch;
+  const headers = {
+    [BYTE_GRANT_OPERATION_HEADER]: request.operation,
+  };
+  if (request.method === "POST") headers["content-type"] = "application/octet-stream";
+  let response;
+  try {
+    response = await fetcher(request.url, {
+      method: request.method,
+      headers,
+      body: request.method === "POST" ? request.body : undefined,
+      redirect: "manual",
+      signal: request.signal,
+    });
+  } catch (error) {
+    if (cancelled(request.signal, error)) throw new KitRefusal("kit_command_cancelled");
+    throw new KitRefusal("kit_house_unavailable");
+  }
+  if (cancelled(request.signal)) throw new KitRefusal("kit_command_cancelled");
+  if (redirected(response.status)) {
+    throw new KitRefusal("kit_byte_redirect_refused");
+  }
+  if (request.method === "GET") {
+    if (response.status === 202) {
+      throwHouseAnswer(202, await response.json().catch(() => null));
+    }
+    if (!response.ok) throw houseRefusal(response.status, await response.json().catch(() => null));
+    return { bytes: await downloadBody(response, request.signal) };
+  }
+  let answer = null;
+  try {
+    answer = await response.json();
+  } catch {
+    answer = null;
+  }
+  if (cancelled(request.signal)) throw new KitRefusal("kit_command_cancelled");
+  throwHouseAnswer(response.status, answer);
+  if (answer === null) throw new KitRefusal("kit_house_unavailable");
+  return answer;
+}