@agentshouse/kit 0.1.0-alpha.28 → 0.1.0-alpha.29

package/README.md

@@ -12,7 +12,7 @@ The Skill set Kit installs is Matt Pocock's
 On Linux `amd64` or `arm64`, run the published, versioned bootstrap once:
 
 ```sh
-bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.28/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.29/connect-linux.sh)
 ```
 
 The bootstrap first establishes Docker Engine from what it observes on the
@@ -564,8 +564,12 @@ command returns exactly one JSON object such as `{ "authorized": true }`.
 The resident Kit holds one `/kit/stream` WebSocket for its Environment,
 authenticated with its Environment control lease and the Kit contract header,
 for as long as it holds that lease; `kit worker run` holds one for the length
-of its pass to receive its owner's commands. The Kit sends nothing on it and
-accepts every frame House sends.
+of its pass to receive its owner's commands, and `kit telegram serve` holds one
+while it serves the gateway under a lease of its own. The Kit sends no
+subscribe frame and accepts every frame House sends. What it writes there is
+the live view of the turns it runs, as draft and plan frames the
+[Worker runtime](#the-worker-runtime) describes, and a `gap` frame when the
+[Telegram gateway](#the-telegram-gateway) needs a turn's whole view again.
 
 Each time the socket connects, the resident acquires everything a signal could
 have named, because a signal House sent while the socket was down is lost: its
@@ -866,37 +870,55 @@ what it has seen so far, and seals the turn itself. No Agent is asked to report
 text a deterministic observer already sees, and no agent-facing tool admits final
 text.
 
-While the adapter generates, the Kit posts the whole User-visible assistant text
-of the turn so far to `sessions/<session>/drafts` as an ephemeral draft. Only
+While the adapter generates, the supervisor writes the whole User-visible
+assistant text of the turn so far as `draft` frames on the Environment's
+[control stream](#the-kit-control-stream); it calls no draft route. Only
 adapter-classified assistant message text enters that stream; reasoning, tool
-calls, plans, and terminal output never do. The Kit maps the structure it can
-read in that text - paragraphs, headings, fenced code, ordered and unordered
-lists, pipe tables, and `$$` formulas - into House's admitted blocks, and leaves
-anything it did not parse as the paragraph it observed. It invents no structure
-and renders nothing.
-
-The Kit coalesces and paces that stream rather than mirroring every chunk. It
-sends the first observed view at once, then at most one view every 500
-milliseconds, and one more the moment the adapter completes a message; one call
-is in flight at a time, so a newer view replaces the view it overtook and the
-view observed last is the view House sees last. A view whose text exceeds
-House's 4096-byte bound is not sent. A draft persists nowhere - not in this
-Kit's local state, not as House history - is never retried, and can neither
-delay nor prove turn completion: a refused, lost, or overtaken draft changes no
-Run, WorkerSession, or delivery state. Ending the stream waits for no draft the
-transport is still holding, so a slow or unanswered draft call cannot delay the
-seal or the Run behind it.
+calls, and terminal output never do. The Kit maps the structure it can read in
+that text - paragraphs, headings, fenced code, ordered and unordered lists, pipe
+tables, and `$$` formulas - into House's blocks, and leaves anything it did not
+parse as the paragraph it observed. It invents no structure, renders nothing,
+and holds back or refuses no draft for its length: a frame carries every block
+of the text however long it is.
+
+A frame names the turn it belongs to, as House answered the Session's `started`
+observation with the turn's `conversation_id` and `turn_id`, together with the
+Execution attempt as `attempt_id`. It carries a `sequence` that grows by one
+with each paced view of the turn, and replaces the turn's view from the block
+index `from` onward with the `blocks` it carries, so a frame for text that only
+grew carries the blocks from the first one that changed, and a view that
+changed no block is a frame that replaces nothing. The launcher numbers the
+views, so a Kit that restarts mid-turn continues the turn's sequence. The Kit
+coalesces and paces that stream rather than mirroring every chunk: it writes
+the first observed view at once and then at most one view in each
+500-millisecond pacing window, the latest one, even when the adapter completes
+a message inside a window. A frame written while the socket is down is lost,
+so the first frame after each reconnect, and after any frame the socket could not carry, replaces the view
+from block 0. A Session House names no conversation turn for gets no frames. A
+draft persists nowhere - not in this Kit's local state, not as House history -
+is never retried, and can neither delay nor prove turn completion.
+
+A `plan` session update is one snapshot of the agent's steps. The Kit writes
+each snapshot as a `plan` frame paced by the same rule, carrying every step's
+`label`, `priority` and `status` exactly as the adapter gave them, its own
+`sequence`, and the step index `from` it replaces the plan onward. The act that
+ends the turn carries the last snapshot the Kit saw as its final `plan`: the
+seal, the observed stop, the Run outcome and an `interrupted` interrupt outcome
+each name the provider turn and every step's `label` and `status`, however many
+steps and however long their text, and a turn that never planned carries none.
+There is no per-snapshot plan route.
 
 When the adapter completes the turn, the Kit seals it with one
-`sessions/<session>/assistant-messages` call carrying the same blocks and a
-UUIDv7 `operation_id`. The exact request - that identity and those blocks - is
-written into the WorkerSession binding before the call leaves, so a recovered
-call returns the outcome House recorded and never seals a turn twice, and
-House's answer names the turn it closed and the delivery it queued. An answer
-the Kit never received leaves the Run unsettled with the request retained: the
-next `kit worker run` replays exactly that operation and those blocks before
-settling anything, rather than reporting a failure it cannot prove. A refusal
-House did decide is the Run's reported failure.
+`sessions/<session>/assistant-messages` call carrying the same blocks, the final
+plan, and a UUIDv7 `operation_id`. The exact request - that identity, those
+blocks and that plan - is written into the WorkerSession binding before the
+call leaves, so a recovered call returns the outcome House recorded and never
+seals a turn twice, and House's answer names the turn it closed and the
+delivery it queued. An answer the Kit never received leaves the Run unsettled
+with the request retained: the next `kit worker run` replays exactly that
+operation, those blocks and that plan before settling anything, rather than
+reporting a failure it cannot prove. A refusal House did decide is the Run's
+reported failure.
 
 That seal is the one durable record of the turn, and only a seal House accepted
 completes a turn: the Kit reports whole-turn completion to House after the seal
@@ -1125,7 +1147,7 @@ A restore of House's database starts a new log epoch. Until this Environment
 has reported in it, House refuses every act that touches a Run, acquisition and
 lease release included, as `epoch_report_required` naming the epoch. The first
 such refusal ends whatever the pass was doing. One raised inside a supervised
-Run's bridge, while it admits or settles a question, streams a draft, or
+Run's bridge, while it admits or settles a question, reports an interrupt, or
 replaces Session authority for a forwarded call, never becomes an answer to the
 Agent: it ends the bridge and the pass at once. The Kit then reports, under the
 lease it holds and at `POST /kit/sessions/report`, every Run it holds a spawn
@@ -1683,7 +1705,7 @@ kit telegram serve
 
 The command holds one Environment control lease for the whole run and performs
 three activities inside it, each paced on its own so none of them blocks
-another:
+another, beside the live drafts described below:
 
 - **ingress** reads updates from the stored offset, normalizes each one into the
   update House accepts, submits it, and advances the stored offset only after
@@ -1704,15 +1726,39 @@ another:
   original, and reported the same way; a pull that fails reports
   `transfer_failed` and an ambiguous upload answer reports `delivery_unknown`.
   Only an image ever becomes a file item, because House offers every other file
-  as a `conversation_file_link` message this queue delivers like any other. Live drafts ride that same queue as their own item and are
-  never reported back, because a draft has no settlement: House has already
-  coalesced each conversation to its latest view, and the gateway sends the
-  drafts of a pass after its durable deliveries with the Bot API's native
-  `sendRichMessageDraft` on the bound forum topic thread, under the same bot-wide
-  `retry_after` gate. The gateway coalesces nothing again and holds no draft for
-  a later pass: a draft taken in a pass that gate closed is dropped, and the next
-  view House coalesces takes its place. Pacing lives here because this is where
-  the Bot API is called.
+  as a `conversation_file_link` message this queue delivers like any other. The
+  queue carries no draft: an answer holding a draft item is refused as
+  `kit_telegram_response_invalid`. House caps no message, so the gateway alone
+  fits one to Telegram's rich message limits, 32,768 characters and 500 blocks:
+  a rich message past them is sent as consecutive messages in order, split
+  between blocks and inside a block only when that block alone exceeds them,
+  and reported once, `delivered` with the first message's id when every part
+  was delivered and otherwise with the answer of the first part that was not.
+  Each answer also names the `threads` the bot's topics carry, a
+  `conversation_id` with its `chat_id` and `topic_id`, which is where live
+  drafts go.
+
+Live drafts come from the control stream, not from House's queue. Run on its
+own, the command holds the Environment's [control stream](#the-kit-control-stream)
+for its lease; served by `kit resident`, it receives the draft and plan frames
+the resident's socket receives, through the resident, and never opens a second
+socket. The gateway Environment's socket carries every conversation bound to a
+topic of the bot, with no subscribe frame. The gateway keeps the latest view of
+each such conversation's turn: a frame that starts at block 0 replaces a view,
+the next frame in sequence applies from its `from`, and a frame after a gap in
+the sequence, or one for a turn it holds no view of, is applied nowhere and
+answered with one `gap` frame naming the conversation and turn, so House sends
+the whole view again. It renders each view as one Telegram draft per turn with
+`sendRichMessageDraft` on the bound topic, the live plan above the assistant
+text, under one draft id derived from the turn, because Telegram shows one bot
+draft per topic and a second id would replace the first. A view past the rich
+message limits is shortened inside that one draft, never split into a second.
+A live plan is part of the draft and never a sent message; the frozen plan
+House queues at the turn's end is the turn's one plan message. Drafts coalesce
+to the latest view, one Bot API call at a time, and are never reported back:
+the same bot-wide `retry_after` gate drops a draft while it is closed, and a
+draft answered with `retry_after` closes it. A closed gate drops a preview,
+never a durable delivery.
 
 Each serve run first asks House to settle the attempts an earlier run abandoned,
 so a restarted gateway never leaves a delivery attempted forever. A Telegram

package/bootstrap.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "version": "0.1.0-alpha.28",
+  "version": "0.1.0-alpha.29",
   "hosts": {
     "linux": {
-      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.28/connect-linux.sh)",
+      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.29/connect-linux.sh)",
       "asset": {
         "name": "connect-linux.sh",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.28/connect-linux.sh"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.29/connect-linux.sh"
       },
       "workspace": {
         "argument": "--workspace",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/kit",
-  "version": "0.1.0-alpha.28",
+  "version": "0.1.0-alpha.29",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/binding.js

@@ -1,5 +1,6 @@
 import { readdir, rm } from "node:fs/promises";
 import { join } from "node:path";
+import { finalPlan, planSnapshot } from "./plan.js";
 import { KitRefusal } from "./refusal.js";
 import { readNote, writeNote } from "./state.js";
 import { reportedNote, retainedReport } from "./terminal.js";
@@ -43,6 +44,7 @@ export async function writeBinding(directory, binding) {
       : { operation: binding.sealed.operation, blocks: binding.sealed.blocks },
     stopped: stoppedNote(binding.stopped),
     reported: reported === null ? null : reportedNote(reported),
+    plan: binding.plan ?? null,
   });
 }
 
@@ -58,6 +60,12 @@ function retainedSeal(stored) {
   return { operation: stored.operation, blocks: stored.blocks };
 }
 
+function retainedPlan(stored) {
+  if (stored === null || stored === undefined) return null;
+  const plan = finalPlan(planSnapshot(stored));
+  return plan === null || JSON.stringify(plan) !== JSON.stringify(stored) ? undefined : plan;
+}
+
 function retainedFailure(stored) {
   if (stored === null) return null;
   if (typeof stored !== "object" || Array.isArray(stored)) return undefined;
@@ -96,6 +104,8 @@ function completeBinding(directory, stored) {
   if (stopped === undefined) return null;
   const reported = retainedReport(stored.reported);
   if (reported === undefined) return null;
+  const plan = retainedPlan(stored.plan);
+  if (plan === undefined) return null;
   return {
     run: stored.run,
     session: stored.session,
@@ -107,6 +117,7 @@ function completeBinding(directory, stored) {
     sealed,
     stopped,
     reported,
+    plan,
   };
 }
 

package/src/blocks.js

@@ -1,8 +1,4 @@
-import {
-  ASSISTANT_BLOCKS_MAX,
-  ASSISTANT_TABLE_COLUMNS_MAX,
-  ASSISTANT_TEXT_MAX_BYTES,
-} from "./contract.js";
+import { ASSISTANT_TABLE_COLUMNS_MAX } from "./contract.js";
 
 const HEADING = /^(#{1,6})\s+(.+)$/;
 const BULLET = /^ {0,3}[-*+]\s+(.+)$/;
@@ -132,25 +128,5 @@ export function assistantBlocks(text) {
     index += 1;
   }
   endParagraph();
-  if (blocks.length === 0) return null;
-  if (blocks.length <= ASSISTANT_BLOCKS_MAX) return blocks;
-  const whole = text.trim();
-  return whole === "" ? null : [{ type: "paragraph", text: whole }];
-}
-
-export function blocksText(blocks) {
-  return blocks
-    .map((block) => {
-      if (block.type === "formula") return block.expression;
-      if (block.type === "list") return block.items.join("\n");
-      if (block.type === "table") {
-        return [block.headers, ...block.rows].map((row) => row.join("\t")).join("\n");
-      }
-      return block.text;
-    })
-    .join("\n\n");
-}
-
-export function withinAssistantBound(text) {
-  return Buffer.byteLength(text, "utf8") <= ASSISTANT_TEXT_MAX_BYTES;
+  return blocks.length === 0 ? null : blocks;
 }

package/src/bridge.js

@@ -16,8 +16,13 @@ import {
   TURN_OUTCOMES,
 } from "./contract.js";
 import { operationId } from "./operation.js";
+import { planSnapshot } from "./plan.js";
 import { houseFailed } from "./refusal.js";
 
+function sequenced(value) {
+  return Number.isSafeInteger(value) && value > 0;
+}
+
 export function bridgedFrame(request, operation) {
   if (typeof request.method !== "string") return request;
   const params = typeof request.params === "object" && request.params !== null ? request.params : {};
@@ -50,6 +55,7 @@ export async function openBridge(options) {
     closed: false,
     questions: new Map(),
     interrupts: new Set(),
+    plan: null,
   };
   const connections = new Set();
   const clients = new Map();
@@ -201,29 +207,31 @@ export async function openBridge(options) {
       return;
     }
     if (frame.type === "draft") {
-      if (typeof frame.text === "string" && frame.text !== "") options.draft?.(frame.text);
+      if (typeof frame.text === "string" && frame.text !== "" && sequenced(frame.sequence)) {
+        options.draft?.({ text: frame.text, sequence: frame.sequence });
+      }
       return;
     }
-    if (
-      frame.type === "plan" &&
-      typeof frame.provider_turn === "string" &&
-      Array.isArray(frame.steps) &&
-      typeof frame.terminal === "boolean"
-    ) {
-      void options.plan?.({
-        provider_turn: frame.provider_turn,
-        steps: frame.steps,
-        terminal: frame.terminal,
-      });
+    if (frame.type === "plan") {
+      const snapshot = planSnapshot(frame);
+      if (snapshot === null || !sequenced(frame.sequence)) return;
+      state.plan = snapshot;
+      options.plan?.({ ...snapshot, sequence: frame.sequence });
       return;
     }
+    const carried = planSnapshot(frame.plan);
+    if (carried !== null) state.plan = carried;
     if (
       frame.type === "interrupt_applied" &&
       typeof frame.interrupt === "string" &&
       ["interrupted", "nothing_to_interrupt"].includes(frame.outcome) &&
       state.interrupts.has(frame.interrupt)
     ) {
-      const reported = options.interrupt?.(frame.interrupt, frame.outcome);
+      const reported = options.interrupt?.(
+        frame.interrupt,
+        frame.outcome,
+        frame.outcome === "interrupted" ? state.plan : null,
+      );
       if (reported === undefined) state.interrupts.delete(frame.interrupt);
       else void Promise.resolve(reported).finally(() => state.interrupts.delete(frame.interrupt));
       return;
@@ -237,6 +245,7 @@ export async function openBridge(options) {
         providerContinuation: frame.provider_continuation === true,
         providerSessionId: typeof frame.provider_session_id === "string" && frame.provider_session_id.length > 0 && frame.provider_session_id.length <= 512 ? frame.provider_session_id : null,
         stopOutcome: TURN_OUTCOMES.includes(frame.stop_outcome) ? frame.stop_outcome : null,
+        plan: carried,
       };
       return;
     }
@@ -436,6 +445,7 @@ export async function openBridge(options) {
         .filter((interaction) => interaction !== null),
     assistant: () => [...state.assistant],
     stop: () => state.stop,
+    plan: () => state.plan,
     failure: () => state.failure,
     stopRecovery: () => lifetime.abort(),
     async close() {

package/src/contract.js

@@ -1,6 +1,6 @@
 import { CLAUDE_PASTED_CODE, CODEX_DEVICE_CODE, GROK_DEVICE_CODE } from "./agent-logins.js";
 
-export const KIT_CONTRACT_VERSION = "2";
+export const KIT_CONTRACT_VERSION = "3";
 export const KIT_CAPTURE_BATCH_MAX = 100;
 export const COMMAND_INPUT_MAX_BYTES = 4 * 1024;
 export const AUTHORIZATION_OUTPUT_MAX_BYTES = 4 * 1024;
@@ -48,14 +48,8 @@ export function runRequestPath(run) {
 export const KIT_SESSIONS_REPORT_PATH = "/kit/sessions/report";
 export const KIT_SESSIONS_REPORT_MAX = 256;
 
-export const ASSISTANT_TEXT_MAX_BYTES = 4096;
-export const ASSISTANT_BLOCKS_MAX = 500;
 export const ASSISTANT_TABLE_COLUMNS_MAX = 20;
 
-export function assistantDraftsPath(workerSession) {
-  return `/kit/sessions/${encodeURIComponent(workerSession)}/drafts`;
-}
-
 export function assistantTextPath(workerSession) {
   return `/kit/sessions/${encodeURIComponent(workerSession)}/assistant-messages`;
 }
@@ -66,6 +60,8 @@ export const TELEGRAM_DELIVERY_BATCH_MAX = 10;
 export const TELEGRAM_DOWNLOAD_CEILING_BYTES = 20 * 1024 * 1024;
 export const TELEGRAM_BOT_API_TIMEOUT_MS = 30_000;
 export const TELEGRAM_GATEWAY_POLL_MS = 2_000;
+export const TELEGRAM_RICH_MESSAGE_CHARACTERS_MAX = 32_768;
+export const TELEGRAM_RICH_MESSAGE_BLOCKS_MAX = 500;
 export const TELEGRAM_CONTROL_KEYBOARD_COMMANDS = ["/stop", "/kill"];
 export const TELEGRAM_MEDIA_KINDS = [
   "document",

package/src/draft.js

@@ -1,89 +1,11 @@
-import { assistantBlocks, blocksText, withinAssistantBound } from "./blocks.js";
-
-const DRAFT_INTERVAL_MS = 500;
+import { pacedLatest } from "./pacing.js";
 
 export function observedAssistantDrafts(options) {
-  const intervalMs = options.intervalMs ?? DRAFT_INTERVAL_MS;
-  const now = options.now ?? (() => Date.now());
-  let timer = null;
-  let sentAt = null;
-  let sent = null;
-  let latest = null;
-
-  function write() {
-    timer = null;
-    if (latest === null || latest === sent) return;
-    sent = latest;
-    sentAt = now();
-    options.send(sent);
-  }
-
-  function cancel() {
-    if (timer === null) return;
-    clearTimeout(timer);
-    timer = null;
-  }
-
+  const paced = pacedLatest(options);
   return {
     observe(view) {
-      if (typeof view !== "string" || view === "") return;
-      latest = view;
-      if (timer !== null) return;
-      const wait = sentAt === null ? 0 : sentAt + intervalMs - now();
-      if (wait <= 0) {
-        write();
-        return;
-      }
-      timer = setTimeout(write, wait);
-      timer.unref?.();
-    },
-    complete(view) {
-      if (typeof view !== "string" || view === "") return;
-      latest = view;
-      cancel();
-      write();
-    },
-    close: cancel,
-  };
-}
-
-export function openAssistantDrafts(options) {
-  let pending = null;
-  let sending = null;
-  let sent = null;
-  let closed = false;
-
-  function pump() {
-    if (sending !== null || pending === null) return;
-    const view = pending;
-    pending = null;
-    sent = view.text;
-    let started;
-    try {
-      started = Promise.resolve(options.send(view.blocks));
-    } catch {
-      started = Promise.resolve();
-    }
-    sending = started
-      .catch(() => undefined)
-      .finally(() => {
-        sending = null;
-        pump();
-      });
-  }
-
-  return {
-    update(text) {
-      if (closed || typeof text !== "string" || text === "") return;
-      if (text === sent || text === pending?.text) return;
-      const blocks = assistantBlocks(text);
-      if (blocks === null || !withinAssistantBound(blocksText(blocks))) return;
-      pending = { text, blocks };
-      pump();
-    },
-    close() {
-      closed = true;
-      pump();
+      if (typeof view === "string" && view !== "") paced.observe(view);
     },
+    close: paced.close,
   };
 }