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

package/src/worker.js

@@ -15,13 +15,13 @@ import { bridgedFrame, openBridge } from "./bridge.js";
 import { transferBytes } from "./bytes.js";
 import { assistantBlocks } from "./blocks.js";
 import { retryConversationFiles } from "./conversation-originals.js";
-import { openAssistantDrafts } from "./draft.js";
 import { localRequest, reconcileInbound } from "./inbound.js";
 import { localFiles } from "./local-files.js";
 import { answerText, answerYaml, editRefusal } from "./mcp.js";
 import { inheritedEnvironment } from "./command.js";
 import { sourceEntries } from "./google/entries.js";
 import { watchKitWork } from "./kit-work-stream.js";
+import { finalPlan } from "./plan.js";
 import { coalescedTask, residentWake } from "./tasks.js";
 import {
   applyWorkingCopies,
@@ -40,10 +40,8 @@ import {
   MCP_REQUEST_BODY_MAX_BYTES,
   PROVIDER_CONTINUATION_UNAVAILABLE,
   WORKER_COMMAND_BATCH_MAX,
-  WORKER_COMMAND_POLL_MS,
   WORKER_EXIT_GRACE_MS,
   WORKER_EXIT_POLL_MS,
-  WORKER_HEARTBEAT_MS,
   WORKER_INHERITED_ENVIRONMENT,
   WORKER_SUPERVISION_POLL_MS,
   WORKING_COPY_INDEX_METHOD,
@@ -58,7 +56,6 @@ import {
   acquireOneRun,
   acquireOneResumption,
   admitInteraction,
-  admitPlanSnapshot,
   awaitSecretInput,
   rejectResumption,
   callHouseMcp,
@@ -76,12 +73,10 @@ import {
   reportInteractionOutcome,
   toolMutations,
   reportRunOutcome,
-  reportSessionHeartbeat,
   releaseControl,
   reportSessions,
   serveResident,
   sessionAuthority,
-  streamAssistantDraft,
   updateDrain,
 } from "./house.js";
 import { operationId } from "./operation.js";
@@ -90,6 +85,7 @@ import { readSettlements, removeSettlement, writeSettlement } from "./settlement
 import { howWeWorkOwed, noteHowWeWork, reconcileSkillSet } from "./skill-set.js";
 import { writeText } from "./state.js";
 import { failedReport, terminalReport } from "./terminal.js";
+import { kitStreamWriter, turnFrames } from "./turn-frames.js";
 import {
   createSession,
   destroySession,
@@ -101,10 +97,11 @@ import {
 
 const LAUNCHER_MAIN = fileURLToPath(new URL("launcher-main.js", import.meta.url));
 const RESIDENT_INTERVAL_MS = 30_000;
+const PASS_REACHES = ["commands", "runs"];
 
 async function dispatchSeal(context, bound) {
   try {
-    await acceptAssistantText(context.session, bound.session, bound.sealed);
+    await acceptAssistantText(context.session, bound.session, bound.sealed, bound.plan);
     bound.stopped.textAccepted = true;
   } catch (refusal) {
     if (!(refusal instanceof KitRefusal)) throw refusal;
@@ -134,9 +131,7 @@ async function pendingCommands(context, kinds = ["stop"]) {
   try {
     return await acquireCommands(context.session, WORKER_COMMAND_BATCH_MAX, kinds);
   } catch (refusal) {
-    if (houseFailed(refusal) || context.session.refused === true) {
-      return { stops: [], answers: [], interrupts: [] };
-    }
+    if (houseFailed(refusal) || context.session.refused === true) return null;
     throw refusal;
   }
 }
@@ -157,14 +152,6 @@ async function settleInterrupt(context, interrupt, outcome) {
   }
 }
 
-async function reportHeartbeat(context, bound) {
-  try {
-    await reportSessionHeartbeat(context.session, bound.session);
-  } catch (refusal) {
-    if (!(refusal instanceof KitRefusal)) throw refusal;
-  }
-}
-
 function retryFiles(context) {
   if (context.retrying !== undefined) return;
   context.retrying = retryConversationFiles(context)
@@ -187,40 +174,32 @@ async function settleFiles(context) {
 }
 
 async function supervise(context, bound, bridge) {
-  const terminal = bridge.departed;
-  let live = true;
-  terminal.then(() => {
-    live = false;
-  });
-  let commanded = Date.now() + WORKER_COMMAND_POLL_MS;
-  let pulsed = Date.now() + WORKER_HEARTBEAT_MS;
-  while (live) {
-    await Promise.race([terminal, delay(WORKER_SUPERVISION_POLL_MS)]);
-    if (!live) return null;
+  const departed = new AbortController();
+  bridge.departed.then(() => departed.abort());
+  const waiting = AbortSignal.any([context.signal, departed.signal]);
+  let owed = false;
+  for (;;) {
+    const commanded = (await context.commands.wait(WORKER_SUPERVISION_POLL_MS, waiting)) || owed;
+    if (departed.signal.aborted) return null;
+    if (context.signal.aborted) throw new KitRefusal("kit_command_cancelled");
     await context.update?.announce();
-    if (Date.now() >= commanded) {
-      commanded = Date.now() + WORKER_COMMAND_POLL_MS;
+    if (commanded) {
       const polled = await pendingCommands(context, ["stop", "interrupt", "answer"]);
-      for (const answer of polled.answers) {
+      owed = polled === null && context.session.refused !== true;
+      for (const answer of polled?.answers ?? []) {
         if (answer.session === bound.session) bridge.answered(answer);
       }
-      for (const interrupt of polled.interrupts) {
+      for (const interrupt of polled?.interrupts ?? []) {
         if (interrupt.session !== bound.session || interrupt.run !== bound.run) continue;
         if (!bridge.interrupt(interrupt)) {
           await settleInterrupt(context, interrupt.interrupt, "nothing_to_interrupt");
         }
       }
-      const stop = polled.stops.find((command) => command.run === bound.run);
+      const stop = polled?.stops.find((command) => command.run === bound.run);
       if (stop !== undefined) return stop;
     }
-    if (Date.now() >= pulsed) {
-      pulsed = Date.now() + WORKER_HEARTBEAT_MS;
-      retryFiles(context);
-      await reportHeartbeat(context, bound);
-    }
     if (!(await sessionPresent(context.runtime, bound.tmux))) return null;
   }
-  return null;
 }
 
 async function grantExitGrace(runtime, handle) {
@@ -237,7 +216,7 @@ async function completeOwnerStop(context, bound, requestedAt) {
   const destroyed = await destroySession(context.runtime, bound.tmux);
   let failure = null;
   try {
-    await observeSessionStop(context.session, bound.session);
+    await observeSessionStop(context.session, bound.session, false, bound.plan);
   } catch (refusal) {
     if (undecided(context, refusal)) return { destroyed, confirmed: false, failure: null };
     if (!(refusal instanceof KitRefusal)) throw refusal;
@@ -250,7 +229,7 @@ async function completeOwnerStop(context, bound, requestedAt) {
 
 async function settleReported(context, bound) {
   try {
-    await reportRunOutcome(context.session, bound.run, bound.reported);
+    await reportRunOutcome(context.session, bound.run, bound.reported, bound.plan);
     return { settled: true, failure: null };
   } catch (refusal) {
     if (undecided(context, refusal)) return { settled: false, failure: null };
@@ -379,25 +358,23 @@ async function sessionPush(context, bound, authority, frame, signal) {
 async function openRunBridge(context, bound, authority, start) {
   const ended = new AbortController();
   const handed = (act) => endOnEpochReport(ended, act);
-  const drafts = openAssistantDrafts({
-    send: handed((blocks) => streamAssistantDraft(context.session, bound.session, blocks)),
-  });
+  const frames = turnFrames(context.stream);
   const bridge = await openBridge({
     socket: bound.socket,
     nonce: bound.nonce,
     signal: AbortSignal.any([context.signal, ended.signal]),
     mutates: mutatingCall(await toolMutations(context.session, context.signal)),
     alive: () => sessionPresent(context.runtime, bound.tmux),
-    draft: (text) => drafts.update(text),
+    draft: (view) => frames.draft(view),
+    plan: (snapshot) => frames.plan(snapshot),
     start,
     question: handed((batch) => admitInteraction(context.session, bound.session, batch)),
-    plan: handed((snapshot) => admitPlanSnapshot(context.session, bound.session, snapshot)),
     howWeWork: () =>
       noteHowWeWork(context.directory).catch((error) =>
         reported(`How-we-work note unwritable (${error.code ?? "unknown"})`),
       ),
-    interrupt: handed((interrupt, outcome) =>
-      reportInterruptOutcome(context.session, interrupt, outcome),
+    interrupt: handed((interrupt, outcome, plan) =>
+      reportInterruptOutcome(context.session, interrupt, outcome, finalPlan(plan)),
     ),
     secret: (interaction, ceremony) => awaitSecretInput(context.session, interaction, ceremony),
     settle: handed((interaction, outcome) => settleInteraction(context, interaction, outcome)),
@@ -413,11 +390,11 @@ async function openRunBridge(context, bound, authority, start) {
           signal,
         ), context.session.dependencies, signal)(frame)),
   });
-  return { bridge, drafts, ended };
+  return { bridge, frames, ended };
 }
 
 async function superviseBound(context, bound, opened, start) {
-  const { bridge, drafts, ended } = opened;
+  const { bridge, ended } = opened;
   const spawn = { committed: false };
   let unsupervised = null;
   let destroyed = false;
@@ -431,23 +408,20 @@ async function superviseBound(context, bound, opened, start) {
     unsupervised = { code: refusal.code, detail: refusal.message };
   } finally {
     try {
-      try {
-        await settleFiles(context);
-        for (const interaction of bridge.unsettledInteractions()) {
-          await settleInteraction(context, interaction, "expired");
-        }
-      } finally {
-        bridge.stopRecovery();
-        if (owner === null) {
-          try {
-            destroyed = await grantExitGrace(context.runtime, bound.tmux);
-          } finally {
-            await bridge.close();
-          }
-        }
+      retryFiles(context);
+      await settleFiles(context);
+      for (const interaction of bridge.unsettledInteractions()) {
+        await settleInteraction(context, interaction, "expired");
       }
     } finally {
-      drafts.close();
+      bridge.stopRecovery();
+      if (owner === null) {
+        try {
+          destroyed = await grantExitGrace(context.runtime, bound.tmux);
+        } finally {
+          await bridge.close();
+        }
+      }
     }
   }
   ended.signal.throwIfAborted();
@@ -463,6 +437,7 @@ async function superviseBound(context, bound, opened, start) {
     destroyed,
     stopped: null,
   };
+  bound.plan = finalPlan(bridge.plan());
   if (owner !== null) {
     const finished = await completeOwnerStop(context, bound, owner.requestedAt);
     return {
@@ -514,12 +489,12 @@ async function settleStopped(context, bound) {
   }
   let failure = stopped.failure;
   try {
-    await observeSessionStop(context.session, bound.session, stopped.textAccepted);
+    await observeSessionStop(context.session, bound.session, stopped.textAccepted, bound.plan);
   } catch (refusal) {
     if (undecided(context, refusal)) return unresolved(null);
     if (!(refusal instanceof KitRefusal) || refusal.code !== "conversation_final_text_pending") throw refusal;
     failure ??= { code: refusal.code, detail: refusal.message };
-    await observeSessionStop(context.session, bound.session);
+    await observeSessionStop(context.session, bound.session, false, bound.plan);
   }
   const report = stoppedReport(bound);
   if (report !== null) await removeContinuation(context.directory, bound.run);
@@ -579,6 +554,7 @@ async function prepareAssignment(context, assignment, resumed) {
     ownerStop: null,
     sealed: null,
     reported: null,
+    plan: null,
   };
   const authority = { token: assignment.session.token, expiresAt: assignment.session.expiresAt };
   const start = {
@@ -661,7 +637,7 @@ async function superviseAssignment(context, assignment, resumed = false) {
       },
       command: context.launcher,
     });
-    await observeSessionStart(context.session, bound.session);
+    opened.frames.identify(await observeSessionStart(context.session, bound.session));
   });
 }
 
@@ -680,7 +656,7 @@ async function superviseRestored(context, binding, authority) {
   const opened = await openRunBridge(context, binding, authority);
   return superviseBound(context, binding, opened, async (spawn) => {
     spawn.committed = true;
-    await observeSessionStart(context.session, binding.session);
+    opened.frames.identify(await observeSessionStart(context.session, binding.session));
   });
 }
 
@@ -727,7 +703,7 @@ async function reconcile(context) {
   }
   const bindings = await readBindings(context.directory);
   if (bindings.length === 0) return { run: null, stopped, unresolved };
-  const commands = (await pendingCommands(context)).stops;
+  const commands = (await pendingCommands(context))?.stops ?? [];
   const carried = [];
   for (const binding of bindings) {
     if (binding.reported !== null) {
@@ -811,7 +787,7 @@ function unlessDraining(context, act) {
   return context.update?.requested ? null : act();
 }
 
-async function workerPass(context, dependencies, baseConfiguration) {
+async function workerPass(context, dependencies, baseConfiguration, reach) {
   const { session, signal } = context;
   const reconciled = await reconcile(context);
   if (reconciled.run !== null || reconciled.unresolved.length > 0 || context.update?.requested) {
@@ -842,6 +818,7 @@ async function workerPass(context, dependencies, baseConfiguration) {
   }
   const resumption = await unlessDraining(context, () => acquireOneResumption(session));
   if (resumption !== null) return { ...reconciled, run: await superviseResumption(context, resumption) };
+  if (reach !== "runs") return reconciled;
   const assignment = await unlessDraining(context, () => acquireOneRun(session));
   if (assignment === null) return reconciled;
   return { ...reconciled, run: await superviseAssignment(context, assignment) };
@@ -865,6 +842,8 @@ async function workerContext(options, dependencies, resident = false) {
     directory: options.directory,
     home: dependencies.home ?? homedir(),
     files: { originals: [], failures: [] },
+    commands: residentWake(),
+    stream: kitStreamWriter(),
     epochReport: null,
     agentRefresh: Promise.resolve(),
     configurationPath: options.configuration,
@@ -909,7 +888,7 @@ function queueAgentRefresh(context, dependencies, signal, configuration, pointer
   return refreshed;
 }
 
-async function controlledPass(context, dependencies, configuration, signal) {
+async function controlledPass(context, dependencies, configuration, signal, reach = "runs") {
   context.signal = signal;
   context.session.signal = signal;
   await reconcileSkillSet({
@@ -919,7 +898,7 @@ async function controlledPass(context, dependencies, configuration, signal) {
   });
   context.busy = true;
   try {
-    return await afterEpochReport(context, () => workerPass(context, dependencies, configuration));
+    return await afterEpochReport(context, () => workerPass(context, dependencies, configuration, reach));
   } finally {
     context.busy = false;
     if (context.deferredRemoval) context.onIdle?.();
@@ -930,8 +909,28 @@ export async function runWorkers(options, dependencies = {}) {
   const { context, tmux } = await workerContext(options, dependencies);
   const { session, runtime } = context;
   const supervised = await maintainControl(session, async (signal) => {
-    await reportedWorkingCopies(applyWorkingCopies, context, signal);
-    return controlledPass(context, dependencies, context.configuration, signal);
+    const watcher = new AbortController();
+    const commanded = (subject) => {
+      if (subject === null || subject === "commands") context.commands.notify();
+    };
+    const watching = (dependencies.watchKitWork ?? watchKitWork)(
+      session,
+      AbortSignal.any([signal, watcher.signal]),
+      {
+        available: commanded,
+        changed: () => {},
+        opened: context.stream.opened,
+        closed: context.stream.closed,
+      },
+      dependencies,
+    ).catch((error) => reported(`control stream ended: ${error?.code ?? error?.message ?? error}`));
+    try {
+      await reportedWorkingCopies(applyWorkingCopies, context, signal);
+      return await controlledPass(context, dependencies, context.configuration, signal);
+    } finally {
+      watcher.abort();
+      await watching;
+    }
   }, session.signal);
   return {
     tmux,
@@ -952,9 +951,11 @@ function reported(line) {
 }
 
 async function reportedWorkingCopies(act, context, signal) {
-  for (const refused of (await act(context, signal)).refused) {
+  const outcome = await act(context, signal);
+  for (const refused of outcome.refused) {
     reported(`working copy ${refused.path} refused: ${refused.code}`);
   }
+  return outcome;
 }
 
 function residentUpdate(context, wake) {
@@ -1036,6 +1037,7 @@ export async function runResident(options, dependencies = {}) {
       ),
     (source) =>
       sources === null ? Promise.reject(new KitRefusal("kit_resident_unavailable")) : sources.capture(source),
+    context.stream,
   );
   const serve = async (signal) => {
     context.busy = true;
@@ -1092,11 +1094,18 @@ export async function runResident(options, dependencies = {}) {
       context.startLogins(needsLogin);
     });
     const unavailable = (error) => reported(`working copies unavailable: ${error?.message ?? error}`);
-    const copies = coalescedTask(signal, unavailable, () =>
-      reportedWorkingCopies(applyWorkingCopies, context, signal),
+    const changed = () => {
+      if (!update.requested) deliveries.trigger();
+    };
+    const behind = (outcome) => {
+      if (!outcome.behind) return;
+      controlSleep(interval, signal).then(changed, () => {});
+    };
+    const copies = coalescedTask(signal, unavailable, async () =>
+      behind(await reportedWorkingCopies(applyWorkingCopies, context, signal)),
     );
-    const deliveries = coalescedTask(signal, unavailable, () =>
-      reportedWorkingCopies(deliverWorkingCopies, context, signal),
+    const deliveries = coalescedTask(signal, unavailable, async () =>
+      behind(await reportedWorkingCopies(deliverWorkingCopies, context, signal)),
     );
     sources = sourceEntries({
       session: context.session,
@@ -1111,7 +1120,38 @@ export async function runResident(options, dependencies = {}) {
     const pointer = () => {
       if (!update.requested) agentRefresh.trigger();
     };
-    const available = (subject = null) => {
+    let passOwed = null;
+    let deferred = null;
+    let retrying = null;
+    const higher = (reach, than) =>
+      PASS_REACHES.indexOf(reach) > PASS_REACHES.indexOf(than) ? reach : than;
+    const owe = (reach) => {
+      passOwed = higher(reach, passOwed);
+      wake.notify();
+    };
+    const defer = (reach) => {
+      deferred = higher(reach, deferred);
+      if (retrying !== null) return;
+      retrying = new AbortController();
+      controlSleep(interval, AbortSignal.any([signal, retrying.signal])).then(() => {
+        retrying = null;
+        const owed = deferred;
+        deferred = null;
+        owe(owed);
+      }, () => {});
+    };
+    const settle = (reach) => {
+      retrying?.abort();
+      retrying = null;
+      if (higher(deferred, reach) !== reach) owe(deferred);
+      deferred = null;
+    };
+    const available = (subject) => {
+      if (subject === null || subject === "runs") owe("runs");
+      if (subject === null || subject === "commands") {
+        context.commands.notify();
+        owe("commands");
+      }
       if (update.requested) return;
       if (subject === null || subject === "agents") agentRefresh.trigger();
       if (subject === null || subject === "working_copy") copies.trigger();
@@ -1119,23 +1159,37 @@ export async function runResident(options, dependencies = {}) {
     };
     context.onIdle = pointer;
     context.workingCopiesApplied = copies.settled;
-    if (!update.requested) copies.trigger();
     const watching = (dependencies.watchKitWork ?? watchKitWork)(
       context.session,
       AbortSignal.any([signal, watcher.signal]),
-      available,
+      {
+        available,
+        changed,
+        opened: context.stream.opened,
+        closed: context.stream.closed,
+        viewed: (frame) => served.forward(frame),
+      },
       dependencies,
     ).catch(fail);
     try {
       while (!signal.aborted) {
         if (failure !== null) throw failure;
-        if (!session.refused) {
+        if (passOwed !== null && !session.refused) {
+          const reach = passOwed;
+          passOwed = null;
           const configuration = await readConfiguration(options.configuration);
-          await controlledPass(context, dependencies, configuration, signal).catch((error) => {
-            if (!session.refused) throw error;
-          });
+          const passed = await controlledPass(context, dependencies, configuration, signal, reach).catch(
+            (error) => {
+              if (!session.refused) throw error;
+              return null;
+            },
+          );
+          if ((passed?.run ?? null) !== null) owe(reach);
+          if ((passed?.unresolved.length ?? 0) > 0) defer(reach);
+          else if (passed !== null) settle(reach);
         }
-        if (session.refused || update.requested) {
+        const draining = session.refused || update.requested;
+        if (draining) {
           const sessions = await heldSessions(context);
           if (sessions.length > 0) update.answer({ ready: false, sessions });
           else if (
@@ -1150,8 +1204,7 @@ export async function runResident(options, dependencies = {}) {
             return;
           }
         }
-        await wake.wait(interval, signal);
-        if (!update.requested && !session.refused) deliveries.trigger();
+        if (session.refused || passOwed === null) await wake.wait(draining ? interval : Infinity, signal);
       }
     } finally {
       watcher.abort();
@@ -1185,7 +1238,7 @@ export async function runResident(options, dependencies = {}) {
       await wake.wait(interval, options.signal);
     }
     update.quiesce();
-    while (!options.signal.aborted) await wake.wait(interval, options.signal);
+    while (!options.signal.aborted) await wake.wait(Infinity, options.signal);
     throw new KitRefusal("kit_command_cancelled");
   } finally {
     await served.close();

package/src/working-copy.js

@@ -497,7 +497,7 @@ async function deliver(context, path, authority, signal) {
   let copy = await readCopy(path);
   if (copy?.active && JSON.stringify(copy.received.declared) !== JSON.stringify(declaration(authority))) {
     await writeCopy(context.directory, await receive(context, copy, scopeOf(copy), signal), signal);
-    return;
+    return false;
   }
   while (
     copy?.active &&
@@ -508,24 +508,26 @@ async function deliver(context, path, authority, signal) {
     try {
       view = await enumerated(context, copy, since, signal);
     } catch (error) {
-      if (error.code === "replica_behind") return;
+      if (error.code === "replica_behind") return true;
       if (error.code !== "position_expired") throw error;
       await writeCopy(context.directory, await receive(context, copy, scopeOf(copy), signal), signal);
-      return;
+      return false;
     }
-    if (view.position === since.position) return;
+    if (view.position === since.position) return false;
     copy = await incorporated(copy, view, authority, signal);
     await writeCopy(context.directory, copy, signal);
   }
+  return false;
 }
 
 async function delivering(context, signal) {
   const copies = (await heldCopies(context.directory)).filter((copy) => copy.active);
-  if (copies.length === 0) return { refused: [], lost: false };
+  if (copies.length === 0) return { refused: [], lost: false, behind: false };
   const prefixes = copies.flatMap((copy) => selectedPrefixes(scopeOf(copy)));
   const discovery = discoveryOf(await door(context.session, KIT_DOOR_DISCOVER_PATH, { prefixes }, signal));
   const refused = [];
   let lost = false;
+  let behind = false;
   for (const copy of copies) {
     const at = housePath(scopeOf(copy));
     const authority = discovery.authorities.find((entry) => entry?.room_ref === copy.room_ref);
@@ -539,18 +541,24 @@ async function delivering(context, signal) {
     }
     const path = copyPath(context.directory, copy);
     try {
-      await exclusively(path, () => deliver(context, path, authority, signal));
+      if (await exclusively(path, () => deliver(context, path, authority, signal))) behind = true;
     } catch (error) {
       if (!scopeRefused(error)) throw error;
       refused.push({ path: at, code: error.code });
     }
   }
-  return { refused, lost };
+  return { refused, lost, behind };
+}
+
+function deliveredOutcome(refused, behind) {
+  return behind ? { refused, behind } : { refused };
 }
 
 export async function deliverWorkingCopies(context, signal) {
   const delivered = await delivering(context, signal);
-  return delivered.lost ? applyWorkingCopies(context, signal) : { refused: delivered.refused };
+  return delivered.lost
+    ? applyWorkingCopies(context, signal)
+    : deliveredOutcome(delivered.refused, delivered.behind);
 }
 
 export async function applyWorkingCopies(context, signal) {
@@ -582,7 +590,8 @@ export async function applyWorkingCopies(context, signal) {
       refused.push({ path: housePath(scope), code: error.code });
     }
   }
-  return { refused: [...refused, ...(await delivering(context, signal)).refused] };
+  const delivered = await delivering(context, signal);
+  return deliveredOutcome([...refused, ...delivered.refused], delivered.behind);
 }
 
 export async function workingCopyPaths(directory) {