@agentshouse/kit 0.2.1-c5d36e97b0fea → 0.2.1-c96543a4c8b15

package/README.md

@@ -1,14 +1,12 @@
 # House Kit
 
-House Kit connects an Environment, a Linux computer or server, to
-[agents.house](https://agents.house). It runs your Agents' conversations
-through the agent CLIs you chose and gives each Agent the `house` command.
+House Kit connects an Environment, a Linux computer or server, to [agents.house](https://agents.house). It runs
+your Agents' conversations through the agent CLIs you chose and gives each Agent the `house` command.
 
 ## Install
 
-Run `curl -fsSL agents.house/kit | sh`, or `irm agents.house/kit.ps1 | iex` on
-Windows, and again to update; options follow `sh -s --`. On macOS and Linux it
-installs House Kit natively under your own account, without an admin password,
+Run `curl -fsSL agents.house/kit | sh`, or `irm agents.house/kit.ps1 | iex` on Windows, and again to update;
+options follow `sh -s --`. On macOS and Linux it installs House Kit natively under your own account, without an admin password,
 as a service that runs while you are logged in. `kit` and `house` are then on
 your login shell's `PATH`, and your workspace is `~/AgentsHouse` unless you
 pass `--workspace <path>`.
@@ -20,7 +18,7 @@ workspace. On Windows 11 the container is the one choice. Append a `kit` or
 Running the command for the other choice on a connected computer asks you to
 confirm, then replaces its Environment, whose Agents end, with a new one.
 
-On your own Ubuntu 26.04 server, run the Linux command with `--linux` to
+On your own Linux server, run the Linux command with `--linux` to
 install House Kit natively, with its workspace at `/agents/house`; `kit` and
 `house` are then on the server's `PATH`.
 
@@ -33,22 +31,24 @@ them out; running it again without the flag brings them back.
 
 ## Commands
 
-`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. Pass
-`--environment <id>` to reconnect an Environment you already have. It 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 the Rooms you chose for it
-as Git repositories under `local-copies` in the workspace. `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`.
+`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>`
+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.
+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. 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.
+
+`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 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

package/dist/agents.js

@@ -257,7 +257,7 @@ export class Agents {
     }
     async load(kind) {
         const known = this.readings.get(kind);
-        if (known !== undefined && known.failure === null)
+        if (known !== undefined && known.failure === null && known.minimum === undefined)
             return;
         await this.examine(kind, SIGNED_OUT, offer);
     }

package/dist/api.js

@@ -1,5 +1,5 @@
 import { setTimeout as delay } from 'node:timers/promises';
-import { end, SIGN_IN_AGAIN } from './end.js';
+import { signInAgain } from './end.js';
 import { readEnrolment } from './home.js';
 import { retryable } from './refusals.js';
 import { relayed } from './relay.js';
@@ -54,7 +54,7 @@ async function enrolledPost(path, body, signal) {
     }
     catch (error) {
         if (error instanceof HouseRefusal && error.status === 401)
-            end(SIGN_IN_AGAIN);
+            await signInAgain(credential);
         throw error;
     }
 }

package/dist/bootstrap.json

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

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

package/dist/conversations.js

@@ -132,6 +132,9 @@ export class Conversations {
             return false;
         return !conversations.some((conversation) => conversation.running?.scope.working() || [...conversation.leftovers].some((scope) => scope.working()));
     }
+    quiet() {
+        return this.idle() && [...this.conversations.values()].every((conversation) => conversation.open === 0);
+    }
     look() {
         for (const conversation of this.conversations.values()) {
             for (const scope of conversation.leftovers) {
@@ -499,7 +502,7 @@ export class Conversations {
         if (conversation.turn === turn)
             conversation.turn = null;
         const body = Promise.allSettled(turn.uploads).then(() => ({
-            parts: turn.parts.parts,
+            parts: turn.parts.saved(),
             context: turn.parts.context,
             ...failed,
         }));
@@ -644,7 +647,7 @@ export class Conversations {
                 turn.parts.plan(event.entries);
                 return;
             case 'image':
-                turn.uploads.push(this.image(conversation, turn, event.data, event.mediaType));
+                turn.uploads.push(this.image(conversation, turn, turn.parts.reserve(), event.data, event.mediaType));
                 this.kit.changed();
                 return;
         }
@@ -664,7 +667,7 @@ export class Conversations {
         else
             conversation.turn.parts.start(part);
     }
-    async image(conversation, turn, data, mediaType) {
+    async image(conversation, turn, reserved, data, mediaType) {
         const bytes = Buffer.from(data, 'base64');
         const name = `image-${++turn.images}.${mediaType.split('/')[1]}`;
         try {
@@ -677,10 +680,10 @@ export class Conversations {
             const saved = declared.upload === undefined ? declared : await uploadBytes(declared.upload, bytes);
             if (saved.save.status !== 'saved')
                 throw new Error(saved.save.failure ?? saved.save.status);
-            turn.parts.start({ type: 'image', file: saved.version, name, media_type: mediaType });
+            turn.parts.arrive({ type: 'image', file: saved.version, name, media_type: mediaType }, reserved);
         }
         catch (error) {
-            turn.parts.start({ type: 'marker', marker: 'retry', text: `${name} was not saved: ${causeOf(error)}` });
+            turn.parts.arrive({ type: 'marker', marker: 'retry', text: `${name} was not saved: ${causeOf(error)}` }, reserved);
         }
     }
 }

package/dist/copies.js

@@ -42,7 +42,7 @@ function expiredAuthority(error) {
         return undefined;
     try {
         const { error: refused } = JSON.parse(error.text);
-        return refused?.code === 'position_expired' && typeof refused.authority === 'string' ? refused.authority : undefined;
+        return refused?.code === 'expired' && typeof refused.authority === 'string' ? refused.authority : undefined;
     }
     catch {
         return undefined;
@@ -168,7 +168,7 @@ export class LocalCopies {
     house;
     copies = new Map();
     queues = new Map();
-    selecting = Promise.resolve();
+    answering = Promise.resolve();
     constructor(house) {
         this.house = house;
         this.owner = {
@@ -200,39 +200,39 @@ export class LocalCopies {
         }
     }
     async mapping() {
-        await this.selecting;
+        await this.answering;
         return [...this.copies.values()]
             .filter((copy) => copy.active)
             .map((copy) => `${rootOf(copy.room_handle)}: ${copy.repository}`)
             .sort();
     }
-    async select() {
-        const selected = await this.selected(() => this.fetched(false));
-        if (selected.refused)
-            logged(selected.text);
+    async connected() {
+        const copied = await this.answered(() => this.fetched(false));
+        if (copied.refused)
+            logged(copied.text);
     }
     fetch() {
-        return this.selected(() => this.fetched(true));
+        return this.answered(() => this.fetched(true));
     }
-    selected(work) {
-        const selected = this.selecting.then(work);
-        this.selecting = selected.catch(() => undefined);
-        return selected;
+    answered(work) {
+        const answered = this.answering.then(work);
+        this.answering = answered.catch(() => undefined);
+        return answered;
     }
     async fetched(refreshing) {
-        const { local_copy: chosen } = await this.house.post('/kit/local-copy/selection', {});
-        const selected = new Map(chosen.rooms.map((room) => [`rooms/${room.room_ref}`, room.room_handle]));
-        return this.holding([...new Set([...this.copies.keys(), ...selected.keys()])].sort(), async () => {
+        const { local_copy: answer } = await this.house.post('/kit/local-copy/selection', {});
+        const synced = new Map(answer.rooms.map((room) => [`rooms/${room.room_ref}`, room.room_handle]));
+        return this.holding([...new Set([...this.copies.keys(), ...synced.keys()])].sort(), async () => {
             const said = [];
             let refused = false;
             for (const copy of this.copies.values()) {
-                if (selected.has(copy.key) || !copy.active)
+                if (synced.has(copy.key) || !copy.active)
                     continue;
                 await this.save({ ...copy, active: false });
                 said.push(`${rootOf(copy.room_handle)}: no longer synced to this Environment; its files stay`);
             }
             const current = [];
-            for (const [key, handle] of selected) {
+            for (const [key, handle] of synced) {
                 try {
                     const held = this.copies.get(key);
                     if (held === undefined || !(await exists(held.repository))) {
@@ -623,7 +623,7 @@ export class LocalCopies {
                 const { upload, ...unstaged } = copy.push;
                 return this.settle(await this.save({ ...copy, push: unstaged }), caller, true);
             }
-            if (outcome.refused.code === 'operation_expired')
+            if (outcome.refused.code === 'expired')
                 return this.recovered(copy);
             const rebased = rebaseFixes(outcome.refused);
             let settled = await this.save(without(copy));

package/dist/end.js

@@ -1,8 +1,18 @@
+import { forgetRejected } from './home.js';
 import { killDescendants } from './scope.js';
 export const REPLACED = 'another Kit started for this Environment';
-export const SIGN_IN_AGAIN = 'sign in again';
-export function end(reason) {
+function exit(reason, status) {
     process.stderr.write(`kit: ${reason}\n`);
     killDescendants();
-    process.exit(0);
+    process.exit(status);
+}
+export function end(reason) {
+    exit(reason, 0);
+}
+export function restart(reason) {
+    exit(reason, 1);
+}
+export async function signInAgain(rejected) {
+    await forgetRejected(rejected);
+    restart('sign in again');
 }

package/dist/enrol-main.js

@@ -1,4 +1,10 @@
 import { readFileSync } from 'node:fs';
 import { writeEnrolment } from './home.js';
 const [house, environment] = process.argv.slice(2);
-await writeEnrolment({ house: house, environment: environment, credential: readFileSync(0, 'utf8').trim() });
+const relay = process.env.HOUSE_KIT_RELAY || undefined;
+await writeEnrolment({
+    house: house,
+    ...(relay === undefined ? {} : { relay }),
+    environment: environment,
+    credential: readFileSync(0, 'utf8').trim(),
+});

package/dist/home.js

@@ -1,11 +1,13 @@
-import { existsSync } from 'node:fs';
+import { existsSync, linkSync, readFileSync, renameSync, rmSync } from 'node:fs';
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { selectRelay } from './relay.js';
 const ENROLMENT = 'credential.json';
 const DISCONNECTED = 'disconnected.json';
 const CONFIGURATION = 'kit.json';
 const OWN_AGENT = 'own-agent.json';
+const RESTART = 'restart';
 export function kitHome() {
     return process.env.HOUSE_KIT_HOME ?? join(homedir(), '.house-kit');
 }
@@ -32,8 +34,11 @@ export async function writeHome(name, value) {
     await writeFile(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600 });
     await rename(temporary, join(home, name));
 }
-export function readEnrolment() {
-    return readHome(ENROLMENT);
+export async function readEnrolment() {
+    const enrolment = await readHome(ENROLMENT);
+    if (enrolment !== null)
+        selectRelay(process.env.HOUSE_KIT_RELAY || enrolment.relay);
+    return enrolment;
 }
 export async function writeEnrolment(enrolment) {
     await writeHome(ENROLMENT, enrolment);
@@ -46,9 +51,42 @@ export async function forgetEnrolment({ house, environment }) {
     await writeHome(DISCONNECTED, { house, environment });
     await rm(join(kitHome(), ENROLMENT), { force: true });
 }
+export async function forgetRejected(rejected) {
+    const held = await readHome(ENROLMENT);
+    if (held?.credential !== rejected)
+        return;
+    await writeHome(DISCONNECTED, { house: held.house, environment: held.environment });
+    const enrolment = join(kitHome(), ENROLMENT);
+    const taken = `${enrolment}.${process.pid}`;
+    try {
+        renameSync(enrolment, taken);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (JSON.parse(readFileSync(taken, 'utf8')).credential !== rejected) {
+        try {
+            linkSync(taken, enrolment);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        rmSync(join(kitHome(), DISCONNECTED), { force: true });
+    }
+    rmSync(taken);
+}
 export function enrolled() {
     return existsSync(join(kitHome(), ENROLMENT));
 }
+export function restartAsked() {
+    return existsSync(join(kitHome(), RESTART));
+}
+export function forgetRestart() {
+    return rm(join(kitHome(), RESTART), { force: true });
+}
 export function readOwnAgent() {
     return readHome(OWN_AGENT);
 }

package/dist/house-main.js

@@ -2,13 +2,13 @@
 import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { request, setGlobalProxyFromEnv } from 'node:http';
-import { basename, join } from 'node:path';
+import { extname, join } from 'node:path';
 import { HOUSE_REF } from './git.js';
-import { kitHome, readOwnAgent } from './home.js';
+import { kitHome, readEnrolment, 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 { 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";
@@ -21,6 +21,33 @@ const REVOKED = 'this conversation no longer has House access; nothing to do fro
 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 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, status, text) {
     const refusal = refusalOf(text);
     if (refusal !== null)
@@ -56,6 +83,7 @@ async function direct(message) {
     const ownAgent = await readOwnAgent();
     if (ownAgent === null)
         throw new Error(UNCONNECTED);
+    await readEnrolment();
     setGlobalProxyFromEnv();
     const answer = await callHouse(ownAgent.house, ownAgent.credential, message).catch(() => {
         throw new Error(UNREACHABLE);
@@ -97,28 +125,43 @@ async function sent(url, bytes, operation) {
         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),
+async function upload({ file, ...destination }) {
+    if (typeof file !== 'string' || file === '')
+        throw new Error('upload needs "file", a local file');
+    const bytes = await localFile(file);
+    const mediaType = MEDIA_TYPES.get(extname(file).slice(1).toLowerCase());
+    const answer = await called('upload', {
+        ...destination,
         bytes: bytes.length,
         sha256: createHash('sha256').update(bytes).digest('hex'),
-    }));
+        ...(mediaType === undefined ? {} : { media_type: mediaType }),
+    });
+    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();
+}
+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)
@@ -129,7 +172,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)
@@ -150,28 +193,23 @@ function argumentsOf(argument) {
         throw new Error(ARGUMENTS);
     return parsed;
 }
-async function house([verb, argument]) {
-    if (verb === undefined || verb === '--help' || verb === 'help') {
+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, ...(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) : called(verb, parsed);
 }
 async function called(name, args) {
     const result = await mcp('tools/call', { name, arguments: args });
@@ -181,7 +219,9 @@ 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) : 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/instructions.js

@@ -1,8 +1,9 @@
 import { HOUSE_REF } from './git.js';
 import { HOW_WE_WORK } from './skills.js';
-const HOUSE_LINE = 'Work with House through the `house` CLI: run `house --help`.';
-const FILE_LINE = 'To give the User a file or a page, upload it with `house upload` and link it; never start a server.';
-const READ_LINE = 'Before working in a Room, read `/rooms/private/rooms/<handle>/AGENTS.md`.';
+const SOURCE_LINE = "From House:";
+const HOUSE_LINE = "Work with House through the `house` CLI: run `house --help`, and `house find_command` for House's guides and formats.";
+const FILE_LINE = 'To give the User a file, upload it with `house upload` and link it; for an App, a Site or a website, follow `house find_command \'{"query":"app"}\'`. Never start a server.';
+const READ_LINE = "Optional per-Room instructions: `/rooms/private/rooms/<handle>/AGENTS.md`.";
 const COPIES_LINE = `House Local copies; before work run \`house fetch\` and rebase onto \`${HOUSE_REF}\`; after it commit, then \`house push\`:`;
 const UNREADABLE = /^(?:\S+: )?(?:path_not_found|room_not_found|operation_denied)\b/;
 const FAILED = /^exit: [1-9]\d*$/;
@@ -30,6 +31,6 @@ async function howWeWork(bridge) {
     return document.replace(/\n$/, '');
 }
 export async function instructions(bridge, base, copies) {
-    const lines = [HOUSE_LINE, FILE_LINE, READ_LINE, ...(copies.length === 0 ? [] : [COPIES_LINE, ...copies])];
+    const lines = [SOURCE_LINE, HOUSE_LINE, FILE_LINE, READ_LINE, ...(copies.length === 0 ? [] : [COPIES_LINE, ...copies])];
     return [lines.join('\n'), base, await howWeWork(bridge)].filter((part) => part !== '').join('\n\n');
 }

package/dist/kit-main.js

@@ -1,22 +1,64 @@
 #!/usr/bin/env node
 import { setGlobalProxyFromEnv } from 'node:http';
+import { parseArgs } from 'node:util';
 import { answerGitCredential } from './app-git.js';
 import { login } from './login.js';
 import { logout } from './logout.js';
 import { resident } from './resident.js';
+const USAGE = 'usage: kit <login|logout|resident>\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 === '--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

@@ -1,11 +1,16 @@
 import { spawn } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import { hostname } from 'node:os';
+import { delimiter, dirname } from 'node:path';
 import { parseArgs } from 'node:util';
 import { post, retrying } from './api.js';
 import { placeAppGit } from './app-git.js';
+import { allowHouseInCodex, loginPath } 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';
+import { placeSkillSet } from './skills.js';
 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.
@@ -23,39 +28,107 @@ 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]
+       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
+  --no-private              give this Environment every Room but your Private Room
+  --code <code>             connect this machine with a login code
+`;
+function chosenRooms(rooms, noPrivate) {
+    if (rooms !== undefined && noPrivate)
+        throw new Error('--rooms and --no-private are two choices of Rooms; pass one');
+    if (rooms !== undefined)
+        return { rooms: { reach: 'selected', refs: rooms.split(',') } };
+    return noPrivate ? { rooms: { reach: 'all_but_private' } } : {};
+}
 export async function login(argv) {
     const { values } = parseArgs({
         args: argv,
         options: {
             house: { type: 'string' },
             environment: { type: 'string' },
+            rooms: { type: 'string' },
+            'no-private': { type: 'boolean', default: false },
+            code: { type: 'string' },
+            help: { type: 'boolean', default: false },
         },
     });
+    if (values.help) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (values.code !== undefined && values.rooms !== undefined)
+        throw new Error('--code cannot be used with --rooms');
+    if (values.code !== undefined && values['no-private'])
+        throw new Error('--code cannot be used with --no-private');
+    if (values.code !== undefined && values.environment !== undefined)
+        throw new Error('--code cannot be used with --environment');
+    const rooms = chosenRooms(values.rooms, values['no-private']);
     const enrolled = (await readEnrolment()) ?? (await readDisconnected());
+    if (values.code !== undefined && enrolled !== null) {
+        throw new Error(`--code connects a new machine; this Kit home records Environment ${enrolled.environment}, so run kit login to reconnect it`);
+    }
+    const relay = process.env.HOUSE_KIT_RELAY || undefined;
+    selectRelay(relay);
     const house = values.house ?? enrolled?.house ?? DEFAULT_HOUSE;
     const replaces = process.env.HOUSE_KIT_REPLACES;
     const environment = replaces === undefined ? (values.environment ?? (enrolled?.house === house ? enrolled.environment : undefined)) : undefined;
     const ownAgent = await readOwnAgent();
-    const held = ownAgent !== null && ownAgent.house === house && (await accepted(house, ownAgent.credential));
-    const verifier = randomBytes(32).toString('base64url');
-    const started = await retrying(() => post(house, '/kit', {
-        ...(environment === undefined
-            ? { act: 'new_environment', label: hostname(), ...(replaces === undefined ? {} : { replaces }) }
-            : { act: 'existing_environment', environment_id: environment }),
-        code_challenge: createHash('sha256').update(verifier).digest('base64url'),
-        ...(held ? {} : { headless: true }),
-    }));
-    process.stdout.write(`Open this link and confirm: ${started.start_url}\n`);
-    open(started.start_url);
-    const exchanged = await retrying(() => post(house, '/kit/token', { login: started.login, code_verifier: verifier }), undefined, () => POLL_INTERVAL_MS);
-    await writeEnrolment({ house, environment: exchanged.environment, credential: exchanged.credential });
+    let held = false;
+    let exchanged;
+    if (values.code !== undefined) {
+        exchanged = await post(house, '/kit/token', { code: values.code, label: hostname() });
+    }
+    else {
+        held = ownAgent !== null && ownAgent.house === house && (await accepted(house, ownAgent.credential));
+        const verifier = randomBytes(32).toString('base64url');
+        const started = await retrying(() => post(house, '/kit', {
+            label: hostname(),
+            ...(environment === undefined
+                ? { act: 'new_environment', ...(replaces === undefined ? {} : { replaces }) }
+                : { act: 'existing_environment', environment_id: environment }),
+            ...rooms,
+            code_challenge: createHash('sha256').update(verifier).digest('base64url'),
+            ...(held ? {} : { headless: true }),
+        }));
+        process.stdout.write(`Open this link and confirm: ${started.start_url}\n`);
+        open(started.start_url);
+        exchanged = await retrying(() => post(house, '/kit/token', { login: started.login, code_verifier: verifier }), undefined, () => POLL_INTERVAL_MS);
+    }
+    try {
+        await placeSkillSet();
+    }
+    catch (error) {
+        process.stderr.write(`kit: the skills could not be placed: ${error.message}\n`);
+    }
+    try {
+        const shell = await loginPath().catch(() => '');
+        await allowHouseInCodex([dirname(process.execPath), process.env.PATH ?? '', shell].join(delimiter));
+    }
+    catch (error) {
+        process.stderr.write(`kit: Codex's rule for house could not be written: ${error.message}\n`);
+    }
+    await writeEnrolment({
+        house,
+        ...(relay === undefined ? {} : { relay }),
+        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 });
     }
-    else if (held && ownAgent.user !== exchanged.user) {
+    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());
+    try {
+        startService();
+    }
+    catch (error) {
+        process.stderr.write(`kit: ${error.message}\n`);
+    }
 }

package/dist/parts.js

@@ -2,7 +2,10 @@ export class Parts {
     parts = [];
     context = null;
     emit;
+    made = [];
+    events = 0;
     writing = null;
+    counting = null;
     planned = null;
     constructor(emit) {
         this.emit = emit;
@@ -10,32 +13,34 @@ export class Parts {
     write(type, id, text) {
         if (text === '')
             return;
-        const last = this.parts.length - 1;
-        const part = this.parts[last];
-        if (this.writing?.type === type && this.writing.id === id && part?.type === type) {
-            part.text += text;
-            this.emit({ op: 'append', index: last, text });
+        if (this.writing?.type === type && this.writing.id === id) {
+            this.parts[this.writing.index].text += text;
+            this.emit({ op: 'append', index: this.writing.index, text });
             return;
         }
-        this.start({ type, text });
-        this.writing = { type, id };
+        this.writing = { type, id, index: this.start({ type, text }) };
     }
     command() {
-        const last = this.parts.length - 1;
-        const part = this.parts[last];
-        if (part?.type !== 'commands') {
-            this.start({ type: 'commands', count: 1 });
+        if (this.counting === null) {
+            this.counting = this.start({ type: 'commands', count: 1 });
             return;
         }
+        const part = this.parts[this.counting];
         part.count++;
-        this.emit({ op: 'count', index: last, count: part.count });
+        this.emit({ op: 'count', index: this.counting, count: part.count });
     }
     start(part) {
         this.writing = null;
-        this.parts.push(part);
-        const index = this.parts.length - 1;
-        this.emit({ op: 'start', index, part });
-        return index;
+        this.counting = null;
+        return this.add(part, ++this.events);
+    }
+    reserve() {
+        this.writing = null;
+        this.counting = null;
+        return ++this.events;
+    }
+    arrive(part, reserved) {
+        this.add(part, reserved);
     }
     done(index, result) {
         const part = this.parts[index];
@@ -55,10 +60,23 @@ export class Parts {
         this.context = context;
         this.emit({ op: 'context', ...context });
     }
+    saved() {
+        return this.parts
+            .map((part, index) => ({ part, made: this.made[index] }))
+            .sort((a, b) => a.made - b.made)
+            .map(({ part }) => part);
+    }
     operations() {
         return [
             ...this.parts.map((part, index) => ({ op: 'start', index, part })),
             ...(this.context === null ? [] : [{ op: 'context', ...this.context }]),
         ];
     }
+    add(part, made) {
+        this.parts.push(part);
+        this.made.push(made);
+        const index = this.parts.length - 1;
+        this.emit({ op: 'start', index, part });
+        return index;
+    }
 }

package/dist/relay.js

@@ -1,7 +1,17 @@
+let selected;
+export function selectRelay(relay) {
+    selected = relay === undefined || relay === '' ? null : relay;
+}
+function relayOrigin() {
+    if (selected !== undefined)
+        return selected ?? undefined;
+    const ambient = process.env.HOUSE_KIT_RELAY;
+    return ambient === undefined || ambient === '' ? undefined : ambient;
+}
 export function relayed(target) {
     const url = new URL(target);
-    const relay = process.env.HOUSE_KIT_RELAY;
-    if (relay === undefined || relay === '')
+    const relay = relayOrigin();
+    if (relay === undefined)
         return url;
     const through = new URL(`${url.host}${url.pathname}${url.search}`, `${relay}/`);
     if (url.protocol === 'wss:' || url.protocol === 'ws:')

package/dist/resident.js

@@ -9,7 +9,8 @@ import { house } from './api.js';
 import { received } from './bridge.js';
 import { Conversations } from './conversations.js';
 import { LocalCopies } from './copies.js';
-import { agentBase, enrolled, kitHome } from './home.js';
+import { restart } from './end.js';
+import { agentBase, enrolled, forgetRestart, kitHome, restartAsked } from './home.js';
 import { killDescendants } from './scope.js';
 import { quoted } from './shell.js';
 import { SignIns } from './sign-in.js';
@@ -73,6 +74,7 @@ function connected() {
 }
 export async function resident() {
     await connected();
+    await forgetRestart();
     watch(kitHome(), () => {
         if (enrolled())
             return;
@@ -95,6 +97,9 @@ export async function resident() {
         if (!idle()) {
             reported = false;
         }
+        else if (restartAsked() && conversations.quiet()) {
+            restart('restarting for an updated CLI');
+        }
         else if (!reported) {
             reported = true;
             logged(house.deliver('/kit/idle', {}, idle));
@@ -122,7 +127,7 @@ export async function resident() {
         opened: () => {
             conversations.opened();
             changed();
-            logged(copies.select());
+            logged(copies.connected());
         },
         frame: (arrived) => {
             if (arrived.type === 'watching')

package/dist/service-main.js

@@ -0,0 +1,9 @@
+import { startService } from './service.js';
+try {
+    if (startService())
+        process.stdout.write('started\n');
+}
+catch (error) {
+    process.stderr.write(`kit: ${error.message}\n`);
+    process.exitCode = 1;
+}

package/dist/service.js

@@ -0,0 +1,33 @@
+import { spawnSync } from 'node:child_process';
+const UNIT = 'house-kit.service';
+// launchctl and systemctl answer at once, so ten seconds only bounds a stuck service manager.
+const MANAGER_MS = 10_000;
+function manage(command, args) {
+    return spawnSync(command, args, { encoding: 'utf8', timeout: MANAGER_MS });
+}
+function start(command, args) {
+    const started = manage(command, args);
+    if (started.status === 0)
+        return;
+    const cause = started.error?.message ?? (started.stderr.trim() || `${command} exited with ${started.status ?? 'a signal'}`);
+    throw new Error(`the House Kit service could not be started: ${cause}`);
+}
+export function startService() {
+    if (process.platform === 'darwin') {
+        const service = `gui/${process.getuid()}/house-kit`;
+        const printed = manage('launchctl', ['print', service]);
+        if (printed.status !== 0 || /^\tstate = running$/m.test(printed.stdout))
+            return false;
+        start('launchctl', ['kickstart', service]);
+        return true;
+    }
+    for (const scope of [['--user'], []]) {
+        if (manage('systemctl', [...scope, 'is-enabled', '--quiet', UNIT]).status !== 0)
+            continue;
+        if (manage('systemctl', [...scope, 'is-active', '--quiet', UNIT]).status === 0)
+            return false;
+        start('systemctl', [...scope, 'start', UNIT]);
+        return true;
+    }
+    return false;
+}

package/dist/stream.js

@@ -1,6 +1,6 @@
 import { subscribe } from 'node:diagnostics_channel';
 import { finalRefusal, HouseRefusal, retryDelay } from './api.js';
-import { end, REPLACED, SIGN_IN_AGAIN } from './end.js';
+import { end, REPLACED, signInAgain } from './end.js';
 import { readEnrolment } from './home.js';
 import { relayed } from './relay.js';
 const PATH = '/kit/stream';
@@ -52,8 +52,10 @@ export function holdStream(handlers) {
             process.stderr.write(`kit: control stream closed ${event.code} ${event.reason}\n`);
             if (event.reason === 'replaced')
                 end(REPLACED);
-            if (event.reason === 'credential_rejected' || refused?.status === 401)
-                end(SIGN_IN_AGAIN);
+            if (event.reason === 'credential_rejected' || refused?.status === 401) {
+                void signInAgain(credential);
+                return;
+            }
             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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/kit",
-  "version": "0.2.1-c5d36e97b0fea",
+  "version": "0.2.1-c96543a4c8b15",
   "description": "House Kit connects an Environment to agents.house.",
   "license": "MIT",
   "repository": {
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.7.0",
-    "@agentshouse/mdmodel": "0.1.0-alpha.19",
+    "@agentshouse/mdmodel": "0.1.0-c68e2039f1ca8",
     "yaml": "2.9.1"
   },
   "peerDependencies": {