// delivery.js - sending, the queue and the turn gate. // // Plain ES module: no gpui-kit, no gpui-base, no herdr. The `hc` runner is // injected (ctx.hc), so the whole delivery layer runs in plain Node // (tests/delivery.test.mjs) without the app. // // The state model is the only writer: drain takes the state, moves the entry // through `reduce` and hands a new state back. Nothing here changes a queue // on its own. // // FACT (measured 2026-11-17 on herdr-core 0.1.16, `hc send --json`): // `hc send` returns {"started":null,"status":null,"turn":0} and exits 0 - also // for a plain shell with no agent, and also when it fails. Neither the exit // code nor those fields say whether the agent got the message. Therefore: // - ok:true means "the text was pasted and Enter pressed", NOT "the agent // received it" - the UI says "Wysłano do terminala"; // - the only failure is a non-zero exit code (its stderr becomes the notice); // - every `--json` call checks the payload for an "error" field, because `hc` // exits 0 even on error (measured: `hc wait t3 --json` for a missing // terminal -> {"error":{"kind":"not_found",...}}, exit 0); // - a payload that is not JSON at all is an unknown result, not a success; // - delivery confirmation comes from the agent's status (agents() / // `hc get --json`), never from the result of `hc send`; // - exit codes are not mapped to meanings (9/11 - unproven, against the // measurement); // - the runner's `ok` flag carries no information the exit code does not // already carry, so only the code and the payload are looked at. import { reduce } from "./state.js"; /** * @typedef {"idle"|"working"|"blocked"|"done"} Status * * @typedef {object} HcResult * @property {boolean} [ok] * @property {number} code * @property {string} stdout * @property {string} stderr * * @typedef {object} Ctx * @property {string} terminal * @property {(args:string[]) => Promise} hc * * @typedef {object} DrainCtx * @property {string} agent - whose queue this is; the queue is `state.queue[agent]` * @property {string} terminal * @property {(args:string[]) => Promise} hc * @property {() => Status} status * @property {() => boolean} gate * @property {(state:object) => void} [onState] - the caller persists the state * here; it is called after every transition, the first time while the entry * is on the wire (before the send runs), so a crash during the send leaves * "sending" on disk and not "queued" * * @typedef {{ok:true} | {ok:false, code:number, message:string}} Result * @typedef {{kind:"send"|"queue"|"hold"}} Decision * @typedef {{state:object, sent:boolean, id?:string, reason?:string}} DrainResult * * @typedef {object} QueueItem * @property {string} id * @property {string} text * @property {"queued"|"countdown"|"sending"|"held"|"uncertain"} state * @property {number} createdAt * @property {number} [left] - seconds to the send, while the state is "countdown" * @property {string} [reason] */ /** * What to do with a message, given the agent's status. * * @param {Status|string} status * @returns {Decision} */ export function decide(status) { switch (status) { case "idle": case "done": return { kind: "send" }; case "working": return { kind: "queue" }; case "blocked": // The agent waits for an answer: what the person writes IS the answer, // so it goes out at once. (The queue does not start on its own while // the agent is blocked - see `shouldDrain`.) return { kind: "send" }; default: // A status we do not know (the core also reports "error") - wait for a // known one instead of pasting into an agent that may not be there. return { kind: "queue" }; } } /** * Does a change of the agent's status start the queue (the countdown)? * * Only the end of a turn does: the agent was working (or waiting for the * person) and is idle or done now. A turn that the composer stopped itself * (the Stop button, Esc) never starts anything. * * @param {Status|string} prev * @param {Status|string} next * @param {boolean} stoppedByComposer * @returns {boolean} */ export function shouldDrain(prev, next, stoppedByComposer) { if (stoppedByComposer) return false; const was = prev === "working" || prev === "blocked"; const is = next === "idle" || next === "done"; return was && is; } /** * The turn gate: the next message goes out only after a whole turn was seen - * the agent was working and then came back to idle/done. Without that * transition a message could land in the middle of the agent's turn. * * @param {Status|string} status * @param {boolean} seenWorking * @returns {boolean} */ export function gateAfter(status, seenWorking) { if (!seenWorking) return false; return status === "idle" || status === "done"; } /** * Paste the text into the terminal and press Enter. * * `ok:true` means the text was pasted - not that the agent read it. The only * failure is a non-zero exit code, an "error" in the `--json` payload, or a * payload that is not JSON at all. * * @param {Ctx} ctx * @param {string} text * @returns {Promise} */ export async function sendNow(ctx, text) { const res = await callHc(ctx, ["send", ctx.terminal, text, "--json"]); if (res.failure) { // The runner itself failed - there is no exit code to report. return { ok: false, code: 0, message: res.failure }; } if (res.code !== 0) { return { ok: false, code: res.code, message: res.stderr.trim() || `hc send zakończone kodem ${res.code}`, }; } const payload = parseJson(res.stdout); if (!isPayload(payload)) { // An unknown result is not a success: the text may or may not have gone // out, so the caller must not treat this as delivered. return { ok: false, code: res.code, message: "Nieznany wynik hc send" }; } const failure = errorFrom(payload); if (failure) return { ok: false, code: res.code, message: failure }; return { ok: true }; } /** * Send the first queued entry of the agent's queue, if the agent is ready and * the gate is open. The queue is `state.queue[ctx.agent]` - the queues are per * agent, and the status and the gate belong to that one agent. * * The state model is the only writer: the entry is claimed (`sending`) before * we wait for `hc`, so it is on the wire while the send runs. On success the * entry leaves the queue; on a failure it becomes `uncertain` - never * `queued`, because `hc` exits 0 even on error and the text may have gone * out. Nothing is repeated on its own. * * Every transition is handed to `ctx.onState` (the caller persists it) before * the next step - the first time while the entry is on the wire, so a crash * during the send leaves `sending` on disk and the restart turns it into * `uncertain` instead of sending the message a second time. * * The gate is the caller's (ctx.gate()); the caller also resets it (sawWorking * = false) after a successful send. * * @param {DrainCtx} ctx * @param {object} state - the composer's state * @returns {Promise} */ export async function drain(ctx, state) { const agent = ctx.agent; const items = state.queue?.[agent] ?? []; const item = items.find(sendable); if (!item) return { state, sent: false }; if (!ready(ctx.status())) return { state, sent: false }; if (!ctx.gate()) return { state, sent: false }; // On the wire before we wait for `hc`: a restart in the middle must find the // entry as `sending` and turn it into `uncertain`. const claimed = reduce(state, { type: "claim", agent, id: item.id }); ctx.onState?.(claimed); const result = await sendNow(ctx, item.text); if (result.ok) { const sent = reduce(claimed, { type: "settle", agent, id: item.id, outcome: "sent" }); ctx.onState?.(sent); return { state: sent, sent: true, id: item.id }; } const failed = reduce(claimed, { type: "settle", agent, id: item.id, outcome: "uncertain", reason: result.message, }); ctx.onState?.(failed); return { state: failed, sent: false, reason: result.message }; } /** * After a restart an entry that was on the wire is `uncertain`: the message * may or may not have reached the agent, so it is never sent again on its own. * * @param {QueueItem[]} queue * @returns {QueueItem[]} */ export function onRestart(queue) { if (!Array.isArray(queue)) return []; return queue.map((item) => { if (item.state === "sending") return { ...item, state: "uncertain" }; if (item.state === "countdown") { // Nothing goes out on its own after a restart. const { left, ...rest } = item; return { ...rest, state: "held" }; } return item; }); } /** The agent can take the next message when it is not working and not blocked. */ function ready(status) { // "done" counts as ready: the core reports "done" for a turn that finished // unseen, and it turns into "idle" only once somebody looks at it // (herdr-app src/model.rs:596-604). A queue that waited for "idle" would // never drain for an agent nobody watches. return status === "idle" || status === "done"; } /** Only an entry that waits in the queue, or whose countdown ran out, may go out. */ function sendable(item) { if (item?.state === "queued") return true; return item?.state === "countdown" && !(item.left > 0); } /** Run `hc` and normalize what comes back. */ async function callHc(ctx, args) { try { const res = await ctx.hc(args); return { code: Number.isFinite(res?.code) ? res.code : 0, stdout: typeof res?.stdout === "string" ? res.stdout : "", stderr: typeof res?.stderr === "string" ? res.stderr : "", failure: null, }; } catch (err) { return { code: 0, stdout: "", stderr: "", failure: err?.message ?? String(err), }; } } /** The "error" of a `--json` payload, if it carries one. */ function errorFrom(payload) { if (!payload.error) return null; const err = payload.error; if (typeof err === "string") return err; if (typeof err.message === "string" && err.message) return err.message; if (typeof err.kind === "string" && err.kind) return err.kind; return JSON.stringify(err); } /** A `--json` payload is an object - anything else is an unknown result. */ function isPayload(value) { return typeof value === "object" && value !== null && !Array.isArray(value); } function parseJson(text) { if (typeof text !== "string" || text.trim() === "") return null; try { return JSON.parse(text); } catch { return null; } }