@agentshouse/kit 0.2.1-alpha.10 → 0.2.1-alpha.12

package/dist/agents.js

@@ -1,21 +1,64 @@
 import { client } from '@agentclientprotocol/sdk';
 import { readFile } from 'node:fs/promises';
-import { startAdapter } from './acp.js';
+import { killTree, startAdapter } from './acp.js';
 import { CLIS, KIT_VERSION, cliCommand, install, run } from './clis.js';
 import { kitHome } from './home.js';
-async function signedIn(kind) {
-    const probe = CLIS[kind].signedIn;
-    if ('command' in probe) {
-        return (await run(cliCommand(kind), probe.command, 30_000)).status === 0;
+const SIGNED_OUT = { signed_in: false, models: [] };
+function select(options, category) {
+    const option = options.find((candidate) => candidate.category === category);
+    return option?.type === 'select' ? option : undefined;
+}
+function values(options) {
+    return options.flatMap((entry) => ('group' in entry ? entry.options : [entry])).map((entry) => entry.value);
+}
+function causeOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function models(kind, adapter, known) {
+    const agent = adapter.connection.agent;
+    const opened = await agent.request('session/new', { cwd: kitHome(), mcpServers: [] });
+    let options = opened.configOptions ?? [];
+    const model = select(options, 'model');
+    if (model === undefined)
+        return [];
+    const offered = [];
+    for (const value of values(model.options)) {
+        if (select(options, 'model')?.currentValue !== value) {
+            try {
+                options = (await agent.request('session/set_config_option', { sessionId: opened.sessionId, configId: model.id, value })).configOptions;
+            }
+            catch (error) {
+                process.stderr.write(`kit: ${kind} refused its model ${value}: ${causeOf(error)}\n`);
+                offered.push({ model: value, efforts: known.find((entry) => entry.model === value)?.efforts ?? [] });
+                continue;
+            }
+        }
+        const effort = select(options, 'thought_level');
+        offered.push({ model: value, efforts: effort === undefined ? [] : values(effort.options) });
     }
+    return offered;
+}
+async function offer(kind, known) {
+    const probe = CLIS[kind].signedIn;
+    if ('command' in probe && (await run(cliCommand(kind), probe.command, 30_000)).status !== 0)
+        return SIGNED_OUT;
+    let adapter;
     try {
-        const adapter = await startAdapter(kind, kitHome(), client({ name: '@agentshouse/kit' }));
-        adapter.child.kill('SIGKILL');
-        const method = adapter.initialized._meta?.[probe.initializeMeta];
-        return typeof method === 'string' && method.length > 0;
+        adapter = await startAdapter(kind, kitHome(), client({ name: '@agentshouse/kit' }));
+        if ('initializeMeta' in probe) {
+            const method = adapter.initialized._meta?.[probe.initializeMeta];
+            if (typeof method !== 'string' || method.length === 0)
+                return SIGNED_OUT;
+        }
+        return { signed_in: true, models: await models(kind, adapter, known.models) };
+    }
+    catch (error) {
+        process.stderr.write(`kit: ${kind} did not offer its models: ${causeOf(error)}\n`);
+        return adapter === undefined && 'initializeMeta' in probe ? known : { signed_in: true, models: known.models };
     }
-    catch {
-        return false;
+    finally {
+        if (adapter !== undefined)
+            killTree(adapter.child);
     }
 }
 async function sshHostKey() {
@@ -31,9 +74,12 @@ export class Agents {
     house;
     reading = Promise.resolve();
     installing = Promise.resolve();
-    releases = new Map();
+    installs = new Map();
+    offers = new Map();
     reporting = null;
     again = false;
+    sending = Promise.resolve();
+    sent = null;
     constructor(house) {
         this.house = house;
     }
@@ -62,24 +108,36 @@ export class Agents {
             this.again = true;
         return Promise.all([installing, this.reporting]).then(() => undefined);
     }
-    async report() {
+    report() {
+        const sending = this.sending.catch(() => undefined).then(() => this.send());
+        this.sending = sending;
+        return sending;
+    }
+    async send() {
         const agents = [];
-        for (const [kind, release] of this.releases) {
-            agents.push({ kind, release, signed_in: release !== null && (await signedIn(kind)) });
+        for (const [kind, installed] of this.installs) {
+            const offered = installed.release === null ? SIGNED_OUT : await offer(kind, this.offers.get(kind) ?? SIGNED_OUT);
+            this.offers.set(kind, offered);
+            agents.push({ kind, ...installed, ...offered });
         }
         const hostKey = await sshHostKey();
-        await this.house.deliver('/kit/agents/report', {
+        const body = {
             os: await operatingSystem(),
             kit_version: KIT_VERSION,
             agents,
             ...(hostKey === null ? {} : { ssh_host_key: hostKey }),
-        });
+        };
+        const state = JSON.stringify(body);
+        if (state === this.sent)
+            return;
+        await this.house.deliver('/kit/agents/report', body);
+        this.sent = state;
     }
     async install(kinds) {
-        const releases = new Map();
+        const installs = new Map();
         for (const kind of kinds)
-            releases.set(kind, await install(kind));
-        this.releases = releases;
+            installs.set(kind, await install(kind));
+        this.installs = installs;
     }
     async reports() {
         try {

package/dist/api.js

@@ -8,6 +8,9 @@ export class HouseRefusal extends Error {
         this.text = text;
     }
 }
+export function retryDelay(attempt) {
+    return Math.min(30_000, 1000 * 2 ** attempt);
+}
 export async function post(house, path, body, credential, signal) {
     const answer = await fetch(new URL(path, house), {
         method: 'POST',
@@ -38,7 +41,7 @@ export const house = {
                 if (error instanceof HouseRefusal && error.status < 500)
                     throw error;
                 process.stderr.write(`kit: ${path} did not reach House: ${error.message}\n`);
-                await new Promise((resolve) => setTimeout(resolve, Math.min(30_000, 1000 * 2 ** attempt)));
+                await new Promise((resolve) => setTimeout(resolve, retryDelay(attempt)));
                 if (!current())
                     throw error;
             }

package/dist/bootstrap.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "version": "0.2.1-alpha.10",
+  "version": "0.2.1-alpha.12",
   "hosts": {
     "linux": {
-      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.2.1-alpha.10/connect-linux.sh)",
+      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.2.1-alpha.12/connect-linux.sh)",
       "asset": {
         "name": "connect-linux.sh",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-alpha.10/connect-linux.sh"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-alpha.12/connect-linux.sh"
       },
       "workspace": {
         "argument": "--workspace",
@@ -14,10 +14,10 @@
       }
     },
     "windows": {
-      "command": "& ([scriptblock]::Create((irm https://github.com/agentshouse/kit/releases/download/v0.2.1-alpha.10/connect-windows.ps1)))",
+      "command": "& ([scriptblock]::Create((irm https://github.com/agentshouse/kit/releases/download/v0.2.1-alpha.12/connect-windows.ps1)))",
       "asset": {
         "name": "connect-windows.ps1",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-alpha.10/connect-windows.ps1"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.2.1-alpha.12/connect-windows.ps1"
       },
       "workspace": {
         "argument": "--workspace",

package/dist/bridge.js

@@ -1,17 +1,20 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { once } from 'node:events';
+import { setTimeout as delay } from 'node:timers/promises';
 import { mkdir } from 'node:fs/promises';
 import { createServer, request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { delimiter, join } from 'node:path';
 import { parse } from 'yaml';
+import { HouseRefusal, retryDelay } from './api.js';
 import { KIT_VERSION } from './clis.js';
-import { changedPaths, refusalCode, } from './copies.js';
+import { changedPaths, } from './copies.js';
 import { kitHome, readEnrolment } from './home.js';
-import { operationId } from './operation.js';
+import { operationId, uuidOf } from './operation.js';
+import { refusalOf } from './refusals.js';
 const MCP_PROTOCOL_VERSION = '2026-07-28';
 const MCP_REQUEST_BYTES = 4 * 1024 * 1024;
-const FORWARDED = new Set(['/', '/kit/attachments/upload']);
+const ATTACHMENTS = '/kit/attachments/upload';
 export async function received(request) {
     let text = '';
     request.setEncoding('utf8');
@@ -31,16 +34,45 @@ function relay(request, response, target, authorization) {
     forwarded.on('error', () => response.destroy());
     request.pipe(forwarded);
 }
+const UNREACHABLE = 'House is unreachable; call again in a minute';
+function refusalIn(text, status) {
+    return refusalOf(text) ?? { code: '', text: text === '' ? `House refused it with ${status}` : text, conflicts: [] };
+}
 function answered(forwarded) {
     if (forwarded.status >= 500)
-        throw new Error(`House answered ${forwarded.status}`);
+        throw new HouseRefusal('/', forwarded.status, forwarded.text);
     if (forwarded.status !== 200)
-        return { refused: { code: refusalCode(forwarded.text), text: forwarded.text } };
+        return { refused: refusalIn(forwarded.text, forwarded.status) };
     const answer = JSON.parse(forwarded.text);
     if (answer.error !== undefined)
-        return { refused: { code: refusalCode(answer.error.message), text: answer.error.message } };
+        return { refused: refusalIn(answer.error.message, forwarded.status) };
     const text = answer.result.content.map((content) => content.text).join('\n');
-    return answer.result.isError === true ? { refused: { code: refusalCode(text), text } } : { text };
+    return answer.result.isError === true ? { refused: refusalIn(text, forwarded.status) } : { text };
+}
+function pendingSeconds(forwarded) {
+    if (forwarded.status !== 200)
+        return null;
+    const { result } = JSON.parse(forwarded.text);
+    if (result === undefined || result.isError === true)
+        return null;
+    const text = result.content.map((content) => content.text).join('\n');
+    if (!text.startsWith('{"pending":'))
+        return null;
+    const seconds = JSON.parse(text).pending.retry_after;
+    return typeof seconds === 'number' ? seconds : null;
+}
+function resendAfter(forwarded, attempt) {
+    if (forwarded === null)
+        return retryDelay(attempt);
+    if (forwarded.status >= 500)
+        return refusalOf(forwarded.text) === null ? retryDelay(attempt) : null;
+    const seconds = pendingSeconds(forwarded);
+    return seconds === null ? null : seconds * 1000;
+}
+function versioned(conversationId, text) {
+    const file = JSON.parse(text);
+    const identity = JSON.stringify([conversationId, file.room_ref ?? null, file.name, file.sha256]);
+    return JSON.stringify({ ...file, version: uuidOf(createHash('sha256').update(identity).digest(), 8) });
 }
 function editAnswer(forwarded) {
     const answer = answered(forwarded);
@@ -50,7 +82,7 @@ function editAnswer(forwarded) {
     return {
         accepted: results.flatMap((result) => [
             ...(result.from === undefined ? [] : [{ path: result.from, revision: null, content: null }]),
-            { path: result.path, revision: result.op === 'remove' ? null : result.revision },
+            { path: result.path, revision: result.revision ?? null },
         ]),
     };
 }
@@ -70,7 +102,7 @@ export async function openBridge(house, copies, conversationId, signal) {
             },
         },
     });
-    const send = async (message, operation) => {
+    const sent = async (message, operation) => {
         const tool = message.method === 'tools/call' ? String(message.params?.name) : null;
         const answer = await fetch(new URL('/', origin), {
             method: 'POST',
@@ -87,7 +119,22 @@ export async function openBridge(house, copies, conversationId, signal) {
         });
         return { status: answer.status, text: await answer.text() };
     };
-    const call = (name, args) => ({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } });
+    const send = async (message, operation) => {
+        if (operation === null)
+            return sent(message, null);
+        for (let attempt = 0;; attempt++) {
+            const forwarded = await sent(message, operation).catch((error) => {
+                if (closed.signal.aborted)
+                    throw error;
+                return null;
+            });
+            const after = resendAfter(forwarded, attempt);
+            if (after === null)
+                return forwarded;
+            await delay(after, undefined, { signal: closed.signal });
+        }
+    };
+    const call = (name, args) => ({ jsonrpc: '2.0', id: randomUUID(), method: 'tools/call', params: { name, arguments: args } });
     const staged = async (operation, changes) => {
         const bytes = Buffer.from(JSON.stringify({ changes }));
         const sha256 = createHash('sha256').update(bytes).digest('hex');
@@ -106,24 +153,35 @@ export async function openBridge(house, copies, conversationId, signal) {
         });
         const text = await posted.text();
         if (posted.status >= 500)
-            throw new Error(`House answered ${posted.status}`);
+            throw new HouseRefusal('/', posted.status, text);
         if (!posted.ok)
-            return { refused: { code: refusalCode(text), text } };
+            return { refused: refusalIn(text, posted.status) };
         const held = JSON.parse(text).transfer;
         return { url: held.url, operation: held.operation, bytes: bytes.length, sha256 };
     };
+    let mutations = null;
+    const writes = async (tool) => {
+        mutations ??= house
+            .post('/kit/tools/mutations', {}, closed.signal)
+            .then(({ tools }) => new Set(tools.filter((listed) => listed.writes).map((listed) => listed.name)));
+        try {
+            return (await mutations).has(tool);
+        }
+        catch (error) {
+            mutations = null;
+            throw error;
+        }
+    };
     const forward = async (path, text) => {
         if (path === '/') {
             const message = JSON.parse(text);
             const tool = message.method === 'tools/call' ? String(message.params?.name) : null;
-            const writes = tool !== null &&
-                (await house.post('/kit/tools/mutations', {}, closed.signal)).tools.some((listed) => listed.name === tool && listed.writes);
-            return send(message, writes ? operationId() : null);
+            return send(message, tool !== null && (await writes(tool)) ? operationId() : null);
         }
         const answer = await fetch(new URL(path, origin), {
             method: 'POST',
             headers: { 'content-type': 'application/json', authorization: `Bearer ${credential}` },
-            body: text,
+            body: versioned(conversationId, text),
             signal: closed.signal,
         });
         return { status: answer.status, text: await answer.text() };
@@ -152,7 +210,7 @@ export async function openBridge(house, copies, conversationId, signal) {
             await copies.observed(JSON.parse(text));
             return { status: 200, text: '{}' };
         }
-        return FORWARDED.has(path) ? forward(path, text) : { status: 404, text: '' };
+        return path === '/' || path === ATTACHMENTS ? forward(path, text) : { status: 404, text: '' };
     };
     const sockets = join(kitHome(), 'bridges');
     await mkdir(sockets, { recursive: true, mode: 0o700 });
@@ -168,7 +226,11 @@ export async function openBridge(house, copies, conversationId, signal) {
             response.writeHead(answered.status, { 'content-type': 'application/json' }).end(answered.text);
         }
         catch (error) {
-            response.writeHead(502).end(error instanceof Error ? error.message : String(error));
+            if (error instanceof HouseRefusal) {
+                response.writeHead(error.status, { 'content-type': 'application/json' }).end(error.text);
+                return;
+            }
+            response.writeHead(502).end(request.url === '/git/push' && error instanceof Error ? error.message : UNREACHABLE);
         }
     });
     bridge.listen(socketPath);
@@ -195,7 +257,7 @@ export async function openBridge(house, copies, conversationId, signal) {
             GIT_CONFIG_VALUE_0: app,
         },
         tool: async (name, args) => {
-            const forwarded = await forward('/', JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } }));
+            const forwarded = await forward('/', JSON.stringify({ jsonrpc: '2.0', id: randomUUID(), method: 'tools/call', params: { name, arguments: args } }));
             if (forwarded.status !== 200)
                 throw new Error(`House refused ${name} with ${forwarded.status}: ${forwarded.text}`);
             const answer = JSON.parse(forwarded.text);

package/dist/clis.js

@@ -20,6 +20,14 @@ function asyncTask({ method, params }) {
     }
     return null;
 }
+function airPhase({ _meta }) {
+    const phase = _meta?.jetbrains?.air?.phase;
+    if (phase === 'commentary')
+        return 'note';
+    if (phase === 'final_answer')
+        return 'answer';
+    return null;
+}
 export const CLIS = {
     'codex-acp': {
         package: '@agentclientprotocol/codex-acp',
@@ -31,6 +39,7 @@ export const CLIS = {
         turnStarted: (notice) => threadStatus(notice) === 'active',
         turnEnded: (notice) => threadStatus(notice) === 'idle',
         job: asyncTask,
+        phase: airPhase,
     },
     'claude-agent-acp': {
         package: '@agentclientprotocol/claude-agent-acp',
@@ -44,6 +53,7 @@ export const CLIS = {
             params?.update?.sessionUpdate === 'usage_update' &&
             params.update._meta?.['_claude/origin'] !== undefined,
         job: asyncTask,
+        phase: () => null,
     },
     'grok-build': {
         package: '@xai-official/grok',
@@ -61,6 +71,7 @@ export const CLIS = {
                 return { id: params.update.task_snapshot.task_id, running: false };
             return null;
         },
+        phase: () => null,
     },
 };
 const KIT_PACKAGE = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
@@ -104,11 +115,12 @@ export function run(command, args, timeoutMs) {
 export async function install(kind) {
     const release = pinned(kind);
     if ((await installedRelease(kind)) === release)
-        return release;
+        return { release, failure: null };
     const ran = await run('npm', ['install', '--prefix', prefix(kind), '--no-save', '--no-audit', '--no-fund', `${CLIS[kind].package}@${release}`], 15 * 60_000);
     if (ran.status !== 0) {
-        process.stderr.write(`kit: ${kind} did not install: ${ran.output.trim()}\n`);
-        return null;
+        const failure = ran.output.trim() || `npm exited with ${ran.status ?? 'a signal'}`;
+        process.stderr.write(`kit: ${kind} did not install: ${failure}\n`);
+        return { release: null, failure };
     }
-    return installedRelease(kind);
+    return { release: await installedRelease(kind), failure: null };
 }

package/dist/conversations.js

@@ -36,6 +36,9 @@ function stop(bridge) {
 class Turn {
     id = randomUUID();
     text = '';
+    segment = null;
+    admitted = false;
+    notes = [];
     sent = [];
     unsentFrom = null;
     draftSequence = 0;
@@ -272,6 +275,7 @@ export class Conversations {
                 sessionId: opened.sessionId,
                 killed: false,
                 queues: CLIS[route.kind].queues,
+                phase: CLIS[route.kind].phase,
             };
             const options = await this.launchSettings(running, route, opened.configOptions ?? []);
             conversation.running = running;
@@ -359,6 +363,9 @@ export class Conversations {
         return turn;
     }
     admitted(conversation, turn) {
+        turn.admitted = true;
+        for (const note of turn.notes.splice(0))
+            this.kit.send(note);
         if (turn.text !== '') {
             turn.unsentFrom = 0;
             this.draft(conversation, turn);
@@ -372,6 +379,17 @@ export class Conversations {
         this.kit.changed();
         return turn;
     }
+    finish(conversation, turn) {
+        if (turn.ended)
+            return;
+        const segment = turn.segment;
+        turn.segment = null;
+        if (segment?.phase === 'note')
+            this.note(conversation, turn, segment.text);
+        else if (segment !== null)
+            this.answer(conversation, turn, segment.text);
+        this.end(conversation, turn, { text: turn.text });
+    }
     end(conversation, turn, outcome) {
         if (turn.ended)
             return;
@@ -429,7 +447,7 @@ export class Conversations {
                 this.end(conversation, turn, { failed });
         }
         else if (turn.prompt === sent) {
-            this.end(conversation, turn, { text: turn.text });
+            this.finish(conversation, turn);
         }
     }
     started(conversation) {
@@ -446,7 +464,7 @@ export class Conversations {
         if (turn === null)
             return;
         if (turn.prompt === null) {
-            this.end(conversation, turn, { text: turn.text });
+            this.finish(conversation, turn);
         }
         else {
             conversation.turn = null;
@@ -500,17 +518,21 @@ export class Conversations {
     update(conversation, notification) {
         const update = notification.update;
         if (update.sessionUpdate === 'agent_message_chunk' && update.content.type === 'text') {
-            const turn = this.started(conversation);
-            turn.text += update.content.text;
-            this.draft(conversation, turn);
+            this.chunk(conversation, this.started(conversation), update, update.content.text);
         }
         else if (update.sessionUpdate === 'plan') {
             const turn = this.started(conversation);
+            this.close(conversation, turn);
             turn.entries = update.entries;
             this.plan(conversation, turn);
         }
-        else if (update.sessionUpdate === 'agent_thought_chunk' || update.sessionUpdate === 'tool_call') {
-            this.started(conversation);
+        else if (update.sessionUpdate === 'tool_call') {
+            this.close(conversation, this.started(conversation));
+        }
+        else if (update.sessionUpdate === 'agent_thought_chunk') {
+            const turn = this.started(conversation);
+            if (turn.segment?.messageId !== (update.messageId ?? null))
+                this.close(conversation, turn);
         }
         else if (update.sessionUpdate === 'available_commands_update') {
             this.commands(conversation, update.availableCommands);
@@ -526,6 +548,38 @@ export class Conversations {
             conversation.jobs.delete(job.id);
         this.kit.changed();
     }
+    chunk(conversation, turn, chunk, text) {
+        const phase = conversation.running?.phase(chunk) ?? null;
+        const messageId = chunk.messageId ?? null;
+        if (turn.segment?.messageId !== messageId || turn.segment.phase !== phase)
+            this.close(conversation, turn);
+        if (phase === 'answer') {
+            this.answer(conversation, turn, text);
+            return;
+        }
+        turn.segment ??= { messageId, phase, text: '' };
+        turn.segment.text += text;
+    }
+    close(conversation, turn) {
+        const segment = turn.segment;
+        if (segment === null)
+            return;
+        turn.segment = null;
+        this.note(conversation, turn, segment.text);
+    }
+    note(conversation, turn, text) {
+        if (text.trim() === '')
+            return;
+        const note = { type: 'working-note', conversation_id: conversation.id, note_id: randomUUID(), text };
+        if (turn.admitted)
+            this.kit.send(note);
+        else
+            turn.notes.push(note);
+    }
+    answer(conversation, turn, text) {
+        turn.text += text;
+        this.draft(conversation, turn);
+    }
     draft(conversation, turn) {
         const blocks = blocksOf(turn.text);
         const from = Math.min(firstChange(turn.sent, blocks), turn.unsentFrom ?? Infinity);

package/dist/copies.js

@@ -6,6 +6,7 @@ import { HouseRefusal } from './api.js';
 import { blobId, blobText, git, HOUSE_REF, importCommits, revision, run, succeeded, tree, WORKING_COPIES, } from './git.js';
 import { kitHome } from './home.js';
 import { operationId } from './operation.js';
+import { refusalOf } from './refusals.js';
 import { changed } from './translate.js';
 const BRANCH = 'main';
 const ROOM_HOMES = ['capture', 'library', 'collaboration'];
@@ -18,13 +19,16 @@ function causeOf(error) {
 function logged(error) {
     process.stderr.write(`kit: ${causeOf(error)}\n`);
 }
-export function refusalCode(text) {
-    try {
-        return String(JSON.parse(text).error.code);
-    }
-    catch {
-        return text.split(':')[0].trim();
-    }
+const REBASED = new Set([
+    'field_base_stale',
+    'section_base_stale',
+    'preamble_base_stale',
+    'base_revision_stale',
+    'path_exists',
+    'path_absent',
+]);
+function rebaseFixes(refusal) {
+    return refusal.code === 'edit_conflict' && refusal.conflicts.some((code) => REBASED.has(code));
 }
 function short(commit) {
     return commit.slice(0, 12);
@@ -166,7 +170,9 @@ export class WorkingCopies {
                 catch (error) {
                     if (!(error instanceof HouseRefusal) || error.status >= 500)
                         throw error;
-                    return { refused: { code: refusalCode(error.text), text: error.message } };
+                    return {
+                        refused: refusalOf(error.text) ?? { code: '', text: `House refused it with ${error.status}`, conflicts: [] },
+                    };
                 }
             },
         };
@@ -253,11 +259,11 @@ export class WorkingCopies {
     async push(cwd, selector, caller) {
         const located = await run(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir', '--show-toplevel']);
         if (located.status !== 0)
-            return { refused: true, text: `${cwd} is not in a Git repository` };
+            return { refused: true, text: `${cwd} is not a House working copy; run house git push inside one` };
         const [common, worktree] = located.stdout.toString('utf8').split('\n');
         const key = await this.keyAt(dirname(common));
         if (key === undefined)
-            return { refused: true, text: `${worktree} is not a House working copy` };
+            return { refused: true, text: `${worktree} is not a House working copy; run house git push inside one` };
         return this.exclusive(key, () => this.pushed(key, worktree, selector, caller));
     }
     async keyAt(repository) {
@@ -437,7 +443,7 @@ export class WorkingCopies {
                 });
             }
             catch (error) {
-                const code = error instanceof HouseRefusal ? refusalCode(error.text) : null;
+                const code = error instanceof HouseRefusal ? (refusalOf(error.text)?.code ?? null) : null;
                 if (code === 'position_expired')
                     return this.received(copy);
                 if (code !== 'replica_behind')
@@ -512,8 +518,9 @@ export class WorkingCopies {
             }
             copy = await this.save(without(copy));
         }
-        if (!copy.active)
-            return { refused: true, text: `${rootOf(copy)} is no longer kept in this Environment` };
+        if (!copy.active) {
+            return { refused: true, text: `${rootOf(copy)} is no longer synced to this Environment, so House takes no push from it` };
+        }
         const listed = (await git(copy.repository, ['rev-list', '--topo-order', commit])).split('\n');
         const base = listed.find((ancestor) => ancestor in copy.manifests);
         if (base === undefined) {
@@ -582,9 +589,8 @@ export class WorkingCopies {
     async settle(start, caller, restaged = false) {
         let copy = start;
         const push = copy.push;
-        if (push.caller !== caller.key) {
-            return this.recovered(copy, `${short(push.commit)} was pushed by another caller and awaited its outcome`);
-        }
+        if (push.caller !== caller.key)
+            return this.recovered(copy);
         let outcome;
         try {
             outcome = await caller.submit(push.operation_id, push.changes, push.upload, async (upload) => {
@@ -592,9 +598,10 @@ export class WorkingCopies {
             });
         }
         catch (error) {
+            const refusal = error instanceof HouseRefusal ? refusalOf(error.text) : null;
             return {
                 refused: true,
-                text: `House's answer to ${short(push.commit)} did not arrive (${causeOf(error)}); run house git push again to recover its outcome.`,
+                text: refusal?.text ?? `House's answer to ${short(push.commit)} did not arrive; run house git push again`,
             };
         }
         if ('refused' in outcome) {
@@ -603,22 +610,28 @@ export class WorkingCopies {
                 return this.settle(await this.save({ ...copy, push: unstaged }), caller, true);
             }
             if (outcome.refused.code === 'operation_expired')
-                return this.recovered(copy, outcome.refused.text);
+                return this.recovered(copy);
+            const rebased = rebaseFixes(outcome.refused);
             let settled = await this.save(without(copy));
             try {
                 settled = await this.save(await this.caughtUp(settled));
             }
-            catch (error) {
-                return { refused: true, text: `${outcome.refused.text}\n${HOUSE_REF} is unchanged: ${causeOf(error)}` };
+            catch {
+                return {
+                    refused: true,
+                    text: rebased ? `${outcome.refused.text}\nHouse's current state did not arrive; push again later` : outcome.refused.text,
+                };
             }
             return {
                 refused: true,
-                text: `${outcome.refused.text}\n${HOUSE_REF} holds House's current state; merge or rebase onto it, commit and push again.`,
+                text: rebased
+                    ? `${outcome.refused.text}\n${HOUSE_REF} holds House's current state; rebase onto it and push again`
+                    : outcome.refused.text,
             };
         }
         return this.finished(await this.save({ ...copy, push: { ...copy.push, state: 'accepted', written: outcome.accepted } }));
     }
-    async recovered(copy, reason) {
+    async recovered(copy) {
         const push = copy.push;
         const current = await this.save(await this.caughtUp(copy));
         const house = await tree(copy.repository, current.house);
@@ -627,7 +640,7 @@ export class WorkingCopies {
             await this.save(without(current));
             return {
                 refused: true,
-                text: `${reason}; House does not hold ${short(push.commit)}; run house git push again to submit it as a new operation.`,
+                text: `House does not hold ${short(push.commit)}; run house git push again`,
             };
         }
         const written = [];
@@ -652,10 +665,10 @@ export class WorkingCopies {
                 await this.save(without(copy));
             return { refused: false, text: integrated.text };
         }
-        catch (error) {
+        catch {
             return {
                 refused: false,
-                text: `House accepted ${short(commit)}; local integration is pending (${causeOf(error)}); run house git push again to finish it.`,
+                text: `House accepted ${short(commit)}; run house git push again to finish integrating it here`,
             };
         }
     }

package/dist/git.js

@@ -50,7 +50,7 @@ export async function blobText(repository, object, path) {
         return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
     }
     catch {
-        throw new Error(`${path} is not UTF-8 text`);
+        throw new Error(`${path} is binary and House stores only text; remove it from the commit`);
     }
 }
 export function blobId(content) {

package/dist/house-main.js

@@ -4,10 +4,25 @@ import { readFile } from 'node:fs/promises';
 import { request } from 'node:http';
 import { basename, join } from 'node:path';
 import { kitHome } from './home.js';
+import { refusalOf } from './refusals.js';
 const USAGE = "usage: house <tool> ['<arguments as JSON>']";
-const GIT_HELP = 'Submit a Room commit to House; default HEAD. Use --owner only outside an Agent conversation. Native git push is not a House remote.';
-const GIT_USAGE = `usage: house git push [commit] [--owner]\n${GIT_HELP}`;
+const GIT_USAGE = 'usage: house git push [commit] [--owner]';
+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 REVOKED = 'this conversation no longer has House access; nothing to do from here';
 const socketPath = process.env.HOUSE_BRIDGE;
+function refused(path, status, text) {
+    const refusal = refusalOf(text);
+    if (refusal !== null)
+        return refusal.text;
+    if (status === 401)
+        return REVOKED;
+    if (URL.canParse(path))
+        return `the upload answered ${status}; upload the file again`;
+    if (status === 502 && /^[A-Za-z]/.test(text))
+        return text;
+    return `${path} answered ${status}`;
+}
 function bridged(path, body, headers = { 'content-type': 'application/json' }, to = socketPath) {
     return new Promise((resolve, reject) => {
         const sent = request({ socketPath: to, path, method: 'POST', headers }, (answer) => {
@@ -20,15 +35,15 @@ function bridged(path, body, headers = { 'content-type': 'application/json' }, t
                 if (answer.statusCode === 200)
                     resolve(text);
                 else
-                    reject(new Error(`${path} answered ${answer.statusCode}: ${text}`));
+                    reject(new Error(refused(path, answer.statusCode, text)));
             });
         });
-        sent.on('error', reject);
+        sent.on('error', () => reject(new Error(CLOSED)));
         sent.end(body instanceof Buffer ? body : JSON.stringify(body));
     });
 }
 async function mcp(method, params) {
-    const answer = JSON.parse(await bridged('/', { jsonrpc: '2.0', id: 1, method, params }));
+    const answer = JSON.parse(await bridged('/', { jsonrpc: '2.0', id: randomUUID(), method, params }));
     if (answer.error !== undefined)
         throw new Error(answer.error.message);
     return answer.result;
@@ -36,29 +51,45 @@ async function mcp(method, params) {
 async function tools() {
     return (await mcp('tools/list', {})).tools;
 }
-async function upload(path, roomRef) {
-    const bytes = await readFile(path);
+async function localFile(path) {
+    try {
+        return await readFile(path);
+    }
+    catch (error) {
+        throw new Error(error.code === 'EISDIR'
+            ? `${path} is a folder; upload one file at a time`
+            : `${path} is not a readable file`);
+    }
+}
+async function upload(path, roomRef, missing) {
+    if (typeof path !== 'string' || path === '')
+        throw new Error(missing);
+    const bytes = await localFile(path);
     const declared = JSON.parse(await bridged('/kit/attachments/upload', {
         ...(roomRef === undefined ? {} : { room_ref: roomRef }),
-        version: randomUUID(),
         name: basename(path),
         bytes: bytes.length,
         sha256: createHash('sha256').update(bytes).digest('hex'),
     }));
-    return bridged(declared.upload.url, bytes, {
+    if (declared.upload === undefined)
+        return declared.attachment;
+    const saved = JSON.parse(await bridged(declared.upload.url, bytes, {
         'content-type': 'application/octet-stream',
         'x-house-byte-operation': declared.upload.operation,
-    });
+    }));
+    if (saved.upload_failure !== undefined)
+        throw new Error(`${path} was not saved: ${saved.upload_failure}; call again later`);
+    return saved.attachment;
 }
 async function gitPush(args) {
     if (args.includes('--help'))
         return GIT_USAGE;
     if (args[0] !== 'push')
-        throw new Error(GIT_USAGE);
+        throw new Error('only house git push [commit] exists; use plain git for the rest');
     const owner = args.includes('--owner');
     const commit = args.slice(1).find((arg) => arg !== '--owner') ?? 'HEAD';
     if (owner && socketPath !== undefined)
-        throw new Error('house git push --owner runs outside an Agent conversation');
+        throw new Error('--owner is not for Agent conversations; run house git push without it');
     if (!owner && socketPath === undefined)
         throw new Error('outside an Agent conversation, house git push needs --owner');
     const pushed = JSON.parse(await bridged('/git/push', { cwd: process.cwd(), commit }, undefined, owner ? join(kitHome(), 'owner.sock') : socketPath));
@@ -66,30 +97,45 @@ async function gitPush(args) {
         throw new Error(pushed.text);
     return pushed.text;
 }
+function argumentsOf(argument) {
+    if (argument === undefined)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(argument);
+    }
+    catch {
+        throw new Error(ARGUMENTS);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        throw new Error(ARGUMENTS);
+    return parsed;
+}
 async function house([verb, argument]) {
     if (verb === undefined || verb === '--help') {
-        return [USAGE, `git push [commit]: ${GIT_HELP}`, ...(await tools()).map((tool) => `${tool.name}: ${tool.description}`)].join('\n');
+        return [USAGE, 'git push [commit]', ...(await tools()).map((tool) => `${tool.name}: ${tool.description}`)].join('\n');
     }
     if (argument === '--help') {
         const tool = (await tools()).find((listed) => listed.name === verb);
         if (tool === undefined)
-            throw new Error(`House has no tool ${verb}`);
-        return `${tool.description}\n${JSON.stringify(tool.inputSchema, null, 2)}`;
+            throw new Error(`${verb} is no Tool; house find_command '{"query":"${verb}"}' finds Commands`);
+        return `${tool.description}\n${JSON.stringify(tool.inputSchema)}`;
+    }
+    const args = argumentsOf(argument);
+    if (verb === 'upload_attachment') {
+        return JSON.stringify({ attachment: await upload(args.path, args.room_ref, 'upload_attachment needs "path", a local file') });
     }
-    const args = (argument === undefined ? {} : JSON.parse(argument));
-    if (verb === 'upload_attachment')
-        return upload(String(args.path), args.room_ref);
     if (verb === 'append_record' && Array.isArray(args.attachments)) {
         const attachments = [];
         for (const path of args.attachments) {
-            attachments.push(JSON.parse(await upload(String(path), args.room_ref)).attachment);
+            attachments.push(await upload(path, args.room_ref, 'each attachments entry is the path of a local file'));
         }
         args.attachments = attachments;
     }
     const result = await mcp('tools/call', { name: verb, arguments: args });
     const text = result.content.map((content) => content.text).join('\n');
     if (result.isError === true)
-        throw new Error(text);
+        throw new Error(text.replace(/\n+$/, ''));
     return text;
 }
 const argv = process.argv.slice(2);

package/dist/instructions.js

@@ -1,33 +1,33 @@
-import { readEnrolment } from './home.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, upload it with `house upload_attachment` and link it in your answer.';
-const COPIES_LINE = 'These House paths are Git working copies here; commit in one and run `house git push` to send the commit to House:';
+const FILE_LINE = 'To give the User a file or a page, upload it with `house upload_attachment` and link it; never start a server.';
+const COPIES_LINE = 'House working copies; commit, then `house git 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');
-        let at = lines[5]?.startsWith('authority: ') ? 6 : 5;
-        if (read.isError === true || lines[2] !== 'exit: 0') {
-            const refusal = read.isError === true ? text : lines.slice(at).join('\n').replace(/^stderr: /gm, '');
+        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 = lines[3] === 'truncation: egress' ? CUT.exec(lines[at++] ?? '') : null;
-        const shown = Buffer.from(`${lines.slice(at).join('\n')}\n`);
-        document += (cut === null ? shown : shown.subarray(0, Number(cut[1]))).toString();
+        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 app = new URL('/app/new.git', (await readEnrolment()).house).href;
-    const appLine = `To show the User a page, upload it or push it to an App instead of starting a server; \`git clone ${app}\` starts a new App.`;
-    const lines = [HOUSE_LINE, FILE_LINE, appLine, ...(copies.length === 0 ? [] : [COPIES_LINE, ...copies])];
+    const lines = [HOUSE_LINE, FILE_LINE, ...(copies.length === 0 ? [] : [COPIES_LINE, ...copies])];
     return [lines.join('\n'), base, await howWeWork(bridge)].filter((part) => part !== '').join('\n\n');
 }

package/dist/operation.js

@@ -1,9 +1,12 @@
 import { randomBytes } from 'node:crypto';
+export function uuidOf(bytes, version) {
+    bytes[6] = (version << 4) | (bytes[6] & 0x0f);
+    bytes[8] = 0x80 | (bytes[8] & 0x3f);
+    const hex = bytes.toString('hex', 0, 16);
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
 export function operationId() {
     const bytes = randomBytes(16);
     bytes.writeUIntBE(Date.now(), 0, 6);
-    bytes[6] = 0x70 | (bytes[6] & 0x0f);
-    bytes[8] = 0x80 | (bytes[8] & 0x3f);
-    const hex = bytes.toString('hex');
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    return uuidOf(bytes, 7);
 }

package/dist/refusals.js

@@ -0,0 +1,41 @@
+import { parse } from 'yaml';
+const HEAD = /^([a-z][a-z0-9_]*): \S/;
+function conflictCodes(detail) {
+    let parsed;
+    try {
+        parsed = parse(detail);
+    }
+    catch {
+        return [];
+    }
+    const conflicts = parsed?.conflicts;
+    if (!Array.isArray(conflicts))
+        return [];
+    return conflicts.flatMap((conflict) => typeof conflict?.code === 'string' ? [conflict.code] : []);
+}
+function spoken(text) {
+    const head = HEAD.exec(text);
+    if (head === null)
+        return null;
+    const said = text.replace(/\n+$/, '');
+    const detail = said.indexOf('\n');
+    return { code: head[1], text: said, conflicts: detail === -1 ? [] : conflictCodes(said.slice(detail + 1)) };
+}
+export function refusalOf(text) {
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return spoken(text);
+    }
+    const error = body?.error;
+    if (typeof error !== 'object' || error === null)
+        return null;
+    const { code, message, data } = error;
+    const said = typeof message === 'string' ? spoken(message) : null;
+    if (said !== null)
+        return said;
+    const named = typeof code === 'string' ? code : typeof data?.code === 'string' ? data.code : null;
+    return named === null ? null : { code: named, text: named, conflicts: [] };
+}

package/dist/resident.js

@@ -14,6 +14,7 @@ import { SignIns } from './sign-in.js';
 import { placeSkillSet } from './skills.js';
 import { holdStream } from './stream.js';
 import { Updates } from './update.js';
+const AGENTS_REREAD_MS = 60 * 60_000;
 function report(error) {
     process.stderr.write(`kit: ${error instanceof Error ? error.message : String(error)}\n`);
 }
@@ -93,6 +94,7 @@ export async function resident() {
     await house.deliver('/kit/restarted', {}).catch(report);
     await updates.resumed().catch(report);
     logged(agents.refresh());
+    setInterval(() => logged(agents.refresh()), AGENTS_REREAD_MS);
     stream = holdStream({
         opened: () => {
             conversations.opened();

package/dist/skills.js

@@ -3,10 +3,9 @@ import { cp, lstat, mkdir, readdir, realpath, rm, symlink, writeFile } from 'nod
 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 { refusalCode } from './copies.js';
 import { kitHome, readConfiguration, readHome, writeHome } from './home.js';
+import { refusalOf } from './refusals.js';
 export const HOW_WE_WORK = '/private/library/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');
@@ -63,20 +62,16 @@ export async function placeSkillSet() {
     else
         await rm(join(kitHome(), RECORD), { force: true });
 }
-function documentPresent(refusal) {
-    const { conflicts } = parse(refusal.slice(refusal.indexOf('\n') + 1));
-    return conflicts.some((conflict) => conflict.code === 'path_exists');
-}
 export async function createHowWeWork(bridge) {
     if ((await readHome(RECORD)) === null || (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) {
         const text = created.content.map((content) => content.text).join('\n');
-        const code = refusalCode(text);
-        if (UNWRITABLE.has(code))
+        const refusal = refusalOf(text);
+        if (UNWRITABLE.has(refusal?.code ?? ''))
             return;
-        if (code !== 'edit_conflict' || !documentPresent(text))
+        if (refusal?.code !== 'edit_conflict' || !refusal.conflicts.includes('path_exists'))
             throw new Error(text);
     }
     await writeFile(join(kitHome(), CREATED), '');

package/how-we-work.md

@@ -2,7 +2,7 @@
 
 A Room is where information people share is kept; it is not the place for
 private information. Work goes into the Room it belongs to, or the First Room
-when none is named. Read and write Rooms with the `house` CLI.
+when none is named.
 
 The skills are already set up; never run `setup-matt-pocock-skills`.
 
@@ -20,6 +20,4 @@ The skills are already set up; never run `setup-matt-pocock-skills`.
 - Research: `library/research/<slug>.md`
 - Questionnaires: `library/questionnaires/<slug>.md`
 - Learning: `library/learning/<topic>/`
-- Files a person should open, such as HTML pages, are uploaded to the Room and
-  linked from the document they belong to; a prototype is one HTML file with
-  every variant on one page.
+- Prototype: one HTML file with every variant on one page.

package/package.json

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