@lzdi/pty-remote-cli 0.1.3

package/src/providers/codex-pty.ts

@@ -0,0 +1,144 @@
+import { spawn as spawnPty, type IPty } from 'node-pty';
+
+export interface CodexPtySession {
+  pty: IPty;
+  recentOutput: string;
+  startupUpdatePromptHandled: boolean;
+}
+
+export type CodexPtyLifecycle = 'not_ready' | 'idle' | 'running';
+
+interface StartCodexPtySessionOptions {
+  codexBin: string;
+  cols: number;
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  resumeSessionId?: string | null;
+  rows: number;
+  onData: (chunk: string) => void;
+  onExit: () => void;
+}
+
+export function createCodexLaunchConfig(
+  codexBin: string,
+  cwd: string,
+  resumeSessionId?: string | null
+): {
+  args: string[];
+  command: string;
+} {
+  const args = ['--no-alt-screen', '-C', cwd];
+  if (resumeSessionId) {
+    args.push('resume', resumeSessionId);
+  }
+
+  return {
+    command: codexBin,
+    args
+  };
+}
+
+export function startCodexPtySession(options: StartCodexPtySessionOptions): CodexPtySession {
+  const launch = createCodexLaunchConfig(options.codexBin, options.cwd, options.resumeSessionId);
+  const pty = spawnPty(launch.command, launch.args, {
+    cols: options.cols,
+    rows: options.rows,
+    cwd: options.cwd,
+    env: options.env,
+    name: 'xterm-256color'
+  });
+
+  const session: CodexPtySession = {
+    pty,
+    recentOutput: '',
+    startupUpdatePromptHandled: false
+  };
+
+  pty.onData((chunk) => {
+    options.onData(chunk);
+  });
+
+  pty.onExit(() => {
+    options.onExit();
+  });
+
+  return session;
+}
+
+export function stopCodexPtySession(session: CodexPtySession | null): void {
+  if (!session) {
+    return;
+  }
+
+  try {
+    session.pty.kill();
+  } catch {
+    // ignore
+  }
+}
+
+export function resizeCodexPtySession(session: CodexPtySession | null, cols: number, rows: number): void {
+  if (!session) {
+    return;
+  }
+
+  try {
+    session.pty.resize(cols, rows);
+  } catch {
+    // ignore resize failures during session transitions
+  }
+}
+
+export function appendRecentOutput(session: CodexPtySession, chunk: string, maxChars: number): string {
+  session.recentOutput = `${session.recentOutput}${chunk}`.slice(-maxChars);
+  return session.recentOutput;
+}
+
+function normalizeOutput(text: string): string {
+  return text.replace(/\r/g, '\n');
+}
+
+function tailOutput(text: string, maxChars = 8_000): string {
+  return normalizeOutput(text).slice(-maxChars);
+}
+
+const RUNNING_LINE_PATTERN = /(^|\n)\s*[•◦]\s+[^\n]*esc to interrupt[^\n]*$/gimu;
+const PROMPT_LINE_PATTERN = /(^|\n)\s*[›>]\s*[^\n]*$/gimu;
+const DIRECTORY_TRUST_PROMPT_PATTERN = /Do you trust the contents of this directory\?/i;
+const UPDATE_AVAILABLE_PROMPT_PATTERN = /Update\s+available!?/i;
+const UPDATE_SKIP_OPTION_PATTERN = /(^|\n)\s*2\.\s*Skip(?:\s|$)/im;
+const STARTER_PROMPT_PATTERN =
+  /Use \/skills to list available skills|Improve documentation in @filename|To get started, describe a task|Implement\s+\{feature\}|Implement\s+<feature>/i;
+
+export function getCodexPtyLifecycle(output: string): CodexPtyLifecycle {
+  const tail = tailOutput(output);
+  const hasRunningLine = RUNNING_LINE_PATTERN.test(tail);
+  const hasPromptLine = PROMPT_LINE_PATTERN.test(tail);
+
+  if (hasRunningLine) {
+    return 'running';
+  }
+
+  if (hasPromptLine) {
+    return 'idle';
+  }
+
+  return 'not_ready';
+}
+
+export function looksReadyForInput(output: string): boolean {
+  return getCodexPtyLifecycle(output) === 'idle';
+}
+
+export function looksLikeDirectoryTrustPrompt(output: string): boolean {
+  return DIRECTORY_TRUST_PROMPT_PATTERN.test(tailOutput(output));
+}
+
+export function looksLikeUpdatePrompt(output: string): boolean {
+  const tail = tailOutput(output);
+  return UPDATE_AVAILABLE_PROMPT_PATTERN.test(tail) && UPDATE_SKIP_OPTION_PATTERN.test(tail);
+}
+
+export function showsStarterPrompt(output: string): boolean {
+  return STARTER_PROMPT_PATTERN.test(tailOutput(output));
+}

package/src/providers/codex-resume-session.ts

@@ -0,0 +1,253 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+
+import { resolveCodexHistoryPaths, type CodexHistoryOptions } from './codex-history.ts';
+
+const execFileAsync = promisify(execFile);
+const TEMPLATE_FILE_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../codex_template.jsonl');
+const PLACEHOLDER_PATTERN = /^\{\{([a-z0-9_.]+)\}\}$/i;
+
+interface CodexResumeSessionOptions extends CodexHistoryOptions {
+  codexBin?: string;
+}
+
+interface SessionMetaTemplateRecord {
+  timestamp?: string;
+  type: 'session_meta';
+  payload: Record<string, unknown>;
+}
+
+interface GitMetadataPayload {
+  commit_hash?: string;
+  branch?: string;
+  repository_url?: string;
+}
+
+export interface PreparedCodexResumeSession {
+  filePath: string;
+  sessionId: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function pad(value: number): string {
+  return String(value).padStart(2, '0');
+}
+
+function formatRolloutFileTimestamp(date: Date): string {
+  return [
+    date.getFullYear(),
+    pad(date.getMonth() + 1),
+    pad(date.getDate())
+  ].join('-') + `T${pad(date.getHours())}-${pad(date.getMinutes())}-${pad(date.getSeconds())}`;
+}
+
+function createRolloutDirectory(rootPath: string, date: Date): string {
+  return path.join(
+    rootPath,
+    String(date.getFullYear()),
+    pad(date.getMonth() + 1),
+    pad(date.getDate())
+  );
+}
+
+async function readTemplateRecord(): Promise<SessionMetaTemplateRecord> {
+  const raw = await fs.readFile(TEMPLATE_FILE_PATH, 'utf8');
+  const firstLine = raw.split('\n', 1)[0]?.trim();
+  if (!firstLine) {
+    throw new Error(`Codex template file is empty: ${TEMPLATE_FILE_PATH}`);
+  }
+
+  const parsed = JSON.parse(firstLine) as unknown;
+  if (!isRecord(parsed) || parsed.type !== 'session_meta' || !isRecord(parsed.payload)) {
+    throw new Error(`Codex template file must start with session_meta: ${TEMPLATE_FILE_PATH}`);
+  }
+
+  return {
+    ...parsed,
+    type: 'session_meta',
+    payload: parsed.payload
+  } as SessionMetaTemplateRecord;
+}
+
+function replaceTemplatePlaceholders(value: unknown, variables: Readonly<Record<string, string>>): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => replaceTemplatePlaceholders(item, variables));
+  }
+
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entryValue]) => [key, replaceTemplatePlaceholders(entryValue, variables)])
+    );
+  }
+
+  if (typeof value !== 'string') {
+    return value;
+  }
+
+  const match = value.match(PLACEHOLDER_PATTERN);
+  if (!match) {
+    return value;
+  }
+
+  const variableName = match[1];
+  if (!(variableName in variables)) {
+    throw new Error(`Unknown Codex template placeholder: ${variableName}`);
+  }
+
+  return variables[variableName];
+}
+
+function findUnresolvedPlaceholder(value: unknown): string | null {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const unresolved = findUnresolvedPlaceholder(item);
+      if (unresolved) {
+        return unresolved;
+      }
+    }
+    return null;
+  }
+
+  if (isRecord(value)) {
+    for (const entryValue of Object.values(value)) {
+      const unresolved = findUnresolvedPlaceholder(entryValue);
+      if (unresolved) {
+        return unresolved;
+      }
+    }
+    return null;
+  }
+
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const match = value.match(PLACEHOLDER_PATTERN);
+  return match ? match[0] : null;
+}
+
+async function readGitMetadata(cwd: string): Promise<GitMetadataPayload | null> {
+  try {
+    const insideWorkTree = await execFileAsync('git', ['-C', cwd, 'rev-parse', '--is-inside-work-tree'], {
+      encoding: 'utf8'
+    });
+    if (insideWorkTree.stdout.trim() !== 'true') {
+      return null;
+    }
+  } catch {
+    return null;
+  }
+
+  const metadata: GitMetadataPayload = {};
+
+  try {
+    const result = await execFileAsync('git', ['-C', cwd, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
+    const commitHash = result.stdout.trim();
+    if (commitHash) {
+      metadata.commit_hash = commitHash;
+    }
+  } catch {
+    // ignore
+  }
+
+  try {
+    const result = await execFileAsync('git', ['-C', cwd, 'branch', '--show-current'], { encoding: 'utf8' });
+    const branch = result.stdout.trim();
+    if (branch) {
+      metadata.branch = branch;
+    }
+  } catch {
+    // ignore
+  }
+
+  try {
+    const result = await execFileAsync('git', ['-C', cwd, 'config', '--get', 'remote.origin.url'], { encoding: 'utf8' });
+    const repositoryUrl = result.stdout.trim();
+    if (repositoryUrl) {
+      metadata.repository_url = repositoryUrl;
+    }
+  } catch {
+    // ignore
+  }
+
+  return Object.keys(metadata).length > 0 ? metadata : null;
+}
+
+async function readCodexCliVersion(codexBin = 'codex'): Promise<string | null> {
+  try {
+    const result = await execFileAsync(codexBin, ['--version'], { encoding: 'utf8' });
+    const version = result.stdout.trim();
+    return version || null;
+  } catch {
+    return null;
+  }
+}
+
+function buildSessionMetaRecord(
+  template: SessionMetaTemplateRecord,
+  templateVariables: Readonly<Record<string, string>>,
+  gitMetadata: GitMetadataPayload | null
+): SessionMetaTemplateRecord {
+  const rendered = replaceTemplatePlaceholders(template, templateVariables) as SessionMetaTemplateRecord;
+  const unresolved = findUnresolvedPlaceholder(rendered);
+  if (unresolved) {
+    throw new Error(`Unresolved Codex template placeholder: ${unresolved}`);
+  }
+
+  const payload = structuredClone(rendered.payload);
+  payload.source ??= 'cli';
+  payload.originator ??= 'codex_cli_rs';
+
+  if (gitMetadata) {
+    payload.git = gitMetadata;
+  } else {
+    delete payload.git;
+  }
+
+  return {
+    ...rendered,
+    type: 'session_meta',
+    payload
+  };
+}
+
+export async function prepareCodexResumeSession(
+  cwd: string,
+  options: CodexResumeSessionOptions = {}
+): Promise<PreparedCodexResumeSession> {
+  const resolvedCwd = path.resolve(cwd);
+  const { sessionsRootPath } = resolveCodexHistoryPaths(options);
+  const template = await readTemplateRecord();
+  const sessionId = randomUUID();
+  const now = new Date();
+  const timestamp = now.toISOString();
+  const cliVersion = (await readCodexCliVersion(options.codexBin)) ?? 'unknown';
+  const gitMetadata = await readGitMetadata(resolvedCwd);
+  const nextRecord = buildSessionMetaRecord(
+    template,
+    {
+      cli_version: cliVersion,
+      cwd: resolvedCwd,
+      session_id: sessionId,
+      timestamp
+    },
+    gitMetadata
+  );
+  const rolloutDir = createRolloutDirectory(sessionsRootPath, now);
+  const filePath = path.join(rolloutDir, `rollout-${formatRolloutFileTimestamp(now)}-${sessionId}.jsonl`);
+
+  await fs.mkdir(rolloutDir, { recursive: true });
+  await fs.copyFile(TEMPLATE_FILE_PATH, filePath);
+  await fs.writeFile(filePath, `${JSON.stringify(nextRecord)}\n`, 'utf8');
+  return {
+    filePath,
+    sessionId
+  };
+}

package/src/providers/codex.ts

@@ -0,0 +1,67 @@
+import type { ProjectSessionSummary } from '@lzdi/pty-remote-protocol/protocol.ts';
+
+import { listCodexRecentSessions } from './codex-history.ts';
+import { CodexManager, type CodexManagerOptions } from './codex-manager.ts';
+import type { ProviderRuntime, ProviderRuntimeCallbacks, ProviderRuntimeSelection } from './provider-runtime.ts';
+import { listProviderSlashCommands } from './slash-commands.ts';
+
+export type CodexProviderRuntimeOptions = CodexManagerOptions;
+
+export function createCodexProviderRuntime(
+  options: CodexProviderRuntimeOptions,
+  callbacks: ProviderRuntimeCallbacks
+): ProviderRuntime {
+  const manager = new CodexManager(options, callbacks);
+
+  return {
+    providerId: 'codex',
+    activateConversation(selection: ProviderRuntimeSelection) {
+      return manager.activateConversation(selection);
+    },
+    cleanupConversation(target) {
+      return manager.cleanupConversation(target);
+    },
+    cleanupProject(cwd: string) {
+      return manager.cleanupProject(cwd);
+    },
+    dispatchMessage(content: string) {
+      return manager.dispatchMessage(content);
+    },
+    getOlderMessages(beforeMessageId?: string, maxMessages?: number) {
+      return manager.getOlderMessages(beforeMessageId, maxMessages);
+    },
+    getRegistrationPayload() {
+      return manager.getRegistrationPayload();
+    },
+    getSnapshot() {
+      return manager.getSnapshot();
+    },
+    listSlashCommands() {
+      return listProviderSlashCommands('codex');
+    },
+    listProjectConversations(_projectRoot: string, maxSessions?: number): Promise<ProjectSessionSummary[]> {
+      return listCodexRecentSessions(maxSessions, options);
+    },
+    listManagedPtyHandles() {
+      return Promise.resolve(manager.listManagedPtyHandles());
+    },
+    primeActiveTerminalFrame() {
+      return manager.primeActiveTerminalFrame();
+    },
+    refreshActiveState() {
+      return manager.refreshActiveState();
+    },
+    resetActiveConversation() {
+      return manager.resetActiveThread();
+    },
+    shutdown() {
+      return manager.shutdown();
+    },
+    stopActiveRun() {
+      return manager.stopActiveRun();
+    },
+    updateTerminalSize(cols: number, rows: number) {
+      manager.updateTerminalSize(cols, rows);
+    }
+  };
+}

package/src/providers/provider-runtime.ts

@@ -0,0 +1,58 @@
+import type {
+  GetOlderMessagesResultPayload,
+  ManagedPtyHandleSummary,
+  ProviderRuntimeRegistration,
+  ProjectSessionSummary,
+  SelectConversationResultPayload,
+  TerminalFramePatchPayload
+} from '@lzdi/pty-remote-protocol/protocol.ts';
+import type { ProviderId, RuntimeSnapshot } from '@lzdi/pty-remote-protocol/runtime-types.ts';
+
+export interface ProviderRuntimeSelection {
+  cwd: string;
+  label: string;
+  sessionId: string | null;
+  conversationKey: string;
+}
+
+export interface ProviderRuntimeCallbacks {
+  emitMessagesUpsert(payload: {
+    providerId: ProviderId | null;
+    conversationKey: string | null;
+    sessionId: string | null;
+    upserts: RuntimeSnapshot['messages'];
+    recentMessageIds: string[];
+    hasOlderMessages: boolean;
+  }): void;
+  emitSnapshot(snapshot: RuntimeSnapshot): void;
+  emitTerminalFramePatch(payload: Omit<TerminalFramePatchPayload, 'cliId' | 'providerId'>): void;
+  emitTerminalSessionEvicted(payload: {
+    conversationKey: string | null;
+    reason: string;
+    sessionId: string;
+  }): void;
+}
+
+export interface ProviderRuntime {
+  readonly providerId: ProviderId;
+  activateConversation(selection: ProviderRuntimeSelection): Promise<SelectConversationResultPayload>;
+  cleanupConversation(target: {
+    cwd: string;
+    conversationKey: string;
+    sessionId: string | null;
+  }): Promise<void>;
+  cleanupProject(cwd: string): Promise<void>;
+  dispatchMessage(content: string): Promise<void>;
+  getOlderMessages(beforeMessageId?: string, maxMessages?: number): Promise<GetOlderMessagesResultPayload>;
+  getRegistrationPayload(): ProviderRuntimeRegistration;
+  getSnapshot(): RuntimeSnapshot;
+  listSlashCommands(): Promise<string[]>;
+  listProjectConversations(projectRoot: string, maxSessions?: number): Promise<ProjectSessionSummary[]>;
+  listManagedPtyHandles(): Promise<ManagedPtyHandleSummary[]>;
+  primeActiveTerminalFrame(): Promise<void>;
+  refreshActiveState(): Promise<void>;
+  resetActiveConversation(): Promise<void>;
+  shutdown(): Promise<void>;
+  stopActiveRun(): Promise<void>;
+  updateTerminalSize(cols: number, rows: number): void;
+}

package/src/providers/slash-commands.ts

@@ -0,0 +1,115 @@
+import { promises as fs } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+import { BUILTIN_SLASH_COMMANDS, type ProviderId } from '@lzdi/pty-remote-protocol/runtime-types.ts';
+
+interface InstalledPluginsFile {
+  version: number;
+  plugins: Record<string, Array<{
+    installPath: string;
+    lastUpdated: string;
+  }>>;
+}
+
+function getClaudeCommandsDir(): string {
+  const configDir = process.env.CLAUDE_CONFIG_DIR?.trim() || path.join(homedir(), '.claude');
+  return path.join(configDir, 'commands');
+}
+
+function getCodexPromptsDir(): string {
+  const codexHome = process.env.CODEX_HOME?.trim() || path.join(homedir(), '.codex');
+  return path.join(codexHome, 'prompts');
+}
+
+async function scanCommandNames(dir: string, segments: string[] = []): Promise<string[]> {
+  const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+  const discovered: string[] = [];
+
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') || entry.isSymbolicLink()) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      if (entry.name.includes(':')) {
+        continue;
+      }
+      discovered.push(...(await scanCommandNames(path.join(dir, entry.name), [...segments, entry.name])));
+      continue;
+    }
+
+    if (!entry.isFile() || !entry.name.endsWith('.md')) {
+      continue;
+    }
+
+    const baseName = entry.name.slice(0, -3);
+    if (!baseName || baseName.includes(':')) {
+      continue;
+    }
+
+    discovered.push([...segments, baseName].join(':'));
+  }
+
+  return discovered;
+}
+
+async function scanClaudePluginCommandNames(): Promise<string[]> {
+  const configDir = process.env.CLAUDE_CONFIG_DIR?.trim() || path.join(homedir(), '.claude');
+  const installedPluginsPath = path.join(configDir, 'plugins', 'installed_plugins.json');
+
+  try {
+    const content = await fs.readFile(installedPluginsPath, 'utf8');
+    const installedPlugins = JSON.parse(content) as InstalledPluginsFile;
+    const discovered: string[] = [];
+
+    for (const [pluginKey, installations] of Object.entries(installedPlugins.plugins ?? {})) {
+      if (installations.length === 0) {
+        continue;
+      }
+
+      const latestInstallation = [...installations].sort((left, right) => {
+        return new Date(right.lastUpdated).getTime() - new Date(left.lastUpdated).getTime();
+      })[0];
+      if (!latestInstallation?.installPath) {
+        continue;
+      }
+
+      const lastAtIndex = pluginKey.lastIndexOf('@');
+      const pluginName = lastAtIndex > 0 ? pluginKey.slice(0, lastAtIndex) : pluginKey;
+      const names = await scanCommandNames(path.join(latestInstallation.installPath, 'commands'));
+      for (const name of names) {
+        discovered.push(`${pluginName}:${name}`);
+      }
+    }
+
+    return discovered;
+  } catch {
+    return [];
+  }
+}
+
+function dedupeCommands(commandGroups: string[][]): string[] {
+  return [...new Set(commandGroups.flat().map((command) => command.trim()).filter(Boolean))].sort((left, right) =>
+    left.localeCompare(right)
+  );
+}
+
+export async function listProviderSlashCommands(providerId: ProviderId): Promise<string[]> {
+  const builtin = BUILTIN_SLASH_COMMANDS[providerId] ?? [];
+
+  if (providerId === 'claude') {
+    const [userCommands, pluginCommands] = await Promise.all([
+      scanCommandNames(getClaudeCommandsDir()),
+      scanClaudePluginCommandNames()
+    ]);
+    return dedupeCommands([builtin, pluginCommands, userCommands]);
+  }
+
+  if (providerId === 'codex') {
+    const userCommands = await scanCommandNames(getCodexPromptsDir());
+    return dedupeCommands([builtin, userCommands]);
+  }
+
+  return dedupeCommands([builtin]);
+}