triflux 10.42.0 → 10.44.0

package/hub/router.mjs

@@ -1,7 +1,15 @@
 // hub/router.mjs — 실시간 라우팅/수신함 상태 관리자
 // SQLite는 감사 로그만 담당하고, 실제 배달 상태는 메모리에서 관리한다.
 import { EventEmitter, once } from "node:events";
+import {
+  clampDurationMs,
+  DEFAULT_ASSIGN_TIMEOUT_MS,
+  DEFAULT_ASSIGN_TTL_MS,
+  DEFAULT_HANDOFF_TTL_MS,
+  resolveHardCeilingMs,
+} from "./lib/timeout-defaults.mjs";
 import { uuidv7 } from "./lib/uuidv7.mjs";
+import { normalizeRoleKey } from "./role-contract.mjs";
 
 const ASSIGN_PENDING_STATUSES = new Set(["queued", "running"]);
 const ROLE_TOPICS = new Set(["cto"]);
@@ -9,6 +17,258 @@ const ROLE_SOURCE_RANK = Object.freeze({
   explicit: 2,
   "topic-fallback": 1,
 });
+const TRANSPORT_LOCATOR_SCHEMA_VERSION = "tfx.transport-locator.v1";
+const TRANSPORT_KINDS = new Set(["claude-uds", "tmux"]);
+const TRANSPORT_CAPABILITIES = new Set([
+  "probe",
+  "wake",
+  "activate",
+  "interrupt",
+]);
+const HOST_ID_RE = /^hst_[A-Za-z0-9_-]+$/u;
+
+function registrationError(code, message = code) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function registrationString(value, code, { maxLength = 256 } = {}) {
+  if (typeof value !== "string" || !value.trim() || value.length > maxLength) {
+    throw registrationError(code);
+  }
+  return value.trim();
+}
+
+function registrationLogicalRef(value, code, { maxLength = 128 } = {}) {
+  const normalized = registrationString(value, code, { maxLength });
+  if (!/^[A-Za-z0-9._:-]+$/u.test(normalized)) {
+    throw registrationError(code);
+  }
+  return normalized;
+}
+
+function assertExactFields(value, allowed, code) {
+  if (
+    value === null ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.keys(value).some((field) => !allowed.has(field))
+  ) {
+    throw registrationError(code);
+  }
+}
+
+function normalizeTransportLocator(
+  value,
+  { cli, hostId, now, leaseExpiresMs },
+) {
+  assertExactFields(
+    value,
+    new Set([
+      "schema_version",
+      "transport_id",
+      "kind",
+      "host_id",
+      "capabilities",
+      "priority",
+      "expires_at_ms",
+      "locator",
+    ]),
+    "TRANSPORT_LOCATOR_INVALID",
+  );
+  if (value.schema_version !== TRANSPORT_LOCATOR_SCHEMA_VERSION) {
+    throw registrationError("TRANSPORT_LOCATOR_SCHEMA_UNSUPPORTED");
+  }
+  const transportId = registrationLogicalRef(
+    value.transport_id,
+    "TRANSPORT_ID_INVALID",
+    { maxLength: 128 },
+  );
+  if (!TRANSPORT_KINDS.has(value.kind)) {
+    throw registrationError("TRANSPORT_KIND_UNSUPPORTED");
+  }
+  if (cli === "codex" && value.kind !== "tmux") {
+    throw registrationError("CODEX_TRANSPORT_UNSUPPORTED");
+  }
+  const locatorHostId = registrationString(value.host_id, "HOST_ID_INVALID", {
+    maxLength: 128,
+  });
+  if (!HOST_ID_RE.test(locatorHostId) || (hostId && locatorHostId !== hostId)) {
+    throw registrationError("HOST_ID_INVALID");
+  }
+  if (!Array.isArray(value.capabilities)) {
+    throw registrationError("TRANSPORT_CAPABILITIES_INVALID");
+  }
+  const capabilities = uniqueStrings(value.capabilities);
+  if (
+    capabilities.length !== value.capabilities.length ||
+    capabilities.some((capability) => !TRANSPORT_CAPABILITIES.has(capability))
+  ) {
+    throw registrationError("TRANSPORT_CAPABILITIES_INVALID");
+  }
+  if (!Number.isSafeInteger(value.priority)) {
+    throw registrationError("TRANSPORT_PRIORITY_INVALID");
+  }
+  if (
+    !Number.isSafeInteger(value.expires_at_ms) ||
+    value.expires_at_ms <= now ||
+    value.expires_at_ms > leaseExpiresMs
+  ) {
+    throw registrationError("TRANSPORT_EXPIRY_INVALID");
+  }
+
+  let locator;
+  if (value.kind === "claude-uds") {
+    assertExactFields(
+      value.locator,
+      new Set(["session_id", "short", "bridge_id"]),
+      "TRANSPORT_LOCATOR_INVALID",
+    );
+    const sessionId = value.locator.session_id;
+    const short = value.locator.short;
+    if (!sessionId && !short) {
+      throw registrationError("CLAUDE_UDS_SESSION_REQUIRED");
+    }
+    locator = {
+      ...(sessionId
+        ? {
+            session_id: registrationLogicalRef(
+              sessionId,
+              "CLAUDE_UDS_SESSION_INVALID",
+            ),
+          }
+        : {}),
+      ...(short
+        ? {
+            short: registrationLogicalRef(short, "CLAUDE_UDS_SHORT_INVALID", {
+              maxLength: 128,
+            }),
+          }
+        : {}),
+      bridge_id: registrationLogicalRef(
+        value.locator.bridge_id,
+        "CLAUDE_UDS_BRIDGE_INVALID",
+        { maxLength: 128 },
+      ),
+    };
+  } else {
+    assertExactFields(
+      value.locator,
+      new Set(["session_name", "mux_server_id"]),
+      "TRANSPORT_LOCATOR_INVALID",
+    );
+    locator = {
+      session_name: registrationLogicalRef(
+        value.locator.session_name,
+        "TMUX_SESSION_INVALID",
+        { maxLength: 128 },
+      ),
+      mux_server_id: registrationLogicalRef(
+        value.locator.mux_server_id,
+        "TMUX_SERVER_INVALID",
+        { maxLength: 128 },
+      ),
+    };
+  }
+
+  return {
+    schema_version: TRANSPORT_LOCATOR_SCHEMA_VERSION,
+    transport_id: transportId,
+    kind: value.kind,
+    host_id: locatorHostId,
+    capabilities,
+    priority: value.priority,
+    expires_at_ms: value.expires_at_ms,
+    locator,
+  };
+}
+
+export function normalizeRegistrationIdentity(args = {}, now = Date.now()) {
+  const hasProjectId = Object.hasOwn(args, "project_id");
+  const hasSessionId = Object.hasOwn(args, "session_id");
+  const hasHostId = Object.hasOwn(args, "host_id");
+  const hasLocatorJson = Object.hasOwn(args, "transport_locators_json");
+  const hasLocators = Object.hasOwn(args, "transport_locators");
+  if (
+    !hasProjectId &&
+    !hasSessionId &&
+    !hasHostId &&
+    !hasLocatorJson &&
+    !hasLocators
+  ) {
+    return null;
+  }
+
+  const projectId = hasProjectId
+    ? normalizeRoleKey({ project_id: args.project_id, role_kind: "cto" })
+        .project_id
+    : null;
+  const sessionId = hasSessionId
+    ? registrationString(args.session_id, "SESSION_ID_INVALID")
+    : null;
+  const hostId = hasHostId
+    ? registrationString(args.host_id, "HOST_ID_INVALID", { maxLength: 128 })
+    : null;
+  if (hostId && !HOST_ID_RE.test(hostId)) {
+    throw registrationError("HOST_ID_INVALID");
+  }
+
+  let rawLocators = [];
+  if (hasLocatorJson) {
+    if (Array.isArray(args.transport_locators_json)) {
+      rawLocators = args.transport_locators_json;
+    } else if (typeof args.transport_locators_json === "string") {
+      try {
+        rawLocators = JSON.parse(args.transport_locators_json);
+      } catch {
+        throw registrationError("TRANSPORT_LOCATORS_JSON_INVALID");
+      }
+    } else {
+      throw registrationError("TRANSPORT_LOCATORS_JSON_INVALID");
+    }
+  } else if (hasLocators) {
+    rawLocators = args.transport_locators;
+  }
+  if (!Array.isArray(rawLocators)) {
+    throw registrationError("TRANSPORT_LOCATORS_INVALID");
+  }
+
+  const ttlMs = Number(args.heartbeat_ttl_ms ?? 30000);
+  if (rawLocators.length > 0 && (!Number.isFinite(ttlMs) || ttlMs <= 0)) {
+    throw registrationError("HEARTBEAT_TTL_INVALID");
+  }
+  const leaseExpiresMs = now + ttlMs;
+  const normalizedLocators = rawLocators
+    .map((locator) =>
+      normalizeTransportLocator(locator, {
+        cli: args.cli,
+        hostId,
+        now,
+        leaseExpiresMs,
+      }),
+    )
+    .sort(
+      (left, right) =>
+        right.priority - left.priority ||
+        left.transport_id.localeCompare(right.transport_id),
+    );
+  const resolvedHostId = hostId || normalizedLocators[0]?.host_id || null;
+  if (
+    resolvedHostId &&
+    normalizedLocators.some((locator) => locator.host_id !== resolvedHostId)
+  ) {
+    throw registrationError("HOST_ID_INVALID");
+  }
+
+  return {
+    project_id: projectId,
+    session_id: sessionId,
+    host_id: resolvedHostId,
+    transport_locators_json:
+      hasLocatorJson || hasLocators ? JSON.stringify(normalizedLocators) : null,
+  };
+}
 
 function uniqueStrings(values = []) {
   return Array.from(
@@ -49,17 +309,6 @@ function rolePriority(metadata = {}, roleName = "") {
   return 0;
 }
 
-function clampAssignDuration(
-  value,
-  fallback = 600000,
-  min = 1000,
-  max = 86400000,
-) {
-  const num = Number(value);
-  if (!Number.isFinite(num)) return fallback;
-  return Math.max(min, Math.min(Math.trunc(num), max));
-}
-
 function normalizeAssignTerminalStatus(input, metadata = {}) {
   const status = String(input || "")
     .trim()
@@ -127,6 +376,18 @@ export function createRouter(store) {
   const queuesByAgent = new Map();
   const liveMessages = new Map();
   const roleStates = new Map();
+  const updateRegistrationIdentity = store.db?.prepare
+    ? store.db.prepare(`
+        UPDATE agents SET
+          project_id=COALESCE(@project_id, project_id),
+          session_id=COALESCE(@session_id, session_id),
+          host_id=COALESCE(@host_id, host_id),
+          transport_locators_json=COALESCE(
+            @transport_locators_json,
+            transport_locators_json
+          )
+        WHERE agent_id=@agent_id`)
+    : null;
   const MAX_LATENCY_SAMPLES = 100;
   let latencyIdx = 0;
   const deliveryLatencies = new Array(MAX_LATENCY_SAMPLES).fill(0);
@@ -606,11 +867,31 @@ export function createRouter(store) {
       record.message.status = "delivered";
       store.updateMessageStatus(messageId, "delivered");
       recordLatency(delivery.delivered_at_ms - record.message.created_at_ms);
+      rearmAssignDeadlineOnDispatch(record.message, delivery.delivered_at_ms);
       return true;
     }
     return false;
   }
 
+  function rearmAssignDeadlineOnDispatch(message, deliveredAtMs) {
+    if (message?.payload?.kind !== "assign.job") return;
+    const jobId = message.payload.assign_job_id;
+    if (!jobId) return;
+    const job = store.getAssign(jobId);
+    if (
+      !job ||
+      !ASSIGN_PENDING_STATUSES.has(job.status) ||
+      job.dispatched_at_ms
+    )
+      return;
+    if (Number(message.payload.attempt) !== job.attempt) return;
+    store.updateAssignStatus(job.job_id, job.status, {
+      dispatched_at_ms: deliveredAtMs,
+      deadline_ms:
+        deliveredAtMs + clampDurationMs(job.timeout_ms, job.timeout_ms),
+    });
+  }
+
   function ackMessages(ids, agentId) {
     const now = Date.now();
     let count = 0;
@@ -706,7 +987,7 @@ export function createRouter(store) {
       to: job.supervisor_agent,
       topic: "assign.result",
       priority: Math.max(5, job.priority || 5),
-      ttl_ms: job.ttl_ms || job.timeout_ms || 600000,
+      ttl_ms: job.ttl_ms || job.timeout_ms || DEFAULT_ASSIGN_TTL_MS,
       payload: {
         event,
         ...buildAssignSnapshot(job),
@@ -725,7 +1006,7 @@ export function createRouter(store) {
       to: job.worker_agent,
       topic: job.topic || "assign.job",
       priority: job.priority || 5,
-      ttl_ms: job.ttl_ms || job.timeout_ms || 600000,
+      ttl_ms: job.ttl_ms || job.timeout_ms || DEFAULT_ASSIGN_TTL_MS,
       payload: {
         kind: "assign.job",
         reason,
@@ -797,6 +1078,24 @@ export function createRouter(store) {
     const timedOut = store.updateAssignStatus(job.job_id, "timed_out", {
       error: job.error ?? { message: "assign job timed out" },
     });
+    if (timedOut?.worker_agent) {
+      dispatchMessage({
+        type: "event",
+        from: "assign-router",
+        to: timedOut.worker_agent,
+        topic: "assign.cancel",
+        priority: 8,
+        ttl_ms: clampDurationMs(timedOut.ttl_ms, DEFAULT_ASSIGN_TTL_MS),
+        payload: {
+          kind: "assign.cancel",
+          assign_job_id: timedOut.job_id,
+          attempt: timedOut.attempt,
+          reason: "timed_out",
+        },
+        trace_id: timedOut.trace_id,
+        correlation_id: timedOut.correlation_id,
+      });
+    }
 
     if (timedOut.retry_count < timedOut.max_retries) {
       return scheduleAssignRetry(
@@ -821,10 +1120,17 @@ export function createRouter(store) {
     deliveryEmitter,
 
     registerAgent(args) {
+      const identity = normalizeRegistrationIdentity(args);
       const result = store.registerAgent(args);
       if (!registerPresenceIsEffective(result)) {
         return registerPresenceFailure(args.agent_id, result);
       }
+      if (identity && updateRegistrationIdentity) {
+        updateRegistrationIdentity.run({
+          agent_id: args.agent_id,
+          ...identity,
+        });
+      }
       upsertRuntimeTopics(args.agent_id, args.topics || [], { replace: true });
       refreshRoleCandidateForAgent(args.agent_id);
       for (const roleName of ROLE_TOPICS) {
@@ -1146,7 +1452,7 @@ export function createRouter(store) {
       acceptance_criteria,
       context_refs,
       priority = 5,
-      ttl_ms = 600000,
+      ttl_ms = DEFAULT_HANDOFF_TTL_MS,
       trace_id,
       correlation_id,
     }) {
@@ -1174,8 +1480,8 @@ export function createRouter(store) {
       task = "",
       payload = {},
       priority = 5,
-      ttl_ms = 600000,
-      timeout_ms = 600000,
+      ttl_ms = DEFAULT_ASSIGN_TTL_MS,
+      timeout_ms = DEFAULT_ASSIGN_TIMEOUT_MS,
       max_retries = 0,
       trace_id,
       correlation_id,
@@ -1232,16 +1538,6 @@ export function createRouter(store) {
           },
         };
       }
-      if (Number.isFinite(Number(attempt)) && Number(attempt) !== job.attempt) {
-        return {
-          ok: false,
-          error: {
-            code: "ASSIGN_ATTEMPT_MISMATCH",
-            message: `stale assign result for attempt ${attempt} (current ${job.attempt})`,
-          },
-        };
-      }
-
       const mergedMetadata = {
         ...(payload?.metadata || {}),
         ...(metadata || {}),
@@ -1255,11 +1551,37 @@ export function createRouter(store) {
         (Object.hasOwn(payload || {}, "result") ? payload.result : payload);
       const nextError = error ?? payload?.error ?? null;
 
+      if (Number.isFinite(Number(attempt)) && Number(attempt) !== job.attempt) {
+        const preserved = notifyAssignSupervisor(job, "late_result", {
+          stale_attempt: Number(attempt),
+          late_status: normalizedStatus,
+          late_result: nextResult,
+          late_error: nextError,
+          reported_by: worker_agent || job.worker_agent,
+        });
+        return {
+          ok: false,
+          error: {
+            code: "ASSIGN_ATTEMPT_MISMATCH",
+            message: `stale assign result for attempt ${attempt} (current ${job.attempt})`,
+            details: {
+              preserved: Boolean(preserved),
+              preserved_message_id: preserved?.id ?? null,
+            },
+          },
+        };
+      }
+
       if (normalizedStatus === "running") {
+        const nowMs = Date.now();
+        const ceilingAtMs =
+          (job.dispatched_at_ms || job.created_at_ms) + resolveHardCeilingMs();
         const running = store.updateAssignStatus(job.job_id, "running", {
-          started_at_ms: job.started_at_ms || Date.now(),
-          deadline_ms:
-            Date.now() + clampAssignDuration(job.timeout_ms, job.timeout_ms),
+          started_at_ms: job.started_at_ms || nowMs,
+          deadline_ms: Math.min(
+            nowMs + clampDurationMs(job.timeout_ms, job.timeout_ms),
+            ceilingAtMs,
+          ),
           result: nextResult,
           error: nextError,
         });
@@ -1328,12 +1650,44 @@ export function createRouter(store) {
     sweepExpired() {
       const now = Date.now();
       let expired = 0;
+      const deadLettered = [];
       for (const [messageId, record] of Array.from(liveMessages.entries())) {
         if (record.message.expires_at_ms > now) continue;
         store.moveToDeadLetter(messageId, "ttl_expired", null);
+        deadLettered.push(record.message);
         removeMessage(messageId);
         expired += 1;
       }
+      for (const message of deadLettered) {
+        if (
+          !["handoff", "request"].includes(message.type) ||
+          message.payload?.kind === "assign.job"
+        )
+          continue;
+        if (
+          !message.from_agent ||
+          String(message.from_agent).startsWith("topic:")
+        )
+          continue;
+        dispatchMessage({
+          type: "event",
+          from: "hub-sweeper",
+          to: message.from_agent,
+          topic: "handoff.dead_letter",
+          priority: 7,
+          ttl_ms: 300000,
+          payload: {
+            kind: "handoff.dead_letter",
+            message_id: message.id,
+            original_topic: message.topic,
+            original_to: message.to_agent,
+            reason: "ttl_expired",
+            task: message.payload?.task ?? null,
+          },
+          trace_id: message.trace_id,
+          correlation_id: message.correlation_id,
+        });
+      }
       return { messages: expired };
     },
 

package/hub/schema.sql

@@ -11,7 +11,11 @@ CREATE TABLE IF NOT EXISTS agents (
   last_seen_ms INTEGER NOT NULL,
   lease_expires_ms INTEGER NOT NULL,
   status TEXT NOT NULL CHECK (status IN ('online','stale','offline')),
-  metadata_json TEXT NOT NULL DEFAULT '{}'
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  project_id TEXT,
+  session_id TEXT,
+  host_id TEXT,
+  transport_locators_json TEXT NOT NULL DEFAULT '[]'
 );
 
 -- 메시지 테이블
@@ -28,7 +32,61 @@ CREATE TABLE IF NOT EXISTS messages (
   correlation_id TEXT NOT NULL,
   trace_id TEXT NOT NULL,
   payload_json TEXT NOT NULL DEFAULT '{}',
-  status TEXT NOT NULL CHECK (status IN ('queued','delivered','acked','expired','dead_letter'))
+  status TEXT NOT NULL CHECK (status IN ('queued','delivered','acked','expired','dead_letter')),
+  role_key_wire TEXT
+);
+
+-- 동적 역할 레지스트리 (schema v6)
+CREATE TABLE IF NOT EXISTS role_registry (
+  role_key_wire TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  role_kind TEXT NOT NULL CHECK (role_kind IN ('cto','lead')),
+  scope_id TEXT NOT NULL DEFAULT '',
+  state TEXT NOT NULL CHECK (
+    state IN (
+      'electable',
+      'elected-probing',
+      'active',
+      'unreachable',
+      'quarantined'
+    )
+  ),
+  holder_agent_id TEXT,
+  previous_holder_agent_id TEXT,
+  epoch INTEGER NOT NULL DEFAULT 0 CHECK (epoch >= 0),
+  activation_seq INTEGER NOT NULL DEFAULT 0 CHECK (activation_seq >= 0),
+  activation_id TEXT,
+  activation_deadline_ms INTEGER,
+  holder_lease_expires_ms INTEGER,
+  charter_version TEXT,
+  charter_acked_epoch INTEGER,
+  retry_count INTEGER NOT NULL DEFAULT 0,
+  next_probe_ms INTEGER,
+  blocked_reason TEXT,
+  last_transition_ms INTEGER NOT NULL,
+  last_reason TEXT NOT NULL,
+  version INTEGER NOT NULL DEFAULT 0,
+  CHECK (
+    (role_kind = 'cto' AND scope_id = '') OR
+    (role_kind = 'lead' AND scope_id <> '')
+  ),
+  UNIQUE(project_id, role_kind, scope_id)
+);
+
+CREATE TABLE IF NOT EXISTS role_candidates (
+  role_key_wire TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  source TEXT NOT NULL CHECK (source IN ('grant','standup','operator')),
+  priority INTEGER NOT NULL DEFAULT 0,
+  transport_locators_json TEXT NOT NULL DEFAULT '[]',
+  consecutive_probe_failures INTEGER NOT NULL DEFAULT 0,
+  excluded_until_ms INTEGER,
+  last_probe_ms INTEGER,
+  last_probe_code TEXT,
+  updated_at_ms INTEGER NOT NULL,
+  PRIMARY KEY(role_key_wire, agent_id),
+  FOREIGN KEY(role_key_wire)
+    REFERENCES role_registry(role_key_wire) ON DELETE CASCADE
 );
 
 -- 메시지 수신함 (배달 추적)
@@ -73,6 +131,7 @@ CREATE INDEX IF NOT EXISTS idx_messages_correlation ON messages(correlation_id);
 CREATE INDEX IF NOT EXISTS idx_messages_trace ON messages(trace_id);
 CREATE INDEX IF NOT EXISTS idx_messages_expires ON messages(expires_at_ms);
 CREATE INDEX IF NOT EXISTS idx_messages_priority ON messages(priority DESC, created_at_ms ASC);
+CREATE INDEX IF NOT EXISTS idx_messages_role_key ON messages(role_key_wire, status, expires_at_ms);
 CREATE INDEX IF NOT EXISTS idx_inbox_agent ON message_inbox(agent_id, delivered_at_ms);
 CREATE INDEX IF NOT EXISTS idx_inbox_message ON message_inbox(message_id);
 CREATE INDEX IF NOT EXISTS idx_human_requests_state ON human_requests(state);
@@ -103,6 +162,7 @@ CREATE TABLE IF NOT EXISTS assign_jobs (
   created_at_ms INTEGER NOT NULL,
   updated_at_ms INTEGER NOT NULL,
   started_at_ms INTEGER,
+  dispatched_at_ms INTEGER,
   completed_at_ms INTEGER,
   last_retry_at_ms INTEGER
 );