@agentshouse/kit 0.1.0-alpha.3 → 0.1.0-alpha.30

package/src/house.js

@@ -1,8 +1,10 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readFile, rm } from "node:fs/promises";
+import { connect, createServer } from "node:net";
+import { dirname, join } from "node:path";
 import { assertAcquiredCommandAdapter } from "./adapter.js";
+import { readFrames, writeFrame } from "./channel.js";
 import {
-  assistantDraftsPath,
   assistantTextPath,
   ADAPTER_KINDS,
   INTERACTION_CORRELATION_MAX,
@@ -21,11 +23,14 @@ import {
   KIT_SESSIONS_REPORT_PATH,
   KIT_SETUP_ACQUIRE_PATH,
   KIT_SETUP_REPORT_PATH,
+  KIT_SOURCES_DESIRED_PATH,
+  KIT_SOURCES_REPORT_PATH,
   KIT_WORKSPACES_ACQUIRE_PATH,
   LEASE_RENEWAL_MARGIN_MS,
   MCP_PROTOCOL_VERSION,
   WORKER_RUN_TOKEN_MARGIN_MS,
   runOutcomePath,
+  runRequestPath,
   secretInputPath,
   SECRET_VALUE_MAX,
   sessionInteractionsPath,
@@ -35,7 +40,10 @@ 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 RESIDENT = "Resident";
+const LEASE_ACTIVE = "environment_control_lease_active";
+const UPGRADE_REQUIRED = "kit_upgrade_required";
+const UPDATE_DRAINING = "kit_update_draining";
 const ITEM_OUTCOMES = ["accepted", "duplicate", "rejected"];
 
 async function readCredential(directory) {
@@ -49,6 +57,10 @@ async function readCredential(directory) {
   return stored;
 }
 
+function latchRefusal(answer, dependencies) {
+  if (answer?.error?.code === UPGRADE_REQUIRED) dependencies.contractRefused?.();
+}
+
 async function houseAnswer(house, path, init, dependencies, signal) {
   const fetcher = dependencies.fetch ?? fetch;
   let response;
@@ -66,6 +78,7 @@ async function houseAnswer(house, path, init, dependencies, signal) {
   } catch {
     answer = null;
   }
+  latchRefusal(answer, dependencies);
   throwHouseAnswer(response.status, answer, path);
   if (answer === null) throw new KitRefusal("kit_house_unavailable", path);
   return answer;
@@ -105,7 +118,291 @@ function heldLease(answer) {
   return { lease: answer.lease, expiresAt: Date.parse(answer.expires_at) };
 }
 
+function residentSocket(directory) {
+  return join(directory, "run", "resident.sock");
+}
+
+export function updateDrain(directory) {
+  return join(directory, "state", "update-drain");
+}
+
+export function refuseDrained(directory) {
+  if (existsSync(updateDrain(directory))) throw new KitRefusal(UPDATE_DRAINING);
+}
+
+function residentAnswer(status, code) {
+  const body = Buffer.from(JSON.stringify({ error: { code } })).toString("base64");
+  return { status, type: "application/json", body };
+}
+
+function newWork(path) {
+  return path === "/kit/telegram/updates" || (path.endsWith("/acquire") && path !== "/kit/commands/acquire");
+}
+
+async function residentRelay(session, request, signal, draining) {
+  const path = typeof request.path === "string" ? request.path : "";
+  if (!path.startsWith("/kit/") || path.startsWith("/kit/lease")) {
+    return residentAnswer(403, "kit_resident_route_refused");
+  }
+  if (draining && newWork(path)) {
+    return residentAnswer(409, UPDATE_DRAINING);
+  }
+  let authorization;
+  try {
+    authorization = await heldControl(session, signal);
+  } catch (error) {
+    return residentAnswer(error.status ?? 401, error.code ?? "kit_lease_rejected");
+  }
+  try {
+    const response = await (session.dependencies.fetch ?? fetch)(`${session.house}${path}`, {
+      method: request.method,
+      headers: { ...request.headers, authorization },
+      body: request.text ?? (request.bytes === undefined ? undefined : Buffer.from(request.bytes, "base64")),
+      signal,
+    });
+    const body = Buffer.from(await response.arrayBuffer());
+    if (response.status === 409) latchRefusal(JSON.parse(body.toString("utf8")), session.dependencies);
+    return {
+      status: response.status,
+      type: response.headers.get("content-type"),
+      body: body.length === 0 ? null : body.toString("base64"),
+    };
+  } catch {
+    return residentAnswer(503, "kit_house_unavailable");
+  }
+}
+
+export async function serveResident(session, directory, signal, drain, push, capture, stream = null) {
+  const socket = residentSocket(directory);
+  await mkdir(dirname(socket), { recursive: true, mode: 0o700 });
+  await rm(socket, { force: true });
+  const connections = new Set();
+  let holder = null;
+  let listening = null;
+  let draining = false;
+  function answerDrain(connection) {
+    draining = true;
+    drain(holder !== null).then(
+      (answer) => {
+        if (!connection.destroyed) writeFrame(connection, answer);
+        connection.end();
+      },
+      () => connection.destroy(),
+    );
+    return false;
+  }
+  function hold(connection) {
+    if (holder !== null || draining || existsSync(updateDrain(directory))) {
+      writeFrame(connection, { refused: draining || holder === null ? UPDATE_DRAINING : LEASE_ACTIVE });
+      connection.end();
+      return false;
+    }
+    holder = connection;
+    renewControl(session, signal).then(
+      () => {
+        writeFrame(connection, { held: true });
+        if (holder === connection) listening = connection;
+      },
+      (error) => {
+        writeFrame(connection, { refused: error.code ?? "kit_lease_rejected" });
+        connection.end();
+      },
+    );
+    return true;
+  }
+  const server = createServer((connection) => {
+    connections.add(connection);
+    connection.on("error", () => connection.destroy());
+    const relayed = new Map();
+    let held = null;
+    connection.on("close", () => {
+      connections.delete(connection);
+      if (holder === connection) holder = null;
+      if (listening === connection) listening = null;
+      for (const cancelled of relayed.values()) cancelled.abort();
+    });
+    readFrames(connection, {
+      onFrame: (request) => {
+        if (held === null) {
+          held = request.drain === true ? answerDrain(connection) : hold(connection);
+          return;
+        }
+        if (!held) return;
+        if (request.stream !== undefined) {
+          if (request.stream?.type === "gap") stream?.write(request.stream);
+          return;
+        }
+        if (request.cancel === true) {
+          relayed.get(request.id)?.abort();
+          return;
+        }
+        const cancelled = new AbortController();
+        relayed.set(request.id, cancelled);
+        const relaySignal = AbortSignal.any([signal, cancelled.signal]);
+        const answered =
+          request.push !== undefined
+            ? push(request.push, relaySignal).then((pushed) => ({ pushed }))
+            : request.capture !== undefined
+              ? capture(request.capture, relaySignal).then(
+                  (captured) => ({ captured }),
+                  (error) => ({ refused: error?.code ?? "kit_resident_unavailable" }),
+                )
+              : residentRelay(session, request, relaySignal, draining);
+        void answered.then((answer) => {
+          relayed.delete(request.id);
+          if (!connection.destroyed) writeFrame(connection, { id: request.id, ...answer });
+        });
+      },
+      onRefusal: () => connection.destroy(),
+    });
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socket, resolve);
+  });
+  await chmod(socket, 0o600);
+  return {
+    serving: () => holder !== null,
+    forward(frame) {
+      if (listening !== null && !listening.destroyed) writeFrame(listening, { stream: frame });
+    },
+    async close() {
+      for (const connection of connections) connection.destroy();
+      await new Promise((resolve) => server.close(resolve));
+      await rm(socket, { force: true });
+    },
+  };
+}
+
+export function requestDrain(directory) {
+  const connection = connect(residentSocket(directory));
+  return new Promise((resolve, reject) => {
+    const unavailable = () => reject(new KitRefusal("kit_resident_unavailable"));
+    connection.on("error", unavailable);
+    connection.on("close", unavailable);
+    readFrames(connection, {
+      onFrame: (answer) => {
+        resolve(answer);
+        connection.end();
+      },
+      onRefusal: () => connection.destroy(),
+    });
+    writeFrame(connection, { drain: true });
+  });
+}
+
+async function residentDelegation(directory, fetcher) {
+  const connection = connect(residentSocket(directory));
+  const pending = new Map();
+  const watchers = new Set();
+  let greet;
+  const greeting = new Promise((resolve) => {
+    greet = resolve;
+  });
+  const unavailable = () => residentAnswer(503, "kit_resident_unavailable");
+  function settle(id, answer) {
+    pending.get(id)?.(answer);
+    pending.delete(id);
+    if (pending.size === 0) connection.unref();
+  }
+  connection.on("error", () => connection.destroy());
+  connection.on("close", () => {
+    greet(null);
+    for (const id of [...pending.keys()]) settle(id, unavailable());
+  });
+  readFrames(connection, {
+    onFrame: (frame) => {
+      if (frame.id !== undefined) settle(frame.id, frame);
+      else if (frame.stream !== undefined) for (const heard of watchers) heard.viewed?.(frame.stream);
+      else greet(frame);
+    },
+    onRefusal: () => connection.destroy(),
+  });
+  writeFrame(connection, { hold: true });
+  const held = await greeting;
+  if (held === null) return null;
+  if (held.held !== true) {
+    connection.destroy();
+    throw new KitRefusal(held.refused);
+  }
+  connection.unref();
+  let next = 0;
+  function exchange(frame, signal) {
+    signal?.throwIfAborted();
+    if (connection.destroyed) return Promise.resolve(unavailable());
+    return new Promise((resolve, reject) => {
+      const id = (next += 1);
+      const cancel = () => {
+        pending.delete(id);
+        settle(id);
+        if (!connection.destroyed) writeFrame(connection, { id, cancel: true });
+        reject(signal.reason);
+      };
+      signal?.addEventListener("abort", cancel, { once: true });
+      pending.set(id, (answer) => {
+        signal?.removeEventListener("abort", cancel);
+        resolve(answer);
+      });
+      connection.ref();
+      writeFrame(connection, { id, ...frame });
+    });
+  }
+  async function push(request, signal) {
+    const answer = await exchange({ push: request }, signal);
+    if (answer.pushed === undefined) throw new KitRefusal("kit_resident_unavailable");
+    return answer.pushed;
+  }
+  async function capture(source, signal) {
+    const answer = await exchange({ capture: source }, signal);
+    if (answer.refused !== undefined) throw new KitRefusal(answer.refused);
+    if (answer.captured === undefined) throw new KitRefusal("kit_resident_unavailable");
+    return answer.captured;
+  }
+  async function delegated(url, init = {}) {
+    const { authorization, ...headers } = init.headers ?? {};
+    if (authorization !== RESIDENT) return fetcher(url, init);
+    const address = new URL(url);
+    const answer = await exchange(
+      {
+        method: init.method ?? "GET",
+        path: `${address.pathname}${address.search}`,
+        headers,
+        ...(typeof init.body === "string"
+          ? { text: init.body }
+          : init.body === undefined
+            ? {}
+            : { bytes: Buffer.from(init.body).toString("base64") }),
+      },
+      init.signal,
+    );
+    return new Response(answer.body === null ? null : Buffer.from(answer.body, "base64"), {
+      status: answer.status,
+      headers: answer.type === null ? {} : { "content-type": answer.type },
+    });
+  }
+  function relay(signal, heard) {
+    return new Promise((resolve) => {
+      const end = () => {
+        signal.removeEventListener("abort", end);
+        connection.removeListener("close", end);
+        if (!watchers.delete(heard)) return;
+        heard.closed?.();
+        resolve();
+      };
+      watchers.add(heard);
+      heard.opened?.((frame) => {
+        if (!connection.destroyed) writeFrame(connection, { stream: frame });
+      });
+      signal.addEventListener("abort", end, { once: true });
+      connection.once("close", end);
+      if (signal.aborted || connection.destroyed) end();
+    });
+  }
+  return { connection, fetch: delegated, push, capture, relay };
+}
+
 export async function openSession(options, dependencies = {}) {
+  if (options.resident !== true) refuseDrained(options.directory);
   const session = {
     house: options.house,
     dependencies,
@@ -114,27 +411,42 @@ export async function openSession(options, dependencies = {}) {
     expiresAt: 0,
     signal: options.signal,
   };
+  const resident =
+    options.acquire === true || options.resident === true
+      ? null
+      : await residentDelegation(options.directory, dependencies.fetch ?? fetch);
+  if (resident !== null) {
+    session.resident = resident.connection;
+    session.push = resident.push;
+    session.capture = resident.capture;
+    session.relay = resident.relay;
+    session.dependencies = { ...dependencies, fetch: resident.fetch };
+    return session;
+  }
+  session.dependencies = {
+    ...dependencies,
+    contractRefused: () => {
+      session.refused = true;
+    },
+  };
   const credential = await readCredential(options.directory);
-  Object.assign(
-    session,
-    heldLease(
-      await houseRequest(
-        session.house,
-        `Bearer ${credential}`,
-        "/kit/lease",
-        {},
-        session.dependencies,
-        session.signal,
-      ),
-    ),
-  );
+  const answer = await houseRequest(
+    session.house,
+    `Bearer ${credential}`,
+    "/kit/lease",
+    {},
+    session.dependencies,
+    session.signal,
+  ).catch((error) => {
+    if (options.resident === true && session.refused) return null;
+    throw error;
+  });
+  if (answer !== null) Object.assign(session, heldLease(answer));
   return session;
 }
 
-export async function heldControl(session, signal = session.signal) {
-  if (session.expiresAt - session.now().getTime() > LEASE_RENEWAL_MARGIN_MS) {
-    return `Bearer ${session.lease}`;
-  }
+async function renewControl(session, signal) {
+  if (session.refused) throw new KitRefusal(UPGRADE_REQUIRED);
   Object.assign(
     session,
     heldLease(
@@ -148,10 +460,18 @@ export async function heldControl(session, signal = session.signal) {
       ),
     ),
   );
+}
+
+export async function heldControl(session, signal = session.signal) {
+  if (session.resident !== undefined) return RESIDENT;
+  if (session.refused) throw new KitRefusal(UPGRADE_REQUIRED);
+  if (session.expiresAt - session.now().getTime() <= LEASE_RENEWAL_MARGIN_MS) {
+    await renewControl(session, signal);
+  }
   return `Bearer ${session.lease}`;
 }
 
-function controlSleep(milliseconds, signal) {
+export function controlSleep(milliseconds, signal) {
   return new Promise((resolve, reject) => {
     if (signal.aborted) {
       reject(new KitRefusal("kit_command_cancelled"));
@@ -195,9 +515,11 @@ export function mutatingCall(classification) {
 }
 
 export async function releaseControl(session, options = {}) {
+  session.resident?.end();
   if (session.lease === null) return;
   const held = session.lease;
   try {
+    if (session.refused) throw new KitRefusal(UPGRADE_REQUIRED);
     await houseRequest(
       session.house,
       `Bearer ${held}`,
@@ -229,6 +551,7 @@ export async function maintainControl(session, operation, signal, { release = tr
     signal?.addEventListener("abort", cancelOperation, { once: true });
   });
   const renewal = (async () => {
+    if (session.resident !== undefined) return;
     const sleep = session.dependencies.controlSleep ?? controlSleep;
     while (!stopped) {
       const delay = Math.max(
@@ -245,7 +568,7 @@ export async function maintainControl(session, operation, signal, { release = tr
           throw new KitRefusal("kit_lease_rejected");
         }
       } catch (error) {
-        if (stopped) return;
+        if (stopped || session.refused) return;
         rejectFailure(error);
         maintenance.abort();
         return;
@@ -253,20 +576,14 @@ export async function maintainControl(session, operation, signal, { release = tr
     }
   })();
   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;
+    return await Promise.race([running, failure, cancellation]);
   } finally {
     stopped = true;
     maintenance.abort();
     signal?.removeEventListener("abort", cancelOperation);
     await Promise.all([renewal, running.catch(() => undefined)]);
-    if (ended && release) await releaseControl(session);
+    if (release) await releaseControl(session);
   }
 }
 
@@ -426,6 +743,30 @@ export async function desiredAgents(session, signal = session.signal) {
   return answer.agents;
 }
 
+export async function desiredSources(session, signal = session.signal) {
+  const answer = await houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    KIT_SOURCES_DESIRED_PATH,
+    {},
+    session.dependencies,
+    signal,
+  );
+  if (!Array.isArray(answer?.sources)) throw new KitRefusal("kit_sources_rejected");
+  return answer.sources;
+}
+
+export async function reportSources(session, sources, signal = session.signal) {
+  return houseRequest(
+    session.house,
+    await heldControl(session, signal),
+    KIT_SOURCES_REPORT_PATH,
+    { sources },
+    session.dependencies,
+    signal,
+  );
+}
+
 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) {
@@ -479,6 +820,7 @@ export async function reportLogin(session, login, outcome, signal = session.sign
 }
 
 const envelope = declarationReader("kit_acquire_rejected");
+const input = declarationReader("kit_run_input_unreadable");
 
 function acquiredRoute(value, declaration) {
   const route = envelope.plain(value, declaration);
@@ -496,79 +838,82 @@ function acquiredRoute(value, declaration) {
 
 function conversationText(value, declaration) {
   if (value === null) return null;
-  if (typeof value !== "string" || value.length > 4096) envelope.refuse(declaration);
+  if (typeof value !== "string" || value.length > 4096) input.refuse(declaration);
   return value;
 }
 
 function conversationMessage(value, declaration) {
-  const message = envelope.plain(value, declaration);
+  const message = input.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`);
+  if (!Array.isArray(message.files)) input.refuse(`${declaration}.files`);
   const files = message.files.map((value, index) => {
     const name = `${declaration}.files[${index}]`;
-    const file = envelope.plain(value, name);
+    const file = input.plain(value, name);
     if (file.bytes !== null && (!Number.isSafeInteger(file.bytes) || file.bytes < 0)) {
-      envelope.refuse(`${name}.bytes`);
+      input.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),
+      path: input.text(file.path, `${name}.path`, 2048),
+      media_kind: input.text(file.media_kind, `${name}.media_kind`, 128),
+      media_type: file.media_type === null ? null : input.text(file.media_type, `${name}.media_type`, 255),
       bytes: file.bytes,
     };
   });
-  if (!text && !caption && files.length === 0) envelope.refuse(declaration);
+  if (!text && !caption && files.length === 0) input.refuse(declaration);
   return {
-    message_id: envelope.text(message.message_id, `${declaration}.message_id`, 128),
+    message_id: input.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`);
+function runRequest(answer) {
+  const request = input.plain(answer, "request");
+  if (request.kind === "conversation") {
+    if (request.origin !== "user") input.refuse("request.origin");
+    const turn = input.plain(request.turn, "request.turn");
     return {
+      kind: "conversation",
       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}]`)),
-        },
+      turn: {
+        id: input.text(turn.id, "request.turn.id", 128),
+        sequence: input.positiveCount(turn.sequence, "request.turn.sequence"),
+        messages: input.filled(turn.messages, "request.turn.messages")
+          .map((message, index) => conversationMessage(message, `request.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`);
+  if (request.kind !== "routine") input.refuse("request.kind");
+  const routine = input.plain(request.routine, "request.routine");
+  if (typeof request.payload !== "string" || Array.from(request.payload).length > 20_000) input.refuse("request.payload");
+  if (!Array.isArray(request.references)) input.refuse("request.references");
   return {
-    origin: envelope.text(acquired.origin, `${declaration}.origin`, 32),
+    kind: "routine",
+    origin: input.text(request.origin, "request.origin", 32),
     routine: {
-      name: envelope.text(routine.name, `${declaration}.routine.name`, 256),
-      version: envelope.positiveCount(routine.version, `${declaration}.routine.version`),
+      name: input.text(routine.name, "request.routine.name", 256),
+      version: input.positiveCount(routine.version, "request.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),
+    instruction: input.text(request.instruction, "request.instruction", 256 * 1024),
+    payload: request.payload,
+    references: request.references.map((reference, index) => input.plain(reference, `request.references[${index}]`)),
+    requested_by: input.text(request.requested_by, "request.requested_by", 128),
+    requested_at: input.text(request.requested_at, "request.requested_at", 64),
+    deliver_at: request.deliver_at === null ? null : input.text(request.deliver_at, "request.deliver_at", 64),
   };
 }
 
+export async function readRunRequest(session, run, token, signal = session.signal) {
+  return runRequest(await houseRequest(
+    session.house,
+    `Bearer ${token}`,
+    runRequestPath(run),
+    {},
+    session.dependencies,
+    signal,
+  ));
+}
+
 function acquiredAssignment(value, declaration) {
   const acquired = envelope.plain(value, declaration);
   const bridge = envelope.plain(acquired.session, `${declaration}.session`);
@@ -582,9 +927,13 @@ function acquiredAssignment(value, declaration) {
   if (Number.isNaN(Date.parse(expiresAt))) {
     envelope.refuse(`${declaration}.session.bridge_token_expires_at`);
   }
+  if (typeof plan.base_instructions !== "string") {
+    envelope.refuse(`${declaration}.plan.base_instructions`);
+  }
   return {
     run: envelope.text(acquired.run, `${declaration}.run`, 128),
     agentId: envelope.text(plan.agent_id, `${declaration}.plan.agent_id`, 128),
+    baseInstructions: plan.base_instructions,
     workingDirectory: envelope.text(
       plan.working_directory,
       `${declaration}.plan.working_directory`,
@@ -597,7 +946,6 @@ function acquiredAssignment(value, declaration) {
       token: envelope.text(bridge.bridge_token, `${declaration}.session.bridge_token`, 512),
       expiresAt: Date.parse(expiresAt),
     },
-    request: acquiredRequest(acquired, declaration),
   };
 }
 
@@ -628,14 +976,17 @@ export async function commitRun(session, run) {
   return answer;
 }
 
-export async function reportRunOutcome(session, run, reported) {
+export async function reportRunOutcome(session, run, reported, plan = null) {
   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 },
+    withPlan(
+      reported.cause === null
+        ? { operation_id: reported.operation, outcome: reported.outcome }
+        : { operation_id: reported.operation, outcome: reported.outcome, cause: reported.cause },
+      plan,
+    ),
     session.dependencies,
     session.signal,
   );
@@ -668,27 +1019,16 @@ export async function reportSessions(session, held) {
   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 };
+function withPlan(body, plan) {
+  return plan === null || plan === undefined ? body : { ...body, plan };
 }
 
-export async function acceptAssistantText(session, workerSession, sealed) {
+export async function acceptAssistantText(session, workerSession, sealed, plan = null) {
   const answer = await houseRequest(
     session.house,
     await heldControl(session),
     assistantTextPath(workerSession),
-    { operation_id: sealed.operation, blocks: sealed.blocks },
+    withPlan({ operation_id: sealed.operation, blocks: sealed.blocks }, plan),
     session.dependencies,
     session.signal,
   );
@@ -703,27 +1043,12 @@ export async function acceptAssistantText(session, workerSession, sealed) {
   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 };
+function named(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
 }
 
 export async function observeSessionStart(session, workerSession) {
-  return houseRequest(
+  const answer = await houseRequest(
     session.house,
     await heldControl(session),
     `/kit/sessions/${encodeURIComponent(workerSession)}/started`,
@@ -731,14 +1056,19 @@ export async function observeSessionStart(session, workerSession) {
     session.dependencies,
     session.signal,
   );
+  const conversation = named(answer?.conversation_id);
+  const turn = named(answer?.turn_id);
+  return conversation === null || turn === null
+    ? null
+    : { conversation_id: conversation, turn_id: turn, attempt_id: workerSession };
 }
 
-export async function observeSessionStop(session, workerSession, turnCompleted = false) {
+export async function observeSessionStop(session, workerSession, turnCompleted = false, plan = null) {
   return houseRequest(
     session.house,
     await heldControl(session),
     `/kit/sessions/${encodeURIComponent(workerSession)}/stopped`,
-    turnCompleted ? { turn_completed: true } : {},
+    withPlan(turnCompleted ? { turn_completed: true } : {}, plan),
     session.dependencies,
     session.signal,
   );
@@ -803,17 +1133,6 @@ function acquiredInterrupt(value, declaration) {
   };
 }
 
-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") {
@@ -983,12 +1302,12 @@ export async function reportInteractionOutcome(session, interaction, outcome) {
   return { disposition: answer.disposition ?? null };
 }
 
-export async function reportInterruptOutcome(session, interrupt, outcome) {
+export async function reportInterruptOutcome(session, interrupt, outcome, plan = null) {
   const answer = await houseRequest(
     session.house,
     await heldControl(session),
     `/kit/interrupts/${encodeURIComponent(interrupt)}/outcome`,
-    { outcome },
+    withPlan({ outcome }, outcome === "interrupted" ? plan : null),
     session.dependencies,
     session.signal,
   );