@agentshouse/kit 0.1.0-alpha.4 → 0.1.0-alpha.41

package/src/how-we-work.md

@@ -0,0 +1,25 @@
+# How we work
+
+A Room is where information people share is kept; it is not the place for
+private information. Work goes into the Room it belongs to, or the First Room
+when none is named. Read and write Rooms with the `house` CLI.
+
+The skills are already set up; never run `setup-matt-pocock-skills`.
+
+## Where skill output goes
+
+- Glossary (`CONTEXT.md`): `library/glossary.md`
+- Decisions (ADRs): `library/decisions/NNNN-<slug>.md`
+- Plan (spec): `library/projects/<name>/plan.md`
+- Tasks (tickets): `library/projects/<name>/tasks/NN-<slug>.md`, with a
+  `Status:` line (`needs-triage`, `needs-info`, `ready-for-agent`,
+  `ready-for-human`, `wontfix`), a `Blocked by:` line and comments under
+  `## Comments`
+- Map (Wayfinding): `library/projects/<name>/map.md`, its tasks under
+  `tasks/` with `Type:`, `Status: claimed|resolved` and `Blocked by:` lines
+- Research: `library/research/<slug>.md`
+- Questionnaires: `library/questionnaires/<slug>.md`
+- Learning: `library/learning/<topic>/`
+- Files a person should open, such as HTML pages, are uploaded to the Room and
+  linked from the document they belong to; a prototype is one HTML file with
+  every variant on one page.

package/src/inbound.js

@@ -134,13 +134,9 @@ export async function reconcileInbound(directory, session) {
 }
 
 export async function localRequest(directory, run, request) {
-  const turn = request?.conversation?.turn ?? (request?.kind === "conversation" ? request.turn : null);
-  if (turn === null || turn === undefined) return request;
+  if (request.kind !== "conversation") return request;
   const result = structuredClone(request);
-  const localTurn = result.conversation?.turn ?? result.turn;
-  if (!Array.isArray(localTurn.messages)) throw new KitRefusal("kit_run_input_unreadable");
-  for (const message of localTurn.messages) {
-    if (!Array.isArray(message.files)) throw new KitRefusal("kit_run_input_unreadable");
+  for (const message of result.turn.messages) {
     for (const file of message.files) {
       const parts = typeof file.path === "string" ? file.path.split("/") : [];
       if (parts.length !== 4 || parts[0] !== ROOT || parts[1] !== run || !UUID.test(parts[1]) || !UUID.test(parts[2]) || !segment(parts[3])) {
@@ -161,15 +157,3 @@ export async function localRequest(directory, run, request) {
   }
   return result;
 }
-
-export async function localReply(directory, run, frame, reply) {
-  if (frame.method !== "tools/call" || frame.params?.name !== "session_get_request" || reply.error || reply.result?.isError) return reply;
-  const result = structuredClone(reply);
-  for (const item of result.result?.content ?? []) {
-    if (item.type !== "text") continue;
-    let input;
-    try { input = JSON.parse(item.text); } catch { throw new KitRefusal("kit_run_input_unreadable"); }
-    item.text = JSON.stringify(await localRequest(directory, run, input));
-  }
-  return result;
-}

package/src/kit-work-stream.js

@@ -0,0 +1,120 @@
+import { setTimeout as delay } from "node:timers/promises";
+import WebSocket from "ws";
+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 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);
+  if (url.protocol === "https:") url.protocol = "wss:";
+  else if (url.protocol === "http:") url.protocol = "ws:";
+  else throw new KitRefusal("kit_house_unavailable", "/kit/stream");
+  return url;
+}
+
+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,
+      perMessageDeflate: false,
+    });
+    let finished = false;
+    const carried = new Map();
+    const finish = (reason = null, refusal = null) => {
+      if (finished) return;
+      finished = true;
+      signal.removeEventListener("abort", stop);
+      heard.closed?.();
+      if (refusal === null) resolve(reason);
+      else reject(refusal);
+    };
+    const stop = () => {
+      socket.terminate();
+      finish();
+    };
+    signal.addEventListener("abort", stop, { once: true });
+    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(frame, carried.get(frame.authority) ?? null);
+        carried.set(frame.authority, frame.position);
+      } 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?.();
+      finish(null, response.statusCode === 409 ? new KitRefusal("kit_upgrade_required") : null);
+      socket.terminate();
+    });
+    socket.on("error", () => {
+      socket.terminate();
+      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, 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 {
+      reason = await held(session, signal, heard, dependencies);
+    } catch (error) {
+      if (error instanceof KitRefusal && FINAL_REFUSALS.includes(error.code)) throw error;
+    }
+    if (signal.aborted) return;
+    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 sleep(wait);
+    } catch (error) {
+      if (!signal.aborted) throw error;
+    }
+  }
+}

package/src/launcher.js

@@ -1,5 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { commandHouseInstructions, commandHouseRequest } from "./adapter-mcp.js";
+import {
+  commandHouseCreateHowWeWork,
+  commandHouseHowWeWork,
+  commandHouseInstructions,
+} from "./adapter-mcp.js";
 import {
   compiledContract,
   initializeCommandAdapter,
@@ -7,7 +11,7 @@ import {
   startCommandAdapter,
   stopCommandAdapter,
 } from "./adapter.js";
-import { PERMISSION_OPTION_KINDS, SESSION_SET_CONFIG_OPTION } from "./contract.js";
+import { HOUSE_CLI_LINE, PERMISSION_OPTION_KINDS, SESSION_SET_CONFIG_OPTION } from "./contract.js";
 import { observedAssistantDrafts } from "./draft.js";
 import { observedPlans } from "./plan.js";
 import { bridgePeer } from "./peer.js";
@@ -129,6 +133,20 @@ async function configureSession(acp, contract, sessionId, adapter) {
   }
 }
 
+async function sessionOpening(channel, bridge, start) {
+  if (start.create_how_we_work === true && (await commandHouseCreateHowWeWork(bridge))) {
+    channel.send({ type: "how_we_work" });
+  }
+  const parts = [HOUSE_CLI_LINE, start.base_instructions, await commandHouseHowWeWork(bridge)];
+  return [{ type: "text", text: parts.filter((part) => part.trim() !== "").join("\n\n") }];
+}
+
+function workingCopyContext(copies) {
+  if (!Array.isArray(copies) || copies.length === 0) return [];
+  const lines = copies.map((copy) => `${copy.path}: ${copy.repository}`);
+  return [{ type: "text", text: ["Local Git working copies of House paths:", ...lines].join("\n") }];
+}
+
 async function runTurn(channel, start, bridge, turn) {
   const contract = compiledContract(start.adapter?.kind);
   const adapter = startCommandAdapter(
@@ -137,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 = () => {
@@ -149,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),
@@ -173,6 +203,8 @@ async function runTurn(channel, start, bridge, turn) {
     const { acp } = await initializeCommandAdapter(adapter, contract, handlers);
     const instructions = await commandHouseInstructions(bridge);
     let providerSessionId = start.provider_session ?? null;
+    const opening =
+      providerSessionId === null ? await sessionOpening(channel, bridge, start) : [];
     const setup = { cwd: start.working_directory, mcpServers: [] };
     if (providerSessionId === null) {
       providerSessionId = openedSession(await acp.request("session/new", setup));
@@ -185,28 +217,29 @@ async function runTurn(channel, start, bridge, turn) {
       loading = false;
     }
     await configureSession(acp, contract, providerSessionId, start.adapter);
-    const request = start.request === null ? await commandHouseRequest(bridge) : start.request;
     turn.adapterSession = true;
     turn.cancel = () => acp.cancel({ sessionId: providerSessionId });
     const prompted = await acp.request("session/prompt", {
       sessionId: providerSessionId,
       prompt: [
-        { type: "text", text: JSON.stringify(request) },
+        ...opening,
+        { type: "text", text: JSON.stringify(start.request) },
         { type: "text", text: instructions },
+        ...workingCopyContext(start.working_copies),
       ],
     });
     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);
@@ -219,6 +252,7 @@ export async function launchWorkerSession(bridge) {
     providerTurn: randomUUID(),
     questions: new Map(),
     cancel: null,
+    plan: () => null,
   };
   const peer = bridgePeer({
     socket: bridge.socket,
@@ -246,6 +280,7 @@ export async function launchWorkerSession(bridge) {
               type: "interrupt_applied",
               interrupt: frame.interrupt,
               outcome: "interrupted",
+              plan: turn.plan(),
             }),
           () =>
             peer.send({
@@ -268,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/local-files.js

@@ -1,6 +1,7 @@
 import { isAbsolute } from "node:path";
-import { parse, stringify } from "yaml";
+import { stringify } from "yaml";
 import { AGENT_OPERATION_META, ATTACHMENT_FILE_META } from "./contract.js";
+import { answerText, answerYaml } from "./mcp.js";
 import { derivedOperationId } from "./operation.js";
 import { localAttachment, sendLocalConversationFile, uploadLocalAttachment } from "./original.js";
 import { KitRefusal } from "./refusal.js";
@@ -12,18 +13,9 @@ class HouseRefused extends Error {
   }
 }
 
-function parsed(text) {
-  try {
-    return parse(text);
-  } catch {
-    return null;
-  }
-}
-
 function answerOf(frame) {
   if (frame.error !== undefined || frame.result?.isError === true) throw new HouseRefused(frame);
-  const text = (frame.result?.content ?? []).filter((item) => item.type === "text").map((item) => item.text).join("\n");
-  const answer = parsed(text);
+  const answer = answerYaml(answerText(frame.result));
   if (answer === null || typeof answer !== "object") throw new KitRefusal("kit_house_answer_unreadable");
   return answer;
 }

package/src/login.js

@@ -8,12 +8,13 @@ import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { KIT_CREDENTIAL } from "./contract.js";
 import { launchBase, prepareLaunchBase } from "./directory.js";
-import { houseRequest } from "./house.js";
+import { houseRequest, refuseDrained } from "./house.js";
 import { KitRefusal } from "./refusal.js";
 import { writeText } from "./state.js";
 
 const ENVIRONMENT =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DEFAULT_HOUSE = "https://agents.house";
 
 function verifier() {
   return randomBytes(32).toString("base64url");
@@ -112,19 +113,29 @@ function houseOrigin(value) {
   return value;
 }
 
-export async function storedHouse(directory, firstLogin = false, requested = undefined) {
-  let value;
+async function recordedHouse(directory) {
   try {
-    value = (await readFile(join(directory, "house"), "utf8")).trim();
+    return (await readFile(join(directory, "house"), "utf8")).trim();
   } catch (error) {
-    if (error.code === "ENOENT") {
-      if ((firstLogin || requested !== undefined) &&
-        await storedEnvironment(directory) === null && !await storedCredentialPresent(directory)) {
-        return houseOrigin(requested ?? "https://agents.house");
-      }
-    }
+    if (error.code === "ENOENT") return null;
     throw new KitRefusal("kit_house_invalid", error.code ?? "unreadable");
   }
+}
+
+export async function storedHouse(directory) {
+  const value = await recordedHouse(directory);
+  if (value === null) throw new KitRefusal("kit_house_invalid", "ENOENT");
+  return houseOrigin(value);
+}
+
+export async function loginHouse(directory, requested) {
+  const value = await recordedHouse(directory);
+  if (value === null) {
+    if (await storedEnvironment(directory) !== null || await storedCredentialPresent(directory)) {
+      throw new KitRefusal("kit_house_invalid", "ENOENT");
+    }
+    return houseOrigin(requested ?? DEFAULT_HOUSE);
+  }
   houseOrigin(value);
   if (requested !== undefined && requested !== value) {
     throw new KitRefusal("kit_house_mismatch", "this Environment is bound to another House origin");
@@ -133,7 +144,7 @@ export async function storedHouse(directory, firstLogin = false, requested = und
 }
 
 export function enrollmentAct(options, retained, host) {
-  if (options.label !== undefined || (options.environment !== undefined && !ENVIRONMENT.test(options.environment))) {
+  if (options.environment !== undefined && !ENVIRONMENT.test(options.environment)) {
     throw new KitRefusal("kit_login_rejected", ENROLLMENT_USAGE);
   }
   const environment = options.environment ?? retained;
@@ -205,11 +216,12 @@ export async function login(options, dependencies = {}) {
   return { environment: exchanged.environment };
 }
 
-export async function loopback() {
+export async function loopback(published) {
   const server = createServer();
   await new Promise((resolve, reject) => {
     server.once("error", reject);
-    server.listen(0, "127.0.0.1", resolve);
+    if (published === undefined) server.listen(0, "127.0.0.1", resolve);
+    else server.listen(Number(published), "0.0.0.0", resolve);
   });
   const address = server.address();
   const code = new Promise((resolve, reject) => {
@@ -260,9 +272,10 @@ export async function openBrowser(url) {
 }
 
 export async function connectHouse(options, dependencies = {}) {
+  refuseDrained(options.directory);
   await prepareLaunchBase(launchBase(dependencies));
   if (options.presentation === "manual") return login(options, dependencies);
-  const callback = await loopback();
+  const callback = await loopback(options.loginPort);
   try {
     return await login(
       { ...options, presentation: "loopback", loopbackUri: callback.uri },

package/src/mcp.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { parse } from "yaml";
 import { bridgePeer } from "./peer.js";
 import { KitRefusal } from "./refusal.js";
 
@@ -69,3 +70,20 @@ export async function bridgeCall(bridge, request, signal = undefined) {
     await peer.end();
   }
 }
+
+export function answerText(result) {
+  return (result?.content ?? []).filter((item) => item.type === "text").map((item) => item.text).join("\n");
+}
+
+export function answerYaml(text) {
+  try {
+    return parse(text);
+  } catch {
+    return null;
+  }
+}
+
+export function editRefusal(text) {
+  const conflicts = answerYaml(text.slice(text.indexOf("\n") + 1))?.conflicts;
+  return { code: text.split(":")[0].trim(), conflicts: Array.isArray(conflicts) ? conflicts : null };
+}

package/src/mount.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
-import { apply, links, parse, serialize } from "@agentshouse/mdmodel";
+import { apply, links, parse, retarget, serialize } from "@agentshouse/mdmodel";
 import {
   KIT_DOOR_BATCH_PATH,
   KIT_DOOR_BOOTSTRAP_PATH,
@@ -84,7 +84,6 @@ export function mountTarget(subtree) {
     refuse("kit_mount_subtree_invalid", subtree);
   }
   return {
-    kind: own ? "private" : "room",
     handle: own ? null : segments[1],
     root: own ? "/private" : `/rooms/${segments[1]}`,
     subtree,
@@ -129,16 +128,11 @@ function authorityFor(discovery, target) {
   };
 }
 
-function hrefSuffix(href) {
-  const match = /[?#]/.exec(href);
-  return match === null ? "" : href.slice(match.index);
-}
-
 function replaceLink(document, href, destination) {
   const marker = `house-kit-link:${operationId()}`;
   const located = apply(document, { kind: "link", href, to: marker });
   if (located.outcome !== "applied") refuse("kit_mount_link_unwritable", href);
-  const cleared = parse(serialize(located.document).replaceAll(`${marker}${hrefSuffix(href)}`, marker));
+  const cleared = parse(serialize(located.document).replaceAll(retarget(href, marker), marker));
   if (!cleared.ok) refuse("kit_mount_link_unwritable", href);
   const changed = apply(cleared.document, { kind: "link", href: marker, to: destination });
   if (changed.outcome !== "applied") refuse("kit_mount_link_unwritable", href);
@@ -179,11 +173,8 @@ export function rewriteAttachmentLinks(held, mintVersion) {
         refuse("kit_migrator_referrer_undeclared", `${relative} -> ${path}`);
       }
       const version = mintVersion(path);
-      const applied = apply(document, {
-        kind: "link",
-        href: link.href,
-        to: `${PENDING_LINK_SCHEME}:${version}`,
-      });
+      const pending = `${PENDING_LINK_SCHEME}:${version}`;
+      const applied = apply(document, { kind: "link", href: link.href, to: pending });
       if (applied.outcome !== "applied") refuse("kit_mount_link_unwritable", link.href);
       document = applied.document;
       let save = saves.find((entry) => entry.path === path);
@@ -192,8 +183,8 @@ export function rewriteAttachmentLinks(held, mintVersion) {
         saves.push(save);
       }
       if (!save.documents.includes(relative)) save.documents.push(relative);
-      const suffix = hrefSuffix(link.href);
-      const href = `${PENDING_LINK_SCHEME}:${version}${suffix}`;
+      const suffix = retarget(link.href, "");
+      const href = retarget(link.href, pending);
       if (!save.hrefs.some((entry) => entry.document === relative && entry.href === href)) {
         save.hrefs.push({ document: relative, href, suffix });
       }
@@ -327,7 +318,7 @@ function pendingTransfer(held, save) {
   };
 }
 
-async function submitAttachments(session, held, target, authority, plan, signal) {
+async function submitAttachments(session, held, authority, plan, signal) {
   const transfers = [];
   for (const save of plan.saves) {
     const local = held.attachments.get(save.path);
@@ -342,7 +333,7 @@ async function submitAttachments(session, held, target, authority, plan, signal)
         version: save.version,
         name: declared.name,
         mediaType: declared.mediaType ?? undefined,
-        room: target.kind === "room" ? authority.authority : null,
+        room: authority.authority,
         body,
         signal,
       });
@@ -472,7 +463,7 @@ export async function mountPackage(held, options, dependencies = {}) {
     };
     const localReport = join(held.root, "MIGRATION.json");
     await writeFile(localReport, `${JSON.stringify(result, null, 2)}\n`);
-    result.transfers = await submitAttachments(session, held, target, authority, plan, signal);
+    result.transfers = await submitAttachments(session, held, authority, plan, signal);
 
     const report = `${target.subtree}/${MOUNT_REPORT_NAME}`;
     await writeFile(localReport, `${JSON.stringify(result, null, 2)}\n`);

package/src/original.js

@@ -133,9 +133,9 @@ function outcomeOf(answer) {
 
 function grantOf(value, kind) {
   if (value === undefined) return null;
-  if (typeof value?.url !== "string" || typeof value?.operation !== "string") {
-    refuse("kit_original_grant_rejected", kind);
-  }
+  if (typeof value?.url !== "string") refuse("kit_original_grant_rejected", kind);
+  if (kind === "download") return { url: value.url };
+  if (typeof value.operation !== "string") refuse("kit_original_grant_rejected", kind);
   return { url: value.url, operation: value.operation };
 }
 
@@ -148,7 +148,7 @@ function sendBytes(dependencies, grant, body, signal) {
 
 async function receiveBytes(session, grant, signal) {
   const transferred = await transferBytes(
-    { url: grant.url, method: "GET", operation: grant.operation, signal },
+    { url: grant.url, method: "GET", signal },
     session.dependencies,
   );
   return transferred.bytes;

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