elanous 0.2.0 → 0.2.4

package/src/nexus/api/terminals.ts

@@ -21,7 +21,7 @@
 
 import { jsonResponse } from './http-server.js';
 import { checkAuth, type MetaApiOpts } from './meta-api.js';
-import { getPty, listPty, type PtyHandle } from '../../pty-shell/registry.js';
+import { getPty, listPty, onPtyEvent, type PtyEvent, type PtyHandle } from '../../pty-shell/registry.js';
 import { listAllPreviewTerminals } from '../../web-terminal/preview-tap-registry.js';
 import { debug } from '../../debug/log.js';
 export { terminalTreeLabel, terminalTreeNames } from '../../pty-shell/terminal-tree.js';
@@ -33,6 +33,7 @@ import { readPtyEventsAfter } from '../../pty-shell/pty-event-log.js';
 import { classifyPtyOwnerRunUsage, joinPtyLineage, resolveRunTermination, type PtyOwnerRunUsage, type RunTermination } from '../../cli/pty-takeover-cli.js';
 import { loadRunLedger, resolveFederatedRunLedgerDirectories, runLedgerDir } from '../../self-implement/run-ledger.js';
 import { requestRemotePtyControl, type PtyControlAction, type PtyControlPayload, type PtyControlRequestOptions, type PtyControlResult } from '../../pty-shell/pty-control-ipc.js';
+import { encodeSgrMouse, type PtyMouseInput } from '../../pty-shell/pty-mouse.js';
 import { queryRunningRuns, type RunningRunAssessment, type RunningRunPresence, type RunningRunStatus, type RunningRunsResult } from '../../self-implement/running-runs.js';
 // ⭐P4 §4-1 — 표시 폭(wide-char/CJK/emoji 인지) SSOT. PNG 캔버스 cols 파생용.
 import { cellWidth } from '../../ui/printer.js';
@@ -457,6 +458,8 @@ interface TerminalsListDeps extends TerminalManifestScopeDeps {
   /** 원격 logs.db 는 읽기 전용으로만 열어 연합한다. */
   openLogStoreReadOnly?(dbPath: string): Pick<LogStore, 'query' | 'close'>;
   queryRunningRuns?(options: { includeTest?: boolean }): RunningRunsResult;
+  /** Clock for the running-runs cache. Tests advance this instead of waiting out the TTL. */
+  now?(): number;
   runTerminated?(runId: string, options: { includeTest: boolean }): RunTermination;
 }
 
@@ -464,6 +467,33 @@ const SUB_AGENT_COUNT_WINDOW_MS = 24 * 60 * 60 * 1_000;
 const TERMINALS_SCOPE_DOMAIN = '이 표면의 terminals 목록은 실체 PTY만 봅니다. 로그에서 수집한 PTY 없는 Agent 서브 에이전트는 subjects와 scope 집계에만 반영됩니다.';
 const TERMINALS_SCOPE_SUB_AGENT_COUNT = '최근 24시간 현재 범위의 로그 스토어에서 센 PTY 없이 실행된 서브 에이전트';
 
+/**
+ * Process-wide single-flight cache. Two GET /v1/terminals calls with the same
+ * includeTest inside the TTL share one queryRunningRuns result. A different
+ * injector (tests) gets its own cache so one suite cannot poison another.
+ */
+interface RunningRunsCacheBinding {
+  cache: (options: { includeTest?: boolean }) => CachedRunningRuns;
+  now: () => number;
+}
+
+const runningRunsCaches = new WeakMap<object, RunningRunsCacheBinding>();
+
+function runningRunsCacheFor(
+  injector: (options: { includeTest?: boolean }) => RunningRunsResult,
+  now: () => number,
+): (options: { includeTest?: boolean }) => CachedRunningRuns {
+  const existing = runningRunsCaches.get(injector);
+  if (existing) {
+    existing.now = now;
+    return existing.cache;
+  }
+  const binding: RunningRunsCacheBinding = { cache: () => { throw new Error('uninitialized'); }, now };
+  binding.cache = createRunningRunsCache({ now: () => binding.now(), queryRunningRuns: injector });
+  runningRunsCaches.set(injector, binding);
+  return binding.cache;
+}
+
 const liveTerminalsListDeps: TerminalsListDeps = {
   ptyManifestTargets,
   listPtyManifestRows,
@@ -566,6 +596,67 @@ export type SubjectRunningRunsSummary = Pick<Record<RunningRunStatus, number>, '
   countedStatuses: readonly ['running', 'probable-running'];
 };
 
+/** Short TTL so a polling terminal list does not re-read every ledger on every request. */
+export const RUNNING_RUNS_CACHE_TTL_MS = 15_000;
+
+export interface CachedRunningRuns {
+  readonly result: RunningRunsResult;
+  /** Milliseconds since this result was computed. 0 on a fresh computation. */
+  readonly ageMs: number;
+}
+
+export interface RunningRunsCacheDeps {
+  now(): number;
+  queryRunningRuns(options: { includeTest?: boolean; caller?: string }): RunningRunsResult;
+}
+
+/**
+ * One computation at a time per includeTest.
+ *
+ * The list handler is synchronous, so two requests overlap only when the
+ * second enters while the injector is still on the stack. That re-entrant
+ * call shares the in-flight result and does not call the injector again.
+ * A later call inside the TTL returns the stored result and its age.
+ * A failed computation is not stored. Which runs are running is unchanged.
+ */
+export function createRunningRunsCache(
+  deps: RunningRunsCacheDeps,
+  ttlMs: number = RUNNING_RUNS_CACHE_TTL_MS,
+): (options: { includeTest?: boolean }) => CachedRunningRuns {
+  const slots = new Map<boolean, { at: number; result: RunningRunsResult }>();
+  const flights = new Set<boolean>();
+  return (options) => {
+    const includeTest = options.includeTest === true;
+    const now = deps.now();
+    const cached = slots.get(includeTest);
+    if (flights.has(includeTest)) {
+      // Same includeTest is already on this stack. Return the one result
+      // the owner publishes into the slot; never call the injector again.
+      if (cached) return { result: cached.result, ageMs: 0 };
+      const shared = {} as RunningRunsResult;
+      slots.set(includeTest, { at: now, result: shared });
+      return { result: shared, ageMs: 0 };
+    }
+    if (cached && now - cached.at < ttlMs) {
+      return { result: cached.result, ageMs: now - cached.at };
+    }
+    flights.add(includeTest);
+    try {
+      const computed = deps.queryRunningRuns({ includeTest, caller: 'nexus.terminals' });
+      const slot = slots.get(includeTest);
+      const result = slot?.result ?? computed;
+      if (slot) Object.assign(slot.result, computed);
+      else slots.set(includeTest, { at: now, result });
+      return { result, ageMs: 0 };
+    } catch (error) {
+      slots.delete(includeTest);
+      throw error;
+    } finally {
+      flights.delete(includeTest);
+    }
+  };
+}
+
 export function summarizeSubjectRunningRuns(subjects: readonly SubjectSummary[]): SubjectRunningRunsSummary {
   const counts: SubjectRunningRunsSummary = { running: 0, 'probable-running': 0, countedStatuses: ['running', 'probable-running'] };
   for (const subject of subjects) {
@@ -805,20 +896,14 @@ function terminalKey(terminal: Pick<TerminalSummary, 'id' | 'sourceRoot'>): stri
   return `${terminal.sourceRoot?.dbPath ?? ptyManifestDbPath()}\u0000${terminal.id}`;
 }
 
-function webTerminalKey(sessionId: string, terminalId: string): string {
-  return `${sessionId}\u0000${terminalId}`;
-}
-
 function mergeWebPreviewTerminals(ptyTerminals: TerminalSummary[]): TerminalSummary[] {
+  // Registry enumeration is shell-unique even when multiple ACP sessions
+  // have output taps on the same PreviewTerminal.
   const webTerminals = listAllPreviewTerminals();
   const liveWebTerminals = webTerminals.filter((terminal) => terminal.isAlive);
-  const seenWebTerminals = new Set<string>();
   const merged = [...ptyTerminals];
   let added = 0;
   for (const terminal of liveWebTerminals) {
-    const key = webTerminalKey(terminal.sessionId, terminal.terminalId);
-    if (seenWebTerminals.has(key)) continue;
-    seenWebTerminals.add(key);
     merged.push({
       id: terminal.terminalId,
       cmd: 'web-terminal',
@@ -969,8 +1054,18 @@ export function handleTerminalsList(req: Request, opts: MetaApiOpts, deps: Termi
   const resolveRunTerminationForRow = (runId: string): RunTermination => deps.runTerminated
     ? deps.runTerminated(runId, { includeTest })
     : 'ledger-indeterminate';
+  const runningRunsCache = runningRunsCacheFor(getRunningRuns, deps.now ?? Date.now);
   let runningRuns: RunningRunsResult | null = null;
-  try { runningRuns = getRunningRuns({ includeTest }); } catch { /* fail-soft: preserve terminal inspection */ }
+  let runningRunsAgeMs = 0;
+  let runningRunsQueryFailed = false;
+  try {
+    const cached = runningRunsCache({ includeTest });
+    runningRuns = cached.result;
+    runningRunsAgeMs = cached.ageMs;
+  } catch {
+    // Fail-soft and do not cache: subjects keep unknown assessments.
+    runningRunsQueryFailed = true;
+  }
   const ptyLessSubAgentCollection = collectPtyLessSubAgents(
     getLogStore,
     federated,
@@ -1013,7 +1108,7 @@ export function handleTerminalsList(req: Request, opts: MetaApiOpts, deps: Termi
     // 웹 터미널은 목록에만 합치며, 동명 ID가 PTY 가시성·scope 집계를 바꾸면 안 된다.
     const visibleIds = new Set(ptyTerminals.map((terminal) => terminal.id));
     const hiddenDead = manifestBeforeCleanup.filter((row) => !visibleIds.has(row.id)).length;
-    return jsonResponse({ terminals, subjects, runningRuns: summarizeSubjectRunningRuns(subjects), scope: terminalsScope(1, false, hiddenDead, hiddenSubAgentRuns) }, 200);
+    return jsonResponse({ terminals, subjects, runningRuns: summarizeSubjectRunningRuns(subjects), runningRunsAgeMs: runningRunsQueryFailed ? null : runningRunsAgeMs, scope: terminalsScope(1, false, hiddenDead, hiddenSubAgentRuns) }, 200);
   }
 
   const { currentDbPath, targets } = scope;
@@ -1044,7 +1139,7 @@ export function handleTerminalsList(req: Request, opts: MetaApiOpts, deps: Termi
   // log-derived agent summaries continue to feed subjects and scope independently.
   const terminals = mergeWebPreviewTerminals(ptyTerminals);
   const subjects = enrichSubjectRunAssessments(deriveSubjectSummaries(ptyTerminals, ptyLessSubAgents), runningRuns);
-  return jsonResponse({ terminals, subjects, runningRuns: summarizeSubjectRunningRuns(subjects), scope: terminalsScope(targets.length, true, hiddenDead, hiddenSubAgentRuns) }, 200);
+  return jsonResponse({ terminals, subjects, runningRuns: summarizeSubjectRunningRuns(subjects), runningRunsAgeMs: runningRunsQueryFailed ? null : runningRunsAgeMs, scope: terminalsScope(targets.length, true, hiddenDead, hiddenSubAgentRuns) }, 200);
 }
 
 export interface TerminalPruneDeps extends TerminalManifestScopeDeps {
@@ -1207,6 +1302,85 @@ export function parseTerminalRenamePath(pathname: string): string | null {
   return m && m[1] ? safeDecodeSegment(m[1]) : null;
 }
 
+/** Path matcher: `/v1/terminals/:id/stream`. */
+export function parseTerminalStreamPath(pathname: string): string | null {
+  const m = /^\/v1\/terminals\/([^/]+)\/stream$/.exec(pathname);
+  return m && m[1] ? safeDecodeSegment(m[1]) : null;
+}
+
+export interface TerminalStreamDeps {
+  getPty?: (id: string) => Pick<PtyHandle, 'renderScreen'> | undefined;
+  onPtyEvent?: (cb: (ev: PtyEvent) => void) => () => void;
+  requestRemotePtyControl?: TerminalControlDeps['requestRemotePtyControl'];
+  isAllowedSourceRoot?: (dbPath: string) => boolean;
+  /** 남의 PTY 화면을 다시 묻는 간격(ms). */
+  pollMs?: number;
+  /** 바이트 묶음 간격(ms). */
+  flushMs?: number;
+}
+
+/** GET /v1/terminals/:id/stream — PWA 웹 터미널 실시간(드라이브 RFC ⑥ · 800ms 폴링 대체 · SSE).
+ *  - 이 데몬이 가진 PTY: 처음 `reset`(현재 화면) → `onPtyEvent` 출력 바이트를 `data` 로 흘린다(flushMs 로 묶음) · 끝나면 `end`.
+ *  - 남의 PTY(다른 프로세스·연합 뿌리): 서버 쪽에서 pollMs 마다 스냅숏 → 화면이 «바뀐 때만» `screen`.
+ *    ⛔ 교차 프로세스 바이트 버스는 아직 없다 — owner 의 제어 처리기가 직렬이라 pollMs 는 150ms 아래로 내리지 않는다.
+ *  - 입력은 그대로 `POST /control`. 연결이 끊기면 구독·루프를 멈춘다(평소 부하 0). */
+export function handleTerminalStream(req: Request, opts: MetaApiOpts, id: string, deps: TerminalStreamDeps = {}): Response {
+  if (!checkAuth(req, opts)) return jsonResponse({ error: 'unauthorized' }, 401);
+  if (!id) return jsonResponse({ error: 'missing-id' }, 400);
+  const sourceRoot = new URL(req.url).searchParams.get('sourceRoot');
+  if (sourceRoot !== null && !(deps.isAllowedSourceRoot ?? isAllowedSourceRoot)(sourceRoot)) return jsonResponse({ error: 'not-found', sourceRoot }, 404);
+  const local = sourceRoot === null ? (deps.getPty ?? getPty)(id) : undefined;
+  const pollMs = Math.max(150, deps.pollMs ?? 200);
+  const flushMs = deps.flushMs ?? 25;
+  const encoder = new TextEncoder();
+  let stop: () => void = () => {};
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      let closed = false;
+      const send = (event: string, data: unknown) => {
+        if (closed) return;
+        try { controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)); } catch { closed = true; }
+      };
+      const close = () => { if (closed) return; closed = true; try { controller.close(); } catch { /* already closed */ } };
+      const heartbeat = setInterval(() => { if (!closed) { try { controller.enqueue(encoder.encode(': hb\n\n')); } catch { closed = true; } } }, 15_000);
+      if (local) {
+        send('mode', { mode: 'bytes' });
+        let pending = '';
+        let timer: ReturnType<typeof setTimeout> | null = null;
+        const flush = () => { timer = null; if (pending) { send('data', pending); pending = ''; } };
+        void local.renderScreen({ ansi: true }).then((screen) => send('reset', { screen })).catch(() => send('reset', { screen: '' }));
+        const off = (deps.onPtyEvent ?? onPtyEvent)((ev) => {
+          if (ev.id !== id) return;
+          if (ev.type === 'output') { pending += ev.chunk; if (!timer) timer = setTimeout(flush, flushMs); }
+          else if (ev.type === 'exit' || ev.type === 'unregistered') { flush(); send('end', { reason: ev.type }); cleanup(); }
+        });
+        const cleanup = () => { off(); if (timer) clearTimeout(timer); clearInterval(heartbeat); close(); };
+        stop = cleanup;
+        return;
+      }
+      send('mode', { mode: 'screen', pollMs });
+      let last = '';
+      let loop: ReturnType<typeof setTimeout> | null = null;
+      const control = deps.requestRemotePtyControl ?? requestRemotePtyControl;
+      const tick = async () => {
+        if (closed) return;
+        try {
+          const r = await control(id, 'snapshot', { ansi: true }, { timeoutMs: TERMINAL_CONTROL_TIMEOUT_MS, ...(sourceRoot ? { manifestDbPath: sourceRoot } : {}) });
+          if (r.status === 'unknown-pty') { send('end', { reason: 'unknown-pty' }); cleanup(); return; }
+          if (r.status === 'success' && typeof r.screen === 'string' && r.screen !== last) { last = r.screen; send('screen', { screen: r.screen }); }
+          else if (r.status !== 'success') send('status', { status: r.status });
+        } catch { send('status', { status: 'control-failed' }); }
+        if (!closed) loop = setTimeout(() => { void tick(); }, pollMs);
+      };
+      const cleanup = () => { if (loop) clearTimeout(loop); clearInterval(heartbeat); close(); };
+      stop = cleanup;
+      void tick();
+    },
+    cancel() { stop(); },
+  });
+  return new Response(stream, { status: 200, headers: { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache', connection: 'keep-alive', 'x-accel-buffering': 'no' } });
+}
+
 /** Path matcher: `/v1/terminals/:id/terminate`. */
 export function parseTerminalTerminatePath(pathname: string): string | null {
   const m = /^\/v1\/terminals\/([^/]+)\/terminate$/.exec(pathname);
@@ -1215,6 +1389,7 @@ export function parseTerminalTerminatePath(pathname: string): string | null {
 
 interface TerminalControlDeps {
   requestRemotePtyControl(id: string, action: PtyControlAction, payload?: PtyControlPayload, options?: PtyControlRequestOptions): Promise<PtyControlResult>;
+  isAllowedSourceRoot?: (dbPath: string) => boolean;
 }
 
 const liveTerminalControlDeps: TerminalControlDeps = { requestRemotePtyControl };
@@ -1233,20 +1408,31 @@ export async function handleTerminalControl(
   if (!id) return jsonResponse({ error: 'missing-id' }, 400);
   let body: unknown;
   try { body = await req.json(); } catch { return jsonResponse({ error: 'invalid-json', reason: 'JSON body required' }, 400); }
-  const request = body !== null && typeof body === 'object' ? body as { action?: unknown; chars?: unknown; ansi?: unknown } : {};
+  const request = body !== null && typeof body === 'object' && !Array.isArray(body) ? body as { action?: unknown; chars?: unknown; ansi?: unknown; x?: unknown; y?: unknown; kind?: unknown; button?: unknown } : {};
   const action = request.action;
-  if (action !== 'takeover' && action !== 'release' && action !== 'input-text' && action !== 'input-key' && action !== 'snapshot') {
-    return jsonResponse({ error: 'invalid-action', reason: 'action must be takeover, release, input-text, input-key, or snapshot' }, 400);
+  if (action !== 'takeover' && action !== 'release' && action !== 'input-text' && action !== 'input-key' && action !== 'input-mouse' && action !== 'snapshot') {
+    return jsonResponse({ error: 'invalid-action', reason: 'action must be takeover, release, input-text, input-key, input-mouse, or snapshot' }, 400);
   }
   const isInput = action === 'input-text' || action === 'input-key';
   if (isInput && (typeof request.chars !== 'string' || request.chars.length === 0)) {
     return jsonResponse({ error: 'invalid-payload', reason: 'chars must be a non-empty string' }, 400);
   }
+  let mouse: PtyMouseInput | undefined;
+  if (action === 'input-mouse') {
+    if (typeof request.x !== 'number' || typeof request.y !== 'number' || (request.kind !== 'click' && request.kind !== 'scroll-up' && request.kind !== 'scroll-down') || (request.button !== undefined && request.button !== 'left' && request.button !== 'middle' && request.button !== 'right')) {
+      return jsonResponse({ error: 'invalid-payload', reason: 'mouse requires 1-based x,y, kind and optional button' }, 400);
+    }
+    mouse = { x: request.x, y: request.y, kind: request.kind, ...(request.button ? { button: request.button } : {}) };
+    try { encodeSgrMouse(mouse); } catch (error) { return jsonResponse({ error: 'invalid-payload', reason: (error as Error).message }, 400); }
+  }
   const payload = isInput ? { chars: request.chars as string }
-    : action === 'snapshot' && request.ansi === true ? { ansi: true }
-      : undefined;
+    : mouse ?? (action === 'snapshot' && request.ansi === true ? { ansi: true } : undefined);
+  // 연합 PTY(다른 매니페스트 뿌리)는 그 DB 에 요청을 남겨야 그 행의 owner 가 처리한다 — PWA 가 `?sourceRoot=` 를 보내는데
+  // 이 자리가 무시해 연합 PTY 제어·스냅숏이 `unknown-pty` 로 떨어졌다(09-28 탐색). frame 핸들러와 같은 규칙으로 받는다.
+  const sourceRoot = new URL(req.url).searchParams.get('sourceRoot');
+  if (sourceRoot !== null && !(deps.isAllowedSourceRoot ?? isAllowedSourceRoot)(sourceRoot)) return jsonResponse({ error: 'not-found', sourceRoot }, 404);
   try {
-    const result = await deps.requestRemotePtyControl(id, action, payload, { timeoutMs: TERMINAL_CONTROL_TIMEOUT_MS });
+    const result = await deps.requestRemotePtyControl(id, action, payload, { timeoutMs: TERMINAL_CONTROL_TIMEOUT_MS, ...(sourceRoot ? { manifestDbPath: sourceRoot } : {}) });
     const status = result.status === 'unknown-pty' ? 404
       : result.status === 'owner-unreachable' ? 504
       : result.status === 'failed' || result.status === 'write-failed' ? 502