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

package/README.md

@@ -1,41 +1,60 @@
-# House Kit
+# Kit
 
-House Kit connects an Environment, a Linux computer or server, to
-[agents.house](https://agents.house). It runs your Agents' conversations
-through the agent CLIs you chose and gives each Agent the `house` command.
+Kit connects an Environment, a Linux computer or server, to [agents.house](https://agents.house). It runs
+your Agents' conversations through the agent CLIs you chose and gives each Agent the `house` command.
 
 ## Install
 
-Connect a computer from agents.house. It gives you the one command that
-installs House Kit on that computer and updates it when you run it again. On
-Linux, macOS and Windows 11 it runs House Kit in one Docker container with
-your workspace, `~/AgentsHouse` unless you pass `--workspace <path>`, mounted
-at `/agents/house`. Append a `kit` or `house` command to the same command to
-run it in that container.
-
-On your own Ubuntu 26.04 server, run the Linux command with `--linux` to
-install House Kit natively, with its workspace at `/agents/house`; `kit` and
+Run `sh -c 'kit=$(curl -fsSL "$0") || { echo "Kit could not be downloaded; run this command again." >&2; exit 1; }; eval "$kit"' agents.house/kit`,
+or `& { try { $kit = irm agents.house/kit.ps1 } catch { throw 'Kit could not be downloaded; run this command again.' }; & ([scriptblock]::Create($kit)) @args }` on Windows, which run nothing of a failed download, and again to update; options follow `agents.house/kit`.
+On macOS and Linux it installs Kit natively under your own account, without an admin password, as a service that runs
+while you are logged in. `kit` and `house` are then on your login shell's `PATH`, and your workspace is `~/AgentsHouse` unless you
+pass `--workspace <path>`.
+
+Add `--container` to run Kit in one Docker container instead, with your
+workspace mounted at `/agents/house`; your Agents then reach only that
+workspace. On Windows 11 the container is the one choice. Append a `kit` or `house` command to the container's options to run it in that container.
+Running the command for the other choice on a connected computer asks you to
+confirm, then replaces its Environment, whose Agents end, with a new one. Running it with a different `HOUSE_KIT_HOME`
+from the running Kit process asks you to confirm before it replaces that process, and leaves the earlier Kit home as it was.
+
+On your own Linux server, run the Linux command with `--linux` to
+install Kit natively, with its workspace at `/agents/house`; `kit` and
 `house` are then on the server's `PATH`.
 
-House Kit also gives every Agent on the Environment a set of agent skills. Add
-`--no-skills` to the command to leave them out; running it again without the
-flag brings them back.
+Kit runs the agent CLIs your login shell finds and installs a missing one
+through that CLI's own installer. Running the command again offers to update
+each CLI older than Kit needs; add `--update-clis` to update every one to
+its latest release without asking. Kit also gives every Agent on the
+Environment the agent skills of `@agentshouse/skills`, at the version each Kit
+release installs. Add `--no-skills` to the command to leave them out; running it again without the flag brings them back.
 
 ## Commands
 
-`kit login` opens a link you confirm in your browser and keeps the
-Environment's credential in `~/.house-kit`, or in `$HOUSE_KIT_HOME` when it is
-set. Pass `--manual` to paste the code by hand on a machine without a browser,
-and `--environment <id>` to reconnect an Environment you already have.
-
-`kit resident` keeps the Environment connected, and keeps the Rooms you chose
-for this Environment as Git repositories under `/agents/house/working-copies`.
-Commit in one and run `house git push --owner` there to send the commit to
-House; on a computer, run it through the install command from the copy's
-directory. Inside an Agent conversation the Agent runs `house git push`.
+`kit login` opens or prints a link you confirm in any browser, on this computer
+or another, continues on its own and keeps the Environment's credential in
+`$HOUSE_KIT_HOME` when it is set, else in `~/.house-kit`, or in `house-kit-<uid>` under the temporary directory when your home is read-only. `--environment <id>`
+reconnects an Environment you already have; `--rooms <ref>[,<ref>...]` gives it
+only those Rooms and `--no-private` every Room but your Private Room; `--code <code>` connects immediately without a link.
+A login also connects your own agent: outside an Agent conversation, `house <tool>` calls
+House as you and `git` clones and pushes your Apps at `<house>/app/` as you, each through the Kit
+home `$HOUSE_KIT_HOME` names where it runs, until you revoke that connection on Connections. `house help` lists the Tools. Codex sessions started after a
+login run a lone `house` command outside their sandbox. `kit logout` disconnects this
+computer, stops the Kit process and ends your own agent's connection, so `house` and `git` no
+longer act as you here; a later `kit login` reconnects the same Environment, or connects
+this computer as a new one when House no longer holds it.
+In a container you do not control, such as ChatGPT's, `npm i -g @agentshouse/kit` and `kit chatgpt --key <key>` with a key made on Connections let `house <tool>` act as you, starting and configuring nothing else.
+
+`kit resident` keeps the Environment connected and, as it connects, copies the text of each Room you chose for it as a
+Git repository in the workspace's `local-copies`, and keeps a Room's copy as it is, no longer refreshing it, once the
+Room may no longer be copied here. `house fetch` does the same and records House's changes on each copy's
+`refs/house/received`; rebase onto it, commit and run `house push --owner` in the copy, through the install command in
+the container. An Agent runs both, without `--owner`. `house upload` and `house download` move a Room's other files straight between disk and House's store, and a broken upload resumes on its own.
+
+Kit turns each audio file your message to an Agent links into text on this computer before the Agent reads it, and keeps a message whose audio it cannot turn into text from starting. While transcription is on, the speech engine and model use about 425 MB beside the Environment's credential; turning it off deletes them.
+
+When you press Run on a Web Wizard's page, Kit runs its script with `bash` in a terminal on this computer, as you, in the home and directory it runs agent CLIs from, with your login shell's `PATH`; the page shows that terminal and takes your typing, and closing the page, or Kit losing its connection to House, ends the script and its child processes. Kit keeps nothing the script prints or you type.
 
 ## License
 
-MIT
-
-The skills come from [mattpocock/skills](https://github.com/mattpocock/skills); thank you, Matt Pocock.
+MIT.

package/dist/abort.js

@@ -0,0 +1,9 @@
+export function unlessAborted(work, signal) {
+    return new Promise((resolve, reject) => {
+        const aborted = () => reject(signal.reason);
+        signal.addEventListener('abort', aborted, { once: true });
+        if (signal.aborted)
+            aborted();
+        work.then(resolve, reject).finally(() => signal.removeEventListener('abort', aborted));
+    });
+}

package/dist/acp.js

@@ -1,47 +1,66 @@
 import { ndJsonStream, PROTOCOL_VERSION, } from '@agentclientprotocol/sdk';
 import { spawn } from 'node:child_process';
-import { readdirSync, readFileSync } from 'node:fs';
 import { Readable, Writable } from 'node:stream';
-import { CLIS, KIT_VERSION, cliCommand, withoutProxy } from './clis.js';
-export const TURN_STARTED = 'kit/turn_started';
-export const TURN_ENDED = 'kit/turn_ended';
-export async function startAdapter(kind, cwd, app, jobs = () => undefined, added = {}) {
-    const child = spawn(cliCommand(kind), CLIS[kind].args, {
+import { CLIS, KIT_RELEASE, adapterCommand, withoutProxy } from './clis.js';
+import { killTree } from './scope.js';
+const RETIRED = 'the CLI was retired';
+export async function startAdapter(kind, cli, cwd, app, events = () => undefined, added = {}, signal, scope = null) {
+    const adapter = CLIS[kind].adapter;
+    const started = [adapter === null ? cli : adapterCommand(kind), CLIS[kind].args];
+    const [command, args] = scope?.command(...started) ?? started;
+    const child = spawn(command, args, {
         cwd,
-        env: { ...withoutProxy(), ...added },
+        env: { ...withoutProxy(), ...(adapter === null ? {} : { ...adapter.env, [adapter.executable]: cli }), ...added },
         stdio: ['pipe', 'pipe', 'pipe'],
         detached: true,
     });
+    let owned = true;
+    let retired = false;
     let stderr = '';
     child.stderr.on('data', (chunk) => {
         stderr = (stderr + chunk.toString('utf8')).slice(-4000);
     });
-    const exited = new Promise((resolve) => {
-        child.on('error', (error) => resolve(`the CLI did not start: ${error.message}`));
-        child.on('exit', (code, signal) => {
-            const last = stderr.trim().split('\n').at(-1);
-            resolve(`the CLI exited with ${code ?? signal}${last ? `: ${last}` : ''}`);
-        });
-    });
     const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
     const connection = app.connect({
         writable: stream.writable,
         readable: stream.readable.pipeThrough(new TransformStream({
             transform(message, controller) {
-                const notice = message;
-                const job = CLIS[kind].job(notice);
-                if (job !== null)
-                    jobs(job);
-                if (!notice.params?.update?.sessionUpdate?.startsWith('async_task_'))
+                const read = message;
+                if (owned)
+                    events(read);
+                if (read.id !== undefined || (read.method !== 'session/update' && !read.method.startsWith('_'))) {
                     controller.enqueue(message);
-                if (CLIS[kind].turnStarted(notice))
-                    controller.enqueue({ jsonrpc: '2.0', method: TURN_STARTED });
-                if (CLIS[kind].turnEnded(notice))
-                    controller.enqueue({ jsonrpc: '2.0', method: TURN_ENDED });
+                }
             },
         })),
     });
-    void exited.then((cause) => connection.close(new Error(cause)));
+    const { promise: lost, resolve: lose } = Promise.withResolvers();
+    const exited = new Promise((resolve) => {
+        const end = (cause) => {
+            if (owned)
+                lose(cause);
+            owned = false;
+            connection.close(new Error(cause));
+            resolve(cause);
+        };
+        child.on('error', (error) => end(`the CLI did not start: ${error.message}`));
+        child.on('exit', (code, signal) => {
+            const last = stderr.trim().split('\n').at(-1);
+            end(`the CLI exited with ${code ?? signal}${last ? `: ${last}` : ''}`);
+        });
+    });
+    const retire = () => {
+        owned = false;
+        if (retired)
+            return;
+        retired = true;
+        if (child.pid !== undefined)
+            killTree(child);
+        scope?.kill();
+        connection.close(new Error(RETIRED));
+    };
+    signal?.addEventListener('abort', retire, { once: true });
+    child.on('exit', () => signal?.removeEventListener('abort', retire));
     try {
         const initialized = await connection.agent.request('initialize', {
             protocolVersion: PROTOCOL_VERSION,
@@ -49,72 +68,16 @@ export async function startAdapter(kind, cwd, app, jobs = () => undefined, added
                 fs: { readTextFile: false, writeTextFile: false },
                 terminal: false,
                 elicitation: { form: {} },
-                _meta: { jetbrains: { air: { version: 1, capabilities: ['asyncTasks'] } } },
+                session: { compaction: {}, notices: {} },
+                _meta: { jetbrains: { air: { version: 1, capabilities: CLIS[kind].air } } },
             },
-            clientInfo: { name: '@agentshouse/kit', version: KIT_VERSION },
+            clientInfo: { name: '@agentshouse/kit', version: KIT_RELEASE },
         });
-        return { child, connection, initialized, exited };
+        scope?.entered(child.pid);
+        return { connection, initialized, exited, lost, retire };
     }
     catch (error) {
-        child.kill('SIGKILL');
+        retire();
         throw error;
     }
 }
-function parents() {
-    const children = new Map();
-    for (const entry of readdirSync('/proc')) {
-        if (!/^\d+$/.test(entry))
-            continue;
-        try {
-            const stat = readFileSync(`/proc/${entry}/stat`, 'utf8');
-            const parent = Number(stat.slice(stat.lastIndexOf(')') + 2).split(' ')[1]);
-            children.set(parent, [...(children.get(parent) ?? []), Number(entry)]);
-        }
-        catch { }
-    }
-    return children;
-}
-function descendants(roots) {
-    const children = parents();
-    const tree = [];
-    const pending = roots.flatMap((root) => children.get(root) ?? []);
-    while (pending.length > 0) {
-        const pid = pending.pop();
-        tree.push(pid);
-        pending.push(...(children.get(pid) ?? []));
-    }
-    return tree;
-}
-function killAll(pids) {
-    for (const pid of pids) {
-        for (const target of [-pid, pid]) {
-            try {
-                process.kill(target, 'SIGKILL');
-            }
-            catch { }
-        }
-    }
-}
-function marked(marker) {
-    return readdirSync('/proc')
-        .filter((entry) => {
-        try {
-            return /^\d+$/.test(entry) && readFileSync(`/proc/${entry}/environ`, 'utf8').split('\0').includes(marker);
-        }
-        catch {
-            return false;
-        }
-    })
-        .map(Number);
-}
-export function killTree(child) {
-    killAll([child.pid, ...descendants([child.pid])]);
-}
-export function killMarked(marker) {
-    const pids = marked(marker);
-    killAll([...pids, ...descendants(pids)]);
-}
-export function killDescendants() {
-    const pids = marked(`HOUSE_KIT_RESIDENT=${process.pid}`);
-    killAll([...pids, ...descendants([process.pid, ...pids])]);
-}