@agentshouse/kit 0.1.0-alpha.22 → 0.1.0-alpha.24

package/README.md

@@ -10,7 +10,7 @@ On Linux `amd64` or `arm64` with a working Docker Engine, run the published,
 versioned bootstrap once:
 
 ```sh
-bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.22/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.24/connect-linux.sh)
 ```
 
 The release asset pins one immutable multi-architecture image digest. It creates
@@ -781,7 +781,18 @@ Kit reads what the Session was started for from House's
 its input, references, requester and the pinned revision's instruction, or the
 sealed conversation turn. It sends that as the first prompt block, followed by
 current House guidance fetched through the Run connection, so the Agent calls
-nothing to learn it. An unreadable request or guidance refuses the turn. It forwards only adapter-classified User-visible assistant
+nothing to learn it. An unreadable request or guidance refuses the turn.
+A session opened with `session/new` gets one more text block ahead of those,
+the same for every adapter kind: the line
+`The agents.house house CLI is available: run house --help.`, the base
+instructions of the Execution attempt plan House acquired, and the current text
+of the owner's How-we-work document `/private/library/how-we-work.md`, which the
+launcher reads with the `shell` tool over the Session's own bridge, following
+House's cursor to the whole text. An absent document, one the Session's ceiling
+cannot read, and empty base instructions add nothing. Any other failed read
+refuses the attempt as `kit_how_we_work_unreadable` with the bridge's cause
+before a prompt is sent. A session reloaded with `session/load` already holds
+the block and gets none. It forwards only adapter-classified User-visible assistant
 text back over the local channel, and leaves reasoning, tool traces, and
 terminal output where they are. The supervised process's own House calls travel
 that same channel through the `house` CLI. The Kit holds the WorkerRunToken, replaces it in place when
@@ -1312,6 +1323,19 @@ control lease when a resident runs, and which otherwise acquires and releases
 its own. A Session refuses `--owner`, and a missing bridge is never replaced by
 owner authority.
 
+A Session's edit too large for one MCP request of 4 MiB goes through House's
+`prepare_edit_upload` Command on that Session's bridge, naming every changed
+path, the byte count and the SHA-256 of the bytes to upload under the push's
+operation. Those bytes are the serialized changes, padded with trailing spaces
+to one byte over 4 MiB when only the request around them passed the bound,
+because House takes no smaller upload. Kit sends them to the upload address
+House returns and then calls `edit` with the paths and the returned upload
+instead of the changes, so House applies them as the same one edit. The upload
+is recorded in Kit home before the edit is sent, so a push whose answer was lost
+resends that same edit; when House no longer holds the uploaded bytes and has
+not applied the edit, the push uploads them again once under the same operation.
+A change set beyond House's batch bounds is refused whole and never split.
+
 Inside an Agent Session `git` is Kit's shim in front of the installed Git, and
 every command runs exactly as that Git runs it. In a copy or one of its linked
 worktrees the shim compares that worktree's index before and after each

package/bootstrap.json

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

package/package.json

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

package/src/adapter-mcp.js

@@ -1,5 +1,10 @@
-import { COMMAND_ADAPTER_INITIALIZE_TIMEOUT_MS, MCP_PROTOCOL_VERSION } from "./contract.js";
-import { bridgeCall } from "./mcp.js";
+import {
+  COMMAND_ADAPTER_INITIALIZE_TIMEOUT_MS,
+  HOW_WE_WORK_PATH,
+  MCP_PROTOCOL_VERSION,
+  SHELL_RENDER,
+} from "./contract.js";
+import { answerText, bridgeCall } from "./mcp.js";
 import { KitRefusal } from "./refusal.js";
 
 function readableDiscovery(discovery) {
@@ -29,3 +34,53 @@ export async function commandHouseInstructions(bridge) {
   }
   return frame.result.instructions;
 }
+
+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");
+}

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);
@@ -41,23 +46,27 @@ export async function transferBytes(request, dependencies = {}) {
   if (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" }
+    : {
+        [BYTE_GRANT_OPERATION_HEADER]: request.operation,
+        ...(request.method === "POST" ? { "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,
     });

package/src/contract.js

@@ -118,6 +118,10 @@ export const BRIDGE_NONCE_ENVIRONMENT = "HOUSE_KIT_BRIDGE_NONCE";
 export const BRIDGE_RECONNECT_MS = 200;
 export const BRIDGE_RECONNECT_MAX_MS = 5_000;
 
+export const HOUSE_CLI_LINE = "The agents.house house CLI is available: run house --help.";
+export const HOW_WE_WORK_PATH = "/private/library/how-we-work.md";
+export const SHELL_RENDER = "shell/1";
+
 export const ACP_PROTOCOL = 1;
 export const ACP_AUTH_REQUIRED = -32000;
 export const ADAPTER_EXIT_GRACE_MS = 2_000;
@@ -308,6 +312,8 @@ export const WORKING_COPY_PUSH_METHOD = "house/git/push";
 export const WORKING_COPY_INDEX_METHOD = "house/git/index";
 export const WORKING_COPY_PUSH_HELP =
   "Submit a Room commit to House; default HEAD. Use --owner only outside an Agent Session. Native git push is not a House remote.";
+export const WORKING_COPY_UPLOAD_COMMAND = "prepare_edit_upload";
+export const MCP_REQUEST_BODY_MAX_BYTES = 4 * 1024 * 1024;
 
 export const MIGRATOR_CONTRACT = "kit-migrator/1";
 export const MIGRATOR_CATEGORY = "migrator";

package/src/house.js

@@ -855,9 +855,13 @@ function acquiredAssignment(value, declaration) {
   if (Number.isNaN(Date.parse(expiresAt))) {
     envelope.refuse(`${declaration}.session.bridge_token_expires_at`);
   }
+  if (typeof plan.base_instructions !== "string") {
+    envelope.refuse(`${declaration}.plan.base_instructions`);
+  }
   return {
     run: envelope.text(acquired.run, `${declaration}.run`, 128),
     agentId: envelope.text(plan.agent_id, `${declaration}.plan.agent_id`, 128),
+    baseInstructions: plan.base_instructions,
     workingDirectory: envelope.text(
       plan.working_directory,
       `${declaration}.plan.working_directory`,

package/src/launcher.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { commandHouseInstructions } from "./adapter-mcp.js";
+import { commandHouseHowWeWork, commandHouseInstructions } from "./adapter-mcp.js";
 import {
   compiledContract,
   initializeCommandAdapter,
@@ -7,7 +7,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 +129,11 @@ async function configureSession(acp, contract, sessionId, adapter) {
   }
 }
 
+async function sessionOpening(bridge, baseInstructions) {
+  const parts = [HOUSE_CLI_LINE, baseInstructions, 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}`);
@@ -179,6 +184,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(bridge, start.base_instructions) : [];
     const setup = { cwd: start.working_directory, mcpServers: [] };
     if (providerSessionId === null) {
       providerSessionId = openedSession(await acp.request("session/new", setup));
@@ -196,6 +203,7 @@ async function runTurn(channel, start, bridge, turn) {
     const prompted = await acp.request("session/prompt", {
       sessionId: providerSessionId,
       prompt: [
+        ...opening,
         { type: "text", text: JSON.stringify(start.request) },
         { type: "text", text: instructions },
         ...workingCopyContext(start.working_copies),

package/src/worker.js

@@ -1,4 +1,4 @@
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
@@ -11,6 +11,7 @@ import {
 import { readBindings, removeBinding, writeBinding } from "./binding.js";
 import { readContinuation, readContinuationRuns, writeContinuation, removeContinuation } from "./continuation.js";
 import { bridgedFrame, openBridge } from "./bridge.js";
+import { transferBytes } from "./bytes.js";
 import { assistantBlocks } from "./blocks.js";
 import { retryConversationFiles } from "./conversation-originals.js";
 import { openAssistantDrafts } from "./draft.js";
@@ -25,6 +26,7 @@ import {
   ownerCaller,
   pushWorkingCopy,
   recordIndexChange,
+  uploadedPaths,
   workingCopyPaths,
 } from "./working-copy.js";
 import { readConfiguration } from "./configuration.js";
@@ -32,6 +34,7 @@ import { launchBase, readyLaunchDirectory } from "./directory.js";
 import {
   BRIDGE_NONCE_ENVIRONMENT,
   BRIDGE_SOCKET_ENVIRONMENT,
+  MCP_REQUEST_BODY_MAX_BYTES,
   PROVIDER_CONTINUATION_UNAVAILABLE,
   WORKER_COMMAND_BATCH_MAX,
   WORKER_COMMAND_POLL_MS,
@@ -42,6 +45,7 @@ import {
   WORKER_SUPERVISION_POLL_MS,
   WORKING_COPY_INDEX_METHOD,
   WORKING_COPY_PUSH_METHOD,
+  WORKING_COPY_UPLOAD_COMMAND,
 } from "./contract.js";
 import { EpochReportRequired, formatCommandError, houseFailed, KitRefusal } from "./refusal.js";
 import {
@@ -299,20 +303,61 @@ function acceptedWith(text) {
   return { refused: null, written: [...written.values()] };
 }
 
+function toolFrame(name, args, operation) {
+  return bridgedFrame({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }, operation);
+}
+
+function uploadBody(changes) {
+  const body = Buffer.from(JSON.stringify({ changes }), "utf8");
+  if (body.length > MCP_REQUEST_BODY_MAX_BYTES) return body;
+  return Buffer.concat([body, Buffer.alloc(MCP_REQUEST_BODY_MAX_BYTES + 1 - body.length, " ")]);
+}
+
 async function sessionPush(context, bound, authority, frame, signal) {
-  const edit = async (body, sent) => {
-    const answer = await callHouseMcp(
-      context.session,
-      await sessionAuthority(context.session, bound.session, authority, sent),
-      bridgedFrame(
-        { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "edit", arguments: { changes: body.changes } } },
-        body.operation_id,
-      ),
+  const call = async (sent, called) =>
+    callHouseMcp(context.session, await sessionAuthority(context.session, bound.session, authority, sent), called, sent);
+  const refused = (answer) =>
+    answer.error !== undefined
+      ? refusedWith(answer.error.message ?? "kit_house_refused")
+      : answer.result?.isError === true
+        ? refusedWith(answerText(answer.result))
+        : null;
+  const stage = async (body, sent) => {
+    const bytes = uploadBody(body.changes);
+    const sha256 = createHash("sha256").update(bytes).digest("hex");
+    const prepare = { paths: uploadedPaths(body.changes), bytes: bytes.length, sha256 };
+    const prepared = await call(
+      sent,
+      toolFrame("run_command", { command: WORKING_COPY_UPLOAD_COMMAND, arguments: prepare }, body.operation_id),
+    );
+    const refusal = refused(prepared);
+    if (refusal !== null) return refusal;
+    const transfer = answerYaml(answerText(prepared.result))?.transfer;
+    const staged = (
+      await transferBytes(
+        { url: transfer?.url, method: "POST", operation: transfer?.operation, body: bytes, framed: true, signal: sent },
+        context.session.dependencies,
+      )
+    ).transfer;
+    if (typeof staged?.url !== "string" || typeof staged.operation !== "string") {
+      throw new KitRefusal("kit_house_answer_unreadable", WORKING_COPY_UPLOAD_COMMAND);
+    }
+    return { upload: { url: staged.url, operation: staged.operation, bytes: bytes.length, sha256 } };
+  };
+  const edit = async (body, sent, retain) => {
+    let { upload } = body;
+    const inline = toolFrame("edit", { changes: body.changes }, body.operation_id);
+    if (upload === undefined && Buffer.byteLength(JSON.stringify(inline)) > MCP_REQUEST_BODY_MAX_BYTES) {
+      const staged = await stage(body, sent);
+      if (staged.upload === undefined) return staged;
+      ({ upload } = staged);
+      await retain(upload);
+    }
+    const answer = await call(
       sent,
+      upload === undefined ? inline : toolFrame("edit", { paths: uploadedPaths(body.changes), upload }, body.operation_id),
     );
-    if (answer.error !== undefined) return refusedWith(answer.error.message ?? "kit_house_refused");
-    const text = answerText(answer.result);
-    return answer.result?.isError === true ? refusedWith(text) : acceptedWith(text);
+    return refused(answer) ?? acceptedWith(answerText(answer.result));
   };
   let outcome;
   try {
@@ -530,6 +575,7 @@ async function prepareAssignment(context, assignment, resumed) {
   };
   const authority = { token: assignment.session.token, expiresAt: assignment.session.expiresAt };
   const start = {
+    base_instructions: assignment.baseInstructions,
     working_directory: assignment.workingDirectory,
     working_copies: await appliedWorkingCopies(context),
     execution_authority: context.configuration.executionAuthority,

package/src/working-copy.js

@@ -914,6 +914,10 @@ function pushedPaths(changes) {
   return new Set(changes.flatMap((change) => (change.op === "rename" ? [change.path, change.to] : [change.path])));
 }
 
+export function uploadedPaths(changes) {
+  return [...pushedPaths(changes)].sort();
+}
+
 async function enumerated(context, copy, since, signal) {
   const answer = await door(
     context.session,
@@ -1104,12 +1108,18 @@ async function expired(context, copy, text, signal) {
   return finish(context, accepted, signal);
 }
 
-async function settle(context, copy, caller, signal) {
+async function settle(context, copy, caller, signal, restaged = false) {
   const { push } = copy;
   if (!sameCaller(push.caller, caller.binding)) return orphaned(context, copy, signal);
+  let staged = push.upload !== undefined;
+  const retain = async (upload) => {
+    staged = true;
+    await writeCopy(context.directory, { ...copy, push: { ...push, upload } }, signal);
+  };
   let answer;
   try {
-    answer = await caller.submit({ operation_id: push.operation_id, changes: push.changes }, signal);
+    const { operation_id, changes, upload } = push;
+    answer = await caller.submit({ operation_id, changes, ...(upload === undefined ? {} : { upload }) }, signal, retain);
   } catch (error) {
     if (!definite(error)) {
       throw new KitRefusal("kit_working_copy_push_uncertain", "run house git push again to recover its outcome");
@@ -1118,6 +1128,12 @@ async function settle(context, copy, caller, signal) {
     answer = { refused: { code: error.code, text: formatCommandError(error), current: Array.isArray(current) ? current : null } };
   }
   const { refused } = answer;
+  if (refused?.code === "upload_unavailable" && staged && !restaged) {
+    const { upload, ...unstaged } = push;
+    const cleared = { ...copy, push: unstaged };
+    await writeCopy(context.directory, cleared, signal);
+    return settle(context, cleared, caller, signal, true);
+  }
   if (refused?.code === "operation_expired") return expired(context, copy, refused.text, signal);
   if (refused === null) {
     const pushed = pushedPaths(push.changes);