@agentshouse/kit 0.2.1-alpha.9 → 0.2.1-c05cd91c26b1d

package/dist/skills.js

@@ -1,18 +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 { refusalCode } from './copies.js';
 import { kitHome, readConfiguration, readHome, writeHome } from './home.js';
-export const HOW_WE_WORK = '/private/library/how-we-work.md';
+import { refusalOf } from './refusals.js';
+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');
 }
@@ -50,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)
@@ -63,21 +84,64 @@ 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');
+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 code = refusalCode(text);
-        if (UNWRITABLE.has(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 (code !== 'edit_conflict' || !documentPresent(text))
-            throw new Error(text);
     }
-    await writeFile(join(kitHome(), CREATED), '');
+    await writeHome(WRITTEN, current);
 }

package/dist/stream.js

@@ -1,39 +1,115 @@
+import { subscribe } from 'node:diagnostics_channel';
+import { finalRefusal, HouseRefusal, retryDelay } from './api.js';
+import { end, REPLACED, signInAgain, updateRequired } from './end.js';
 import { readEnrolment } from './home.js';
-const SUBPROTOCOL = 'house.kit.stream.1';
+import { relayed } from './relay.js';
+import { KIT_WIRE, tooOld } from './wire.js';
+const PATH = '/kit/stream';
+const SUBPROTOCOL = `house.kit.stream.${KIT_WIRE}`;
+const REFUSAL_HEADER = 'x-house-refusal';
+// House beats each stream every thirty seconds, so two silent beats mean this Kit cannot hear House.
+export const STREAM_SILENCE_MS = 60_000;
+const SYSTEM_STREAM_CLOCK = {
+    later: (delay, callback) => setTimeout(callback, delay),
+    clear: (timer) => clearTimeout(timer),
+};
+export class StreamSilence {
+    timer = null;
+    silent;
+    clock;
+    interval;
+    constructor(silent, clock = SYSTEM_STREAM_CLOCK, interval = STREAM_SILENCE_MS) {
+        this.silent = silent;
+        this.clock = clock;
+        this.interval = interval;
+    }
+    heard() {
+        this.stop();
+        this.timer = this.clock.later(this.interval, () => {
+            this.timer = null;
+            this.silent();
+        });
+    }
+    stop() {
+        if (this.timer === null)
+            return;
+        this.clock.clear(this.timer);
+        this.timer = null;
+    }
+}
 function streamUrl(house) {
-    const url = new URL('/kit/stream', house);
+    const url = new URL(PATH, house);
     url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
     return url;
 }
+function header(headers, name) {
+    for (let index = 0; index < headers.length; index += 2) {
+        if (headers[index].toString('latin1').toLowerCase() === name)
+            return headers[index + 1].toString('latin1');
+    }
+    return '';
+}
+let refused = null;
+subscribe('undici:request:headers', (message) => {
+    const { request, response } = message;
+    if (!request.path.endsWith(PATH))
+        return;
+    refused = new HouseRefusal(PATH, response.statusCode, header(response.headers, REFUSAL_HEADER) || response.statusText);
+});
 export function holdStream(handlers) {
     let socket = null;
     let failures = 0;
     const connect = async () => {
         const { house, credential } = (await readEnrolment());
-        const opening = new WebSocket(streamUrl(house), {
+        refused = null;
+        const opening = new WebSocket(relayed(streamUrl(house)), {
             protocols: [SUBPROTOCOL],
             headers: { authorization: `Bearer ${credential}` },
         });
         let opened = false;
+        let silence = null;
+        const closed = (event) => {
+            silence?.stop();
+            silence = null;
+            if (socket === opening)
+                socket = null;
+            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) {
+                void signInAgain(credential);
+                return;
+            }
+            if (refused !== null && tooOld(refused.text))
+                updateRequired();
+            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.
+            setTimeout(() => void connect(), opened ? 1000 + Math.random() * 2000 : retryDelay(failures++));
+        };
         opening.onopen = () => {
             opened = true;
             failures = 0;
             socket = opening;
+            silence = new StreamSilence(() => {
+                if (socket !== opening)
+                    return;
+                socket = null;
+                opening.onclose = null;
+                opening.close();
+                closed(new CloseEvent('close', { code: 1006, reason: 'heartbeat_missed' }));
+            });
+            silence.heard();
             handlers.opened();
         };
         opening.onmessage = (event) => {
-            handlers.frame(JSON.parse(String(event.data)));
+            silence?.heard();
+            const frame = JSON.parse(String(event.data));
+            if (frame.type !== 'beat')
+                handlers.frame(frame);
         };
         opening.onerror = () => undefined;
-        opening.onclose = (event) => {
-            if (socket === opening)
-                socket = null;
-            process.stderr.write(`kit: control stream closed ${event.code} ${event.reason}\n`);
-            const delay = opened
-                ? 1000 + Math.random() * 2000
-                : Math.min(30_000, 1000 * 2 ** failures++);
-            setTimeout(() => void connect(), delay);
-        };
+        opening.onclose = closed;
     };
     void connect();
     return {

package/dist/transcription.js

@@ -0,0 +1,170 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { chmod, mkdir, mkdtemp, readdir, readFile, rename, rm, stat } from 'node:fs/promises';
+import { availableParallelism, tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { unlessAborted } from './abort.js';
+import { failureOf, run } from './clis.js';
+import { kitHome } from './home.js';
+const RELEASE = 'https://github.com/agentshouse/kit/releases/download/engine-2';
+export const MODEL = {
+    url: 'https://huggingface.co/ggml-org/parakeet-GGUF/resolve/35156454d1a39de06863303dd209fd2bed6ee079/ggml-parakeet-tdt-0.6b-v3-q4_k.bin',
+    sha256: '8b205b8b39c6535e153de6fb11c51db46125d45c4f16ba496fe41a0fe71b885e',
+    executable: false,
+};
+export const ENGINES = {
+    'linux-x64': {
+        decoder: { url: `${RELEASE}/ffmpeg-linux-x86_64`, sha256: '1f8235d206428305afb89c6e8ab99d100425a0ba61e22bb4c7aff017db8c8de5', executable: true },
+        engine: { url: `${RELEASE}/parakeet-cli-linux-x86_64`, sha256: 'bb2585695992fe1927a33960002cdf51b8a90a96ad65593c3d0a9f1fbc0865c2', executable: true },
+    },
+    'linux-arm64': {
+        decoder: { url: `${RELEASE}/ffmpeg-linux-aarch64`, sha256: 'a7e08a0fae0179d1078312f6bb13d2a9aa4d4c71a1d82a022953f25dee452f5e', executable: true },
+        engine: { url: `${RELEASE}/parakeet-cli-linux-aarch64`, sha256: 'cbc0bedc8daae97f1ef9dcee4200c06226218e300e0fd62ead1306d22742b7ed', executable: true },
+    },
+    'darwin-arm64': {
+        decoder: { url: `${RELEASE}/ffmpeg-darwin-arm64`, sha256: '7abe154aaed3d6b49f5167ca7221bb66bed51388925d99a7e4261a41fe52fba6', executable: true },
+        engine: { url: `${RELEASE}/parakeet-cli-darwin-arm64`, sha256: '9a2aafc0922ad7c0b6db6eff1641e96572ba32ac40bf995a1df242ed2febf297', executable: true },
+    },
+};
+const CHUNK_SECONDS = 20;
+let held = Promise.resolve();
+let holding = Promise.resolve();
+let setting = null;
+let downloading = null;
+let readiness = { installed: false, failure: null };
+function directory() {
+    return join(kitHome(), 'transcription');
+}
+function installed(artifact) {
+    return join(directory(), artifact.sha256);
+}
+async function executed(command, args, signal) {
+    // A download or a transcription runs as long as its size needs; the setting turning off or the turn's interrupt or end aborts it instead.
+    const ran = await run(command, args, 0, false, signal);
+    if (ran.status !== 0)
+        throw new Error(failureOf(ran, basename(command)));
+    return ran.stdout;
+}
+function present(path) {
+    return stat(path).then(() => true, () => false);
+}
+async function threads() {
+    const [quota, period] = (await readFile('/sys/fs/cgroup/cpu.max', 'utf8').catch(() => 'max')).split(' ');
+    const allowed = quota === 'max' ? Infinity : Math.ceil(Number(quota) / Number(period));
+    return Math.max(1, Math.floor(Math.min(availableParallelism(), allowed) / 2));
+}
+async function sha256(path) {
+    const hash = createHash('sha256');
+    await pipeline(createReadStream(path), hash);
+    return hash.digest('hex');
+}
+function causeOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function pinnedHere() {
+    return ENGINES[`${process.platform}-${process.arch}`];
+}
+async function install(artifacts, signal) {
+    await mkdir(directory(), { recursive: true });
+    const pinned = new Set(artifacts.map((artifact) => artifact.sha256));
+    for (const name of await readdir(directory())) {
+        if (!pinned.has(name))
+            await rm(join(directory(), name), { recursive: true, force: true });
+    }
+    const missing = [];
+    for (const artifact of artifacts)
+        if (!(await present(installed(artifact))))
+            missing.push(artifact);
+    try {
+        for (const artifact of missing) {
+            const part = `${installed(artifact)}.part`;
+            // Three retries carry a large download past a dropped connection before the download fails.
+            await executed('curl', ['-fsSL', '--retry', '3', '-o', part, artifact.url], signal);
+            if ((await sha256(part)) !== artifact.sha256)
+                throw new Error(`${artifact.url} does not match its sha256`);
+        }
+        for (const artifact of missing) {
+            if (artifact.executable)
+                await chmod(`${installed(artifact)}.part`, 0o755);
+            await rename(`${installed(artifact)}.part`, installed(artifact));
+        }
+    }
+    finally {
+        for (const artifact of missing)
+            await rm(`${installed(artifact)}.part`, { force: true });
+    }
+}
+function reported(next) {
+    const changed = next.installed !== readiness.installed || next.failure !== readiness.failure;
+    readiness = next;
+    return changed;
+}
+async function settle(transcribe) {
+    if (transcribe === setting)
+        return false;
+    setting = transcribe;
+    if (!transcribe) {
+        await rm(directory(), { recursive: true, force: true });
+        return reported({ installed: false, failure: null });
+    }
+    const download = new AbortController();
+    downloading = download;
+    try {
+        const pinned = pinnedHere();
+        await install([pinned.decoder, pinned.engine, MODEL], download.signal);
+        return reported({ installed: true, failure: null });
+    }
+    catch (error) {
+        await rm(directory(), { recursive: true, force: true });
+        return reported({ installed: false, failure: download.signal.aborted ? null : causeOf(error) });
+    }
+    finally {
+        downloading = null;
+    }
+}
+export function holdTranscription(transcribe) {
+    if (!transcribe)
+        downloading?.abort();
+    const settled = holding.then(() => settle(transcribe));
+    holding = settled.catch(() => undefined);
+    return settled;
+}
+export function transcriptionReport() {
+    return readiness;
+}
+async function transcribed(path, signal) {
+    const pinned = pinnedHere();
+    const work = await mkdtemp(join(tmpdir(), 'kit-transcription-'));
+    try {
+        await executed(installed(pinned.decoder), ['-nostdin', '-hide_banner', '-loglevel', 'error', '-i', path, '-ar', '16000', '-ac', '1', '-c:a', 'pcm_s16le',
+            '-f', 'segment', '-segment_time', String(CHUNK_SECONDS), join(work, '%05d.wav')], signal);
+        const parts = (await readdir(work)).sort().flatMap((part) => ['-f', join(work, part)]);
+        const text = await executed(installed(pinned.engine), ['-t', String(await threads()), '-np', '-m', installed(MODEL), ...parts], signal);
+        return text
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line !== '')
+            .join(' ');
+    }
+    finally {
+        await rm(work, { recursive: true, force: true });
+    }
+}
+export async function transcribe(path, signal) {
+    if (!readiness.installed)
+        return null;
+    const before = held;
+    let release;
+    const mine = new Promise((resolve) => {
+        release = resolve;
+    });
+    held = Promise.all([before, mine]);
+    try {
+        await unlessAborted(before, signal);
+        return readiness.installed ? await transcribed(path, signal) : null;
+    }
+    finally {
+        release();
+    }
+}

package/dist/update.js

@@ -0,0 +1,138 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { run } from './clis.js';
+import { kitHome, workspaceRoot } from './home.js';
+import { service, throughSudo } from './placement.js';
+function directory() {
+    return join(kitHome(), 'update');
+}
+function pending() {
+    return join(directory(), 'pending.json');
+}
+function outcome() {
+    return join(directory(), 'outcome');
+}
+function unit(inputId) {
+    return `house-kit-update-${inputId}`;
+}
+function manager() {
+    return service() === 'user' ? ['--user'] : [];
+}
+function elevated() {
+    return throughSudo() ? ['sudo', '-n'] : [];
+}
+function account() {
+    return throughSudo() ? [`--uid=${process.getuid()}`, `--gid=${process.getgid()}`] : [];
+}
+function placement() {
+    return service() === 'user' ? ['--workspace', workspaceRoot()] : ['--linux'];
+}
+function record() {
+    return `outcome=$1; shift; bash "$0" "$@"; printf %s "$?" > "$outcome"; ${[...elevated(), 'systemctl', ...manager(), 'start', 'house-kit.service'].join(' ')}`;
+}
+async function pendingInput() {
+    try {
+        return JSON.parse(await readFile(pending(), 'utf8')).input_id;
+    }
+    catch {
+        return null;
+    }
+}
+async function recorded() {
+    const status = await readFile(outcome(), 'utf8').catch(() => null);
+    if (status === null)
+        return null;
+    return status.trim() === '0' ? {} : { refused: `the Kit bootstrap exited with ${status.trim()}` };
+}
+async function forget(inputId) {
+    if ((await pendingInput()) !== inputId)
+        return;
+    await rm(pending(), { force: true });
+    await rm(outcome(), { force: true });
+}
+async function finished(inputId) {
+    for (;;) {
+        const ack = await recorded();
+        if (ack !== null)
+            return ack;
+        // systemctl answers at once, so ten seconds only bounds a stuck service manager.
+        if ((await run('systemctl', [...manager(), 'is-active', '--quiet', unit(inputId)], 10_000)).status !== 0) {
+            return (await recorded()) ?? { refused: 'the Kit bootstrap did not finish' };
+        }
+        // The bootstrap runs for minutes, so checking each second sees its outcome within a second at little cost.
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+}
+function rerun(script, inputId, flags) {
+    return new Promise((resolve) => {
+        const [command, ...args] = [
+            ...elevated(),
+            'systemd-run',
+            ...manager(),
+            ...account(),
+            '--wait',
+            '--collect',
+            '--quiet',
+            `--unit=${unit(inputId)}`,
+            `--setenv=HOME=${homedir()}`,
+            `--setenv=HOUSE_KIT_HOME=${kitHome()}`,
+            '/bin/sh',
+            '-c',
+            record(),
+            script,
+            outcome(),
+            ...placement(),
+            ...flags,
+        ];
+        const child = spawn(command, args, { stdio: ['ignore', 'ignore', 'inherit'] });
+        child.on('error', () => resolve({ refused: 'no service manager runs this Kit' }));
+        child.on('close', () => resolve(null));
+    });
+}
+export class Updates {
+    inputs;
+    queue = Promise.resolve();
+    constructor(inputs) {
+        this.inputs = inputs;
+    }
+    async resumed() {
+        const inputId = await pendingInput();
+        if (inputId === null)
+            return;
+        await this.enqueue(inputId, () => finished(inputId));
+    }
+    start(input) {
+        void this.enqueue(input.input_id, () => this.carry(input));
+    }
+    enqueue(inputId, work) {
+        const before = this.queue;
+        const carried = this.inputs.carry(inputId, async () => {
+            await before;
+            return { ack: await work(), acknowledged: () => forget(inputId) };
+        });
+        this.queue = before.then(() => carried);
+        return carried;
+    }
+    async carry(input) {
+        if ((await pendingInput()) === input.input_id)
+            return finished(input.input_id);
+        const answer = await fetch(input.bootstrap);
+        if (!answer.ok)
+            return { refused: `the Kit bootstrap could not be downloaded: ${answer.status}` };
+        const script = Buffer.from(await answer.arrayBuffer());
+        if (createHash('sha256').update(script).digest('hex') !== input.sha256) {
+            return { refused: 'the Kit bootstrap does not match its sha256' };
+        }
+        await mkdir(directory(), { recursive: true, mode: 0o700 });
+        const path = join(directory(), 'connect-linux.sh');
+        await writeFile(path, script, { mode: 0o700 });
+        await rm(outcome(), { force: true });
+        await writeFile(pending(), `${JSON.stringify({ input_id: input.input_id })}\n`, { mode: 0o600 });
+        return (await rerun(path, input.input_id, input.update_clis ? ['--update-clis'] : [])) ?? (await recorded()) ?? {
+            refused: 'the Kit bootstrap did not finish',
+        };
+    }
+}

package/dist/wire.js

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