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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/kit",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.30",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -9,11 +9,16 @@
   "private": false,
   "type": "module",
   "bin": {
+    "house": "src/session-bin/house",
     "kit": "bin/kit.js"
   },
+  "exports": {
+    "./bootstrap": "./bootstrap.json"
+  },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.5.0",
-    "@agentshouse/mdmodel": "0.1.0-alpha.13",
+    "@agentshouse/mdmodel": "0.1.0-alpha.15",
+    "ws": "8.22.0",
     "yaml": "2.9.1",
     "zod": "4.6.5"
   },

package/src/adapter-mcp.js

@@ -1,7 +1,15 @@
-import { COMMAND_ADAPTER_INITIALIZE_TIMEOUT_MS, MCP_PROTOCOL_VERSION } from "./contract.js";
-import { bridgeCall } from "./mcp.js";
+import { readFileSync } from "node:fs";
+import {
+  COMMAND_ADAPTER_INITIALIZE_TIMEOUT_MS,
+  HOW_WE_WORK_PATH,
+  MCP_PROTOCOL_VERSION,
+  SHELL_RENDER,
+} from "./contract.js";
+import { answerText, bridgeCall, editRefusal } from "./mcp.js";
 import { KitRefusal } from "./refusal.js";
 
+const HOW_WE_WORK_TEXT = readFileSync(new URL("how-we-work.md", import.meta.url), "utf8");
+
 function readableDiscovery(discovery) {
   const identity = discovery?._meta?.["io.modelcontextprotocol/serverInfo"];
   return Array.isArray(discovery?.supportedVersions) &&
@@ -30,15 +38,71 @@ export async function commandHouseInstructions(bridge) {
   return frame.result.instructions;
 }
 
-export async function commandHouseRequest(bridge) {
-  const frame = await commandHouseReply(bridge, { method: "tools/call", params: { name: "session_get_request", arguments: {} } });
-  if (frame.error !== undefined || frame.result?.isError === true) throw new KitRefusal("kit_run_input_unreadable");
-  try {
-    const content = frame.result.content;
-    const input = JSON.parse(content.find((item) => item.type === "text").text);
-    if (typeof input !== "object" || input === null || Array.isArray(input)) throw new Error();
-    return input;
-  } catch {
-    throw new KitRefusal("kit_run_input_unreadable");
+function shellAnswer(text) {
+  const lines = text.split("\n");
+  if (!lines[0].startsWith(`protocol: render=${SHELL_RENDER} `)) return null;
+  const exit = Number(lines[2].slice("exit: ".length));
+  let at = lines[5]?.startsWith("authority: ") ? 6 : 5;
+  if (exit === 0) return { exit, stderr: [], stdout: lines.slice(at).join("\n"), cursor: null };
+  const stderr = [];
+  while (lines[at]?.startsWith("stderr: ")) stderr.push(lines[at++].slice("stderr: ".length));
+  const stdout = lines.slice(at);
+  const cursor = stdout.at(-1)?.startsWith("cursor: ") ? stdout.pop().slice("cursor: ".length) : null;
+  return { exit, stderr, stdout: stdout.join("\n"), cursor };
+}
+
+async function howWeWorkPage(bridge, cursor) {
+  const frame = await bridgeCall(bridge, {
+    method: "tools/call",
+    params: {
+      name: "shell",
+      arguments: { command: `cat ${HOW_WE_WORK_PATH}`, ...(cursor === null ? {} : { cursor }) },
+    },
+  });
+  if (frame.error !== undefined) {
+    throw new KitRefusal("kit_how_we_work_unreadable", frame.error.message ?? null);
+  }
+  const text = answerText(frame.result);
+  if (frame.result?.isError === true) {
+    if (text.split(":")[0] === "room_not_found") return null;
+    throw new KitRefusal("kit_how_we_work_unreadable", text);
+  }
+  const page = shellAnswer(text);
+  if (page === null) throw new KitRefusal("kit_how_we_work_unreadable", text);
+  if (page.cursor === null && page.exit !== 0) {
+    if (page.stderr.length === 1 && page.stderr[0].split(" ")[1] === "path_not_found") return null;
+    throw new KitRefusal("kit_how_we_work_unreadable", page.stderr.join("\n"));
+  }
+  return page;
+}
+
+export async function commandHouseHowWeWork(bridge) {
+  const pages = [];
+  let cursor = null;
+  do {
+    const page = await howWeWorkPage(bridge, cursor);
+    if (page === null) return "";
+    pages.push(page.stdout);
+    cursor = page.cursor;
+  } while (cursor !== null);
+  return pages.join("\n");
+}
+
+export async function commandHouseCreateHowWeWork(bridge) {
+  const frame = await bridgeCall(bridge, {
+    method: "tools/call",
+    params: {
+      name: "edit",
+      arguments: { changes: [{ op: "create", path: HOW_WE_WORK_PATH, content: HOW_WE_WORK_TEXT }] },
+    },
+  });
+  if (frame.error !== undefined) {
+    throw new KitRefusal("kit_how_we_work_unwritable", frame.error.message ?? null);
   }
+  if (frame.result?.isError !== true) return true;
+  const text = answerText(frame.result);
+  const { code, conflicts } = editRefusal(text);
+  if (code === "room_not_found" || code === "operation_denied") return false;
+  if (code === "edit_conflict" && conflicts?.some((conflict) => conflict.code === "path_exists")) return true;
+  throw new KitRefusal("kit_how_we_work_unwritable", text);
 }

package/src/agents.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { readFile, rm } from "node:fs/promises";
+import { readFile, readdir, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import {
@@ -11,6 +11,7 @@ import {
 } from "./adapter.js";
 import { inheritedEnvironment } from "./command.js";
 import {
+  ADAPTER_KINDS,
   AGENT_HOME,
   AGENT_INSTALL_TIMEOUT_MS,
   AGENT_RELEASES_HOME,
@@ -261,6 +262,60 @@ export async function updateDeclaredAgents(options, configuration, dependencies
   return updated;
 }
 
+export async function removeUndeclaredAgents(directory, wanted, keep = false) {
+  const home = join(directory, AGENT_HOME);
+  let entries;
+  try {
+    entries = await readdir(home, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  const retained = [];
+  for (const entry of entries) {
+    if (!wanted.includes(entry.name)) {
+      if (keep && ADAPTER_KINDS.includes(entry.name)) retained.push(entry.name);
+      else await rm(join(home, entry.name), { recursive: true, force: true });
+    }
+  }
+  return retained;
+}
+
+export async function reconcileAgentKinds(
+  options,
+  session,
+  configuration,
+  dependencies = {},
+  signal = session.signal,
+  state = {},
+) {
+  const selected = { ...configuration, agents: await desiredAgents(session, signal) };
+  state.onDesired?.(selected.agents);
+  const newlyWanted = selected.agents.filter((kind) => !state.lastDesired?.includes(kind));
+  const retained = await removeUndeclaredAgents(options.directory, selected.agents, state.busy);
+  const pointerKinds = state.busy
+    ? (
+        await Promise.all(
+          newlyWanted.map(async (kind) =>
+            (await readAgentState(options.directory, kind)).release === null ? kind : null,
+          ),
+        )
+      ).filter((kind) => kind !== null)
+    : newlyWanted;
+  const updated = await updateDeclaredAgents(
+    { directory: options.directory, at: dependencies.now?.(), forced: state.forced },
+    { ...selected, agents: state.pointer ? pointerKinds : selected.agents },
+    dependencies,
+  );
+  const readiness = await agentReadiness(
+    { directory: options.directory },
+    { ...selected, agents: [...selected.agents, ...retained] },
+    dependencies,
+  );
+  await reportAgentCapabilities(session, readiness.agents, signal);
+  return { selected, updated, reported: readiness.agents, refused: readiness.refused, retained };
+}
+
 export async function agentSignedIn(directory, kind, dependencies = {}) {
   const contract = compiledContract(kind);
   const state = await readAgentState(directory, kind);
@@ -341,15 +396,15 @@ export async function updateAgents(options, dependencies = {}) {
   return maintainControl(
     session,
     async (signal) => {
-      const selected = { ...configuration, agents: await desiredAgents(session, signal) };
-      const updated = await updateDeclaredAgents(
-        { directory: options.directory, at: dependencies.now?.(), forced: true },
-        selected,
+      const result = await reconcileAgentKinds(
+        options,
+        session,
+        configuration,
         dependencies,
+        signal,
+        { forced: true },
       );
-      const { agents } = await agentReadiness(options, selected, dependencies);
-      await reportAgentCapabilities(session, agents, signal);
-      return { updated, reported: agents };
+      return { updated: result.updated, reported: result.reported };
     },
     options.signal,
   );

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";
@@ -15,6 +16,18 @@ function bindingPath(directory, tmux) {
   return join(bindingDirectory(directory), `${tmux}.json`);
 }
 
+function stoppedNote(stopped) {
+  if (stopped === null || stopped === undefined) return null;
+  return {
+    turn_completed: stopped.turnCompleted,
+    capacity_exhausted: stopped.capacityExhausted,
+    provider_refused: stopped.providerRefused,
+    continuable: stopped.continuable,
+    failure: stopped.failure,
+    text_accepted: stopped.textAccepted,
+  };
+}
+
 export async function writeBinding(directory, binding) {
   const reported = binding.reported ?? null;
   await writeNote(bindingPath(directory, binding.tmux), {
@@ -29,7 +42,9 @@ export async function writeBinding(directory, binding) {
     sealed: binding.sealed === null || binding.sealed === undefined
       ? null
       : { operation: binding.sealed.operation, blocks: binding.sealed.blocks },
+    stopped: stoppedNote(binding.stopped),
     reported: reported === null ? null : reportedNote(reported),
+    plan: binding.plan ?? null,
   });
 }
 
@@ -45,6 +60,37 @@ 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;
+  if (typeof stored.code !== "string" || stored.code.length === 0) return undefined;
+  if (stored.detail !== null && typeof stored.detail !== "string") return undefined;
+  return { code: stored.code, detail: stored.detail };
+}
+
+function retainedStop(stored) {
+  if (stored === null || stored === undefined) return null;
+  if (typeof stored !== "object" || Array.isArray(stored)) return undefined;
+  const flags = ["turn_completed", "capacity_exhausted", "provider_refused", "continuable", "text_accepted"];
+  if (flags.some((flag) => typeof stored[flag] !== "boolean")) return undefined;
+  const failure = retainedFailure(stored.failure);
+  if (failure === undefined) return undefined;
+  return {
+    turnCompleted: stored.turn_completed,
+    capacityExhausted: stored.capacity_exhausted,
+    providerRefused: stored.provider_refused,
+    continuable: stored.continuable,
+    failure,
+    textAccepted: stored.text_accepted,
+  };
+}
+
 function completeBinding(directory, stored) {
   if (typeof stored !== "object" || stored === null || Array.isArray(stored)) return null;
   const named = [stored.run, stored.session, stored.tmux, stored.socket, stored.nonce];
@@ -54,8 +100,12 @@ function completeBinding(directory, stored) {
   if (stored.owner_stop !== null && typeof stored.owner_stop !== "string") return null;
   const sealed = retainedSeal(stored.sealed);
   if (sealed === undefined) return null;
+  const stopped = retainedStop(stored.stopped);
+  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,
@@ -65,7 +115,9 @@ function completeBinding(directory, stored) {
     conversation: stored.conversation === true,
     ownerStop: stored.owner_stop,
     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,9 +16,14 @@ import {
   TURN_OUTCOMES,
 } from "./contract.js";
 import { operationId } from "./operation.js";
+import { planSnapshot } from "./plan.js";
 import { houseFailed } from "./refusal.js";
 
-function bridgedFrame(request, operation) {
+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 : {};
   const declared = typeof params._meta === "object" && params._meta !== null ? params._meta : {};
@@ -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,38 +207,45 @@ 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;
     }
+    if (frame.type === "how_we_work") {
+      void options.howWeWork?.();
+      return;
+    }
     if (frame.type === "turn_ended") {
       state.stop = {
         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;
     }
@@ -432,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/bytes.js

@@ -31,6 +31,11 @@ async function downloadBody(response, signal) {
   return Buffer.concat(chunks, size);
 }
 
+function framedBody(request) {
+  if (request.method !== "POST" || !Buffer.isBuffer(request.body)) throw new KitRefusal("kit_byte_body_invalid");
+  return Buffer.concat([Buffer.from(`${request.operation}\n`, "utf8"), request.body]);
+}
+
 export async function transferBytes(request, dependencies = {}) {
   if (request.method !== "GET" && request.method !== "POST") {
     throw new KitRefusal("kit_byte_method_invalid", request.method);
@@ -38,26 +43,32 @@ export async function transferBytes(request, dependencies = {}) {
   if (typeof request.url !== "string" || request.url.length === 0) {
     throw new KitRefusal("kit_byte_url_invalid");
   }
-  if (typeof request.operation !== "string" || request.operation.length === 0) {
+  if (request.method === "POST" && (typeof request.operation !== "string" || request.operation.length === 0)) {
     throw new KitRefusal("kit_byte_operation_invalid");
   }
+  const framed = request.framed === true;
+  const body = framed ? framedBody(request) : request.body;
   if (request.method === "POST") {
-    if (!Buffer.isBuffer(request.body)) throw new KitRefusal("kit_byte_body_invalid");
-    if (request.body.length > BYTE_GRANT_POST_BYTES_MAX) {
+    if (!Buffer.isBuffer(body)) throw new KitRefusal("kit_byte_body_invalid");
+    if (body.length > BYTE_GRANT_POST_BYTES_MAX) {
       throw new KitRefusal("original_bytes_exceeded");
     }
   }
   const fetcher = dependencies.fetch ?? fetch;
-  const headers = {
-    [BYTE_GRANT_OPERATION_HEADER]: request.operation,
-  };
-  if (request.method === "POST") headers["content-type"] = "application/octet-stream";
+  const headers = framed
+    ? { "content-type": "text/plain; charset=utf-8" }
+    : request.method === "POST"
+      ? {
+          [BYTE_GRANT_OPERATION_HEADER]: request.operation,
+          "content-type": "application/octet-stream",
+        }
+      : {};
   let response;
   try {
     response = await fetcher(request.url, {
       method: request.method,
       headers,
-      body: request.method === "POST" ? request.body : undefined,
+      body: request.method === "POST" ? body : undefined,
       redirect: "manual",
       signal: request.signal,
     });