hilos-agent 0.10.1 → 0.11.2

package/src/run-inputs.mjs

@@ -0,0 +1,211 @@
+// 1182 — room directions for a daemon run.
+//
+// A person can add a direction to a running job from its live card. The
+// server holds it on the run and lists it back on this daemon's own progress
+// heartbeat as `pendingInputs` (1181); nothing is pushed, and nothing reaches
+// the coding CLI mid-turn (its stdin is closed by design). So the daemon:
+//
+//   1. harvests `pendingInputs` off every post_progress reply, deduplicated
+//      by `inputId` across beats, and answers `queued` once per new direction
+//      (the server keeps listing it until a real answer lands; `queued` is a
+//      courtesy, never a claim of delivery);
+//   2. after the coding turn ends, runs ONE more CLI turn with the pending
+//      directions as its prompt and answers `acknowledged` with that turn's
+//      command id — the only answer that counts as delivered;
+//   3. once the run is past the point of running turns, answers
+//      `unsupported` for anything that arrives late, so the room is told now
+//      rather than at run end.
+//
+// Every server call here is best-effort and never throws into the run: a
+// direction the daemon could not settle stays listed, and the server's
+// run-end rule drops it with the room's correction when the run stops.
+
+/** The largest batch of directions one heartbeat reply may carry. */
+const PENDING_INPUTS_MAX = 20;
+/** Shapes a post_progress reply into the pending list, or `[]`. */
+export function readPendingInputs(res) {
+  const list = res && Array.isArray(res.pendingInputs) ? res.pendingInputs : [];
+  const out = [];
+  for (const item of list) {
+    if (!item || typeof item !== "object") continue;
+    const inputId = typeof item.inputId === "string" ? item.inputId : null;
+    const body = typeof item.body === "string" ? item.body.trim() : "";
+    if (!inputId || !body) continue;
+    out.push({
+      inputId,
+      ordinal: Number.isSafeInteger(item.ordinal) ? item.ordinal : Number.MAX_SAFE_INTEGER,
+      body,
+    });
+    if (out.length >= PENDING_INPUTS_MAX) break;
+  }
+  return out;
+}
+
+/**
+ * The run's direction inbox.
+ *
+ * @param {{ tool: Function, runId: string, log?: (line: string) => void,
+ *   answerTimeoutMs?: number, closeDeadlineMs?: number, now?: () => number }} o
+ */
+export function createDirectionInbox({
+  tool,
+  runId,
+  log = () => {},
+  answerTimeoutMs = 5000,
+  closeDeadlineMs = 15000,
+  now = Date.now,
+}) {
+  /** @type {Map<string, {inputId: string, ordinal: number, body: string}>} */
+  const pending = new Map();
+  /** Every id ever listed to us, so a beat that lists it again changes nothing. */
+  const seen = new Set();
+  /**
+   * Receipts the server did not confirm (a blip on the one call that counts).
+   * The server keeps listing an unsettled direction on every beat, so the
+   * next beat that names one of these is the retry: the same command id, the
+   * same turn, never a second story.
+   * @type {Map<string, {ackId: string, turn?: number}>}
+   */
+  const unacked = new Map();
+  let closed = false;
+
+  // Bounded: `close()` runs on the ship's critical path, and a hung server
+  // must delay the push by at most this per answer, never hang it.
+  const answer = async (inputId, outcome, extra = {}) => {
+    let timer = null;
+    try {
+      const call = Promise.resolve(tool("acknowledge_run_input", { runId, inputId, outcome, ...extra }));
+      const late = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`no answer within ${answerTimeoutMs}ms`)), answerTimeoutMs);
+        if (typeof timer.unref === "function") timer.unref();
+      });
+      const r = await Promise.race([call, late]);
+      return r && typeof r === "object" ? r : null;
+    } catch (error) {
+      log(`  direction → ${outcome} for ${inputId} did not reach the server: ${error?.message ?? error}`);
+      return null;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  };
+  const acknowledgeOne = async (inputId, receipt) => {
+    const r = await answer(inputId, "acknowledged", {
+      ackId: receipt.ackId,
+      ...(Number.isSafeInteger(receipt.turn) ? { turn: receipt.turn } : {}),
+    });
+    if (r && r.ok === true) {
+      unacked.delete(inputId);
+      return true;
+    }
+    unacked.set(inputId, receipt);
+    return false;
+  };
+
+  return {
+    /** Fold one heartbeat reply's list in. New ids are answered once. */
+    absorb(list) {
+      for (const item of readPendingInputs({ pendingInputs: list })) {
+        if (unacked.has(item.inputId)) {
+          // Still listed because our receipt never landed: send it again.
+          void acknowledgeOne(item.inputId, unacked.get(item.inputId));
+          continue;
+        }
+        if (seen.has(item.inputId)) continue;
+        seen.add(item.inputId);
+        if (closed) {
+          log(`  direction → arrived after the last turn; telling the room it will not be applied`);
+          void answer(item.inputId, "unsupported", { reason: "no-turn-left" });
+          continue;
+        }
+        pending.set(item.inputId, item);
+        log(`  direction → held for the next turn (${pending.size} pending)`);
+        void answer(item.inputId, "queued");
+      }
+    },
+    /** Take everything pending, oldest first. The turn that follows owns them. */
+    take() {
+      const batch = [...pending.values()].sort((a, b) => a.ordinal - b.ordinal);
+      pending.clear();
+      return batch;
+    },
+    size() {
+      return pending.size;
+    },
+    /**
+     * The turn ran with these directions in its prompt: say so, with the
+     * exact command id and the turn it went into. Answered one by one so a
+     * lost reply settles the rest.
+     */
+    async acknowledge(batch, { ackId, turn }) {
+      let delivered = 0;
+      for (const item of batch) {
+        if (await acknowledgeOne(item.inputId, { ackId, turn })) delivered += 1;
+      }
+      return delivered;
+    },
+    /**
+     * No further turn will run. Whatever is still held could not be applied
+     * in this pass, and anything listed from now on cannot be either: both
+     * are answered `unsupported` with the reason `no-turn-left`, so the room
+     * hears the true reason now (this runner takes notes; this pass has no
+     * turn left) rather than when the run ends. A receipt still unconfirmed
+     * is tried once more.
+     */
+    async close() {
+      closed = true;
+      const held = [...pending.values()];
+      pending.clear();
+      // One overall deadline on top of the per-answer bound: the ship waits
+      // at most this long for the room to be told. Receipts go first (a lost
+      // one would otherwise become a false correction); what is not answered
+      // in time stays the server's to correct at the run's end.
+      const deadline = now() + closeDeadlineMs;
+      for (const [inputId, receipt] of [...unacked.entries()]) {
+        if (now() >= deadline) break;
+        await acknowledgeOne(inputId, receipt);
+      }
+      for (const item of held) {
+        if (now() >= deadline) {
+          log(`  direction → out of time telling the room about ${item.inputId}; the run's end will`);
+          continue;
+        }
+        log(`  direction → no turn left to apply it; telling the room it will not be applied`);
+        await answer(item.inputId, "unsupported", { reason: "no-turn-left" });
+      }
+      return held.length;
+    },
+    get closed() {
+      return closed;
+    },
+    /** Receipts the server has not confirmed yet (visible for tests and logs). */
+    unconfirmed() {
+      return [...unacked.keys()];
+    },
+  };
+}
+
+/**
+ * Did this `runAndStage` result come from a CLI that actually ran? A spawn
+ * failure (a misconfigured command, ENOENT) returns in milliseconds with an
+ * error code and nothing else; no runtime ever saw the prompt, so no receipt
+ * may be written for it. A turn that ran and then failed is still a delivery:
+ * the runtime took the command, and the report tells the outcome.
+ */
+export function directionTurnRan(applied) {
+  if (!applied || applied.aborted) return false;
+  return !(applied.empty && applied.failed && applied.errCode);
+}
+
+
+/** The prompt for the direction turn: the original task, then the directions. */
+export function directionTurnPrompt(codePrompt, batch) {
+  const lines = batch.map((item) => `- ${item.body}`).join("\n");
+  return (
+    `${codePrompt}\n\n` +
+    `While you were working, a person in the room added direction for this same task. ` +
+    `Continue from the current state of the working tree and apply it:\n${lines}`
+  );
+}
+
+/** How many direction turns one run may take before the rest waits for the next pass. */
+export const MAX_DIRECTION_TURNS = 3;