@thevinci/web 1.0.0

package/server/lib/skills-catalog/install.js

@@ -0,0 +1,294 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { assertGitAvailable, looksLikeAuthError, runGit } from './git.js';
+import { parseSkillRepoSource } from './source.js';
+
+const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/;
+
+function normalizeUserSkillDir(userSkillDir) {
+  if (!userSkillDir) return null;
+  const legacySkillDir = path.join(os.homedir(), '.vinci', '.opencode', 'skill');
+  const pluralSkillDir = path.join(os.homedir(), '.vinci', '.opencode', 'skills');
+  if (userSkillDir === legacySkillDir) {
+    if (fs.existsSync(legacySkillDir) && !fs.existsSync(pluralSkillDir)) return legacySkillDir;
+    return pluralSkillDir;
+  }
+  return userSkillDir;
+}
+
+function validateSkillName(skillName) {
+  if (typeof skillName !== 'string') return false;
+  if (skillName.length < 1 || skillName.length > 64) return false;
+  return SKILL_NAME_PATTERN.test(skillName);
+}
+
+async function safeRm(dir) {
+  try {
+    await fs.promises.rm(dir, { recursive: true, force: true });
+  } catch {
+    // ignore
+  }
+}
+
+function toFsPath(repoDir, repoRelPosixPath) {
+  const parts = String(repoRelPosixPath || '')
+    .split('/')
+    .map((p) => p.trim())
+    .filter(Boolean);
+  return path.join(repoDir, ...parts);
+}
+
+async function ensureDir(dirPath) {
+  await fs.promises.mkdir(dirPath, { recursive: true });
+}
+
+async function copyDirectoryNoSymlinks(srcDir, dstDir) {
+  const srcReal = await fs.promises.realpath(srcDir);
+  await ensureDir(dstDir);
+
+  const walk = async (currentSrc, currentDst) => {
+    const entries = await fs.promises.readdir(currentSrc, { withFileTypes: true });
+    for (const entry of entries) {
+      const nextSrc = path.join(currentSrc, entry.name);
+      const nextDst = path.join(currentDst, entry.name);
+
+      const stat = await fs.promises.lstat(nextSrc);
+      if (stat.isSymbolicLink()) {
+        throw new Error('Symlinks are not supported in skills');
+      }
+
+      // Guard against traversal: ensure source is still under srcReal
+      const nextRealParent = await fs.promises.realpath(path.dirname(nextSrc));
+      if (!nextRealParent.startsWith(srcReal)) {
+        throw new Error('Invalid source path traversal detected');
+      }
+
+      if (stat.isDirectory()) {
+        await ensureDir(nextDst);
+        await walk(nextSrc, nextDst);
+        continue;
+      }
+
+      if (stat.isFile()) {
+        await ensureDir(path.dirname(nextDst));
+        await fs.promises.copyFile(nextSrc, nextDst);
+        try {
+          await fs.promises.chmod(nextDst, stat.mode & 0o777);
+        } catch {
+          // best-effort
+        }
+        continue;
+      }
+
+      // Skip other types (sockets, devices, etc.)
+    }
+  };
+
+  await walk(srcDir, dstDir);
+}
+
+async function cloneRepo({ cloneUrl, identity, tempDir }) {
+  const preferred = ['clone', '--depth', '1', '--filter=blob:none', '--no-checkout', cloneUrl, tempDir];
+  const fallback = ['clone', '--depth', '1', '--no-checkout', cloneUrl, tempDir];
+
+  const result = await runGit(preferred, { identity, timeoutMs: 90_000 });
+  if (result.ok) return { ok: true };
+
+  const fallbackResult = await runGit(fallback, { identity, timeoutMs: 90_000 });
+  if (fallbackResult.ok) return { ok: true };
+
+  return {
+    ok: false,
+    error: fallbackResult,
+  };
+}
+
+function getTargetSkillDir({ scope, targetSource, workingDirectory, userSkillDir, skillName }) {
+  const source = targetSource === 'agents' ? 'agents' : 'opencode';
+
+  if (scope === 'user') {
+    if (source === 'agents') {
+      return path.join(os.homedir(), '.agents', 'skills', skillName);
+    }
+    return path.join(userSkillDir, skillName);
+  }
+
+  if (!workingDirectory) {
+    throw new Error('workingDirectory is required for project installs');
+  }
+
+  if (source === 'agents') {
+    return path.join(workingDirectory, '.agents', 'skills', skillName);
+  }
+
+  return path.join(workingDirectory, '.opencode', 'skills', skillName);
+}
+
+export async function installSkillsFromRepository({
+  source,
+  subpath,
+  defaultSubpath,
+  identity,
+  scope,
+  targetSource,
+  workingDirectory,
+  userSkillDir,
+  selections,
+  conflictPolicy,
+  conflictDecisions,
+} = {}) {
+  const gitCheck = await assertGitAvailable();
+  if (!gitCheck.ok) {
+    return { ok: false, error: gitCheck.error };
+  }
+
+  const normalizedUserSkillDir = normalizeUserSkillDir(userSkillDir);
+  if (normalizedUserSkillDir) {
+    userSkillDir = normalizedUserSkillDir;
+  }
+
+  if (!userSkillDir) {
+    return { ok: false, error: { kind: 'unknown', message: 'userSkillDir is required' } };
+  }
+
+  if (scope !== 'user' && scope !== 'project') {
+    return { ok: false, error: { kind: 'invalidSource', message: 'Invalid scope' } };
+  }
+
+  if (targetSource !== undefined && targetSource !== 'opencode' && targetSource !== 'agents') {
+    return { ok: false, error: { kind: 'invalidSource', message: 'Invalid target source' } };
+  }
+
+  if (scope === 'project' && !workingDirectory) {
+    return { ok: false, error: { kind: 'invalidSource', message: 'Project installs require a directory parameter' } };
+  }
+
+  const parsed = parseSkillRepoSource(source, { subpath });
+  if (!parsed.ok) {
+    return { ok: false, error: parsed.error };
+  }
+
+  const effectiveSubpath = parsed.effectiveSubpath || (typeof defaultSubpath === 'string' && defaultSubpath.trim() ? defaultSubpath.trim() : null);
+  void effectiveSubpath;
+
+  const cloneUrl = identity?.sshKey ? parsed.cloneUrlSsh : parsed.cloneUrlHttps;
+
+  const requestedDirs = Array.isArray(selections) ? selections.map((s) => String(s?.skillDir || '').trim()).filter(Boolean) : [];
+  if (requestedDirs.length === 0) {
+    return { ok: false, error: { kind: 'invalidSource', message: 'No skills selected for installation' } };
+  }
+
+  // Validate names early and compute conflicts without mutating.
+  const skillPlans = requestedDirs.map((skillDirPosix) => {
+    const skillName = path.posix.basename(skillDirPosix);
+    return { skillDirPosix, skillName, installable: validateSkillName(skillName) };
+  });
+
+  const conflicts = [];
+  for (const plan of skillPlans) {
+    if (!plan.installable) {
+      continue;
+    }
+
+    const targetDir = getTargetSkillDir({ scope, targetSource, workingDirectory, userSkillDir, skillName: plan.skillName });
+    if (fs.existsSync(targetDir)) {
+      const decision = conflictDecisions?.[plan.skillName];
+      const hasAutoPolicy = conflictPolicy === 'skipAll' || conflictPolicy === 'overwriteAll';
+      if (!decision && !hasAutoPolicy) {
+        conflicts.push({ skillName: plan.skillName, scope, source: targetSource === 'agents' ? 'agents' : 'opencode' });
+      }
+    }
+  }
+
+  if (conflicts.length > 0) {
+    return {
+      ok: false,
+      error: {
+        kind: 'conflicts',
+        message: 'Some skills already exist in the selected scope',
+        conflicts,
+      },
+    };
+  }
+
+  const tempBase = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'vinci-skills-install-'));
+
+  try {
+    const cloned = await cloneRepo({ cloneUrl, identity, tempDir: tempBase });
+    if (!cloned.ok) {
+      const msg = `${cloned.error?.stderr || ''}\n${cloned.error?.message || ''}`.trim();
+      if (looksLikeAuthError(msg)) {
+        return { ok: false, error: { kind: 'authRequired', message: 'Authentication required to access this repository', sshOnly: true } };
+      }
+      return { ok: false, error: { kind: 'networkError', message: msg || 'Failed to clone repository' } };
+    }
+
+    // Selective checkout for only requested skill dirs.
+    await runGit(['-C', tempBase, 'sparse-checkout', 'init', '--cone'], { identity, timeoutMs: 15_000 });
+    const setResult = await runGit(['-C', tempBase, 'sparse-checkout', 'set', ...requestedDirs], { identity, timeoutMs: 30_000 });
+    if (!setResult.ok) {
+      return { ok: false, error: { kind: 'unknown', message: setResult.stderr || setResult.message || 'Failed to configure sparse checkout' } };
+    }
+
+    const checkoutResult = await runGit(['-C', tempBase, 'checkout', '--force', 'HEAD'], { identity, timeoutMs: 60_000 });
+    if (!checkoutResult.ok) {
+      return { ok: false, error: { kind: 'unknown', message: checkoutResult.stderr || checkoutResult.message || 'Failed to checkout repository' } };
+    }
+
+    const installed = [];
+    const skipped = [];
+
+    for (const plan of skillPlans) {
+      if (!plan.installable) {
+        skipped.push({ skillName: plan.skillName, reason: 'Invalid skill name (directory basename)' });
+        continue;
+      }
+
+      const srcDir = toFsPath(tempBase, plan.skillDirPosix);
+      const skillMdPath = path.join(srcDir, 'SKILL.md');
+      if (!fs.existsSync(skillMdPath)) {
+        skipped.push({ skillName: plan.skillName, reason: 'SKILL.md not found in selected directory' });
+        continue;
+      }
+
+      const targetDir = getTargetSkillDir({ scope, targetSource, workingDirectory, userSkillDir, skillName: plan.skillName });
+      const exists = fs.existsSync(targetDir);
+
+      let decision = conflictDecisions?.[plan.skillName] || null;
+      if (!decision) {
+        if (exists && conflictPolicy === 'skipAll') decision = 'skip';
+        if (exists && conflictPolicy === 'overwriteAll') decision = 'overwrite';
+        if (!exists) decision = 'overwrite'; // no conflict, proceed
+      }
+
+      if (exists && decision === 'skip') {
+        skipped.push({ skillName: plan.skillName, reason: 'Already installed (skipped)' });
+        continue;
+      }
+
+      if (exists && decision === 'overwrite') {
+        await safeRm(targetDir);
+      }
+
+      // Ensure project parent directories exist
+      await ensureDir(path.dirname(targetDir));
+
+      try {
+        await copyDirectoryNoSymlinks(srcDir, targetDir);
+        installed.push({ skillName: plan.skillName, scope, source: targetSource === 'agents' ? 'agents' : 'opencode' });
+      } catch (error) {
+        await safeRm(targetDir);
+        skipped.push({
+          skillName: plan.skillName,
+          reason: error instanceof Error ? error.message : 'Failed to copy skill files',
+        });
+      }
+    }
+
+    return { ok: true, installed, skipped };
+  } finally {
+    await safeRm(tempBase);
+  }
+}

package/server/lib/skills-catalog/scan.js

@@ -0,0 +1,221 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import yaml from 'yaml';
+
+import { assertGitAvailable, looksLikeAuthError, runGit } from './git.js';
+import { parseSkillRepoSource } from './source.js';
+
+const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/;
+
+function validateSkillName(skillName) {
+  if (typeof skillName !== 'string') return false;
+  if (skillName.length < 1 || skillName.length > 64) return false;
+  return SKILL_NAME_PATTERN.test(skillName);
+}
+
+function parseSkillMd(content) {
+  const text = typeof content === 'string' ? content : '';
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+  if (!match) {
+    return {
+      ok: true,
+      frontmatter: {},
+      warnings: ['Invalid SKILL.md: missing YAML frontmatter delimiter'],
+    };
+  }
+
+  try {
+    const frontmatter = yaml.parse(match[1]) || {};
+    return { ok: true, frontmatter, warnings: [] };
+  } catch {
+    return {
+      ok: true,
+      frontmatter: {},
+      warnings: ['Invalid SKILL.md: failed to parse YAML frontmatter'],
+    };
+  }
+}
+
+async function safeRm(dir) {
+  try {
+    await fs.promises.rm(dir, { recursive: true, force: true });
+  } catch {
+    // ignore
+  }
+}
+
+async function cloneRepo({ cloneUrl, identity, tempDir }) {
+  const preferred = ['clone', '--depth', '1', '--filter=blob:none', '--no-checkout', cloneUrl, tempDir];
+  const fallback = ['clone', '--depth', '1', '--no-checkout', cloneUrl, tempDir];
+
+  const result = await runGit(preferred, { identity, timeoutMs: 60_000 });
+  if (result.ok) return { ok: true };
+
+  const fallbackResult = await runGit(fallback, { identity, timeoutMs: 60_000 });
+  if (fallbackResult.ok) return { ok: true };
+
+  return {
+    ok: false,
+    error: fallbackResult,
+  };
+}
+
+export async function scanSkillsRepository({
+  source,
+  subpath,
+  defaultSubpath,
+  identity,
+} = {}) {
+  const gitCheck = await assertGitAvailable();
+  if (!gitCheck.ok) {
+    return { ok: false, error: gitCheck.error };
+  }
+
+  const parsed = parseSkillRepoSource(source, { subpath });
+  if (!parsed.ok) {
+    return { ok: false, error: parsed.error };
+  }
+
+  const effectiveSubpath = parsed.effectiveSubpath || (typeof defaultSubpath === 'string' && defaultSubpath.trim() ? defaultSubpath.trim() : null);
+  const cloneUrl = identity?.sshKey ? parsed.cloneUrlSsh : parsed.cloneUrlHttps;
+
+  const tempBase = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'vinci-skills-scan-'));
+
+  try {
+    const cloned = await cloneRepo({ cloneUrl, identity, tempDir: tempBase });
+    if (!cloned.ok) {
+      const msg = `${cloned.error?.stderr || ''}\n${cloned.error?.message || ''}`.trim();
+      if (looksLikeAuthError(msg)) {
+        return { ok: false, error: { kind: 'authRequired', message: 'Authentication required to access this repository', sshOnly: true } };
+      }
+      return { ok: false, error: { kind: 'networkError', message: msg || 'Failed to clone repository' } };
+    }
+
+    const toFsPath = (posixPath) => path.join(tempBase, ...String(posixPath || '').split('/').filter(Boolean));
+
+    const patterns = effectiveSubpath
+      ? [`${effectiveSubpath}/SKILL.md`, `${effectiveSubpath}/**/SKILL.md`]
+      : ['SKILL.md', '**/SKILL.md'];
+
+    let skillMdPaths = null;
+
+    // Fast path: sparse checkout only SKILL.md files, then parse from disk.
+    // This avoids one `git show` per skill.
+    const sparseInit = await runGit(['-C', tempBase, 'sparse-checkout', 'init', '--no-cone'], { identity, timeoutMs: 15_000 });
+    if (sparseInit.ok) {
+      const sparseSet = await runGit(['-C', tempBase, 'sparse-checkout', 'set', ...patterns], { identity, timeoutMs: 30_000 });
+      if (sparseSet.ok) {
+        const checkout = await runGit(['-C', tempBase, 'checkout', '--force', 'HEAD'], { identity, timeoutMs: 60_000 });
+        if (checkout.ok) {
+          const lsFiles = await runGit(['-C', tempBase, 'ls-files'], { identity, timeoutMs: 15_000 });
+          if (lsFiles.ok) {
+            skillMdPaths = lsFiles.stdout
+              .split(/\r?\n/)
+              .map((line) => line.trim())
+              .filter(Boolean)
+              .filter((p) => p.endsWith('/SKILL.md') || p === 'SKILL.md');
+          }
+        }
+      }
+    }
+
+    // Fallback: list tree and read SKILL.md blobs via git.
+    if (!Array.isArray(skillMdPaths)) {
+      const listArgs = ['-C', tempBase, 'ls-tree', '-r', '--name-only', 'HEAD'];
+      if (effectiveSubpath) {
+        listArgs.push('--', effectiveSubpath);
+      }
+
+      const listResult = await runGit(listArgs, { identity, timeoutMs: 30_000 });
+      if (!listResult.ok) {
+        // If subpath doesn't exist, treat as empty scan.
+        return {
+          ok: true,
+          normalizedRepo: parsed.normalizedRepo,
+          effectiveSubpath,
+          items: [],
+        };
+      }
+
+      skillMdPaths = listResult.stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .filter((p) => p.endsWith('/SKILL.md') || p === 'SKILL.md');
+    }
+
+    // Root-level SKILL.md doesn't map cleanly to OpenCode's "skill name == folder name" convention.
+    const uniqueSkillDirs = Array.from(
+      new Set(
+        skillMdPaths
+          .filter((p) => p !== 'SKILL.md')
+          .map((p) => path.posix.dirname(p))
+      )
+    );
+
+    const items = [];
+    const maxParallel = 10;
+    let idx = 0;
+
+    const worker = async () => {
+      while (idx < uniqueSkillDirs.length) {
+        const skillDir = uniqueSkillDirs[idx++];
+        const skillName = path.posix.basename(skillDir);
+        const skillMdPath = path.posix.join(skillDir, 'SKILL.md');
+
+        const warnings = [];
+        let skillMdContent = '';
+
+        // Prefer filesystem reads when sparse checkout succeeded.
+        const filePath = toFsPath(skillMdPath);
+        try {
+          skillMdContent = await fs.promises.readFile(filePath, 'utf8');
+        } catch {
+          const showResult = await runGit(['-C', tempBase, 'show', `HEAD:${skillMdPath}`], { identity, timeoutMs: 15_000 });
+          if (!showResult.ok) {
+            warnings.push('Failed to read SKILL.md');
+          } else {
+            skillMdContent = showResult.stdout;
+          }
+        }
+
+        const parsedMd = parseSkillMd(skillMdContent);
+        warnings.push(...(parsedMd.warnings || []));
+
+        const description = typeof parsedMd.frontmatter?.description === 'string' ? parsedMd.frontmatter.description : undefined;
+        const frontmatterName = typeof parsedMd.frontmatter?.name === 'string' ? parsedMd.frontmatter.name : undefined;
+
+        const installable = validateSkillName(skillName);
+        if (!installable) {
+          warnings.push('Skill directory name is not a valid OpenCode skill name');
+        }
+
+        items.push({
+          repoSource: source,
+          repoSubpath: effectiveSubpath || undefined,
+          skillDir,
+          skillName,
+          frontmatterName,
+          description,
+          installable,
+          warnings: warnings.length ? warnings : undefined,
+        });
+      }
+    };
+
+    await Promise.all(Array.from({ length: Math.min(maxParallel, uniqueSkillDirs.length || 1) }, () => worker()));
+
+    // Stable ordering for UX
+    items.sort((a, b) => a.skillName.localeCompare(b.skillName));
+
+    return {
+      ok: true,
+      normalizedRepo: parsed.normalizedRepo,
+      effectiveSubpath,
+      items,
+    };
+  } finally {
+    await safeRm(tempBase);
+  }
+}

package/server/lib/skills-catalog/source.js

@@ -0,0 +1,87 @@
+const GITHUB_HOST = 'github.com';
+
+
+function normalizeGitOwnerRepo(owner, repo) {
+  const normalizedOwner = String(owner || '').trim();
+  const normalizedRepo = String(repo || '').trim().replace(/\.git$/i, '');
+  if (!normalizedOwner || !normalizedRepo) {
+    return null;
+  }
+  return { owner: normalizedOwner, repo: normalizedRepo };
+}
+
+
+export function parseSkillRepoSource(input, options = {}) {
+  const raw = typeof input === 'string' ? input.trim() : '';
+  if (!raw) {
+    return { ok: false, error: { kind: 'invalidSource', message: 'Repository source is required' } };
+  }
+  const explicitSubpath = typeof options.subpath === 'string' && options.subpath.trim() ? options.subpath.trim() : null;
+  
+  const urlFormat = raw.startsWith('https://') ? 'https' : raw.startsWith('git@') ? 'ssh' : 'shorthand';
+  const gitHost = urlFormat === 'https' ? raw.split('/')[2] : urlFormat === 'ssh' ? raw.split('@')[1].split(':')[0] : null;
+
+  if (gitHost === null && urlFormat !== 'shorthand') {
+    return { ok: false, error: { kind: 'invalidSource', message: 'Invalid repository URL format' } };
+  }
+
+  const pathSegments = urlFormat === 'https'
+    ? raw.split('/').slice(3).filter(Boolean)
+    : urlFormat === 'ssh'
+      ? (raw.split('@')[1].split(':')[1] ?? '').split('/').filter(Boolean)
+      : null;
+
+  const repoName = pathSegments && pathSegments.length > 0
+    ? pathSegments[pathSegments.length - 1].replace(/\.git$/i, '')
+    : null;
+
+  const gitOwner = pathSegments && pathSegments.length > 1
+    ? pathSegments.slice(0, -1).join('/')
+    : (pathSegments && pathSegments.length === 1 ? pathSegments[0] : null);
+
+
+  // SSH git@host:owner/repo(.git) or HTTPS https://host/owner/repo(.git)
+  if (urlFormat === 'ssh' || urlFormat === 'https') {
+    const parsed = normalizeGitOwnerRepo(gitOwner, repoName);
+    if (!parsed) {
+      return { ok: false, error: { kind: 'invalidSource', message: `Invalid ${urlFormat} repository URL` } };
+    }
+
+    return {
+      ok: true,
+      host: gitHost,
+      owner: parsed.owner,
+      repo: parsed.repo,
+      cloneUrlSsh: `git@${gitHost}:${parsed.owner}/${parsed.repo}.git`,
+      cloneUrlHttps: `https://${gitHost}/${parsed.owner}/${parsed.repo}.git`,
+      // For SSH URLs, subpath is only accepted via options.subpath
+      effectiveSubpath: explicitSubpath,
+      normalizedRepo: `${parsed.owner}/${parsed.repo}`,
+    };
+  }
+
+  // Shorthand: owner/repo[/subpath...]
+  const shorthandMatch = raw.match(/^([^/\s]+)\/([^/\s]+)(?:\/(.+))?$/);
+  if (shorthandMatch) {
+    const parsed = normalizeGitOwnerRepo(shorthandMatch[1], shorthandMatch[2]);
+    if (!parsed) {
+      return { ok: false, error: { kind: 'invalidSource', message: 'Invalid repository source' } };
+    }
+
+    const shorthandSubpath = typeof shorthandMatch[3] === 'string' && shorthandMatch[3].trim() ? shorthandMatch[3].trim() : null;
+    const effectiveSubpath = explicitSubpath || shorthandSubpath;
+
+    return {
+      ok: true,
+      host: GITHUB_HOST,
+      owner: parsed.owner,
+      repo: parsed.repo,
+      cloneUrlSsh: `git@github.com:${parsed.owner}/${parsed.repo}.git`,
+      cloneUrlHttps: `https://github.com/${parsed.owner}/${parsed.repo}.git`,
+      effectiveSubpath,
+      normalizedRepo: `${parsed.owner}/${parsed.repo}`,
+    };
+  }
+
+  return { ok: false, error: { kind: 'invalidSource', message: 'Unsupported repository source format' } };
+}

package/server/lib/terminal/DOCUMENTATION.md

@@ -0,0 +1,76 @@
+# Terminal Module Documentation
+
+## Purpose
+This module provides WebSocket transport utilities for terminal input and output in the web server runtime, including message normalization, control frame parsing, rate limiting, pathname resolution, and short-lived output replay buffering for terminal WebSocket connections.
+
+## Entrypoints and structure
+- `packages/web/server/lib/terminal/`: Terminal module directory.
+  - `index.js`: Stable module entrypoint that re-exports protocol helpers and replay-buffer helpers.
+  - `runtime.js`: Runtime module that owns terminal session state, WS server setup, and `/api/terminal/*` route registration.
+  - `terminal-ws-protocol.js`: Single-file module containing terminal WebSocket protocol utilities.
+  - `output-replay-buffer.js`: Helper module for buffering recent terminal output so late subscribers can receive startup prompt data.
+- `packages/web/server/lib/terminal/terminal-ws-protocol.test.js`: Test file for protocol utilities.
+- `packages/web/server/lib/terminal/output-replay-buffer.test.js`: Test file for replay buffer helpers.
+
+Public API entry point: imported by `packages/web/server/index.js` from `./lib/terminal/index.js`.
+
+## Public exports
+
+### Constants
+- `TERMINAL_WS_PATH`: Primary WebSocket endpoint path (`/api/terminal/ws`).
+- `TERMINAL_WS_CONTROL_TAG_JSON`: Control frame tag byte (`0x01`) indicating JSON payload.
+- `TERMINAL_WS_MAX_PAYLOAD_BYTES`: Maximum inbound WebSocket payload size (64KB).
+- `TERMINAL_OUTPUT_REPLAY_MAX_BYTES`: Maximum buffered terminal output retained for replay (64KB).
+
+### Request Parsing
+- `parseRequestPathname(requestUrl)`: Extracts pathname from request URL string. Returns empty string for invalid inputs.
+- `isTerminalWsPathname(pathname)`: Returns whether a pathname matches a supported terminal WebSocket route.
+
+### Message Normalization
+- `normalizeTerminalWsMessageToBuffer(rawData)`: Normalizes various data types (Buffer, Uint8Array, ArrayBuffer, string, chunk arrays) to a single Buffer.
+- `normalizeTerminalWsMessageToText(rawData)`: Normalizes data to UTF-8 text string.
+
+### Control Frame Handling
+- `readTerminalWsControlFrame(rawData)`: Parses WebSocket message as control frame. Returns parsed JSON object or null if invalid or malformed.
+- `createTerminalWsControlFrame(payload)`: Creates a control frame with JSON payload and prepends the control tag byte.
+
+### Replay Buffer Helpers
+- `createTerminalOutputReplayBuffer()`: Creates mutable state for recent terminal output replay.
+- `appendTerminalOutputReplayChunk(bufferState, data, maxBytes?)`: Appends a chunk, trimming older buffered data to stay within the configured byte budget.
+- `listTerminalOutputReplayChunksSince(bufferState, lastSeenId)`: Returns buffered chunks newer than the provided replay cursor.
+- `getLatestTerminalOutputReplayChunkId(bufferState)`: Returns the latest chunk id in the replay buffer, or `0` when empty.
+
+### Rate Limiting
+- `pruneRebindTimestamps(timestamps, now, windowMs)`: Filters timestamps to keep only those within the active time window.
+- `isRebindRateLimited(timestamps, maxPerWindow)`: Checks if rebind operations have exceeded the configured threshold.
+
+## Usage in web server
+The terminal helpers are used by `packages/web/server/index.js` for:
+- WebSocket endpoint path definition and matching
+- Message normalization for terminal input payloads
+- Control frame parsing for session binding, keepalive, and exit signaling
+- Rate limiting for session rebind operations
+- Request pathname parsing for WebSocket routing
+- Replaying startup output such as shell prompts when the client binds after the PTY already emitted data
+
+The web server combines these utilities with `bun-pty` or `node-pty` to drive full-duplex PTY sessions.
+
+## Notes for contributors
+- Keep control frames backward-compatible when possible; use explicit `v` values for protocol changes.
+- Always normalize incoming WebSocket messages before processing them.
+- Keep replay buffering small and memory-only; it exists to cover startup races, not to implement persistent scrollback.
+- Add tests for new control frame types, websocket path changes, malformed payload handling, and replay trimming semantics.
+- Keep HTTP input and SSE output fallbacks functional unless the rollout explicitly removes them.
+
+## Verification notes
+### Manual verification
+1. Start the web server and create a terminal session via `/api/terminal/create`.
+2. Wait briefly before binding the client to ensure the shell emits its prompt first.
+3. Connect to `/api/terminal/ws` WebSocket and bind to the session.
+4. Verify the startup prompt and early shell output are replayed before interactive input begins.
+5. Verify `/api/terminal/input-ws` is rejected with `404 Not Found` and `/api/terminal/:sessionId/stream` still works as a fallback path.
+
+### Automated verification
+- Run `bun test packages/web/server/lib/terminal/terminal-ws-protocol.test.js`
+- Run `bun test packages/web/server/lib/terminal/output-replay-buffer.test.js`
+- Run `bun run type-check`, `bun run lint`, and `bun run build` before finalizing changes.