@agentshouse/kit 0.0.1 → 0.1.0-alpha.2

package/src/house.js

@@ -0,0 +1,1085 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { assertAcquiredCommandAdapter } from "./adapter.js";
+import {
+  assistantDraftsPath,
+  assistantTextPath,
+  ADAPTER_KINDS,
+  INTERACTION_CORRELATION_MAX,
+  INTERACTION_OUTCOMES,
+  INTERACTION_PROPERTY_MAX,
+  INTERACTION_VALUES_MAX,
+  INTERACTION_VALUE_MAX,
+  interactionOutcomePath,
+  KIT_CONTRACT_VERSION,
+  KIT_CREDENTIAL,
+  KIT_AGENTS_REPORT_PATH,
+  KIT_AGENTS_DESIRED_PATH,
+  KIT_HOST_CAPACITY_PATH,
+  KIT_LOGIN_REPORT_PATH,
+  KIT_SESSIONS_REPORT_MAX,
+  KIT_SESSIONS_REPORT_PATH,
+  KIT_SETUP_ACQUIRE_PATH,
+  KIT_SETUP_REPORT_PATH,
+  KIT_WORKSPACES_ACQUIRE_PATH,
+  LEASE_RENEWAL_MARGIN_MS,
+  MCP_PROTOCOL_VERSION,
+  WORKER_RUN_TOKEN_MARGIN_MS,
+  runOutcomePath,
+  secretInputPath,
+  SECRET_VALUE_MAX,
+  sessionInteractionsPath,
+  workspaceOutcomePath,
+} from "./contract.js";
+import { declarationReader } from "./declaration.js";
+import { houseRefusal, KitRefusal, throwHouseAnswer } from "./refusal.js";
+
+const LEASE = /^ahl_[A-Za-z0-9_-]+$/;
+const ASSISTANT_DRAFT_STATES = ["streamed", "unsupported"];
+const ITEM_OUTCOMES = ["accepted", "duplicate", "rejected"];
+
+async function readCredential(directory) {
+  let stored;
+  try {
+    stored = (await readFile(join(directory, "credential"), "utf8")).trim();
+  } catch {
+    throw new KitRefusal("kit_credential_rejected", directory);
+  }
+  if (!KIT_CREDENTIAL.test(stored)) throw new KitRefusal("kit_credential_rejected", directory);
+  return stored;
+}
+
+async function houseAnswer(house, path, init, dependencies, signal) {
+  const fetcher = dependencies.fetch ?? fetch;
+  let response;
+  try {
+    response = await fetcher(`${house}${path}`, { ...init, signal });
+  } catch (error) {
+    if (signal?.aborted === true || error?.name === "AbortError") {
+      throw new KitRefusal("kit_command_cancelled");
+    }
+    throw new KitRefusal("kit_house_unavailable", path);
+  }
+  let answer = null;
+  try {
+    answer = await response.json();
+  } catch {
+    answer = null;
+  }
+  throwHouseAnswer(response.status, answer, path);
+  if (answer === null) throw new KitRefusal("kit_house_unavailable", path);
+  return answer;
+}
+
+export async function houseGetJson(url, dependencies, signal) {
+  return houseAnswer(url, "", { method: "GET" }, dependencies, signal);
+}
+
+export async function houseRequest(house, authorization, path, body, dependencies, signal) {
+  return houseAnswer(
+    house,
+    path,
+    {
+      method: "POST",
+      headers: {
+        ...(authorization === null ? {} : { authorization }),
+        "content-type": "application/json",
+        "x-house-kit-version": KIT_CONTRACT_VERSION,
+      },
+      body: JSON.stringify(body),
+    },
+    dependencies,
+    signal,
+  );
+}
+
+function heldLease(answer) {
+  if (
+    typeof answer?.lease !== "string" ||
+    !LEASE.test(answer.lease) ||
+    typeof answer.expires_at !== "string" ||
+    Number.isNaN(Date.parse(answer.expires_at))
+  ) {
+    throw new KitRefusal("kit_lease_rejected");
+  }
+  return { lease: answer.lease, expiresAt: Date.parse(answer.expires_at) };
+}
+
+export async function openSession(options, dependencies = {}) {
+  const session = {
+    house: options.house,
+    dependencies,
+    now: dependencies.now ?? (() => new Date()),
+    lease: null,
+    expiresAt: 0,
+    signal: options.signal,
+  };
+  const credential = await readCredential(options.directory);
+  Object.assign(
+    session,
+    heldLease(
+      await houseRequest(
+        session.house,
+        `Bearer ${credential}`,
+        "/kit/lease",
+        {},
+        session.dependencies,
+        session.signal,
+      ),
+    ),
+  );
+  return session;
+}
+
+export async function heldControl(session, signal = session.signal) {
+  if (session.expiresAt - session.now().getTime() > LEASE_RENEWAL_MARGIN_MS) {
+    return `Bearer ${session.lease}`;
+  }
+  Object.assign(
+    session,
+    heldLease(
+      await houseRequest(
+        session.house,
+        `Bearer ${session.lease}`,
+        "/kit/lease/renew",
+        {},
+        session.dependencies,
+        signal,
+      ),
+    ),
+  );
+  return `Bearer ${session.lease}`;
+}
+
+function controlSleep(milliseconds, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(new KitRefusal("kit_command_cancelled"));
+      return;
+    }
+    const timer = setTimeout(finish, milliseconds);
+    function finish() {
+      signal.removeEventListener("abort", cancel);
+      resolve();
+    }
+    function cancel() {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", cancel);
+      reject(new KitRefusal("kit_command_cancelled"));
+    }
+    signal.addEventListener("abort", cancel, { once: true });
+  });
+}
+
+export async function toolMutations(session, signal = session.signal) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    "/kit/tools/mutations",
+    {},
+    session.dependencies,
+    signal,
+  );
+  if (!Array.isArray(answer?.tools)) throw new KitRefusal("kit_tool_classification_invalid");
+  const writes = new Map();
+  for (const tool of answer.tools) {
+    if (typeof tool?.name !== "string") throw new KitRefusal("kit_tool_classification_invalid");
+    if (typeof tool.writes !== "boolean") throw new KitRefusal("kit_tool_classification_invalid");
+    writes.set(tool.name, tool.writes);
+  }
+  return writes;
+}
+
+export function mutatingCall(classification) {
+  return (name) => classification.get(name) === true;
+}
+
+export async function releaseControl(session, options = {}) {
+  if (session.lease === null) return;
+  const held = session.lease;
+  try {
+    await houseRequest(
+      session.house,
+      `Bearer ${held}`,
+      "/kit/lease/release",
+      {},
+      session.dependencies,
+    );
+  } catch (error) {
+    if (options.required === true) throw error;
+    return;
+  }
+  session.lease = null;
+  session.expiresAt = 0;
+}
+
+export async function maintainControl(session, operation, signal, { release = true } = {}) {
+  if (signal?.aborted === true) throw new KitRefusal("kit_command_cancelled");
+  const maintenance = new AbortController();
+  const operationSignal =
+    signal === undefined ? maintenance.signal : AbortSignal.any([signal, maintenance.signal]);
+  let stopped = false;
+  let rejectFailure;
+  const failure = new Promise((_, reject) => {
+    rejectFailure = reject;
+  });
+  let cancelOperation;
+  const cancellation = new Promise((_, reject) => {
+    cancelOperation = () => reject(new KitRefusal("kit_command_cancelled"));
+    signal?.addEventListener("abort", cancelOperation, { once: true });
+  });
+  const renewal = (async () => {
+    const sleep = session.dependencies.controlSleep ?? controlSleep;
+    while (!stopped) {
+      const delay = Math.max(
+        0,
+        session.expiresAt - session.now().getTime() - LEASE_RENEWAL_MARGIN_MS,
+      );
+      try {
+        await sleep(delay, maintenance.signal);
+        if (stopped) return;
+        const previousExpiry = session.expiresAt;
+        const renewalDue = previousExpiry - session.now().getTime() <= LEASE_RENEWAL_MARGIN_MS;
+        await heldControl(session, operationSignal);
+        if (renewalDue && session.expiresAt <= previousExpiry) {
+          throw new KitRefusal("kit_lease_rejected");
+        }
+      } catch (error) {
+        if (stopped) return;
+        rejectFailure(error);
+        maintenance.abort();
+        return;
+      }
+    }
+  })();
+  const running = Promise.resolve().then(() => operation(operationSignal));
+  let ended = false;
+  try {
+    const answer = await Promise.race([running, failure, cancellation]);
+    ended = true;
+    return answer;
+  } catch (error) {
+    ended = error instanceof KitRefusal && error.code === "kit_command_cancelled";
+    throw error;
+  } finally {
+    stopped = true;
+    maintenance.abort();
+    signal?.removeEventListener("abort", cancelOperation);
+    await Promise.all([renewal, running.catch(() => undefined)]);
+    if (ended && release) await releaseControl(session);
+  }
+}
+
+function capturedOutcome(answer, count, rooms) {
+  const refused = () => {
+    throw new KitRefusal("kit_capture_rejected");
+  };
+  if (!Array.isArray(answer?.items) || answer.items.length > count) refused();
+  if (!Array.isArray(answer.blocked_routes)) refused();
+  if (answer.items.length < count && answer.items.at(-1)?.outcome !== "rejected") refused();
+  for (const result of answer.items) {
+    if (!ITEM_OUTCOMES.includes(result?.outcome)) refused();
+    if (result.outcome !== "rejected") {
+      if (
+        !Array.isArray(result.rooms) ||
+        result.rooms.length !== rooms.length ||
+        result.rooms.some(
+          (room, position) =>
+            room?.room !== rooms[position] ||
+            typeof room.record !== "string" ||
+            room.record.length === 0,
+        )
+      ) {
+        refused();
+      }
+      continue;
+    }
+    if (typeof result.code !== "string") refused();
+    if (result.disposition !== "retry" && result.disposition !== "blocked") refused();
+    if (result.scope !== "item" && result.scope !== "route") refused();
+  }
+  return { items: answer.items, blocked_routes: answer.blocked_routes };
+}
+
+export async function applyDeclared(session, document, signal = session.signal) {
+  return houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    "/kit/apply",
+    document,
+    session.dependencies,
+    signal,
+  );
+}
+
+export async function captureBatch(session, batch) {
+  return capturedOutcome(
+    await houseRequest(
+      session.house,
+      await heldControl(session),
+      "/kit/capture",
+      { source_ref: batch.sourceRef, rooms: batch.rooms, items: batch.items },
+      session.dependencies,
+      session.signal,
+    ),
+    batch.items.length,
+    batch.rooms,
+  );
+}
+
+export async function openPublicationManifest(session, manifest, signal) {
+  return houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    "/kit/repository/manifest",
+    manifest,
+    session.dependencies,
+    signal,
+  );
+}
+
+export async function deliverPublicationChunk(session, declaration, body, signal) {
+  return houseAnswer(
+    session.house,
+    "/kit/repository/chunk",
+    {
+      method: "POST",
+      headers: {
+        authorization: await heldControl(session, signal),
+        "content-type": "application/x-tar",
+        "x-house-kit-version": KIT_CONTRACT_VERSION,
+        "x-agents-house-room": declaration.room,
+        "x-agents-house-publication": declaration.publication,
+      },
+      body,
+      duplex: "half",
+    },
+    session.dependencies,
+    signal,
+  );
+}
+
+export async function acquireWorkspaces(session, max, signal = session.signal) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    KIT_WORKSPACES_ACQUIRE_PATH,
+    { max },
+    session.dependencies,
+    signal,
+  );
+  if (!Array.isArray(answer?.workspaces) || !Array.isArray(answer?.operations)) {
+    throw new KitRefusal("kit_workspace_work_rejected");
+  }
+  return answer;
+}
+
+export async function reportWorkspaceOutcome(session, operation, report, signal = session.signal) {
+  return houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    workspaceOutcomePath(operation),
+    report,
+    session.dependencies,
+    signal,
+  );
+}
+
+export async function reportHostCapacity(session, observation, signal = session.signal) {
+  return houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    KIT_HOST_CAPACITY_PATH,
+    observation,
+    session.dependencies,
+    signal,
+  );
+}
+
+export async function reportAgentCapabilities(session, agents, signal = session.signal) {
+  return houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    KIT_AGENTS_REPORT_PATH,
+    { agents },
+    session.dependencies,
+    signal,
+  );
+}
+
+export async function desiredAgents(session, signal = session.signal) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    KIT_AGENTS_DESIRED_PATH,
+    {},
+    session.dependencies,
+    signal,
+  );
+  if (
+    !Array.isArray(answer?.agents) ||
+    answer.agents.some((kind) => typeof kind !== "string" || !ADAPTER_KINDS.includes(kind)) ||
+    new Set(answer.agents).size !== answer.agents.length
+  ) {
+    throw new KitRefusal("kit_agents_rejected");
+  }
+  return answer.agents;
+}
+
+const HOUSE_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export async function acquireSetup(session, signal = session.signal) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    KIT_SETUP_ACQUIRE_PATH,
+    {},
+    session.dependencies,
+    signal,
+  );
+  if (answer?.setup === null) return null;
+  if (typeof answer?.setup?.request !== "string" || !HOUSE_UUID.test(answer.setup.request)) {
+    throw new KitRefusal("kit_setup_rejected", "setup");
+  }
+  return { request: answer.setup.request };
+}
+
+export async function reportSetup(session, request, modules, signal = session.signal) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    KIT_SETUP_REPORT_PATH,
+    { request, modules },
+    session.dependencies,
+    signal,
+  );
+  if (answer?.request !== request) throw new KitRefusal("kit_setup_rejected", "request");
+  return answer;
+}
+
+const LOGIN_STATES = ["renewal_open", "clear"];
+
+export async function reportLogin(session, login, outcome, signal = session.signal) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    KIT_LOGIN_REPORT_PATH,
+    { ...login, outcome },
+    session.dependencies,
+    signal,
+  );
+  if (
+    !LOGIN_STATES.includes(answer?.state) ||
+    (answer.state === "renewal_open" &&
+      (typeof answer.episode !== "string" || !HOUSE_UUID.test(answer.episode)))
+  ) {
+    throw new KitRefusal("kit_login_rejected", login.integration);
+  }
+  return { state: answer.state, episode: answer.state === "renewal_open" ? answer.episode : null };
+}
+
+const envelope = declarationReader("kit_acquire_rejected");
+
+function acquiredRoute(value, declaration) {
+  const route = envelope.plain(value, declaration);
+  if (!Array.isArray(route.arguments)) envelope.refuse(`${declaration}.arguments`);
+  return {
+    id: envelope.text(route.id, `${declaration}.id`, 128),
+    adapter: assertAcquiredCommandAdapter(route.adapter),
+    model: envelope.text(route.model, `${declaration}.model`, 128),
+    effort: route.effort === null ? null : envelope.text(route.effort, `${declaration}.effort`, 128),
+    arguments: route.arguments.map((argument, position) =>
+      envelope.text(argument, `${declaration}.arguments[${position}]`, 4096),
+    ),
+  };
+}
+
+function conversationText(value, declaration) {
+  if (value === null) return null;
+  if (typeof value !== "string" || value.length > 4096) envelope.refuse(declaration);
+  return value;
+}
+
+function conversationMessage(value, declaration) {
+  const message = envelope.plain(value, declaration);
+  const text = conversationText(message.text, `${declaration}.text`);
+  const caption = conversationText(message.caption, `${declaration}.caption`);
+  if (!Array.isArray(message.files)) envelope.refuse(`${declaration}.files`);
+  const files = message.files.map((value, index) => {
+    const name = `${declaration}.files[${index}]`;
+    const file = envelope.plain(value, name);
+    if (file.bytes !== null && (!Number.isSafeInteger(file.bytes) || file.bytes < 0)) {
+      envelope.refuse(`${name}.bytes`);
+    }
+    return {
+      path: envelope.text(file.path, `${name}.path`, 2048),
+      media_kind: envelope.text(file.media_kind, `${name}.media_kind`, 128),
+      media_type: file.media_type === null ? null : envelope.text(file.media_type, `${name}.media_type`, 255),
+      bytes: file.bytes,
+    };
+  });
+  if (!text && !caption && files.length === 0) envelope.refuse(declaration);
+  return {
+    message_id: envelope.text(message.message_id, `${declaration}.message_id`, 128),
+    text, caption, files,
+  };
+}
+
+function acquiredRequest(acquired, declaration) {
+  if (acquired.kind === "conversation") {
+    if (acquired.origin !== "user") envelope.refuse(`${declaration}.origin`);
+    const conversation = envelope.plain(acquired.conversation, `${declaration}.conversation`);
+    const turn = envelope.plain(conversation.turn, `${declaration}.conversation.turn`);
+    return {
+      origin: "user",
+      conversation: {
+        turn: {
+          id: envelope.text(turn.id, `${declaration}.conversation.turn.id`, 128),
+          sequence: envelope.positiveCount(turn.sequence, `${declaration}.conversation.turn.sequence`),
+          messages: envelope.filled(turn.messages, `${declaration}.conversation.turn.messages`)
+            .map((message, index) => conversationMessage(message, `${declaration}.conversation.turn.messages[${index}]`)),
+        },
+      },
+    };
+  }
+  if (acquired.kind !== "routine") envelope.refuse(`${declaration}.kind`);
+  const request = envelope.plain(acquired.request, `${declaration}.request`);
+  const routine = envelope.plain(acquired.routine, `${declaration}.routine`);
+  return {
+    origin: envelope.text(acquired.origin, `${declaration}.origin`, 32),
+    routine: {
+      name: envelope.text(routine.name, `${declaration}.routine.name`, 256),
+      version: envelope.positiveCount(routine.version, `${declaration}.routine.version`),
+    },
+    payload: envelope.plain(request.payload, `${declaration}.request.payload`),
+    requested_by: envelope.text(
+      request.requested_by,
+      `${declaration}.request.requested_by`,
+      128,
+    ),
+    requested_at: envelope.text(
+      request.requested_at,
+      `${declaration}.request.requested_at`,
+      64,
+    ),
+    deliver_at:
+      request.deliver_at === null
+        ? null
+        : envelope.text(request.deliver_at, `${declaration}.request.deliver_at`, 64),
+  };
+}
+
+function acquiredAssignment(value, declaration) {
+  const acquired = envelope.plain(value, declaration);
+  const bridge = envelope.plain(acquired.session, `${declaration}.session`);
+  const plan = envelope.plain(acquired.plan, `${declaration}.plan`);
+  const route = acquiredRoute(plan.route, `${declaration}.plan.route`);
+  const expiresAt = envelope.text(
+    bridge.bridge_token_expires_at,
+    `${declaration}.session.bridge_token_expires_at`,
+    64,
+  );
+  if (Number.isNaN(Date.parse(expiresAt))) {
+    envelope.refuse(`${declaration}.session.bridge_token_expires_at`);
+  }
+  return {
+    run: envelope.text(acquired.run, `${declaration}.run`, 128),
+    agentId: envelope.text(plan.agent_id, `${declaration}.plan.agent_id`, 128),
+    workingDirectory: envelope.text(
+      plan.working_directory,
+      `${declaration}.plan.working_directory`,
+      2048,
+    ),
+    route,
+    conversation: acquired.kind === "conversation",
+    session: {
+      id: envelope.text(bridge.id, `${declaration}.session.id`, 128),
+      token: envelope.text(bridge.bridge_token, `${declaration}.session.bridge_token`, 512),
+      expiresAt: Date.parse(expiresAt),
+    },
+    request: acquiredRequest(acquired, declaration),
+  };
+}
+
+export async function acquireOneRun(session) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session),
+    "/kit/runs/acquire",
+    { max: 1 },
+    session.dependencies,
+    session.signal,
+  );
+  if (!Array.isArray(answer?.runs) || answer.runs.length > 1) envelope.refuse("runs");
+  if (answer.runs.length === 0) return null;
+  return acquiredAssignment(answer.runs[0], "runs[0]");
+}
+
+export async function commitRun(session, run) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session),
+    `/kit/runs/${encodeURIComponent(run)}/commit`,
+    {},
+    session.dependencies,
+    session.signal,
+  );
+  if (answer?.state !== "committed") throw new KitRefusal("kit_commit_rejected", run);
+  return answer;
+}
+
+export async function reportRunOutcome(session, run, reported) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session),
+    runOutcomePath(run),
+    reported.cause === null
+      ? { operation_id: reported.operation, outcome: reported.outcome }
+      : { operation_id: reported.operation, outcome: reported.outcome, cause: reported.cause },
+    session.dependencies,
+    session.signal,
+  );
+  if (answer?.run !== run || typeof answer.state !== "string" || answer.state.length === 0) {
+    throw new KitRefusal("kit_outcome_rejected", run);
+  }
+  return { state: answer.state, cause: answer.cause ?? null };
+}
+
+function heldOutcome(run, reported) {
+  if (reported === null) return { session: run, outcome: null };
+  if (reported.cause === null) return { session: run, outcome: reported.outcome };
+  return { session: run, outcome: reported.outcome, cause: reported.cause };
+}
+
+export async function reportSessions(session, held) {
+  const sessions = held.map((entry) => heldOutcome(entry.run, entry.reported));
+  let offset = 0;
+  do {
+    await houseRequest(
+      session.house,
+      await heldControl(session),
+      KIT_SESSIONS_REPORT_PATH,
+      { sessions: sessions.slice(offset, offset + KIT_SESSIONS_REPORT_MAX) },
+      session.dependencies,
+      session.signal,
+    );
+    offset += KIT_SESSIONS_REPORT_MAX;
+  } while (offset < sessions.length);
+  return sessions;
+}
+
+export async function streamAssistantDraft(session, workerSession, blocks) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session),
+    assistantDraftsPath(workerSession),
+    { blocks },
+    session.dependencies,
+    session.signal,
+  );
+  if (!ASSISTANT_DRAFT_STATES.includes(answer?.state)) {
+    throw new KitRefusal("kit_assistant_draft_rejected", workerSession);
+  }
+  return { state: answer.state };
+}
+
+export async function acceptAssistantText(session, workerSession, sealed) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session),
+    assistantTextPath(workerSession),
+    { operation_id: sealed.operation, blocks: sealed.blocks },
+    session.dependencies,
+    session.signal,
+  );
+  if (
+    answer?.session !== workerSession ||
+    typeof answer.turn !== "string" ||
+    answer.turn.length === 0 ||
+    (answer.delivery !== null && typeof answer.delivery !== "string")
+  ) {
+    throw new KitRefusal("kit_assistant_text_rejected", workerSession);
+  }
+  return { turn: answer.turn, delivery: answer.delivery };
+}
+
+export async function admitPlanSnapshot(session, workerSession, snapshot) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session),
+    `/kit/sessions/${encodeURIComponent(workerSession)}/plans`,
+    snapshot,
+    session.dependencies,
+    session.signal,
+  );
+  if (
+    answer?.session !== workerSession ||
+    typeof answer.plan !== "string" ||
+    !["live", "frozen"].includes(answer.state)
+  ) {
+    throw new KitRefusal("kit_plan_rejected", workerSession);
+  }
+  return { plan: answer.plan, state: answer.state };
+}
+
+export async function observeSessionStart(session, workerSession) {
+  return houseRequest(
+    session.house,
+    await heldControl(session),
+    `/kit/sessions/${encodeURIComponent(workerSession)}/started`,
+    {},
+    session.dependencies,
+    session.signal,
+  );
+}
+
+export async function observeSessionStop(session, workerSession, turnCompleted = false) {
+  return houseRequest(
+    session.house,
+    await heldControl(session),
+    `/kit/sessions/${encodeURIComponent(workerSession)}/stopped`,
+    turnCompleted ? { turn_completed: true } : {},
+    session.dependencies,
+    session.signal,
+  );
+}
+
+export async function reportContinuation(session, workerSession, report) {
+  return houseRequest(
+    session.house,
+    await heldControl(session),
+    `/kit/sessions/${encodeURIComponent(workerSession)}/continuation`,
+    {
+      provider_continuation: report.providerContinuation,
+      provider_capacity_exhausted: report.providerCapacityExhausted,
+    },
+    session.dependencies,
+    session.signal,
+  );
+}
+
+export async function replaceSessionAuthority(session, workerSession, signal = session.signal) {
+  const replaced = await houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    `/kit/sessions/${encodeURIComponent(workerSession)}/token`,
+    {},
+    session.dependencies,
+    signal,
+  );
+  const expiresAt = Date.parse(replaced?.bridge_token_expires_at);
+  if (typeof replaced?.bridge_token !== "string" || Number.isNaN(expiresAt)) {
+    throw new KitRefusal("kit_session_token_rejected", workerSession);
+  }
+  return { token: replaced.bridge_token, expiresAt };
+}
+
+export async function sessionAuthority(session, workerSession, bridge, signal = session.signal) {
+  if (bridge.expiresAt - session.now().getTime() > WORKER_RUN_TOKEN_MARGIN_MS) return bridge.token;
+  Object.assign(bridge, await replaceSessionAuthority(session, workerSession, signal));
+  return bridge.token;
+}
+
+const commands = declarationReader("kit_command_rejected");
+
+function acquiredStop(value, declaration) {
+  const acquired = commands.plain(value, declaration);
+  if (acquired.command !== "stop") return null;
+  return {
+    run: commands.text(acquired.run, `${declaration}.run`, 128),
+    session: commands.text(acquired.session, `${declaration}.session`, 128),
+    requestedAt: commands.text(acquired.requested_at, `${declaration}.requested_at`, 64),
+  };
+}
+
+function acquiredInterrupt(value, declaration) {
+  const acquired = commands.plain(value, declaration);
+  if (acquired.command !== "interrupt") return null;
+  return {
+    interrupt: commands.text(acquired.interrupt, `${declaration}.interrupt`, 128),
+    run: commands.text(acquired.run, `${declaration}.run`, 128),
+    session: commands.text(acquired.session, `${declaration}.session`, 128),
+    requestedAt: commands.text(acquired.requested_at, `${declaration}.requested_at`, 64),
+  };
+}
+
+export async function reportSessionHeartbeat(session, workerSession) {
+  await houseRequest(
+    session.house,
+    await heldControl(session),
+    `/kit/sessions/${encodeURIComponent(workerSession)}/heartbeat`,
+    {},
+    session.dependencies,
+    session.signal,
+  );
+}
+
+function answeredValue(value, declaration) {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) commands.refuse(declaration);
+    return value;
+  }
+  if (typeof value === "string") {
+    if (value.length > INTERACTION_VALUE_MAX) commands.refuse(declaration);
+    return value;
+  }
+  if (!Array.isArray(value) || value.length > INTERACTION_VALUES_MAX) commands.refuse(declaration);
+  return value.map((item, position) => {
+    const named = `${declaration}[${position}]`;
+    if (typeof item !== "string" || item.length > INTERACTION_VALUE_MAX) commands.refuse(named);
+    return item;
+  });
+}
+
+function answeredContent(value, declaration) {
+  const content = commands.plain(value, declaration);
+  const named = Object.keys(content);
+  return Object.fromEntries(
+    named.map((name) => {
+      if (name.length === 0 || name.length > INTERACTION_PROPERTY_MAX) {
+        commands.refuse(`${declaration}.${name}`);
+      }
+      return [name, answeredValue(content[name], `${declaration}.${name}`)];
+    }),
+  );
+}
+
+function acquiredResponse(value, declaration) {
+  const response = commands.closed(value, ["action", "content"], declaration);
+  if (response.action === "decline") {
+    if (response.content !== undefined) commands.refuse(`${declaration}.content`);
+    return { action: "decline" };
+  }
+  if (response.action !== "accept") commands.refuse(`${declaration}.action`);
+  return { action: "accept", content: answeredContent(response.content, `${declaration}.content`) };
+}
+
+function acquiredAnswer(value, declaration) {
+  const acquired = commands.plain(value, declaration);
+  if (acquired.command !== "answer") return null;
+  return {
+    interaction: commands.text(acquired.interaction, `${declaration}.interaction`, 128),
+    run: commands.text(acquired.run, `${declaration}.run`, 128),
+    session: commands.text(acquired.session, `${declaration}.session`, 128),
+    providerTurn: commands.text(
+      acquired.provider_turn,
+      `${declaration}.provider_turn`,
+      INTERACTION_CORRELATION_MAX,
+    ),
+    correlation: commands.text(
+      acquired.correlation,
+      `${declaration}.correlation`,
+      INTERACTION_CORRELATION_MAX,
+    ),
+    revision: commands.positiveCount(acquired.revision, `${declaration}.revision`),
+    response: acquiredResponse(acquired.response, `${declaration}.response`),
+  };
+}
+
+export async function acquireCommands(session, max, kinds = ["stop"]) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session),
+    "/kit/commands/acquire",
+    { max, kinds },
+    session.dependencies,
+    session.signal,
+  );
+  if (!Array.isArray(answer?.commands)) commands.refuse("commands");
+  const acquired = answer.commands.map((command, position) => ({
+    command,
+    declaration: `commands[${position}]`,
+  }));
+  return {
+    stops: acquired
+      .map((entry) => acquiredStop(entry.command, entry.declaration))
+      .filter((stop) => stop !== null),
+    answers: acquired
+      .map((entry) => acquiredAnswer(entry.command, entry.declaration))
+      .filter((answer) => answer !== null),
+    interrupts: acquired
+      .map((entry) => acquiredInterrupt(entry.command, entry.declaration))
+      .filter((interrupt) => interrupt !== null),
+  };
+}
+
+const INTERACTION_STATES = ["pending", "answered", "settled"];
+
+export async function admitInteraction(session, workerSession, batch) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session),
+    sessionInteractionsPath(workerSession),
+    batch,
+    session.dependencies,
+    session.signal,
+  );
+  if (
+    answer?.session !== workerSession ||
+    !INTERACTION_STATES.includes(answer.state) ||
+    typeof answer.interaction !== "string" ||
+    answer.interaction.length === 0 ||
+    answer.interaction.length > 128
+  ) {
+    throw new KitRefusal("kit_interaction_rejected", workerSession);
+  }
+  return {
+    interaction: answer.interaction,
+    state: answer.state,
+    disposition: answer.disposition ?? null,
+  };
+}
+
+const SECRET_RELAY_OUTCOMES = ["collected", "released"];
+
+function relayedCollection(answer, ceremony) {
+  if (!SECRET_RELAY_OUTCOMES.includes(answer?.outcome)) return null;
+  if (answer.outcome === "released") return { collected: null };
+  const content = answer.content;
+  if (typeof content !== "object" || content === null || Array.isArray(content)) return null;
+  const wanted = ceremony.steps.filter((step) => step.kind === "collect").map((step) => step.name);
+  const given = Object.keys(content);
+  if (given.length !== wanted.length || wanted.some((name) => !given.includes(name))) return null;
+  if (
+    given.some(
+      (name) => typeof content[name] !== "string" || content[name].length > SECRET_VALUE_MAX,
+    )
+  ) {
+    return null;
+  }
+  return { collected: content };
+}
+
+export async function awaitSecretInput(session, interaction, ceremony, signal = session.signal) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    secretInputPath(interaction),
+    { steps: ceremony.steps },
+    session.dependencies,
+    signal,
+  );
+  const relayed = relayedCollection(answer, ceremony);
+  if (relayed === null) throw new KitRefusal("kit_interaction_rejected", interaction);
+  return relayed;
+}
+
+export async function reportInteractionOutcome(session, interaction, outcome) {
+  if (!INTERACTION_OUTCOMES.includes(outcome)) {
+    throw new KitRefusal("kit_interaction_rejected", interaction);
+  }
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session),
+    interactionOutcomePath(interaction),
+    { outcome },
+    session.dependencies,
+    session.signal,
+  );
+  if (answer?.interaction !== interaction) {
+    throw new KitRefusal("kit_interaction_rejected", interaction);
+  }
+  return { disposition: answer.disposition ?? null };
+}
+
+export async function reportInterruptOutcome(session, interrupt, outcome) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session),
+    `/kit/interrupts/${encodeURIComponent(interrupt)}/outcome`,
+    { outcome },
+    session.dependencies,
+    session.signal,
+  );
+  if (answer?.interrupt !== interrupt || answer.outcome !== outcome) {
+    throw new KitRefusal("kit_interrupt_rejected", interrupt);
+  }
+  return { outcome: answer.outcome };
+}
+
+export async function acquireOneResumption(session) {
+  const answer = await houseRequest(session.house, await heldControl(session), "/kit/commands/acquire",
+    { max: 1, kinds: ["resume"] }, session.dependencies, session.signal);
+  if (!Array.isArray(answer?.commands) || answer.commands.length > 1) commands.refuse("commands");
+  if (answer.commands.length === 0) return null;
+  const command = commands.plain(answer.commands[0], "commands[0]");
+  if (command.command !== "resume" || command.origin !== "resumption") commands.refuse("commands[0].command");
+  const bridge = commands.plain(command.session, "commands[0].session");
+  const expiresAt = Date.parse(bridge.bridge_token_expires_at);
+  if (!Number.isFinite(expiresAt)) commands.refuse("commands[0].session.bridge_token_expires_at");
+  return {
+    run: commands.text(command.run, "commands[0].run", 128),
+    route: acquiredRoute(command.route, "commands[0].route"),
+    session: {
+      id: commands.text(bridge.id, "commands[0].session.id", 128),
+      token: commands.text(bridge.bridge_token, "commands[0].session.bridge_token", 512),
+      expiresAt,
+    },
+  };
+}
+
+export async function rejectResumption(session, workerSession) {
+  return houseRequest(session.house, await heldControl(session),
+    `/kit/sessions/${encodeURIComponent(workerSession)}/resumption-rejected`, {}, session.dependencies, session.signal);
+}
+
+function mcpNameHeader(frame) {
+  const value = frame.method === "resources/read"
+    ? frame.params?.uri
+    : ["tools/call", "prompts/get"].includes(frame.method) ? frame.params?.name : undefined;
+  if (typeof value !== "string") return {};
+  const plain = /^[\t\x20-\x7e]+$/.test(value) && value === value.trim() &&
+    !(value.startsWith("=?base64?") && value.endsWith("?="));
+  return { "mcp-name": plain ? value : `=?base64?${Buffer.from(value).toString("base64")}?=` };
+}
+
+export async function callHouseMcp(session, token, frame, signal = session.signal) {
+  if (signal?.aborted) throw new KitRefusal("kit_command_cancelled");
+  const fetcher = session.dependencies.fetch ?? fetch;
+  let response;
+  try {
+    response = await fetcher(`${session.house}/`, {
+      method: "POST",
+      headers: {
+        accept: "application/json, text/event-stream",
+        authorization: `Bearer ${token}`,
+        "content-type": "application/json",
+        "mcp-protocol-version": MCP_PROTOCOL_VERSION,
+        ...(typeof frame.method === "string" ? { "mcp-method": frame.method } : {}),
+        ...mcpNameHeader(frame),
+      },
+      body: JSON.stringify(frame),
+      signal,
+    });
+  } catch {
+    if (signal?.aborted) throw new KitRefusal("kit_command_cancelled");
+    throw new KitRefusal("kit_house_unavailable", "/");
+  }
+  if (response.status >= 500) {
+    throw houseRefusal(response.status, await response.json().catch(() => null), "/");
+  }
+  let serialized;
+  try {
+    serialized = await response.text();
+  } catch {
+    if (signal?.aborted) throw new KitRefusal("kit_command_cancelled");
+    if (!response.ok) throw new KitRefusal("kit_house_mcp_rejected", `${response.status}`);
+    throw new KitRefusal("kit_house_unavailable", "/");
+  }
+  if (serialized.trim() === "") {
+    if (!response.ok) throw new KitRefusal("kit_house_mcp_rejected", `${response.status}`);
+    if (frame.id === undefined) return null;
+    throw new KitRefusal("kit_house_unavailable", "/");
+  }
+  let answer;
+  try {
+    answer = JSON.parse(serialized);
+  } catch {
+    throw new KitRefusal("kit_house_mcp_rejected", `${response.status}`);
+  }
+  if (answer?.jsonrpc !== "2.0") {
+    throw new KitRefusal("kit_house_mcp_rejected", `${response.status}`);
+  }
+  return answer;
+}