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

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

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "version": "0.1.0-alpha.23",
+  "version": "0.1.0-alpha.24",
   "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.24/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.24/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.24",
   "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,