@agentshouse/kit 0.1.0-alpha.23 → 0.1.0-alpha.25

package/README.md

@@ -6,13 +6,33 @@ this repository contains only the package source and its operator documentation.
 
 ## Connect a Linux computer
 
-On Linux `amd64` or `arm64` with a working Docker Engine, run the published,
-versioned bootstrap once:
+On Linux `amd64` or `arm64`, run the published, versioned bootstrap once:
 
 ```sh
-bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.23/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.25/connect-linux.sh)
 ```
 
+The bootstrap first establishes Docker Engine from what it observes on the
+computer. A Docker Engine that already answers is used as it is, on any
+distribution. On Ubuntu 22.04, 24.04 or 26.04 LTS it follows Docker's
+[apt repository recipe](https://docs.docker.com/engine/install/ubuntu/) for
+whatever is missing: it installs `docker-ce`, `docker-ce-cli`,
+`containerd.io`, `docker-buildx-plugin` and `docker-compose-plugin` from
+`download.docker.com`, starts the `docker` service when it is stopped and adds
+the account to the `docker` group. Every such step runs through `sudo`, which
+asks for the password as it ordinarily does. A new group membership applies
+from the account's next sign-in, so the invocation that grants it reaches
+Docker Engine through `sudo` for the rest of its own run; a later invocation
+from a session older than the membership is refused until the account signs
+out and back in. The bootstrap refuses an Ubuntu computer whose installed
+`docker.io`, `docker-compose`, `docker-compose-v2`, `docker-doc`,
+`docker-buildx`, `podman-docker`, `containerd` or `runc` package conflicts with
+that recipe rather than removing it. Any other distribution needs a working
+Docker Engine supplied by its owner, and without one the bootstrap stops with
+that missing prerequisite. A step that fails names its cause and changes
+nothing further; running the same bootstrap again continues from the state it
+left, including after a restart.
+
 The release asset pins one immutable multi-architecture image digest. It creates
 owner-protected `~/.house-kit` and `~/AgentsHouse`, mounts those as the complete
 Kit home and `/agents/house`, enrolls through House Login in the host browser,
@@ -781,7 +801,18 @@ Kit reads what the Session was started for from House's
 its input, references, requester and the pinned revision's instruction, or the
 sealed conversation turn. It sends that as the first prompt block, followed by
 current House guidance fetched through the Run connection, so the Agent calls
-nothing to learn it. An unreadable request or guidance refuses the turn. It forwards only adapter-classified User-visible assistant
+nothing to learn it. An unreadable request or guidance refuses the turn.
+A session opened with `session/new` gets one more text block ahead of those,
+the same for every adapter kind: the line
+`The agents.house house CLI is available: run house --help.`, the base
+instructions of the Execution attempt plan House acquired, and the current text
+of the owner's How-we-work document `/private/library/how-we-work.md`, which the
+launcher reads with the `shell` tool over the Session's own bridge, following
+House's cursor to the whole text. An absent document, one the Session's ceiling
+cannot read, and empty base instructions add nothing. Any other failed read
+refuses the attempt as `kit_how_we_work_unreadable` with the bridge's cause
+before a prompt is sent. A session reloaded with `session/load` already holds
+the block and gets none. It forwards only adapter-classified User-visible assistant
 text back over the local channel, and leaves reasoning, tool traces, and
 terminal output where they are. The supervised process's own House calls travel
 that same channel through the `house` CLI. The Kit holds the WorkerRunToken, replaces it in place when

package/bin/connect-linux.sh

@@ -11,6 +11,10 @@ HOUSE_SELECTED=0
 FORWARDING=0
 FORWARDED=kit
 FORWARD=()
+UBUNTU_RELEASES=(jammy noble resolute)
+DOCKER_PACKAGES=(docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin)
+CONFLICTING_PACKAGES=(docker.io docker-compose docker-compose-v2 docker-doc docker-buildx podman-docker containerd runc)
+DOCKER_GROUP=0
 
 refuse() {
   printf 'kit_bootstrap_refused: %s\n' "$1" >&2
@@ -42,6 +46,94 @@ start_resident() {
   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 >/dev/null
 }
 
+docker() {
+  if ((DOCKER_GROUP)); then
+    sudo -u "$(id -un)" docker "$@"
+  else
+    command docker "$@"
+  fi
+}
+
+elevated() {
+  if ((EUID == 0)); then
+    "$@"
+  else
+    sudo "$@"
+  fi
+}
+
+docker_member() {
+  [[ " $(id -nG "$@") " == *' docker '* ]]
+}
+
+docker_answers() {
+  DOCKER_PLATFORM=$(docker info --format '{{.OSType}}/{{.Architecture}}' 2>/dev/null)
+}
+
+docker_cause() {
+  docker info 2>&1 >/dev/null | tail -n 1
+}
+
+unanswered() {
+  type -P docker >/dev/null || return 0
+  printf '; Docker Engine does not answer: %s' "$(docker_cause)"
+}
+
+installed_packages() {
+  { dpkg-query -W -f='${db:Status-Status} ${Package}\n' "$@" 2>/dev/null || true; } | awk '$1 == "installed" { print $2 }'
+}
+
+install_docker_engine() {
+  printf 'Installing Docker Engine from Docker'\''s apt repository for %s; sudo may ask for your password.\n' "$1"
+  elevated apt-get update -qq >/dev/null || refuse 'apt could not refresh its package lists'
+  elevated apt-get install -y -qq ca-certificates curl >/dev/null || refuse 'apt could not install ca-certificates and curl'
+  elevated install -m 0755 -d /etc/apt/keyrings || refuse '/etc/apt/keyrings could not be created'
+  elevated curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc || refuse 'the Docker apt repository key could not be downloaded'
+  elevated chmod a+r /etc/apt/keyrings/docker.asc || refuse 'the Docker apt repository key could not be made readable'
+  printf 'Types: deb\nURIs: https://download.docker.com/linux/ubuntu\nSuites: %s\nComponents: stable\nArchitectures: %s\nSigned-By: /etc/apt/keyrings/docker.asc\n' "$2" "$(dpkg --print-architecture)" \
+    | elevated tee /etc/apt/sources.list.d/docker.sources >/dev/null || refuse 'the Docker apt repository could not be configured'
+  elevated apt-get update -qq >/dev/null || refuse 'apt could not read the Docker apt repository'
+  elevated apt-get install -y -qq "${DOCKER_PACKAGES[@]}" >/dev/null || refuse 'apt could not install Docker Engine'
+}
+
+establish_docker_engine() {
+  docker_answers && return
+  if ((EUID != 0)) && ! docker_member && docker_member "$(id -un)"; then
+    refuse "$(id -un) joined the docker group after this session began; sign out and back in, then rerun this bootstrap"
+  fi
+  local distribution='' release='' described='this Linux distribution' conflicting present
+  if [[ -r /etc/os-release ]]; then
+    distribution=$(. /etc/os-release && printf '%s' "${ID:-}")
+    release=$(. /etc/os-release && printf '%s' "${UBUNTU_CODENAME:-${VERSION_CODENAME:-}}")
+    described=$(. /etc/os-release && printf '%s' "${PRETTY_NAME:-$described}")
+  fi
+  if ((FORWARDING)); then
+    type -P docker >/dev/null || refuse 'House Kit is not installed; run this bootstrap without arguments first'
+    refuse "Docker Engine does not answer: $(docker_cause)"
+  fi
+  if [[ "$distribution" != ubuntu ]]; then
+    type -P docker >/dev/null || refuse "Docker Engine is not installed on $described; install a working Docker Engine, then rerun this bootstrap"
+    refuse "Docker Engine does not answer on $described: $(docker_cause)"
+  fi
+  [[ " ${UBUNTU_RELEASES[*]} " == *" $release "* ]] || refuse "this bootstrap installs Docker Engine only on Ubuntu 22.04, 24.04 and 26.04 LTS, not $described; install a working Docker Engine, then rerun this bootstrap$(unanswered)"
+  conflicting=$(installed_packages "${CONFLICTING_PACKAGES[@]}" | paste -sd ' ' -)
+  [[ -z "$conflicting" ]] || refuse "the installed packages $conflicting conflict with Docker Engine; remove them or make their Docker Engine work, then rerun this bootstrap$(unanswered)"
+  present=$(installed_packages "${DOCKER_PACKAGES[@]}" | wc -l)
+  ((present == ${#DOCKER_PACKAGES[@]})) || install_docker_engine "$described" "$release"
+  if ! systemctl is-active --quiet docker.service; then
+    printf 'Starting Docker Engine; sudo may ask for your password.\n'
+    elevated systemctl start docker.service || refuse 'Docker Engine could not be started'
+  fi
+  if ((EUID != 0)); then
+    if ! docker_member "$(id -un)"; then
+      printf 'Adding %s to the docker group; it applies from your next sign-in, so this run reaches Docker Engine through sudo.\n' "$(id -un)"
+      elevated usermod -aG docker "$(id -un)" || refuse "$(id -un) could not be added to the docker group"
+    fi
+    docker_member || DOCKER_GROUP=1
+  fi
+  docker_answers || refuse "Docker Engine does not answer: $(docker_cause)"
+}
+
 if [[ "${1:-}" == kit || "${1:-}" == house ]]; then
   FORWARDING=1
   FORWARDED="$1"
@@ -80,8 +172,7 @@ case "$(uname -m)" in
   *) 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'
+establish_docker_engine
 case "$DOCKER_PLATFORM" in
   linux/x86_64|linux/amd64) DOCKER_ARCH=amd64 ;;
   linux/aarch64|linux/arm64) DOCKER_ARCH=arm64 ;;

package/bootstrap.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "version": "0.1.0-alpha.23",
+  "version": "0.1.0-alpha.25",
   "hosts": {
     "linux": {
-      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.23/connect-linux.sh)",
+      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.25/connect-linux.sh)",
       "asset": {
         "name": "connect-linux.sh",
-        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.23/connect-linux.sh"
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.25/connect-linux.sh"
       },
       "workspace": {
         "argument": "--workspace",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/kit",
-  "version": "0.1.0-alpha.23",
+  "version": "0.1.0-alpha.25",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/adapter-mcp.js

@@ -1,5 +1,10 @@
-import { COMMAND_ADAPTER_INITIALIZE_TIMEOUT_MS, MCP_PROTOCOL_VERSION } from "./contract.js";
-import { bridgeCall } from "./mcp.js";
+import {
+  COMMAND_ADAPTER_INITIALIZE_TIMEOUT_MS,
+  HOW_WE_WORK_PATH,
+  MCP_PROTOCOL_VERSION,
+  SHELL_RENDER,
+} from "./contract.js";
+import { answerText, bridgeCall } from "./mcp.js";
 import { KitRefusal } from "./refusal.js";
 
 function readableDiscovery(discovery) {
@@ -29,3 +34,53 @@ export async function commandHouseInstructions(bridge) {
   }
   return frame.result.instructions;
 }
+
+function shellAnswer(text) {
+  const lines = text.split("\n");
+  if (!lines[0].startsWith(`protocol: render=${SHELL_RENDER} `)) return null;
+  const exit = Number(lines[2].slice("exit: ".length));
+  let at = lines[5]?.startsWith("authority: ") ? 6 : 5;
+  if (exit === 0) return { exit, stderr: [], stdout: lines.slice(at).join("\n"), cursor: null };
+  const stderr = [];
+  while (lines[at]?.startsWith("stderr: ")) stderr.push(lines[at++].slice("stderr: ".length));
+  const stdout = lines.slice(at);
+  const cursor = stdout.at(-1)?.startsWith("cursor: ") ? stdout.pop().slice("cursor: ".length) : null;
+  return { exit, stderr, stdout: stdout.join("\n"), cursor };
+}
+
+async function howWeWorkPage(bridge, cursor) {
+  const frame = await bridgeCall(bridge, {
+    method: "tools/call",
+    params: {
+      name: "shell",
+      arguments: { command: `cat ${HOW_WE_WORK_PATH}`, ...(cursor === null ? {} : { cursor }) },
+    },
+  });
+  if (frame.error !== undefined) {
+    throw new KitRefusal("kit_how_we_work_unreadable", frame.error.message ?? null);
+  }
+  const text = answerText(frame.result);
+  if (frame.result?.isError === true) {
+    if (text.split(":")[0] === "room_not_found") return null;
+    throw new KitRefusal("kit_how_we_work_unreadable", text);
+  }
+  const page = shellAnswer(text);
+  if (page === null) throw new KitRefusal("kit_how_we_work_unreadable", text);
+  if (page.cursor === null && page.exit !== 0) {
+    if (page.stderr.length === 1 && page.stderr[0].split(" ")[1] === "path_not_found") return null;
+    throw new KitRefusal("kit_how_we_work_unreadable", page.stderr.join("\n"));
+  }
+  return page;
+}
+
+export async function commandHouseHowWeWork(bridge) {
+  const pages = [];
+  let cursor = null;
+  do {
+    const page = await howWeWorkPage(bridge, cursor);
+    if (page === null) return "";
+    pages.push(page.stdout);
+    cursor = page.cursor;
+  } while (cursor !== null);
+  return pages.join("\n");
+}

package/src/contract.js

@@ -118,6 +118,10 @@ export const BRIDGE_NONCE_ENVIRONMENT = "HOUSE_KIT_BRIDGE_NONCE";
 export const BRIDGE_RECONNECT_MS = 200;
 export const BRIDGE_RECONNECT_MAX_MS = 5_000;
 
+export const HOUSE_CLI_LINE = "The agents.house house CLI is available: run house --help.";
+export const HOW_WE_WORK_PATH = "/private/library/how-we-work.md";
+export const SHELL_RENDER = "shell/1";
+
 export const ACP_PROTOCOL = 1;
 export const ACP_AUTH_REQUIRED = -32000;
 export const ADAPTER_EXIT_GRACE_MS = 2_000;

package/src/house.js

@@ -855,9 +855,13 @@ function acquiredAssignment(value, declaration) {
   if (Number.isNaN(Date.parse(expiresAt))) {
     envelope.refuse(`${declaration}.session.bridge_token_expires_at`);
   }
+  if (typeof plan.base_instructions !== "string") {
+    envelope.refuse(`${declaration}.plan.base_instructions`);
+  }
   return {
     run: envelope.text(acquired.run, `${declaration}.run`, 128),
     agentId: envelope.text(plan.agent_id, `${declaration}.plan.agent_id`, 128),
+    baseInstructions: plan.base_instructions,
     workingDirectory: envelope.text(
       plan.working_directory,
       `${declaration}.plan.working_directory`,

package/src/launcher.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { commandHouseInstructions } from "./adapter-mcp.js";
+import { commandHouseHowWeWork, commandHouseInstructions } from "./adapter-mcp.js";
 import {
   compiledContract,
   initializeCommandAdapter,
@@ -7,7 +7,7 @@ import {
   startCommandAdapter,
   stopCommandAdapter,
 } from "./adapter.js";
-import { PERMISSION_OPTION_KINDS, SESSION_SET_CONFIG_OPTION } from "./contract.js";
+import { HOUSE_CLI_LINE, PERMISSION_OPTION_KINDS, SESSION_SET_CONFIG_OPTION } from "./contract.js";
 import { observedAssistantDrafts } from "./draft.js";
 import { observedPlans } from "./plan.js";
 import { bridgePeer } from "./peer.js";
@@ -129,6 +129,11 @@ async function configureSession(acp, contract, sessionId, adapter) {
   }
 }
 
+async function sessionOpening(bridge, baseInstructions) {
+  const parts = [HOUSE_CLI_LINE, baseInstructions, await commandHouseHowWeWork(bridge)];
+  return [{ type: "text", text: parts.filter((part) => part.trim() !== "").join("\n\n") }];
+}
+
 function workingCopyContext(copies) {
   if (!Array.isArray(copies) || copies.length === 0) return [];
   const lines = copies.map((copy) => `${copy.path}: ${copy.repository}`);
@@ -179,6 +184,8 @@ async function runTurn(channel, start, bridge, turn) {
     const { acp } = await initializeCommandAdapter(adapter, contract, handlers);
     const instructions = await commandHouseInstructions(bridge);
     let providerSessionId = start.provider_session ?? null;
+    const opening =
+      providerSessionId === null ? await sessionOpening(bridge, start.base_instructions) : [];
     const setup = { cwd: start.working_directory, mcpServers: [] };
     if (providerSessionId === null) {
       providerSessionId = openedSession(await acp.request("session/new", setup));
@@ -196,6 +203,7 @@ async function runTurn(channel, start, bridge, turn) {
     const prompted = await acp.request("session/prompt", {
       sessionId: providerSessionId,
       prompt: [
+        ...opening,
         { type: "text", text: JSON.stringify(start.request) },
         { type: "text", text: instructions },
         ...workingCopyContext(start.working_copies),

package/src/worker.js

@@ -575,6 +575,7 @@ async function prepareAssignment(context, assignment, resumed) {
   };
   const authority = { token: assignment.session.token, expiresAt: assignment.session.expiresAt };
   const start = {
+    base_instructions: assignment.baseInstructions,
     working_directory: assignment.workingDirectory,
     working_copies: await appliedWorkingCopies(context),
     execution_authority: context.configuration.executionAuthority,