loadtoagent 1.1.0 → 1.3.1

package/src/sessionIntelligence.js

@@ -0,0 +1,247 @@
+'use strict';
+
+const LIVE_STATUSES = new Set(['starting', 'running']);
+const COMPLETE_STATUSES = new Set(['completed', 'cancelled', 'failed']);
+const FAILURE_PATTERN = /(?:error|failed|failure|fatal|exception|오류|실패)/i;
+const PERMISSION_PATTERN = /(?:permission|approve|approval|권한|승인)/i;
+const DECISION_PATTERN = /(?:choose|select|decision|선택|결정|골라)/i;
+const INPUT_PATTERN = /(?:input|reply|answer|confirm|provide|입력|답변|확인|알려|제공)/i;
+const TEST_PATTERN = /(?:test|spec|검증|테스트)/i;
+
+function text(value, limit = 1200) {
+  const output = String(value == null ? '' : value).replace(/\s+/g, ' ').trim();
+  return output.length > limit ? `${output.slice(0, limit).trimEnd()}…` : output;
+}
+
+function timestamp(value) {
+  const parsed = Date.parse(value || 0);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function latestActivity(session) {
+  const values = [session.updatedAt, session.startedAt];
+  for (const row of session.messages || []) values.push(row && row.timestamp);
+  for (const row of session.lifecycle || []) values.push(row && (row.completedAt || row.timestamp));
+  const millis = Math.max(0, ...values.map(timestamp));
+  return millis ? new Date(millis).toISOString() : null;
+}
+
+function latestMeaningfulText(session) {
+  const messages = [...(session.messages || [])].reverse();
+  const preferred = messages.find(row => row && row.role === 'assistant' && text(row.text));
+  const fallback = messages.find(row => row && text(row.text));
+  return text((preferred || fallback || {}).text || session.statusDetail || session.result || '', 360);
+}
+
+function controlCapabilities(session) {
+  const live = LIVE_STATUSES.has(session.status);
+  const managed = Boolean(session.runId);
+  const resumable = Boolean(session.externalId && ['claude', 'codex', 'gemini'].includes(session.provider));
+  const directlyControllable = (session.runtimePresence || []).some(item => item && (item.terminalId || item.paneId || item.nativeId));
+  const canSend = directlyControllable || resumable;
+  return {
+    managed,
+    respond: (session.status === 'waiting' || live) && canSend,
+    approve: session.status === 'waiting' && canSend,
+    deny: session.status === 'waiting' && canSend,
+    sendInstruction: canSend,
+    stop: managed && (live || session.status === 'paused'),
+    pause: managed && session.status === 'running',
+    resume: (managed && session.status === 'paused') || (!live && resumable),
+    retry: managed && ['failed', 'cancelled'].includes(session.status),
+    reassign: Boolean(session.cwd && (session.title || session.sharedGoal || latestMeaningfulText(session))),
+    openOrigin: ['claude-desktop', 'codex-desktop'].includes(session.clientKind),
+  };
+}
+
+function evidenceFor(session) {
+  const statusObserved = Boolean(session.statusObserved || session.runId || session.runtimePresence?.length);
+  const delegation = session.delegation || {};
+  const hierarchyObserved = !session.parentId
+    || Boolean(delegation.assignmentObserved && delegation.assignmentSource !== 'unavailable')
+    || session.source === 'collaboration-history';
+  const completionObserved = Boolean(session.completionObserved || (session.runId && COMPLETE_STATUSES.has(session.status)));
+  const sources = [session.sourceLabel, statusObserved ? 'runtime-event' : 'activity-inference'];
+  if (session.parentId) sources.push(hierarchyObserved ? 'delegation-event' : 'hierarchy-inference');
+  if (completionObserved) sources.push('completion-event');
+  return {
+    confidence: statusObserved && hierarchyObserved ? 'high' : statusObserved || hierarchyObserved ? 'medium' : 'low',
+    status: statusObserved ? 'observed' : 'inferred',
+    hierarchy: hierarchyObserved ? 'observed' : 'inferred',
+    completion: completionObserved ? 'observed' : 'unverified',
+    sources: [...new Set(sources.filter(Boolean).map(value => text(value, 80)))],
+  };
+}
+
+function progressFor(session, attention) {
+  const lifecycle = (session.lifecycle || []).filter(Boolean);
+  const checkpoints = lifecycle.slice(-12).map((row, index) => ({
+    id: String(row.id || `${session.id}:checkpoint:${index}`),
+    label: text(row.label || row.type || 'Activity', 140),
+    detail: text(row.detail || '', 240),
+    status: ['failed', 'error'].includes(row.status) ? 'failed'
+      : ['running', 'pending', 'started'].includes(row.status) ? 'running'
+        : 'completed',
+    timestamp: row.completedAt || row.timestamp || session.updatedAt || null,
+  }));
+  const completedSteps = checkpoints.filter(row => row.status === 'completed').length;
+  const failedSteps = checkpoints.filter(row => row.status === 'failed').length;
+  const running = [...checkpoints].reverse().find(row => row.status === 'running');
+  const last = checkpoints.at(-1);
+  const totalSteps = checkpoints.length;
+  let percent = totalSteps ? Math.round(completedSteps / totalSteps * 100) : 0;
+  if (session.status === 'completed') percent = 100;
+  else if (LIVE_STATUSES.has(session.status) && percent >= 100) percent = 95;
+  const stage = session.status === 'completed' ? 'completed'
+    : session.status === 'failed' ? 'failed'
+      : session.status === 'waiting' ? 'waiting'
+        : session.status === 'paused' ? 'paused'
+          : LIVE_STATUSES.has(session.status) ? 'executing' : 'idle';
+  return {
+    stage,
+    percent,
+    completedSteps,
+    failedSteps,
+    totalSteps,
+    currentStep: text((running || last || {}).label || session.statusDetail || '', 180),
+    blocker: attention.required ? attention.summary : '',
+    lastActivityAt: latestActivity(session),
+    source: totalSteps ? 'lifecycle-events' : 'session-status',
+    checkpoints,
+  };
+}
+
+function extractArtifacts(session) {
+  const body = [
+    session.result,
+    ...(session.messages || []).map(row => row && row.text),
+    ...(session.lifecycle || []).map(row => row && `${row.label || ''} ${row.detail || ''}`),
+  ].filter(Boolean).join('\n');
+  const artifacts = [];
+  const seen = new Set();
+  const add = (kind, value, verified = false) => {
+    const clean = text(value, 260).replace(/[),.;:]+$/, '');
+    const key = `${kind}:${clean.toLowerCase()}`;
+    if (!clean || seen.has(key) || artifacts.length >= 24) return;
+    seen.add(key);
+    artifacts.push({ kind, value: clean, verified });
+  };
+  const filePattern = /(?:[A-Za-z]:\\|\/)?(?:[\w.@-]+[\\/])+[\w.@()+-]+\.[A-Za-z0-9]{1,12}/g;
+  for (const match of body.match(filePattern) || []) add(TEST_PATTERN.test(match) ? 'test' : 'file', match, false);
+  if (/(?:commit|커밋)/i.test(body)) {
+    for (const match of body.match(/\b[0-9a-f]{7,40}\b/gi) || []) add('commit', match, true);
+  }
+  return artifacts;
+}
+
+function outcomeFor(session, evidence) {
+  const artifacts = extractArtifacts(session);
+  const checks = (session.lifecycle || [])
+    .filter(row => row && TEST_PATTERN.test(`${row.label || ''} ${row.detail || ''}`))
+    .slice(-12)
+    .map(row => ({
+      label: text(row.label || row.detail || 'Test', 180),
+      status: row.status === 'failed' ? 'failed' : row.status === 'running' ? 'running' : 'passed',
+      timestamp: row.completedAt || row.timestamp || null,
+    }));
+  const latestAssistant = [...(session.messages || [])].reverse().find(row => row && row.role === 'assistant' && text(row.text));
+  return {
+    status: session.status === 'completed' ? 'completed'
+      : session.status === 'failed' ? 'failed'
+        : session.status === 'cancelled' ? 'cancelled' : 'in-progress',
+    summary: text(session.result || (COMPLETE_STATUSES.has(session.status) && latestAssistant && latestAssistant.text) || session.statusDetail || '', 800),
+    verified: evidence.completion === 'observed',
+    verification: evidence.completion,
+    completedAt: session.completedAt || session.endedAt || null,
+    artifacts,
+    checks,
+  };
+}
+
+function attentionFor(session) {
+  const latest = latestMeaningfulText(session);
+  const combined = `${session.statusDetail || ''} ${latest}`;
+  let kind = 'none';
+  if (session.status === 'failed' || (session.status === 'waiting' && FAILURE_PATTERN.test(session.statusDetail || ''))) kind = 'error';
+  else if (session.status === 'paused') kind = 'paused';
+  else if (session.status === 'waiting' && PERMISSION_PATTERN.test(combined)) kind = 'approval';
+  else if (session.status === 'waiting' && DECISION_PATTERN.test(combined)) kind = 'decision';
+  else if (session.status === 'waiting' && INPUT_PATTERN.test(combined)) kind = 'input';
+  else if (session.status === 'waiting') kind = 'response';
+  const required = kind !== 'none';
+  const summaries = {
+    error: session.statusDetail || latest || 'The run failed and needs review.',
+    paused: session.statusDetail || 'The run is paused.',
+    approval: latest || session.statusDetail || 'Approval is required.',
+    decision: latest || session.statusDetail || 'A decision is required.',
+    input: latest || session.statusDetail || 'Input is required.',
+    response: latest || session.statusDetail || 'A response is required.',
+  };
+  return {
+    required,
+    kind,
+    summary: required ? text(summaries[kind], 360) : '',
+    requestedAt: required ? latestActivity(session) : null,
+    source: session.statusObserved || session.runId ? 'observed-status' : 'message-inference',
+    confidence: session.statusObserved || session.runId ? 'high' : required ? 'medium' : 'low',
+  };
+}
+
+function healthFor(session, sessions, attention, progress, evidence, nowValue) {
+  const now = Number(nowValue || Date.now());
+  const byId = new Map((sessions || []).map(row => [row.id, row]));
+  const signals = [];
+  const add = (code, severity, detail = '') => signals.push({ code, severity, detail: text(detail, 240) });
+  const activity = timestamp(progress.lastActivityAt);
+  const ageMs = activity ? Math.max(0, now - activity) : 0;
+  if (session.status === 'failed') add('run-failed', 'critical', session.statusDetail);
+  if (session.status === 'paused') add('run-paused', 'warning', session.statusDetail);
+  if (LIVE_STATUSES.has(session.status) && ageMs >= 10 * 60_000) add('stalled', 'critical', progress.currentStep);
+  else if (LIVE_STATUSES.has(session.status) && ageMs >= 2 * 60_000) add('stale', 'warning', progress.currentStep);
+  if (session.status === 'waiting' && ageMs >= 60 * 60_000) add('waiting-too-long', 'critical', attention.summary);
+  else if (session.status === 'waiting' && ageMs >= 10 * 60_000) add('waiting-too-long', 'warning', attention.summary);
+  const contextPercent = Number(session.context && session.context.percent || 0);
+  if (contextPercent >= 90) add('context-critical', 'critical', `${contextPercent.toFixed(1)}%`);
+  else if (contextPercent >= 75) add('context-warning', 'warning', `${contextPercent.toFixed(1)}%`);
+  if (progress.failedSteps >= 2) add('repeated-failures', 'critical', String(progress.failedSteps));
+  if (session.parentId && !byId.has(session.parentId)) add('orphan-agent', 'warning', session.parentId);
+  if (evidence.confidence === 'low') add('low-confidence', 'info', evidence.sources.join(', '));
+  const rank = { info: 1, warning: 2, critical: 3 };
+  const max = signals.reduce((value, signal) => Math.max(value, rank[signal.severity] || 0), 0);
+  return {
+    level: max >= 3 ? 'critical' : max === 2 ? 'warning' : attention.required ? 'attention' : max === 1 ? 'unknown' : 'healthy',
+    score: Math.max(0, 100 - signals.reduce((sum, signal) => sum + (signal.severity === 'critical' ? 35 : signal.severity === 'warning' ? 18 : 5), 0)),
+    signals,
+    lastActivityAt: progress.lastActivityAt,
+    ageSeconds: activity ? Math.round(ageMs / 1000) : null,
+  };
+}
+
+function enrichSession(session, sessions = [], nowValue = Date.now()) {
+  if (!session) return session;
+  const attention = attentionFor(session);
+  const progress = progressFor(session, attention);
+  const evidence = evidenceFor(session);
+  const controls = controlCapabilities(session);
+  const health = healthFor(session, sessions, attention, progress, evidence, nowValue);
+  return {
+    ...session,
+    attention,
+    progress,
+    health,
+    controlCapabilities: controls,
+    evidence,
+    outcome: outcomeFor(session, evidence),
+  };
+}
+
+module.exports = {
+  attentionFor,
+  controlCapabilities,
+  enrichSession,
+  evidenceFor,
+  extractArtifacts,
+  healthFor,
+  outcomeFor,
+  progressFor,
+};

package/src/terminalHost.js

@@ -0,0 +1,381 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const net = require('net');
+const crypto = require('crypto');
+const { EventEmitter } = require('events');
+const { spawn } = require('child_process');
+const { endpointFor, safeWriteJson } = require('./bridgeServer');
+const { runBestEffort } = require('./diagnostics');
+
+const TERMINAL_HOST_PROTOCOL = 1;
+const MAX_FRAME_CHARS = 4 * 1024 * 1024;
+const AUTH_TIMEOUT_MS = 5_000;
+const REQUEST_TIMEOUT_MS = 15_000;
+const HOST_OPERATIONS = new Set(['list', 'get', 'create', 'write', 'command', 'resize', 'signal', 'restart', 'close']);
+
+function sendFrame(socket, payload) {
+  if (!socket || socket.destroyed) return;
+  socket.write(`${JSON.stringify(payload)}\n`, 'utf8');
+}
+
+function readHostDiscovery(file, fileSystem = fs) {
+  const parsed = JSON.parse(fileSystem.readFileSync(file, 'utf8'));
+  if (parsed?.protocol !== TERMINAL_HOST_PROTOCOL || !parsed.endpoint || !parsed.token) {
+    throw new Error('터미널 호스트 연결 정보가 올바르지 않습니다.');
+  }
+  return parsed;
+}
+
+function activeSessions(manager) {
+  return manager.list().filter(session => session.status === 'running' || session.status === 'starting');
+}
+
+class TerminalHostServer {
+  constructor(options = {}) {
+    this.manager = options.manager;
+    this.platform = options.platform || process.platform;
+    this.discoveryFile = path.resolve(options.discoveryFile || path.join(os.tmpdir(), 'loadtoagent-terminal-host.json'));
+    this.endpoint = options.endpoint || endpointFor(this.platform, `${path.dirname(this.discoveryFile)}:terminal-host`);
+    this.token = options.token || crypto.randomBytes(32).toString('hex');
+    this.server = null;
+    this.clients = new Set();
+    this.shutdownTimer = null;
+    this.onShutdown = typeof options.onShutdown === 'function' ? options.onShutdown : () => {};
+    this.onManagerData = payload => this.broadcast({ type: 'event', event: 'data', payload });
+    this.onManagerState = payload => this.broadcast({ type: 'event', event: 'state', payload });
+  }
+
+  info() {
+    return {
+      protocol: TERMINAL_HOST_PROTOCOL,
+      endpoint: this.endpoint,
+      token: this.token,
+      pid: process.pid,
+      platform: this.platform,
+      updatedAt: new Date().toISOString(),
+    };
+  }
+
+  start() {
+    if (!this.manager) return Promise.reject(new Error('터미널 관리자가 준비되지 않았습니다.'));
+    if (this.server) return Promise.resolve(this.info());
+    if (this.platform !== 'win32' && fs.existsSync(this.endpoint)) {
+      runBestEffort('terminal-host-stale-endpoint', () => fs.unlinkSync(this.endpoint));
+    }
+    this.server = net.createServer(socket => this.accept(socket));
+    return new Promise((resolve, reject) => {
+      const fail = error => {
+        if (this.server) runBestEffort('terminal-host-start-close', () => this.server.close());
+        this.server = null;
+        reject(error);
+      };
+      this.server.once('error', fail);
+      this.server.listen(this.endpoint, () => {
+        this.server.removeListener('error', fail);
+        try {
+          safeWriteJson(this.discoveryFile, this.info());
+          this.manager.on('data', this.onManagerData);
+          this.manager.on('state', this.onManagerState);
+          resolve(this.info());
+        } catch (error) {
+          fail(error);
+        }
+      });
+    });
+  }
+
+  accept(socket) {
+    socket.setNoDelay(true);
+    const client = {
+      socket,
+      buffer: '',
+      authenticated: false,
+      queue: Promise.resolve(),
+      authTimer: setTimeout(() => socket.destroy(new Error('터미널 호스트 인증 시간이 초과되었습니다.')), AUTH_TIMEOUT_MS),
+    };
+    this.clients.add(client);
+    socket.on('data', chunk => this.consume(client, chunk));
+    socket.on('error', () => this.detach(client));
+    socket.on('close', () => this.detach(client));
+  }
+
+  consume(client, chunk) {
+    client.buffer += chunk.toString('utf8');
+    if (client.buffer.length > MAX_FRAME_CHARS) {
+      client.socket.destroy(new Error('터미널 호스트 요청이 너무 큽니다.'));
+      return;
+    }
+    let newline;
+    while ((newline = client.buffer.indexOf('\n')) >= 0) {
+      const line = client.buffer.slice(0, newline).trim();
+      client.buffer = client.buffer.slice(newline + 1);
+      if (!line) continue;
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch (_invalidFrame) {
+        client.socket.destroy(new Error('터미널 호스트 요청 형식이 올바르지 않습니다.'));
+        return;
+      }
+      client.queue = client.queue
+        .then(() => this.handle(client, message || {}))
+        .catch(error => sendFrame(client.socket, {
+          type: 'response',
+          requestId: String(message?.requestId || ''),
+          ok: false,
+          error: String(error?.message || error),
+        }));
+    }
+  }
+
+  async handle(client, message) {
+    if (!client.authenticated) {
+      if (message.type !== 'authenticate' || message.token !== this.token) {
+        throw new Error('터미널 호스트 인증에 실패했습니다.');
+      }
+      client.authenticated = true;
+      clearTimeout(client.authTimer);
+      client.authTimer = null;
+      if (this.shutdownTimer) {
+        clearTimeout(this.shutdownTimer);
+        this.shutdownTimer = null;
+      }
+      sendFrame(client.socket, { type: 'ready', sessions: this.manager.list() });
+      return;
+    }
+    if (message.type === 'control' && message.operation === 'shutdown-if-idle') {
+      if (activeSessions(this.manager).length === 0 && !this.shutdownTimer) {
+        this.shutdownTimer = setTimeout(() => {
+          this.shutdownTimer = null;
+          const connectedClients = [...this.clients].filter(entry => entry.authenticated && !entry.socket.destroyed);
+          if (activeSessions(this.manager).length === 0 && connectedClients.length === 0) this.onShutdown();
+        }, 1_500);
+        if (typeof this.shutdownTimer.unref === 'function') this.shutdownTimer.unref();
+      }
+      return;
+    }
+    if (message.type !== 'request' || !HOST_OPERATIONS.has(message.operation)) {
+      throw new Error('지원하지 않는 터미널 호스트 작업입니다.');
+    }
+    const operation = message.operation;
+    const args = Array.isArray(message.args) ? message.args : [];
+    const result = await Promise.resolve(this.manager[operation](...args));
+    sendFrame(client.socket, { type: 'response', requestId: String(message.requestId || ''), ok: true, result });
+  }
+
+  broadcast(payload) {
+    for (const client of this.clients) {
+      if (client.authenticated) sendFrame(client.socket, payload);
+    }
+  }
+
+  detach(client) {
+    if (client.authTimer) clearTimeout(client.authTimer);
+    this.clients.delete(client);
+  }
+
+  dispose() {
+    if (this.shutdownTimer) clearTimeout(this.shutdownTimer);
+    this.shutdownTimer = null;
+    this.manager.removeListener('data', this.onManagerData);
+    this.manager.removeListener('state', this.onManagerState);
+    for (const client of this.clients) runBestEffort('terminal-host-client-close', () => client.socket.destroy());
+    this.clients.clear();
+    if (this.server) runBestEffort('terminal-host-server-close', () => this.server.close());
+    this.server = null;
+    try {
+      const current = readHostDiscovery(this.discoveryFile);
+      if (current.pid === process.pid && current.token === this.token) fs.unlinkSync(this.discoveryFile);
+    } catch (_missingOrReplacedDiscovery) {}
+    if (this.platform !== 'win32' && fs.existsSync(this.endpoint)) {
+      runBestEffort('terminal-host-endpoint-cleanup', () => fs.unlinkSync(this.endpoint));
+    }
+  }
+}
+
+function launchTerminalHost(options = {}) {
+  const executable = options.executable || process.execPath;
+  const script = options.script;
+  if (!script) throw new Error('터미널 호스트 스크립트 경로가 없습니다.');
+  const config = Buffer.from(JSON.stringify({
+    storeFile: options.storeFile,
+    discoveryFile: options.discoveryFile,
+    bridgeHome: options.bridgeHome,
+  }), 'utf8').toString('base64');
+  fs.mkdirSync(path.dirname(options.discoveryFile), { recursive: true });
+  const child = (options.spawnProcess || spawn)(executable, [script, '--config', config], {
+    cwd: path.dirname(options.discoveryFile),
+    detached: true,
+    windowsHide: true,
+    stdio: 'ignore',
+    env: { ...process.env, ...options.env, ELECTRON_RUN_AS_NODE: '1' },
+  });
+  child.unref();
+  return child.pid;
+}
+
+class TerminalHostClient extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.discoveryFile = path.resolve(options.discoveryFile);
+    this.spawnHost = typeof options.spawnHost === 'function' ? options.spawnHost : null;
+    this.connectTimeoutMs = Number(options.connectTimeoutMs || 12_000);
+    this.socket = null;
+    this.buffer = '';
+    this.connected = false;
+    this.disposed = false;
+    this.sessions = [];
+    this.sequence = 0;
+    this.pending = new Map();
+    this.handshake = null;
+  }
+
+  async connect() {
+    this.disposed = false;
+    const deadline = Date.now() + this.connectTimeoutMs;
+    let launched = false;
+    let lastError = null;
+    while (Date.now() < deadline) {
+      try {
+        await this.connectExisting();
+        return this;
+      } catch (error) {
+        lastError = error;
+        this.resetSocket();
+      }
+      if (!launched) {
+        if (!this.spawnHost) throw lastError;
+        await Promise.resolve(this.spawnHost());
+        launched = true;
+      }
+      await new Promise(resolve => setTimeout(resolve, 120));
+    }
+    throw new Error(`터미널 호스트에 연결하지 못했습니다: ${lastError?.message || '시간 초과'}`);
+  }
+
+  connectExisting() {
+    const discovery = readHostDiscovery(this.discoveryFile);
+    return new Promise((resolve, reject) => {
+      const socket = net.createConnection(discovery.endpoint);
+      const timer = setTimeout(() => {
+        socket.destroy();
+        reject(new Error('터미널 호스트 연결 시간이 초과되었습니다.'));
+      }, 1_500);
+      this.socket = socket;
+      this.buffer = '';
+      this.handshake = {
+        resolve: () => { clearTimeout(timer); this.handshake = null; resolve(); },
+        reject: error => { clearTimeout(timer); this.handshake = null; reject(error); },
+      };
+      socket.setNoDelay(true);
+      socket.on('connect', () => sendFrame(socket, { type: 'authenticate', token: discovery.token }));
+      socket.on('data', chunk => this.consume(chunk));
+      socket.on('error', error => {
+        if (this.handshake) this.handshake.reject(error);
+      });
+      socket.on('close', () => this.handleDisconnect());
+    });
+  }
+
+  consume(chunk) {
+    this.buffer += chunk.toString('utf8');
+    if (this.buffer.length > MAX_FRAME_CHARS) {
+      this.socket?.destroy(new Error('터미널 호스트 응답이 너무 큽니다.'));
+      return;
+    }
+    let newline;
+    while ((newline = this.buffer.indexOf('\n')) >= 0) {
+      const line = this.buffer.slice(0, newline).trim();
+      this.buffer = this.buffer.slice(newline + 1);
+      if (!line) continue;
+      let message;
+      try { message = JSON.parse(line); } catch { continue; }
+      if (message.type === 'ready') {
+        this.sessions = Array.isArray(message.sessions) ? message.sessions : [];
+        this.connected = true;
+        if (this.handshake) this.handshake.resolve();
+      } else if (message.type === 'response') {
+        const pending = this.pending.get(String(message.requestId || ''));
+        if (!pending) continue;
+        this.pending.delete(String(message.requestId || ''));
+        clearTimeout(pending.timer);
+        if (message.ok) pending.resolve(message.result);
+        else pending.reject(new Error(String(message.error || '터미널 호스트 작업 실패')));
+      } else if (message.type === 'event' && message.event === 'data') {
+        this.emit('data', message.payload);
+      } else if (message.type === 'event' && message.event === 'state') {
+        if (Array.isArray(message.payload?.sessions)) this.sessions = message.payload.sessions;
+        this.emit('state', message.payload);
+      }
+    }
+  }
+
+  handleDisconnect() {
+    const wasConnected = this.connected;
+    this.connected = false;
+    if (this.handshake) this.handshake.reject(new Error('터미널 호스트 연결이 닫혔습니다.'));
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error('터미널 호스트 연결이 닫혔습니다.'));
+    }
+    this.pending.clear();
+    this.socket = null;
+    if (wasConnected && !this.disposed) this.emit('disconnect');
+  }
+
+  resetSocket() {
+    if (this.socket) this.socket.destroy();
+    this.socket = null;
+    this.connected = false;
+    this.buffer = '';
+  }
+
+  request(operation, ...args) {
+    if (!this.connected || !this.socket || this.socket.destroyed) {
+      return Promise.reject(new Error('터미널 호스트에 연결되어 있지 않습니다.'));
+    }
+    const requestId = String(++this.sequence);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(requestId);
+        reject(new Error(`터미널 호스트 작업 시간이 초과되었습니다: ${operation}`));
+      }, REQUEST_TIMEOUT_MS);
+      this.pending.set(requestId, { resolve, reject, timer });
+      sendFrame(this.socket, { type: 'request', requestId, operation, args });
+    });
+  }
+
+  list() { return this.sessions.map(session => ({ ...session })); }
+  get(id, includeReplay = true) { return this.request('get', id, includeReplay); }
+  create(options) { return this.request('create', options); }
+  write(id, data) { return this.request('write', id, data); }
+  command(id, command) { return this.request('command', id, command); }
+  resize(id, cols, rows) { return this.request('resize', id, cols, rows); }
+  signal(id, signal) { return this.request('signal', id, signal); }
+  restart(id) { return this.request('restart', id); }
+  close(id) { return this.request('close', id); }
+
+  dispose({ shutdownIfIdle = false } = {}) {
+    this.disposed = true;
+    if (this.socket && !this.socket.destroyed) {
+      if (shutdownIfIdle) sendFrame(this.socket, { type: 'control', operation: 'shutdown-if-idle' });
+      this.socket.end();
+    }
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error('터미널 호스트 클라이언트가 종료되었습니다.'));
+    }
+    this.pending.clear();
+  }
+}
+
+module.exports = {
+  TerminalHostServer,
+  TerminalHostClient,
+  TERMINAL_HOST_PROTOCOL,
+  readHostDiscovery,
+  launchTerminalHost,
+};

package/src/terminalHostDaemon.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { TerminalManager } = require('./terminalManager');
+const { BridgeServer } = require('./bridgeServer');
+const { TerminalHostServer } = require('./terminalHost');
+
+function parseConfig(argv = process.argv.slice(2)) {
+  const index = argv.indexOf('--config');
+  if (index < 0 || !argv[index + 1]) throw new Error('터미널 호스트 설정이 없습니다.');
+  const parsed = JSON.parse(Buffer.from(argv[index + 1], 'base64').toString('utf8'));
+  for (const key of ['storeFile', 'discoveryFile', 'bridgeHome']) {
+    if (!parsed[key] || typeof parsed[key] !== 'string') throw new Error(`터미널 호스트 설정이 올바르지 않습니다: ${key}`);
+  }
+  return {
+    storeFile: path.resolve(parsed.storeFile),
+    discoveryFile: path.resolve(parsed.discoveryFile),
+    bridgeHome: path.resolve(parsed.bridgeHome),
+  };
+}
+
+async function run(config = parseConfig()) {
+  process.title = 'LoadToAgent Terminal Host';
+  const manager = new TerminalManager({ storeFile: config.storeFile });
+  let stopping = false;
+  let host = null;
+  let bridge = null;
+  const stop = () => {
+    if (stopping) return;
+    stopping = true;
+    if (bridge) bridge.dispose();
+    if (host) host.dispose();
+    manager.dispose({ preserveSessions: true });
+    setImmediate(() => process.exit(0));
+  };
+  host = new TerminalHostServer({ manager, discoveryFile: config.discoveryFile, onShutdown: stop });
+  bridge = new BridgeServer({ terminalManager: manager, home: config.bridgeHome, platform: process.platform });
+  await host.start();
+  try { await bridge.start(); } catch (error) {
+    const logFile = path.join(path.dirname(config.discoveryFile), 'terminal-host.log');
+    fs.appendFileSync(logFile, `${new Date().toISOString()} bridge: ${error.stack || error.message}\n`, 'utf8');
+  }
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+  return { manager, host, bridge, stop };
+}
+
+if (require.main === module) {
+  run().catch(error => {
+    try {
+      const config = parseConfig();
+      fs.mkdirSync(path.dirname(config.discoveryFile), { recursive: true });
+      fs.appendFileSync(path.join(path.dirname(config.discoveryFile), 'terminal-host.log'), `${new Date().toISOString()} fatal: ${error.stack || error.message}\n`, 'utf8');
+    } catch {}
+    process.exitCode = 1;
+  });
+}
+
+module.exports = { parseConfig, run };