@rind-ai/cli 0.4.1 → 0.6.0

package/lib/runtime-client.js

@@ -1,201 +1,249 @@
-import { spawn, spawnSync } from "node:child_process";
-import path from "node:path";
-
-import { buildRuntimeEnv } from "./runtime-env.js";
-import { createRuntimeRequest, runtimeRequestId } from "./runtime-protocol.js";
-
-export function resolveRuntimeLaunch({ python, repoRoot, runtimePath = "", cliArgs = [] }) {
-  const executable = runtimePath
-    ? { command: runtimePath, args: [] }
-    : { command: python, args: [path.join(repoRoot, "main.py")] };
-  const traceFlag = isTraceLlmEnvSet() ? ["--trace-llm"] : [];
-  return {
-    command: executable.command,
-    args: [...executable.args, "app-server", "--stdio", ...traceFlag, ...cliArgs],
-  };
-}
-
-const TRACE_TRUTHY = new Set(["1", "true", "yes", "on"]);
-export function isTraceLlmEnvSet() {
-  return TRACE_TRUTHY.has(String(process.env.RIND_TRACE_LLM || "").trim().toLowerCase());
-}
-
-export function runHelpVersion({ python, repoRoot, runtimePath = "", cliArgs, cwd = process.cwd() }) {
-  const executable = runtimePath
-    ? { command: runtimePath, args: [] }
-    : { command: python, args: [path.join(repoRoot, "main.py")] };
-  const result = spawnSync(executable.command, [...executable.args, ...cliArgs], {
-    cwd,
-    env: buildRuntimeEnv(repoRoot, process.env, { sourceRuntime: !runtimePath }),
-    stdio: "inherit",
-  });
-  return result.status ?? 1;
-}
-
-export function createRuntimeClient({
-  python,
-  repoRoot,
-  cliArgs = [],
-  cwd = process.cwd(),
-  rindHome = process.env.RIND_HOME,
-  runtimePath = process.env.RIND_RUNTIME_PATH || "",
-  onEvent = () => {},
-  onMessage = null,
-  onStderr = () => {},
-  onExit = () => {},
-}) {
-  const handleEvent = onMessage || onEvent;
-  const launch = resolveRuntimeLaunch({ python, repoRoot, runtimePath, cliArgs });
-
-  let nextId = 1;
-  let stdoutBuffer = "";
-  let closing = false;
-  let killTimer = null;
-  let exitHandled = false;
-  const pending = new Map();
-  const child = spawn(launch.command, launch.args, {
-    cwd,
-    env: buildRuntimeEnv(repoRoot, process.env, {
-      sourceRuntime: !runtimePath,
-      rindHome,
-    }),
-    stdio: ["pipe", "pipe", "pipe"],
-  });
-
-  child.stdout.setEncoding("utf8");
-  child.stdout.on("data", (chunk) => {
-    stdoutBuffer += chunk;
-    const lines = stdoutBuffer.split(/\r?\n/);
-    stdoutBuffer = lines.pop() || "";
-    for (const line of lines) {
-      if (line) {
-        receive(line);
-      }
-    }
-  });
-  child.stderr.on("data", (chunk) => onStderr(chunk));
-  child.once("error", (error) => {
-    handleExit(null, null, error);
-  });
-  child.once("exit", (code, signal) => {
-    handleExit(code, signal);
-  });
-
-  function handleExit(code, signal, cause = null) {
-    if (exitHandled) {
-      return;
-    }
-    exitHandled = true;
-    clearKillTimer();
-    const error = cause || new Error(`Runtime exited with ${signal || code}`);
-    for (const { reject } of pending.values()) {
-      reject(error);
-    }
-    pending.clear();
-    onExit(code, signal, { closing, error });
-  }
-
+import { spawn, spawnSync } from "node:child_process";
+import path from "node:path";
+
+import { buildRuntimeEnv } from "./runtime-env.js";
+import {
+  createRuntimeRequest,
+  isRuntimeEvent,
+  isRuntimeResponse,
+  runtimeMethods,
+  runtimeRequestId,
+} from "./runtime-protocol.js";
+
+export function resolveRuntimeLaunch({ python, repoRoot, runtimePath = "", cliArgs = [] }) {
+  const executable = runtimePath
+    ? { command: runtimePath, args: [] }
+    : { command: python, args: [path.join(repoRoot, "main.py")] };
+  const traceFlag = isTraceLlmEnvSet() ? ["--trace-llm"] : [];
+  return {
+    command: executable.command,
+    args: [...executable.args, "app-server", "--stdio", ...traceFlag, ...cliArgs],
+  };
+}
+
+const TRACE_TRUTHY = new Set(["1", "true", "yes", "on"]);
+export function isTraceLlmEnvSet() {
+  return TRACE_TRUTHY.has(String(process.env.RIND_TRACE_LLM || "").trim().toLowerCase());
+}
+
+// Turns stream for as long as the model runs; every other method must answer
+// within a bounded window so a stalled runtime surfaces as an error, not silence.
+const LONG_RUNNING_METHODS = new Set([runtimeMethods.sessionPrompt, runtimeMethods.sessionFollowUp]);
+const REQUEST_TIMEOUT_MS = 120_000;
+
+export function runHelpVersion({ python, repoRoot, runtimePath = "", cliArgs, cwd = process.cwd() }) {
+  const executable = runtimePath
+    ? { command: runtimePath, args: [] }
+    : { command: python, args: [path.join(repoRoot, "main.py")] };
+  const result = spawnSync(executable.command, [...executable.args, ...cliArgs], {
+    cwd,
+    env: buildRuntimeEnv(repoRoot, process.env, { sourceRuntime: !runtimePath }),
+    stdio: "inherit",
+  });
+  return result.status ?? 1;
+}
+
+export function createRuntimeClient({
+  python,
+  repoRoot,
+  cliArgs = [],
+  cwd = process.cwd(),
+  rindHome = process.env.RIND_HOME,
+  runtimePath = process.env.RIND_RUNTIME_PATH || "",
+  onEvent = () => {},
+  onMessage = null,
+  onStderr = () => {},
+  onExit = () => {},
+}) {
+  const handleEvent = onMessage || onEvent;
+  const launch = resolveRuntimeLaunch({ python, repoRoot, runtimePath, cliArgs });
+
+  let nextId = 1;
+  let stdoutBuffer = "";
+  let closing = false;
+  let killTimer = null;
+  let exitHandled = false;
+  const pending = new Map();
+  let child = null;
+
+  function start() {
+    if (child && !child.killed && child.exitCode === null) {
+      return child;
+    }
+    if (closing) {
+      throw new Error("Runtime is shutting down.");
+    }
+    stdoutBuffer = "";
+    exitHandled = false;
+    child = spawn(launch.command, launch.args, {
+      cwd,
+      env: buildRuntimeEnv(repoRoot, process.env, {
+        sourceRuntime: !runtimePath,
+        rindHome,
+      }),
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdoutBuffer += chunk;
+      const lines = stdoutBuffer.split(/\r?\n/);
+      stdoutBuffer = lines.pop() || "";
+      for (const line of lines) {
+        if (line) {
+          receive(line);
+        }
+      }
+    });
+    child.stderr.on("data", (chunk) => onStderr(chunk));
+    child.once("error", (error) => {
+      handleExit(null, null, error);
+    });
+    child.once("exit", (code, signal) => {
+      handleExit(code, signal);
+    });
+    return child;
+  }
+
+  function handleExit(code, signal, cause = null) {
+    if (exitHandled) {
+      return;
+    }
+    exitHandled = true;
+    clearKillTimer();
+    const error = cause || new Error(`Runtime exited with ${signal || code}`);
+    for (const entry of pending.values()) {
+      clearRequestTimer(entry);
+      entry.reject(error);
+    }
+    pending.clear();
+    child = null;
+    onExit(code, signal, { closing, error });
+  }
+
   function request(method, params = {}) {
     const id = nextId++;
     return new Promise((resolve, reject) => {
-      if (!child.stdin.writable || child.destroyed) {
-        reject(new Error("Runtime stdin is closed. Restart Rind and try again."));
+      if (!child || !child.stdin.writable || child.destroyed) {
+        reject(new Error("Runtime is not running. Start it before sending a request."));
         return;
       }
-      pending.set(id, { resolve, reject });
-      child.stdin.write(JSON.stringify(createRuntimeRequest(id, method, params)) + "\n", (error) => {
-        if (!error) {
-          return;
-        }
-        pending.delete(id);
-        reject(error);
-      });
-    });
-  }
-
-  function receive(line) {
-    let message;
-    try {
-      message = JSON.parse(line);
-    } catch {
-      return;
-    }
-    if (message.kind === "response") {
-      finishRequest(message);
-      return;
-    }
-    if (message.kind === "event") {
-      handleEvent(message);
-    }
-  }
-
-  function finishRequest(message) {
-    const id = runtimeRequestId(message);
-    const callbacks = pending.get(id);
-    if (!callbacks) {
-      return;
-    }
-    pending.delete(id);
-    if (message.error) {
-      callbacks.reject(new Error(message.error.message || "Runtime request failed"));
-    } else {
-      callbacks.resolve(message.result);
-    }
-  }
-
-  function shutdown() {
-    if (closing) {
-      return Promise.resolve();
-    }
-    closing = true;
-    scheduleKill();
-    return request("shutdown").catch(() => {
-      forceShutdown();
-    }).finally(() => {
-      if (child.stdin.writable) {
-        child.stdin.end();
-      }
-    });
-  }
-
-  function forceShutdown() {
-    closing = true;
-    clearKillTimer();
-    if (!child.killed && child.exitCode === null) {
-      try {
-        child.kill("SIGKILL");
-      } catch {
-        // Ignore kill races during shutdown.
-      }
-    }
-  }
-
-  function closeInput() {
-    if (child.stdin.writable) {
-      child.stdin.end();
-    }
-  }
-
-  function scheduleKill() {
-    clearKillTimer();
-    killTimer = setTimeout(forceShutdown, 1500);
-    killTimer.unref?.();
-  }
-
-  function clearKillTimer() {
-    if (!killTimer) {
-      return;
-    }
-    clearTimeout(killTimer);
-    killTimer = null;
+      const entry = { resolve, reject };
+      if (!LONG_RUNNING_METHODS.has(method)) {
+        entry.timer = setTimeout(() => {
+          pending.delete(id);
+          reject(new Error(`Runtime request timed out after ${REQUEST_TIMEOUT_MS / 1000}s: ${method}`));
+        }, REQUEST_TIMEOUT_MS);
+        entry.timer.unref?.();
+      }
+      pending.set(id, entry);
+      child.stdin.write(JSON.stringify(createRuntimeRequest(id, method, params)) + "\n", (error) => {
+        if (!error) {
+          return;
+        }
+        pending.delete(id);
+        clearRequestTimer(entry);
+        reject(error);
+      });
+    });
   }
 
-  return {
-    child,
+  function receive(line) {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (isRuntimeResponse(message)) {
+      finishRequest(message);
+      return;
+    }
+    if (isRuntimeEvent(message)) {
+      handleEvent(message);
+    }
+  }
+
+  function finishRequest(message) {
+    const id = runtimeRequestId(message);
+    const callbacks = pending.get(id);
+    if (!callbacks) {
+      return;
+    }
+    pending.delete(id);
+    clearRequestTimer(callbacks);
+    if (message.error) {
+      callbacks.reject(new Error(message.error.message || "Runtime request failed"));
+    } else {
+      callbacks.resolve(message.result);
+    }
+  }
+
+  function clearRequestTimer(entry) {
+    if (entry.timer) {
+      clearTimeout(entry.timer);
+      entry.timer = null;
+    }
+  }
+
+  function shutdown() {
+    if (closing) {
+      return Promise.resolve();
+    }
+    closing = true;
+    if (!child) {
+      return Promise.resolve();
+    }
+    scheduleKill();
+    return request(runtimeMethods.shutdown).catch(() => {
+      forceShutdown();
+    }).finally(() => {
+      if (child?.stdin.writable) {
+        child.stdin.end();
+      }
+    });
+  }
+
+  function forceShutdown() {
+    closing = true;
+    clearKillTimer();
+    if (child && !child.killed && child.exitCode === null) {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        // Ignore kill races during shutdown.
+      }
+    }
+  }
+
+  function closeInput() {
+    if (child?.stdin.writable) {
+      child.stdin.end();
+    }
+  }
+
+  function scheduleKill() {
+    clearKillTimer();
+    killTimer = setTimeout(forceShutdown, 1500);
+    killTimer.unref?.();
+  }
+
+  function clearKillTimer() {
+    if (!killTimer) {
+      return;
+    }
+    clearTimeout(killTimer);
+    killTimer = null;
+  }
+
+  return {
+    get child() {
+      return child;
+    },
+    start,
     request,
-    shutdown,
-    forceShutdown,
-    closeInput,
-    isClosing: () => closing,
-  };
-}
+    shutdown,
+    forceShutdown,
+    closeInput,
+    isClosing: () => closing,
+  };
+}

package/lib/runtime-env.js

@@ -1,21 +1,21 @@
-import path from "node:path";
-
-export function buildRuntimeEnv(repoRoot, baseEnv = process.env, { sourceRuntime = true, rindHome } = {}) {
-  const env = { ...baseEnv };
-  if (rindHome) {
-    env.RIND_HOME = rindHome;
-  }
-  if (!sourceRuntime) {
-    return env;
-  }
-  return {
-    ...env,
-    PYTHONIOENCODING: "utf-8",
-    PYTHONPATH: prependPath(repoRoot, baseEnv.PYTHONPATH),
-    PYTHONUTF8: "1",
-  };
-}
-
-function prependPath(entry, value) {
-  return value ? `${entry}${path.delimiter}${value}` : entry;
-}
+import path from "node:path";
+
+export function buildRuntimeEnv(repoRoot, baseEnv = process.env, { sourceRuntime = true, rindHome } = {}) {
+  const env = { ...baseEnv };
+  if (rindHome) {
+    env.RIND_HOME = rindHome;
+  }
+  if (!sourceRuntime) {
+    return env;
+  }
+  return {
+    ...env,
+    PYTHONIOENCODING: "utf-8",
+    PYTHONPATH: prependPath(repoRoot, baseEnv.PYTHONPATH),
+    PYTHONUTF8: "1",
+  };
+}
+
+function prependPath(entry, value) {
+  return value ? `${entry}${path.delimiter}${value}` : entry;
+}

package/lib/runtime-protocol.js

@@ -1,15 +1,122 @@
-export function createRuntimeRequest(requestId, method, params = {}) {
-  return { request_id: requestId, method, params };
-}
-
-export function runtimeRequestId(message) {
-  return message?.request_id;
-}
-
-export function runtimeEventType(message) {
-  return message?.event_type || message?.event?.type || "";
-}
-
-export function turnInputMethod(activeTurn) {
-  return activeTurn ? "turn.follow_up" : "turn.start";
-}
+export const runtimeProtocolVersion = "2";
+
+export const REASONING_EFFORTS = Object.freeze(["low", "medium", "high", "xhigh", "max"]);
+
+export const runtimeMethods = Object.freeze({
+  initialize: "initialize",
+  shutdown: "shutdown",
+  sessionNew: "session/new",
+  sessionList: "session/list",
+  sessionSwitch: "session/switch",
+  sessionReplay: "session/replay",
+  sessionPrompt: "session/prompt",
+  sessionCancel: "session/cancel",
+  modelList: "model/list",
+  modelSet: "model/set",
+  modelEffortSet: "model/effort",
+  sessionSteer: "rind/session/steer",
+  sessionFollowUp: "rind/session/follow_up",
+  sessionPromoteFollowUp: "rind/session/promote_follow_up",
+  sessionUnsteer: "rind/session/unsteer",
+  sessionDequeueFollowUp: "rind/session/dequeue_follow_up",
+  sessionCompact: "rind/session/compact",
+  commandExecute: "rind/command/execute",
+  userQuestionRespond: "rind/user-question/respond",
+  backgroundList: "rind/background/list",
+  backgroundOutput: "rind/background/output",
+  goalGet: "rind/goal/get",
+  goalSet: "rind/goal/set",
+  goalStatus: "rind/goal/status",
+  goalClear: "rind/goal/clear",
+});
+
+export const sessionScopedMethods = new Set([
+  runtimeMethods.sessionPrompt,
+  runtimeMethods.sessionReplay,
+  runtimeMethods.sessionSwitch,
+  runtimeMethods.sessionCancel,
+  runtimeMethods.modelSet,
+  runtimeMethods.modelEffortSet,
+  runtimeMethods.sessionSteer,
+  runtimeMethods.sessionFollowUp,
+  runtimeMethods.sessionPromoteFollowUp,
+  runtimeMethods.sessionUnsteer,
+  runtimeMethods.sessionDequeueFollowUp,
+  runtimeMethods.sessionCompact,
+  runtimeMethods.commandExecute,
+  runtimeMethods.userQuestionRespond,
+  runtimeMethods.backgroundList,
+  runtimeMethods.backgroundOutput,
+  runtimeMethods.goalGet,
+  runtimeMethods.goalSet,
+  runtimeMethods.goalStatus,
+  runtimeMethods.goalClear,
+]);
+
+export const turnScopedMethods = new Set([
+  runtimeMethods.sessionCancel,
+  runtimeMethods.sessionSteer,
+]);
+
+export function createRuntimeRequest(requestId, method, params = {}) {
+  return { kind: "request", request_id: requestId, method, params };
+}
+
+export function isRuntimeResponse(message) {
+  return message?.kind === "response"
+    && isRequestId(message.request_id)
+    && (Object.hasOwn(message, "result") || isRuntimeError(message.error));
+}
+
+export function isRuntimeEvent(message) {
+  return message?.kind === "event"
+    && message.method === "session/update"
+    && Number.isInteger(message.sequence)
+    && (message.durability === "durable" || message.durability === "incremental")
+    && typeof message.session_id === "string"
+    && typeof message.turn_id === "string"
+    && isRecord(message.event);
+}
+
+export function requireRuntimeInitialization(result) {
+  if (!isRecord(result) || result.protocol_version !== runtimeProtocolVersion) {
+    const received = isRecord(result) ? String(result.protocol_version || "missing") : "invalid";
+    throw new Error(`Unsupported Runtime protocol version: ${received}.`);
+  }
+  if (!Array.isArray(result.capabilities) || !Array.isArray(result.methods)) {
+    throw new Error("Runtime initialization response is missing capabilities or methods.");
+  }
+  return result;
+}
+
+export function runtimeRequestId(message) {
+  return message?.request_id;
+}
+
+export function runtimeEventType(message) {
+  return message?.event?.type || "";
+}
+
+export function isRuntimeEventForTurn(message, sessionId = "", turnId = "") {
+  const eventSessionId = String(message?.session_id || "");
+  if (sessionId && eventSessionId && eventSessionId !== sessionId) {
+    return false;
+  }
+  if (runtimeEventType(message) === "turn_started") {
+    return Boolean(String(message?.turn_id || ""));
+  }
+  const eventTurnId = String(message?.turn_id || "");
+  return !eventTurnId || Boolean(turnId && eventTurnId === turnId);
+}
+
+function isRequestId(value) {
+  return (typeof value === "string" && value.trim()) || (typeof value === "number" && Number.isFinite(value));
+}
+
+function isRuntimeError(value) {
+  return isRecord(value) && typeof value.type === "string" && typeof value.message === "string";
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/lib/slash-command-mode.js

@@ -1,14 +1,3 @@
-export function isReadonlySlashCommand(value) {
-  const text = String(value || "").trim().toLowerCase();
-  return text === "/status" || text.startsWith("/status ") || text === "/doctor" || text.startsWith("/doctor ");
-}
-
-export function steeringCommandText(value) {
-  const text = String(value || "").trim();
-  const match = text.match(/^\/steer(?:\s+([\s\S]*))?$/i);
-  return match ? String(match[1] || "").trim() : null;
-}
-
 export function parseGoalCommand(value) {
   const text = String(value || "").trim();
   const match = text.match(/^\/goal(?:\s+([\s\S]*))?$/i);