triflux 3.2.0-dev.8 → 3.3.0-dev.1

package/hub/hitl.mjs

@@ -1,12 +1,30 @@
 // hub/hitl.mjs — Human-in-the-Loop 매니저
 // 사용자 입력 요청/응답, 타임아웃 자동 처리
 
-/**
- * HITL 매니저 생성
- * @param {object} store — createStore() 반환 객체
- */
-export function createHitlManager(store) {
-  return {
+/**
+ * HITL 매니저 생성
+ * @param {object} store — createStore() 반환 객체
+ * @param {object} router — createRouter() 반환 객체
+ */
+export function createHitlManager(store, router = null) {
+  function forwardHumanResponse({ requesterAgent, requestId, action, content, submittedBy, correlationId, traceId, priority }) {
+    if (!router?.handlePublish) {
+      throw new Error('router.handlePublish is required for HITL forwarding');
+    }
+    return router.handlePublish({
+      from: 'hub:hitl',
+      to: requesterAgent,
+      topic: 'human.response',
+      priority,
+      ttl_ms: 300000,
+      payload: { request_id: requestId, action, content, submitted_by: submittedBy },
+      correlation_id: correlationId,
+      trace_id: traceId,
+      message_type: 'human_response',
+    });
+  }
+
+  return {
     /**
      * 사용자에게 입력 요청 생성
      * 터미널에 알림 출력 후 pending 상태로 저장
@@ -61,21 +79,19 @@ export function createHitlManager(store) {
 
       // 요청자에게 응답 메시지 전달
       let forwardedMessageId = null;
-      if (action === 'accept' || action === 'decline') {
-        const msg = store.enqueueMessage({
-          type: 'human_response',
-          from: 'hub:hitl',
-          to: hr.requester_agent,
-          topic: 'human.response',
-          priority: 7, // urgent — 사용자 블로킹 해소
-          ttl_ms: 300000,
-          payload: { request_id, action, content, submitted_by },
-          correlation_id: hr.correlation_id,
-          trace_id: hr.trace_id,
-        });
-        store.deliverToAgent(msg.id, hr.requester_agent);
-        forwardedMessageId = msg.id;
-      }
+      if (action === 'accept' || action === 'decline') {
+        const published = forwardHumanResponse({
+          requesterAgent: hr.requester_agent,
+          requestId: request_id,
+          action,
+          content,
+          submittedBy: submitted_by,
+          correlationId: hr.correlation_id,
+          traceId: hr.trace_id,
+          priority: 7,
+        });
+        forwardedMessageId = published.data?.message_id || null;
+      }
 
       return {
         ok: true,
@@ -98,18 +114,16 @@ export function createHitlManager(store) {
         for (const hr of expired) {
           store.updateHumanRequest(hr.request_id, 'timed_out', null);
           if (hr.default_action === 'timeout_continue') {
-            const msg = store.enqueueMessage({
-              type: 'human_response',
-              from: 'hub:hitl',
-              to: hr.requester_agent,
-              topic: 'human.response',
+            forwardHumanResponse({
+              requesterAgent: hr.requester_agent,
+              requestId: hr.request_id,
+              action: 'timeout_continue',
+              content: null,
+              submittedBy: 'system',
+              correlationId: hr.correlation_id,
+              traceId: hr.trace_id,
               priority: 5,
-              ttl_ms: 300000,
-              payload: { request_id: hr.request_id, action: 'timeout_continue', content: null },
-              correlation_id: hr.correlation_id,
-              trace_id: hr.trace_id,
             });
-            store.deliverToAgent(msg.id, hr.requester_agent);
           }
         }
         return expired.length;

package/hub/pipe.mjs

@@ -0,0 +1,457 @@
+// hub/pipe.mjs — Named Pipe/Unix socket 제어 채널
+// NDJSON 프로토콜로 에이전트 실시간 제어/이벤트 푸시를 처리한다.
+
+import net from 'node:net';
+import { existsSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const DEFAULT_HEARTBEAT_TTL_MS = 60000;
+
+/** 플랫폼별 pipe 경로 계산 */
+export function getPipePath(sessionId = process.pid) {
+  if (process.platform === 'win32') {
+    return `\\\\.\\pipe\\triflux-${sessionId}`;
+  }
+  return join('/tmp', `triflux-${sessionId}.sock`);
+}
+
+function safeJsonParse(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+function normalizeTopics(topics) {
+  if (!Array.isArray(topics)) return [];
+  return topics
+    .map((topic) => String(topic || '').trim())
+    .filter(Boolean);
+}
+
+/**
+ * Named Pipe 서버 생성
+ * @param {object} opts
+ * @param {object} opts.router
+ * @param {object} [opts.store]
+ * @param {string|number} [opts.sessionId]
+ * @param {number} [opts.heartbeatTtlMs]
+ */
+export function createPipeServer({
+  router,
+  store = null,
+  sessionId = process.pid,
+  heartbeatTtlMs = DEFAULT_HEARTBEAT_TTL_MS,
+} = {}) {
+  if (!router) {
+    throw new Error('router is required');
+  }
+
+  const pipePath = getPipePath(sessionId);
+  const clients = new Map();
+  let server = null;
+  let heartbeatTimer = null;
+
+  function sendFrame(client, frame) {
+    if (!client || client.closed || !client.socket.writable) return false;
+    try {
+      client.socket.write(`${JSON.stringify(frame)}\n`);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function sendResponse(client, requestId, result) {
+    return sendFrame(client, { type: 'response', request_id: requestId, ...result });
+  }
+
+  function closeClient(client) {
+    if (!client || client.closed) return;
+    client.closed = true;
+    clients.delete(client.id);
+    try { client.socket.destroy(); } catch {}
+  }
+
+  function touchClient(client) {
+    client.lastHeartbeatMs = Date.now();
+  }
+
+  function resolveAgentId(client, payload) {
+    const agentId = payload?.agent_id || client?.agentId;
+    if (!agentId) {
+      throw new Error('agent_id required');
+    }
+    return agentId;
+  }
+
+  function pushEvent(agentId, message) {
+    let delivered = false;
+    for (const client of clients.values()) {
+      if (client.agentId !== agentId) continue;
+      if (sendFrame(client, {
+        type: 'event',
+        event: 'message',
+        payload: { agent_id: agentId, message },
+      })) {
+        delivered = true;
+      }
+    }
+    return delivered;
+  }
+
+  function pushPendingMessages(agentId) {
+    if (!agentId) return 0;
+    const pending = router.getPendingMessages(agentId, { max_messages: 100 });
+    let pushed = 0;
+    for (const message of pending) {
+      if (router.markMessagePushed(agentId, message.id)) {
+        pushed += pushEvent(agentId, message) ? 1 : 0;
+      } else if (pushEvent(agentId, message)) {
+        pushed += 1;
+      }
+    }
+    return pushed;
+  }
+
+  async function processCommand(client, action, payload = {}) {
+    switch (action) {
+      case 'register': {
+        const result = router.registerAgent(payload);
+        if (client) {
+          client.agentId = payload.agent_id;
+          client.subscriptions = new Set(router.getSubscribedTopics(client.agentId));
+          touchClient(client);
+          pushPendingMessages(client.agentId);
+        }
+        return { ok: true, data: { ...result, pipe_path: pipePath } };
+      }
+
+      case 'subscribe': {
+        const agentId = resolveAgentId(client, payload);
+        const topics = normalizeTopics(payload.topics);
+        const result = router.subscribeAgent(agentId, topics, {
+          replace: Boolean(payload.replace),
+        });
+        if (client) {
+          client.agentId = agentId;
+          client.subscriptions = new Set(result.topics);
+          touchClient(client);
+        }
+        const replayed = pushPendingMessages(agentId);
+        return {
+          ok: true,
+          data: { ...result, replayed_messages: replayed },
+        };
+      }
+
+      case 'ack': {
+        const agentId = resolveAgentId(client, payload);
+        const acked = router.ackMessages(payload.message_ids || payload.ack_ids || [], agentId);
+        if (client) touchClient(client);
+        return { ok: true, data: { agent_id: agentId, acked_count: acked } };
+      }
+
+      case 'heartbeat': {
+        const agentId = resolveAgentId(client, payload);
+        const result = router.refreshAgentLease(agentId, payload.heartbeat_ttl_ms || heartbeatTtlMs);
+        if (client) touchClient(client);
+        return { ok: true, data: result };
+      }
+
+      case 'publish': {
+        const result = router.handlePublish(payload);
+        if (client) touchClient(client);
+        return result;
+      }
+
+      case 'handoff': {
+        const result = router.handleHandoff(payload);
+        if (client) touchClient(client);
+        return result;
+      }
+
+      case 'result': {
+        const result = router.handlePublish({
+          from: payload.agent_id,
+          to: `topic:${payload.topic || 'task.result'}`,
+          topic: payload.topic || 'task.result',
+          payload: payload.payload || {},
+          priority: 5,
+          ttl_ms: 3600000,
+          trace_id: payload.trace_id,
+          correlation_id: payload.correlation_id,
+        });
+        if (client) touchClient(client);
+        return result;
+      }
+
+      case 'control': {
+        const result = router.handlePublish({
+          from: payload.from_agent || 'lead',
+          to: payload.to_agent,
+          topic: 'lead.control',
+          payload: {
+            command: payload.command,
+            reason: payload.reason || '',
+            ...(payload.payload || {}),
+            issued_at: Date.now(),
+          },
+          priority: 8,
+          ttl_ms: Math.max(1000, Math.min(Number(payload.ttl_ms) || 3600000, 86400000)),
+          trace_id: payload.trace_id,
+          correlation_id: payload.correlation_id,
+        });
+        if (client) touchClient(client);
+        return result;
+      }
+
+      case 'deregister': {
+        const agentId = resolveAgentId(client, payload);
+        router.updateAgentStatus(agentId, 'offline');
+        if (client) touchClient(client);
+        return {
+          ok: true,
+          data: { agent_id: agentId, status: 'offline' },
+        };
+      }
+
+      default:
+        return {
+          ok: false,
+          error: { code: 'UNKNOWN_PIPE_COMMAND', message: `지원하지 않는 command: ${action}` },
+        };
+    }
+  }
+
+  function buildReplayMessages(agentId, payload = {}) {
+    const maxMessages = Math.max(1, Math.min(Number(payload.max_messages) || 20, 100));
+    const pending = router.getPendingMessages(agentId, {
+      max_messages: maxMessages,
+      include_topics: payload.topics,
+    });
+    if (!store?.getAuditMessagesForAgent) {
+      return pending.slice(0, maxMessages);
+    }
+
+    const audit = store.getAuditMessagesForAgent(agentId, {
+      max_messages: maxMessages,
+      include_topics: payload.topics,
+    });
+    const byId = new Map();
+    for (const message of [...pending, ...audit]) {
+      if (!message?.id || byId.has(message.id)) continue;
+      byId.set(message.id, message);
+    }
+    return Array.from(byId.values())
+      .sort((left, right) => right.created_at_ms - left.created_at_ms)
+      .slice(0, maxMessages);
+  }
+
+  async function processQuery(client, action, payload = {}) {
+    switch (action) {
+      case 'drain': {
+        const agentId = resolveAgentId(client, payload);
+        const messages = router.drainAgent(agentId, {
+          max_messages: payload.max_messages,
+          include_topics: payload.topics,
+          auto_ack: payload.auto_ack,
+        });
+        if (client) touchClient(client);
+        return {
+          ok: true,
+          data: { messages, count: messages.length, server_time_ms: Date.now() },
+        };
+      }
+
+      case 'context': {
+        const agentId = resolveAgentId(client, payload);
+        const messages = buildReplayMessages(agentId, payload);
+        if (client) touchClient(client);
+        return {
+          ok: true,
+          data: { messages, count: messages.length, server_time_ms: Date.now() },
+        };
+      }
+
+      case 'status': {
+        const scope = payload.scope || 'hub';
+        if (client) touchClient(client);
+        return router.getStatus(scope, payload);
+      }
+
+      default:
+        return {
+          ok: false,
+          error: { code: 'UNKNOWN_PIPE_QUERY', message: `지원하지 않는 query: ${action}` },
+        };
+    }
+  }
+
+  function onMessage(agentId, message) {
+    if (!agentId || !message) return;
+    if (router.markMessagePushed(agentId, message.id)) {
+      pushEvent(agentId, message);
+      return;
+    }
+    pushEvent(agentId, message);
+  }
+
+  async function handleFrame(client, frame) {
+    if (!frame || typeof frame !== 'object') {
+      return sendResponse(client, null, {
+        ok: false,
+        error: { code: 'INVALID_FRAME', message: 'JSON object frame required' },
+      });
+    }
+
+    if (!frame.type) {
+      return sendResponse(client, frame.request_id || null, {
+        ok: false,
+        error: { code: 'INVALID_FRAME', message: 'type required' },
+      });
+    }
+
+    touchClient(client);
+
+    try {
+      if (frame.type === 'command') {
+        const action = frame.payload?.action || frame.payload?.command;
+        const result = await processCommand(client, action, frame.payload || {});
+        return sendResponse(client, frame.payload?.request_id || frame.request_id || null, result);
+      }
+      if (frame.type === 'query') {
+        const action = frame.payload?.action || frame.payload?.query;
+        const result = await processQuery(client, action, frame.payload || {});
+        return sendResponse(client, frame.payload?.request_id || frame.request_id || null, result);
+      }
+      return sendResponse(client, frame.request_id || null, {
+        ok: false,
+        error: { code: 'INVALID_FRAME_TYPE', message: `지원하지 않는 type: ${frame.type}` },
+      });
+    } catch (error) {
+      return sendResponse(client, frame.request_id || null, {
+        ok: false,
+        error: { code: 'PIPE_REQUEST_FAILED', message: error.message },
+      });
+    }
+  }
+
+  function attachSocket(socket) {
+    const client = {
+      id: randomUUID(),
+      socket,
+      buffer: '',
+      agentId: null,
+      subscriptions: new Set(),
+      lastHeartbeatMs: Date.now(),
+      closed: false,
+    };
+    clients.set(client.id, client);
+
+    socket.setEncoding('utf8');
+    socket.on('data', async (chunk) => {
+      client.buffer += chunk;
+      let newlineIndex = client.buffer.indexOf('\n');
+      while (newlineIndex >= 0) {
+        const line = client.buffer.slice(0, newlineIndex).trim();
+        client.buffer = client.buffer.slice(newlineIndex + 1);
+        if (line) {
+          const frame = safeJsonParse(line);
+          await handleFrame(client, frame);
+        }
+        newlineIndex = client.buffer.indexOf('\n');
+      }
+    });
+
+    socket.on('close', () => closeClient(client));
+    socket.on('error', () => closeClient(client));
+  }
+
+  function startHeartbeatMonitor() {
+    heartbeatTimer = setInterval(() => {
+      const now = Date.now();
+      for (const client of clients.values()) {
+        if (now - client.lastHeartbeatMs <= heartbeatTtlMs) continue;
+        sendFrame(client, {
+          type: 'event',
+          event: 'disconnect',
+          payload: { reason: 'heartbeat_timeout' },
+        });
+        closeClient(client);
+      }
+    }, Math.max(1000, Math.floor(heartbeatTtlMs / 2)));
+    heartbeatTimer.unref();
+  }
+
+  return {
+    path: pipePath,
+
+    async start() {
+      if (server) return { path: pipePath };
+
+      if (process.platform !== 'win32' && existsSync(pipePath)) {
+        try { unlinkSync(pipePath); } catch {}
+      }
+
+      server = net.createServer(attachSocket);
+      router.deliveryEmitter.on('message', onMessage);
+
+      await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(pipePath, () => {
+          server.off('error', reject);
+          resolve();
+        });
+      });
+
+      startHeartbeatMonitor();
+      return { path: pipePath };
+    },
+
+    async stop() {
+      if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+      }
+
+      router.deliveryEmitter.off('message', onMessage);
+
+      for (const client of clients.values()) {
+        closeClient(client);
+      }
+
+      if (server) {
+        const current = server;
+        server = null;
+        await new Promise((resolve) => current.close(resolve));
+      }
+
+      if (process.platform !== 'win32' && existsSync(pipePath)) {
+        try { unlinkSync(pipePath); } catch {}
+      }
+    },
+
+    getStatus() {
+      return {
+        path: pipePath,
+        protocol: 'ndjson',
+        clients: clients.size,
+        pending_messages: Array.from(clients.values()).reduce((sum, client) => {
+          if (!client.agentId) return sum;
+          return sum + router.getPendingMessages(client.agentId, { max_messages: 1000 }).length;
+        }, 0),
+      };
+    },
+
+    async executeCommand(action, payload) {
+      return await processCommand(null, action, payload);
+    },
+
+    async executeQuery(action, payload) {
+      return await processQuery(null, action, payload);
+    },
+  };
+}

package/hub/pipeline/index.mjs

@@ -0,0 +1,121 @@
+// hub/pipeline/index.mjs — 파이프라인 매니저
+//
+// 상태(state.mjs) + 전이(transitions.mjs) 통합 인터페이스
+
+import { canTransition, transitionPhase, ralphRestart, TERMINAL } from './transitions.mjs';
+import {
+  ensurePipelineTable,
+  initPipelineState,
+  readPipelineState,
+  updatePipelineState,
+  removePipelineState,
+} from './state.mjs';
+
+/**
+ * 파이프라인 매니저 생성
+ * @param {object} db - better-sqlite3 인스턴스 (store.db)
+ * @param {string} teamName
+ * @param {object} opts - { fix_max?, ralph_max? }
+ * @returns {object} 파이프라인 API
+ */
+export function createPipeline(db, teamName, opts = {}) {
+  ensurePipelineTable(db);
+
+  // 기존 상태가 있으면 로드, 없으면 초기화
+  let state = readPipelineState(db, teamName);
+  if (!state) {
+    state = initPipelineState(db, teamName, opts);
+  }
+
+  return {
+    /**
+     * 현재 상태 조회
+     */
+    getState() {
+      state = readPipelineState(db, teamName) || state;
+      return { ...state };
+    },
+
+    /**
+     * 다음 단계로 전이 가능 여부
+     * @param {string} phase
+     */
+    canAdvance(phase) {
+      const current = readPipelineState(db, teamName);
+      return current ? canTransition(current.phase, phase) : false;
+    },
+
+    /**
+     * 다음 단계로 전이
+     * @param {string} nextPhase
+     * @returns {{ ok: boolean, state?: object, error?: string }}
+     */
+    advance(nextPhase) {
+      const current = readPipelineState(db, teamName);
+      if (!current) {
+        return { ok: false, error: `파이프라인 없음: ${teamName}` };
+      }
+
+      const result = transitionPhase(current, nextPhase);
+      if (!result.ok) return result;
+
+      state = updatePipelineState(db, teamName, result.state);
+      return { ok: true, state: { ...state } };
+    },
+
+    /**
+     * ralph loop 재시작 (plan부터 다시)
+     * @returns {{ ok: boolean, state?: object, error?: string }}
+     */
+    restart() {
+      const current = readPipelineState(db, teamName);
+      if (!current) {
+        return { ok: false, error: `파이프라인 없음: ${teamName}` };
+      }
+
+      const result = ralphRestart(current);
+      if (!result.ok) return result;
+
+      state = updatePipelineState(db, teamName, result.state);
+      return { ok: true, state: { ...state } };
+    },
+
+    /**
+     * artifact 저장 (plan_path, prd_path, verify_report 등)
+     * @param {string} key
+     * @param {*} value
+     */
+    setArtifact(key, value) {
+      const current = readPipelineState(db, teamName);
+      if (!current) return;
+      const artifacts = { ...(current.artifacts || {}), [key]: value };
+      state = updatePipelineState(db, teamName, { artifacts });
+    },
+
+    /**
+     * 터미널 상태 여부
+     */
+    isTerminal() {
+      const current = readPipelineState(db, teamName);
+      return current ? TERMINAL.has(current.phase) : true;
+    },
+
+    /**
+     * 파이프라인 초기화 (리셋)
+     */
+    reset() {
+      state = initPipelineState(db, teamName, opts);
+      return { ...state };
+    },
+
+    /**
+     * 파이프라인 삭제
+     */
+    remove() {
+      return removePipelineState(db, teamName);
+    },
+  };
+}
+
+export { ensurePipelineTable } from './state.mjs';
+export { PHASES, TERMINAL, ALLOWED, canTransition } from './transitions.mjs';