@agentshouse/kit 0.1.0-alpha.3 → 0.1.0-alpha.30

package/src/telegram-view.js

@@ -0,0 +1,214 @@
+import { createHash } from "node:crypto";
+import {
+  TELEGRAM_RICH_MESSAGE_BLOCKS_MAX,
+  TELEGRAM_RICH_MESSAGE_CHARACTERS_MAX,
+} from "./contract.js";
+
+const PARTS = Object.freeze({ draft: "blocks", plan: "steps" });
+const UNCOUNTED = new Set(["type", "language"]);
+
+function richCharacters(value, key = null) {
+  if (typeof value === "string") return UNCOUNTED.has(key) ? 0 : value.length;
+  if (Array.isArray(value)) return value.reduce((sum, item) => sum + richCharacters(item), 0);
+  if (typeof value === "object" && value !== null) {
+    return Object.entries(value).reduce((sum, [name, item]) => sum + richCharacters(item, name), 0);
+  }
+  return 0;
+}
+
+function richText(value, key = null) {
+  if (typeof value === "string") return UNCOUNTED.has(key) ? [] : [value];
+  if (Array.isArray(value)) return value.flatMap((item) => richText(item));
+  if (typeof value === "object" && value !== null) {
+    return Object.entries(value).flatMap(([name, item]) => richText(item, name));
+  }
+  return [];
+}
+
+function slices(text) {
+  const pieces = [];
+  let start = 0;
+  while (start < text.length) {
+    let end = Math.min(start + TELEGRAM_RICH_MESSAGE_CHARACTERS_MAX, text.length);
+    const last = text.charCodeAt(end - 1);
+    if (end < text.length && last >= 0xd800 && last <= 0xdbff) end -= 1;
+    pieces.push(text.slice(start, end));
+    start = end;
+  }
+  return pieces;
+}
+
+function grouped(block, listed) {
+  const groups = [];
+  let group = [];
+  let characters = 0;
+  for (const entry of block[listed]) {
+    const length = richCharacters(entry);
+    if (group.length > 0 && characters + length > TELEGRAM_RICH_MESSAGE_CHARACTERS_MAX) {
+      groups.push(group);
+      group = [];
+      characters = 0;
+    }
+    group.push(entry);
+    characters += length;
+  }
+  if (group.length > 0) groups.push(group);
+  return groups.flatMap((entries) => fitted({ ...block, [listed]: entries }));
+}
+
+function fitted(block) {
+  if (richCharacters(block) <= TELEGRAM_RICH_MESSAGE_CHARACTERS_MAX) return [block];
+  if (typeof block.text === "string") return slices(block.text).map((text) => ({ ...block, text }));
+  if (typeof block.expression === "string") {
+    return slices(block.expression).map((expression) => ({ ...block, expression }));
+  }
+  for (const listed of ["items", "cells"]) {
+    if (Array.isArray(block[listed]) && block[listed].length > 1) return grouped(block, listed);
+  }
+  return slices(richText(block).join("\n")).map((text) => ({ type: "paragraph", text }));
+}
+
+export function richPieces(message) {
+  const pieces = [];
+  let blocks = [];
+  let characters = 0;
+  for (const part of message.blocks.flatMap(fitted)) {
+    const length = richCharacters(part);
+    if (
+      blocks.length > 0 &&
+      (blocks.length >= TELEGRAM_RICH_MESSAGE_BLOCKS_MAX ||
+        characters + length > TELEGRAM_RICH_MESSAGE_CHARACTERS_MAX)
+    ) {
+      pieces.push({ ...message, blocks });
+      blocks = [];
+      characters = 0;
+    }
+    blocks.push(part);
+    characters += length;
+  }
+  pieces.push({ ...message, blocks });
+  return pieces;
+}
+
+function listItems(items, ordered) {
+  return items.map((item, index) => ({
+    blocks: [{ type: "paragraph", text: item }],
+    ...(ordered ? { value: index + 1, type: "1" } : {}),
+  }));
+}
+
+function telegramBlock(block) {
+  if (typeof block !== "object" || block === null) return null;
+  if (block.type === "paragraph") return { type: "paragraph", text: block.text };
+  if (block.type === "heading") return { type: "heading", size: block.level, text: block.text };
+  if (block.type === "code") {
+    return {
+      type: "pre",
+      ...(typeof block.language === "string" ? { language: block.language } : {}),
+      text: block.text,
+    };
+  }
+  if (block.type === "list" && Array.isArray(block.items)) {
+    return { type: "list", items: listItems(block.items, block.ordered === true) };
+  }
+  if (block.type === "table" && Array.isArray(block.headers) && Array.isArray(block.rows)) {
+    return {
+      type: "table",
+      cells: [
+        block.headers.map((text) => ({ text, is_header: true })),
+        ...block.rows.map((row) => (Array.isArray(row) ? row : []).map((text) => ({ text }))),
+      ],
+      is_bordered: true,
+    };
+  }
+  if (block.type === "formula") return { type: "mathematical_expression", expression: block.expression };
+  return null;
+}
+
+function planBlocks(steps) {
+  return [
+    { type: "heading", text: "Plan", size: 3 },
+    {
+      type: "list",
+      items: steps.map((step, index) => ({
+        blocks: [{ type: "paragraph", text: [`${step.label} — `, { type: "bold", text: step.status }] }],
+        value: index + 1,
+        type: "1",
+      })),
+    },
+  ];
+}
+
+function draftId(turn) {
+  return (createHash("sha256").update(turn).digest().readUInt32BE(0) % 2_147_483_647) + 1;
+}
+
+function viewFrame(frame) {
+  if (typeof frame !== "object" || frame === null || !Object.hasOwn(PARTS, frame.type)) return null;
+  for (const named of ["conversation_id", "turn_id"]) {
+    if (typeof frame[named] !== "string" || frame[named] === "") return null;
+  }
+  if (!Number.isSafeInteger(frame.sequence) || frame.sequence < 1) return null;
+  if (!Number.isSafeInteger(frame.from) || frame.from < 0) return null;
+  return Array.isArray(frame[PARTS[frame.type]]) ? frame : null;
+}
+
+export function turnViews(options) {
+  let threads = new Map();
+  const views = new Map();
+
+  function applied(view, frame) {
+    const items = frame[PARTS[frame.type]];
+    const held = view[frame.type];
+    if (held !== null && frame.sequence <= held.sequence) return false;
+    if (frame.from === 0) {
+      view[frame.type] = { sequence: frame.sequence, items };
+      view.asked = false;
+      return true;
+    }
+    if (held === null || frame.sequence !== held.sequence + 1 || frame.from > held.items.length) {
+      if (!view.asked) {
+        view.asked = true;
+        options.gap({ type: "gap", conversation_id: frame.conversation_id, turn_id: frame.turn_id });
+      }
+      return false;
+    }
+    view[frame.type] = { sequence: frame.sequence, items: [...held.items.slice(0, frame.from), ...items] };
+    return true;
+  }
+
+  return {
+    address(listed) {
+      threads = new Map(listed.map((thread) => [thread.conversation_id, thread]));
+      for (const conversation of views.keys()) {
+        if (!threads.has(conversation)) views.delete(conversation);
+      }
+    },
+    receive(value) {
+      const frame = viewFrame(value);
+      if (frame === null || !threads.has(frame.conversation_id)) return null;
+      let view = views.get(frame.conversation_id);
+      if (view === undefined || view.turn !== frame.turn_id) {
+        view = { turn: frame.turn_id, draft: null, plan: null, asked: false };
+        views.set(frame.conversation_id, view);
+      }
+      return applied(view, frame) ? frame.conversation_id : null;
+    },
+    draft(conversation) {
+      const view = views.get(conversation);
+      const thread = threads.get(conversation);
+      if (view === undefined || thread === undefined) return null;
+      const blocks = [
+        ...(view.plan === null ? [] : planBlocks(view.plan.items)),
+        ...(view.draft === null ? [] : view.draft.items.map(telegramBlock).filter((block) => block !== null)),
+      ];
+      if (blocks.length === 0) return null;
+      return {
+        chat_id: thread.chat_id,
+        topic_id: thread.topic_id,
+        draft_id: draftId(view.turn),
+        rich_message: richPieces({ blocks })[0],
+      };
+    },
+  };
+}

package/src/telegram.js

@@ -24,8 +24,11 @@ import {
   telegramFileUrl,
 } from "./contract.js";
 import { heldControl, houseRequest, maintainControl, openSession } from "./house.js";
+import { watchKitWork } from "./kit-work-stream.js";
 import { KitRefusal } from "./refusal.js";
 import { writeText } from "./state.js";
+import { richPieces, turnViews } from "./telegram-view.js";
+import { kitStreamWriter } from "./turn-frames.js";
 
 const TOKEN_PROMPT = "Paste the BotFather token for this Environment: ";
 const AMBIGUOUS_DELIVERY = Object.freeze({ telegram_message_id: null, telegram_topic_id: null });
@@ -282,6 +285,15 @@ export function deliveryCall(delivery) {
   return { method: "sendMessage", body: sendBody(delivery) };
 }
 
+function deliveryCalls(delivery) {
+  const call = deliveryCall(delivery);
+  if (call.method !== "sendRichMessage") return [call];
+  return richPieces(call.body.rich_message).map((rich_message) => ({
+    method: call.method,
+    body: { ...call.body, rich_message },
+  }));
+}
+
 function acceptedDelivery(delivery, result) {
   if (delivery.kind === "conversation_topic") {
     const threadId = plain(result) ? result.message_thread_id : undefined;
@@ -353,12 +365,15 @@ function queuedDelivery(value) {
   return value;
 }
 
-function queuedDraft(value) {
-  if (!plain(value) || !plain(value.rich_message)) refuseAnswer();
-  for (const named of ["conversation_id", "turn_id", "chat_id", "topic_id", "draft_id"]) {
-    if (typeof value[named] !== "string" || value[named].length === 0) refuseAnswer();
-  }
-  return value;
+function threadsOf(answer) {
+  if (!Array.isArray(answer?.threads)) refuseAnswer();
+  return answer.threads.map((thread) => {
+    if (!plain(thread)) refuseAnswer();
+    for (const named of ["conversation_id", "chat_id", "topic_id"]) {
+      if (typeof thread[named] !== "string" || thread[named].length === 0) refuseAnswer();
+    }
+    return { conversation_id: thread.conversation_id, chat_id: thread.chat_id, topic_id: thread.topic_id };
+  });
 }
 
 function queuedUpload(value) {
@@ -374,7 +389,6 @@ function queueOf(answer) {
   return answer.queue.map((item) => {
     if (!plain(item)) refuseAnswer();
     if (item.type === "message") return { type: "message", delivery: queuedDelivery(item.delivery) };
-    if (item.type === "draft") return { type: "draft", draft: queuedDraft(item.draft) };
     if (item.type !== "file") refuseAnswer();
     return { type: "file", upload: queuedUpload(item.upload) };
   });
@@ -722,7 +736,7 @@ async function relayInboundFiles(gateway) {
       gateway.summary.relayed.push({ attachment: file.id, bytes: bytes.length });
     } catch (error) {
       if (cancelled(error) || !(error instanceof KitRefusal)) throw error;
-      gateway.summary.failures.push({ activity: "inbound", item: file.id, code: error.code });
+      refusedPass(gateway, { activity: "inbound", item: file.id, code: error.code });
     }
   }
 }
@@ -751,23 +765,30 @@ async function reportUpload(gateway, upload, settled) {
 
 async function sendQueuedMessage(gateway, token, delivery) {
   await houseCall(gateway, `deliveries/${delivery.id}/attempt`);
-  const call = deliveryCall(delivery);
-  let answered;
-  try {
-    answered = await telegramPost(gateway, telegramApiUrl(token, call.method), call.body);
-  } catch (error) {
-    if (cancelled(error)) throw error;
-    await reportDelivery(gateway, delivery, {
-      outcome: "delivery_unknown",
-      report: AMBIGUOUS_DELIVERY,
-    });
-    return false;
+  let first = null;
+  for (const call of deliveryCalls(delivery)) {
+    let answered;
+    try {
+      answered = await telegramPost(gateway, telegramApiUrl(token, call.method), call.body);
+    } catch (error) {
+      if (cancelled(error)) throw error;
+      await reportDelivery(gateway, delivery, {
+        outcome: "delivery_unknown",
+        report: AMBIGUOUS_DELIVERY,
+      });
+      return false;
+    }
+    const settled = deliveryOutcome(delivery, answered);
+    const retryAfter = telegramRetryAfter(answered);
+    if (retryAfter !== null) gateway.gate.hold(retryAfter);
+    if (settled.outcome !== "delivered") {
+      await reportDelivery(gateway, delivery, settled);
+      return retryAfter !== null;
+    }
+    first ??= settled;
   }
-  await reportDelivery(gateway, delivery, deliveryOutcome(delivery, answered));
-  const retryAfter = telegramRetryAfter(answered);
-  if (retryAfter === null) return false;
-  gateway.gate.hold(retryAfter);
-  return true;
+  await reportDelivery(gateway, delivery, first);
+  return false;
 }
 
 async function sendQueuedUpload(gateway, token, upload) {
@@ -812,71 +833,111 @@ async function sendQueuedUpload(gateway, token, upload) {
   return true;
 }
 
-export async function streamDrafts(drafts, gate, post) {
-  for (const draft of drafts) {
-    if (gate.open()) return;
-    const call = draftCall(draft);
-    let answered;
-    try {
-      answered = await post(call);
-    } catch (error) {
-      if (cancelled(error)) throw error;
-      return;
-    }
-    const retryAfter = telegramRetryAfter(answered);
-    if (retryAfter !== null) {
-      gate.hold(retryAfter);
-      return;
+function liveDrafts(gateway) {
+  const stream = kitStreamWriter();
+  const views = turnViews({ gap: (frame) => stream.write(frame) });
+  const dirty = new Set();
+  let pumping = null;
+
+  async function pump() {
+    while (dirty.size > 0) {
+      const [conversation] = dirty;
+      dirty.delete(conversation);
+      if (gateway.gate.open()) {
+        dirty.clear();
+        return;
+      }
+      const draft = views.draft(conversation);
+      if (draft === null) continue;
+      const call = draftCall(draft);
+      let answered;
+      try {
+        const token = await gatewayToken(gateway);
+        answered = await telegramPost(gateway, telegramApiUrl(token, call.method), call.body);
+      } catch (error) {
+        if (!(error instanceof KitRefusal)) throw error;
+        if (cancelled(error)) dirty.clear();
+        continue;
+      }
+      const retryAfter = telegramRetryAfter(answered);
+      if (retryAfter !== null) {
+        gateway.gate.hold(retryAfter);
+        dirty.clear();
+      }
     }
   }
+
+  function start() {
+    if (pumping !== null || dirty.size === 0) return;
+    pumping = pump().finally(() => {
+      pumping = null;
+      start();
+    });
+    pumping.catch(() => undefined);
+  }
+
+  return {
+    heard: {
+      available: () => undefined,
+      changed: () => undefined,
+      opened: stream.opened,
+      closed: stream.closed,
+      viewed: (frame) => {
+        const conversation = views.receive(frame);
+        if (conversation === null) return;
+        dirty.add(conversation);
+        start();
+      },
+    },
+    address: (threads) => views.address(threads),
+    settled: () => pumping ?? Promise.resolve(),
+  };
 }
 
-async function streamQueuedDrafts(gateway, token, drafts) {
-  if (gateway.gate.open()) return;
-  await streamDrafts(drafts, gateway.gate, (call) =>
-    telegramPost(gateway, telegramApiUrl(token, call.method), call.body),
-  );
+function watchGatewayStream(session, signal, heard) {
+  if (session.relay !== undefined) return session.relay(signal, heard);
+  return (session.dependencies.watchKitWork ?? watchKitWork)(session, signal, heard, session.dependencies);
 }
 
 async function drainOutboundQueue(gateway) {
   if (gateway.gate.open()) return;
   const token = await gatewayToken(gateway);
-  const queue = queueOf(
-    await houseCall(gateway, "queue/acquire", { max: TELEGRAM_DELIVERY_BATCH_MAX }),
-  );
-  const drafts = [];
+  const answer = await houseCall(gateway, "queue/acquire", { max: TELEGRAM_DELIVERY_BATCH_MAX });
+  const queue = queueOf(answer);
+  gateway.live?.address(threadsOf(answer));
   for (const item of queue) {
-    if (item.type === "draft") {
-      drafts.push(item.draft);
-      continue;
-    }
     const gated =
       item.type === "file"
         ? await sendQueuedUpload(gateway, token, item.upload)
         : await sendQueuedMessage(gateway, token, item.delivery);
     if (gated) return;
   }
-  await streamQueuedDrafts(gateway, token, drafts);
+}
+
+function refusedPass(gateway, failure) {
+  gateway.summary.failures.push(failure);
+  gateway.refused(failure);
 }
 
 async function onePass(gateway, activity, work) {
   try {
     await work(gateway);
   } catch (error) {
-    if (cancelled(error) || !(error instanceof KitRefusal)) throw error;
-    gateway.summary.failures.push({ activity, item: null, code: error.code });
+    if (cancelled(error) || !(error instanceof KitRefusal) || error.code === "kit_update_draining") throw error;
+    refusedPass(gateway, { activity, item: null, code: error.code });
   }
 }
 
 async function paceActivity(gateway, stopping, activity, work) {
   try {
-    for (let index = 0; index < gateway.passes; index += 1) {
+    for (let index = 0; index < gateway.passes && !gateway.draining; index += 1) {
       if (gateway.signal?.aborted === true) throw new KitRefusal("kit_command_cancelled");
       await onePass(gateway, activity, work);
       if (index + 1 < gateway.passes) await gateway.wait(TELEGRAM_GATEWAY_POLL_MS, gateway.signal);
     }
   } catch (error) {
-    stopping.abort();
+    if (error.code === "kit_update_draining") gateway.draining = true;
+    else stopping.abort();
     throw error;
   }
 }
@@ -955,22 +1016,32 @@ async function proveOwner(gateway, token, telegramBotUserId) {
   throw new KitRefusal("telegram_owner_not_proven");
 }
 
-function gatewayContext(session, options, dependencies, signal, summary = emptySummary()) {
+function gatewayContext(session, options, signal, summary = emptySummary()) {
   return {
     session,
     directory: options.directory,
-    dependencies,
+    dependencies: session.dependencies,
     signal,
     gate: rateGate(() => session.now().getTime()),
-    wait: dependencies.wait ?? pause,
+    wait: session.dependencies.wait ?? pause,
     passes: options.passes ?? Number.POSITIVE_INFINITY,
+    draining: false,
     summary,
+    refused: options.refused,
   };
 }
 
 export async function connectPersonalBot(options, dependencies = {}) {
   const session = await openSession(options, dependencies);
-  const gateway = gatewayContext(session, options, dependencies, options.signal);
+  return maintainControl(
+    session,
+    (signal) => connectBot(session, options, dependencies, signal),
+    options.signal,
+  );
+}
+
+async function connectBot(session, options, dependencies, signal) {
+  const gateway = gatewayContext(session, options, signal);
   const ask = dependencies.prompt ?? (() => askForToken(dependencies));
   const token = (await ask()).trim();
   if (token.length === 0) throw new KitRefusal("telegram_bot_token_required");
@@ -989,7 +1060,7 @@ export async function connectPersonalBot(options, dependencies = {}) {
     owner_telegram_user_id: await proveOwner(gateway, token, identity.telegramBotUserId),
     has_topics_enabled: true,
   };
-  await writeOwned(tokenPath(options.directory), `${token}\n`, options.signal);
+  await writeOwned(tokenPath(options.directory), `${token}\n`, signal);
   try {
     await houseCall(gateway, "personal-bot", setup);
   } catch (error) {
@@ -1001,7 +1072,15 @@ export async function connectPersonalBot(options, dependencies = {}) {
 
 export async function disconnectPersonalBot(options, dependencies = {}) {
   const session = await openSession(options, dependencies);
-  const gateway = gatewayContext(session, options, dependencies, options.signal);
+  return maintainControl(
+    session,
+    (signal) => disconnectBot(session, options, signal),
+    options.signal,
+  );
+}
+
+async function disconnectBot(session, options, signal) {
+  const gateway = gatewayContext(session, options, signal);
   const directory = options.directory;
   const marked = await disconnecting(directory);
   let token = null;
@@ -1010,7 +1089,7 @@ export async function disconnectPersonalBot(options, dependencies = {}) {
   } catch (error) {
     if (!marked) throw error;
   }
-  if (!marked) await writeOwned(disconnectPath(directory), "{}\n", options.signal);
+  if (!marked) await writeOwned(disconnectPath(directory), "{}\n", signal);
   if (token !== null) {
     await telegramCall(gateway, token, "deleteWebhook", { drop_pending_updates: false });
     await Promise.all([
@@ -1032,9 +1111,25 @@ export async function serveTelegramGateway(options, dependencies = {}) {
       async (signal) => {
         const stopping = new AbortController();
         const shared = AbortSignal.any([signal, stopping.signal]);
-        const gateway = gatewayContext(session, options, dependencies, shared, summary);
+        const gateway = gatewayContext(session, options, shared, summary);
         summary.abandoned = abandonedOf(await houseCall(gateway, "deliveries/abandoned"));
-        await serveActivities(gateway, stopping);
+        gateway.live = liveDrafts(gateway);
+        const watcher = new AbortController();
+        const watching = watchGatewayStream(
+          session,
+          AbortSignal.any([shared, watcher.signal]),
+          gateway.live.heard,
+        ).catch((error) => {
+          if (cancelled(error)) return;
+          refusedPass(gateway, { activity: "drafts", item: null, code: error?.code ?? "kit_stream_failed" });
+        });
+        try {
+          await serveActivities(gateway, stopping);
+        } finally {
+          watcher.abort();
+          await watching;
+          await gateway.live.settled();
+        }
       },
       options.signal,
     );

package/src/turn-frames.js

@@ -0,0 +1,69 @@
+import { assistantBlocks } from "./blocks.js";
+
+export function kitStreamWriter() {
+  let send = null;
+  let generation = 0;
+  return {
+    get generation() {
+      return generation;
+    },
+    opened(write) {
+      generation += 1;
+      send = write;
+    },
+    closed() {
+      send = null;
+    },
+    write(frame) {
+      if (send === null) return false;
+      send(frame);
+      return true;
+    },
+  };
+}
+
+function firstChange(written, items) {
+  const shared = Math.min(written.length, items.length);
+  for (let index = 0; index < shared; index += 1) {
+    if (JSON.stringify(written[index]) !== JSON.stringify(items[index])) return index;
+  }
+  return shared;
+}
+
+export function turnFrames(stream) {
+  let identity = null;
+  const parts = {
+    draft: { key: "blocks", latest: null, written: null, generation: null },
+    plan: { key: "steps", latest: null, written: null, generation: null },
+  };
+
+  function write(type) {
+    const part = parts[type];
+    if (identity === null || part.latest === null) return;
+    const { sequence, items } = part.latest;
+    const whole = part.written === null || part.generation !== stream.generation;
+    const from = whole ? 0 : firstChange(part.written, items);
+    const generation = stream.generation;
+    const sent = stream.write({ type, ...identity, sequence, from, [part.key]: items.slice(from) });
+    part.written = sent ? items : null;
+    part.generation = generation;
+  }
+
+  return {
+    identify(named) {
+      identity = named;
+      write("draft");
+      write("plan");
+    },
+    draft(view) {
+      const blocks = assistantBlocks(view.text);
+      if (blocks === null) return;
+      parts.draft.latest = { sequence: view.sequence, items: blocks };
+      write("draft");
+    },
+    plan(snapshot) {
+      parts.plan.latest = { sequence: snapshot.sequence, items: snapshot.steps };
+      write("plan");
+    },
+  };
+}