negotium 0.2.13 → 0.2.14

package/dist/runtime/src/platform/background-bash/manager.ts

@@ -1,8 +1,8 @@
 import { type ChildProcess, execFileSync, spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import {
-  BACKGROUND_BASH_SERVER,
   BASH_RS_BIN,
+  BASH_RS_VERSION,
   BASHRS_SPILL_ROOT,
   BG_BASH_BASE_PORT,
   BG_BASH_MAX_PORT,
@@ -31,7 +31,12 @@ export interface BackgroundBashManager {
 }
 
 export interface BackgroundBashManagerOptions {
-  serverFile?: string;
+  /**
+   * bash-rs executable. Defaults to the installed binary; injectable so a test
+   * can drive the manager's bookkeeping with a fake `spawn` on a host that has
+   * no binary at all.
+   */
+  bashRsBin?: string;
   basePort?: number;
   maxPort?: number;
   capability?: string;
@@ -71,7 +76,7 @@ export function createBackgroundBashManager(
   const knownContexts = new Map<string, { userId: string; topic: string }>();
   const runtimeCapability = options.capability ?? randomBytes(32).toString("hex");
   const runtimeServerId = options.serverId ?? randomBytes(16).toString("hex");
-  const serverFile = options.serverFile ?? BACKGROUND_BASH_SERVER;
+  const bashRsBin = options.bashRsBin ?? BASH_RS_BIN;
   const basePort = options.basePort ?? BG_BASH_BASE_PORT;
   const maxPort = options.maxPort ?? BG_BASH_MAX_PORT;
   const fetchImpl = options.fetch ?? globalThis.fetch;
@@ -110,20 +115,17 @@ export function createBackgroundBashManager(
         signal: AbortSignal.timeout(2000),
       });
       if (!response.ok) return false;
+      // Confirm this port answers for *our* spawned process rather than a
+      // stale one left behind by a previous manager instance.
       const body = await response.text();
-      // bash-rs (Rust binary) answers with JSON + `instance_id`; the legacy
-      // TS server answers with the bare id as `text/plain`. Both exist to
-      // confirm this port is answering *our* spawned process, not a stale
-      // one left over from a previous manager instance.
       try {
         const parsed = JSON.parse(body);
-        if (parsed && typeof parsed === "object" && "instance_id" in parsed) {
-          return parsed.instance_id === runtimeServerId;
-        }
+        return (
+          Boolean(parsed) && typeof parsed === "object" && parsed.instance_id === runtimeServerId
+        );
       } catch {
-        // Not JSON — fall through to the plain-text comparison below.
+        return false;
       }
-      return body === runtimeServerId;
     } catch {
       return false;
     }
@@ -146,17 +148,23 @@ export function createBackgroundBashManager(
     reservedPort?: number,
     excludedPorts: ReadonlySet<number> = new Set(),
   ): Promise<number> {
+    // bash-rs is the only implementation. A TS server used to stand in when the
+    // binary was absent, but the two agreed on the HTTP protocol while exposing
+    // different MCP tool names (bash_run vs background_bash_run), so which one
+    // spawned silently changed the tool surface an agent saw. Failing loudly
+    // beats serving a different API than the caller was told to expect.
+    //
+    // Checked before allocating: the caller retries once per turn, and a port
+    // reserved by a throw is never released, so allocating first leaked one
+    // port per attempt until the range was exhausted and the real cause was
+    // buried under "No available ports".
+    if (!bashRsBin) {
+      throw new Error(
+        `background-bash requires the bash-rs ${BASH_RS_VERSION} binary; run install-bash-rs.mjs (or set NEGOTIUM_BASH_RS_BIN)`,
+      );
+    }
     const port = reservedPort ?? (await allocatePort(excludedPorts));
-    // Prefer the Rust binary when the installer (install-bash-rs.mjs) put
-    // one in place; otherwise fall back to the TS server unconditionally —
-    // e.g. no prebuilt binary for this platform/arch yet. Both speak the
-    // same wire protocol (X-Background-Bash-* headers, HMAC capability
-    // derived from the same `runtimeCapability` root secret), so either one
-    // is a transparent swap from the caller's point of view.
-    const [command, args] = BASH_RS_BIN
-      ? [BASH_RS_BIN, [String(port)]]
-      : ["bun", ["run", serverFile, `--port=${port}`]];
-    const process = spawnImpl(command, args, {
+    const process = spawnImpl(bashRsBin, [String(port)], {
       stdio: "ignore",
       detached: false,
       env: {

package/dist/runtime/src/platform/config.ts

@@ -168,13 +168,16 @@ export const SNIPPETS_API_URL = (
 export const BROWSER_RS_BIN = resolveBrowserRsBin(envText("NEGOTIUM_BROWSER_RS_BIN"));
 
 /** bash-rs release tested with this Negotium version — see apps/negotium/install-bash-rs.mjs. */
-export const BASH_RS_VERSION = "v0.1.2";
+export const BASH_RS_VERSION = "v0.1.5";
 
 /**
  * Resolve the bash-rs binary the same way `resolveBrowserRsBin` resolves
  * Browser.rs: a versioned private location, no PATH lookup, `undefined`
- * (rather than throwing) when it's missing — callers fall back to the TS
- * `background-bash-server.ts` in that case (see `background-bash/manager.ts`).
+ * (rather than throwing) when it's missing. There is no substitute: the manager
+ * throws when a turn tries to prepare background-bash without a binary (see
+ * `background-bash/manager.ts`), the turn runner catches that and continues
+ * with a reminder that the tools are gone, so background-bash is simply
+ * unavailable on a platform without a prebuilt binary.
  */
 export function resolveBashRsBin(envValue?: string): string | undefined {
   const override = envValue?.trim();
@@ -281,8 +284,6 @@ export const SYSTEM_HEALTH_SERVER = resolve(PROJECT_ROOT, "src/mcp/system-health
 
 export const AGENT_HEALTH_SERVER = resolve(PROJECT_ROOT, "src/mcp/agent-health-server.ts");
 
-export const BACKGROUND_BASH_SERVER = resolve(PROJECT_ROOT, "src/mcp/background-bash-server.ts");
-
 export const VAULT_SERVER = resolve(PROJECT_ROOT, "src/mcp/vault-server.ts");
 
 export const BG_BASH_BASE_PORT = parsePortEnv(process.env.BG_BASH_BASE_PORT, 9700);
@@ -385,8 +386,8 @@ export const SESSION_ASKS_DIR = resolve(RUN_DIR, "session-asks");
  * Passed to `bash-rs` as `BASHRS_SPILL_ROOT`. Each job gets a subdirectory
  * here (`{bash_id}/meta.json`, `result.json`, `stdout.log`, `stderr.log`) —
  * see bash-rs-mcp's `journal.rs`. `runtime/bashrs-completions.ts` watches
- * this directory and turns `result.json` into a session-inbox `tell`, the
- * same way `background-bash-server.ts` used to write one directly.
+ * this directory and turns `result.json` into a session-inbox `tell`. The
+ * retired TypeScript server used to write one directly instead.
  */
 export const BASHRS_SPILL_ROOT = resolve(RUN_DIR, "bashrs");
 export const PLAYWRIGHT_BASE_PORT = parsePortEnv(process.env.PLAYWRIGHT_BASE_PORT, 9100);

package/dist/runtime/src/runtime/bashrs-completions.ts

@@ -1,7 +1,7 @@
 /**
  * bash-rs completion watcher — turns `result.json` files written by the Rust
- * `bash-rs` background-bash daemon into session-inbox `tell`s, the same way
- * `background-bash-server.ts` used to call `injectMessage()` directly.
+ * `bash-rs` background-bash daemon into session-inbox `tell`s. bash-rs is the
+ * only backend; the retired TypeScript server called `injectMessage()` itself.
  *
  * Why a watcher instead of bash-rs calling back into negotium: bash-rs is a
  * standalone project (github.com/maestrojeong/bash-rs-mcp, sibling of
@@ -40,6 +40,46 @@ import {
   type RuntimeProcessLeaseHandle,
 } from "#storage/runtime-process-leases";
 
+/**
+ * Where a finished background job's turn is delivered.
+ *
+ * The default appends to negotium's own session inbox. An embedding host that
+ * owns a different inbox installs its own sink here — otium, for one, resolves
+ * `RUN_DIR` to its own state dir and runs its own inbox worker, so writing to
+ * negotium's path would drop the turn on the floor rather than deliver it.
+ * Mirrors the `setFileHooks()` seam in `runtime/file-hooks.ts`.
+ *
+ * A sink must throw to signal failure: the caller leaves `result.json` in
+ * place so the next sweep retries, which is what keeps delivery at-least-once.
+ */
+export interface BashrsCompletion {
+  userId: string;
+  topicId: string;
+  /** Stable per-job id; use it to collapse a retried delivery into one turn. */
+  bashId: string;
+  message: string;
+}
+
+export type BashrsCompletionSink = (completion: BashrsCompletion) => void;
+
+const defaultSink: BashrsCompletionSink = ({ userId, topicId, bashId, message }) => {
+  appendJsonlEntry(sessionInboxPath(userId, topicId), {
+    type: "tell",
+    from: "__bg_bash__",
+    message,
+    depth: 0,
+    requestId: bashId,
+    timestamp: new Date().toISOString(),
+  });
+};
+
+let completionSink: BashrsCompletionSink = defaultSink;
+
+/** Install a host's delivery sink, or pass null to restore the default. */
+export function setBashrsCompletionSink(sink: BashrsCompletionSink | null): void {
+  completionSink = sink ?? defaultSink;
+}
+
 const PROCESS_ROLE = "worker:bashrs-completions";
 /** How long a delivered job's spill dir (logs + result.json.injected) is kept
  * around before being swept — mirrors the TS server's own
@@ -56,6 +96,12 @@ interface JobResult {
   exit_code: number | null;
   finished_at_ms: number;
   matched_line: string | null;
+  /**
+   * Which arm ended a watch. Absent for a plain background run, and absent
+   * from results written by bash-rs before v0.1.4 — those fall back to the
+   * generic completion notice.
+   */
+  watch_outcome?: "matched" | "timeout" | "exited";
   unknown: boolean;
 }
 
@@ -96,15 +142,31 @@ function buildMessage(dir: string, result: JobResult): string {
       `stderr${stderr.truncated ? ` (truncated, full output: ${join(dir, "stderr.log")})` : ""}:\n${stderr.text.trim()}`,
     );
   }
-  const header = result.matched_line
-    ? `[background_bash_watch ${result.bash_id} matched]\nmatched line: ${result.matched_line.slice(0, 500)}`
-    : `[background_bash ${result.bash_id} finished]`;
+  const header = watchHeader(result) ?? `[background_bash ${result.bash_id} finished]`;
   const exitLine = result.unknown
     ? "exit code: unknown (bash-rs restarted while this job was running)"
     : `exit code: ${result.exit_code ?? "unknown"}`;
   return `${header}\n${exitLine}\n${parts.join("\n") || "(no output)"}`;
 }
 
+/**
+ * A watch promises exactly one turn, and which outcome produced it is the
+ * whole point of the notice: "timed out" and "exited before matching" mean
+ * opposite things about whether the condition is still coming.
+ */
+function watchHeader(result: JobResult): string | null {
+  if (result.matched_line) {
+    return `[background_bash_watch ${result.bash_id} matched]\nmatched line: ${result.matched_line.slice(0, 500)}`;
+  }
+  if (result.watch_outcome === "timeout") {
+    return `[background_bash_watch ${result.bash_id} timed out without a match]`;
+  }
+  if (result.watch_outcome === "exited") {
+    return `[background_bash_watch ${result.bash_id} exited before matching]`;
+  }
+  return null;
+}
+
 function parseOwner(owner: string): { userId: string; topicId: string } | null {
   const nul = owner.indexOf("\0");
   if (nul < 0) return null;
@@ -171,16 +233,14 @@ export async function flushBashrsCompletions(): Promise<void> {
     }
 
     try {
-      appendJsonlEntry(sessionInboxPath(parsed.userId, parsed.topicId), {
-        type: "tell",
-        from: "__bg_bash__",
+      // The stable bash_id is carried through so at-least-once delivery on
+      // either side — this watcher crashing before the rename, or the sink's
+      // own retry semantics — collapses to one turn rather than several.
+      completionSink({
+        userId: parsed.userId,
+        topicId: parsed.topicId,
+        bashId: result.bash_id,
         message: buildMessage(dir, result),
-        depth: 0,
-        // Stable per-job id: at-least-once delivery on both sides (this
-        // watcher's own crash-before-rename, and the session-inbox worker's
-        // own at-least-once semantics) collapses to one turn, not several.
-        requestId: result.bash_id,
-        timestamp: new Date().toISOString(),
       });
       renameSync(resultPath, marker);
       logger.info(

package/dist/runtime/src/runtime/turn-runner.ts

@@ -1556,6 +1556,12 @@ export function startAiTurn(params: StartAiTurnParams): string | null {
           { topicId, err },
           "ai: ensureBgBash failed — proceeding without background bash tools",
         );
+        // Say so in the turn. Losing the tool silently makes the model plan
+        // around a capability it does not have, and the operator only finds
+        // out by reading server logs.
+        turnReminders.push(
+          "<system-reminder>Background bash tools are UNAVAILABLE this turn. The `background_bash_*` tools could not be prepared, most often because the bash-rs binary is not installed on this host. Do not attempt to call them; run short commands in the foreground instead, and tell the user if the work genuinely needs a background job.</system-reminder>",
+        );
       }
     }
     if (playwrightRequested && !browserProfileOwner) {

package/dist/runtime/src/version.ts

@@ -1 +1 @@
-export const NEGOTIUM_VERSION = "0.2.13";
+export const NEGOTIUM_VERSION = "0.2.14";

package/dist/runtime-helpers.js

@@ -496,7 +496,7 @@ function resolveBrowserRsBin(envValue) {
 }
 var SNIPPETS_API_URL = (envText("NEGOTIUM_SNIPPETS_API_URL") ?? envText("SNIPPETS_API_URL") ?? "").replace(/\/+$/, "");
 var BROWSER_RS_BIN = resolveBrowserRsBin(envText("NEGOTIUM_BROWSER_RS_BIN"));
-var BASH_RS_VERSION = "v0.1.2";
+var BASH_RS_VERSION = "v0.1.5";
 function resolveBashRsBin(envValue) {
   const override = envValue?.trim();
   const candidate = override ? resolve(override) : resolve(BINARIES_DIR, "bash-rs", BASH_RS_VERSION, "bash-rs");
@@ -527,7 +527,6 @@ var TOKEN_STATS_SERVER = resolve(PROJECT_ROOT, "src/mcp/token-stats-server.ts");
 var COMPACTION_LOG_SERVER = resolve(PROJECT_ROOT, "src/mcp/compaction-log-server.ts");
 var SYSTEM_HEALTH_SERVER = resolve(PROJECT_ROOT, "src/mcp/system-health-server.ts");
 var AGENT_HEALTH_SERVER = resolve(PROJECT_ROOT, "src/mcp/agent-health-server.ts");
-var BACKGROUND_BASH_SERVER = resolve(PROJECT_ROOT, "src/mcp/background-bash-server.ts");
 var VAULT_SERVER = resolve(PROJECT_ROOT, "src/mcp/vault-server.ts");
 var BG_BASH_BASE_PORT = parsePortEnv(process.env.BG_BASH_BASE_PORT, 9700);
 var BG_BASH_MAX_PORT = parsePortEnv(process.env.BG_BASH_MAX_PORT, 9799);
@@ -1146,4 +1145,4 @@ export {
   CLAUDE_EFFORT_VALUES
 };
 
-//# debugId=3113220EF57A6BCB64756E2164756E21
+//# debugId=856D33930FED17E364756E2164756E21