negotium 0.2.12 → 0.2.14

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

@@ -1,6 +1,12 @@
 import { type ChildProcess, execFileSync, spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
-import { BACKGROUND_BASH_SERVER, BG_BASH_BASE_PORT, BG_BASH_MAX_PORT } from "#platform/config";
+import {
+  BASH_RS_BIN,
+  BASH_RS_VERSION,
+  BASHRS_SPILL_ROOT,
+  BG_BASH_BASE_PORT,
+  BG_BASH_MAX_PORT,
+} from "#platform/config";
 import { delay } from "#platform/delay";
 import { logger } from "#platform/logger";
 import { deriveBgBashContextCapability } from "./context";
@@ -25,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;
@@ -65,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;
@@ -103,7 +114,18 @@ export function createBackgroundBashManager(
       const response = await fetchImpl(`http://127.0.0.1:${port}/health`, {
         signal: AbortSignal.timeout(2000),
       });
-      return response.ok && (await response.text()) === runtimeServerId;
+      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();
+      try {
+        const parsed = JSON.parse(body);
+        return (
+          Boolean(parsed) && typeof parsed === "object" && parsed.instance_id === runtimeServerId
+        );
+      } catch {
+        return false;
+      }
     } catch {
       return false;
     }
@@ -126,14 +148,32 @@ 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));
-    const process = spawnImpl("bun", ["run", serverFile, `--port=${port}`], {
+    const process = spawnImpl(bashRsBin, [String(port)], {
       stdio: "ignore",
       detached: false,
       env: {
         ...(options.env ?? globalThis.process.env),
         NEGOTIUM_BG_BASH_CAPABILITY: runtimeCapability,
         NEGOTIUM_BG_BASH_SERVER_ID: runtimeServerId,
+        BASHRS_HTTP_CAPABILITY: runtimeCapability,
+        BASHRS_INSTANCE_ID: runtimeServerId,
+        BASHRS_SPILL_ROOT,
       },
     });
 

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

@@ -167,6 +167,33 @@ 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.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. 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();
+  const candidate = override
+    ? resolve(override)
+    : resolve(BINARIES_DIR, "bash-rs", BASH_RS_VERSION, "bash-rs");
+  try {
+    accessSync(candidate, constants.X_OK);
+    return candidate;
+  } catch {
+    return undefined;
+  }
+}
+
+export const BASH_RS_BIN = resolveBashRsBin(envText("NEGOTIUM_BASH_RS_BIN"));
+
 // Managed Browser.rs terminates MCP transports and security policy itself.
 export function resolveBrowserMcpBin(envValue?: string): string {
   const override = envValue?.trim();
@@ -257,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);
@@ -357,6 +382,14 @@ export const DM_CMD_DIR = resolve(RUN_DIR, "dm-commands");
 export const DM_RESP_DIR = resolve(RUN_DIR, "dm-responses");
 export const SESSION_INBOX_DIR = resolve(RUN_DIR, "session-inbox");
 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
+ * 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);
 export const PLAYWRIGHT_MAX_PORT = parsePortEnv(process.env.PLAYWRIGHT_MAX_PORT, 9499);
 export const PLAYWRIGHT_PORTS_DIR = resolve(RUN_DIR, "playwright-ports");

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

@@ -0,0 +1,328 @@
+/**
+ * bash-rs completion watcher — turns `result.json` files written by the Rust
+ * `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
+ * browser-rs-mcp) that knows nothing about topics/session-inbox/turns — it
+ * only ever appends `{bash_id}/meta.json` (on spawn) and `{bash_id}/result.json`
+ * (on completion) under `BASHRS_SPILL_ROOT`, and never reads or deletes
+ * either. Any consumer, negotium or otherwise, watches that directory the
+ * same way `runtime/inbox.ts` already watches the session-inbox itself:
+ * `fs.watch` + a fallback poll, at-least-once, dedup by a stable id.
+ *
+ * `owner` on the wire is `${userId}\0${topicId}` — see
+ * `platform/mcp-config.ts::backgroundBashTransport` for what negotium sends
+ * as `X-Background-Bash-User`/`X-Background-Bash-Topic`, and bash-rs's own
+ * `security.rs::resolve_identity` for the matching NUL-join on the other end.
+ */
+
+import {
+  closeSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readSync,
+  renameSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+import { debouncedFlush, FALLBACK_INTERVAL_MS, watchDir } from "#outbox/utils";
+import { BASHRS_SPILL_ROOT } from "#platform/config";
+import { appendJsonlEntry } from "#platform/jsonl";
+import { logger } from "#platform/logger";
+import { sessionInboxPath } from "#query/session-inbox-path";
+import {
+  acquireRuntimeProcessLease,
+  PROCESS_LEASE_HEARTBEAT_MS,
+  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
+ * `COMPLETED_RETENTION_MS`, for the same reason: a reader might still be
+ * mid-way through fetching a spill path out of the injected message. */
+const RETENTION_MS = 15 * 60_000;
+/** Read at most this many trailing bytes of stdout.log/stderr.log into the
+ * injected message — full output stays on disk at the path we report. */
+const TAIL_BYTES = 8 * 1024;
+
+interface JobResult {
+  bash_id: string;
+  owner: string;
+  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;
+}
+
+function isJobResult(value: unknown): value is JobResult {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  return typeof v.bash_id === "string" && typeof v.owner === "string";
+}
+
+function readTail(filePath: string): { text: string; truncated: boolean } {
+  try {
+    const { size } = statSync(filePath);
+    const fd = openSync(filePath, "r");
+    try {
+      const start = Math.max(0, size - TAIL_BYTES);
+      const buf = Buffer.alloc(size - start);
+      readSync(fd, buf, 0, buf.length, start);
+      return { text: buf.toString("utf8"), truncated: start > 0 };
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return { text: "", truncated: false };
+  }
+}
+
+function buildMessage(dir: string, result: JobResult): string {
+  const stdout = readTail(join(dir, "stdout.log"));
+  const stderr = readTail(join(dir, "stderr.log"));
+  const parts: string[] = [];
+  if (stdout.text.trim() || stdout.truncated) {
+    parts.push(
+      `stdout${stdout.truncated ? ` (truncated, full output: ${join(dir, "stdout.log")})` : ""}:\n${stdout.text.trim()}`,
+    );
+  }
+  if (stderr.text.trim() || stderr.truncated) {
+    parts.push(
+      `stderr${stderr.truncated ? ` (truncated, full output: ${join(dir, "stderr.log")})` : ""}:\n${stderr.text.trim()}`,
+    );
+  }
+  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;
+  const userId = owner.slice(0, nul);
+  const topicId = owner.slice(nul + 1);
+  if (!userId || !topicId) return null;
+  return { userId, topicId };
+}
+
+function injectedMarker(dir: string): string {
+  return join(dir, "result.json.injected");
+}
+
+/** One sweep: deliver any new `result.json`, then reap old delivered jobs. */
+export async function flushBashrsCompletions(): Promise<void> {
+  let entries: string[];
+  try {
+    entries = readdirSync(BASHRS_SPILL_ROOT);
+  } catch {
+    return; // Nothing spawned yet.
+  }
+
+  const now = Date.now();
+  for (const bashId of entries) {
+    const dir = join(BASHRS_SPILL_ROOT, bashId);
+    const resultPath = join(dir, "result.json");
+    const marker = injectedMarker(dir);
+
+    // Already delivered: sweep once the retention window has passed.
+    try {
+      const markerStat = statSync(marker);
+      if (now - markerStat.mtimeMs > RETENTION_MS) {
+        rmSync(dir, { recursive: true, force: true });
+      }
+      continue;
+    } catch {
+      // No marker yet — fall through to try delivering it.
+    }
+
+    let raw: string;
+    try {
+      raw = readFileSync(resultPath, "utf8");
+    } catch {
+      continue; // Job still running, or not a bash-rs dir at all.
+    }
+
+    let result: unknown;
+    try {
+      result = JSON.parse(raw);
+    } catch (err) {
+      logger.warn({ err, dir }, "bashrs-completions: corrupt result.json, skipping");
+      continue;
+    }
+    if (!isJobResult(result)) {
+      logger.warn({ dir }, "bashrs-completions: result.json missing bash_id/owner, skipping");
+      continue;
+    }
+
+    const parsed = parseOwner(result.owner);
+    if (!parsed) {
+      // Not negotium's convention (e.g. clawgram's bare-topic owner, or a
+      // standalone curl user) — nothing for this watcher to do with it.
+      continue;
+    }
+
+    try {
+      // 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),
+      });
+      renameSync(resultPath, marker);
+      logger.info(
+        { bashId: result.bash_id, userId: parsed.userId, topicId: parsed.topicId },
+        "bashrs-completions: delivered",
+      );
+    } catch (err) {
+      // Leave result.json in place — the next sweep retries. At-least-once,
+      // same as every other outbox in this codebase.
+      logger.warn({ err, dir }, "bashrs-completions: delivery failed, will retry");
+    }
+  }
+}
+
+let watcher: ReturnType<typeof watchDir> | null = null;
+let fallbackTimer: ReturnType<typeof setInterval> | null = null;
+let debouncedTrigger: (() => void) | null = null;
+let leadershipTimer: ReturnType<typeof setInterval> | null = null;
+let workerLease: RuntimeProcessLeaseHandle | null = null;
+let workerStarted = false;
+
+function stopLeaderResources(): void {
+  if (watcher) {
+    watcher.close();
+    watcher = null;
+  }
+  if (fallbackTimer) {
+    clearInterval(fallbackTimer);
+    fallbackTimer = null;
+  }
+  debouncedTrigger = null;
+}
+
+function tryBecomeLeader(): void {
+  if (!workerStarted || workerLease) return;
+  const acquired = acquireRuntimeProcessLease(PROCESS_ROLE, {
+    onLost: () => {
+      if (workerLease !== acquired) return;
+      workerLease = null;
+      stopLeaderResources();
+      logger.warn("bashrs-completions: worker leadership lost");
+    },
+  });
+  if (!acquired) return;
+
+  workerLease = acquired;
+  debouncedTrigger = debouncedFlush(flushBashrsCompletions, "bashrs-completions", 200);
+  watcher = watchDir(BASHRS_SPILL_ROOT, () => debouncedTrigger?.());
+  fallbackTimer = setInterval(() => debouncedTrigger?.(), FALLBACK_INTERVAL_MS);
+  fallbackTimer.unref?.();
+
+  logger.info(
+    { dir: BASHRS_SPILL_ROOT, role: PROCESS_ROLE },
+    "bashrs-completions: worker leadership acquired",
+  );
+  void flushBashrsCompletions();
+}
+
+/**
+ * Join the bashrs-completions worker election — same one-leader-per-role
+ * lease as `startSessionInboxWorker`, so exactly one runtime process watches
+ * `BASHRS_SPILL_ROOT` regardless of how many are up. Returns a cleanup
+ * function for graceful shutdown.
+ */
+export function startBashrsCompletionsWorker(): () => void {
+  if (workerStarted) return () => {};
+  workerStarted = true;
+
+  tryBecomeLeader();
+  leadershipTimer = setInterval(tryBecomeLeader, PROCESS_LEASE_HEARTBEAT_MS);
+  leadershipTimer.unref?.();
+
+  return () => {
+    if (!workerStarted) return;
+    workerStarted = false;
+    if (leadershipTimer) {
+      clearInterval(leadershipTimer);
+      leadershipTimer = null;
+    }
+    stopLeaderResources();
+    workerLease?.stop();
+    workerLease = null;
+    logger.info("bashrs-completions: worker stopped");
+  };
+}

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.12";
+export const NEGOTIUM_VERSION = "0.2.14";

package/dist/runtime-helpers.js

@@ -496,6 +496,18 @@ 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.5";
+function resolveBashRsBin(envValue) {
+  const override = envValue?.trim();
+  const candidate = override ? resolve(override) : resolve(BINARIES_DIR, "bash-rs", BASH_RS_VERSION, "bash-rs");
+  try {
+    accessSync(candidate, constants.X_OK);
+    return candidate;
+  } catch {
+    return;
+  }
+}
+var BASH_RS_BIN = resolveBashRsBin(envText("NEGOTIUM_BASH_RS_BIN"));
 function resolveBrowserMcpBin(envValue) {
   const override = envValue?.trim();
   if (override)
@@ -515,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);
@@ -572,6 +583,7 @@ var DM_CMD_DIR = resolve(RUN_DIR, "dm-commands");
 var DM_RESP_DIR = resolve(RUN_DIR, "dm-responses");
 var SESSION_INBOX_DIR = resolve(RUN_DIR, "session-inbox");
 var SESSION_ASKS_DIR = resolve(RUN_DIR, "session-asks");
+var BASHRS_SPILL_ROOT = resolve(RUN_DIR, "bashrs");
 var PLAYWRIGHT_BASE_PORT = parsePortEnv(process.env.PLAYWRIGHT_BASE_PORT, 9100);
 var PLAYWRIGHT_MAX_PORT = parsePortEnv(process.env.PLAYWRIGHT_MAX_PORT, 9499);
 var PLAYWRIGHT_PORTS_DIR = resolve(RUN_DIR, "playwright-ports");
@@ -1133,4 +1145,4 @@ export {
   CLAUDE_EFFORT_VALUES
 };
 
-//# debugId=530C52D9E19716B564756E2164756E21
+//# debugId=856D33930FED17E364756E2164756E21