@agentshouse/kit 0.2.1-c3fc787e93f0e → 0.2.1-c4823db4ff116

package/README.md

@@ -41,7 +41,8 @@ House as you and `git` clones and pushes your Apps at `<house>/app/` as you, unt
 that connection on Connections. `house help` lists the Tools. Codex sessions started after a
 login run a lone `house` command outside their sandbox. `kit logout` disconnects this
 computer, stops House Kit and ends your own agent's connection, so `house` and `git` no
-longer act as you here; a later `kit login` reconnects the same Environment.
+longer act as you here; a later `kit login` reconnects the same Environment, or connects
+this computer as a new one when House no longer holds it.
 In a container you do not control, such as ChatGPT's, `npm i -g @agentshouse/kit` and `kit chatgpt --key <key>` with a key made on Connections let `house <tool>` act as you, starting and configuring nothing else.
 
 `kit resident` keeps the Environment connected and, as it connects, copies the text of each Room

package/dist/agents.js

@@ -1,5 +1,6 @@
 import { client } from '@agentclientprotocol/sdk';
 import { readFile, realpath } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
 import { startAdapter } from './acp.js';
 import { CLIS, KIT_VERSION, below, installAdapter, installCli, locate, run, versionOf } from './clis.js';
 import { agentBase, kitHome } from './home.js';
@@ -7,6 +8,8 @@ import { updatesItself } from './placement.js';
 import { killTree } from './scope.js';
 import { holdTranscription, transcriptionReport } from './transcription.js';
 import { KIT_WIRE } from './wire.js';
+// Two quiet seconds let a fresh conversation start before background model discovery competes for its CPU.
+const MODEL_PROBE_QUIET_MS = 2_000;
 const SIGNED_OUT = { signed_in: false, models: [], modes: [] };
 function select(options, category) {
     const option = options.find((candidate) => candidate.category === category);
@@ -24,6 +27,22 @@ function causeOf(error) {
 function logged(error) {
     process.stderr.write(`kit: ${causeOf(error)}\n`);
 }
+const LAPTOP_CHASSIS = new Set(['8', '9', '10', '14', '30', '31', '32']);
+const DESKTOP_CHASSIS = new Set(['3', '4', '5', '6', '7', '15', '16']);
+const SERVER_CHASSIS = new Set(['17', '18', '19', '20', '21', '22', '23', '24']);
+export function chassisForm(value) {
+    const chassis = value.trim();
+    if (LAPTOP_CHASSIS.has(chassis))
+        return 'laptop';
+    if (DESKTOP_CHASSIS.has(chassis))
+        return 'desktop';
+    if (SERVER_CHASSIS.has(chassis))
+        return 'server';
+    return undefined;
+}
+export function hostVm(version) {
+    return /docker desktop|microsoft|wsl|linuxkit/i.test(version);
+}
 async function models(kind, adapter, known) {
     const agent = adapter.connection.agent;
     const opened = await agent.request('session/new', { cwd: kitHome(), mcpServers: [] });
@@ -122,6 +141,22 @@ async function operatingSystem() {
     const release = await readFile('/etc/os-release', 'utf8');
     return /^PRETTY_NAME="?([^"\n]*)"?$/m.exec(release)?.[1] ?? release;
 }
+async function hostForm() {
+    if (process.platform === 'darwin') {
+        const battery = await run('pmset', ['-g', 'batt'], 10_000);
+        return battery.status === 0 && battery.output.includes('InternalBattery') ? 'laptop' : 'desktop';
+    }
+    if (process.platform !== 'linux')
+        return undefined;
+    const [container, version, chassis] = await Promise.all([
+        readFile('/.dockerenv', 'utf8').then(() => true).catch(() => false),
+        readFile('/proc/version', 'utf8').catch(() => ''),
+        readFile('/sys/class/dmi/id/chassis_type', 'utf8').catch(() => ''),
+    ]);
+    if (container && hostVm(version))
+        return undefined;
+    return chassisForm(chassis);
+}
 export class Agents {
     desired = { agents: [], routes: [], transcribe: false };
     house;
@@ -130,6 +165,7 @@ export class Agents {
     installing = Promise.resolve();
     readings = new Map();
     reads = new Map();
+    starts = 0;
     sending = Promise.resolve();
     sent = null;
     refreshing = 0;
@@ -172,6 +208,7 @@ export class Agents {
         return reading.then(() => undefined);
     }
     cli(kind) {
+        this.starts += 1;
         return this.queue(kind, async () => {
             const resolved = await this.resolve(kind);
             if (!('cli' in resolved)) {
@@ -185,7 +222,7 @@ export class Agents {
                 this.update(kind, { release, failure: null, signed_in: kept.signed_in, models: kept.models, modes: kept.modes });
             }
             const read = this.nextRead(kind);
-            offer(kind, cli, kept)
+            this.quietOffer(kind, cli, kept)
                 .then((offered) => {
                 const current = this.readings.get(kind);
                 if (this.reads.get(kind) === read && current?.release === release)
@@ -272,11 +309,19 @@ export class Agents {
         if (this.reads.get(kind) === current && !signal?.aborted)
             this.readings.set(kind, reading);
     }
+    async quietOffer(kind, cli, known) {
+        for (let seen = -1; seen !== this.starts;) {
+            seen = this.starts;
+            await delay(MODEL_PROBE_QUIET_MS);
+        }
+        return offer(kind, cli, known);
+    }
     async load(kind) {
         const known = this.readings.get(kind);
         if (known !== undefined && known.failure === null && known.minimum === undefined)
             return;
-        await this.examine(kind, SIGNED_OUT, offer);
+        await this.examine(kind, SIGNED_OUT, (kind, cli, known) => this.quietOffer(kind, cli, known));
+        await this.report();
     }
     async send() {
         const agents = this.desired.agents.flatMap((kind) => {
@@ -284,8 +329,10 @@ export class Agents {
             return reading === undefined ? [] : [reported(kind, reading)];
         });
         const hostKey = await sshHostKey();
+        const form = await hostForm();
         const body = {
             os: await operatingSystem(),
+            ...(form === undefined ? {} : { form }),
             kit_version: KIT_VERSION,
             wire: KIT_WIRE,
             updates_itself: await updatesItself(),

package/dist/bootstrap.json

@@ -1,23 +1,23 @@
 {
   "schemaVersion": 2,
-  "version": "0.2.1-c3fc787e93f0e",
+  "version": "0.2.1-c4823db4ff116",
   "hosts": {
     "macos": {
       "asset": {
         "name": "connect-linux.sh",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-c3fc787e93f0e/connect-linux.sh"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-c4823db4ff116/connect-linux.sh"
       }
     },
     "linux": {
       "asset": {
         "name": "connect-linux.sh",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-c3fc787e93f0e/connect-linux.sh"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-c4823db4ff116/connect-linux.sh"
       }
     },
     "windows": {
       "asset": {
         "name": "connect-windows.ps1",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-c3fc787e93f0e/connect-windows.ps1"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-c4823db4ff116/connect-windows.ps1"
       }
     }
   }

package/dist/chatgpt.js

@@ -1,4 +1,5 @@
 import { parseArgs } from 'node:util';
+import { placeAppGit } from './app-git.js';
 import { kitHome, readOwnAgent, writeOwnAgent } from './home.js';
 import { accepted, DEFAULT_HOUSE } from './login.js';
 const KEY_SOURCE = 'New key for a script on Connections';
@@ -17,10 +18,15 @@ export async function chatgpt(argv) {
     }
     if (values.key === undefined)
         throw new Error(`pass --key with a key from ${KEY_SOURCE}`);
-    const house = values.house ?? (await readOwnAgent())?.house ?? DEFAULT_HOUSE;
+    const before = await readOwnAgent();
+    const house = values.house ?? before?.house ?? DEFAULT_HOUSE;
     if (!(await accepted(house, values.key)))
         throw new Error(`${house} does not accept this key; pass one from ${KEY_SOURCE}`);
     const relay = process.env.HOUSE_KIT_RELAY || undefined;
     await writeOwnAgent({ house, ...(relay === undefined ? {} : { relay }), credential: values.key });
+    await placeAppGit(before, await readOwnAgent()).catch((error) => process.stderr.write(`kit: ${error.message}\n`));
+    if (before !== null && before.credential !== values.key) {
+        process.stdout.write('This replaced the key this Kit home held; give each session its own HOUSE_KIT_HOME to keep its own key.\n');
+    }
     process.stdout.write(`house now calls ${house} as you, with the key kept in ${kitHome()}.\n`);
 }

package/dist/clis.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { constants, readFileSync } from 'node:fs';
 import { access, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { homedir, userInfo } from 'node:os';
@@ -54,7 +55,7 @@ export async function allowHouseInCodex(path) {
             houses.push(house);
     }
     await mkdir(rules, { recursive: true });
-    const temporary = `${file}.${process.pid}`;
+    const temporary = `${file}.${randomUUID()}`;
     await writeFile(temporary, houseRule(houses));
     await rename(temporary, file);
 }

package/dist/conversations.js

@@ -6,7 +6,7 @@ import { unlessAborted } from './abort.js';
 import { startAdapter } from './acp.js';
 import { openBridge } from './bridge.js';
 import { CLIS } from './clis.js';
-import { readerFor } from './events.js';
+import { answeredFailure, readerFor } from './events.js';
 import { placeFiles, uploadBytes } from './files.js';
 import { agentBase } from './home.js';
 import { instructions } from './instructions.js';
@@ -17,6 +17,15 @@ import { createHowWeWork } from './skills.js';
 import { transcribe } from './transcription.js';
 import { workFor } from './work.js';
 const KILLED = 'the conversation was killed';
+const REFUSED = 'the CLI refused the prompt';
+const EXIT_PLAN_MODE = {
+    parse(value) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            throw new Error('_x.ai/exit_plan_mode needs an object');
+        }
+        return value;
+    },
+};
 export const CONVERSATION_INPUTS = new Set(['open', 'message', 'interrupt', 'kill', 'option', 'answer']);
 function causeOf(error) {
     return error instanceof Error ? error.message : String(error);
@@ -348,7 +357,8 @@ export class Conversations {
         reader.session = sessionId;
         const app = client({ name: '@agentshouse/kit' })
             .onRequest('session/request_permission', ({ params, signal }) => this.ask(conversation, 'session/request_permission', params, false, signal))
-            .onRequest('elicitation/create', ({ params, signal }) => this.ask(conversation, 'elicitation/create', params, asksSecret(params), signal));
+            .onRequest('elicitation/create', ({ params, signal }) => this.ask(conversation, 'elicitation/create', params, asksSecret(params), signal))
+            .onRequest('_x.ai/exit_plan_mode', EXIT_PLAN_MODE, ({ params, signal }) => this.ask(conversation, '_x.ai/exit_plan_mode', params, false, signal));
         const cli = await unlessAborted(this.kit.agents.cli(route.kind), conversation.killed.signal);
         const bridge = await openBridge(this.kit.house, this.kit.copies, conversation.id, conversation.killed.signal);
         if (conversation.kills > 0) {
@@ -491,13 +501,15 @@ export class Conversations {
         this.kit.changed();
         return turn;
     }
-    end(conversation, turn, failed) {
+    end(conversation, turn, failed, notice = null) {
         if (turn.ended)
             return;
         if (conversation.turn === turn) {
             for (const event of conversation.running?.reader.closeTurn() ?? [])
                 this.apply(conversation, turn, event);
         }
+        if (notice !== null)
+            turn.parts.start({ type: 'marker', marker: 'retry', text: notice });
         turn.ended = true;
         conversation.open--;
         if (conversation.turn === turn)
@@ -515,7 +527,11 @@ export class Conversations {
         const running = conversation.running;
         const turn = this.begin(conversation);
         turn.prompted = true;
-        running.adapter.connection.agent.request('session/prompt', { sessionId: running.sessionId, prompt }).then(() => this.end(conversation, turn, null), async (error) => {
+        running.adapter.connection.agent.request('session/prompt', { sessionId: running.sessionId, prompt }).then((answer) => {
+            const notice = answeredFailure(answer);
+            const failed = notice ?? (answer.stopReason === 'refusal' ? REFUSED : null);
+            this.end(conversation, turn, failed === null ? null : { failed }, notice);
+        }, async (error) => {
             if (running.adapter.connection.signal.aborted) {
                 this.end(conversation, turn, { failed: running.killed ? KILLED : await running.adapter.exited });
             }

package/dist/copies.js

@@ -15,6 +15,9 @@ const IDENTITY = { GIT_COMMITTER_NAME: 'House Kit', GIT_COMMITTER_EMAIL: 'house-
 function causeOf(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function houseCause(error) {
+    return error instanceof HouseRefusal ? (refusalOf(error.text)?.text ?? causeOf(error)) : causeOf(error);
+}
 function logged(error) {
     process.stderr.write(`kit: ${causeOf(error)}\n`);
 }
@@ -261,7 +264,7 @@ export class LocalCopies {
                 }
                 catch (error) {
                     refused = true;
-                    said.push(error instanceof HouseRefusal ? (refusalOf(error.text)?.text ?? causeOf(error)) : causeOf(error));
+                    said.push(houseCause(error));
                 }
             }
             return { refused, text: said.length === 0 ? 'Nothing new from House.' : said.join('\n') };
@@ -549,7 +552,7 @@ export class LocalCopies {
             changes = await this.derived(copy, base, commit);
         }
         catch (error) {
-            return { refused: true, text: causeOf(error) };
+            return { refused: true, text: houseCause(error) };
         }
         if (changes.length === 0)
             return { refused: false, text: `Nothing to submit: ${short(commit)} matches House.` };
@@ -576,12 +579,17 @@ export class LocalCopies {
         const after = await tree(copy.repository, commit);
         const moved = movedPaths(copy.moves, before, after);
         const arrived = new Set(moved.values());
-        const binary = [];
-        for (const [path, entry] of after)
-            if (before.get(path) !== entry && !(await isText(copy.repository, entry)))
-                binary.push(path);
-        if (binary.length > 0)
-            throw new Error(textOnly(binary));
+        const arriving = [...after].filter(([path, entry]) => before.get(path) !== entry);
+        if (arriving.length > 0) {
+            const { bounds } = await this.house.post('/kit/door/discover', { prefixes: [root] });
+            const binary = [];
+            for (const [path, entry] of arriving) {
+                if (!(await isText(copy.repository, entry, bounds.max_authored_file_bytes)))
+                    binary.push(path);
+            }
+            if (binary.length > 0)
+                throw new Error(textOnly(binary));
+        }
         const text = (entry) => blobText(copy.repository, entry);
         const changes = [];
         for (const path of [...new Set([...before.keys(), ...after.keys()])].sort()) {

package/dist/events.js

@@ -512,6 +512,9 @@ class GrokReader extends Reader {
         return [];
     }
 }
+export function answeredFailure(answer) {
+    return answer._meta?.jetbrains?.air?.sessionFailure?.title ?? null;
+}
 export function readerFor(kind) {
     if (kind === 'claude-agent-acp')
         return new ClaudeReader();

package/dist/git.js

@@ -49,16 +49,15 @@ export async function tree(repository, commit) {
     }
     return entries;
 }
-const TEXT_MAX_BYTES = 16 * 1024 * 1024;
 async function blob(repository, object) {
     return (await run(repository, ['cat-file', 'blob', object])).stdout;
 }
 export async function blobText(repository, object) {
     return (await blob(repository, object)).toString('utf8');
 }
-export async function isText(repository, object) {
+export async function isText(repository, object, maxBytes) {
     const bytes = await blob(repository, object);
-    return bytes.length <= TEXT_MAX_BYTES && isUtf8(bytes) && !bytes.includes(0);
+    return bytes.length <= maxBytes && isUtf8(bytes) && !bytes.includes(0);
 }
 export function blobId(content) {
     const bytes = Buffer.from(content, 'utf8');

package/dist/home.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { accessSync, chmodSync, constants, existsSync, linkSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { homedir, tmpdir } from 'node:os';
@@ -63,7 +64,7 @@ export async function readHome(name) {
 export async function writeHome(name, value) {
     const home = kitHome();
     await mkdir(home, { recursive: true, mode: 0o700 });
-    const temporary = join(home, `${name}.${process.pid}`);
+    const temporary = join(home, `${name}.${randomUUID()}`);
     await writeFile(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600 });
     await rename(temporary, join(home, name));
 }
@@ -80,6 +81,9 @@ export async function writeEnrolment(enrolment) {
 export function readDisconnected() {
     return readHome(DISCONNECTED);
 }
+export function forgetDisconnected() {
+    return rm(join(kitHome(), DISCONNECTED), { force: true });
+}
 export async function forgetEnrolment({ house, environment }) {
     await writeHome(DISCONNECTED, { house, environment });
     await rm(join(kitHome(), ENROLMENT), { force: true });

package/dist/house-cli.js

@@ -0,0 +1,291 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { request, setGlobalProxyFromEnv } from 'node:http';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { verified } from './files.js';
+import { HOUSE_REF } from './git.js';
+import { kitHome, readOwnAgent } from './home.js';
+import { callHouse, rpc, UNREACHABLE } from './mcp.js';
+import { refusalOf } from './refusals.js';
+import { relayed, selectRelay } from './relay.js';
+import { parse, stringify } from 'yaml';
+const USAGE = "usage: house <tool> ['<arguments as JSON>']";
+const PUSH_USAGE = 'usage: house push [commit] [--owner]';
+const PUSH = "push [commit]: sends the Local copy's committed changes to House";
+const FETCH_USAGE = 'usage: house fetch';
+const FETCH = `fetch: records House's changes on each Local copy's ${HOUSE_REF}`;
+const DOWNLOAD_USAGE = `usage: house download '{"path":"/rooms/<handle>/<path>","file":"<local file>"}', adding "ref" for a revision`;
+const DOWNLOAD = 'download: writes a binary file of a Room to the local file named by file';
+const ARGUMENTS = `the arguments are one JSON object in single quotes, like house search '{"query":"invoice"}'`;
+const CLOSED = "this conversation's House connection is closed; nothing to do from here";
+const SANDBOXED = "your CLI's sandbox kept house from House; run house directly, not through another program";
+const REVOKED = 'this conversation no longer has House access; nothing to do from here';
+const UNCONNECTED = "this computer's own agent has no House connection; run kit login, or kit chatgpt --key <key> with a script key";
+const DISCONNECTED = "House no longer accepts this computer's own agent; run kit login, or kit chatgpt --key <key> with a script key";
+const UNCONFIRMED = 'with no result; a write may or may not have taken effect, so read before you repeat it';
+const socketPath = process.env.HOUSE_BRIDGE;
+const MEDIA_TYPES = new Map([
+    ['avif', 'image/avif'],
+    ['csv', 'text/csv'],
+    ['docx', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
+    ['gif', 'image/gif'],
+    ['heic', 'image/heic'],
+    ['html', 'text/html'],
+    ['jpeg', 'image/jpeg'],
+    ['jpg', 'image/jpeg'],
+    ['json', 'application/json'],
+    ['m4a', 'audio/mp4'],
+    ['md', 'text/markdown'],
+    ['mov', 'video/quicktime'],
+    ['mp3', 'audio/mpeg'],
+    ['mp4', 'video/mp4'],
+    ['ogg', 'audio/ogg'],
+    ['pdf', 'application/pdf'],
+    ['png', 'image/png'],
+    ['pptx', 'application/vnd.openxmlformats-officedocument.presentationml.presentation'],
+    ['svg', 'image/svg+xml'],
+    ['txt', 'text/plain'],
+    ['wav', 'audio/wav'],
+    ['webm', 'video/webm'],
+    ['webp', 'image/webp'],
+    ['xlsx', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
+    ['zip', 'application/zip'],
+]);
+function refused(path, method, status, text, local) {
+    const refusal = refusalOf(text);
+    if (refusal !== null)
+        return refusal.text;
+    if (status === 401)
+        return REVOKED;
+    const act = method === 'GET' ? 'download' : 'upload';
+    if (URL.canParse(path))
+        return `the ${act} answered ${status}; ${act} the file again`;
+    if (status === 502 && local)
+        return text;
+    return path === '/' ? unconfirmed(status) : `${path} answered ${status}`;
+}
+function unconfirmed(status) {
+    return `House answered ${status} ${UNCONFIRMED}`;
+}
+function exchanged(path, method, body, headers = { 'content-type': 'application/json' }, to = socketPath) {
+    return new Promise((resolve, reject) => {
+        const sent = request({ socketPath: to, path, method, headers }, (answer) => {
+            const chunks = [];
+            answer.on('data', (chunk) => chunks.push(chunk));
+            answer.on('end', () => {
+                const bytes = Buffer.concat(chunks);
+                if (answer.statusCode === 200)
+                    resolve(bytes);
+                else
+                    reject(new Error(refused(path, method, answer.statusCode, bytes.toString('utf8'), answer.headers['content-type'] === undefined)));
+            });
+        });
+        sent.on('error', (error) => reject(new Error(error.code === 'EPERM' || error.code === 'EACCES' ? SANDBOXED : CLOSED)));
+        sent.end(body === undefined ? undefined : body instanceof Buffer ? body : JSON.stringify(body));
+    });
+}
+async function bridged(path, body, headers, to = socketPath) {
+    return (await exchanged(path, 'POST', body, headers, to)).toString('utf8');
+}
+async function direct(message) {
+    const ownAgent = await readOwnAgent();
+    if (ownAgent === null)
+        throw new Error(UNCONNECTED);
+    selectRelay(process.env.HOUSE_KIT_RELAY || ownAgent.relay);
+    setGlobalProxyFromEnv();
+    const answer = await callHouse(ownAgent.house, ownAgent.credential, message).catch(() => {
+        throw new Error(UNREACHABLE);
+    });
+    if (answer.status === 200)
+        return answer.text;
+    throw new Error(answer.status === 401 ? DISCONNECTED : (refusalOf(answer.text)?.text ?? unconfirmed(answer.status)));
+}
+async function mcp(method, params) {
+    const message = rpc(method, params);
+    const answer = JSON.parse(socketPath === undefined ? await direct(message) : await bridged('/', message));
+    if (answer.error !== undefined)
+        throw new Error(answer.error.message);
+    return answer.result;
+}
+async function tools() {
+    return (await mcp('tools/list', {})).tools;
+}
+async function localFile(path) {
+    try {
+        return await readFile(path);
+    }
+    catch (error) {
+        throw new Error(error.code === 'EISDIR'
+            ? `${path} is a folder; upload one file at a time`
+            : `${path} is not a readable file`);
+    }
+}
+async function transferred(url, method, bytes, headers) {
+    if (socketPath !== undefined)
+        return exchanged(url, method, bytes, headers);
+    setGlobalProxyFromEnv();
+    const answer = await fetch(relayed(url), { method, ...(headers === undefined ? {} : { headers }), ...(bytes === undefined ? {} : { body: bytes }) }).catch(() => {
+        throw new Error(UNREACHABLE);
+    });
+    const received = Buffer.from(await answer.arrayBuffer());
+    if (answer.status === 200)
+        return received;
+    throw new Error(refused(url, method, answer.status, received.toString('utf8'), false));
+}
+async function sent(url, bytes, operation) {
+    const headers = { 'content-type': 'application/octet-stream', 'x-house-byte-operation': operation };
+    return (await transferred(url, 'POST', bytes, headers)).toString('utf8');
+}
+async function download(args) {
+    const { flags, positionals: [argument] } = accepted(args, ['--help'], 1, DOWNLOAD_USAGE);
+    if (flags.has('--help'))
+        return DOWNLOAD_USAGE;
+    const { file, ...selected } = argumentsOf(argument);
+    if (typeof file !== 'string' || file === '')
+        throw new Error('download needs "file", the local file to write');
+    const inspected = parse(await called('inspect', selected));
+    if (typeof inspected?.download !== 'string')
+        throw new Error(`${String(selected.path)} holds no binary file; shell reads its text`);
+    const bytes = verified(await transferred(inspected.download, 'GET'), String(inspected.sha256), String(selected.path));
+    const written = resolve(file);
+    await mkdir(dirname(written), { recursive: true });
+    await writeFile(written, bytes);
+    return written;
+}
+async function described(file) {
+    const bytes = await localFile(file);
+    const mediaType = MEDIA_TYPES.get(extname(file).slice(1).toLowerCase());
+    return {
+        bytes,
+        description: {
+            bytes: bytes.length,
+            sha256: createHash('sha256').update(bytes).digest('hex'),
+            ...(mediaType === undefined ? {} : { media_type: mediaType }),
+        },
+    };
+}
+async function upload({ file, ...destination }) {
+    if (typeof file !== 'string' || file === '')
+        throw new Error('upload needs "file", a local file');
+    const { bytes, description } = await described(file);
+    const answer = await called('upload', { ...destination, ...description });
+    const declared = parse(answer);
+    if (declared.upload === undefined)
+        return answer;
+    const written = JSON.parse(await sent(declared.upload.url, bytes, declared.upload.operation));
+    return stringify(written, { lineWidth: 0 }).trimEnd();
+}
+async function appendRecord(args) {
+    const held = new Map();
+    const attachments = Array.isArray(args.attachments)
+        ? await Promise.all(args.attachments.map(async (attachment) => {
+            if (typeof attachment !== 'string')
+                return attachment;
+            const { bytes, description } = await described(attachment);
+            held.set(description.sha256, bytes);
+            return { name: basename(attachment), ...description };
+        }))
+        : args.attachments;
+    const record = { ...args, attachments };
+    for (;;) {
+        const answer = await called('append_record', record);
+        const { upload } = parse(answer);
+        if (upload === undefined)
+            return answer;
+        for (const grant of upload)
+            await sent(grant.url, held.get(grant.sha256), grant.operation);
+    }
+}
+function unexpected(argument, usage) {
+    return new Error(`unexpected argument ${argument}; ${usage}`);
+}
+function accepted(args, flags, positionals, usage) {
+    const given = { flags: new Set(), positionals: [] };
+    for (const arg of args) {
+        if (flags.includes(arg))
+            given.flags.add(arg);
+        else if (!arg.startsWith('-') && given.positionals.length < positionals)
+            given.positionals.push(arg);
+        else
+            throw unexpected(arg, usage);
+    }
+    return given;
+}
+async function push(args) {
+    const { flags, positionals: [commit = 'HEAD'] } = accepted(args, ['--help', '--owner'], 1, PUSH_USAGE);
+    if (flags.has('--help'))
+        return PUSH_USAGE;
+    const owner = flags.has('--owner');
+    if (owner && socketPath !== undefined)
+        throw new Error('--owner is not for Agent conversations; run house push without it');
+    if (!owner && socketPath === undefined)
+        throw new Error('outside an Agent conversation, house push needs --owner');
+    const pushed = JSON.parse(await bridged('/git/push', { cwd: process.cwd(), commit }, undefined, owner ? join(kitHome(), 'owner.sock') : socketPath));
+    if (pushed.refused)
+        throw new Error(pushed.text);
+    return pushed.text;
+}
+async function fetched(args) {
+    if (accepted(args, ['--help'], 0, FETCH_USAGE).flags.has('--help'))
+        return FETCH_USAGE;
+    const answer = JSON.parse(await bridged('/git/fetch', {}, undefined, socketPath ?? join(kitHome(), 'owner.sock')));
+    if (answer.refused)
+        throw new Error(answer.text);
+    return answer.text;
+}
+function argumentsOf(argument) {
+    if (argument === undefined)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(argument);
+    }
+    catch {
+        throw new Error(ARGUMENTS);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        throw new Error(ARGUMENTS);
+    return parsed;
+}
+async function house(args) {
+    const { flags, positionals: [verb, argument] } = accepted(args, ['--help'], 2, USAGE);
+    if (verb === 'help' && argument !== undefined)
+        throw unexpected(argument, USAGE);
+    if (flags.has('--help') && argument !== undefined)
+        throw unexpected('--help', USAGE);
+    if (verb === undefined || verb === 'help') {
+        return [USAGE, 'help', PUSH, FETCH, DOWNLOAD, ...(await tools()).map((tool) => (tool.description === undefined ? tool.name : `${tool.name}: ${tool.description}`))].join('\n');
+    }
+    if (flags.has('--help')) {
+        const tool = (await tools()).find((listed) => listed.name === verb);
+        if (tool === undefined)
+            throw new Error(`${verb} is no Tool; house find_command '{"query":"${verb}"}' finds Commands`);
+        return [...(tool.description === undefined ? [] : [tool.description]), JSON.stringify(tool.inputSchema)].join('\n');
+    }
+    const parsed = argumentsOf(argument);
+    return verb === 'upload' ? upload(parsed) : verb === 'append_record' ? appendRecord(parsed) : called(verb, parsed);
+}
+async function called(name, args) {
+    const result = await mcp('tools/call', { name, arguments: args });
+    const text = result.content.map((content) => content.text).join('\n');
+    if (result.isError === true)
+        throw new Error(text.replace(/\n+$/, ''));
+    return text;
+}
+const argv = process.argv.slice(2);
+const named = argv.findIndex((arg) => !arg.startsWith('-'));
+const rest = argv.filter((_arg, index) => index !== named);
+(argv[named] === 'push'
+    ? push(rest)
+    : argv[named] === 'fetch'
+        ? fetched(rest)
+        : argv[named] === 'download'
+            ? download(rest)
+            : house(argv)).then((text) => {
+    process.stdout.write(`${text}\n`);
+    if (argv[0] === 'shell')
+        process.exitCode = Number(/^exit: (\d+)(?:\n|$)/.exec(text)?.[1] ?? 0);
+}, (error) => {
+    process.stderr.write(`house: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});