@agentshouse/kit 0.1.0-alpha.27 → 0.1.0-alpha.29

package/src/house.js

@@ -5,7 +5,6 @@ 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,
@@ -45,7 +44,6 @@ const RESIDENT = "Resident";
 const LEASE_ACTIVE = "environment_control_lease_active";
 const UPGRADE_REQUIRED = "kit_upgrade_required";
 const UPDATE_DRAINING = "kit_update_draining";
-const ASSISTANT_DRAFT_STATES = ["streamed", "unsupported"];
 const ITEM_OUTCOMES = ["accepted", "duplicate", "rejected"];
 
 async function readCredential(directory) {
@@ -174,12 +172,13 @@ async function residentRelay(session, request, signal, draining) {
   }
 }
 
-export async function serveResident(session, directory, signal, drain, push, capture) {
+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;
@@ -200,7 +199,10 @@ export async function serveResident(session, directory, signal, drain, push, cap
     }
     holder = connection;
     renewControl(session, signal).then(
-      () => writeFrame(connection, { held: true }),
+      () => {
+        writeFrame(connection, { held: true });
+        if (holder === connection) listening = connection;
+      },
       (error) => {
         writeFrame(connection, { refused: error.code ?? "kit_lease_rejected" });
         connection.end();
@@ -216,6 +218,7 @@ export async function serveResident(session, directory, signal, drain, push, cap
     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, {
@@ -225,6 +228,10 @@ export async function serveResident(session, directory, signal, drain, push, cap
           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;
@@ -256,6 +263,9 @@ export async function serveResident(session, directory, signal, drain, push, cap
   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));
@@ -284,6 +294,7 @@ export function requestDrain(directory) {
 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;
@@ -300,7 +311,11 @@ async function residentDelegation(directory, fetcher) {
     for (const id of [...pending.keys()]) settle(id, unavailable());
   });
   readFrames(connection, {
-    onFrame: (frame) => (frame.id === undefined ? greet(frame) : settle(frame.id, frame)),
+    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 });
@@ -365,7 +380,25 @@ async function residentDelegation(directory, fetcher) {
       headers: answer.type === null ? {} : { "content-type": answer.type },
     });
   }
-  return { connection, fetch: delegated, push, capture };
+  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 = {}) {
@@ -386,6 +419,7 @@ export async function openSession(options, dependencies = {}) {
     session.resident = resident.connection;
     session.push = resident.push;
     session.capture = resident.capture;
+    session.relay = resident.relay;
     session.dependencies = { ...dependencies, fetch: resident.fetch };
     return session;
   }
@@ -942,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,
   );
@@ -982,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,
   );
@@ -1017,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`,
@@ -1045,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,
   );
@@ -1117,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") {
@@ -1297,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,
   );

package/src/kit-work-stream.js

@@ -1,11 +1,18 @@
 import { setTimeout as delay } from "node:timers/promises";
 import WebSocket from "ws";
-import { KIT_CONTRACT_VERSION } from "./contract.js";
+import {
+  KIT_CONTRACT_VERSION,
+  KIT_STREAM_RECONNECT_MAX_MS,
+  KIT_STREAM_RECONNECT_MS,
+  KIT_STREAM_REJOIN_MS,
+} from "./contract.js";
 import { heldControl } from "./house.js";
 import { KitRefusal } from "./refusal.js";
 
 const PROTOCOL = "house.kit.stream.1";
-const WATCHED_SUBJECTS = ["agents", "working_copy", "sources"];
+const WORK_SUBJECTS = ["runs", "commands", "agents", "working_copy", "sources"];
+const FINAL_REFUSALS = ["kit_upgrade_required", "kit_stream_replaced"];
+const VIEW_FRAMES = ["draft", "plan"];
 
 function streamAddress(house) {
   const url = new URL("/kit/stream", house);
@@ -15,72 +22,95 @@ function streamAddress(house) {
   return url;
 }
 
-async function connected(session, signal, available, dependencies) {
+function frameOf(data) {
+  try {
+    return JSON.parse(data.toString());
+  } catch {
+    return null;
+  }
+}
+
+async function held(session, signal, heard, dependencies) {
   const authorization = await heldControl(session, signal);
   return new Promise((resolve, reject) => {
     const Socket = dependencies.workSocket ?? WebSocket;
     const socket = new Socket(streamAddress(session.house), PROTOCOL, {
       headers: { authorization, "x-house-kit-version": KIT_CONTRACT_VERSION },
       handshakeTimeout: 10_000,
-      maxPayload: 4096,
       perMessageDeflate: false,
     });
     let finished = false;
-    const finish = (error = null) => {
+    const finish = (reason = null, refusal = null) => {
       if (finished) return;
       finished = true;
       signal.removeEventListener("abort", stop);
-      if (error === null) resolve();
-      else reject(error);
+      heard.closed?.();
+      if (refusal === null) resolve(reason);
+      else reject(refusal);
     };
     const stop = () => {
       socket.terminate();
       finish();
     };
     signal.addEventListener("abort", stop, { once: true });
-    socket.on("open", () => available(null));
+    socket.on("open", () => {
+      if (finished) return;
+      heard.opened?.((frame) => socket.send(JSON.stringify(frame), () => undefined));
+      heard.available(null);
+    });
     socket.on("message", (data) => {
-      let frame;
-      try {
-        frame = JSON.parse(data.toString());
-      } catch {
-        return;
-      }
-      if (frame?.type === "work_available" && WATCHED_SUBJECTS.includes(frame.subject)) {
-        available(frame.subject);
+      const frame = frameOf(data);
+      if (frame?.type === "work_available" && WORK_SUBJECTS.includes(frame.subject)) {
+        heard.available(frame.subject);
+      } else if (frame?.type === "entries") {
+        heard.changed();
+      } else if (VIEW_FRAMES.includes(frame?.type)) {
+        heard.viewed?.(frame);
       }
     });
     socket.on("unexpected-response", (_request, response) => {
       response.resume();
       if (response.statusCode === 409) session.dependencies.contractRefused?.();
-      const refusal =
-        response.statusCode === 409 ? new KitRefusal("kit_upgrade_required") : null;
+      finish(null, response.statusCode === 409 ? new KitRefusal("kit_upgrade_required") : null);
       socket.terminate();
-      finish(refusal);
     });
     socket.on("error", () => {
       socket.terminate();
       finish();
     });
-    socket.on("close", () => finish());
+    socket.on("close", (_code, reason) => {
+      const closed = reason?.toString() ?? "";
+      finish(closed, closed === "replaced" ? new KitRefusal("kit_stream_replaced") : null);
+    });
     if (signal.aborted) stop();
   });
 }
 
-export async function watchKitWork(session, signal, available, dependencies = {}) {
-  let retryMs = 500;
+export async function watchKitWork(session, signal, heard, dependencies = {}) {
+  const random = dependencies.random ?? Math.random;
+  const sleep = dependencies.streamSleep ?? ((milliseconds) => delay(milliseconds, undefined, { signal }));
+  let failures = 0;
   while (!signal.aborted) {
     const began = Date.now();
+    let reason = null;
     try {
-      await connected(session, signal, available, dependencies);
+      reason = await held(session, signal, heard, dependencies);
     } catch (error) {
-      if (error instanceof KitRefusal && error.code === "kit_upgrade_required") throw error;
-      if (signal.aborted) return;
+      if (error instanceof KitRefusal && FINAL_REFUSALS.includes(error.code)) throw error;
     }
     if (signal.aborted) return;
-    retryMs = Date.now() - began >= 30_000 ? 1000 : Math.min(retryMs * 2, 30_000);
+    let wait;
+    if (reason === "authority_changed") {
+      failures = 0;
+      wait = random() * KIT_STREAM_REJOIN_MS;
+    } else {
+      if (Date.now() - began >= KIT_STREAM_RECONNECT_MAX_MS) failures = 0;
+      const ceiling = Math.min(KIT_STREAM_RECONNECT_MAX_MS, KIT_STREAM_RECONNECT_MS * 2 ** failures);
+      failures += 1;
+      wait = ceiling / 2 + (random() * ceiling) / 2;
+    }
     try {
-      await delay(dependencies.workReconnectMs ?? retryMs, undefined, { signal });
+      await sleep(wait);
     } catch (error) {
       if (!signal.aborted) throw error;
     }

package/src/launcher.js

@@ -155,11 +155,23 @@ async function runTurn(channel, start, bridge, turn) {
   );
   const said = [];
   const message = { text: "" };
-  const drafts = observedAssistantDrafts({ send: (text) => channel.send({ type: "draft", text }) });
+  const sequences = { draft: 0, plan: 0 };
+  const drafts = observedAssistantDrafts({
+    send: (text) => channel.send({ type: "draft", text, sequence: (sequences.draft += 1) }),
+  });
   const plans = observedPlans({
-    send: (snapshot) =>
-      channel.send({ type: "plan", provider_turn: turn.providerTurn, ...snapshot }),
+    send: (steps) =>
+      channel.send({
+        type: "plan",
+        provider_turn: turn.providerTurn,
+        sequence: (sequences.plan += 1),
+        steps,
+      }),
   });
+  turn.plan = () => {
+    const steps = plans.latest();
+    return steps === null ? null : { provider_turn: turn.providerTurn, steps };
+  };
   const wholeSoFar = () => [...said, message.text].filter((text) => text !== "").join("\n\n");
   let loading = false;
   const flush = () => {
@@ -167,7 +179,7 @@ async function runTurn(channel, start, bridge, turn) {
     channel.send({ type: "assistant", text: message.text });
     said.push(message.text);
     message.text = "";
-    drafts.complete(wholeSoFar());
+    drafts.observe(wholeSoFar());
   };
   const handlers = {
     onPermission: (params) => resolvedPermission(params, start.execution_authority),
@@ -218,16 +230,16 @@ async function runTurn(channel, start, bridge, turn) {
     });
     await new Promise((resolve) => setImmediate(resolve));
     flush();
-    plans.complete();
     channel.send({
       type: "turn_ended",
       stop_outcome: turnOutcome(contract, prompted?.stopReason),
       provider_continuation: contract.sessionLoad,
       provider_session_id: providerSessionId,
+      plan: turn.plan(),
     });
   } finally {
     turn.cancel = null;
-    plans.complete();
+    plans.close();
     abandonQuestions(channel, turn);
     drafts.close();
     stopCommandAdapter(adapter);
@@ -240,6 +252,7 @@ export async function launchWorkerSession(bridge) {
     providerTurn: randomUUID(),
     questions: new Map(),
     cancel: null,
+    plan: () => null,
   };
   const peer = bridgePeer({
     socket: bridge.socket,
@@ -267,6 +280,7 @@ export async function launchWorkerSession(bridge) {
               type: "interrupt_applied",
               interrupt: frame.interrupt,
               outcome: "interrupted",
+              plan: turn.plan(),
             }),
           () =>
             peer.send({
@@ -289,6 +303,7 @@ export async function launchWorkerSession(bridge) {
       type: "failed",
       code: refusal instanceof KitRefusal ? refusal.code : "kit_adapter_failed",
       detail: refusal instanceof Error ? refusal.message : null,
+      plan: turn.plan(),
     });
   }
   peer.send({ type: "exiting" });

package/src/pacing.js

@@ -0,0 +1,41 @@
+const PACING_INTERVAL_MS = 500;
+
+export function pacedLatest(options) {
+  const intervalMs = options.intervalMs ?? PACING_INTERVAL_MS;
+  const now = options.now ?? (() => Date.now());
+  let timer = null;
+  let sentAt = null;
+  let sent = null;
+  let latest = null;
+  let closed = false;
+
+  function write() {
+    timer = null;
+    const serialized = JSON.stringify(latest);
+    if (latest === null || serialized === sent) return;
+    sent = serialized;
+    sentAt = now();
+    options.send(latest);
+  }
+
+  return {
+    observe(value) {
+      latest = value;
+      if (closed || timer !== null) return;
+      const wait = sentAt === null ? 0 : sentAt + intervalMs - now();
+      if (wait <= 0) {
+        write();
+        return;
+      }
+      timer = setTimeout(write, wait);
+      timer.unref?.();
+    },
+    latest: () => latest,
+    close() {
+      closed = true;
+      if (timer === null) return;
+      clearTimeout(timer);
+      timer = null;
+    },
+  };
+}

package/src/plan.js

@@ -1,57 +1,49 @@
-const PLAN_INTERVAL_MS = 500;
+import { pacedLatest } from "./pacing.js";
 
-function steps(entries) {
-  if (!Array.isArray(entries) || entries.length === 0) return null;
-  return entries.map((entry) => ({ label: entry.content, status: entry.status }));
+function plannedStep(step) {
+  if (typeof step !== "object" || step === null || Array.isArray(step)) return null;
+  if (typeof step.label !== "string" || typeof step.status !== "string") return null;
+  return {
+    label: step.label,
+    ...(typeof step.priority === "string" ? { priority: step.priority } : {}),
+    status: step.status,
+  };
 }
 
-export function observedPlans(options) {
-  const intervalMs = options.intervalMs ?? PLAN_INTERVAL_MS;
-  const now = options.now ?? (() => Date.now());
-  let timer = null;
-  let sentAt = null;
-  let sent = null;
-  let latest = null;
-  let completed = false;
+export function planSnapshot(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
+  if (typeof value.provider_turn !== "string" || value.provider_turn === "") return null;
+  if (!Array.isArray(value.steps) || value.steps.length === 0) return null;
+  const steps = value.steps.map(plannedStep);
+  if (steps.includes(null)) return null;
+  return { provider_turn: value.provider_turn, steps };
+}
 
-  function write(terminal) {
-    if (latest === null) return;
-    const serialized = JSON.stringify(latest);
-    if (!terminal && serialized === sent) return;
-    sent = serialized;
-    sentAt = now();
-    options.send({ steps: latest, terminal });
-  }
+export function finalPlan(snapshot) {
+  if (snapshot === null || snapshot === undefined) return null;
+  return {
+    provider_turn: snapshot.provider_turn,
+    steps: snapshot.steps.map((step) => ({ label: step.label, status: step.status })),
+  };
+}
 
-  function cancel() {
-    if (timer === null) return;
-    clearTimeout(timer);
-    timer = null;
-  }
+function steps(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  return entries.map((entry) => ({
+    label: entry.content,
+    priority: entry.priority,
+    status: entry.status,
+  }));
+}
 
+export function observedPlans(options) {
+  const paced = pacedLatest(options);
   return {
     observe(entries) {
-      if (completed) return;
       const observed = steps(entries);
-      if (observed === null) return;
-      latest = observed;
-      if (timer !== null) return;
-      const wait = sentAt === null ? 0 : sentAt + intervalMs - now();
-      if (wait <= 0) {
-        write(false);
-        return;
-      }
-      timer = setTimeout(() => {
-        timer = null;
-        write(false);
-      }, wait);
-      timer.unref?.();
-    },
-    complete() {
-      if (completed) return;
-      completed = true;
-      cancel();
-      write(true);
+      if (observed !== null) paced.observe(observed);
     },
+    latest: paced.latest,
+    close: paced.close,
   };
 }

package/src/tasks.js

@@ -33,25 +33,28 @@ export function residentWake() {
       release?.();
     },
     async wait(milliseconds, signal) {
-      if (pending) {
-        pending = false;
-        return;
-      }
-      const pause = new AbortController();
-      try {
-        await Promise.race([
-          new Promise((resolve) => {
-            release = resolve;
-          }),
-          delay(milliseconds, undefined, { signal: AbortSignal.any([signal, pause.signal]) }),
-        ]);
-      } catch (error) {
-        if (!signal.aborted) throw error;
-      } finally {
-        release = null;
-        pending = false;
-        pause.abort();
+      if (!pending && !signal.aborted) {
+        const pause = new AbortController();
+        const paused = AbortSignal.any([signal, pause.signal]);
+        try {
+          await Promise.race([
+            new Promise((resolve) => {
+              release = resolve;
+            }),
+            Number.isFinite(milliseconds)
+              ? delay(milliseconds, undefined, { signal: paused })
+              : new Promise((resolve) => paused.addEventListener("abort", resolve, { once: true })),
+          ]);
+        } catch (error) {
+          if (!signal.aborted) throw error;
+        } finally {
+          release = null;
+          pause.abort();
+        }
       }
+      const woken = pending;
+      pending = false;
+      return woken;
     },
   };
 }