@agentshouse/kit 0.1.0-alpha.9 → 0.2.1-alpha.1

package/dist/instructions.js

@@ -0,0 +1,28 @@
+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 HOW_WE_WORK = '/private/library/how-we-work.md';
+const UNREADABLE = /^(?:\S+: )?(?:path_not_found|room_not_found|operation_denied)\b/;
+const CUT = /^stderr: shell: output_cut (\d+) of \d+ bytes; continue with: (.+)$/;
+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 (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();
+        command = cut?.[2];
+    }
+    return document.replace(/\n$/, '');
+}
+export async function instructions(bridge, base) {
+    return [`${HOUSE_LINE}\n${FILE_LINE}`, base, await howWeWork(bridge)].filter((part) => part !== '').join('\n\n');
+}

package/dist/kit-main.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { login } from './login.js';
+import { resident } from './resident.js';
+const [command, ...argv] = process.argv.slice(2);
+async function run() {
+    if (command === 'login')
+        return login(argv);
+    if (command === 'resident')
+        return resident();
+    process.stderr.write('usage: kit <login|resident>\n');
+    process.exitCode = 2;
+}
+run().catch((error) => {
+    process.stderr.write(`kit: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/login.js

@@ -0,0 +1,112 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { hostname } from 'node:os';
+import { createInterface } from 'node:readline/promises';
+import { parseArgs } from 'node:util';
+import { post } from './api.js';
+import { readEnrolment, writeEnrolment } from './home.js';
+const DEFAULT_HOUSE = 'https://agents.house';
+function listen() {
+    return new Promise((resolve, reject) => {
+        let deliver = () => undefined;
+        let held = null;
+        const code = new Promise((settle) => {
+            deliver = settle;
+        });
+        const server = createServer((request, response) => {
+            const received = new URL(request.url ?? '/', 'http://127.0.0.1').searchParams.get('code');
+            if (received === null || held !== null) {
+                response.writeHead(404).end();
+                return;
+            }
+            held = response;
+            deliver(received);
+        });
+        const close = () => {
+            server.close();
+            server.closeAllConnections();
+        };
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (address === null || typeof address === 'string') {
+                reject(new Error('the login callback has no port'));
+                return;
+            }
+            resolve({
+                uri: `http://127.0.0.1:${address.port}/callback`,
+                code,
+                answer: (text) => new Promise((written) => {
+                    if (held === null || held.destroyed || !held.socket || held.socket.destroyed)
+                        return written();
+                    held.once('close', () => written());
+                    held.writeHead(200, { 'content-type': 'text/plain; charset=utf-8', connection: 'close' }).end(`${text}\n`);
+                }),
+                close,
+            });
+        });
+    });
+}
+async function typed(question) {
+    const reader = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await reader.question(question)).trim();
+    }
+    finally {
+        reader.close();
+    }
+}
+export async function login(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            house: { type: 'string' },
+            environment: { type: 'string' },
+            manual: { type: 'boolean', default: false },
+        },
+    });
+    const enrolled = await readEnrolment();
+    const house = values.house ?? enrolled?.house ?? DEFAULT_HOUSE;
+    const environment = values.environment ?? (enrolled?.house === house ? enrolled.environment : undefined);
+    const verifier = randomBytes(32).toString('base64url');
+    const started = {
+        ...(environment === undefined
+            ? { act: 'new_environment', label: hostname() }
+            : { act: 'existing_environment', environment_id: environment }),
+        code_challenge: createHash('sha256').update(verifier).digest('base64url'),
+    };
+    const exchange = async (code) => {
+        const exchanged = await post(house, '/kit/token', { code, code_verifier: verifier });
+        await writeEnrolment({ house, environment: exchanged.environment, credential: exchanged.credential });
+        process.stdout.write(`Environment ${exchanged.environment} is connected to ${house}.\n`);
+    };
+    if (values.manual) {
+        const { start_url } = await post(house, '/kit', {
+            ...started,
+            presentation: 'manual',
+        });
+        process.stdout.write(`Open this link and confirm: ${start_url}\n`);
+        await exchange(await typed('Code: '));
+        return;
+    }
+    const callback = await listen();
+    try {
+        const { start_url } = await post(house, '/kit', {
+            ...started,
+            presentation: 'loopback',
+            loopback_uri: callback.uri,
+        });
+        process.stdout.write(`Open this link and confirm: ${start_url}\n`);
+        try {
+            await exchange(await callback.code);
+        }
+        catch (error) {
+            await callback.answer(`This Environment was not connected: ${error.message}`);
+            throw error;
+        }
+        await callback.answer('This Environment is connected. You can close this tab.');
+    }
+    finally {
+        callback.close();
+    }
+}

package/dist/resident.js

@@ -0,0 +1,66 @@
+import { killDescendants } from './acp.js';
+import { Agents } from './agents.js';
+import { house } from './api.js';
+import { Conversations } from './conversations.js';
+import { readEnrolment } from './home.js';
+import { SignIns } from './sign-in.js';
+import { holdStream } from './stream.js';
+function report(error) {
+    process.stderr.write(`kit: ${error instanceof Error ? error.message : String(error)}\n`);
+}
+function logged(work) {
+    work.catch(report);
+}
+export async function resident() {
+    if ((await readEnrolment()) === null) {
+        process.stderr.write('kit: this Environment is not enrolled; run kit login\n');
+        process.exitCode = 1;
+        return;
+    }
+    process.env.HOUSE_KIT_RESIDENT = String(process.pid);
+    const agents = new Agents(house);
+    let stream = null;
+    let reported = false;
+    const idle = () => conversations.idle() && signIns.idle();
+    const changed = () => {
+        if (!idle()) {
+            reported = false;
+        }
+        else if (!reported) {
+            reported = true;
+            logged(house.deliver('/kit/idle', {}, idle));
+        }
+    };
+    const conversations = new Conversations({
+        house,
+        agents,
+        send: (frame) => stream?.send(frame) ?? false,
+        changed,
+    });
+    const signIns = new SignIns(house, agents, changed);
+    for (const signal of ['SIGTERM', 'SIGINT']) {
+        process.once(signal, () => {
+            killDescendants();
+            process.kill(process.pid, signal);
+        });
+    }
+    await house.deliver('/kit/restarted', {}).catch(report);
+    logged(agents.refresh());
+    stream = holdStream({
+        opened: () => {
+            conversations.opened();
+            changed();
+        },
+        frame: (received) => {
+            if (received.type === 'work_available' && received.subject === 'agents')
+                logged(agents.refresh());
+            if (received.type === 'input') {
+                reported = false;
+                if (received.kind === 'sign_in')
+                    signIns.start(received);
+                else
+                    conversations.input(received);
+            }
+        },
+    });
+}

package/dist/secret-input.js

@@ -0,0 +1,16 @@
+export async function holdSecretInput(house, subject, steps, waiting) {
+    while (waiting()) {
+        try {
+            const held = await house.post(`/kit/secret-input/${subject}`, { steps });
+            if (held.outcome === 'collected')
+                return held.content;
+            if (held.release !== 'held')
+                return null;
+        }
+        catch (error) {
+            process.stderr.write(`kit: ${error instanceof Error ? error.message : String(error)}\n`);
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+        }
+    }
+    return null;
+}

package/dist/sign-in.js

@@ -0,0 +1,83 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { killTree } from './acp.js';
+import { CLIS, cliCommand } from './clis.js';
+import { holdSecretInput } from './secret-input.js';
+const ESCAPE = /\u001b\[[\d;]*m/g;
+const LINK = /https:\/\/\S+/;
+const CODE = /^[A-Z0-9]+-[A-Z0-9]+$/;
+function logged(error) {
+    process.stderr.write(`kit: ${error instanceof Error ? error.message : String(error)}\n`);
+}
+export class SignIns {
+    house;
+    agents;
+    changed;
+    running = new Set();
+    constructor(house, agents, changed) {
+        this.house = house;
+        this.agents = agents;
+        this.changed = changed;
+    }
+    idle() {
+        return this.running.size === 0;
+    }
+    start(input) {
+        if (this.running.has(input.input_id))
+            return;
+        this.running.add(input.input_id);
+        this.changed();
+        this.login(input)
+            .then(() => this.agents.report())
+            .then(() => this.house.deliver(`/kit/inputs/${input.input_id}/ack`, {}))
+            .catch(logged)
+            .finally(() => {
+            this.running.delete(input.input_id);
+            this.changed();
+        });
+    }
+    async login(input) {
+        await this.agents.installed();
+        const login = CLIS[input.cli].login;
+        const child = spawn(cliCommand(input.cli), login.args, { stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+        const running = () => child.exitCode === null && child.signalCode === null;
+        let link;
+        let code;
+        let last = '';
+        let held = false;
+        const read = (line) => {
+            const plain = line.replace(ESCAPE, '').trim();
+            if (plain === '')
+                return;
+            last = plain;
+            link ??= LINK.exec(plain)?.[0];
+            if (CODE.test(plain))
+                code ??= plain;
+            const step = login.code === 'collect'
+                ? { kind: 'collect', label: 'Code shown after you sign in', name: 'code' }
+                : code === undefined
+                    ? undefined
+                    : { kind: 'show', label: 'One-time code', text: code };
+            if (held || link === undefined || step === undefined)
+                return;
+            held = true;
+            const steps = [{ kind: 'visit', label: 'Open this link and sign in', url: link }, step];
+            void holdSecretInput(this.house, input.input_id, steps, running).then((content) => {
+                if (!running())
+                    return;
+                if (content === null)
+                    killTree(child);
+                else
+                    child.stdin.end(`${content.code}\n`);
+            });
+        };
+        for (const output of [child.stdout, child.stderr])
+            createInterface({ input: output }).on('line', read);
+        const failed = await new Promise((resolve) => {
+            child.on('error', (error) => resolve(error.message));
+            child.on('close', (status, signal) => resolve(status === 0 ? null : `exited with ${status ?? signal}${last ? `: ${last}` : ''}`));
+        });
+        if (failed !== null)
+            process.stderr.write(`kit: the ${input.cli} sign-in failed: ${failed}\n`);
+    }
+}

package/dist/stream.js

@@ -0,0 +1,47 @@
+import { readEnrolment } from './home.js';
+const SUBPROTOCOL = 'house.kit.stream.1';
+function streamUrl(house) {
+    const url = new URL('/kit/stream', house);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    return url;
+}
+export function holdStream(handlers) {
+    let socket = null;
+    let failures = 0;
+    const connect = async () => {
+        const { house, credential } = (await readEnrolment());
+        const opening = new WebSocket(streamUrl(house), {
+            protocols: [SUBPROTOCOL],
+            headers: { authorization: `Bearer ${credential}` },
+        });
+        let opened = false;
+        opening.onopen = () => {
+            opened = true;
+            failures = 0;
+            socket = opening;
+            handlers.opened();
+        };
+        opening.onmessage = (event) => {
+            handlers.frame(JSON.parse(String(event.data)));
+        };
+        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);
+        };
+    };
+    void connect();
+    return {
+        send(frame) {
+            if (socket === null || socket.readyState !== WebSocket.OPEN)
+                return false;
+            socket.send(JSON.stringify(frame));
+            return true;
+        },
+    };
+}

package/package.json

@@ -1,25 +1,49 @@
 {
   "name": "@agentshouse/kit",
-  "version": "0.1.0-alpha.9",
+  "version": "0.2.1-alpha.1",
+  "description": "House Kit connects an Environment to agents.house.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/agentshouse/kit.git"
   },
-  "private": false,
   "type": "module",
   "bin": {
-    "kit": "bin/kit.js"
+    "kit": "dist/kit-main.js",
+    "house": "dist/house-main.js"
   },
-  "exports": {
-    "./bootstrap": "./bootstrap.json"
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "tsc -p tsconfig.json && vitest run"
   },
   "dependencies": {
-    "@agentclientprotocol/sdk": "1.5.0",
-    "@agentshouse/mdmodel": "0.1.0-alpha.13",
-    "ws": "8.22.0",
-    "yaml": "2.9.1",
-    "zod": "4.6.5"
+    "@agentclientprotocol/sdk": "1.7.0"
+  },
+  "peerDependencies": {
+    "@agentclientprotocol/claude-agent-acp": "0.85.1",
+    "@agentclientprotocol/codex-acp": "2.1.1",
+    "@xai-official/grok": "1.0.46"
+  },
+  "peerDependenciesMeta": {
+    "@agentclientprotocol/claude-agent-acp": {
+      "optional": true
+    },
+    "@agentclientprotocol/codex-acp": {
+      "optional": true
+    },
+    "@xai-official/grok": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "24.13.6",
+    "@types/ws": "8.18.2",
+    "typescript": "7.0.2",
+    "vitest": "5.0.1",
+    "ws": "8.22.0"
   },
   "packageManager": "npm@11.19.0",
   "engines": {

package/bin/connect-linux.sh

@@ -1,134 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-IMAGE='ghcr.io/agentshouse/kit@sha256:__IMAGE_DIGEST__'
-NAME='house-kit'
-HOUSE='https://agents.house'
-WORKSPACE="$HOME/AgentsHouse"
-MANUAL=0
-WORKSPACE_SELECTED=0
-HOUSE_SELECTED=0
-
-refuse() {
-  printf 'kit_bootstrap_refused: %s\n' "$1" >&2
-  exit 1
-}
-
-bind_mount() {
-  local source=${1//\"/\"\"}
-  printf 'type=bind,"src=%s",dst=%s' "$source" "$2"
-}
-
-while (($#)); do
-  case "$1" in
-    --workspace|--house)
-      (($# >= 2)) || refuse "$1 requires one value"
-      if [[ "$1" == --workspace ]]; then
-        ((WORKSPACE_SELECTED == 0)) || refuse 'supply exactly one workspace root'
-        WORKSPACE="$2"
-        WORKSPACE_SELECTED=1
-      else
-        ((HOUSE_SELECTED == 0)) || refuse 'supply exactly one House origin'
-        HOUSE="$2"
-        HOUSE_SELECTED=1
-      fi
-      shift 2
-      ;;
-    --manual)
-      MANUAL=1
-      shift
-      ;;
-    *) refuse "unknown argument $1" ;;
-  esac
-done
-
-[[ "$IMAGE" =~ ^ghcr\.io/agentshouse/kit@sha256:[0-9a-f]{64}$ ]] || refuse 'this bootstrap has not been published with an immutable image digest'
-[[ "$(uname -s)" == Linux ]] || refuse "unsupported host $(uname -s); this bootstrap is for Linux"
-case "$(uname -m)" in
-  x86_64|amd64) ARCH=amd64 ;;
-  aarch64|arm64) ARCH=arm64 ;;
-  *) refuse "unsupported Linux architecture $(uname -m)" ;;
-esac
-[[ "$WORKSPACE" == /* ]] || refuse 'workspace root must be an absolute path'
-command -v docker >/dev/null || refuse 'Docker Engine client is unavailable'
-DOCKER_PLATFORM=$(docker info --format '{{.OSType}}/{{.Architecture}}' 2>/dev/null) || refuse 'Docker Engine is unavailable'
-case "$DOCKER_PLATFORM" in
-  linux/x86_64|linux/amd64) DOCKER_ARCH=amd64 ;;
-  linux/aarch64|linux/arm64) DOCKER_ARCH=arm64 ;;
-  *) refuse "unsupported Docker Engine platform $DOCKER_PLATFORM" ;;
-esac
-[[ "$DOCKER_ARCH" == "$ARCH" ]] || refuse "host linux/$ARCH does not match Docker Engine linux/$DOCKER_ARCH"
-
-umask 077
-KIT_HOME="$HOME/.house-kit"
-for path in "$KIT_HOME" "$WORKSPACE"; do
-  [[ ! -L "$path" ]] || refuse "$path is a symbolic link"
-  mkdir -p -m 700 "$path" || refuse "$path could not be created"
-  [[ -d "$path" ]] || refuse "$path is not a directory"
-  [[ "$(stat -c %u "$path")" == "$(id -u)" ]] || refuse "$path is not owned by this User"
-  chmod 700 "$path" || refuse "$path could not be owner-protected"
-done
-KIT_HOME=$(cd "$KIT_HOME" && pwd -P)
-WORKSPACE=$(cd "$WORKSPACE" && pwd -P)
-KIT_HOME_MOUNT=$(bind_mount "$KIT_HOME" /kit-home)
-WORKSPACE_MOUNT=$(bind_mount "$WORKSPACE" /agents/house)
-if [[ -f "$KIT_HOME/credential" || -f "$KIT_HOME/environment" ]] && [[ ! -f "$KIT_HOME/house" ]]; then
-  refuse 'stored House origin is missing for an enrolled Environment'
-fi
-if [[ -f "$KIT_HOME/house" ]]; then
-  IFS= read -r BOUND_HOUSE < "$KIT_HOME/house" || refuse 'stored House origin is unreadable'
-  if ((HOUSE_SELECTED)) && [[ "$HOUSE" != "$BOUND_HOUSE" ]]; then
-    refuse 'this Environment is bound to another House origin'
-  fi
-  HOUSE="$BOUND_HOUSE"
-fi
-[[ "$HOUSE" == https://* || "$HOUSE" == http://127.0.0.1:* || "$HOUSE" == http://localhost:* ]] || refuse 'House origin must use HTTPS or local loopback HTTP'
-DOCKER_RUN=(docker run --rm --network host --user "$(id -u):$(id -g)" --mount "$KIT_HOME_MOUNT" --mount "$WORKSPACE_MOUNT" --env HOME=/kit-home --env HOUSE_KIT_HOME=/kit-home --env HOUSE_KIT_CONTAINER=1 --env "HOUSE_KIT_HOSTNAME=$(hostname)" "$IMAGE")
-
-if docker container inspect "$NAME" >/dev/null 2>&1; then
-  [[ "$(docker inspect --format '{{.Config.Image}}' "$NAME")" == "$IMAGE" ]] || refuse 'an installed Kit uses a different image; update it explicitly'
-  [[ "$(docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' "$NAME")" == unless-stopped ]] || refuse 'the installed Kit has a different lifecycle'
-  [[ "$(docker inspect --format '{{len .Mounts}}' "$NAME")" == 2 ]] || refuse 'the installed Kit has unexpected mounts'
-  [[ "$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/kit-home"}}{{.Source}}{{end}}{{end}}' "$NAME")" == "$KIT_HOME" ]] || refuse 'the installed Kit uses another Kit home'
-  [[ "$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/kit-home"}}{{.Type}}/{{.RW}}{{end}}{{end}}' "$NAME")" == bind/true ]] || refuse 'the installed Kit home is not a writable bind mount'
-  [[ "$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/agents/house"}}{{.Source}}{{end}}{{end}}' "$NAME")" == "$WORKSPACE" ]] || refuse 'the installed Kit uses another workspace root'
-  [[ "$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/agents/house"}}{{.Type}}/{{.RW}}{{end}}{{end}}' "$NAME")" == bind/true ]] || refuse 'the installed workspace is not a writable bind mount'
-  [[ "$(docker inspect --format '{{index .Config.Labels "agentshouse.house"}}' "$NAME")" == "$HOUSE" ]] || refuse 'the installed Kit uses another House origin'
-  [[ -f "$KIT_HOME/credential" && -f "$KIT_HOME/environment" && -f "$KIT_HOME/house" ]] || refuse 'the installed Kit has no enrolled authority'
-  "${DOCKER_RUN[@]}" credential check --house "$HOUSE"
-  if [[ "$(docker inspect --format '{{.State.Running}}' "$NAME")" == true ]]; then
-    printf 'House Kit is already running for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
-  else
-    docker start "$NAME" >/dev/null
-    printf 'House Kit restarted for Environment %s.\n' "$(cat "$KIT_HOME/environment")"
-  fi
-  exit 0
-fi
-
-docker pull --quiet --platform "linux/$ARCH" "$IMAGE" >/dev/null
-
-if [[ ! -f "$KIT_HOME/kit.json" ]]; then
-  printf '{"availability":"intermittent","execution_authority":"allow","migrators":[],"instances":[],"clients":[],"host":null}\n' > "$KIT_HOME/kit.json"
-fi
-
-if [[ -f "$KIT_HOME/credential" ]]; then
-  "${DOCKER_RUN[@]}" credential check --house "$HOUSE"
-else
-  if ((MANUAL)); then
-    "${DOCKER_RUN[@]:0:2}" -i "${DOCKER_RUN[@]:2}" login --house "$HOUSE" --manual
-  else
-    command -v xdg-open >/dev/null || refuse 'no host browser opener; rerun with --manual'
-    "${DOCKER_RUN[@]}" login --house "$HOUSE" --host-browser | while IFS= read -r line; do
-      if [[ "$line" == 'Open '* ]]; then
-        printf 'Opening House Login in the host browser.\n'
-        xdg-open "${line#Open }" >/dev/null 2>&1 || refuse 'host browser did not open; rerun with --manual'
-      else
-        printf '%s\n' "$line"
-      fi
-    done
-  fi
-fi
-
-"${DOCKER_RUN[@]}" apply --house "$HOUSE"
-docker run -d --name "$NAME" --restart unless-stopped --user "$(id -u):$(id -g)" --mount "$KIT_HOME_MOUNT" --mount "$WORKSPACE_MOUNT" --label "agentshouse.house=$HOUSE" --env HOME=/kit-home --env HOUSE_KIT_HOME=/kit-home --env HOUSE_KIT_CONTAINER=1 "$IMAGE" resident --house "$HOUSE" >/dev/null
-printf 'House Kit connected for Environment %s.\n' "$(cat "$KIT_HOME/environment")"