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

package/src/telegram.js

@@ -10,6 +10,7 @@ import {
   PERSONAL_BOT_OFFSET_RELATIVE_PATH,
   PERSONAL_BOT_TOKEN_RELATIVE_PATH,
   TELEGRAM_BOT_API_TIMEOUT_MS,
+  TELEGRAM_CAPTION_CHARACTERS_MAX,
   TELEGRAM_CONTROL_KEYBOARD_COMMANDS,
   TELEGRAM_DELIVERY_BATCH_MAX,
   TELEGRAM_DELIVERY_KINDS,
@@ -18,14 +19,18 @@ import {
   TELEGRAM_IMAGE_UPLOAD_CEILING_BYTES,
   TELEGRAM_INGRESS_BATCH_MAX,
   TELEGRAM_MEDIA_KINDS,
+  TELEGRAM_MESSAGE_CHARACTERS_MAX,
   TELEGRAM_UNSUPPORTED_MEDIA_FIELDS,
   TELEGRAM_UPDATE_OUTCOMES,
   telegramApiUrl,
   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, slices, 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 +287,28 @@ export function deliveryCall(delivery) {
   return { method: "sendMessage", body: sendBody(delivery) };
 }
 
+function topicMessage(chat, topic, text) {
+  const body = { chat_id: Number(chat), text };
+  if (topic !== null) body.message_thread_id = Number(topic);
+  return { method: "sendMessage", body };
+}
+
+function deliveryCalls(delivery) {
+  const call = deliveryCall(delivery);
+  if (call.method === "sendMessage" && call.body.text.length > TELEGRAM_MESSAGE_CHARACTERS_MAX) {
+    const [first, ...following] = slices(call.body.text, TELEGRAM_MESSAGE_CHARACTERS_MAX);
+    return [
+      { method: call.method, body: { ...call.body, text: first } },
+      ...following.map((text) => topicMessage(delivery.chat_id, delivery.topic_id, text)),
+    ];
+  }
+  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 +380,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 +404,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 +751,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 +780,51 @@ 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;
+}
+
+function captionPieces(caption) {
+  if (caption === null || caption.length <= TELEGRAM_CAPTION_CHARACTERS_MAX) return [caption];
+  const [head] = slices(caption, TELEGRAM_CAPTION_CHARACTERS_MAX);
+  return [head, ...slices(caption.slice(head.length), TELEGRAM_MESSAGE_CHARACTERS_MAX)];
+}
+
+async function sentOverflow(gateway, token, upload, overflow) {
+  for (const text of overflow) {
+    const call = topicMessage(upload.chat_id, upload.topic_id, text);
+    let answered;
+    try {
+      answered = await telegramPost(gateway, telegramApiUrl(token, call.method), call.body);
+    } catch (error) {
+      if (cancelled(error)) throw error;
+      return { settled: uploadOutcome(null), answered: null };
+    }
+    if (!botApiAccepted(answered)) return { settled: uploadOutcome(answered), answered };
+  }
+  return null;
 }
 
 async function sendQueuedUpload(gateway, token, upload) {
@@ -789,12 +846,13 @@ async function sendQueuedUpload(gateway, token, upload) {
     });
     return false;
   }
+  const [caption, ...overflow] = captionPieces(upload.caption);
   let answered;
   try {
     answered = await telegramUpload(
       gateway,
       telegramApiUrl(token, "sendPhoto"),
-      uploadFields(upload),
+      uploadFields({ ...upload, caption }),
       { field: "photo", name: upload.file_name, bytes },
     );
   } catch (error) {
@@ -805,78 +863,121 @@ async function sendQueuedUpload(gateway, token, upload) {
     });
     return false;
   }
-  await reportUpload(gateway, upload, uploadOutcome(answered));
-  const retryAfter = telegramRetryAfter(answered);
+  const photographed = uploadOutcome(answered);
+  const unsent =
+    photographed.outcome === "delivered" ? await sentOverflow(gateway, token, upload, overflow) : null;
+  await reportUpload(gateway, upload, unsent?.settled ?? photographed);
+  const retryAfter = telegramRetryAfter(unsent === null ? answered : unsent.answered);
   if (retryAfter === null) return false;
   gateway.gate.hold(retryAfter);
   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 +1056,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 +1100,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 +1112,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 +1129,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 +1151,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");
+    },
+  };
+}