@triflux/remote 10.1.0 → 10.26.0

package/hub/team/schemas/worker-completion.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "WorkerCompletion",
+  "description": "Self-reported worker completion payload emitted by a swarm shard worker.",
+  "type": "object",
+  "required": ["status"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["ok", "skipped", "failed"]
+    },
+    "shard": { "type": "string" },
+    "reason": { "type": "string" },
+    "commits_made": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["sha"],
+        "properties": {
+          "sha": { "type": "string", "minLength": 7 },
+          "message": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true,
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "ok" } } },
+      "then": {
+        "required": ["commits_made"],
+        "properties": {
+          "commits_made": { "minItems": 1 }
+        }
+      }
+    }
+  ]
+}

package/hub/team/sentinel-capture.mjs

@@ -0,0 +1,127 @@
+// hub/team/sentinel-capture.mjs — stdout sentinel-framed payload capture (#125)
+//
+// Workers emit completion payloads delimited by `<<<TFX_COMPLETION_BEGIN>>>`
+// and `<<<TFX_COMPLETION_END>>>` (see swarm-hypervisor.mjs buildWorkerPrompt
+// appendix). conductor.mjs feeds every stdout chunk through `push()`. After the
+// child exits, `snapshot()` returns the captured slice (BEGIN..END inclusive)
+// for `extractCompletionPayload`.
+//
+// Why this lives outside the 16 KiB stdoutTail buffer:
+//   payloads with large `commits_made` arrays can exceed 16 KiB and a sliding
+//   tail would head-truncate the BEGIN marker, leading to silent fallback to
+//   brace-scan and an incorrect inner-object extraction (#115 Codex Finding 2).
+//
+// Pure module — no I/O, no timers — so it can be unit-tested directly.
+
+export const SENTINEL_BEGIN = "<<<TFX_COMPLETION_BEGIN>>>";
+export const SENTINEL_END = "<<<TFX_COMPLETION_END>>>";
+
+const DEFAULT_MAX_BYTES = 1 << 20; // 1 MiB safety cap on captured region
+
+// Per the worker prompt appendix, both markers must appear alone on their own
+// line. Substring matches inside log lines / debug echoes must NOT trigger
+// capture or terminate it. We treat `\n`, `\r`, and string boundaries (start
+// or end of buffer) as line edges so Windows `\r\n` works without special-casing.
+function isLineEdgeChar(ch) {
+  return ch === "\n" || ch === "\r";
+}
+
+function findStandaloneMarker(text, marker, fromIdx = 0) {
+  let from = fromIdx;
+  while (from <= text.length - marker.length) {
+    const idx = text.indexOf(marker, from);
+    if (idx === -1) return -1;
+    const before = idx === 0 || isLineEdgeChar(text[idx - 1]);
+    const afterIdx = idx + marker.length;
+    const after = afterIdx === text.length || isLineEdgeChar(text[afterIdx]);
+    if (before && after) return idx;
+    from = idx + 1;
+  }
+  return -1;
+}
+
+/**
+ * Streaming sentinel capture state machine.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.maxBytes=1048576] safety cap on the captured region.
+ *   If the capture grows past this and head-truncation removes the BEGIN
+ *   marker, `isOverflow()` becomes true so the conductor can deterministically
+ *   reject instead of falling back to brace-scan on a runaway payload
+ *   (Codex R1 MEDIUM finding).
+ * @returns {{push: (text: string) => void, snapshot: () => string,
+ *            isActive: () => boolean, isComplete: () => boolean,
+ *            isOverflow: () => boolean}}
+ */
+export function createSentinelCapture({ maxBytes = DEFAULT_MAX_BYTES } = {}) {
+  let capturing = false;
+  let capture = "";
+  let overlap = "";
+  let done = false;
+  let overflowed = false;
+
+  // Boundary overlap covers the marker length plus one extra byte so we can
+  // verify the line-edge character that precedes BEGIN across chunk seams.
+  const overlapWindow = SENTINEL_BEGIN.length;
+
+  function maybeFlagOverflow() {
+    if (findStandaloneMarker(capture, SENTINEL_BEGIN) === -1) {
+      overflowed = true;
+      done = true;
+      return true;
+    }
+    return false;
+  }
+
+  function push(text) {
+    if (done || typeof text !== "string" || text.length === 0) return;
+
+    if (!capturing) {
+      const search = overlap + text;
+      const idx = findStandaloneMarker(search, SENTINEL_BEGIN);
+      if (idx !== -1) {
+        capturing = true;
+        capture = search.slice(idx);
+        overlap = "";
+        if (capture.length > maxBytes) {
+          capture = capture.slice(-maxBytes);
+          if (maybeFlagOverflow()) return;
+        }
+      } else {
+        overlap = search.slice(-overlapWindow);
+        return;
+      }
+    } else {
+      capture += text;
+      if (capture.length > maxBytes) {
+        capture = capture.slice(-maxBytes);
+        if (maybeFlagOverflow()) return;
+      }
+    }
+
+    // Stop capturing once the standalone-line END marker is seen. Trim to the
+    // first BEGIN..END pair so a worker that re-emitted (retry, debug log)
+    // doesn't bloat the snapshot.
+    const endIdx = findStandaloneMarker(capture, SENTINEL_END);
+    if (endIdx !== -1) {
+      done = true;
+      capture = capture.slice(0, endIdx + SENTINEL_END.length);
+    }
+  }
+
+  return {
+    push,
+    snapshot() {
+      return capture;
+    },
+    isActive() {
+      return capturing && !done;
+    },
+    isComplete() {
+      return done && !overflowed;
+    },
+    isOverflow() {
+      return overflowed;
+    },
+  };
+}

package/hub/team/session-sync.mjs

@@ -1,13 +1,19 @@
+import { readState } from "@triflux/core/hub/state.mjs";
+
 const DEFAULT_TIMEOUT_MS = 2500;
+const DEFAULT_HEADLESS_POLL_MS = 1000;
 
 function resolveFetch(fetchImpl) {
   if (typeof fetchImpl === "function") return fetchImpl;
-  if (typeof globalThis.fetch === "function") return globalThis.fetch.bind(globalThis);
+  if (typeof globalThis.fetch === "function")
+    return globalThis.fetch.bind(globalThis);
   return null;
 }
 
 function normalizeHubBaseUrl(hubUrl) {
-  return String(hubUrl || "").replace(/\/+$/, "").replace(/\/mcp$/, "");
+  return String(hubUrl || "")
+    .replace(/\/+$/, "")
+    .replace(/\/mcp$/, "");
 }
 
 function safeAbortSignal(timeoutMs) {
@@ -15,6 +21,55 @@ function safeAbortSignal(timeoutMs) {
   return AbortSignal.timeout(timeoutMs);
 }
 
+function isPidAlive(pid) {
+  const resolvedPid = Number(pid);
+  if (!Number.isFinite(resolvedPid) || resolvedPid <= 0) return false;
+  try {
+    process.kill(resolvedPid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveHeadlessHubUrl(hubUrl) {
+  const normalized = normalizeHubBaseUrl(hubUrl);
+  if (normalized) return normalized;
+
+  const stateUrl = normalizeHubBaseUrl(readState()?.url);
+  if (stateUrl) return stateUrl;
+
+  const envHubUrl = normalizeHubBaseUrl(process.env.TFX_HUB_URL);
+  if (envHubUrl) return envHubUrl;
+
+  const envPort = Number(process.env.TFX_HUB_PORT || "27888");
+  const port = Number.isFinite(envPort) && envPort > 0 ? envPort : 27888;
+  return `http://127.0.0.1:${port}`;
+}
+
+function hasLiveHubState() {
+  const state = readState();
+  return !!normalizeHubBaseUrl(state?.url) && isPidAlive(state?.pid);
+}
+
+function toHeadlessSessionAgentId(sessionName) {
+  const normalizedSessionName = String(sessionName || "").trim();
+  return normalizedSessionName ? `session:${normalizedSessionName}` : "";
+}
+
+async function dispatchHeadlessCommand(command, callbacks) {
+  const callbackMap = {
+    pause: callbacks.onPause,
+    resume: callbacks.onResume,
+    abort: callbacks.onAbort,
+    reassign: callbacks.onReassign,
+  };
+  const handler = callbackMap[command?.command];
+  if (typeof handler === "function") {
+    await handler(command);
+  }
+}
+
 async function safeJson(res) {
   try {
     return await res.json();
@@ -24,8 +79,13 @@ async function safeJson(res) {
 }
 
 function normalizeLeadCommandMessage(message) {
-  const payload = message?.payload && typeof message.payload === "object" ? message.payload : {};
-  const command = String(payload.command || "").trim().toLowerCase();
+  const payload =
+    message?.payload && typeof message.payload === "object"
+      ? message.payload
+      : {};
+  const command = String(payload.command || "")
+    .trim()
+    .toLowerCase();
   if (!command) return null;
   return {
     messageId: message.id || null,
@@ -79,7 +139,9 @@ export async function subscribeToLeadCommands({
     });
 
     const body = await safeJson(res);
-    const messages = Array.isArray(body?.data?.messages) ? body.data.messages : [];
+    const messages = Array.isArray(body?.data?.messages)
+      ? body.data.messages
+      : [];
     const commands = messages
       .filter((message) => message?.topic === "lead.control")
       .map(normalizeLeadCommandMessage)
@@ -108,6 +170,90 @@ export async function subscribeToLeadCommands({
   }
 }
 
+export function createHeadlessControlSubscriber(
+  sessionName,
+  {
+    onPause,
+    onResume,
+    onAbort,
+    onReassign,
+    hubUrl,
+    pollIntervalMs = DEFAULT_HEADLESS_POLL_MS,
+    maxMessages = 10,
+    autoAck = true,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    fetchImpl,
+  } = {},
+) {
+  const sessionAgentId = toHeadlessSessionAgentId(sessionName);
+  if (!sessionAgentId) {
+    return { stop() {} };
+  }
+
+  const explicitHubUrl =
+    normalizeHubBaseUrl(hubUrl) || normalizeHubBaseUrl(process.env.TFX_HUB_URL);
+  if (!explicitHubUrl && !hasLiveHubState()) {
+    return { stop() {} };
+  }
+
+  const resolvedHubUrl = explicitHubUrl || resolveHeadlessHubUrl(hubUrl);
+  const callbacks = { onPause, onResume, onAbort, onReassign };
+  const intervalMs = Math.max(
+    50,
+    Number(pollIntervalMs) || DEFAULT_HEADLESS_POLL_MS,
+  );
+
+  let stopped = false;
+  let timer = null;
+  let pending = false;
+
+  const stop = () => {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    timer = null;
+  };
+
+  const scheduleNext = () => {
+    if (stopped) return;
+    timer = setTimeout(tick, intervalMs);
+    if (typeof timer?.unref === "function") timer.unref();
+  };
+
+  const tick = async () => {
+    if (stopped || pending) {
+      scheduleNext();
+      return;
+    }
+
+    pending = true;
+    try {
+      const result = await subscribeToLeadCommands({
+        hubUrl: resolvedHubUrl,
+        agentId: sessionAgentId,
+        maxMessages,
+        autoAck,
+        timeoutMs,
+        fetchImpl,
+        onCommand: async (command) => {
+          await dispatchHeadlessCommand(command, callbacks);
+        },
+      });
+
+      if (!result?.ok && result?.error === "LEAD_COMMAND_SUBSCRIBE_FAILED") {
+        stop();
+        return;
+      }
+    } finally {
+      pending = false;
+      scheduleNext();
+    }
+  };
+
+  void tick();
+
+  return { stop };
+}
+
 export async function getTeamStatus({
   hubUrl,
   scope = "hub",
@@ -127,7 +273,8 @@ export async function getTeamStatus({
     return { ok: false, error: "HUB_URL_REQUIRED" };
   }
 
-  const normalizedMethod = String(method || "GET").toUpperCase() === "POST" ? "POST" : "GET";
+  const normalizedMethod =
+    String(method || "GET").toUpperCase() === "POST" ? "POST" : "GET";
   const statusScope = String(scope || "hub").trim() || "hub";
 
   let endpoint = `${hubBase}/bridge/status`;