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

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.10/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
@@ -1067,6 +1135,15 @@ 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.
 
+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 +1188,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 +1259,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 +1663,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.10",
+  "hosts": {
+    "linux": {
+      "command": "bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.10/connect-linux.sh)",
+      "asset": {
+        "name": "connect-linux.sh",
+        "url": "https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.10/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.10",
   "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";