negotium 0.1.6 → 0.1.8

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

@@ -0,0 +1,18 @@
+/** "from" field for session-inbox entries injected after a setting change. */
+export const FROM_AUTO_CONTINUE = "auto-continue";
+
+/** "from" field for durable delayed continuations created by schedule_self. */
+export const FROM_SELF_SCHEDULE = "self-schedule";
+
+/** Topic names that collide with internal sentinels and must not be used. */
+export const RESERVED_TOPIC_NAMES: ReadonlySet<string> = new Set([
+  FROM_AUTO_CONTINUE,
+  FROM_SELF_SCHEDULE,
+  "general",
+]);
+
+/** Legacy shared General id. New General rooms use per-user UUIDs. */
+export const GENERAL_TOPIC_ID = "general";
+
+/** Internal topic name for the forum manager session (General topic). */
+export const TOPIC_MANAGER = "__manager__";

package/dist/runtime/src/platform/debug-users.ts

@@ -0,0 +1,14 @@
+import { writeFileSync } from "node:fs";
+import { DEBUG_FILE } from "#platform/config";
+import { readJsonFile } from "#platform/jsonl";
+
+/** Load the set of debug-enabled user IDs from disk. Returns empty set on error. */
+export function loadDebugUsers(): Set<string> {
+  const arr = readJsonFile<string[]>(DEBUG_FILE);
+  return new Set(arr ?? []);
+}
+
+/** Persist the debug users set to disk. */
+export function saveDebugUsers(users: Set<string>): void {
+  writeFileSync(DEBUG_FILE, JSON.stringify([...users], null, 2));
+}

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

@@ -0,0 +1 @@
+export const delay = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));

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

@@ -0,0 +1,9 @@
+/**
+ * Stringify an unknown thrown value for logging or user-visible messages.
+ * Default fallback is `String(e)`. Pass an explicit fallback (e.g. "unknown")
+ * to override what non-Error throws turn into.
+ */
+export function errMsg(e: unknown, fallback?: string): string {
+  if (e instanceof Error) return e.message;
+  return fallback ?? String(e);
+}

package/dist/runtime/src/platform/file-utils.ts

@@ -0,0 +1,16 @@
+import { unlinkSync } from "node:fs";
+import { logger } from "#platform/logger";
+
+/**
+ * Best-effort unlink. ENOENT is always swallowed (the file is already gone).
+ * Other errors are silent unless `warnLabel` is provided, in which case they
+ * are logged at warn level with `{ err, path }` context.
+ */
+export function safeUnlink(path: string, warnLabel?: string): void {
+  try {
+    unlinkSync(path);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException)?.code === "ENOENT") return;
+    if (warnLabel) logger.warn({ err: e, path }, warnLabel);
+  }
+}

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

@@ -0,0 +1,202 @@
+import {
+  appendFileSync,
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { safeUnlink } from "#platform/file-utils";
+
+export function readJsonlLines(filePath: string): string[] {
+  return readFileSync(filePath, "utf-8").trim().split("\n").filter(Boolean);
+}
+
+/**
+ * Parse a JSONL string (one JSON value per line) into an array of `T`.
+ * Throws on malformed lines — use when a corrupt fixture/log should fail
+ * loudly rather than silently drop entries (paired with `readJsonlLines`'
+ * resilient counterpart for live data streams).
+ */
+export function parseJsonlText<T = unknown>(raw: string): T[] {
+  return raw
+    .trim()
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => JSON.parse(line) as T);
+}
+
+/**
+ * Read and JSON-parse a file. Returns null if the file is missing or contains
+ * invalid JSON. Use when a missing/corrupt file should fall through to a
+ * default rather than throw.
+ */
+export function readJsonFile<T = unknown>(filePath: string): T | null {
+  try {
+    return JSON.parse(readFileSync(filePath, "utf-8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+// --- Cross-process append lock ---
+// POSIX `O_APPEND` is only atomic when the write payload fits in PIPE_BUF
+// (Linux 4096, macOS 512). MCP servers and the bot run as separate
+// processes that all `appendFileSync` to shared inbox/outbox files; a long
+// `tell_session` prompt or large `ask_session` reply is comfortably above
+// PIPE_BUF, and a concurrent append from another process can interleave at
+// the byte level — the result fails JSON parse and the entire entry is
+// silently dropped by `parseOutboxLine`.
+//
+// Mitigation: a sidecar `<filePath>.lock` created with `O_EXCL` serializes
+// every append at the OS level. Lock is held for the duration of one
+// `appendFileSync`, so the contention window is microseconds. Stale locks
+// (process crashed mid-write) are detected via mtime and forcibly removed
+// after `LOCK_STALE_MS`. As a last resort, after `LOCK_TIMEOUT_MS` of
+// retries, the lock is bypassed — the entry survives but may interleave;
+// preferable to dropping it entirely.
+const LOCK_SUFFIX = ".lock";
+const LOCK_RETRY_MS = 5;
+const LOCK_TIMEOUT_MS = 1500;
+const LOCK_STALE_MS = 5000;
+const LOCK_SLEEP = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
+
+/** Synchronous, non-spinning sleep supported by both Bun and Node MCP workers. */
+function sleepForAppendLock(ms: number): void {
+  Atomics.wait(LOCK_SLEEP, 0, 0, ms);
+}
+
+function tryAcquireAppendLock(lockPath: string): boolean {
+  try {
+    closeSync(openSync(lockPath, "wx")); // O_CREAT | O_EXCL — atomic
+    return true;
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== "EEXIST") throw e;
+    return false;
+  }
+}
+
+function isStaleLock(lockPath: string): boolean {
+  try {
+    return Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Append a JSON-encoded entry + newline to a JSONL file. Ensures the parent
+ * directory exists and serializes concurrent multi-process appends through a
+ * sidecar lock so payloads larger than PIPE_BUF do not interleave.
+ *
+ * The drainer side (`outbox/file-ops.ts`) claims the file via atomic rename
+ * and handles recovery of leftover `.processing` files from crashes.
+ */
+export function appendJsonlEntry(filePath: string, entry: unknown): void {
+  appendJsonlLine(filePath, `${JSON.stringify(entry)}\n`);
+}
+
+/**
+ * Append an already-serialized JSONL line (must end with "\n") under the
+ * same cross-process append lock as `appendJsonlEntry`. Use when you
+ * want to write back a raw line **exactly** — e.g. flusher tail-writeback
+ * preserving lines that current parser can't decode, so a future parser
+ * release still sees them.
+ */
+export function appendJsonlLine(filePath: string, line: string): void {
+  mkdirSync(dirname(filePath), { recursive: true });
+  const lockPath = `${filePath}${LOCK_SUFFIX}`;
+  const payload = line.endsWith("\n") ? line : `${line}\n`;
+
+  let acquired = tryAcquireAppendLock(lockPath);
+  // Pre-check: if the existing lock is already stale (writer crashed before
+  // unlinking), reclaim it before sleeping. Saves the entire retry budget
+  // for the common stale-leftover case.
+  if (!acquired && isStaleLock(lockPath)) {
+    safeUnlink(lockPath);
+    acquired = tryAcquireAppendLock(lockPath);
+  }
+  if (!acquired) {
+    const start = Date.now();
+    while (!acquired && Date.now() - start < LOCK_TIMEOUT_MS) {
+      // Codex launches built-in stdio MCPs under Node+tsx while the runtime
+      // itself uses Bun. Atomics.wait gives both processes a blocking sleep
+      // without a CPU-spinning fallback or a Bun-only global.
+      sleepForAppendLock(LOCK_RETRY_MS);
+      acquired = tryAcquireAppendLock(lockPath);
+      // Recheck staleness inside the loop so a writer that crashes mid-wait
+      // doesn't leave us spinning the whole timeout.
+      if (!acquired && isStaleLock(lockPath)) {
+        safeUnlink(lockPath);
+        acquired = tryAcquireAppendLock(lockPath);
+      }
+    }
+  }
+
+  if (!acquired) {
+    // Best-effort fallback: append unlocked. Worst case the line interleaves
+    // with another writer and one of them is dropped at parse time — still
+    // better than dropping the entry on the floor here.
+    appendFileSync(filePath, payload);
+    return;
+  }
+
+  try {
+    appendFileSync(filePath, payload);
+  } finally {
+    safeUnlink(lockPath);
+  }
+}
+
+/** Overwrite a JSONL file with the given entries. Trailing newline included. */
+export function writeJsonlFile(filePath: string, entries: readonly unknown[]): void {
+  const dir = dirname(filePath);
+  mkdirSync(dir, { recursive: true });
+  const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random()
+    .toString(16)
+    .slice(2)}`;
+  const payload = `${entries.map((e) => JSON.stringify(e)).join("\n")}\n`;
+  let fd: number | null = null;
+  try {
+    fd = openSync(tmpPath, "w");
+    writeFileSync(fd, payload);
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = null;
+    renameSync(tmpPath, filePath);
+    fsyncDirectoryBestEffort(dir);
+  } catch (err) {
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch {}
+    }
+    try {
+      unlinkSync(tmpPath);
+    } catch {}
+    throw err;
+  }
+}
+
+function fsyncDirectoryBestEffort(dir: string): void {
+  let fd: number | null = null;
+  try {
+    fd = openSync(dir, "r");
+    fsyncSync(fd);
+  } catch {
+    // Directory fsync is not portable across every runtime/filesystem. The
+    // file fsync + rename above is the important integrity boundary; this is
+    // best-effort durability for the directory entry.
+  } finally {
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch {}
+    }
+  }
+}

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

@@ -0,0 +1,174 @@
+import { logger } from "#platform/logger";
+
+/**
+ * Shared process-shutdown registry.
+ *
+ * The backend has multiple subsystems that need to clean up on SIGTERM /
+ * SIGINT / beforeExit — MCP client pool, browser/background-bash
+ * children, codex process trees, and DB/runtime handles. Before this module each subsystem
+ * registered its own `process.once("SIGTERM", ...)` handler. node fires
+ * them in registration order with no priority, so a cleanup that wanted
+ * to wait for in-flight MCP calls to finish could be racing the same
+ * subprocess-kill cleanup that takes those calls' children out from under
+ * it.
+ *
+ * Replace that with a single set of signal hooks + a priority-ordered
+ * registry. Modules call `onShutdown(name, priority, fn)`; the single
+ * handler iterates handlers in priority order (highest first), awaiting
+ * each with a hard ceiling so a hung cleanup can't keep the process
+ * alive past a reasonable bound.
+ *
+ * Priority convention (rough):
+ *   - 100+: stateful network/connection resources whose in-flight calls
+ *     deserve a graceful close before any subprocess gets killed
+ *     (MCP pool, DB connections, WebSocket/server resources).
+ *   - 50:   subsystems that kill external processes / free OS handles
+ *     (playwright, background-bash, codex tree).
+ *   - 10:   final reporting / metrics flushing.
+ * Numbers are not enforced — they're a convention so the order is
+ * scrutable at a glance.
+ *
+ * Idempotent: the first signal triggers; subsequent signals are
+ * no-ops so SIGINT-then-SIGTERM doesn't double-run handlers.
+ *
+ * Test isolation: `__resetForTests()` clears the registry AND removes
+ * the installed listeners so a fresh registration in the next test
+ * starts clean.
+ */
+
+export interface ShutdownHandler {
+  name: string;
+  priority: number;
+  fn: () => Promise<void> | void;
+}
+
+const handlers: ShutdownHandler[] = [];
+let signalHooksInstalled = false;
+let triggered = false;
+let shutdownPromise: Promise<void> | null = null;
+
+/** Per-handler hard ceiling. A hung cleanup can't keep the process up
+ *  beyond this; we log and move on so subsequent handlers still run. */
+const HANDLER_TIMEOUT_MS = 5_000;
+
+/** Process-exit-after-handlers ceiling. Even if every handler hangs we
+ *  call process.exit so an orphaned bot doesn't wedge a forum forever. */
+const HARD_EXIT_TIMEOUT_MS = 15_000;
+
+/** Test-injectable signal trigger — exposed so tests can fire shutdown
+ *  without touching real process signals. */
+export type SignalReason = "beforeExit" | "SIGINT" | "SIGTERM" | "test";
+
+/**
+ * Register a shutdown handler. Lazy-installs the single process-level
+ * signal listener on first call.
+ *
+ * `priority` is highest-first (100 runs before 50). Ties keep registration
+ * order (stable sort), so two subsystems at the same tier behave
+ * deterministically across runs.
+ */
+export function onShutdown(name: string, priority: number, fn: () => Promise<void> | void): void {
+  handlers.push({ name, priority, fn });
+  ensureSignalHooks();
+}
+
+function ensureSignalHooks(): void {
+  if (signalHooksInstalled) return;
+  signalHooksInstalled = true;
+  process.once("beforeExit", () => {
+    void runShutdown("beforeExit");
+  });
+  process.once("SIGINT", () => {
+    void runShutdown("SIGINT");
+  });
+  process.once("SIGTERM", () => {
+    void runShutdown("SIGTERM");
+  });
+}
+
+/**
+ * Run every registered handler in priority order. Each handler gets a
+ * HANDLER_TIMEOUT_MS budget; if it hangs we log and continue. The whole
+ * sweep is capped at HARD_EXIT_TIMEOUT_MS — past that we call
+ * `process.exit` so a stuck cleanup can't deadlock the shutdown.
+ *
+ * `reason` is passed through to handlers so a handler can log which
+ * signal triggered it (useful for debugging which path led to exit).
+ *
+ * Exported for tests / explicit "I want shutdown now" callers.
+ */
+export function runShutdown(reason: SignalReason): Promise<void> {
+  if (shutdownPromise) return shutdownPromise;
+  triggered = true;
+  shutdownPromise = performShutdown(reason);
+  return shutdownPromise;
+}
+
+async function performShutdown(reason: SignalReason): Promise<void> {
+  logger.info({ reason, handlerCount: handlers.length }, "lifecycle: shutdown sequence starting");
+  // Stable sort: descending priority, registration order on ties.
+  const ordered = handlers
+    .map((h, i) => ({ h, i }))
+    .sort((a, b) => b.h.priority - a.h.priority || a.i - b.i)
+    .map(({ h }) => h);
+
+  const hardExit = setTimeout(() => {
+    logger.error({ reason }, "lifecycle: hard-exit ceiling reached, forcing process.exit");
+    process.exit(1);
+  }, HARD_EXIT_TIMEOUT_MS);
+  hardExit.unref?.();
+
+  for (const h of ordered) {
+    const start = Date.now();
+    let handlerTimeout: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        Promise.resolve().then(() => h.fn()),
+        new Promise<void>((_, reject) => {
+          handlerTimeout = setTimeout(
+            () => reject(new Error("handler timeout")),
+            HANDLER_TIMEOUT_MS,
+          );
+        }),
+      ]);
+      logger.info(
+        { handler: h.name, priority: h.priority, ms: Date.now() - start },
+        "lifecycle: shutdown handler completed",
+      );
+    } catch (err) {
+      logger.warn(
+        { err, handler: h.name, priority: h.priority, ms: Date.now() - start },
+        "lifecycle: shutdown handler failed or timed out (continuing)",
+      );
+    } finally {
+      if (handlerTimeout) clearTimeout(handlerTimeout);
+    }
+  }
+  clearTimeout(hardExit);
+  logger.info({ reason }, "lifecycle: shutdown sequence complete");
+}
+
+/** Test-only: clear the registry and uninstall signal hooks so the next
+ *  test's onShutdown calls start fresh. Does NOT actually call any
+ *  handler — tests that want to exercise the trigger path should call
+ *  `runShutdown("test")` after registering. */
+export function __resetForTests(): void {
+  handlers.length = 0;
+  triggered = false;
+  shutdownPromise = null;
+  signalHooksInstalled = false;
+  // No way to remove process.once listeners that haven't fired yet —
+  // they'll just become no-ops because `triggered` is false-but-handlers
+  // is empty. The signalHooksInstalled flag is reset so the next
+  // onShutdown call installs fresh listeners.
+}
+
+/** Test-only: read the registered handler count. */
+export function __handlerCount(): number {
+  return handlers.length;
+}
+
+/** Test-only: read whether triggered. */
+export function __triggered(): boolean {
+  return triggered;
+}

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

@@ -0,0 +1,31 @@
+import pino from "pino";
+
+/**
+ * Always write logs to stderr (fd 2), never stdout.
+ *
+ * MCP servers under `src/mcp/**` run as stdio subprocesses where stdout is the
+ * JSON-RPC transport channel. A single log line on stdout corrupts the next
+ * message and the MCP client closes the transport ("Transport closed"). The
+ * main bot process is also fine with stderr — pm2 captures both streams.
+ *
+ * In dev mode pino spawns a `pino-pretty` worker that owns its own sink, so we
+ * pass `destination: 2` through transport.options. In prod (no transport) the
+ * second arg to `pino()` sets the destination directly.
+ */
+export const logger = pino(
+  {
+    level: process.env.LOG_LEVEL || "info",
+    transport:
+      process.env.NODE_ENV === "development"
+        ? {
+            target: "pino-pretty",
+            options: {
+              colorize: true,
+              translateTime: "SYS:yyyy-mm-dd HH:MM:ss",
+              destination: 2,
+            },
+          }
+        : undefined,
+  },
+  pino.destination(2),
+);

package/dist/runtime/src/platform/maestro-bootstrap-env.ts

@@ -0,0 +1,3 @@
+// The SDK's login-PATH bootstrap is expected host setup, not actionable
+// runtime output. Keep it enabled while suppressing its module-load chatter.
+process.env.MAESTRO_SDK_SILENT_BOOTSTRAP ??= "1";