@algosuite/vo-mcp 0.2.0-beta.57 → 0.2.0-beta.59

package/dist/runner-supervisor.js

@@ -340,6 +340,87 @@ async function getTaskKnowledgeContextRequest(req, taskId, { query } = {}, {
   throw new Error("knowledge-context retry loop exited unexpectedly");
 }
 
+// ../../scripts/virtual-office/code-runner/control-plane-prepared-job.mjs
+var PREPARED_JOB_ENV_QUERY_KEYS = [
+  "VO_CODE_RUNNER_NO_WEB",
+  "VO_CODE_RUNNER_NO_WORKFLOW",
+  "VO_CODE_RUNNER_NO_CONSENSUS",
+  "VO_CODE_RUNNER_PERMISSION_MODE",
+  "VO_CODE_RUNNER_DEFAULT_BUDGET_USD",
+  "VO_CODE_RUNNER_META_REASONING_EFFORT",
+  "VO_CODE_RUNNER_ALLOW_MISSING_KNOWLEDGE_CONTEXT",
+  "VO_ENABLE_CONTEXT7"
+];
+var PREPARED_JOB_ENV_VALUE_MAX = 64;
+function preparedJobQuery({ agent = "claude", env = {} } = {}) {
+  const params = new URLSearchParams();
+  params.set("agent", String(agent));
+  const sent = [];
+  const dropped = [];
+  for (const key of PREPARED_JOB_ENV_QUERY_KEYS) {
+    const raw = env?.[key];
+    if (typeof raw !== "string" || raw.length === 0) continue;
+    if (raw.length > PREPARED_JOB_ENV_VALUE_MAX) {
+      dropped.push(key);
+      continue;
+    }
+    params.set(key, raw);
+    sent.push(key);
+  }
+  return { query: params.toString(), sent, dropped };
+}
+async function refusalCode(res) {
+  try {
+    const body = await res.json();
+    return typeof body?.error === "string" && body.error ? body.error : null;
+  } catch {
+    return null;
+  }
+}
+async function getPreparedJobRequest(req, taskId, options = {}, invalidateToken = () => {
+}) {
+  const { agent = "claude", env = {}, timeoutMs = 15e3 } = options;
+  const { query, sent, dropped } = preparedJobQuery({ agent, env });
+  const envMeta = { envSent: sent, envDropped: dropped };
+  if (typeof taskId !== "string" || taskId.length === 0) {
+    return { ok: false, reason: "missing_task_id", status: 0, ...envMeta };
+  }
+  const path2 = `/api/v1/code-task/${encodeURIComponent(taskId)}/prepared-job?${query}`;
+  let res;
+  try {
+    res = await req("GET", path2, void 0, { timeoutMs });
+  } catch (err) {
+    return { ok: false, reason: `transport: ${err?.message || String(err)}`, status: 0, ...envMeta };
+  }
+  if (res?.status === 401) {
+    try {
+      invalidateToken();
+    } catch {
+    }
+    return { ok: false, reason: "unauthorized", status: 401, ...envMeta };
+  }
+  if (!res?.ok) {
+    const code = await refusalCode(res);
+    return { ok: false, reason: code || `http_${res?.status ?? "unknown"}`, status: res?.status ?? 0, ...envMeta };
+  }
+  let body;
+  try {
+    body = await res.json();
+  } catch (err) {
+    return { ok: false, reason: `unreadable_body: ${err?.message || String(err)}`, status: res.status, ...envMeta };
+  }
+  const job = body?.prepared_job;
+  if (!job || typeof job !== "object") {
+    return { ok: false, reason: "no_prepared_job_in_body", status: res.status, ...envMeta };
+  }
+  return {
+    ok: true,
+    job,
+    composition: body?.composition && typeof body.composition === "object" ? body.composition : {},
+    ...envMeta
+  };
+}
+
 // ../../scripts/virtual-office/code-runner/control-plane-client.mjs
 var cachedFirebaseToken = null;
 var ClaimAuthorityChangedError = class extends Error {
@@ -569,6 +650,10 @@ function createControlPlaneClient({
         log: (m) => console.warn(`[code-runner ${(/* @__PURE__ */ new Date()).toISOString()}] ${m}`)
       });
     },
+    /** ADR-004 § 11.1b: the plane's prepared job, for SHADOW comparison. Never throws. */
+    getPreparedJob: (taskId, options) => getPreparedJobRequest(req, taskId, options, () => {
+      cachedFirebaseToken = null;
+    }),
     /** Weekly Claude token usage report — see control-plane-weekly-tokens.mjs. */
     async postWeeklyTokens(report) {
       return postWeeklyTokensRequest(taskReq, report, () => {
@@ -590,8 +675,8 @@ function createControlPlaneClient({
      * authenticated operator so the web shows a TRUE "runner online" signal.
      * Best-effort caller; throws on 401/non-ok so the daemon can log + retry.
      */
-    async postHeartbeat({ runnerId: runnerId3, runnerInstanceId: runnerInstanceId2, operatorId, uptimeSec, activeTasks, maxConcurrency, effectiveConcurrency, measuredTaskSlots, measuredCpuSlots, measuredMemorySlots, version, daemonVersion, defaultAgent, supervisorInstanceId: supervisorInstanceId2, supervisorVersion: supervisorVersion2, supervisorCapabilities, servedRepos, servedOperators, availableAgents, accountUsage, availableLocalModels }) {
-      const body = { runner_id: runnerId3 };
+    async postHeartbeat({ runnerId: runnerId3, runnerInstanceId: runnerInstanceId2, operatorId, uptimeSec, activeTasks, maxConcurrency, effectiveConcurrency, measuredTaskSlots, measuredCpuSlots, measuredMemorySlots, version, daemonVersion, defaultAgent, supervisorInstanceId: supervisorInstanceId2, supervisorVersion: supervisorVersion2, supervisorCapabilities, servedRepos, servedOperators, availableAgents, accountUsage, availableLocalModels, prepared_job_shadow: preparedJobShadow }) {
+      const body = { runner_id: runnerId3, ...preparedJobShadow ? { prepared_job_shadow: preparedJobShadow } : {} };
       if (runnerInstanceId2) body.runner_instance_id = runnerInstanceId2;
       if (operatorId) body.operator_id = operatorId;
       if (typeof uptimeSec === "number") body.uptime_sec = uptimeSec;
@@ -2318,6 +2403,157 @@ function resolveSupervisorChildEntry({
   };
 }
 
+// src/runner/update-drain-gate.mjs
+var DEFAULT_DRAIN_CAP_MS = 45 * 60 * 1e3;
+var DEFAULT_DRAIN_CHECK_MS = 3e4;
+var MAX_DRAIN_CAP_MS = 6 * 60 * 60 * 1e3;
+var MIN_DRAIN_CHECK_MS = 1e3;
+var MAX_DRAIN_CHECK_MS = 5 * 60 * 1e3;
+var UPDATE_RESTART_ERROR_MESSAGE = "runner update restart after drain timeout";
+var UPDATE_RESTART_RESULT = "runner_update_restart";
+var sleepMs = (ms) => new Promise((resolve5) => setTimeout(resolve5, ms));
+function positiveNumber(raw) {
+  if (raw === void 0 || raw === null || String(raw).trim() === "") return null;
+  const value = Number(raw);
+  return Number.isFinite(value) && value >= 0 ? value : null;
+}
+function resolveDrainCapMs(env = {}) {
+  const ms = positiveNumber(env.VO_RUNNER_UPDATE_DRAIN_CAP_MS);
+  if (ms !== null) return Math.min(ms, MAX_DRAIN_CAP_MS);
+  const minutes = positiveNumber(env.VO_RUNNER_UPDATE_DRAIN_CAP_MIN);
+  if (minutes !== null) return Math.min(minutes * 6e4, MAX_DRAIN_CAP_MS);
+  return DEFAULT_DRAIN_CAP_MS;
+}
+function resolveDrainCheckMs(env = {}) {
+  const ms = positiveNumber(env.VO_RUNNER_UPDATE_DRAIN_CHECK_MS);
+  if (ms === null) return DEFAULT_DRAIN_CHECK_MS;
+  return Math.min(Math.max(ms, MIN_DRAIN_CHECK_MS), MAX_DRAIN_CHECK_MS);
+}
+function readActiveTasks(status, { childRunning = true } = {}) {
+  if (!childRunning) {
+    return { count: 0, ids: [], known: true, runnerId: null, runnerInstanceId: null };
+  }
+  if (!status || status.ok === false) {
+    return { count: 0, ids: [], known: false, runnerId: null, runnerInstanceId: null };
+  }
+  const ids = Array.isArray(status.activeTaskIds) ? status.activeTaskIds.map((id) => String(id)).filter(Boolean) : [];
+  const reported = Number(status.activeTasks);
+  const count = Number.isFinite(reported) && reported >= 0 ? reported : ids.length;
+  return {
+    count: Math.max(count, ids.length),
+    ids,
+    known: true,
+    runnerId: status.runnerId ? String(status.runnerId) : null,
+    runnerInstanceId: status.runnerInstanceId ? String(status.runnerInstanceId) : null
+  };
+}
+function decideDrainStep({ active, elapsedMs, capMs }) {
+  const busy = active.known ? active.count : "unknown";
+  if (active.known && active.count === 0) return { action: "proceed", busy };
+  if (elapsedMs >= capMs) return { action: "cap", busy };
+  return { action: "wait", busy };
+}
+function describeBusy(active) {
+  if (!active.known) return "status unreadable from a running child (assumed busy)";
+  const ids = active.ids.length > 0 ? ` [${active.ids.join(", ")}]` : " [ids unavailable]";
+  return `${active.count} active task(s)${ids}`;
+}
+async function markCappedTasks({ active, failInFlightTask, log }) {
+  if (active.ids.length === 0) {
+    if (active.count > 0 || !active.known) {
+      log(`update drain cap reached with ${describeBusy(active)} \u2014 cannot annotate tasks the runner did not name`);
+    }
+    return [];
+  }
+  const marked = [];
+  for (const taskId of active.ids) {
+    try {
+      await failInFlightTask(taskId, {
+        message: UPDATE_RESTART_ERROR_MESSAGE,
+        result: UPDATE_RESTART_RESULT,
+        runnerId: active.runnerId,
+        runnerInstanceId: active.runnerInstanceId
+      });
+      marked.push(taskId);
+    } catch (error) {
+      log(`could not mark task ${taskId} before update restart: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return marked;
+}
+async function awaitRunnerUpdateDrain({
+  readStatus,
+  isChildRunning = () => true,
+  failInFlightTask = async () => {
+  },
+  drainable = false,
+  env = {},
+  now = Date.now,
+  sleep: sleep2 = sleepMs,
+  log = () => {
+  }
+} = {}) {
+  const capMs = resolveDrainCapMs(env);
+  const checkMs = resolveDrainCheckMs(env);
+  const startedAt = now();
+  let checks = 0;
+  let lastReported = null;
+  const snapshot = async () => {
+    checks += 1;
+    const childRunning = Boolean(isChildRunning());
+    let status;
+    try {
+      status = await readStatus();
+    } catch {
+      status = null;
+    }
+    return readActiveTasks(status, { childRunning });
+  };
+  if (!drainable) {
+    const active = await snapshot();
+    if (active.known && active.count > 0) {
+      return {
+        proceed: false,
+        detail: `deferred safely: ${active.count} active task(s); retry when the runner is idle`,
+        capped: false,
+        waitedMs: 0,
+        checks,
+        markedTaskIds: []
+      };
+    }
+    return { proceed: true, detail: "runner idle", capped: false, waitedMs: 0, checks, markedTaskIds: [] };
+  }
+  for (; ; ) {
+    const active = await snapshot();
+    const elapsedMs = now() - startedAt;
+    const step = decideDrainStep({ active, elapsedMs, capMs });
+    if (step.action === "proceed") {
+      if (lastReported !== null) {
+        log(`update drain complete after ${Math.round(elapsedMs / 1e3)}s \u2014 runner idle, applying staged update restart`);
+      }
+      return { proceed: true, detail: "runner idle", capped: false, waitedMs: elapsedMs, checks, markedTaskIds: [] };
+    }
+    if (step.action === "cap") {
+      log(`update drain cap reached after ${Math.round(elapsedMs / 1e3)}s (cap ${Math.round(capMs / 1e3)}s) \u2014 ${describeBusy(active)}; marking task(s) before restart`);
+      const markedTaskIds = await markCappedTasks({ active, failInFlightTask, log });
+      return {
+        proceed: true,
+        capped: true,
+        detail: `update restart applied after drain cap; marked ${markedTaskIds.length} task(s) as "${UPDATE_RESTART_ERROR_MESSAGE}"`,
+        waitedMs: elapsedMs,
+        checks,
+        markedTaskIds
+      };
+    }
+    const fingerprint = `${step.busy}:${active.ids.join(",")}`;
+    if (fingerprint !== lastReported) {
+      lastReported = fingerprint;
+      log(`deferring staged update restart \u2014 ${describeBusy(active)}; re-checking every ${Math.round(checkMs / 1e3)}s until idle (cap ${Math.round(capMs / 1e3)}s)`);
+    }
+    await sleep2(Math.max(1, Math.min(checkMs, capMs - elapsedMs)));
+  }
+}
+
 // src/runner/supervisor-child-env.mjs
 import { hostname as systemHostname } from "node:os";
 
@@ -3408,22 +3644,24 @@ async function main() {
       }
       deferredControlRecoveryGeneration = null;
       handling = true;
-      const beforeStop = await localStatus();
-      if (beforeStop && Number(beforeStop.activeTasks || 0) > 0) {
-        await client.completeRunnerControl(action.actionId, {
-          runnerId,
-          ...operatorId ? { operatorId } : {},
-          ...supervisorControlIdentity,
-          status: "failed",
-          detail: `deferred safely: ${beforeStop.activeTasks} active task(s); retry when the runner is idle`
-        });
+      const controlIdentity = { runnerId, ...operatorId ? { operatorId } : {}, ...supervisorControlIdentity };
+      const bundledAction = action.kind === "update" || action.kind === "reinstall";
+      const drain = await awaitRunnerUpdateDrain({
+        readStatus: localStatus,
+        drainable: bundledAction,
+        env: process.env,
+        isChildRunning: () => supervisorChildIsRunning(child),
+        failInFlightTask: (taskId, patch) => client.postProgress(taskId, { status: "failed", message: patch.message, result: patch.result, ...patch.runnerId ? { runner_id: patch.runnerId } : {}, ...patch.runnerInstanceId ? { runner_instance_id: patch.runnerInstanceId } : {} }),
+        log: (message) => console.warn(`[vo-runner supervisor] ${message}`)
+      });
+      if (!drain.proceed) {
+        await client.completeRunnerControl(action.actionId, { ...controlIdentity, status: "failed", detail: drain.detail });
         handling = false;
         respawn();
         continue;
       }
       controlRecoveryFence.markBeforeStop(child);
       await stopChildExpectedly(child);
-      const bundledAction = action.kind === "update" || action.kind === "reinstall";
       const result = bundledAction ? stageAndActivateBundledUpdate({
         runtimeRoot,
         packageSpec: `@algosuite/vo-mcp@${action.desired_package_version}`,
@@ -3445,6 +3683,7 @@ async function main() {
         log: (message) => console.warn(`[vo-runner supervisor] ${message}`)
       });
       if (result.ok && result.handoff) {
+        if (drain.capped) console.warn(`[vo-runner supervisor] ${drain.detail}`);
         console.warn(`[vo-runner supervisor] activated ${result.active.version}; exiting for new-process attestation`);
         return;
       }
@@ -3456,9 +3695,7 @@ async function main() {
       const relaunchedHealthy = recoveryAuthorized ? await ensureHealthyChildAfterControl() : false;
       if (!relaunchedHealthy) result.ok = false;
       await client.completeRunnerControl(action.actionId, {
-        runnerId,
-        ...operatorId ? { operatorId } : {},
-        ...supervisorControlIdentity,
+        ...controlIdentity,
         status: result.ok ? "succeeded" : "failed",
         detail: result.ok ? result.detail ? `${result.detail}; runner ${packageVersion()} reconnected`.slice(0, 1e3) : `runner ${packageVersion()} reconnected` : `maintenance exited ${result.status}${result.detail ? `: ${result.detail}` : ""}${relaunchedHealthy ? "" : "; runner relaunch did not become healthy"}`
       });