@linkshell/gateway 0.5.2 → 0.6.0

package/src/pairings.ts

@@ -1,133 +0,0 @@
-import { randomInt, randomUUID } from "node:crypto";
-import type { GatewayStateStore } from "./state-store.js";
-
-export interface PairingRecord {
-  sessionId: string;
-  pairingCode: string;
-  expiresAt: number; // unix ms
-  claimed: boolean;
-  failedAttempts: number; // failed claim attempts against this code
-}
-
-const PAIRING_TTL = Number(process.env.PAIRING_TTL_MS ?? 10 * 60_000); // 10 minutes
-const CLEANUP_INTERVAL = 60_000;
-// Invalidate a code after this many failed claim attempts to cap brute-forcing.
-const MAX_FAILED_CLAIM_ATTEMPTS = Number(
-  process.env.PAIRING_MAX_FAILED_ATTEMPTS ?? 5,
-);
-
-export class PairingManager {
-  private pairings = new Map<string, PairingRecord>();
-  private cleanupTimer: ReturnType<typeof setInterval>;
-
-  constructor(private readonly store?: GatewayStateStore) {
-    this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL);
-  }
-
-  async hydrate(): Promise<void> {
-    if (!this.store) return;
-    try {
-      const records = await this.store.loadPairings();
-      const now = Date.now();
-      for (const record of records) {
-        if (record.expiresAt < now) {
-          void this.store.deletePairing(record.pairingCode).catch(() => {});
-          continue;
-        }
-        // Stored records predate the failedAttempts field; default it.
-        this.pairings.set(record.pairingCode, { ...record, failedAttempts: 0 });
-      }
-    } catch (err) {
-      process.stderr.write(`[gateway] pairing store hydrate failed, using memory only: ${err}\n`);
-    }
-  }
-
-  create(sessionId?: string): PairingRecord {
-    const id = sessionId ?? randomUUID();
-    const code = String(randomInt(100000, 999999));
-    const record: PairingRecord = {
-      sessionId: id,
-      pairingCode: code,
-      expiresAt: Date.now() + PAIRING_TTL,
-      claimed: false,
-      failedAttempts: 0,
-    };
-    this.pairings.set(code, record);
-    this.persist(record);
-    return record;
-  }
-
-  claim(pairingCode: string): PairingRecord | { error: string; status: number } {
-    const record = this.pairings.get(pairingCode);
-    if (!record) {
-      return { error: "pairing_not_found", status: 404 };
-    }
-    if (record.expiresAt < Date.now()) {
-      this.pairings.delete(pairingCode);
-      void this.store?.deletePairing(pairingCode).catch(() => {});
-      return { error: "pairing_expired", status: 410 };
-    }
-    if (record.claimed) {
-      // Count repeated claim attempts on an existing code; once the cap is
-      // exceeded, invalidate it so it can no longer be targeted.
-      record.failedAttempts += 1;
-      if (record.failedAttempts >= MAX_FAILED_CLAIM_ATTEMPTS) {
-        this.pairings.delete(pairingCode);
-        void this.store?.deletePairing(pairingCode).catch(() => {});
-      } else {
-        this.persist(record);
-      }
-      return { error: "pairing_already_claimed", status: 409 };
-    }
-    record.claimed = true;
-    this.persist(record);
-    return record;
-  }
-
-  /** Look up a code's session without consuming an attempt or mutating state.
-   *  Lets the claim endpoint stay idempotent for a device that already owns the
-   *  mapped session (it re-issues instead of erroring with already_claimed). */
-  peek(pairingCode: string): { sessionId: string; claimed: boolean } | null {
-    const record = this.pairings.get(pairingCode);
-    if (!record) return null;
-    if (record.expiresAt < Date.now()) return null;
-    return { sessionId: record.sessionId, claimed: record.claimed };
-  }
-
-  getStatus(pairingCode: string): { status: string; expiresAt: number; sessionId: string } | { error: string; httpStatus: number } {
-    const record = this.pairings.get(pairingCode);
-    if (!record) {
-      return { error: "pairing_not_found", httpStatus: 404 };
-    }
-    if (record.expiresAt < Date.now()) {
-      this.pairings.delete(pairingCode);
-      void this.store?.deletePairing(pairingCode).catch(() => {});
-      return { error: "pairing_expired", httpStatus: 410 };
-    }
-    return {
-      status: record.claimed ? "claimed" : "waiting",
-      expiresAt: record.expiresAt,
-      sessionId: record.sessionId,
-    };
-  }
-
-  private cleanup(): void {
-    const now = Date.now();
-    for (const [code, record] of this.pairings) {
-      if (record.expiresAt < now) {
-        this.pairings.delete(code);
-        void this.store?.deletePairing(code).catch(() => {});
-      }
-    }
-  }
-
-  private persist(record: PairingRecord): void {
-    void this.store?.savePairing(record).catch((err) => {
-      process.stderr.write(`[gateway] pairing store save failed: ${err}\n`);
-    });
-  }
-
-  destroy(): void {
-    clearInterval(this.cleanupTimer);
-  }
-}

package/src/presence.ts

@@ -1,118 +0,0 @@
-import type WebSocket from "ws";
-import { createEnvelope, serializeEnvelope, PROTOCOL_VERSION } from "@linkshell/protocol";
-import type { Session, SessionManager } from "./sessions.js";
-
-interface Watcher {
-  socket: WebSocket;
-  /** Session ids this watcher is allowed to see. Re-evaluated per notify
-   *  so newly-bound tokens pick up sessions without reconnecting. */
-  sessionIds: () => Set<string>;
-  userId?: string;
-}
-
-/** Cross-session presence fan-out for the web session list. */
-export class PresenceHub {
-  private watchers = new Set<Watcher>();
-
-  add(watcher: Watcher): void {
-    this.watchers.add(watcher);
-    watcher.socket.on("close", () => this.watchers.delete(watcher));
-    watcher.socket.on("error", () => this.watchers.delete(watcher));
-  }
-
-  /** Send the current summary for every visible session (connect snapshot). */
-  snapshot(watcher: Watcher, sessions: SessionManager): void {
-    const allowed = watcher.sessionIds();
-    for (const session of sessions.listActive()) {
-      if (!this.visible(watcher, session, allowed)) continue;
-      this.send(watcher.socket, session);
-    }
-  }
-
-  notify(session: Session): void {
-    if (this.watchers.size === 0) return;
-    for (const watcher of this.watchers) {
-      if (watcher.socket.readyState !== watcher.socket.OPEN) continue;
-      if (!this.visible(watcher, session, watcher.sessionIds())) continue;
-      this.send(watcher.socket, session);
-    }
-  }
-
-  private visible(watcher: Watcher, session: Session, allowed: Set<string>): boolean {
-    if (allowed.has(session.id)) return true;
-    if (watcher.userId && session.userId && watcher.userId === session.userId) return true;
-    return false;
-  }
-
-  private send(socket: WebSocket, session: Session): void {
-    if (socket.readyState !== socket.OPEN) return;
-    socket.send(
-      serializeEnvelope(
-        createEnvelope({
-          type: "session.presence",
-          sessionId: session.id,
-          payload: {
-            hasHost:
-              !!session.host &&
-              session.host.socket.readyState === session.host.socket.OPEN,
-            agentStatus: session.agentStatus ?? null,
-            agentProvider: session.agentProvider ?? null,
-            agentConversationId: session.agentConversationId ?? null,
-            agentTitle: session.agentTitle ?? null,
-            agentDetail: session.agentDetail ?? null,
-            agentLastActivity: session.agentLastActivity ?? null,
-            lastActivity: session.lastActivity,
-            agentUsage: session.agentUsage ?? null,
-          },
-        }),
-      ),
-    );
-  }
-}
-
-export function startPresenceWatcher(input: {
-  socket: WebSocket;
-  sessions: SessionManager;
-  hub: PresenceHub;
-  sessionIds: () => Set<string>;
-  userId?: string;
-  pingIntervalMs?: number;
-}): void {
-  const { socket, sessions, hub, sessionIds, userId, pingIntervalMs = 20_000 } = input;
-  const watcher = { socket, sessionIds, userId };
-  hub.add(watcher);
-
-  socket.send(
-    serializeEnvelope(
-      createEnvelope({
-        type: "session.connect",
-        sessionId: "_presence",
-        payload: {
-          role: "client",
-          clientName: "watcher",
-          protocolVersion: PROTOCOL_VERSION,
-        },
-      }),
-    ),
-  );
-  hub.snapshot(watcher, sessions);
-
-  const liveSocket = socket as WebSocket & { isAlive?: boolean };
-  liveSocket.isAlive = true;
-  socket.on("pong", () => {
-    liveSocket.isAlive = true;
-  });
-  socket.on("message", () => {
-    liveSocket.isAlive = true;
-  });
-  const pingTimer = setInterval(() => {
-    if (socket.readyState !== socket.OPEN) return;
-    if (liveSocket.isAlive === false) {
-      socket.terminate();
-      return;
-    }
-    liveSocket.isAlive = false;
-    socket.ping();
-  }, pingIntervalMs);
-  socket.on("close", () => clearInterval(pingTimer));
-}

package/src/sessions.ts

@@ -1,432 +0,0 @@
-import type WebSocket from "ws";
-import type { Envelope } from "@linkshell/protocol";
-
-export type SessionState = "active" | "host_disconnected" | "terminated";
-
-export interface ConnectedDevice {
-  socket: WebSocket;
-  role: "host" | "client";
-  deviceId: string;
-  connectedAt: number;
-}
-
-export interface Session {
-  id: string;
-  state: SessionState;
-  host: ConnectedDevice | undefined;
-  clients: Map<string, ConnectedDevice>;
-  controllerId: string | undefined;
-  lastActivity: number;
-  createdAt: number;
-  outputBuffers: Map<string, Envelope[]>; // keyed by terminalId
-  outputBufferBytes: Map<string, number>; // approx byte size per terminalId buffer
-  lastStatusByTerminal: Map<string, Envelope>; // last terminal.status per terminal
-  hostDisconnectedAt: number | undefined;
-  // Metadata from host's session.connect
-  provider: string | undefined;
-  machineId: string | undefined;
-  hostname: string | undefined;
-  platform: string | undefined;
-  cwd: string | undefined;
-  projectName: string | undefined;
-  // Auth: user who owns this session (set on AUTH_REQUIRED gateways)
-  userId: string | undefined;
-  // Latest agent/conversation state reported by the host.
-  agentStatus: string | undefined;
-  agentProvider: string | undefined;
-  agentConversationId: string | undefined;
-  agentTitle: string | undefined;
-  // Short "what it's doing / asking" line for the session list.
-  agentDetail: string | undefined;
-  agentLastActivity: number | undefined;
-  // Latest token/context usage for the picked conversation (for at-a-glance
-  // display on the session list, without opening the console).
-  agentUsage: AgentUsageSummary | undefined;
-  // Latest full usage report from the host (cross-provider aggregate across ALL
-  // on-disk transcripts). Sent automatically on connect; shown as summary cards
-  // on the session list page without entering the console.
-  agentUsageReport: unknown | undefined;
-  // Last agent.v2.snapshot + recent host→client agent envelopes, so a
-  // reconnecting console can catch up without waiting on the host.
-  lastAgentSnapshot: Envelope | undefined;
-  agentReplay: Envelope[];
-}
-
-export interface AgentUsageSummary {
-  inputTokens?: number;
-  outputTokens?: number;
-  cacheReadTokens?: number;
-  totalTokens?: number;
-  contextWindow?: number;
-  totalCostUsd?: number;
-}
-
-const OUTPUT_BUFFER_CAPACITY = 200;
-const OUTPUT_BUFFER_MAX_BYTES = 8 * 1024 * 1024; // 8MB per terminal buffer
-const AGENT_REPLAY_CAPACITY = 80;
-const HOST_RECONNECT_WINDOW = 60_000; // 60s
-const CLEANUP_INTERVAL = 30_000;
-
-/** Approximate the wire byte size of an envelope for buffer accounting. */
-function approxEnvelopeBytes(envelope: Envelope): number {
-  const data = (envelope.payload as { data?: unknown } | undefined)?.data;
-  if (typeof data === "string") return data.length;
-  try {
-    return JSON.stringify(envelope).length;
-  } catch {
-    return 0;
-  }
-}
-
-export class SessionManager {
-  private sessions = new Map<string, Session>();
-  private cleanupTimer: ReturnType<typeof setInterval>;
-  /** Fired when host liveness or visible agent summary fields change. */
-  onPresenceChange?: (session: Session) => void;
-
-  constructor() {
-    this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL);
-  }
-
-  private emitPresence(session: Session): void {
-    this.onPresenceChange?.(session);
-  }
-
-  getOrCreate(sessionId: string): Session {
-    let session = this.sessions.get(sessionId);
-    if (!session) {
-      session = {
-        id: sessionId,
-        state: "active",
-        host: undefined,
-        clients: new Map(),
-        controllerId: undefined,
-        lastActivity: Date.now(),
-        createdAt: Date.now(),
-        outputBuffers: new Map(),
-        outputBufferBytes: new Map(),
-        lastStatusByTerminal: new Map(),
-        hostDisconnectedAt: undefined,
-        provider: undefined,
-        machineId: undefined,
-        hostname: undefined,
-        platform: undefined,
-        cwd: undefined,
-        projectName: undefined,
-        userId: undefined,
-        agentStatus: undefined,
-        agentProvider: undefined,
-        agentConversationId: undefined,
-        agentTitle: undefined,
-        agentDetail: undefined,
-        agentLastActivity: undefined,
-        agentUsage: undefined,
-        agentUsageReport: undefined,
-        lastAgentSnapshot: undefined,
-        agentReplay: [],
-      };
-      this.sessions.set(sessionId, session);
-    }
-    return session;
-  }
-
-  get(sessionId: string): Session | undefined {
-    return this.sessions.get(sessionId);
-  }
-
-  setHost(sessionId: string, device: ConnectedDevice): void {
-    const session = this.getOrCreate(sessionId);
-    session.host = device;
-    session.state = "active";
-    session.hostDisconnectedAt = undefined;
-    session.lastActivity = Date.now();
-    this.emitPresence(session);
-  }
-
-  addClient(sessionId: string, device: ConnectedDevice): void {
-    const session = this.getOrCreate(sessionId);
-    session.clients.set(device.deviceId, device);
-    if (!session.controllerId) {
-      session.controllerId = device.deviceId;
-    }
-    session.lastActivity = Date.now();
-  }
-
-  removeHost(
-    sessionId: string,
-  ): { clients: Map<string, ConnectedDevice> } | undefined {
-    const session = this.sessions.get(sessionId);
-    if (!session) return undefined;
-    session.host = undefined;
-    session.state = "host_disconnected";
-    session.hostDisconnectedAt = Date.now();
-    this.emitPresence(session);
-    return { clients: session.clients };
-  }
-
-  removeClient(sessionId: string, deviceId: string): void {
-    const session = this.sessions.get(sessionId);
-    if (!session) return;
-    session.clients.delete(deviceId);
-    if (session.controllerId === deviceId) {
-      // Transfer control to next client or clear
-      const next = session.clients.keys().next();
-      session.controllerId = next.done ? undefined : next.value;
-    }
-    this.maybeDelete(sessionId);
-  }
-
-  /** Force-delete a session: disconnect host + all clients, remove from map. */
-  forceDelete(sessionId: string): boolean {
-    const session = this.sessions.get(sessionId);
-    if (!session) return false;
-    if (session.host) {
-      try { session.host.socket.close(1000, "session deleted"); } catch {}
-    }
-    for (const [, client] of session.clients) {
-      try { client.socket.close(1000, "session deleted"); } catch {}
-    }
-    this.sessions.delete(sessionId);
-    return true;
-  }
-
-  bufferOutput(sessionId: string, envelope: Envelope): void {
-    const session = this.sessions.get(sessionId);
-    if (!session) return;
-    const tid = (envelope as any).terminalId ?? "default";
-    let buf = session.outputBuffers.get(tid);
-    if (!buf) {
-      buf = [];
-      session.outputBuffers.set(tid, buf);
-      session.outputBufferBytes.set(tid, 0);
-    }
-    buf.push(envelope);
-    let bytes = (session.outputBufferBytes.get(tid) ?? 0) + approxEnvelopeBytes(envelope);
-    // Evict oldest until under BOTH the count cap and the byte cap, so a
-    // malicious/abnormal host can't pin unbounded memory via large frames.
-    while (
-      buf.length > OUTPUT_BUFFER_CAPACITY ||
-      (bytes > OUTPUT_BUFFER_MAX_BYTES && buf.length > 1)
-    ) {
-      const removed = buf.shift();
-      if (removed) bytes -= approxEnvelopeBytes(removed);
-    }
-    session.outputBufferBytes.set(tid, Math.max(0, bytes));
-    session.lastActivity = Date.now();
-  }
-
-  cacheStatus(sessionId: string, envelope: Envelope): void {
-    const session = this.sessions.get(sessionId);
-    if (!session) return;
-    const tid = (envelope as any).terminalId ?? "default";
-    session.lastStatusByTerminal.set(tid, envelope);
-    session.lastActivity = Date.now();
-  }
-
-  getStatusReplay(sessionId: string): Envelope[] {
-    const session = this.sessions.get(sessionId);
-    if (!session) return [];
-    return [...session.lastStatusByTerminal.values()];
-  }
-
-  getReplayFrom(
-    sessionId: string,
-    afterSeqByTerminal: Record<string, number>,
-    fallbackAfterSeq = -1,
-  ): Envelope[] {
-    const session = this.sessions.get(sessionId);
-    if (!session) return [];
-    const result: Envelope[] = [];
-    for (const [terminalId, buf] of session.outputBuffers) {
-      const afterSeq = afterSeqByTerminal[terminalId] ?? fallbackAfterSeq;
-      for (const e of buf) {
-        if (e.seq !== undefined && e.seq > afterSeq) result.push(e);
-      }
-    }
-    return result.sort((a, b) => {
-      const at = Date.parse(a.timestamp);
-      const bt = Date.parse(b.timestamp);
-      if (!Number.isNaN(at) && !Number.isNaN(bt) && at !== bt) return at - bt;
-      return (a.seq ?? 0) - (b.seq ?? 0);
-    });
-  }
-
-  claimControl(sessionId: string, deviceId: string): boolean {
-    const session = this.sessions.get(sessionId);
-    if (!session) return false;
-    // Always allow takeover – last claimer wins
-    session.controllerId = deviceId;
-    return true;
-  }
-
-  releaseControl(sessionId: string, deviceId: string): boolean {
-    const session = this.sessions.get(sessionId);
-    if (!session) return false;
-    if (session.controllerId !== deviceId) return false;
-    session.controllerId = undefined;
-    return true;
-  }
-
-  terminate(sessionId: string): void {
-    const session = this.sessions.get(sessionId);
-    if (!session) return;
-    session.state = "terminated";
-  }
-
-  listActive(): Session[] {
-    return [...this.sessions.values()].filter((s) => s.state !== "terminated");
-  }
-
-  getSummary(sessionId: string) {
-    const session = this.sessions.get(sessionId);
-    if (!session) return undefined;
-    return {
-      id: session.id,
-      state: session.state,
-      hasHost:
-        !!session.host &&
-        session.host.socket.readyState === session.host.socket.OPEN,
-      clientCount: session.clients.size,
-      controllerId: session.controllerId ?? null,
-      lastActivity: session.lastActivity,
-      createdAt: session.createdAt,
-      bufferSize: [...session.outputBuffers.values()].reduce((sum, buf) => sum + buf.length, 0),
-      provider: session.provider ?? null,
-      machineId: session.machineId ?? null,
-      hostname: session.hostname ?? null,
-      platform: session.platform ?? null,
-      cwd: session.cwd ?? null,
-      projectName: session.projectName ?? null,
-      userId: session.userId ?? null,
-      agentStatus: session.agentStatus ?? null,
-      agentProvider: session.agentProvider ?? null,
-      agentConversationId: session.agentConversationId ?? null,
-      agentTitle: session.agentTitle ?? null,
-      agentDetail: session.agentDetail ?? null,
-      agentLastActivity: session.agentLastActivity ?? null,
-      agentUsage: session.agentUsage ?? null,
-      agentUsageReport: session.agentUsageReport ?? null,
-    };
-  }
-
-  cacheAgentSummary(
-    sessionId: string,
-    summary: {
-      status?: string;
-      provider?: string | null;
-      conversationId?: string | null;
-      title?: string | null;
-      detail?: string | null;
-      lastActivity?: number | null;
-      usage?: AgentUsageSummary | null;
-    },
-  ): boolean {
-    const session = this.sessions.get(sessionId);
-    if (!session) return false;
-    const prev = {
-      status: session.agentStatus,
-      provider: session.agentProvider,
-      conversationId: session.agentConversationId,
-      title: session.agentTitle,
-      detail: session.agentDetail,
-    };
-    if (summary.status) session.agentStatus = summary.status;
-    if (summary.provider !== undefined) session.agentProvider = summary.provider ?? undefined;
-    if (summary.conversationId !== undefined) session.agentConversationId = summary.conversationId ?? undefined;
-    if (summary.title !== undefined) session.agentTitle = summary.title ?? undefined;
-    if (summary.detail !== undefined) {
-      session.agentDetail = summary.detail ?? undefined;
-    } else if (summary.status && summary.status !== "waiting_permission") {
-      // Permission lines are only meaningful while waiting. A running/idle
-      // status without a new preview must not keep "运行命令 · …" around.
-      session.agentDetail = undefined;
-    }
-    if (summary.lastActivity !== undefined) session.agentLastActivity = summary.lastActivity ?? undefined;
-    if (summary.usage !== undefined) session.agentUsage = summary.usage ?? undefined;
-    session.lastActivity = Date.now();
-    const changed =
-      prev.status !== session.agentStatus ||
-      prev.provider !== session.agentProvider ||
-      prev.conversationId !== session.agentConversationId ||
-      prev.title !== session.agentTitle ||
-      prev.detail !== session.agentDetail;
-    if (changed) this.emitPresence(session);
-    return changed;
-  }
-
-  bufferAgentEnvelope(sessionId: string, envelope: Envelope): void {
-    const session = this.sessions.get(sessionId);
-    if (!session) return;
-    if (envelope.type === "agent.v2.snapshot") {
-      session.lastAgentSnapshot = envelope;
-      session.agentReplay = [];
-      return;
-    }
-    session.agentReplay.push(envelope);
-    if (session.agentReplay.length > AGENT_REPLAY_CAPACITY) {
-      session.agentReplay.splice(0, session.agentReplay.length - AGENT_REPLAY_CAPACITY);
-    }
-  }
-
-  getAgentReplay(sessionId: string): Envelope[] {
-    const session = this.sessions.get(sessionId);
-    if (!session) return [];
-    return [
-      ...(session.lastAgentSnapshot ? [session.lastAgentSnapshot] : []),
-      ...session.agentReplay,
-    ];
-  }
-
-  setMetadata(
-    sessionId: string,
-    provider?: string,
-    machineId?: string,
-    hostname?: string,
-    platform?: string,
-    cwd?: string,
-    projectName?: string,
-  ): void {
-    const session = this.sessions.get(sessionId);
-    if (!session) return;
-    if (provider) session.provider = provider;
-    if (machineId) session.machineId = machineId;
-    if (hostname) session.hostname = hostname;
-    if (platform) session.platform = platform;
-    if (cwd) session.cwd = cwd;
-    if (projectName) session.projectName = projectName;
-  }
-
-  private maybeDelete(sessionId: string): void {
-    const session = this.sessions.get(sessionId);
-    if (!session) return;
-    if (!session.host && session.clients.size === 0) {
-      this.sessions.delete(sessionId);
-    }
-  }
-
-  private cleanup(): void {
-    const now = Date.now();
-    for (const [id, session] of this.sessions) {
-      // Remove sessions where host disconnected and window expired
-      if (
-        session.state === "host_disconnected" &&
-        session.hostDisconnectedAt &&
-        now - session.hostDisconnectedAt > HOST_RECONNECT_WINDOW
-      ) {
-        session.state = "terminated";
-      }
-      // Clean up terminated sessions with no connections
-      if (
-        session.state === "terminated" &&
-        !session.host &&
-        session.clients.size === 0
-      ) {
-        this.sessions.delete(id);
-      }
-    }
-  }
-
-  destroy(): void {
-    clearInterval(this.cleanupTimer);
-  }
-}