@agentshouse/kit 0.2.1-cf669c6d1ecbb → 0.2.1-cfd9926e1dac7

package/README.md

@@ -33,26 +33,26 @@ them out; running it again without the flag brings them back.
 
 `kit login` opens or prints a link you confirm in any browser, on this computer
 or another, continues on its own and keeps the Environment's credential in
-`~/.house-kit`, or in `$HOUSE_KIT_HOME` when it is set. `--environment <id>`
+`$HOUSE_KIT_HOME` when it is set, else in `~/.house-kit`, or in `house-kit-<uid>` under the temporary directory when your home is read-only. `--environment <id>`
 reconnects an Environment you already have; `--rooms <ref>[,<ref>...]` gives it
-only those Rooms and `--no-private` every Room but your Private Room;
-`--code <code>` connects immediately without a link.
+only those Rooms and `--no-private` every Room but your Private Room; `--code <code>` connects immediately without a link.
 A login also connects your own agent: outside an Agent conversation, `house <tool>` calls
-House as you and `git` clones and pushes your Apps at `<house>/app/` as you,
-until you revoke that connection on Connections. `house help` lists the Tools.
-`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.
-
-`kit resident` keeps the Environment connected and, as it connects, copies each
-Room you chose for it as a Git repository in the workspace's `local-copies`.
-`house fetch` records House's changes on each copy's `refs/house/received`;
-rebase onto it, commit and run `house push --owner` in the copy, through the
-install command in the container. An Agent runs both, without `--owner`.
+House as you and `git` clones and pushes your Apps at `<house>/app/` as you, until you revoke
+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.
+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
+you chose for it as a Git repository in the workspace's `local-copies`. `house fetch` records
+House's changes on each copy's `refs/house/received`; rebase onto it, commit and run
+`house push --owner` in the copy, through the install command in the container. An Agent runs
+both, without `--owner`. `house upload` and `house download` move a Room's other files.
 
 House Kit turns each audio file of your message to an Agent into text on this
 computer before the Agent reads it. While transcription is on, the speech
-engine and model use about 425 MB in `~/.house-kit`; turning it off deletes them.
+engine and model use about 425 MB beside the Environment's credential; turning it off deletes them.
 
 ## License
 

package/dist/agents.js

@@ -3,8 +3,10 @@ import { readFile, realpath } from 'node:fs/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';
+import { updatesItself } from './placement.js';
 import { killTree } from './scope.js';
 import { holdTranscription, transcriptionReport } from './transcription.js';
+import { KIT_WIRE } from './wire.js';
 const SIGNED_OUT = { signed_in: false, models: [], modes: [] };
 function select(options, category) {
     const option = options.find((candidate) => candidate.category === category);
@@ -130,8 +132,14 @@ export class Agents {
     reads = new Map();
     sending = Promise.resolve();
     sent = null;
-    constructor(house) {
+    refreshing = 0;
+    changed;
+    constructor(house, changed = () => undefined) {
         this.house = house;
+        this.changed = changed;
+    }
+    idle() {
+        return this.refreshing === 0;
     }
     read() {
         return this.reading.then(() => undefined, () => undefined);
@@ -140,19 +148,28 @@ export class Agents {
         return this.desired.routes.find((route) => route.agent_id === agentId);
     }
     refresh() {
+        this.refreshing++;
+        this.changed();
         const reading = this.read().then(async () => {
             this.desired = await this.house.deliver('/kit/agents/desired', {});
             return this.desired;
         });
         this.reading = reading;
-        return reading.then(({ agents, transcribe }) => {
+        reading
+            .then(({ agents, transcribe }) => Promise.all([
             holdTranscription(transcribe)
                 .then((changed) => (changed ? this.report() : undefined))
-                .catch(logged);
+                .catch(logged),
             Promise.all(agents.map((kind) => this.load(kind)))
                 .then(() => this.report())
-                .catch(logged);
+                .catch(logged),
+        ]))
+            .catch(() => undefined)
+            .finally(() => {
+            this.refreshing--;
+            this.changed();
         });
+        return reading.then(() => undefined);
     }
     cli(kind) {
         return this.queue(kind, async () => {
@@ -270,6 +287,8 @@ export class Agents {
         const body = {
             os: await operatingSystem(),
             kit_version: KIT_VERSION,
+            wire: KIT_WIRE,
+            updates_itself: await updatesItself(),
             agent_base: agentBase(),
             agents,
             transcription: transcriptionReport(),

package/dist/api.js

@@ -1,8 +1,9 @@
 import { setTimeout as delay } from 'node:timers/promises';
-import { signInAgain } from './end.js';
+import { signInAgain, updateRequired } from './end.js';
 import { readEnrolment } from './home.js';
 import { retryable } from './refusals.js';
 import { relayed } from './relay.js';
+import { KIT_WIRE, KIT_WIRE_HEADER, tooOld } from './wire.js';
 export class HouseRefusal extends Error {
     status;
     text;
@@ -37,12 +38,15 @@ export async function post(house, path, body, credential, signal) {
         method: 'POST',
         headers: {
             'content-type': 'application/json',
+            [KIT_WIRE_HEADER]: String(KIT_WIRE),
             ...(credential === undefined ? {} : { authorization: `Bearer ${credential}` }),
         },
         body: JSON.stringify(body),
         signal,
     });
     const text = await answer.text();
+    if (!answer.ok && tooOld(text))
+        updateRequired(house);
     if (!answer.ok)
         throw new HouseRefusal(path, answer.status, text);
     return JSON.parse(text);

package/dist/bootstrap.json

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

package/dist/chatgpt.js

@@ -0,0 +1,26 @@
+import { parseArgs } from 'node:util';
+import { kitHome, readOwnAgent, writeOwnAgent } from './home.js';
+import { accepted, DEFAULT_HOUSE } from './login.js';
+const KEY_SOURCE = 'New key for a script on Connections';
+const USAGE = `usage: kit chatgpt --key <key> [--house <origin>]
+  --key <key>       a key from ${KEY_SOURCE}
+  --house <origin>  the House of the key, ${DEFAULT_HOUSE} unless one is stored
+`;
+export async function chatgpt(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: { key: { type: 'string' }, house: { type: 'string' }, help: { type: 'boolean', default: false } },
+    });
+    if (values.help) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (values.key === undefined)
+        throw new Error(`pass --key with a key from ${KEY_SOURCE}`);
+    const house = values.house ?? (await readOwnAgent())?.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 });
+    process.stdout.write(`house now calls ${house} as you, with the key kept in ${kitHome()}.\n`);
+}

package/dist/clis.js

@@ -1,9 +1,13 @@
 import { spawn } from 'node:child_process';
 import { constants, readFileSync } from 'node:fs';
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { access, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { homedir, userInfo } from 'node:os';
-import { delimiter, isAbsolute, join } from 'node:path';
+import { delimiter, dirname, isAbsolute, join } from 'node:path';
 import { kitHome } from './home.js';
+const HOUSE_EXECUTABLES = /^host_executable\(name = "house", paths = (\[.*\])\)$/m;
+function houseRule(houses) {
+    return `prefix_rule(pattern = ["house"], decision = "allow")\nhost_executable(name = "house", paths = ${JSON.stringify(houses)})\n`;
+}
 const RAW_SUBTYPES = [
     'background_tasks_changed',
     'task_started',
@@ -22,15 +26,37 @@ async function executable(path) {
         return false;
     }
 }
-async function allowHouseInCodex(path) {
+async function listedHouses(file) {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    try {
+        const listed = JSON.parse(HOUSE_EXECUTABLES.exec(text)?.[1] ?? '[]');
+        return Array.isArray(listed) ? listed.filter((house) => typeof house === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
+export async function allowHouseInCodex(path) {
     const candidates = [...new Set(path.split(delimiter).filter((directory) => isAbsolute(directory)))].map((directory) => join(directory, 'house'));
-    const houses = [];
-    for (const candidate of candidates)
-        if (await executable(candidate))
-            houses.push(candidate);
     const rules = join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'rules');
+    const file = join(rules, 'house.rules');
+    const houses = [];
+    for (const house of [...(await listedHouses(file)), ...candidates]) {
+        if (!houses.includes(house) && (await executable(house)))
+            houses.push(house);
+    }
     await mkdir(rules, { recursive: true });
-    await writeFile(join(rules, 'house.rules'), `prefix_rule(pattern = ["house"], decision = "allow")\nhost_executable(name = "house", paths = ${JSON.stringify(houses)})\n`);
+    const temporary = `${file}.${process.pid}`;
+    await writeFile(temporary, houseRule(houses));
+    await rename(temporary, file);
 }
 async function nothing() { }
 function bridgeInClaudeSandbox(bridge) {
@@ -173,7 +199,7 @@ export async function installAdapter(kind, signal) {
     const release = KIT_PACKAGE.peerDependencies[adapter.package];
     if ((await installedAdapter(kind)) === release)
         return null;
-    const ran = await run('npm', ['install', '--prefix', prefix(kind), '--no-save', '--no-audit', '--no-fund', '--omit=optional', `${adapter.package}@${release}`], INSTALL_MS, true, signal);
+    const ran = await run('npm', ['install', '--prefix', prefix(kind), '--cache', join(kitHome(), 'npm-cache'), '--no-save', '--no-audit', '--no-fund', '--omit=optional', `${adapter.package}@${release}`], INSTALL_MS, true, signal);
     return ran.status === 0 ? null : failureOf(ran, 'npm');
 }
 export async function installCli(kind, signal) {
@@ -198,6 +224,12 @@ export async function loginPath() {
     const ran = await inLoginShell(`printf "${marker}%s\\n" "$PATH"`);
     return ran.stdout.split('\n').findLast((line) => line.startsWith(marker)).slice(marker.length);
 }
+export async function writeCodexRule() {
+    const shell = await loginPath().catch(() => '');
+    await allowHouseInCodex([dirname(process.execPath), process.env.PATH ?? '', shell].join(delimiter)).catch((error) => {
+        throw new Error(`Codex's rule for house could not be written: ${error.message}`);
+    });
+}
 export async function versionOf(path, signal) {
     return VERSION.exec((await run(path, ['--version'], READ_MS, false, signal)).stdout)?.[0] ?? null;
 }

package/dist/conversations.js

@@ -17,6 +17,7 @@ import { createHowWeWork } from './skills.js';
 import { transcribe } from './transcription.js';
 import { workFor } from './work.js';
 const KILLED = 'the conversation was killed';
+export const CONVERSATION_INPUTS = new Set(['open', 'message', 'interrupt', 'kill', 'option', 'answer']);
 function causeOf(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/copies.js

@@ -3,7 +3,7 @@ import { randomUUID } from 'node:crypto';
 import { mkdir, readFile, readdir, realpath, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { finalRefusal, HouseRefusal, retrying } from './api.js';
-import { blobId, blobText, git, HOUSE_REF, importCommits, localCopies, revision, run, succeeded, tree, } from './git.js';
+import { blobId, blobText, git, isText, HOUSE_REF, importCommits, localCopies, revision, run, succeeded, tree, } from './git.js';
 import { kitHome } from './home.js';
 import { operationId } from './operation.js';
 import { refusalOf } from './refusals.js';
@@ -29,6 +29,10 @@ const REBASED = new Set([
 function rebaseFixes(refusal) {
     return refusal.code === 'edit_conflict' && refusal.conflicts.some((code) => REBASED.has(code));
 }
+function textOnly(paths) {
+    const [named, them] = paths.length === 1 ? [`${paths[0]} is`, 'it'] : [`${paths.join(', ')} are`, 'them'];
+    return `${named} not text, and house push sends text only; remove ${them} from the commit and place ${them} with house upload`;
+}
 function short(commit) {
     return commit.slice(0, 12);
 }
@@ -572,7 +576,13 @@ export class LocalCopies {
         const after = await tree(copy.repository, commit);
         const moved = movedPaths(copy.moves, before, after);
         const arrived = new Set(moved.values());
-        const text = (entry, path) => blobText(copy.repository, entry, path);
+        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 text = (entry) => blobText(copy.repository, entry);
         const changes = [];
         for (const path of [...new Set([...before.keys(), ...after.keys()])].sort()) {
             if (arrived.has(path))
@@ -585,7 +595,7 @@ export class LocalCopies {
                 changes.push({ op: 'rename', path: `${root}/${path}`, to: `${root}/${to}`, base: known });
                 const moving = after.get(to);
                 if (moving !== prior) {
-                    changes.push({ op: 'replace', path: `${root}/${to}`, base: known, content: await text(moving, to) });
+                    changes.push({ op: 'replace', path: `${root}/${to}`, base: known, content: await text(moving) });
                 }
                 continue;
             }
@@ -594,9 +604,9 @@ export class LocalCopies {
             if (next === undefined)
                 changes.push({ op: 'remove', path: `${root}/${path}`, base: known });
             else if (prior === undefined)
-                changes.push({ op: 'create', path: `${root}/${path}`, content: await text(next, path) });
+                changes.push({ op: 'create', path: `${root}/${path}`, content: await text(next) });
             else
-                changes.push(...changed(`${root}/${path}`, path, known, await text(prior, path), await text(next, path)));
+                changes.push(...changed(`${root}/${path}`, path, known, await text(prior), await text(next)));
         }
         return changes;
     }
@@ -663,7 +673,7 @@ export class LocalCopies {
             written.push({
                 path: `${root}/${path}`,
                 revision: entry === undefined ? null : (revisionAt(current, current.house, path) ?? null),
-                content: entry === undefined ? null : await blobText(copy.repository, entry, path),
+                content: entry === undefined ? null : await blobText(copy.repository, entry),
             });
         }
         return this.finished(await this.save({ ...current, push: { ...push, state: 'accepted', written } }));
@@ -707,7 +717,7 @@ export class LocalCopies {
                     {
                         path: `${rootOf(copy.room_handle)}/${path}`,
                         revision: entry === undefined ? null : (revisionAt(copy, copy.house, path) ?? null),
-                        content: entry === undefined ? null : await blobText(copy.repository, entry, path),
+                        content: entry === undefined ? null : await blobText(copy.repository, entry),
                     },
                 ];
             }
@@ -752,7 +762,7 @@ export class LocalCopies {
     async landed(repository, changes, house, selected) {
         const text = async (path) => {
             const entry = house.get(relative(path));
-            return entry === undefined ? undefined : blobText(repository, entry, path);
+            return entry === undefined ? undefined : blobText(repository, entry);
         };
         for (const change of changes) {
             const current = await text(change.path);

package/dist/end.js

@@ -1,4 +1,5 @@
 import { forgetRejected } from './home.js';
+import { installCommand } from './placement.js';
 import { killDescendants } from './scope.js';
 export const REPLACED = 'another Kit started for this Environment';
 function exit(reason, status) {
@@ -12,6 +13,9 @@ export function end(reason) {
 export function restart(reason) {
     exit(reason, 1);
 }
+export function updateRequired(house) {
+    end(`This Kit is too old for House. Update it: ${installCommand(house)}`);
+}
 export async function signInAgain(rejected) {
     await forgetRejected(rejected);
     restart('sign in again');

package/dist/files.js

@@ -1,7 +1,13 @@
+import { createHash } from 'node:crypto';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { HouseRefusal, retrying } from './api.js';
 import { relayed } from './relay.js';
+export function verified(bytes, sha256, name) {
+    if (createHash('sha256').update(bytes).digest('hex') !== sha256)
+        throw new Error(`${name} did not arrive whole; download it again`);
+    return bytes;
+}
 export async function placeFiles(house, directory, files, signal) {
     const paths = [];
     for (const file of files) {
@@ -16,7 +22,7 @@ export async function placeFiles(house, directory, files, signal) {
         });
         await mkdir(folder, { recursive: true });
         const path = join(folder, file.name);
-        await writeFile(path, Buffer.from(await answer.arrayBuffer()));
+        await writeFile(path, verified(Buffer.from(await answer.arrayBuffer()), file.sha256, file.name));
         paths.push(path);
     }
     return paths;

package/dist/git.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { isUtf8 } from 'node:buffer';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { withoutProxy } from './clis.js';
@@ -48,14 +49,16 @@ export async function tree(repository, commit) {
     }
     return entries;
 }
-export async function blobText(repository, object, path) {
-    const bytes = (await run(repository, ['cat-file', 'blob', object])).stdout;
-    try {
-        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
-    }
-    catch {
-        throw new Error(`${path} is binary and House stores only text; remove it from the commit`);
-    }
+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) {
+    const bytes = await blob(repository, object);
+    return bytes.length <= TEXT_MAX_BYTES && isUtf8(bytes) && !bytes.includes(0);
 }
 export function blobId(content) {
     const bytes = Buffer.from(content, 'utf8');

package/dist/home.js

@@ -1,6 +1,6 @@
-import { existsSync, linkSync, readFileSync, renameSync, rmSync } from 'node:fs';
+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 } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { selectRelay } from './relay.js';
 const ENROLMENT = 'credential.json';
@@ -8,8 +8,41 @@ const DISCONNECTED = 'disconnected.json';
 const CONFIGURATION = 'kit.json';
 const OWN_AGENT = 'own-agent.json';
 const RESTART = 'restart';
+let defaulted;
+function writable(directory) {
+    try {
+        accessSync(directory, constants.W_OK | constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function ownTemporaryHome() {
+    const home = join(tmpdir(), `house-kit-${process.getuid()}`);
+    try {
+        mkdirSync(home, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    const found = lstatSync(home);
+    if (found.isSymbolicLink())
+        throw new Error(`${home} is a symbolic link`);
+    if (!found.isDirectory())
+        throw new Error(`${home} is not a directory`);
+    if (found.uid !== process.getuid())
+        throw new Error(`${home} is not owned by this User`);
+    chmodSync(home, 0o700);
+    return home;
+}
+function defaultHome() {
+    const home = join(homedir(), '.house-kit');
+    return existsSync(home) || writable(homedir()) ? home : ownTemporaryHome();
+}
 export function kitHome() {
-    return process.env.HOUSE_KIT_HOME ?? join(homedir(), '.house-kit');
+    return process.env.HOUSE_KIT_HOME || (defaulted ??= defaultHome());
 }
 export function workspaceRoot() {
     return process.env.HOUSE_KIT_WORKSPACE ?? '/agents/house';

package/dist/house-main.js

@@ -1,69 +1,105 @@
 #!/usr/bin/env node
 import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { request, setGlobalProxyFromEnv } from 'node:http';
-import { basename, join } from 'node:path';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { verified } from './files.js';
 import { HOUSE_REF } from './git.js';
-import { kitHome, readEnrolment, readOwnAgent } from './home.js';
+import { kitHome, readOwnAgent } from './home.js';
 import { callHouse, rpc, UNREACHABLE } from './mcp.js';
 import { refusalOf } from './refusals.js';
-import { relayed } from './relay.js';
-import { parse } from 'yaml';
+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";
 const DISCONNECTED = "House no longer accepts this computer's own agent; run kit login";
+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;
-function refused(path, status, text) {
+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 upload answered ${status}; upload the file again`;
-    if (status === 502 && /^[A-Za-z]/.test(text))
+        return `the ${act} answered ${status}; ${act} the file again`;
+    if (status === 502 && local)
         return text;
-    return `${path} answered ${status}`;
+    return path === '/' ? unconfirmed(status) : `${path} answered ${status}`;
 }
-function bridged(path, body, headers = { 'content-type': 'application/json' }, to = socketPath) {
+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: 'POST', headers }, (answer) => {
-            let text = '';
-            answer.setEncoding('utf8');
-            answer.on('data', (chunk) => {
-                text += chunk;
-            });
+        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(text);
+                    resolve(bytes);
                 else
-                    reject(new Error(refused(path, answer.statusCode, text)));
+                    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 instanceof Buffer ? body : JSON.stringify(body));
+        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);
-    await readEnrolment();
+    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 ?? `House answered ${answer.status}`));
+    throw new Error(answer.status === 401 ? DISCONNECTED : (refusalOf(answer.text)?.text ?? unconfirmed(answer.status)));
 }
 async function mcp(method, params) {
     const message = rpc(method, params);
@@ -85,41 +121,102 @@ async function localFile(path) {
             : `${path} is not a readable file`);
     }
 }
-async function sent(url, bytes, operation) {
-    const headers = { 'content-type': 'application/octet-stream', 'x-house-byte-operation': operation };
+async function transferred(url, method, bytes, headers) {
     if (socketPath !== undefined)
-        return bridged(url, bytes, headers);
+        return exchanged(url, method, bytes, headers);
     setGlobalProxyFromEnv();
-    const answer = await fetch(relayed(url), { method: 'POST', headers, body: bytes }).catch(() => {
+    const answer = await fetch(relayed(url), { method, ...(headers === undefined ? {} : { headers }), ...(bytes === undefined ? {} : { body: bytes }) }).catch(() => {
         throw new Error(UNREACHABLE);
     });
-    const text = await answer.text();
+    const received = Buffer.from(await answer.arrayBuffer());
     if (answer.status === 200)
-        return text;
-    throw new Error(refused(url, answer.status, text));
-}
-async function upload(path, roomRef, missing) {
-    if (typeof path !== 'string' || path === '')
-        throw new Error(missing);
-    const bytes = await localFile(path);
-    const declared = parse(await called('upload', {
-        ...(roomRef === undefined ? {} : { room_ref: roomRef }),
-        name: basename(path),
-        bytes: bytes.length,
-        sha256: createHash('sha256').update(bytes).digest('hex'),
-    }));
+        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 declared.attachment;
-    const saved = JSON.parse(await sent(declared.upload.url, bytes, declared.upload.operation));
-    if (saved.upload_failure !== undefined)
-        throw new Error(`${path} was not saved: ${saved.upload_failure}; call again later`);
-    return saved.attachment;
+        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) {
-    if (args.includes('--help'))
+    const { flags, positionals: [commit = 'HEAD'] } = accepted(args, ['--help', '--owner'], 1, PUSH_USAGE);
+    if (flags.has('--help'))
         return PUSH_USAGE;
-    const owner = args.includes('--owner');
-    const commit = args.find((arg) => arg !== '--owner') ?? 'HEAD';
+    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)
@@ -130,7 +227,7 @@ async function push(args) {
     return pushed.text;
 }
 async function fetched(args) {
-    if (args.includes('--help'))
+    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)
@@ -151,28 +248,23 @@ function argumentsOf(argument) {
         throw new Error(ARGUMENTS);
     return parsed;
 }
-async function house([verb, argument]) {
-    if (verb === undefined || verb === '--help' || verb === 'help') {
-        return [USAGE, 'help', PUSH, FETCH, ...(await tools()).map((tool) => (tool.description === undefined ? tool.name : `${tool.name}: ${tool.description}`))].join('\n');
+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 (argument === '--help') {
+    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 args = argumentsOf(argument);
-    if (verb === 'upload') {
-        return JSON.stringify({ attachment: await upload(args.path, args.room_ref, 'upload needs "path", a local file') });
-    }
-    if (verb === 'append_record' && Array.isArray(args.attachments)) {
-        const attachments = [];
-        for (const path of args.attachments) {
-            attachments.push(await upload(path, args.room_ref, 'each attachments entry is the path of a local file'));
-        }
-        args.attachments = attachments;
-    }
-    return called(verb, args);
+    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 });
@@ -182,7 +274,15 @@ async function called(name, args) {
     return text;
 }
 const argv = process.argv.slice(2);
-(argv[0] === 'push' ? push(argv.slice(1)) : argv[0] === 'fetch' ? fetched(argv.slice(1)) : house(argv)).then((text) => {
+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);

package/dist/kit-main.js

@@ -1,22 +1,67 @@
 #!/usr/bin/env node
 import { setGlobalProxyFromEnv } from 'node:http';
+import { parseArgs } from 'node:util';
 import { answerGitCredential } from './app-git.js';
+import { chatgpt } from './chatgpt.js';
 import { login } from './login.js';
 import { logout } from './logout.js';
 import { resident } from './resident.js';
+const USAGE = 'usage: kit <login|logout|resident|chatgpt>\n';
+const COMMANDS = new Map([
+    [
+        'logout',
+        {
+            usage: 'usage: kit logout',
+            about: "disconnects this computer, stops House Kit and ends your own agent's connection",
+            operands: 0,
+            run: logout,
+        },
+    ],
+    [
+        'resident',
+        {
+            usage: 'usage: kit resident',
+            about: "keeps this Environment connected; House Kit's service runs it",
+            operands: 0,
+            run: resident,
+        },
+    ],
+    [
+        'git-credential',
+        {
+            usage: 'usage: kit git-credential <get|store|erase>',
+            about: "answers git with your own agent's House credential; git runs it",
+            operands: 1,
+            run: ([operation]) => answerGitCredential(operation),
+        },
+    ],
+]);
 const [command, ...argv] = process.argv.slice(2);
 setGlobalProxyFromEnv();
 async function run() {
     if (command === 'login')
         return login(argv);
-    if (command === 'logout')
-        return logout();
-    if (command === 'resident')
-        return resident();
-    if (command === 'git-credential')
-        return answerGitCredential(argv[0]);
-    process.stderr.write('usage: kit <login|logout|resident>\n');
-    process.exitCode = 2;
+    if (command === 'chatgpt')
+        return chatgpt(argv);
+    if (command === '--help') {
+        parseArgs({ args: argv });
+        process.stdout.write(USAGE);
+        return;
+    }
+    const chosen = COMMANDS.get(command ?? '');
+    if (chosen === undefined) {
+        process.stderr.write(USAGE);
+        process.exitCode = 2;
+        return;
+    }
+    const { values, positionals } = parseArgs({ args: argv, options: { help: { type: 'boolean', default: false } }, allowPositionals: true });
+    if (positionals.length > chosen.operands)
+        throw new Error(`unexpected argument ${positionals[chosen.operands]}; ${chosen.usage}`);
+    if (values.help) {
+        process.stdout.write(`${chosen.usage}\n  ${chosen.about}\n`);
+        return;
+    }
+    return chosen.run(positionals);
 }
 run().catch((error) => {
     process.stderr.write(`kit: ${error instanceof Error ? error.message : String(error)}\n`);

package/dist/login.js

@@ -4,11 +4,13 @@ import { hostname } from 'node:os';
 import { parseArgs } from 'node:util';
 import { post, retrying } from './api.js';
 import { placeAppGit } from './app-git.js';
+import { writeCodexRule } from './clis.js';
 import { forgetOwnAgent, readDisconnected, readEnrolment, readOwnAgent, writeEnrolment, writeOwnAgent } from './home.js';
 import { callHouse, rpc } from './mcp.js';
 import { selectRelay } from './relay.js';
 import { startService } from './service.js';
-const DEFAULT_HOUSE = 'https://agents.house';
+import { placeSkillSet } from './skills.js';
+export const DEFAULT_HOUSE = 'https://agents.house';
 const OPENER = process.platform === 'darwin' ? 'open' : 'xdg-open';
 // Polling every two seconds brings the User's confirmation to the waiting Kit moments after they give it.
 const POLL_INTERVAL_MS = 2000;
@@ -17,7 +19,7 @@ function open(link) {
         .on('error', () => undefined)
         .unref();
 }
-async function accepted(house, credential) {
+export async function accepted(house, credential) {
     const checked = await callHouse(house, credential, rpc('tools/list', {}));
     if (checked.status === 200)
         return true;
@@ -25,7 +27,8 @@ async function accepted(house, credential) {
         return false;
     throw new Error(`House answered ${checked.status} when Kit checked this computer's own agent's connection: ${checked.text}`);
 }
-const USAGE = `usage: kit login [--house <origin>] [--environment <id>] [--rooms <ref>[,<ref>...] | --no-private] [--code <code>]
+const USAGE = `usage: kit login [--house <origin>] [--environment <id>] [--rooms <ref>[,<ref>...] | --no-private]
+       kit login [--house <origin>] --code <code>
   --house <origin>          the House to connect to, ${DEFAULT_HOUSE} unless one is stored
   --environment <id>        reconnect this Environment
   --rooms <ref>[,<ref>...]  give this Environment only these Rooms
@@ -93,21 +96,27 @@ export async function login(argv) {
         open(started.start_url);
         exchanged = await retrying(() => post(house, '/kit/token', { login: started.login, code_verifier: verifier }), undefined, () => POLL_INTERVAL_MS);
     }
+    await placeSkillSet();
+    await writeCodexRule().catch((error) => process.stderr.write(`kit: ${error.message}\n`));
+    const relayRecord = relay === undefined ? {} : { relay };
     await writeEnrolment({
         house,
-        ...(relay === undefined ? {} : { relay }),
+        ...relayRecord,
         environment: exchanged.environment,
         credential: exchanged.credential,
     });
     process.stdout.write(`Environment ${exchanged.environment} is connected to ${house}.\n`);
     if (exchanged.headless_credential !== undefined) {
-        await writeOwnAgent({ house, user: exchanged.user, credential: exchanged.headless_credential });
+        await writeOwnAgent({ house, ...relayRecord, user: exchanged.user, credential: exchanged.headless_credential });
     }
     else if (held && ownAgent !== null && ownAgent.user !== exchanged.user) {
         await forgetOwnAgent();
         process.stdout.write("This computer's own agent was another User's; run kit login again to connect it to you.\n");
     }
-    await placeAppGit(ownAgent, await readOwnAgent());
+    else if (held && ownAgent !== null) {
+        await writeOwnAgent({ house, ...relayRecord, user: ownAgent.user, credential: ownAgent.credential });
+    }
+    await placeAppGit(ownAgent, await readOwnAgent()).catch((error) => process.stderr.write(`kit: ${error.message}\n`));
     try {
         startService();
     }

package/dist/placement.js

@@ -0,0 +1,48 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { run } from './clis.js';
+import { kitHome } from './home.js';
+import { relayOrigin } from './relay.js';
+export function service() {
+    if (process.platform !== 'linux' || !process.env.INVOCATION_ID)
+        return null;
+    return process.env.MANAGERPID ? 'user' : 'system';
+}
+export function throughSudo() {
+    return service() === 'system' && process.getuid() !== 0;
+}
+export async function updatesItself() {
+    if (service() === null)
+        return false;
+    if (!throughSudo())
+        return true;
+    // sudo answers at once, so ten seconds only bounds a stuck sudo.
+    return (await run('sudo', ['-n', 'true'], 10_000)).status === 0;
+}
+function installed() {
+    try {
+        return readFileSync(join(kitHome(), 'placement'), 'utf8').trim();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function entries(house) {
+    const host = new URL(house).host;
+    const relay = relayOrigin();
+    if (relay === undefined)
+        return [`curl -fsSL ${host}/kit | sh`, `irm ${host}/kit.ps1 | iex`];
+    const entry = `${relay}/${host}/kit`;
+    return [`curl -fsSL ${entry} | HOUSE_KIT_RELAY=${relay} sh`, `$env:HOUSE_KIT_RELAY='${relay}'; irm ${entry}.ps1 | iex`];
+}
+export function installCommand(house) {
+    const [shell, windows] = entries(house);
+    const placement = installed();
+    if (placement === 'native')
+        return shell;
+    if (placement === 'server')
+        return `${shell} -s -- --linux`;
+    return `${shell} -s -- --container, or ${windows} on Windows`;
+}

package/dist/relay.js

@@ -2,7 +2,7 @@ let selected;
 export function selectRelay(relay) {
     selected = relay === undefined || relay === '' ? null : relay;
 }
-function relayOrigin() {
+export function relayOrigin() {
     if (selected !== undefined)
         return selected ?? undefined;
     const ambient = process.env.HOUSE_KIT_RELAY;

package/dist/resident.js

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'node:url';
 import { Agents } from './agents.js';
 import { house } from './api.js';
 import { received } from './bridge.js';
-import { Conversations } from './conversations.js';
+import { CONVERSATION_INPUTS, Conversations } from './conversations.js';
 import { LocalCopies } from './copies.js';
 import { restart } from './end.js';
 import { agentBase, enrolled, forgetRestart, kitHome, restartAsked } from './home.js';
@@ -84,7 +84,7 @@ export async function resident() {
     await placeSkillSet();
     await mkdir(agentBase(), { recursive: true });
     process.env.HOUSE_KIT_RESIDENT = String(process.pid);
-    const agents = new Agents(house);
+    const agents = new Agents(house, () => changed());
     const copies = new LocalCopies(house);
     await copies.load();
     await installShim(join(kitHome(), 'shim', 'git'), 'git-main');
@@ -92,7 +92,7 @@ export async function resident() {
     await serveOwner(copies);
     let stream = null;
     let reported = false;
-    const idle = () => conversations.idle() && signIns.idle();
+    const idle = () => conversations.idle() && signIns.idle() && agents.idle();
     const changed = () => {
         if (!idle()) {
             reported = false;
@@ -140,8 +140,12 @@ export async function resident() {
                     signIns.start(arrived);
                 else if (arrived.kind === 'update')
                     updates.start(arrived);
-                else
+                else if (CONVERSATION_INPUTS.has(arrived.kind))
                     conversations.input(arrived);
+                else {
+                    const refused = { refused: `This Kit does not know ${arrived.kind}; update the Kit` };
+                    logged(house.deliver(`/kit/inputs/${arrived.input_id}/ack`, refused).finally(changed));
+                }
             }
         },
     });

package/dist/skills.js

@@ -49,6 +49,14 @@ async function install() {
     await writeHome(RECORD, { version: KIT_VERSION, names });
 }
 export async function placeSkillSet() {
+    try {
+        await replaceSkillSet();
+    }
+    catch (error) {
+        process.stderr.write(`kit: the skills could not be placed: ${error.message}\n`);
+    }
+}
+async function replaceSkillSet() {
     const accepted = (await readConfiguration()).skills;
     const installed = await readHome(RECORD);
     if (accepted && installed?.version === KIT_VERSION)
@@ -63,7 +71,9 @@ export async function placeSkillSet() {
         await rm(join(kitHome(), RECORD), { force: true });
 }
 export async function createHowWeWork(bridge) {
-    if ((await readHome(RECORD)) === null || (await present(join(kitHome(), CREATED))))
+    if (!(await readConfiguration()).skills || (await readHome(RECORD))?.version === undefined)
+        return;
+    if (await present(join(kitHome(), CREATED)))
         return;
     const created = await bridge.tool('edit', { changes: [{ op: 'create', path: HOW_WE_WORK, content: HOW_WE_WORK_TEXT }] });
     if (created.isError === true) {

package/dist/stream.js

@@ -1,10 +1,11 @@
 import { subscribe } from 'node:diagnostics_channel';
 import { finalRefusal, HouseRefusal, retryDelay } from './api.js';
-import { end, REPLACED, signInAgain } from './end.js';
+import { end, REPLACED, signInAgain, updateRequired } from './end.js';
 import { readEnrolment } from './home.js';
 import { relayed } from './relay.js';
+import { KIT_WIRE, tooOld } from './wire.js';
 const PATH = '/kit/stream';
-const SUBPROTOCOL = 'house.kit.stream.1';
+const SUBPROTOCOL = `house.kit.stream.${KIT_WIRE}`;
 const REFUSAL_HEADER = 'x-house-refusal';
 function streamUrl(house) {
     const url = new URL(PATH, house);
@@ -56,6 +57,8 @@ export function holdStream(handlers) {
                 void signInAgain(credential);
                 return;
             }
+            if (refused !== null && tooOld(refused.text))
+                updateRequired(house);
             if (finalRefusal(refused))
                 end(refused.message);
             // A closed socket reopens in one to three seconds, spread so Kits one restart closed return apart; an opening House refused as retryable or left unanswered backs off on the jittered curve.

package/dist/update.js

@@ -4,8 +4,8 @@ import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { run } from './clis.js';
-import { kitHome } from './home.js';
-const RECORD = 'outcome=$1; shift; bash "$0" --linux "$@"; printf %s "$?" > "$outcome"; systemctl start house-kit.service';
+import { kitHome, workspaceRoot } from './home.js';
+import { service, throughSudo } from './placement.js';
 function logged(error) {
     process.stderr.write(`kit: ${error instanceof Error ? error.message : String(error)}\n`);
 }
@@ -21,6 +21,21 @@ function outcome() {
 function unit(inputId) {
     return `house-kit-update-${inputId}`;
 }
+function manager() {
+    return service() === 'user' ? ['--user'] : [];
+}
+function elevated() {
+    return throughSudo() ? ['sudo', '-n'] : [];
+}
+function account() {
+    return throughSudo() ? [`--uid=${process.getuid()}`, `--gid=${process.getgid()}`] : [];
+}
+function placement() {
+    return service() === 'user' ? ['--workspace', workspaceRoot()] : ['--linux'];
+}
+function record() {
+    return `outcome=$1; shift; bash "$0" "$@"; printf %s "$?" > "$outcome"; ${[...elevated(), 'systemctl', ...manager(), 'start', 'house-kit.service'].join(' ')}`;
+}
 async function pendingInput() {
     try {
         return JSON.parse(await readFile(pending(), 'utf8')).input_id;
@@ -41,7 +56,7 @@ async function finished(inputId) {
         if (ack !== null)
             return ack;
         // systemctl answers at once, so ten seconds only bounds a stuck service manager.
-        if ((await run('systemctl', ['is-active', '--quiet', unit(inputId)], 10_000)).status !== 0) {
+        if ((await run('systemctl', [...manager(), 'is-active', '--quiet', unit(inputId)], 10_000)).status !== 0) {
             return (await recorded()) ?? { refused: 'the Kit bootstrap did not finish' };
         }
         // The bootstrap runs for minutes, so checking each second sees its outcome within a second at little cost.
@@ -50,19 +65,26 @@ async function finished(inputId) {
 }
 function rerun(script, inputId, flags) {
     return new Promise((resolve) => {
-        const child = spawn('systemd-run', [
+        const [command, ...args] = [
+            ...elevated(),
+            'systemd-run',
+            ...manager(),
+            ...account(),
             '--wait',
             '--collect',
             '--quiet',
             `--unit=${unit(inputId)}`,
             `--setenv=HOME=${homedir()}`,
+            `--setenv=HOUSE_KIT_HOME=${kitHome()}`,
             '/bin/sh',
             '-c',
-            RECORD,
+            record(),
             script,
             outcome(),
+            ...placement(),
             ...flags,
-        ], { stdio: ['ignore', 'ignore', 'inherit'] });
+        ];
+        const child = spawn(command, args, { stdio: ['ignore', 'ignore', 'inherit'] });
         child.on('error', () => resolve({ refused: 'no service manager runs this Kit' }));
         child.on('close', () => resolve(null));
     });

package/dist/wire.js

@@ -0,0 +1,6 @@
+import { refusalOf } from './refusals.js';
+export const KIT_WIRE = 1;
+export const KIT_WIRE_HEADER = 'x-house-kit-wire';
+export function tooOld(text) {
+    return refusalOf(text)?.code === 'kit_update_required';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/kit",
-  "version": "0.2.1-cf669c6d1ecbb",
+  "version": "0.2.1-cfd9926e1dac7",
   "description": "House Kit connects an Environment to agents.house.",
   "license": "MIT",
   "repository": {