@agentshouse/kit 0.1.0-alpha.21 → 0.1.0-alpha.23

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.21/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.23/connect-linux.sh)
 ```
 
 The release asset pins one immutable multi-architecture image digest. It creates
@@ -142,11 +142,18 @@ which the User wrote once this adoption's proof had passed. The adapter
 packages themselves are Environment prerequisites, not Kit dependencies, and
 carry no record.
 
-The bootstrap invokes bare `kit login`. The first login names its new
+The bootstrap invokes bare `kit login`, which connects to `https://agents.house`;
+`--house <origin>` names another House. Login records the House in Kit home
+beside the credential. Every House-bound command talks to that recorded House,
+and every command but login refuses `--house` as an unknown argument. The first login names its new
 Environment after the host computer and stores its Environment id in Kit home;
-an explicit later login reconnects that retained id. `--environment <uuid>`
-selects a different retained Environment for explicit recovery. A malformed
-id or an answer naming a different Environment is refused before installation.
+the panel renames it. An explicit later login reconnects that retained id, and
+`--environment <uuid>` reconnects the Environment it names instead, whether or
+not Kit home records one, and Kit home then records that id. Reconnecting issues the next credential for the same Environment
+and ends the previous one, including one `envs/revoke` ended; House refuses an
+Environment it no longer holds with its cause and never creates a replacement.
+A malformed id or an answer naming a different Environment is refused before
+installation.
 
 Use `--manual` when the browser cannot reach the Kit's loopback listener. The
 command stores the issued Kit User credential in `$HOUSE_KIT_HOME/credential`
@@ -253,7 +260,7 @@ and the batch it produces, and the lease has to outlive both.
 Apply the declared source state to House:
 
 ```sh
-kit apply --house https://agents.house
+kit apply
 ```
 
 Only the state House declares - instances, services, `source_ref`, and Room
@@ -442,7 +449,7 @@ its owner asks it to renew what the Environment holds. The Kit acts on the
 request it acquires, never on its own:
 
 ```sh
-kit setup --house https://agents.house
+kit setup
 ```
 
 `kit worker run` performs the same step at the start of a pass, before it
@@ -558,7 +565,7 @@ command returns exactly one JSON object such as `{ "authorized": true }`.
 ## The Worker runtime
 
 ```sh
-kit worker run --house https://agents.house
+kit worker run
 ```
 
 Worker-runtime readiness validates the tmux this Kit declares support for,
@@ -1112,8 +1119,8 @@ into the evidence each spec writes under `tmp/delivery-evidence/`.
 ## Capturing
 
 ```sh
-kit source capture acme --house https://agents.house        # every declared service
-kit source capture acme notes --house https://agents.house  # one service
+kit source capture acme        # every declared service
+kit source capture acme notes  # one service
 ```
 
 Each run reads the checkpoint, acquires one bounded page, submits one batch,
@@ -1146,8 +1153,8 @@ Room and Record and exits non-zero while any stays unsaved; acquisition health
 stays about acquisition, so a failed save never changes it.
 
 ```sh
-kit source retry-files acme --house https://agents.house        # every declared service
-kit source retry-files acme notes --house https://agents.house  # one service
+kit source retry-files acme        # every declared service
+kit source retry-files acme notes  # one service
 ```
 
 `retry-files` saves only the references still outstanding. It runs no connector,
@@ -1203,8 +1210,7 @@ Git credential:
 ```sh
 kit repository capture /srv/acme \
   --room work-room \
-  --source-handle acme-repository \
-  --house https://agents.house
+  --source-handle acme-repository
 ```
 
 The command runs ordinary `git pull` in the checkout with the local User's Git
@@ -1306,6 +1312,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
@@ -1387,13 +1406,12 @@ beside `library/**`.
 
 ```sh
 kit sync bootstrap ./replica \
-  --house https://agents.house \
   --prefix /rooms/work/library \
   --prefix /rooms/work/capture \
   --prefix /private/library
-kit sync pull ./replica --house https://agents.house
-kit sync submit ./replica --house https://agents.house --changes ./changes.json
-kit sync rebootstrap ./replica --house https://agents.house
+kit sync pull ./replica
+kit sync submit ./replica --changes ./changes.json
+kit sync rebootstrap ./replica
 ```
 
 `bootstrap` writes `ROOM.md`, Library text, House-derived projections, and
@@ -1456,16 +1474,13 @@ absolute paths.
 
 ```sh
 kit attachment upload ./notes.bin \
-  --house https://agents.house \
   --room room:work \
   --media-type application/pdf
 
 kit attachment upload ./notes.bin \
-  --house https://agents.house \
   --private
 
 kit attachment get \
-  --house https://agents.house \
   --attachment at_1x.q \
   --room room:work \
   --output ./notes.bin
@@ -1511,7 +1526,7 @@ Any missing prerequisite refuses the create before House ever presents the
 workspace as constrained, naming the exact missing piece.
 
 ```sh
-kit workspace host --house https://agents.house
+kit workspace host
 ```
 
 The command acquires this host's workspace work under its Environment control
@@ -1566,7 +1581,7 @@ image from the original the Session stored.
 Bind the bot to this Environment:
 
 ```sh
-kit telegram connect --house https://agents.house
+kit telegram connect
 ```
 
 The command asks for the token on a hidden terminal prompt, or reads one line
@@ -1585,7 +1600,7 @@ proven owner's Telegram user id.
 Run the gateway:
 
 ```sh
-kit telegram serve --house https://agents.house
+kit telegram serve
 ```
 
 The command holds one Environment control lease for the whole run and performs
@@ -1631,7 +1646,7 @@ command is resident and stops on SIGINT or SIGTERM, printing what it settled.
 Release the bot:
 
 ```sh
-kit telegram disconnect --house https://agents.house
+kit telegram disconnect
 ```
 
 The command writes a local disconnect marker first, deletes the webhook, removes
@@ -1677,8 +1692,8 @@ Disabling a service or an instance leaves its state in place, so re-enabling
 resumes from the stored cursor instead of importing again.
 
 ```sh
-kit source reset acme --house https://agents.house        # every service
-kit source reset acme notes --house https://agents.house  # one service
+kit source reset acme        # every service
+kit source reset acme notes  # one service
 ```
 
 Reset is the only deletion of captured state. It removes the named checkpoints
@@ -1715,7 +1730,7 @@ refused rather than read as no limit. A ceiling is a shared ceiling, never a
 reservation, and House infers no supported Agent count from any of these values.
 
 ```sh
-kit host report --house https://agents.house
+kit host report
 ```
 
 The command reads `/proc/stat` twice a second apart, reads `/proc/meminfo`, and
@@ -1737,7 +1752,7 @@ Description=Report measured host capacity to House
 [Service]
 Type=oneshot
 User=house-kit
-ExecStart=/usr/bin/kit host report --house https://agents.house
+ExecStart=/usr/bin/kit host report
 ```
 
 ```
@@ -1786,11 +1801,10 @@ manifest, URLs, or attachments.
 
 ```sh
 kit migrate emit my-import --package /home/ada/exports/project
-kit migrate mount /home/ada/exports/project --house https://agents.house \
-  --subtree /rooms/work/library/project
+kit migrate mount /home/ada/exports/project --subtree /rooms/work/library/project
 # Or emit and mount in one maintained mount session:
 kit migrate run my-import --package /home/ada/exports/another-project \
-  --house https://agents.house --subtree /private/library/another-project
+  --subtree /private/library/another-project
 ```
 
 Emission refuses an existing output directory. The module reads one JSON line
@@ -1877,8 +1891,8 @@ leaves the pending mounted report plus the local outcomes. Re-migration is
 explicit unmount followed by mount.
 
 ```sh
-kit migrate unmount /rooms/work/library/project --house https://agents.house
-kit migrate unmount /rooms/work/library/project --house https://agents.house \
+kit migrate unmount /rooms/work/library/project
+kit migrate unmount /rooms/work/library/project \
   --confirm /rooms/work/library/project
 ```
 

package/bin/connect-linux.sh

@@ -39,7 +39,7 @@ login_kit() {
 }
 
 start_resident() {
-  docker run -d --name "$NAME" --restart unless-stopped --user "$(id -u):$(id -g)" --mount "$KIT_HOME_MOUNT" --mount "$WORKSPACE_MOUNT" --label "agentshouse.house=$HOUSE" --env HOME=/kit-home --env HOUSE_KIT_HOME=/kit-home --env HOUSE_KIT_CONTAINER=1 "$IMAGE" resident --house "$HOUSE" >/dev/null
+  docker run -d --name "$NAME" --restart unless-stopped --user "$(id -u):$(id -g)" --mount "$KIT_HOME_MOUNT" --mount "$WORKSPACE_MOUNT" --label "agentshouse.house=$HOUSE" --env HOME=/kit-home --env HOUSE_KIT_HOME=/kit-home --env HOUSE_KIT_CONTAINER=1 "$IMAGE" resident >/dev/null
 }
 
 if [[ "${1:-}" == kit || "${1:-}" == house ]]; then
@@ -168,7 +168,7 @@ if docker container inspect "$NAME" >/dev/null 2>&1; then
     printf 'House Kit updated for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
     exit 0
   fi
-  "${DOCKER_RUN[@]}" credential check --house "$HOUSE"
+  "${DOCKER_RUN[@]}" credential check
   if [[ "$(docker inspect --format '{{.State.Running}}' "$NAME")" == true ]]; then
     printf 'House Kit is already running for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
   else
@@ -185,15 +185,14 @@ if [[ ! -f "$KIT_HOME/kit.json" ]]; then
 fi
 
 if [[ -f "$KIT_HOME/credential" ]]; then
-  "${DOCKER_RUN[@]}" credential check --house "$HOUSE"
+  "${DOCKER_RUN[@]}" credential check
 else
-  if ((MANUAL)); then
-    login_kit --house "$HOUSE" --manual
-  else
-    login_kit --house "$HOUSE"
-  fi
+  LOGIN=()
+  if ((HOUSE_SELECTED)); then LOGIN+=(--house "$HOUSE"); fi
+  if ((MANUAL)); then LOGIN+=(--manual); fi
+  login_kit "${LOGIN[@]}"
 fi
 
-"${DOCKER_RUN[@]}" apply --house "$HOUSE"
+"${DOCKER_RUN[@]}" apply
 start_resident
 printf 'House Kit connected for Environment %s.\n' "$(cat "$KIT_HOME/environment")"

package/bin/kit.js

@@ -2,7 +2,7 @@
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { connectHouse, storedEnvironment, storedHouse } from "../src/login.js";
+import { connectHouse, loginHouse, storedEnvironment, storedHouse } from "../src/login.js";
 import { apply } from "../src/apply.js";
 import { captureSource, resetSource, retrySourceOriginals, sourceStatus } from "../src/source.js";
 import { setupEnvironment } from "../src/setup.js";
@@ -32,44 +32,44 @@ const USAGE =
   "usage: kit <login|resident|credential|setup|apply|agents|source|repository|worker|sync|migrate|attachment|host|workspace|telegram> ...";
 const LOGIN_USAGE =
   "usage: kit login [--house <url>] [--environment <uuid>] [--manual|--host-browser]";
-const HOST_USAGE = "usage: kit host report [--house <url>] [--config <path>]";
+const HOST_USAGE = "usage: kit host report [--config <path>]";
 const AGENTS_USAGE =
-  "usage: kit agents update [--house <url>] [--config <path>] | kit agents sign-in <kind> [--house <url>] [--config <path>]";
-const WORKSPACE_USAGE = "usage: kit workspace host [--house <url>] [--config <path>] [--passes <count>]";
+  "usage: kit agents update [--config <path>] | kit agents sign-in <kind> [--config <path>]";
+const WORKSPACE_USAGE = "usage: kit workspace host [--config <path>] [--passes <count>]";
 const SOURCE_USAGE =
-  "usage: kit source <capture|reset|retry-files> <instance> [service] [--house <url>] [--config <path>]\n" +
+  "usage: kit source <capture|reset|retry-files> <instance> [service] [--config <path>]\n" +
   "       kit source status <instance> [service] [--config <path>]\n" +
   "       kit source sign-in <instance> [--config <path>]";
-const SETUP_USAGE = "usage: kit setup [--house <url>] [--config <path>]";
+const SETUP_USAGE = "usage: kit setup [--config <path>]";
 const REPOSITORY_USAGE =
-  "usage: kit repository capture <checkout> --room <room> --source-handle <handle> [--house <url>]";
+  "usage: kit repository capture <checkout> --room <room> --source-handle <handle>";
 const WORKER_USAGE =
-  "usage: kit worker run [--house <url>] [--config <path>] | kit worker attach [<session>]";
+  "usage: kit worker run [--config <path>] | kit worker attach [<session>]";
 const SYNC_USAGE =
   "usage: kit sync <bootstrap|pull|rebootstrap|submit> ...";
 const SYNC_BOOTSTRAP_USAGE =
-  "usage: kit sync bootstrap <directory> [--house <url>] --prefix <path> [--prefix <path> ...]";
-const SYNC_PULL_USAGE = "usage: kit sync pull <directory> [--house <url>]";
-const SYNC_REBOOTSTRAP_USAGE = "usage: kit sync rebootstrap <directory> [--house <url>]";
+  "usage: kit sync bootstrap <directory> --prefix <path> [--prefix <path> ...]";
+const SYNC_PULL_USAGE = "usage: kit sync pull <directory>";
+const SYNC_REBOOTSTRAP_USAGE = "usage: kit sync rebootstrap <directory>";
 const SYNC_SUBMIT_USAGE =
-  "usage: kit sync submit <directory> [--house <url>] [--changes <path>]";
+  "usage: kit sync submit <directory> [--changes <path>]";
 const MIGRATE_USAGE = "usage: kit migrate <emit|mount|unmount|run> ...";
 const MIGRATE_EMIT_USAGE =
   "usage: kit migrate emit <migrator> --package <directory> [--config <path>]";
 const MIGRATE_MOUNT_USAGE =
-  "usage: kit migrate mount <package> [--house <url>] --subtree <path>";
+  "usage: kit migrate mount <package> --subtree <path>";
 const MIGRATE_UNMOUNT_USAGE =
-  "usage: kit migrate unmount <subtree> [--house <url>] [--confirm <subtree>]";
+  "usage: kit migrate unmount <subtree> [--confirm <subtree>]";
 const MIGRATE_RUN_USAGE =
-  "usage: kit migrate run <migrator> [--house <url>] --subtree <path> --package <directory> [--config <path>]";
+  "usage: kit migrate run <migrator> --subtree <path> --package <directory> [--config <path>]";
 const ATTACHMENT_USAGE = "usage: kit attachment <upload|get> ...";
 const ATTACHMENT_UPLOAD_USAGE =
-  "usage: kit attachment upload <file> [--house <url>] (--room <ref> | --private) [--name <name>] [--media-type <type>]";
+  "usage: kit attachment upload <file> (--room <ref> | --private) [--name <name>] [--media-type <type>]";
 const ATTACHMENT_GET_USAGE =
-  "usage: kit attachment get [--house <url>] --attachment <at_ref> (--room <ref> | --private) [--output <path>]";
+  "usage: kit attachment get --attachment <at_ref> (--room <ref> | --private) [--output <path>]";
 const TELEGRAM_USAGE =
-  "usage: kit telegram <connect|disconnect> [--house <url>]\n" +
-  "       kit telegram serve [--house <url>] [--passes <count>]";
+  "usage: kit telegram <connect|disconnect>\n" +
+  "       kit telegram serve [--passes <count>]";
 
 function declared(argv, accepted, positionals, options = {}) {
   const repeated = options.repeated ?? [];
@@ -115,14 +115,10 @@ function builtGoogleOAuthClient() {
   return GOOGLE_OAUTH_CLIENT;
 }
 
-async function selectedHouse(values, directory) {
-  return storedHouse(directory, false, values["--house"]);
-}
-
 async function runLogin(args, directory) {
   const { values } = declared(args, ["--house", "--manual", "--host-browser", "--environment"], 0, { flags: ["--host-browser"] });
   if (values["--manual"] && values["--host-browser"]) throw new Error(LOGIN_USAGE);
-  const house = await storedHouse(directory, true, values["--house"]);
+  const house = await loginHouse(directory, values["--house"]);
   const presentation = values["--manual"] === true ? "manual" : "loopback";
   await connectHouse({
     house,
@@ -135,9 +131,9 @@ async function runLogin(args, directory) {
 }
 
 async function runCredentialCheck(args, directory) {
-  const { values } = declared(args, ["--house"], 0, { exact: true });
+  declared(args, [], 0, { exact: true });
   if (await storedEnvironment(directory) === null) throw new KitRefusal("kit_environment_invalid", "no enrolled Environment id");
-  const house = await selectedHouse(values, directory);
+  const house = await storedHouse(directory);
   let session;
   try {
     session = await openSession({ house, directory, acquire: true });
@@ -153,8 +149,8 @@ async function runCredentialCheck(args, directory) {
 }
 
 async function runResidentCommand(args, directory) {
-  const { values } = declared(args, ["--house", "--config"], 0, { exact: true });
-  const house = await selectedHouse(values, directory);
+  const { values } = declared(args, ["--config"], 0, { exact: true });
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   const stop = () => cancellation.abort();
   process.once("SIGINT", stop);
@@ -185,9 +181,8 @@ async function runResidentDrain(args, directory) {
 }
 
 async function runSetup(args, directory) {
-  const { values } = declared(args, ["--house", "--config"], 0, { exact: true });
-  const house = await selectedHouse(values, directory);
-  if (!house) throw new Error(SETUP_USAGE);
+  const { values } = declared(args, ["--config"], 0, { exact: true });
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   const cancel = () => cancellation.abort();
   process.once("SIGINT", cancel);
@@ -240,9 +235,8 @@ async function runSourceSignIn(args, directory) {
 }
 
 async function runApply(args, directory) {
-  const { values } = declared(args, ["--house", "--config"], 0);
-  const house = await selectedHouse(values, directory);
-  if (!house) throw new Error("usage: kit apply --house <url> [--config <path>]");
+  const { values } = declared(args, ["--config"], 0);
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   const cancel = () => cancellation.abort();
   process.once("SIGINT", cancel);
@@ -269,9 +263,9 @@ async function runApply(args, directory) {
 }
 
 async function runSourceCapture(args, directory) {
-  const { values, rest } = declared(args, ["--house", "--config"], 2);
-  const house = await selectedHouse(values, directory);
-  if (!house || rest.length === 0) throw new Error(SOURCE_USAGE);
+  const { values, rest } = declared(args, ["--config"], 2);
+  if (rest.length === 0) throw new Error(SOURCE_USAGE);
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   process.once("SIGINT", () => cancellation.abort());
   const result = await captureSource(
@@ -314,9 +308,9 @@ function writeSourceOriginals(instance, service) {
 }
 
 async function runSourceRetryFiles(args, directory) {
-  const { values, rest } = declared(args, ["--house", "--config"], 2);
-  const house = await selectedHouse(values, directory);
-  if (!house || rest.length === 0) throw new Error(SOURCE_USAGE);
+  const { values, rest } = declared(args, ["--config"], 2);
+  if (rest.length === 0) throw new Error(SOURCE_USAGE);
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   process.once("SIGINT", () => cancellation.abort());
   const result = await retrySourceOriginals({
@@ -359,9 +353,9 @@ async function runSourceStatus(args, directory) {
 }
 
 async function runSourceReset(args, directory) {
-  const { values, rest } = declared(args, ["--house", "--config"], 2);
-  const house = await selectedHouse(values, directory);
-  if (!house || rest.length === 0) throw new Error(SOURCE_USAGE);
+  const { values, rest } = declared(args, ["--config"], 2);
+  if (rest.length === 0) throw new Error(SOURCE_USAGE);
+  const house = await storedHouse(directory);
   const result = await resetSource({
     house,
     directory,
@@ -377,11 +371,11 @@ async function runSourceReset(args, directory) {
 }
 
 async function runRepositoryCapture(args, directory) {
-  const { values, rest } = declared(args, ["--house", "--room", "--source-handle"], 1);
-  const house = await selectedHouse(values, directory);
+  const { values, rest } = declared(args, ["--room", "--source-handle"], 1);
   const room = values["--room"];
   const sourceHandle = values["--source-handle"];
-  if (!house || !room || !sourceHandle || rest.length !== 1) throw new Error(REPOSITORY_USAGE);
+  if (!room || !sourceHandle || rest.length !== 1) throw new Error(REPOSITORY_USAGE);
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   const cancel = () => cancellation.abort();
   process.once("SIGINT", cancel);
@@ -429,9 +423,8 @@ function writeConversationFiles(supervised) {
 }
 
 async function runWorkerRun(args, directory) {
-  const { values } = declared(args, ["--house", "--config"], 0);
-  const house = await selectedHouse(values, directory);
-  if (!house) throw new Error(WORKER_USAGE);
+  const { values } = declared(args, ["--config"], 0);
+  const house = await storedHouse(directory);
   const supervised = await runWorkers(
     {
       house,
@@ -500,12 +493,12 @@ function syncCancellation() {
 }
 
 async function runSyncBootstrap(args, directory) {
-  const { values, lists, rest } = declared(args, ["--house", "--prefix"], 1, {
+  const { lists, rest } = declared(args, ["--prefix"], 1, {
     repeated: ["--prefix"],
     exact: true,
   });
-  const house = await selectedHouse(values, directory);
-  if (!house || lists["--prefix"].length === 0) throw new Error(SYNC_BOOTSTRAP_USAGE);
+  if (lists["--prefix"].length === 0) throw new Error(SYNC_BOOTSTRAP_USAGE);
+  const house = await storedHouse(directory);
   const run = syncCancellation();
   try {
     const result = await bootstrap({
@@ -524,9 +517,8 @@ async function runSyncBootstrap(args, directory) {
 }
 
 async function runSyncPull(args, directory) {
-  const { values, rest } = declared(args, ["--house"], 1, { exact: true });
-  const house = await selectedHouse(values, directory);
-  if (!house) throw new Error(SYNC_PULL_USAGE);
+  const { rest } = declared(args, [], 1, { exact: true });
+  const house = await storedHouse(directory);
   const run = syncCancellation();
   try {
     const result = await pull({
@@ -544,9 +536,8 @@ async function runSyncPull(args, directory) {
 }
 
 async function runSyncRebootstrap(args, directory) {
-  const { values, rest } = declared(args, ["--house"], 1, { exact: true });
-  const house = await selectedHouse(values, directory);
-  if (!house) throw new Error(SYNC_REBOOTSTRAP_USAGE);
+  const { rest } = declared(args, [], 1, { exact: true });
+  const house = await storedHouse(directory);
   const run = syncCancellation();
   try {
     const result = await rebootstrap({
@@ -571,9 +562,8 @@ async function readChanges(path) {
 }
 
 async function runSyncSubmit(args, directory) {
-  const { values, rest } = declared(args, ["--house", "--changes"], 1, { exact: true });
-  const house = await selectedHouse(values, directory);
-  if (!house) throw new Error(SYNC_SUBMIT_USAGE);
+  const { values, rest } = declared(args, ["--changes"], 1, { exact: true });
+  const house = await storedHouse(directory);
   const run = syncCancellation();
   try {
     const result = await submit({
@@ -646,11 +636,11 @@ async function mountEmitted(packagePath, options, run) {
 }
 
 async function runMigrateMount(args, directory) {
-  const { values, rest } = declared(args, ["--house", "--subtree"], 1, { exact: true });
-  const house = await selectedHouse(values, directory);
-  if (!house || rest.length !== 1 || values["--subtree"] === undefined) {
+  const { values, rest } = declared(args, ["--subtree"], 1, { exact: true });
+  if (rest.length !== 1 || values["--subtree"] === undefined) {
     throw new Error(MIGRATE_MOUNT_USAGE);
   }
+  const house = await storedHouse(directory);
   const run = migrateCancellation();
   try {
     await mountEmitted(rest[0], { house, directory, subtree: values["--subtree"] }, run);
@@ -660,18 +650,17 @@ async function runMigrateMount(args, directory) {
 }
 
 async function runMigrateRun(args, directory) {
-  const { values, rest } = declared(args, ["--house", "--subtree", "--package", "--config"], 1, {
+  const { values, rest } = declared(args, ["--subtree", "--package", "--config"], 1, {
     exact: true,
   });
-  const house = await selectedHouse(values, directory);
   if (
-    !house ||
     rest.length !== 1 ||
     values["--subtree"] === undefined ||
     values["--package"] === undefined
   ) {
     throw new Error(MIGRATE_RUN_USAGE);
   }
+  const house = await storedHouse(directory);
   const run = migrateCancellation();
   try {
     const emitted = await emitPackage(
@@ -688,9 +677,9 @@ async function runMigrateRun(args, directory) {
 }
 
 async function runMigrateUnmount(args, directory) {
-  const { values, rest } = declared(args, ["--house", "--confirm"], 1, { exact: true });
-  const house = await selectedHouse(values, directory);
-  if (!house || rest.length !== 1) throw new Error(MIGRATE_UNMOUNT_USAGE);
+  const { values, rest } = declared(args, ["--confirm"], 1, { exact: true });
+  if (rest.length !== 1) throw new Error(MIGRATE_UNMOUNT_USAGE);
+  const house = await storedHouse(directory);
   const run = migrateCancellation();
   try {
     const result = await unmountSubtree({
@@ -746,12 +735,12 @@ function attachmentCancellation() {
 async function runAttachmentUpload(args, directory) {
   const { values, rest } = declared(
     args,
-    ["--house", "--room", "--private", "--name", "--media-type"],
+    ["--room", "--private", "--name", "--media-type"],
     1,
     { flags: ["--private"] },
   );
-  const house = await selectedHouse(values, directory);
-  if (!house || rest.length !== 1) throw new Error(ATTACHMENT_UPLOAD_USAGE);
+  if (rest.length !== 1) throw new Error(ATTACHMENT_UPLOAD_USAGE);
+  const house = await storedHouse(directory);
   const run = attachmentCancellation();
   try {
     const result = await uploadAttachment({
@@ -773,13 +762,13 @@ async function runAttachmentUpload(args, directory) {
 async function runAttachmentGet(args, directory) {
   const { values } = declared(
     args,
-    ["--house", "--attachment", "--room", "--private", "--output"],
+    ["--attachment", "--room", "--private", "--output"],
     0,
     { flags: ["--private"] },
   );
-  const house = await selectedHouse(values, directory);
   const attachment = values["--attachment"];
-  if (!house || !attachment) throw new Error(ATTACHMENT_GET_USAGE);
+  if (!attachment) throw new Error(ATTACHMENT_GET_USAGE);
+  const house = await storedHouse(directory);
   const run = attachmentCancellation();
   try {
     const result = await getAttachment({
@@ -805,9 +794,8 @@ async function runAttachment(args, directory) {
 }
 
 async function runHostReport(args, directory) {
-  const { values } = declared(args, ["--house", "--config"], 0, { exact: true });
-  const house = await selectedHouse(values, directory);
-  if (!house) throw new Error(HOST_USAGE);
+  const { values } = declared(args, ["--config"], 0, { exact: true });
+  const house = await storedHouse(directory);
   const observed = await reportHost({
     house,
     directory,
@@ -819,9 +807,8 @@ async function runHostReport(args, directory) {
 }
 
 async function runAgentsUpdate(args, directory) {
-  const { values } = declared(args, ["--house", "--config"], 0, { exact: true });
-  const house = await selectedHouse(values, directory);
-  if (!house) throw new Error(AGENTS_USAGE);
+  const { values } = declared(args, ["--config"], 0, { exact: true });
+  const house = await storedHouse(directory);
   const { updated } = await updateAgents({
     house,
     directory,
@@ -847,10 +834,10 @@ async function runAgentsUpdate(args, directory) {
 }
 
 async function runAgentsSignIn(args, directory) {
-  const { values, rest } = declared(args, ["--house", "--config"], 1, { exact: true });
-  const house = await selectedHouse(values, directory);
+  const { values, rest } = declared(args, ["--config"], 1, { exact: true });
   const [kind] = rest;
-  if (!house || !kind) throw new Error(AGENTS_USAGE);
+  if (!kind) throw new Error(AGENTS_USAGE);
+  const house = await storedHouse(directory);
   const { status, reported } = await signInAgent({
     house,
     directory,
@@ -867,13 +854,12 @@ async function runAgentsSignIn(args, directory) {
 }
 
 async function runWorkspaceHost(args, directory) {
-  const { values } = declared(args, ["--house", "--config", "--passes"], 0, { exact: true });
-  const house = await selectedHouse(values, directory);
-  if (!house) throw new Error(WORKSPACE_USAGE);
+  const { values } = declared(args, ["--config", "--passes"], 0, { exact: true });
   const passes = values["--passes"] === undefined ? undefined : Number(values["--passes"]);
   if (passes !== undefined && (!Number.isSafeInteger(passes) || passes < 1)) {
     throw new Error(WORKSPACE_USAGE);
   }
+  const house = await storedHouse(directory);
   const served = await serveWorkspaces({
     house,
     directory,
@@ -894,9 +880,8 @@ async function runWorkspaceHost(args, directory) {
 }
 
 async function runTelegramConnect(args, directory) {
-  const { values } = declared(args, ["--house"], 0, { exact: true });
-  const house = await selectedHouse(values, directory);
-  if (!house) throw new Error(TELEGRAM_USAGE);
+  declared(args, [], 0, { exact: true });
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   const cancel = () => cancellation.abort();
   process.once("SIGINT", cancel);
@@ -914,9 +899,8 @@ async function runTelegramConnect(args, directory) {
 }
 
 async function runTelegramDisconnect(args, directory) {
-  const { values } = declared(args, ["--house"], 0, { exact: true });
-  const house = await selectedHouse(values, directory);
-  if (!house) throw new Error(TELEGRAM_USAGE);
+  declared(args, [], 0, { exact: true });
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   const cancel = () => cancellation.abort();
   process.once("SIGINT", cancel);
@@ -936,13 +920,12 @@ async function runTelegramDisconnect(args, directory) {
 }
 
 async function runTelegramServe(args, directory) {
-  const { values } = declared(args, ["--house", "--passes"], 0, { exact: true });
-  const house = await selectedHouse(values, directory);
-  if (!house) throw new Error(TELEGRAM_USAGE);
+  const { values } = declared(args, ["--passes"], 0, { exact: true });
   const passes = values["--passes"] === undefined ? undefined : Number(values["--passes"]);
   if (passes !== undefined && (!Number.isSafeInteger(passes) || passes < 1)) {
     throw new Error(TELEGRAM_USAGE);
   }
+  const house = await storedHouse(directory);
   const cancellation = new AbortController();
   const cancel = () => cancellation.abort();
   process.once("SIGINT", cancel);

package/bootstrap.json

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

package/package.json

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

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

@@ -308,6 +308,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/login.js

@@ -14,6 +14,7 @@ import { writeText } from "./state.js";
 
 const ENVIRONMENT =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DEFAULT_HOUSE = "https://agents.house";
 
 function verifier() {
   return randomBytes(32).toString("base64url");
@@ -112,19 +113,29 @@ function houseOrigin(value) {
   return value;
 }
 
-export async function storedHouse(directory, firstLogin = false, requested = undefined) {
-  let value;
+async function recordedHouse(directory) {
   try {
-    value = (await readFile(join(directory, "house"), "utf8")).trim();
+    return (await readFile(join(directory, "house"), "utf8")).trim();
   } catch (error) {
-    if (error.code === "ENOENT") {
-      if ((firstLogin || requested !== undefined) &&
-        await storedEnvironment(directory) === null && !await storedCredentialPresent(directory)) {
-        return houseOrigin(requested ?? "https://agents.house");
-      }
-    }
+    if (error.code === "ENOENT") return null;
     throw new KitRefusal("kit_house_invalid", error.code ?? "unreadable");
   }
+}
+
+export async function storedHouse(directory) {
+  const value = await recordedHouse(directory);
+  if (value === null) throw new KitRefusal("kit_house_invalid", "ENOENT");
+  return houseOrigin(value);
+}
+
+export async function loginHouse(directory, requested) {
+  const value = await recordedHouse(directory);
+  if (value === null) {
+    if (await storedEnvironment(directory) !== null || await storedCredentialPresent(directory)) {
+      throw new KitRefusal("kit_house_invalid", "ENOENT");
+    }
+    return houseOrigin(requested ?? DEFAULT_HOUSE);
+  }
   houseOrigin(value);
   if (requested !== undefined && requested !== value) {
     throw new KitRefusal("kit_house_mismatch", "this Environment is bound to another House origin");
@@ -133,7 +144,7 @@ export async function storedHouse(directory, firstLogin = false, requested = und
 }
 
 export function enrollmentAct(options, retained, host) {
-  if (options.label !== undefined || (options.environment !== undefined && !ENVIRONMENT.test(options.environment))) {
+  if (options.environment !== undefined && !ENVIRONMENT.test(options.environment)) {
     throw new KitRefusal("kit_login_rejected", ENROLLMENT_USAGE);
   }
   const environment = options.environment ?? retained;

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 {

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);