@agentshouse/kit 0.1.0-alpha.1 → 0.1.0-alpha.11

package/README.md

@@ -10,7 +10,7 @@ On Linux `amd64` or `arm64` with a working Docker Engine, run the published,
 versioned bootstrap once:
 
 ```sh
-bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.1/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.11/connect-linux.sh)
 ```
 
 The release asset pins one immutable multi-architecture image digest. It creates
@@ -23,9 +23,65 @@ another House and is retained in Kit home. A repeated invocation reuses the
 same container, credential and Environment; a different installed image is
 left for the explicit update journey.
 
+The versioned `bootstrap.json` is the machine-readable command source for this
+release. It is exported from the npm package as `@agentshouse/kit/bootstrap`
+(JSON import) and published byte-for-byte beside `connect-linux.sh` in the
+GitHub release. Its schema version is `1`, its `version` is the Kit package
+version, and `hosts` contains only bootstrap scripts published in that release.
+The package exports only the `./bootstrap` subpath; `./package.json` and source
+subpaths are not exported. For this release, only `hosts.linux` exists. In this
+schema example, `<version>` stands for the package's version:
+
+```json
+{
+  "schemaVersion": 1,
+  "version": "<version>",
+  "hosts": {
+    "linux": {
+      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v<version>/connect-linux.sh)",
+      "asset": {
+        "name": "connect-linux.sh",
+        "url": "https://github.com/agentshouse/kit/releases/download/v<version>/connect-linux.sh"
+      },
+      "workspace": { "argument": "--workspace", "quoting": "posix" }
+    }
+  }
+}
+```
+
+`command` is complete for the default workspace. To show a selected absolute
+workspace, append the declared `workspace.argument` and the path as one POSIX
+shell-quoted argument. For example, `/home/user/My Agents' House` becomes
+`--workspace '/home/user/My Agents'\'' House'`. Quote the entire path before
+adding it to a copyable shell command; never interpolate it as shell syntax.
+The bootstrap validates an absolute workspace root and encodes it as one Docker
+`--mount` CSV source field, including commas and double quotes in the name.
+The package manifest contains no image digest: the release workflow
+fills the immutable image digest into the published script after the package
+has been built.
+
 The bootstrap does not install native Kit on an ordinary computer. The native
 package remains for managed Nodes and an explicitly selected eligible Kit host.
 
+The same bootstrap is the host's entry point for the existing `kit` commands:
+append `kit` and the command to the connect command above, as in
+`bash <(curl -fsSL …/connect-linux.sh) kit apply` or
+`bash <(curl -fsSL …/connect-linux.sh) kit telegram connect`. It forwards the
+command and its arguments unchanged into the installed container through the
+host's Docker client and ends with the command's own output and exit status.
+Standard input stays attached and a terminal stays a terminal, so a hidden
+prompt such as the Telegram bot token is read inside the container and never
+becomes an argument or printed output. With the output redirected, the
+command's output and errors stay separate and the terminal stops echoing typed
+input until the command ends. A running container runs the command beside its
+resident Kit; a stopped one runs it in a one-off container over the same Kit
+home and workspace and stays stopped. `kit login` takes the bootstrap's own
+login route, a one-off container on the host network so the host browser can
+return to its loopback listener, or `--manual` for the URL and one-time code.
+Forwarding installs no host-native Kit and gives the container no Docker socket
+or further mount; it refuses when no Kit is installed or the installed one
+differs from this bootstrap's.
+
 ## Building the package
 
 The repository checkout is the development source. Build the package
@@ -48,7 +104,8 @@ Runtime dependencies stay minimal and exactly pinned in `package.json` and
 `package-lock.json`: House's own `@agentshouse/mdmodel`, `yaml`, which reads
 House's text answers, and the Agent Client Protocol SDK
 `@agentclientprotocol/sdk` with its peer `zod`, which is this Kit's one protocol
-client for the compiled adapter contracts. The SDK's approval
+client for the compiled adapter contracts, and `ws` for the authenticated Kit
+control stream. The SDK's approval
 receipt is [`docs/agents/acp-sdk-dependency-approval.json`](docs/agents/acp-sdk-dependency-approval.json),
 which the User wrote once this adoption's proof had passed. The adapter
 packages themselves are Environment prerequisites, not Kit dependencies, and
@@ -575,6 +632,17 @@ minimum's major - under
 `$HOUSE_KIT_HOME/agents/<kind>/releases/<release>/`, never touching what the
 owner installed globally, and an acquired route's command is that installed
 executable rather than a path anyone writes into `kit.json`.
+The resident Kit also listens for an `agents` availability pointer on its
+control stream. It reads the whole wanted list from House over HTTPS, removes
+Kit-owned CLI directories that are no longer wanted, installs newly wanted
+kinds, and reports its held state immediately, including while another Agent
+run remains active. A newly wanted kind that needs provider authorization uses
+the existing guided House login ceremony; Kit reports readiness again when it
+ends. A reconnect reads the list again, so a pointer missed during a stream
+outage changes no authority.
+Removal waits for an active worker pass or any unresolved live WorkerSession
+binding to stop using a CLI directory; the Kit keeps reporting that kind until
+it removes the directory.
 
 Every candidate release is proved before it serves: the Kit installs it beside
 the current release, runs the contract's own conformance check - the protocol's
@@ -1062,10 +1130,18 @@ retained references still waiting to be saved.
 Every command that changes or reads installation state takes this
 installation's exclusive Environment control lease for the length of its run
 and renews it before it expires, so two Kit commands never work against the
-same installation at once. A command that ends, or is interrupted once its work
-has stopped, releases that exact lease so the next command acquires at once; a
-refused command leaves it to expire. A `kit login` credential is presented only to take
-that lease.
+same installation at once. A command that ends, is refused, or is interrupted
+once its work has stopped releases that exact lease so the next command acquires
+at once. A `kit login` credential is presented only to take that lease.
+
+While `kit resident` holds that lease, a command runs through it instead: the
+command presents no credential, the resident confirms its current lease with
+House and sends the command's House requests under it, an interrupted command
+cancels its request there, and the lease stays held when the command ends. The
+resident serves one such command at a time and refuses another with
+`environment_control_lease_active`, so two commands still never work at once.
+A resident whose lease House refuses answers the command with that refusal; the
+command never acquires a lease of its own while a resident serves it.
 
 Interrupting the command cancels the running connector without advancing the
 checkpoint.
@@ -1111,8 +1187,11 @@ It selects prefixes over the User root, materializes them into a named local
 directory, enumerates whole content and removals after the recorded positions,
 and submits a resolved exact-base change set the caller prepared. Kit does no
 local reconciliation. The mode shares no Working Copy manifest, never infers a
-removal from a locally absent file, and writes authored mutations only for the
-two Libraries and `ROOM.md`.
+removal from a locally absent file, and writes authored mutations only within
+House's declared write scopes: a selected Room's Library and, where granted,
+`ROOM.md`. `/private` selects the Private Room by its Room reference, records an independent Room
+position, and keeps its `agents/` cards and Room-specific private `AGENTS.md`
+beside `library/**`.
 
 ```sh
 kit sync bootstrap ./replica \
@@ -1179,7 +1258,7 @@ for a batch that reaches it.
 
 ## Attachments
 
-Upload one local file as an attachment to a Room or to your private tree. Name
+Upload one local file as an attachment to a Room or to your Private Room. Name
 the place explicitly. Kit sends the descriptor and the selected bytes; it does
 not scan a directory, convert a URL, or attach sibling files, credentials, or
 absolute paths.
@@ -1583,7 +1662,7 @@ prepared model definitions survive a later content-mount refusal or unmount.
 
 The atomic text mount includes a report with pending transfer rows. Kit then
 uploads each downloaded file once as an attachment to the mount's Room or
-private tree, independently retrieves and compares the saved bytes, and only
+Private Room, independently retrieves and compares the saved bytes, and only
 after that proof succeeds rewrites every link to it, in every referring
 document, to its attachment reference, such as `at_1x.q`. The reference is an
 identity House resolves, not an HTTP download URL. A link's query and fragment

package/bin/connect-linux.sh

@@ -8,12 +8,41 @@ WORKSPACE="$HOME/AgentsHouse"
 MANUAL=0
 WORKSPACE_SELECTED=0
 HOUSE_SELECTED=0
+FORWARDING=0
+FORWARD=()
 
 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"
+}
+
+login_kit() {
+  if [[ " $* " == *' --manual '* ]]; then
+    "${DOCKER_RUN[@]:0:2}" -i "${DOCKER_RUN[@]:2}" login "$@"
+    return
+  fi
+  command -v xdg-open >/dev/null || refuse 'no host browser opener; rerun with --manual'
+  "${DOCKER_RUN[@]}" login "$@" --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
+}
+
+if [[ "${1:-}" == kit ]]; then
+  FORWARDING=1
+  FORWARD=("${@:2}")
+  set --
+fi
+
 while (($#)); do
   case "$1" in
     --workspace|--house)
@@ -53,6 +82,10 @@ case "$DOCKER_PLATFORM" in
   *) refuse "unsupported Docker Engine platform $DOCKER_PLATFORM" ;;
 esac
 [[ "$DOCKER_ARCH" == "$ARCH" ]] || refuse "host linux/$ARCH does not match Docker Engine linux/$DOCKER_ARCH"
+if ((FORWARDING)); then
+  docker container inspect "$NAME" >/dev/null 2>&1 || refuse 'House Kit is not installed; run this bootstrap without arguments first'
+  WORKSPACE=$(docker inspect --format '{{range .Mounts}}{{if eq .Destination "/agents/house"}}{{.Source}}{{end}}{{end}}' "$NAME")
+fi
 
 umask 077
 KIT_HOME="$HOME/.house-kit"
@@ -65,6 +98,8 @@ for path in "$KIT_HOME" "$WORKSPACE"; do
 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
@@ -76,7 +111,7 @@ if [[ -f "$KIT_HOME/house" ]]; then
   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 "type=bind,src=$KIT_HOME,dst=/kit-home" --mount "type=bind,src=$WORKSPACE,dst=/agents/house" --env HOME=/kit-home --env HOUSE_KIT_HOME=/kit-home --env HOUSE_KIT_CONTAINER=1 --env "HOUSE_KIT_HOSTNAME=$(hostname)" "$IMAGE")
+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'
@@ -88,6 +123,25 @@ if docker container inspect "$NAME" >/dev/null 2>&1; then
   [[ "$(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'
+  if ((FORWARDING)); then
+    if [[ "${FORWARD[0]:-}" == login ]]; then
+      login_kit "${FORWARD[@]:1}"
+      exit 0
+    fi
+    TERMINAL=()
+    if [[ -t 0 && -t 1 ]]; then TERMINAL=(-t); fi
+    if [[ -t 0 && ! -t 1 ]]; then
+      ECHOED=$(stty -g)
+      trap 'stty "$ECHOED"' EXIT
+      stty -echo
+    fi
+    if [[ "$(docker inspect --format '{{.State.Running}}' "$NAME")" == true ]]; then
+      docker exec -i "${TERMINAL[@]}" "$NAME" kit "${FORWARD[@]}"
+    else
+      "${DOCKER_RUN[@]:0:2}" -i "${TERMINAL[@]}" "${DOCKER_RUN[@]:2}" "${FORWARD[@]}"
+    fi
+    exit
+  fi
   "${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")"
@@ -108,20 +162,12 @@ 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
+    login_kit --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
+    login_kit --house "$HOUSE"
   fi
 fi
 
 "${DOCKER_RUN[@]}" apply --house "$HOUSE"
-docker run -d --name "$NAME" --restart unless-stopped --user "$(id -u):$(id -g)" --mount "type=bind,src=$KIT_HOME,dst=/kit-home" --mount "type=bind,src=$WORKSPACE,dst=/agents/house" --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
+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")"

package/bin/kit.js

@@ -140,7 +140,7 @@ async function runCredentialCheck(args, directory) {
   const house = await selectedHouse(values, directory);
   let session;
   try {
-    session = await openSession({ house, directory });
+    session = await openSession({ house, directory, acquire: true });
   } catch (error) {
     if (error instanceof KitRefusal && error.code === "environment_control_lease_active") {
       write("Stored Kit authority is accepted; its Environment already has an active control lease.");

package/bootstrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/kit",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.11",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -11,9 +11,13 @@
   "bin": {
     "kit": "bin/kit.js"
   },
+  "exports": {
+    "./bootstrap": "./bootstrap.json"
+  },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.5.0",
-    "@agentshouse/mdmodel": "0.1.0-alpha.12",
+    "@agentshouse/mdmodel": "0.1.0-alpha.13",
+    "ws": "8.22.0",
     "yaml": "2.9.1",
     "zod": "4.6.5"
   },

package/src/agents.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { readFile, rm } from "node:fs/promises";
+import { readFile, readdir, rm } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import {
@@ -11,6 +11,7 @@ import {
 } from "./adapter.js";
 import { inheritedEnvironment } from "./command.js";
 import {
+  ADAPTER_KINDS,
   AGENT_HOME,
   AGENT_INSTALL_TIMEOUT_MS,
   AGENT_RELEASES_HOME,
@@ -261,6 +262,60 @@ export async function updateDeclaredAgents(options, configuration, dependencies
   return updated;
 }
 
+export async function removeUndeclaredAgents(directory, wanted, keep = false) {
+  const home = join(directory, AGENT_HOME);
+  let entries;
+  try {
+    entries = await readdir(home, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+  const retained = [];
+  for (const entry of entries) {
+    if (!wanted.includes(entry.name)) {
+      if (keep && ADAPTER_KINDS.includes(entry.name)) retained.push(entry.name);
+      else await rm(join(home, entry.name), { recursive: true, force: true });
+    }
+  }
+  return retained;
+}
+
+export async function reconcileAgentKinds(
+  options,
+  session,
+  configuration,
+  dependencies = {},
+  signal = session.signal,
+  state = {},
+) {
+  const selected = { ...configuration, agents: await desiredAgents(session, signal) };
+  state.onDesired?.(selected.agents);
+  const newlyWanted = selected.agents.filter((kind) => !state.lastDesired?.includes(kind));
+  const retained = await removeUndeclaredAgents(options.directory, selected.agents, state.busy);
+  const pointerKinds = state.busy
+    ? (
+        await Promise.all(
+          newlyWanted.map(async (kind) =>
+            (await readAgentState(options.directory, kind)).release === null ? kind : null,
+          ),
+        )
+      ).filter((kind) => kind !== null)
+    : newlyWanted;
+  const updated = await updateDeclaredAgents(
+    { directory: options.directory, at: dependencies.now?.(), forced: state.forced },
+    { ...selected, agents: state.pointer ? pointerKinds : selected.agents },
+    dependencies,
+  );
+  const readiness = await agentReadiness(
+    { directory: options.directory },
+    { ...selected, agents: [...selected.agents, ...retained] },
+    dependencies,
+  );
+  await reportAgentCapabilities(session, readiness.agents, signal);
+  return { selected, updated, reported: readiness.agents, refused: readiness.refused, retained };
+}
+
 export async function agentSignedIn(directory, kind, dependencies = {}) {
   const contract = compiledContract(kind);
   const state = await readAgentState(directory, kind);
@@ -341,15 +396,15 @@ export async function updateAgents(options, dependencies = {}) {
   return maintainControl(
     session,
     async (signal) => {
-      const selected = { ...configuration, agents: await desiredAgents(session, signal) };
-      const updated = await updateDeclaredAgents(
-        { directory: options.directory, at: dependencies.now?.(), forced: true },
-        selected,
+      const result = await reconcileAgentKinds(
+        options,
+        session,
+        configuration,
         dependencies,
+        signal,
+        { forced: true },
       );
-      const { agents } = await agentReadiness(options, selected, dependencies);
-      await reportAgentCapabilities(session, agents, signal);
-      return { updated, reported: agents };
+      return { updated: result.updated, reported: result.reported };
     },
     options.signal,
   );

package/src/contract.js

@@ -1,6 +1,6 @@
 import { CLAUDE_PASTED_CODE, CODEX_DEVICE_CODE, GROK_DEVICE_CODE } from "./agent-logins.js";
 
-export const KIT_CONTRACT_VERSION = "2026-09-26-house-agent-kinds";
+export const KIT_CONTRACT_VERSION = "2026-09-27-wanted-agent-clis";
 export const KIT_CAPTURE_BATCH_MAX = 100;
 export const COMMAND_INPUT_MAX_BYTES = 4 * 1024;
 export const AUTHORIZATION_OUTPUT_MAX_BYTES = 4 * 1024;
@@ -195,7 +195,7 @@ export const ADAPTER_CONTRACTS = Object.freeze({
     guidedLogin: CLAUDE_PASTED_CODE,
     identity: Object.freeze({ agentInfo: "@agentclientprotocol/claude-agent-acp" }),
     nativeQuestion: null,
-    sessionLoad: false,
+    sessionLoad: true,
     sessionConfig: Object.freeze({ model: "model", effort: "effort" }),
     capabilities: Object.freeze({
       field_kinds: ELICITATION_FIELD_KINDS,
@@ -288,7 +288,7 @@ export const KIT_DOOR_DISCOVER_PATH = "/kit/door/discover";
 export const KIT_DOOR_BOOTSTRAP_PATH = "/kit/door/bootstrap";
 export const KIT_DOOR_ENUMERATE_PATH = "/kit/door/enumerate";
 export const KIT_DOOR_BATCH_PATH = "/kit/door/batch";
-export const EXPLICIT_SYNC_VERSION = "explicit-sync/1";
+export const EXPLICIT_SYNC_VERSION = "explicit-sync/2";
 export const KIT_DOOR_UNMOUNT_PATH = "/kit/door/unmount";
 
 export const MIGRATOR_CONTRACT = "kit-migrator/1";

package/src/host.js

@@ -1,7 +1,7 @@
 import { readFile, statfs } from "node:fs/promises";
 import { readConfiguration } from "./configuration.js";
 import { HOST_CPU_SAMPLE_MS } from "./contract.js";
-import { openSession, reportHostCapacity } from "./house.js";
+import { maintainControl, openSession, reportHostCapacity } from "./house.js";
 import { KitRefusal } from "./refusal.js";
 
 const PROC_STAT = "/proc/stat";
@@ -116,6 +116,10 @@ export async function reportHost(options, dependencies = {}) {
       ? observed
       : { ...observed, maxima: declaredMaxima(configuration.host.maxima) };
   const session = await openSession(options, dependencies);
-  await reportHostCapacity(session, declaration);
+  await maintainControl(
+    session,
+    (signal) => reportHostCapacity(session, declaration, signal),
+    options.signal,
+  );
   return declaration;
 }