@agentshouse/kit 0.1.0-alpha.6 → 0.1.0-alpha.7

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.6/connect-linux.sh)
+bash <(curl -fsSL https://github.com/agentshouse/kit/releases/download/v0.1.0-alpha.7/connect-linux.sh)
 ```
 
 The release asset pins one immutable multi-architecture image digest. It creates
@@ -48,7 +48,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 +576,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentshouse/kit",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -14,6 +14,7 @@
   "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"
   },

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-27-private-room-scope";
+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;

package/src/kit-work-stream.js

@@ -0,0 +1,84 @@
+import { setTimeout as delay } from "node:timers/promises";
+import WebSocket from "ws";
+import { KIT_CONTRACT_VERSION } from "./contract.js";
+import { heldControl } from "./house.js";
+import { KitRefusal } from "./refusal.js";
+
+const PROTOCOL = "house.kit.stream.1";
+
+function streamAddress(house) {
+  const url = new URL("/kit/stream", house);
+  if (url.protocol === "https:") url.protocol = "wss:";
+  else if (url.protocol === "http:") url.protocol = "ws:";
+  else throw new KitRefusal("kit_house_unavailable", "/kit/stream");
+  return url;
+}
+
+async function connected(session, signal, available, dependencies) {
+  const authorization = await heldControl(session, signal);
+  return new Promise((resolve, reject) => {
+    const Socket = dependencies.workSocket ?? WebSocket;
+    const socket = new Socket(streamAddress(session.house), PROTOCOL, {
+      headers: { authorization, "x-house-kit-version": KIT_CONTRACT_VERSION },
+      handshakeTimeout: 10_000,
+      maxPayload: 4096,
+      perMessageDeflate: false,
+    });
+    let finished = false;
+    const finish = (error = null) => {
+      if (finished) return;
+      finished = true;
+      signal.removeEventListener("abort", stop);
+      if (error === null) resolve();
+      else reject(error);
+    };
+    const stop = () => {
+      socket.terminate();
+      finish();
+    };
+    signal.addEventListener("abort", stop, { once: true });
+    socket.on("open", available);
+    socket.on("message", (data) => {
+      let frame;
+      try {
+        frame = JSON.parse(data.toString());
+      } catch {
+        return;
+      }
+      if (frame?.type === "work_available" && frame.subject === "agents") available();
+    });
+    socket.on("unexpected-response", (_request, response) => {
+      response.resume();
+      const refusal =
+        response.statusCode === 409 ? new KitRefusal("kit_upgrade_required") : null;
+      socket.terminate();
+      finish(refusal);
+    });
+    socket.on("error", () => {
+      socket.terminate();
+      finish();
+    });
+    socket.on("close", () => finish());
+    if (signal.aborted) stop();
+  });
+}
+
+export async function watchKitAgentWork(session, signal, available, dependencies = {}) {
+  let retryMs = 500;
+  while (!signal.aborted) {
+    const began = Date.now();
+    try {
+      await connected(session, signal, available, dependencies);
+    } catch (error) {
+      if (error instanceof KitRefusal && error.code === "kit_upgrade_required") throw error;
+      if (signal.aborted) return;
+    }
+    if (signal.aborted) return;
+    retryMs = Date.now() - began >= 30_000 ? 1000 : Math.min(retryMs * 2, 30_000);
+    try {
+      await delay(dependencies.workReconnectMs ?? retryMs, undefined, { signal });
+    } catch (error) {
+      if (!signal.aborted) throw error;
+    }
+  }
+}

package/src/setup.js

@@ -114,14 +114,14 @@ async function signedIn(module) {
   }
 }
 
-async function setUpModule(context, module) {
+async function setUpModule(context, module, install = true) {
   const summary = (status, reason = null) => ({
     category: module.category,
     name: module.name,
     status,
     reason,
   });
-  if (module.install !== null) {
+  if (install && module.install !== null) {
     try {
       await module.install();
     } catch (error) {
@@ -144,10 +144,15 @@ async function setUpModule(context, module) {
   return summary("ready");
 }
 
+export function signInWantedAgent(context, kind) {
+  return setUpModule(context, agentModule(context, kind), false);
+}
+
 export async function runSetup(context, request) {
   await prepareLaunchBase(launchBase(context.dependencies));
   const modules = [];
   for (const kind of context.configuration.agents) {
+    await context.waitAgentLogin?.(kind);
     modules.push(await setUpModule(context, agentModule(context, kind)));
   }
   for (const instance of context.configuration.instances) {

package/src/worker.js

@@ -2,7 +2,11 @@ import { randomBytes } from "node:crypto";
 import { join } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
-import { agentReadiness, installedAgentCommand, updateDeclaredAgents } from "./agents.js";
+import {
+  installedAgentCommand,
+  readAgentState,
+  reconcileAgentKinds,
+} from "./agents.js";
 import { readBindings, removeBinding, writeBinding } from "./binding.js";
 import { readContinuation, readContinuationRuns, writeContinuation, removeContinuation } from "./continuation.js";
 import { openBridge } from "./bridge.js";
@@ -12,6 +16,7 @@ import { openAssistantDrafts } from "./draft.js";
 import { localReply, localRequest, reconcileInbound } from "./inbound.js";
 import { localFiles } from "./local-files.js";
 import { inheritedEnvironment } from "./command.js";
+import { watchKitAgentWork } from "./kit-work-stream.js";
 import { readConfiguration } from "./configuration.js";
 import { launchBase, readyLaunchDirectory } from "./directory.js";
 import {
@@ -31,7 +36,6 @@ import {
   acceptAssistantText,
   acquireCommands,
   acquireSetup,
-  reportAgentCapabilities,
   acquireOneRun,
   acquireOneResumption,
   admitInteraction,
@@ -40,7 +44,6 @@ import {
   rejectResumption,
   callHouseMcp,
   commitRun,
-  desiredAgents,
   maintainControl,
   mutatingCall,
   observeSessionStart,
@@ -58,7 +61,7 @@ import {
   streamAssistantDraft,
 } from "./house.js";
 import { operationId } from "./operation.js";
-import { runSetup } from "./setup.js";
+import { runSetup, signInWantedAgent } from "./setup.js";
 import { readSettlements, removeSettlement, writeSettlement } from "./settlement.js";
 import { failedReport, terminalReport } from "./terminal.js";
 import {
@@ -666,26 +669,33 @@ async function afterEpochReport(context, pass) {
   return pass();
 }
 
-async function workerPass(context, dependencies) {
-  const { configuration, session, signal } = context;
+async function workerPass(context, dependencies, baseConfiguration) {
+  const { session, signal } = context;
   const reconciled = await reconcile(context);
   if (reconciled.run !== null || reconciled.unresolved.length > 0) return reconciled;
+  context.busy = false;
+  const needsLogin = await queueAgentRefresh(context, dependencies, signal, baseConfiguration);
+  context.startLogins?.(needsLogin);
+  context.busy = true;
+  const { configuration } = context;
   context.inbound = await reconcileInbound(context.directory, session);
   const setup = await acquireSetup(session, signal);
   if (setup !== null) {
     context.setup = await runSetup(
-      { session, configuration, directory: context.directory, dependencies, signal },
+      {
+        session,
+        configuration,
+        directory: context.directory,
+        dependencies,
+        signal,
+        waitAgentLogin: context.waitAgentLogin,
+      },
       setup.request,
     );
+    await context.recordSetupLogins?.(context.setup);
+    const needsLogin = await queueAgentRefresh(context, dependencies, signal, undefined, true);
+    context.startLogins?.(needsLogin);
   }
-  context.agents = await updateDeclaredAgents(
-    { directory: context.directory, at: dependencies.now?.() },
-    configuration,
-    dependencies,
-  );
-  const readiness = await agentReadiness({ directory: context.directory }, configuration, dependencies);
-  await reportAgentCapabilities(session, readiness.agents);
-  if (readiness.refused !== null) throw readiness.refused;
   const resumption = await acquireOneResumption(session);
   if (resumption !== null) return { ...reconciled, run: await superviseResumption(context, resumption) };
   const assignment = await acquireOneRun(session);
@@ -709,15 +719,59 @@ async function workerContext(options, dependencies) {
     directory: options.directory,
     files: { originals: [], failures: [] },
     epochReport: null,
+    agentRefresh: Promise.resolve(),
+    configurationPath: options.configuration,
+    busy: false,
+    deferredRemoval: false,
   };
   return { context, tmux };
 }
 
+async function refreshAgentCapabilities(context, dependencies, signal, configuration, pointer = false) {
+  const base = configuration ?? (await readConfiguration(context.configurationPath));
+  const busy = context.busy || (await readBindings(context.directory)).length > 0;
+  const result = await reconcileAgentKinds(
+    { directory: context.directory },
+    context.session,
+    base,
+    dependencies,
+    signal,
+    {
+      pointer,
+      busy,
+      lastDesired: context.lastDesired,
+      onDesired: (wanted) => context.cancelLogins?.(wanted),
+    },
+  );
+  context.deferredRemoval = result.retained.length > 0;
+  context.configuration = result.selected;
+  context.agents = result.updated;
+  context.lastDesired = [...result.selected.agents];
+  if (result.refused !== null) throw result.refused;
+  return result.reported.filter(
+    (agent) =>
+      result.selected.agents.includes(agent.kind) && agent.release !== null && !agent.signed_in,
+  );
+}
+
+function queueAgentRefresh(context, dependencies, signal, configuration, pointer = false) {
+  const refreshed = context.agentRefresh.then(() =>
+    refreshAgentCapabilities(context, dependencies, signal, configuration, pointer),
+  );
+  context.agentRefresh = refreshed.catch(() => {});
+  return refreshed;
+}
+
 async function controlledPass(context, dependencies, configuration, signal) {
-  context.configuration = { ...configuration, agents: await desiredAgents(context.session, signal) };
   context.signal = signal;
   context.session.signal = signal;
-  return afterEpochReport(context, () => workerPass(context, dependencies));
+  context.busy = true;
+  try {
+    return await afterEpochReport(context, () => workerPass(context, dependencies, configuration));
+  } finally {
+    context.busy = false;
+    if (context.deferredRemoval) context.onIdle?.();
+  }
 }
 
 export async function runWorkers(options, dependencies = {}) {
@@ -740,17 +794,132 @@ export async function runWorkers(options, dependencies = {}) {
   };
 }
 
-export async function runResident(options, dependencies = {}) {
-  const { context } = await workerContext(options, dependencies);
-  await maintainControl(context.session, async (signal) => {
-    while (!signal.aborted) {
-      const configuration = await readConfiguration(options.configuration);
-      await controlledPass(context, dependencies, configuration, signal);
+function residentWake() {
+  let pending = false;
+  let release = null;
+  return {
+    notify() {
+      pending = true;
+      release?.();
+    },
+    async wait(milliseconds, signal) {
+      if (pending) {
+        pending = false;
+        return;
+      }
+      const pause = new AbortController();
       try {
-        await delay(dependencies.residentIntervalMs ?? 30_000, undefined, { signal });
+        await Promise.race([
+          new Promise((resolve) => {
+            release = resolve;
+          }),
+          delay(milliseconds, undefined, { signal: AbortSignal.any([signal, pause.signal]) }),
+        ]);
       } catch (error) {
         if (!signal.aborted) throw error;
+      } finally {
+        release = null;
+        pending = false;
+        pause.abort();
+      }
+    },
+  };
+}
+
+export async function runResident(options, dependencies = {}) {
+  const { context } = await workerContext(options, dependencies);
+  await maintainControl(context.session, async (signal) => {
+    context.busy = true;
+    const wake = residentWake();
+    const watcher = new AbortController();
+    let failure = null;
+    const logins = new Map();
+    const attemptedLogins = new Map();
+    context.cancelLogins = (wanted) => {
+      for (const [kind, running] of logins) {
+        if (!wanted.includes(kind)) running.controller.abort();
+      }
+      for (const kind of attemptedLogins.keys()) {
+        if (!wanted.includes(kind)) attemptedLogins.delete(kind);
       }
+    };
+    context.recordSetupLogins = async (modules) => {
+      for (const module of modules) {
+        if (module.category !== "agent" || module.status !== "needs_attention") continue;
+        const release = (await readAgentState(context.directory, module.name)).release;
+        if (release !== null) attemptedLogins.set(module.name, release);
+      }
+    };
+    context.startLogins = (agents) => {
+      for (const agent of agents) {
+        const { kind, release } = agent;
+        if (logins.has(kind) || attemptedLogins.get(kind) === release) continue;
+        const controller = new AbortController();
+        const loginSignal = AbortSignal.any([signal, controller.signal]);
+        const task = (async () => {
+          if ((await acquireSetup(context.session, loginSignal)) !== null) return;
+          attemptedLogins.set(kind, release);
+          await signInWantedAgent({ ...context, dependencies, signal: loginSignal }, kind);
+          await queueAgentRefresh(context, dependencies, signal, undefined, true);
+        })()
+          .catch((error) => {
+            if (loginSignal.aborted) return;
+            failure = error;
+            wake.notify();
+          })
+          .finally(() => logins.delete(kind));
+        logins.set(kind, { controller, task });
+      }
+    };
+    context.waitAgentLogin = async (kind) => {
+      await logins.get(kind)?.task;
+    };
+    let pointerPending = false;
+    let pointerTask = null;
+    const pointer = () => {
+      pointerPending = true;
+      if (pointerTask !== null) return;
+      pointerTask = (async () => {
+        while (pointerPending && !signal.aborted) {
+          pointerPending = false;
+          const needsLogin = await queueAgentRefresh(context, dependencies, signal, undefined, true);
+          context.startLogins(needsLogin);
+        }
+      })()
+        .catch((error) => {
+          if (signal.aborted) return;
+          failure = error;
+          wake.notify();
+        })
+        .finally(() => {
+          pointerTask = null;
+          if (pointerPending && !signal.aborted) pointer();
+        });
+    };
+    context.onIdle = pointer;
+    const watching = (dependencies.watchKitAgentWork ?? watchKitAgentWork)(
+      context.session,
+      AbortSignal.any([signal, watcher.signal]),
+      pointer,
+      dependencies,
+    ).catch((error) => {
+      failure = error;
+      wake.notify();
+    });
+    try {
+      while (!signal.aborted) {
+        if (failure !== null) throw failure;
+        const configuration = await readConfiguration(options.configuration);
+        await controlledPass(context, dependencies, configuration, signal);
+        await wake.wait(dependencies.residentIntervalMs ?? 30_000, signal);
+      }
+    } finally {
+      watcher.abort();
+      await watching;
+      if (pointerTask !== null) await pointerTask;
+      for (const running of logins.values()) running.controller.abort();
+      await Promise.all([...logins.values()].map((running) => running.task));
+      await context.agentRefresh;
     }
   }, options.signal);
 }