@lzdi/pty-remote-protocol 0.1.3

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@lzdi/pty-remote-protocol",
+  "version": "0.1.3",
+  "private": false,
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/234687552/pty-remote"
+  },
+  "engines": {
+    "node": ">=23.0.0"
+  },
+  "exports": {
+    "./protocol": "./src/protocol.ts",
+    "./protocol.ts": "./src/protocol.ts",
+    "./terminal-frame": "./src/terminal-frame.ts",
+    "./terminal-frame.ts": "./src/terminal-frame.ts",
+    "./runtime-types": "./src/runtime-types.ts",
+    "./runtime-types.ts": "./src/runtime-types.ts"
+  },
+  "files": [
+    "src"
+  ]
+}

package/src/protocol.ts

@@ -0,0 +1,267 @@
+import type { ChatMessage, CliDescriptor, ProviderId, RuntimeSnapshot } from './runtime-types.ts';
+import type { TerminalFramePatch, TerminalFrameSnapshot } from './terminal-frame.ts';
+
+export interface CliRegisterPayload {
+  cliId?: string;
+  label?: string;
+  cwd: string;
+  supportedProviders: ProviderId[];
+  runtimes: Partial<Record<ProviderId, ProviderRuntimeRegistration>>;
+  runtimeBackend: string;
+}
+
+export interface ProviderRuntimeRegistration {
+  cwd: string;
+  sessionId: string | null;
+  conversationKey: string | null;
+}
+
+export interface CliRegisterResult {
+  ok: boolean;
+  cliId: string;
+  error?: string;
+  errorCode?: 'conflict';
+}
+
+export interface ProjectSessionSummary {
+  providerId: ProviderId;
+  sessionId: string;
+  cwd: string;
+  title: string;
+  preview: string;
+  updatedAt: string;
+  messageCount: number;
+}
+
+export type ManagedPtyLifecycle = 'attached' | 'detached' | 'exited' | 'error';
+
+export interface ManagedPtyHandleSummary {
+  conversationKey: string;
+  sessionId: string | null;
+  cwd: string;
+  label: string;
+  lifecycle: ManagedPtyLifecycle;
+  hasPty: boolean;
+  lastActivityAt: number | null;
+}
+
+export type CliCommandName =
+  | 'send-message'
+  | 'list-slash-commands'
+  | 'upload-attachment'
+  | 'delete-attachment'
+  | 'stop-message'
+  | 'reset-session'
+  | 'get-runtime-snapshot'
+  | 'get-older-messages'
+  | 'pick-project-directory'
+  | 'list-project-conversations'
+  | 'list-managed-pty-handles'
+  | 'select-conversation'
+  | 'cleanup-project'
+  | 'cleanup-conversation';
+
+export interface CliCommandPayloadMap {
+  'send-message': { content: string };
+  'list-slash-commands': Record<string, never>;
+  'upload-attachment': {
+    contentBase64: string;
+    conversationKey: string | null;
+    cwd: string;
+    filename: string;
+    mimeType: string;
+    sessionId: string | null;
+    size: number;
+  };
+  'delete-attachment': {
+    attachmentId: string;
+  };
+  'stop-message': Record<string, never>;
+  'reset-session': Record<string, never>;
+  'get-runtime-snapshot': Record<string, never>;
+  'get-older-messages': {
+    beforeMessageId?: string;
+    maxMessages?: number;
+  };
+  'pick-project-directory': Record<string, never>;
+  'list-project-conversations': {
+    cwd: string;
+    maxSessions?: number;
+  };
+  'list-managed-pty-handles': Record<string, never>;
+  'select-conversation': {
+    cwd: string;
+    conversationKey: string;
+    sessionId: string | null;
+    clientRequestId?: string | null;
+  };
+  'cleanup-project': {
+    cwd: string;
+  };
+  'cleanup-conversation': {
+    cwd: string;
+    conversationKey: string;
+    sessionId: string | null;
+  };
+}
+
+export interface GetRuntimeSnapshotResultPayload {
+  snapshot: RuntimeSnapshot;
+}
+
+export interface GetOlderMessagesResultPayload {
+  messages: ChatMessage[];
+  providerId: ProviderId | null;
+  conversationKey: string | null;
+  sessionId: string | null;
+  hasOlderMessages: boolean;
+}
+
+export interface PickProjectDirectoryResultPayload {
+  cwd: string;
+  label: string;
+}
+
+export interface ListProjectSessionsResultPayload {
+  providerId: ProviderId;
+  cwd: string;
+  label: string;
+  sessions: ProjectSessionSummary[];
+}
+
+export interface ListManagedPtyHandlesResultPayload {
+  providerId: ProviderId;
+  handles: ManagedPtyHandleSummary[];
+}
+
+export interface SelectConversationResultPayload {
+  providerId: ProviderId;
+  cwd: string;
+  label: string;
+  conversationKey: string;
+  sessionId: string | null;
+  clientRequestId?: string | null;
+}
+
+export interface UploadAttachmentResultPayload {
+  attachmentId: string;
+  filename: string;
+  mimeType: string;
+  path: string;
+  size: number;
+}
+
+export interface ListSlashCommandsResultPayload {
+  providerId: ProviderId;
+  commands: string[];
+}
+
+export interface CliCommandResultPayloadMap {
+  'send-message': null;
+  'list-slash-commands': ListSlashCommandsResultPayload;
+  'upload-attachment': UploadAttachmentResultPayload;
+  'delete-attachment': null;
+  'stop-message': null;
+  'reset-session': null;
+  'get-runtime-snapshot': GetRuntimeSnapshotResultPayload;
+  'get-older-messages': GetOlderMessagesResultPayload;
+  'pick-project-directory': PickProjectDirectoryResultPayload;
+  'list-project-conversations': ListProjectSessionsResultPayload;
+  'list-managed-pty-handles': ListManagedPtyHandlesResultPayload;
+  'select-conversation': SelectConversationResultPayload;
+  'cleanup-project': null;
+  'cleanup-conversation': null;
+}
+
+export interface CliCommandEnvelope<TName extends CliCommandName = CliCommandName> {
+  requestId: string;
+  targetProviderId?: ProviderId | null;
+  name: TName;
+  payload: CliCommandPayloadMap[TName];
+}
+
+export interface CliCommandResult<TName extends CliCommandName = CliCommandName> {
+  ok: boolean;
+  error?: string;
+  payload?: CliCommandResultPayloadMap[TName];
+}
+
+export interface TerminalFramePatchPayload {
+  cliId: string;
+  providerId: ProviderId;
+  conversationKey: string | null;
+  patch: TerminalFramePatch;
+}
+
+export interface TerminalSessionEvictedPayload {
+  cliId: string;
+  providerId: ProviderId;
+  conversationKey: string | null;
+  reason: string;
+  sessionId: string;
+}
+
+export interface RuntimeSubscriptionPayload {
+  targetCliId: string | null;
+  targetProviderId: ProviderId | null;
+  conversationKey: string | null;
+  sessionId: string | null;
+  lastSeq?: number | null;
+  terminalEnabled?: boolean | null;
+}
+
+export interface TerminalFrameSyncRequestPayload {
+  targetCliId: string | null;
+  targetProviderId: ProviderId | null;
+  lastRevision: number | null;
+  sessionId: string | null;
+}
+
+export interface TerminalResizePayload {
+  targetCliId: string | null;
+  targetProviderId: ProviderId | null;
+  cols: number;
+  rows: number;
+}
+
+export interface TerminalFrameSyncResultPayload {
+  ok: boolean;
+  error?: string;
+  providerId: ProviderId | null;
+  sessionId: string | null;
+  mode?: 'patches' | 'snapshot';
+  snapshot?: TerminalFrameSnapshot;
+  patches?: TerminalFramePatch[];
+}
+
+export interface RuntimeSnapshotPayload {
+  cliId: string;
+  providerId: ProviderId;
+  snapshot: RuntimeSnapshot;
+}
+
+export interface MessagesUpsertPayload {
+  cliId: string;
+  providerId: ProviderId | null;
+  conversationKey: string | null;
+  sessionId: string | null;
+  upserts: ChatMessage[];
+  recentMessageIds: string[];
+  hasOlderMessages: boolean;
+  seq?: number;
+}
+
+export interface WebInitPayload {
+  clis: CliDescriptor[];
+}
+
+export interface CliStatusPayload {
+  clis: CliDescriptor[];
+}
+
+export interface WebCommandEnvelope<TName extends CliCommandName = CliCommandName> {
+  targetCliId: string | null;
+  targetProviderId?: ProviderId | null;
+  name: TName;
+  payload: CliCommandPayloadMap[TName];
+}

package/src/runtime-types.ts

@@ -0,0 +1,87 @@
+export type Role = 'user' | 'assistant';
+export type MessageStatus = 'complete' | 'streaming' | 'error';
+export type RuntimeStatus = 'idle' | 'starting' | 'running' | 'error';
+export type ProviderId = 'claude' | 'codex';
+
+export const PROVIDER_LABELS: Record<ProviderId, string> = {
+  claude: 'claude',
+  codex: 'codex'
+};
+
+export const PROVIDER_ORDER: ProviderId[] = ['claude', 'codex'];
+
+export const BUILTIN_SLASH_COMMANDS: Record<ProviderId, string[]> = {
+  claude: ['clear', 'compact', 'context', 'cost', 'doctor', 'help', 'plan', 'stats', 'status'],
+  codex: ['review', 'new', 'compat', 'undo', 'diff', 'status']
+};
+
+export interface TextChatMessageBlock {
+  id: string;
+  type: 'text';
+  text: string;
+}
+
+export interface ToolUseChatMessageBlock {
+  id: string;
+  type: 'tool_use';
+  toolCallId?: string;
+  toolName: string;
+  input: string;
+}
+
+export interface ToolResultChatMessageBlock {
+  id: string;
+  type: 'tool_result';
+  toolCallId?: string;
+  content: string;
+  isError: boolean;
+}
+
+export type ChatMessageBlock = TextChatMessageBlock | ToolUseChatMessageBlock | ToolResultChatMessageBlock;
+
+export interface ChatAttachment {
+  attachmentId: string;
+  filename: string;
+  mimeType: string;
+  path: string;
+  size: number;
+  previewUrl?: string;
+}
+
+export interface ChatMessage {
+  id: string;
+  role: Role;
+  blocks: ChatMessageBlock[];
+  attachments?: ChatAttachment[];
+  status: MessageStatus;
+  createdAt: string;
+}
+
+export interface RuntimeSnapshot {
+  providerId: ProviderId | null;
+  conversationKey: string | null;
+  status: RuntimeStatus;
+  sessionId: string | null;
+  messages: ChatMessage[];
+  hasOlderMessages: boolean;
+  lastError: string | null;
+}
+
+export interface CliProviderRuntimeDescriptor {
+  cwd: string;
+  conversationKey: string | null;
+  status: RuntimeStatus;
+  sessionId: string | null;
+}
+
+export interface CliDescriptor {
+  cliId: string;
+  label: string;
+  cwd: string;
+  supportedProviders: ProviderId[];
+  runtimes: Partial<Record<ProviderId, CliProviderRuntimeDescriptor>>;
+  runtimeBackend: string;
+  connected: boolean;
+  connectedAt: string | null;
+  lastSeenAt: string | null;
+}

package/src/terminal-frame.ts

@@ -0,0 +1,295 @@
+export interface TerminalFrameRun {
+  style: string;
+  text: string;
+}
+
+export interface TerminalFrameLine {
+  wrapped: boolean;
+  runs: TerminalFrameRun[];
+}
+
+export interface TerminalFrameSnapshot {
+  sessionId: string | null;
+  revision: number;
+  cols: number;
+  rows: number;
+  tailStart: number;
+  cursorX: number;
+  cursorY: number;
+  viewportY: number;
+  baseY: number;
+  totalLines: number;
+  lines: TerminalFrameLine[];
+}
+
+export type TerminalColorMode = 'default' | 'palette' | 'rgb';
+
+export interface TerminalFrameStyle {
+  flags: number;
+  fgMode: TerminalColorMode;
+  fg: number;
+  bgMode: TerminalColorMode;
+  bg: number;
+}
+
+export type TerminalFramePatchOp =
+  | {
+      type: 'reset';
+      snapshot: TerminalFrameSnapshot;
+    }
+  | {
+      type: 'trimHead';
+      count: number;
+    }
+  | {
+      type: 'spliceLines';
+      start: number;
+      deleteCount: number;
+      lines: TerminalFrameLine[];
+    }
+  | {
+      type: 'meta';
+      cols: number;
+      rows: number;
+      tailStart: number;
+      cursorX: number;
+      cursorY: number;
+      viewportY: number;
+      baseY: number;
+      totalLines: number;
+    };
+
+export interface TerminalFramePatch {
+  sessionId: string | null;
+  baseRevision: number;
+  revision: number;
+  ops: TerminalFramePatchOp[];
+}
+
+const DEFAULT_STYLE: TerminalFrameStyle = {
+  flags: 0,
+  fgMode: 'default',
+  fg: 0,
+  bgMode: 'default',
+  bg: 0
+};
+
+const ANSI_16_COLOR_PALETTE = [
+  '#000000',
+  '#cd3131',
+  '#0dbc79',
+  '#949800',
+  '#2472c8',
+  '#bc3fbc',
+  '#11a8cd',
+  '#e5e5e5',
+  '#666666',
+  '#f14c4c',
+  '#23d18b',
+  '#f5f543',
+  '#3b8eea',
+  '#d670d6',
+  '#29b8db',
+  '#ffffff'
+] as const;
+
+function cloneTerminalFrameRun(run: TerminalFrameRun): TerminalFrameRun {
+  return {
+    style: run.style,
+    text: run.text
+  };
+}
+
+function cloneTerminalFrameLine(line: TerminalFrameLine): TerminalFrameLine {
+  return {
+    wrapped: line.wrapped,
+    runs: line.runs.map(cloneTerminalFrameRun)
+  };
+}
+
+export function cloneTerminalFrameSnapshot(snapshot: TerminalFrameSnapshot): TerminalFrameSnapshot {
+  return {
+    sessionId: snapshot.sessionId,
+    revision: snapshot.revision,
+    cols: snapshot.cols,
+    rows: snapshot.rows,
+    tailStart: snapshot.tailStart,
+    cursorX: snapshot.cursorX,
+    cursorY: snapshot.cursorY,
+    viewportY: snapshot.viewportY,
+    baseY: snapshot.baseY,
+    totalLines: snapshot.totalLines,
+    lines: snapshot.lines.map(cloneTerminalFrameLine)
+  };
+}
+
+export function createEmptyTerminalFrameSnapshot(
+  sessionId: string | null = null,
+  revision = 0,
+  cols = 0,
+  rows = 0
+): TerminalFrameSnapshot {
+  return {
+    sessionId,
+    revision,
+    cols,
+    rows,
+    tailStart: 0,
+    cursorX: 0,
+    cursorY: 0,
+    viewportY: 0,
+    baseY: 0,
+    totalLines: 0,
+    lines: []
+  };
+}
+
+export function terminalFrameLineEquals(left: TerminalFrameLine | undefined, right: TerminalFrameLine | undefined): boolean {
+  if (!left || !right) {
+    return false;
+  }
+  if (left.wrapped !== right.wrapped || left.runs.length !== right.runs.length) {
+    return false;
+  }
+  for (let index = 0; index < left.runs.length; index += 1) {
+    const leftRun = left.runs[index];
+    const rightRun = right.runs[index];
+    if (!leftRun || !rightRun || leftRun.style !== rightRun.style || leftRun.text !== rightRun.text) {
+      return false;
+    }
+  }
+  return true;
+}
+
+export function encodeTerminalFrameStyle(style: TerminalFrameStyle): string {
+  if (
+    style.flags === DEFAULT_STYLE.flags &&
+    style.fgMode === DEFAULT_STYLE.fgMode &&
+    style.fg === DEFAULT_STYLE.fg &&
+    style.bgMode === DEFAULT_STYLE.bgMode &&
+    style.bg === DEFAULT_STYLE.bg
+  ) {
+    return '';
+  }
+
+  return `${style.flags};${style.fgMode}:${style.fg};${style.bgMode}:${style.bg}`;
+}
+
+export function decodeTerminalFrameStyle(value: string): TerminalFrameStyle {
+  if (!value) {
+    return DEFAULT_STYLE;
+  }
+
+  const [flagsPart = '0', fgPart = 'default:0', bgPart = 'default:0'] = value.split(';');
+  const [fgModePart = 'default', fgValuePart = '0'] = fgPart.split(':');
+  const [bgModePart = 'default', bgValuePart = '0'] = bgPart.split(':');
+  const fgMode = normalizeColorMode(fgModePart);
+  const bgMode = normalizeColorMode(bgModePart);
+
+  return {
+    flags: Number.parseInt(flagsPart, 10) || 0,
+    fgMode,
+    fg: Number.parseInt(fgValuePart, 10) || 0,
+    bgMode,
+    bg: Number.parseInt(bgValuePart, 10) || 0
+  };
+}
+
+function normalizeColorMode(value: string): TerminalColorMode {
+  if (value === 'palette' || value === 'rgb') {
+    return value;
+  }
+  return 'default';
+}
+
+function rgbNumberToHex(value: number): string {
+  const normalized = Math.max(0, Math.min(value, 0xffffff));
+  return `#${normalized.toString(16).padStart(6, '0')}`;
+}
+
+export function terminalPaletteIndexToCss(index: number): string {
+  if (index >= 0 && index < ANSI_16_COLOR_PALETTE.length) {
+    return ANSI_16_COLOR_PALETTE[index] ?? ANSI_16_COLOR_PALETTE[0];
+  }
+
+  if (index >= 16 && index <= 231) {
+    const cubeIndex = index - 16;
+    const redIndex = Math.floor(cubeIndex / 36);
+    const greenIndex = Math.floor((cubeIndex % 36) / 6);
+    const blueIndex = cubeIndex % 6;
+    const component = [0, 95, 135, 175, 215, 255];
+    return rgbNumberToHex(
+      ((component[redIndex] ?? 0) << 16) |
+        ((component[greenIndex] ?? 0) << 8) |
+        (component[blueIndex] ?? 0)
+    );
+  }
+
+  if (index >= 232 && index <= 255) {
+    const value = 8 + (index - 232) * 10;
+    return rgbNumberToHex((value << 16) | (value << 8) | value);
+  }
+
+  return ANSI_16_COLOR_PALETTE[0];
+}
+
+export function resolveTerminalFrameColor(mode: TerminalColorMode, value: number, fallback: string): string {
+  if (mode === 'rgb') {
+    return rgbNumberToHex(value);
+  }
+  if (mode === 'palette') {
+    return terminalPaletteIndexToCss(value);
+  }
+  return fallback;
+}
+
+export function applyTerminalFramePatch(
+  currentSnapshot: TerminalFrameSnapshot | null,
+  patch: TerminalFramePatch
+): TerminalFrameSnapshot {
+  let nextSnapshot = currentSnapshot ? cloneTerminalFrameSnapshot(currentSnapshot) : createEmptyTerminalFrameSnapshot();
+
+  for (const op of patch.ops) {
+    if (op.type === 'reset') {
+      nextSnapshot = cloneTerminalFrameSnapshot(op.snapshot);
+      continue;
+    }
+
+    if (op.type === 'spliceLines') {
+      const nextLines = nextSnapshot.lines.slice();
+      nextLines.splice(op.start, op.deleteCount, ...op.lines.map(cloneTerminalFrameLine));
+      nextSnapshot = {
+        ...nextSnapshot,
+        lines: nextLines
+      };
+      continue;
+    }
+
+    if (op.type === 'trimHead') {
+      nextSnapshot = {
+        ...nextSnapshot,
+        lines: nextSnapshot.lines.slice(op.count)
+      };
+      continue;
+    }
+
+    nextSnapshot = {
+      ...nextSnapshot,
+      cols: op.cols,
+      rows: op.rows,
+      tailStart: op.tailStart,
+      cursorX: op.cursorX,
+      cursorY: op.cursorY,
+      viewportY: op.viewportY,
+      baseY: op.baseY,
+      totalLines: op.totalLines
+    };
+  }
+
+  return {
+    ...nextSnapshot,
+    sessionId: patch.sessionId,
+    revision: patch.revision,
+    totalLines: nextSnapshot.lines.length
+  };
+}