@agentshouse/kit 0.2.1-c96543a4c8b15 → 0.2.1-c9a26041e119a

package/dist/house-main.js

@@ -1,25 +1,29 @@
 #!/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 { extname, 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 { 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;
 const MEDIA_TYPES = new Map([
     ['avif', 'image/avif'],
@@ -48,49 +52,54 @@ const MEDIA_TYPES = new Map([
     ['xlsx', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
     ['zip', 'application/zip'],
 ]);
-function refused(path, status, text) {
+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);
@@ -112,36 +121,82 @@ 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));
+        return received;
+    throw new Error(refused(url, method, answer.status, received.toString('utf8'), false));
 }
-async function upload({ file, ...destination }) {
+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('upload needs "file", a local 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());
-    const answer = await called('upload', {
-        ...destination,
-        bytes: bytes.length,
-        sha256: createHash('sha256').update(bytes).digest('hex'),
-        ...(mediaType === undefined ? {} : { media_type: mediaType }),
-    });
+    return {
+        bytes,
+        description: {
+            bytes: bytes.length,
+            sha256: createHash('sha256').update(bytes).digest('hex'),
+            ...(mediaType === undefined ? {} : { media_type: mediaType }),
+        },
+    };
+}
+async function upload({ file, ...destination }) {
+    if (typeof file !== 'string' || file === '')
+        throw new Error('upload needs "file", a local file');
+    const { bytes, description } = await described(file);
+    const answer = await called('upload', { ...destination, ...description });
     const declared = parse(answer);
     if (declared.upload === undefined)
         return answer;
     const written = JSON.parse(await sent(declared.upload.url, bytes, declared.upload.operation));
     return stringify(written, { lineWidth: 0 }).trimEnd();
 }
+async function appendRecord(args) {
+    const held = new Map();
+    const attachments = Array.isArray(args.attachments)
+        ? await Promise.all(args.attachments.map(async (attachment) => {
+            if (typeof attachment !== 'string')
+                return attachment;
+            const { bytes, description } = await described(attachment);
+            held.set(description.sha256, bytes);
+            return { name: basename(attachment), ...description };
+        }))
+        : args.attachments;
+    const record = { ...args, attachments };
+    for (;;) {
+        const answer = await called('append_record', record);
+        const { upload } = parse(answer);
+        if (upload === undefined)
+            return answer;
+        for (const grant of upload)
+            await sent(grant.url, held.get(grant.sha256), grant.operation);
+    }
+}
 function unexpected(argument, usage) {
     return new Error(`unexpected argument ${argument}; ${usage}`);
 }
@@ -200,7 +255,7 @@ async function house(args) {
     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');
+        return [USAGE, 'help', PUSH, FETCH, DOWNLOAD, ...(await tools()).map((tool) => (tool.description === undefined ? tool.name : `${tool.name}: ${tool.description}`))].join('\n');
     }
     if (flags.has('--help')) {
         const tool = (await tools()).find((listed) => listed.name === verb);
@@ -209,7 +264,7 @@ async function house(args) {
         return [...(tool.description === undefined ? [] : [tool.description]), JSON.stringify(tool.inputSchema)].join('\n');
     }
     const parsed = argumentsOf(argument);
-    return verb === 'upload' ? upload(parsed) : called(verb, parsed);
+    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 });
@@ -221,7 +276,13 @@ async function called(name, args) {
 const argv = process.argv.slice(2);
 const named = argv.findIndex((arg) => !arg.startsWith('-'));
 const rest = argv.filter((_arg, index) => index !== named);
-(argv[named] === 'push' ? push(rest) : argv[named] === 'fetch' ? fetched(rest) : house(argv)).then((text) => {
+(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/instructions.js

@@ -1,36 +1,11 @@
 import { HOUSE_REF } from './git.js';
-import { HOW_WE_WORK } from './skills.js';
+import { readHowWeWork } from './skills.js';
 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*$/;
-const CUT = /^stderr: shell: output_cut (\d+) of \d+ bytes; continue with: (.+)$/;
-function cutOf(lines) {
-    const cut = CUT.exec(lines[0] ?? '');
-    return cut !== null && Buffer.byteLength(lines.slice(1).join('\n')) === Number(cut[1]) ? cut : null;
-}
-async function howWeWork(bridge) {
-    let document = '';
-    for (let command = `cat ${HOW_WE_WORK}`; command !== undefined;) {
-        const read = await bridge.tool('shell', { command });
-        const text = read.content.map((content) => content.text).join('\n');
-        const lines = text.split('\n');
-        if (read.isError === true || (FAILED.test(lines[0] ?? '') && lines[1]?.startsWith('stderr: '))) {
-            const refusal = read.isError === true ? text : lines.slice(1).join('\n').replace(/^stderr: /gm, '');
-            if (UNREADABLE.test(refusal))
-                return '';
-            throw new Error(refusal);
-        }
-        const cut = cutOf(lines);
-        document += lines.slice(cut === null ? 0 : 1).join('\n');
-        command = cut?.[2];
-    }
-    return document.replace(/\n$/, '');
-}
 export async function instructions(bridge, base, 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');
+    return [lines.join('\n'), base, (await readHowWeWork(bridge)).replace(/\n$/, '')].filter((part) => part !== '').join('\n\n');
 }

package/dist/kit-main.js

@@ -2,10 +2,11 @@
 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>\n';
+const USAGE = 'usage: kit <login|logout|resident|chatgpt>\n';
 const COMMANDS = new Map([
     [
         'logout',
@@ -40,6 +41,8 @@ setGlobalProxyFromEnv();
 async function run() {
     if (command === 'login')
         return login(argv);
+    if (command === 'chatgpt')
+        return chatgpt(argv);
     if (command === '--help') {
         parseArgs({ args: argv });
         process.stdout.write(USAGE);

package/dist/login.js

@@ -1,17 +1,17 @@
 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 { HouseRefusal, 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 { writeCodexRule } from './clis.js';
+import { forgetDisconnected, forgetOwnAgent, readDisconnected, readEnrolment, readOwnAgent, writeEnrolment, writeOwnAgent, } from './home.js';
 import { callHouse, rpc } from './mcp.js';
+import { refusalOf } from './refusals.js';
 import { selectRelay } from './relay.js';
 import { startService } from './service.js';
 import { placeSkillSet } from './skills.js';
-const DEFAULT_HOUSE = 'https://agents.house';
+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;
@@ -20,7 +20,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;
@@ -36,6 +36,9 @@ const USAGE = `usage: kit login [--house <origin>] [--environment <id>] [--rooms
   --no-private              give this Environment every Room but your Private Room
   --code <code>             connect this machine with a login code
 `;
+function gone(error) {
+    return error instanceof HouseRefusal && refusalOf(error.text)?.code === 'kit_environment_not_found';
+}
 function chosenRooms(rooms, noPrivate) {
     if (rooms !== undefined && noPrivate)
         throw new Error('--rooms and --no-private are two choices of Rooms; pass one');
@@ -74,7 +77,8 @@ export async function login(argv) {
     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 remembered = replaces === undefined && values.environment === undefined && enrolled?.house === house ? enrolled.environment : undefined;
+    const environment = replaces === undefined ? (values.environment ?? remembered) : undefined;
     const ownAgent = await readOwnAgent();
     let held = false;
     let exchanged;
@@ -84,47 +88,51 @@ export async function login(argv) {
     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', {
+        const start = (named) => retrying(() => post(house, '/kit', {
             label: hostname(),
-            ...(environment === undefined
+            ...(named === undefined
                 ? { act: 'new_environment', ...(replaces === undefined ? {} : { replaces }) }
-                : { act: 'existing_environment', environment_id: environment }),
+                : { act: 'existing_environment', environment_id: named }),
             ...rooms,
             code_challenge: createHash('sha256').update(verifier).digest('base64url'),
             ...(held ? {} : { headless: true }),
         }));
+        let started;
+        try {
+            started = await start(environment);
+        }
+        catch (error) {
+            if (remembered === undefined || !gone(error))
+                throw error;
+            await forgetDisconnected();
+            process.stdout.write(`House no longer holds Environment ${remembered}; connecting this computer as a new one.\n`);
+            started = await start(undefined);
+        }
         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 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

@@ -1,17 +1,31 @@
+import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { cp, lstat, mkdir, readdir, realpath, rm, symlink, writeFile } from 'node:fs/promises';
+import { cp, lstat, mkdir, readdir, realpath, rm, symlink } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { parse } from 'yaml';
 import { KIT_VERSION } from './clis.js';
 import { kitHome, readConfiguration, readHome, writeHome } from './home.js';
 import { refusalOf } from './refusals.js';
-export const HOW_WE_WORK = '/rooms/private/how-we-work.md';
+const HOW_WE_WORK = '/rooms/private/how-we-work.md';
 const SKILL_SET = fileURLToPath(new URL('../skills/', import.meta.url));
 const HOW_WE_WORK_TEXT = readFileSync(new URL('../how-we-work.md', import.meta.url), 'utf8');
+const SHIPPED_HOW_WE_WORK = [
+    'ae4dda60da7b174f22dc5fa9bf07fc27c25864932a74230de4f9f509ddd91f41',
+    '0bdcd43e1603ba6673a3cae56d70bbf90657cbeefd124e91a47be2ca1cbd6c93',
+    '4106a87ec66da6f7b2a10e74d18e6559d68d5f4fe7415dae68f5c7bdb9081968',
+    'ac814a2197038f037b657bb719340395f89f319ac9fcdd386629c3fe2cec68f1',
+    '29951ee394aad9979eecfed3e5dc32c2c86e2226b6a380db5dbd4f305f4d1156',
+];
 const RECORD = 'skill-set.json';
-const CREATED = 'how-we-work-created';
+const WRITTEN = 'how-we-work.json';
 const UNWRITABLE = new Set(['room_not_found', 'operation_denied']);
+const PRESENT = new Set(['path_exists']);
+const CHANGED = new Set(['base_revision_stale', 'path_absent']);
+const UNREADABLE = /^(?:\S+: )?(?:path_not_found|room_not_found|operation_denied)\b/;
+const FAILED = /^exit: [1-9]\d*$/;
+const CUT = /^stderr: shell: output_cut (\d+) of \d+ bytes; continue with: (.+)$/;
 function skillsDirectory() {
     return join(homedir(), '.agents', 'skills');
 }
@@ -49,6 +63,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)
@@ -62,17 +84,64 @@ export async function placeSkillSet() {
     else
         await rm(join(kitHome(), RECORD), { force: true });
 }
+function sha256(text) {
+    return createHash('sha256').update(text).digest('hex');
+}
+function cutOf(lines) {
+    const cut = CUT.exec(lines[0] ?? '');
+    return cut !== null && Buffer.byteLength(lines.slice(1).join('\n')) === Number(cut[1]) ? cut : null;
+}
+export async function readHowWeWork(bridge) {
+    let document = '';
+    for (let command = `cat ${HOW_WE_WORK}`; command !== undefined;) {
+        const read = await bridge.tool('shell', { command });
+        const text = read.content.map((content) => content.text).join('\n');
+        const lines = text.split('\n');
+        if (read.isError === true || (FAILED.test(lines[0] ?? '') && lines[1]?.startsWith('stderr: '))) {
+            const refusal = read.isError === true ? text : lines.slice(1).join('\n').replace(/^stderr: /gm, '');
+            if (UNREADABLE.test(refusal))
+                return '';
+            throw new Error(refusal);
+        }
+        const cut = cutOf(lines);
+        document += lines.slice(cut === null ? 0 : 1).join('\n');
+        command = cut?.[2];
+    }
+    return document;
+}
+async function currentRevision(bridge) {
+    const inspected = await bridge.tool('inspect', { path: HOW_WE_WORK });
+    const text = inspected.content.map((content) => content.text).join('\n');
+    if (inspected.isError === true)
+        throw new Error(text);
+    return parse(text).revisions[0].revision;
+}
+async function edit(bridge, change, kept) {
+    const edited = await bridge.tool('edit', { changes: [{ ...change, path: HOW_WE_WORK, content: HOW_WE_WORK_TEXT }] });
+    if (edited.isError !== true)
+        return 'written';
+    const text = edited.content.map((content) => content.text).join('\n');
+    const refusal = refusalOf(text);
+    if (UNWRITABLE.has(refusal?.code ?? ''))
+        return 'unwritable';
+    if (refusal?.code === 'edit_conflict' && refusal.conflicts.some((conflict) => kept.has(conflict)))
+        return 'kept';
+    throw new Error(text);
+}
 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;
+    const current = sha256(HOW_WE_WORK_TEXT);
+    if ((await readHome(WRITTEN)) === current)
+        return;
+    const created = await edit(bridge, { op: 'create' }, PRESENT);
+    if (created === 'unwritable')
         return;
-    const created = await bridge.tool('edit', { changes: [{ op: 'create', path: HOW_WE_WORK, content: HOW_WE_WORK_TEXT }] });
-    if (created.isError === true) {
-        const text = created.content.map((content) => content.text).join('\n');
-        const refusal = refusalOf(text);
-        if (UNWRITABLE.has(refusal?.code ?? ''))
+    if (created === 'kept') {
+        const base = await currentRevision(bridge);
+        const held = sha256(await readHowWeWork(bridge));
+        if (held !== current && SHIPPED_HOW_WE_WORK.includes(held) && (await edit(bridge, { op: 'replace', base }, CHANGED)) === 'unwritable')
             return;
-        if (refusal?.code !== 'edit_conflict' || !refusal.conflicts.includes('path_exists'))
-            throw new Error(text);
     }
-    await writeFile(join(kitHome(), CREATED), '');
+    await writeHome(WRITTEN, current);
 }