@agentshouse/kit 0.1.0-alpha.28 → 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,
   );
@@ -1286,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

@@ -12,6 +12,7 @@ import { KitRefusal } from "./refusal.js";
 const PROTOCOL = "house.kit.stream.1";
 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);
@@ -43,6 +44,7 @@ async function held(session, signal, heard, dependencies) {
       if (finished) return;
       finished = true;
       signal.removeEventListener("abort", stop);
+      heard.closed?.();
       if (refusal === null) resolve(reason);
       else reject(refusal);
     };
@@ -51,13 +53,19 @@ async function held(session, signal, heard, dependencies) {
       finish();
     };
     signal.addEventListener("abort", stop, { once: true });
-    socket.on("open", () => heard.available(null));
+    socket.on("open", () => {
+      if (finished) return;
+      heard.opened?.((frame) => socket.send(JSON.stringify(frame), () => undefined));
+      heard.available(null);
+    });
     socket.on("message", (data) => {
       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) => {

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,
   };
 }