@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

package/runtime/node_modules/@metro-labs/daemon/src/claude/api.ts

@@ -0,0 +1,304 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from '@metro-labs/core/log';
+import { apiFailure, apiSession, requireAdmin, cors, readJsonBody, sendJson } from '@metro-labs/http/api-http';
+import { ApiError } from '@metro-labs/http/api-error';
+import { isRecord } from '@metro-labs/core/is-record';
+import { githubSkillsAnswer } from './github-api.js';
+import { githubSkills, type GitHubSkills } from './github-skills.js';
+import { listClaudeSettings, SETTINGS_MAX, writeClaudeSettings } from './settings.js';
+import {
+  createClaudeSkill,
+  deleteClaudeSkill,
+  listClaudeSkills,
+  readClaudeSkill,
+  writeClaudeSkill,
+} from './skills.js';
+import {
+  answerClaudeLogin,
+  claudeAccount,
+  claudeInstalled,
+  claudeLoginView,
+  endClaudeLogin,
+  startClaudeLogin,
+  type LoginDeps,
+  type LoginTarget,
+} from './login.js';
+import { claudeLoginTarget, type ClaudeLoginDeps } from '../gateway/claude-logins.js';
+import { setupAnswer, type SetupApiDeps } from './setup-api.js';
+import {
+  autostartEnabled,
+  ensureSession,
+  sessionSnapshot,
+  sessionStatus,
+  setAutostart,
+  startSession,
+  stopSession,
+  type SessionDeps,
+} from './session.js';
+import { receiveSessionFile, sessionFilePath } from './session-files.js';
+import { createReadStream } from '../agent-user/agent-fs.js';
+import { pipeline } from 'node:stream/promises';
+import {
+  claudeDir,
+  deleteClaudeSession,
+  deleteMemoryFile,
+  listClaudeProjects,
+  listClaudeSessions,
+  listMemory,
+  readMemoryFile,
+  readTranscript,
+  writeMemoryFile,
+} from './files.js';
+
+const PREFIX = '/api/claude';
+const BODY_MAX = SETTINGS_MAX + 4096;
+const WRITABLE = new Set(['GET', 'DELETE', 'PUT', 'POST']);
+const PAGE = 100;
+const PAGE_MAX = 500;
+
+export interface ClaudeApiDeps extends SetupApiDeps {
+  dir?: () => string;
+  login?: LoginDeps;
+  claudeLogins?: ClaudeLoginDeps;
+  skillSource?: GitHubSkills;
+}
+
+function projectOf(query: URLSearchParams): string {
+  const project = query.get('project');
+  if (project === null || project === '') throw new ApiError('project is required', 400);
+  return project;
+}
+
+function pageOf(query: URLSearchParams): { offset: number; limit: number } {
+  const offset = Math.max(0, Math.floor(Number(query.get('offset') ?? '0')) || 0);
+  const limit = Math.min(PAGE_MAX, Math.max(1, Math.floor(Number(query.get('limit') ?? String(PAGE))) || PAGE));
+  return { offset, limit };
+}
+
+type Handler = (query: URLSearchParams, dir: string, item: string) => unknown;
+
+const COLLECTIONS: Record<string, Handler> = {
+  projects: (_query, dir) => ({ projects: listClaudeProjects(dir) }),
+  sessions: (query, dir) => ({ sessions: listClaudeSessions(projectOf(query), dir) }),
+  memory: (query, dir) => listMemory(projectOf(query), dir),
+  settings: (_query, dir) => ({ files: listClaudeSettings(dir) }),
+  skills: (_query, dir) => ({ skills: listClaudeSkills(dir) }),
+};
+
+const ITEMS: Record<string, Handler> = {
+  sessions: (query, dir, id) => {
+    const { offset, limit } = pageOf(query);
+    return readTranscript(projectOf(query), id, offset, limit, dir);
+  },
+  memory: (query, dir, raw) => {
+    const name = decodeURIComponent(raw);
+    return { name, content: readMemoryFile(projectOf(query), name, dir) };
+  },
+  skills: (_query, dir, id) => readClaudeSkill(decodeURIComponent(id), dir),
+};
+
+const parts = (path: string): string[] => path.slice(PREFIX.length + 1).split('/').filter(Boolean);
+
+const seenIn = (body: Record<string, unknown>): string | null | undefined =>
+  'seenAt' in body ? (typeof body.seenAt === 'string' ? body.seenAt : null) : undefined;
+
+const WRITE_HEADS = new Set(['settings', 'skills', 'memory']);
+
+interface Write {
+  text: string;
+  seen: string | null | undefined;
+  modifiedAt: string | undefined;
+}
+
+function writeItem(head: string, item: string, write: Write, search: string, dir: string): unknown {
+  if (head === 'skills') return writeClaudeSkill(decodeURIComponent(item), write.text, write.seen, dir);
+  if (head === 'memory') return writeMemoryFile(projectOf(new URLSearchParams(search)), decodeURIComponent(item), write.text, dir, write.modifiedAt);
+  return writeClaudeSettings(item, write.text, write.seen, dir);
+}
+
+async function writeAnswer(req: IncomingMessage, path: string, search: string, dir: string): Promise<unknown> {
+  const [head = '', item = ''] = parts(path);
+  if (!WRITE_HEADS.has(head) || item === '') throw new ApiError('method not allowed', 405);
+  const body = await readJsonBody(req, BODY_MAX);
+  if (!isRecord(body) || typeof body.text !== 'string') throw new ApiError('text is required', 400);
+  const modifiedAt = typeof body.modifiedAt === 'string' ? body.modifiedAt : undefined;
+  return writeItem(head, item, { text: body.text, seen: seenIn(body), modifiedAt }, search, dir);
+}
+
+async function created(req: IncomingMessage, path: string, dir: string): Promise<unknown> {
+  const rest = parts(path);
+  if (rest.length !== 1 || rest[0] !== 'skills') throw new ApiError('method not allowed', 405);
+  const body = await readJsonBody(req, BODY_MAX);
+  if (!isRecord(body) || typeof body.name !== 'string') throw new ApiError('name is required', 400);
+  return createClaudeSkill(body.name, typeof body.text === 'string' ? body.text : undefined, dir);
+}
+
+const ADMIN_ONLY = /^\/api\/claude\/(login|session|setup|skill-source)(\/|$)/;
+const LOGIN = 'login';
+const SESSION = 'session';
+const SETUP = 'setup';
+
+function sessionCommand(body: Record<string, unknown>, session: SessionDeps): unknown {
+  if (body.action === 'start') {
+    const status = sessionStatus(session);
+    if (!status.running && status.blocked !== null) throw new ApiError(`cannot start a Claude session: ${status.blocked}`, 409);
+    const started = status.running ? status : startSession(session);
+    setAutostart(typeof body.autostart === 'boolean' ? body.autostart : true, session.agents);
+    return { ...started, autostart: autostartEnabled(session.agents) };
+  }
+  if (body.action === 'stop') {
+    setAutostart(false, session.agents);
+    return stopSession(session, true);
+  }
+  if (body.action !== undefined) throw new ApiError('action must be start or stop', 400);
+  if (typeof body.autostart === 'boolean') setAutostart(body.autostart, session.agents);
+  if (body.autostart === true) ensureSession(session);
+  return sessionStatus(session);
+}
+
+async function sessionAnswer(req: IncomingMessage, deps: ClaudeApiDeps): Promise<unknown> {
+  const session = deps.session ?? {};
+  const method = req.method ?? 'GET';
+  if (method === 'GET') return sessionStatus(session);
+  if (method !== 'POST') throw new ApiError('method not allowed', 405);
+  const body = await readJsonBody(req);
+  if (!isRecord(body)) throw new ApiError('a body is required', 400);
+  return sessionCommand(body, session);
+}
+
+function loginTarget(req: IncomingMessage, deps: ClaudeApiDeps): LoginTarget | null {
+  const asked = new URL(req.url ?? '', 'http://metro').searchParams.get('connection');
+  return asked === null ? null : claudeLoginTarget(asked, deps.claudeLogins);
+}
+
+async function loginAnswer(req: IncomingMessage, id: string, deps: ClaudeApiDeps): Promise<unknown> {
+  const method = req.method ?? 'GET';
+  if (id === '') {
+    if (method === 'POST') return startClaudeLogin(deps.login, Date.now(), loginTarget(req, deps));
+    if (method === 'GET') return { available: claudeInstalled(), ...claudeAccount() };
+    throw new ApiError('method not allowed', 405);
+  }
+  if (method === 'GET') return claudeLoginView(id);
+  if (method === 'DELETE') return endClaudeLogin(id);
+  if (method !== 'POST') throw new ApiError('method not allowed', 405);
+  const body = await readJsonBody(req);
+  if (!isRecord(body) || typeof body.text !== 'string') throw new ApiError('text is required', 400);
+  return answerClaudeLogin(id, body.text);
+}
+
+function removed(rest: string[], query: URLSearchParams, dir: string): unknown {
+  const [head = '', item = ''] = rest;
+  if (rest.length !== 2) throw new ApiError('method not allowed', 405);
+  if (head === 'skills') return { deleted: deleteClaudeSkill(decodeURIComponent(item), dir) };
+  if (head === 'memory') return { deleted: deleteMemoryFile(projectOf(query), decodeURIComponent(item), dir) };
+  if (head !== 'sessions') throw new ApiError('method not allowed', 405);
+  deleteClaudeSession(projectOf(query), item, dir);
+  return { deleted: item };
+}
+
+function answer(method: string, path: string, query: URLSearchParams, dir: string): unknown {
+  const rest = parts(path);
+  const [head = '', item = ''] = rest;
+  if (method === 'DELETE') return removed(rest, query, dir);
+  if (method !== 'GET') throw new ApiError('method not allowed', 405);
+  const handler = rest.length === 1 ? COLLECTIONS[head] : rest.length === 2 ? ITEMS[head] : undefined;
+  if (handler === undefined) throw new ApiError('no such route', 404);
+  return handler(query, dir, item);
+}
+
+const SINGLETONS: Record<string, (req: IncomingMessage, deps: ClaudeApiDeps) => Promise<unknown>> = {
+  [SESSION]: sessionAnswer,
+  [SETUP]: setupAnswer,
+};
+
+function skillsAnswer(req: IncomingMessage, path: string, search: string, dir: string, source: GitHubSkills): unknown {
+  const segments = parts(path);
+  if (req.method === 'GET' && segments.length === 1) {
+    const listing = source.listing();
+    return { skills: [...listClaudeSkills(dir), ...listing.rows], skillSource: listing.skillSource };
+  }
+  const item = decodeURIComponent(segments[1] ?? '');
+  if (segments.length === 2 && item.startsWith('github:')) {
+    if (req.method !== 'GET') throw new ApiError('GitHub skills are read-only here. Edit the repository or remove its source.', 409);
+    return source.read(item);
+  }
+  return fileAnswer(req, path, search, dir);
+}
+
+const sourceOf = (deps: ClaudeApiDeps): GitHubSkills => deps.skillSource ?? githubSkills();
+
+function fileAnswer(req: IncomingMessage, path: string, search: string, dir: string): unknown {
+  if (req.method === 'PUT') return writeAnswer(req, path, search, dir);
+  if (req.method === 'POST') return created(req, path, dir);
+  return answer(req.method ?? 'GET', path, new URLSearchParams(search), dir);
+}
+
+function routed(req: IncomingMessage, path: string, search: string, deps: ClaudeApiDeps): unknown {
+  const dir = (deps.dir ?? claudeDir)();
+  const [head = '', item = ''] = parts(path);
+  if (head === LOGIN) return loginAnswer(req, item, deps);
+  if (head === 'skill-source' && parts(path).length === 1) return githubSkillsAnswer(req, deps.skillSource);
+  if (head === 'skills') return skillsAnswer(req, path, search, dir, sourceOf(deps));
+  const single = item === '' ? SINGLETONS[head] : undefined;
+  if (single !== undefined) return single(req, deps);
+  return fileAnswer(req, path, search, dir);
+}
+
+const TEXT = 'text/plain; charset=utf-8';
+
+async function streamed(req: IncomingMessage, res: ServerResponse, path: string, search: string, dir: string): Promise<boolean> {
+  const [head = '', item = ''] = parts(path);
+  if (head !== 'sessions' || item === '') return false;
+  const query = new URLSearchParams(search);
+  if (req.method === 'GET' && query.get('raw') === '1') {
+    const file = sessionFilePath(projectOf(query), item, dir);
+    res.writeHead(200, { 'content-type': TEXT, 'cache-control': 'no-store', ...cors(req) });
+    await pipeline(createReadStream(file), res).catch(() => {
+      res.destroy();
+    });
+    return true;
+  }
+  if (req.method === 'PUT') {
+    if ((req.headers['content-type'] ?? '').includes('json')) throw new ApiError('send the session file as text/plain', 415);
+    sendJson(req, res, 200, await receiveSessionFile(projectOf(query), item, req, dir));
+    return true;
+  }
+  return false;
+}
+
+export function handleClaudeRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ClaudeApiDeps,
+): boolean {
+  const [path = '', search = ''] = (req.url ?? '').split('?');
+  if (path !== PREFIX && !path.startsWith(`${PREFIX}/`)) return false;
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  if (!WRITABLE.has(req.method ?? '')) {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  apiSession(req)
+    .then(async (session) => {
+      if (!session) throw new ApiError('unauthorized', 401);
+      if (path === `${PREFIX}/session/snapshot`) {
+        if (req.method !== 'GET') throw new ApiError('method not allowed', 405);
+        sendJson(req, res, 200, sessionSnapshot(deps.session));
+        return;
+      }
+      if (req.method !== 'GET' && ADMIN_ONLY.test(path.replace(/\/{2,}/g, '/'))) requireAdmin(session);
+      if (await streamed(req, res, path, search, (deps.dir ?? claudeDir)())) return;
+      sendJson(req, res, 200, await routed(req, path, search, deps));
+    })
+    .catch((err: unknown) => {
+      if (err instanceof ApiError) apiFailure(req, res, err, 'claude-api');
+      else {
+        log.warn({ err: errMsg(err) }, 'claude-api: request failed');
+        if (!res.headersSent) sendJson(req, res, 500, { error: 'claude-api failed' });
+      }
+    });
+  return true;
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/cli-files.ts

@@ -0,0 +1,28 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CHECKOUT = fileURLToPath(new URL('../../../../packages/cli', import.meta.url));
+const HOOKS = 'hooks';
+const SKILLS = 'skills';
+export const GUARD_HOOK = 'guard.mjs';
+export const SESSION_START_HOOK = 'session-start.mjs';
+const UNSAFE_PATH = /["$`\\\n]/;
+
+export function cliPackageDir(env: NodeJS.ProcessEnv = process.env): string {
+  const bin = env.METRO_CLI_BIN?.trim() ?? '';
+  if (bin === '') return CHECKOUT;
+  try {
+    return dirname(dirname(realpathSync(bin)));
+  } catch {
+    return CHECKOUT;
+  }
+}
+
+export const skillsDir = (cli: string): string => join(cli, SKILLS);
+
+export function hooksDir(cli: string): string | null {
+  const dir = join(cli, HOOKS);
+  if (UNSAFE_PATH.test(dir)) return null;
+  return existsSync(join(dir, GUARD_HOOK)) && existsSync(join(dir, SESSION_START_HOOK)) ? dir : null;
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/files.ts

@@ -0,0 +1,359 @@
+import { createReadStream, existsSync, readdirEntries, readdirNames, readRange, statSync } from '../agent-user/agent-fs.js';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { ApiError } from '@metro-labs/http/api-error';
+import { isRecord } from '@metro-labs/core/is-record';
+import { removeHome, writeHomeText } from '../agent-user/home-fs.js';
+import { agentUser } from '../agent-user/user.js';
+
+export const PROJECT_RE = /^[A-Za-z0-9._-]{1,200}$/;
+export const SESSION_RE = /^[A-Za-z0-9][A-Za-z0-9-]{7,63}$/;
+const MEMORY_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,119}\.md$/;
+const FOLDER_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,119}$/;
+const MEMORY_DEPTH = 6;
+const MEMORY_FILES_MAX = 5000;
+const EDGE_BYTES = 64 * 1024;
+const TEXT_CAP = 20_000;
+const RESULT_CAP = 8_000;
+const INPUT_CAP = 4_000;
+const FILE_CAP = 1_000_000;
+const MEMORY_MAX = 256 * 1024;
+const MEMORY_MODE = 0o644;
+const NOISE = ['<task-notification>', '<system-reminder>', '<local-command', '<command-name>'];
+
+export function claudeDir(): string {
+  const explicit = process.env.METRO_CLAUDE_DIR?.trim();
+  if (explicit !== undefined && explicit !== '') return explicit;
+  const cfg = process.env.CLAUDE_CONFIG_DIR?.trim();
+  if (cfg !== undefined && cfg !== '') return cfg;
+  const user = agentUser();
+  return join(user === null ? homedir() : user.home, '.claude');
+}
+
+const str = (v: unknown): string | null => (typeof v === 'string' && v !== '' ? v : null);
+
+export function safeName(value: string, re: RegExp, what: string): string {
+  if (!re.test(value) || value === '.' || value === '..')
+    throw new ApiError(`that is not a ${what}`, 400);
+  return value;
+}
+
+function projectDir(project: string, dir: string): string {
+  const path = join(dir, 'projects', safeName(project, PROJECT_RE, 'Claude project id'));
+  if (!existsSync(path)) throw new ApiError('no such Claude project', 404);
+  return path;
+}
+
+function parseLines(text: string): Record<string, unknown>[] {
+  const out: Record<string, unknown>[] = [];
+  for (const line of text.split('\n')) {
+    if (line.trim() === '') continue;
+    try {
+      const parsed: unknown = JSON.parse(line);
+      if (isRecord(parsed)) out.push(parsed);
+    } catch {
+      continue;
+    }
+  }
+  return out;
+}
+
+function readEdge(path: string, fromEnd: boolean): Record<string, unknown>[] {
+  const size = statSync(path).size;
+  const length = Math.min(EDGE_BYTES, size);
+  const text = readRange(path, fromEnd ? size - length : 0, length).toString('utf8');
+  const cut = fromEnd && length < size ? text.indexOf('\n') + 1 : 0;
+  return parseLines(text.slice(cut));
+}
+
+export interface ClaudeProject {
+  id: string;
+  cwd: string | null;
+  sessions: number;
+  lastActiveAt: string | null;
+  hasMemory: boolean;
+}
+
+function sessionFiles(path: string): { name: string; mtime: number; size: number }[] {
+  return readdirNames(path)
+    .filter((name) => name.endsWith('.jsonl'))
+    .map((name) => {
+      const s = statSync(join(path, name));
+      return { name, mtime: s.mtimeMs, size: s.size };
+    })
+    .sort((a, b) => b.mtime - a.mtime);
+}
+
+function cwdOf(path: string): string | null {
+  for (const line of readEdge(path, false)) {
+    const cwd = str(line.cwd);
+    if (cwd !== null) return cwd;
+  }
+  return null;
+}
+
+export function listClaudeProjects(dir = claudeDir()): ClaudeProject[] {
+  const root = join(dir, 'projects');
+  if (!existsSync(root)) return [];
+  return readdirEntries(root)
+    .filter((entry) => entry.isDirectory() && PROJECT_RE.test(entry.name))
+    .map((entry) => {
+      const path = join(root, entry.name);
+      const files = sessionFiles(path);
+      const newest = files[0];
+      return {
+        id: entry.name,
+        cwd: newest === undefined ? null : cwdOf(join(path, newest.name)),
+        sessions: files.length,
+        lastActiveAt: newest === undefined ? null : new Date(newest.mtime).toISOString(),
+        hasMemory: existsSync(join(path, 'memory')),
+      };
+    })
+    .sort((a, b) => (b.lastActiveAt ?? '').localeCompare(a.lastActiveAt ?? ''));
+}
+
+export interface ClaudeSession {
+  id: string;
+  title: string;
+  startedAt: string | null;
+  lastAt: string;
+  bytes: number;
+  gitBranch: string | null;
+  version: string | null;
+}
+
+function firstPrompt(lines: Record<string, unknown>[]): string | null {
+  for (const line of lines) {
+    if (line.type !== 'user' || line.isSidechain === true) continue;
+    const message = isRecord(line.message) ? line.message : {};
+    const text = promptText(message.content);
+    if (text !== null && !NOISE.some((n) => text.startsWith(n))) return text.slice(0, 120);
+  }
+  return null;
+}
+
+function promptText(content: unknown): string | null {
+  if (typeof content === 'string') return content.trim() === '' ? null : content.trim();
+  if (!Array.isArray(content)) return null;
+  for (const block of content)
+    if (isRecord(block) && block.type === 'text') {
+      const text = str(block.text);
+      if (text !== null) return text.trim();
+    }
+  return null;
+}
+
+function sessionOf(path: string, id: string, mtime: number, size: number): ClaudeSession {
+  const head = readEdge(path, false);
+  const tail = readEdge(path, true);
+  const titled = [...tail].reverse().find((l) => l.type === 'ai-title' && str(l.aiTitle) !== null);
+  const meta = head.find((l) => l.type === 'user' || l.type === 'assistant') ?? {};
+  return {
+    id,
+    title: (titled === undefined ? null : str(titled.aiTitle)) ?? firstPrompt(head) ?? 'Untitled session',
+    startedAt: str(head.find((l) => str(l.timestamp) !== null)?.timestamp) ?? null,
+    lastAt: new Date(mtime).toISOString(),
+    bytes: size,
+    gitBranch: str(meta.gitBranch),
+    version: str(meta.version),
+  };
+}
+
+export function listClaudeSessions(project: string, dir = claudeDir()): ClaudeSession[] {
+  const path = projectDir(project, dir);
+  return sessionFiles(path).map((f) =>
+    sessionOf(join(path, f.name), f.name.slice(0, -'.jsonl'.length), f.mtime, f.size),
+  );
+}
+
+type Block =
+  | { kind: 'text'; text: string }
+  | { kind: 'tool_use'; name: string; input: string }
+  | { kind: 'tool_result'; text: string; isError: boolean }
+  | { kind: 'thinking' }
+  | { kind: 'image' };
+
+interface TranscriptEntry {
+  uuid: string;
+  at: string | null;
+  role: 'user' | 'assistant';
+  blocks: Block[];
+}
+
+export interface TranscriptPage {
+  entries: TranscriptEntry[];
+  total: number;
+  next: number | null;
+}
+
+const cap = (text: string, max: number): string =>
+  text.length > max ? `${text.slice(0, max)}\n… (${String(text.length - max)} more characters)` : text;
+
+function resultText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .map((b) => (isRecord(b) && b.type === 'text' ? (str(b.text) ?? '') : ''))
+    .filter((t) => t !== '')
+    .join('\n');
+}
+
+function textBlock(raw: Record<string, unknown>): Block | null {
+  const text = str(raw.text);
+  if (text === null || NOISE.some((n) => text.startsWith(n))) return null;
+  return { kind: 'text', text: cap(text, TEXT_CAP) };
+}
+
+const BLOCKS: Record<string, (raw: Record<string, unknown>) => Block | null> = {
+  text: textBlock,
+  tool_use: (raw) => ({
+    kind: 'tool_use',
+    name: str(raw.name) ?? 'tool',
+    input: cap(JSON.stringify(raw.input ?? {}, null, 1), INPUT_CAP),
+  }),
+  tool_result: (raw) => ({
+    kind: 'tool_result',
+    text: cap(resultText(raw.content), RESULT_CAP),
+    isError: raw.is_error === true,
+  }),
+  thinking: () => ({ kind: 'thinking' }),
+  image: () => ({ kind: 'image' }),
+};
+
+function blockOf(raw: unknown): Block | null {
+  if (!isRecord(raw) || typeof raw.type !== 'string') return null;
+  const make = BLOCKS[raw.type];
+  return make === undefined ? null : make(raw);
+}
+
+function entryOf(line: Record<string, unknown>): TranscriptEntry | null {
+  if ((line.type !== 'user' && line.type !== 'assistant') || line.isSidechain === true) return null;
+  const message = isRecord(line.message) ? line.message : {};
+  const content = message.content;
+  const blocks =
+    typeof content === 'string'
+      ? [blockOf({ type: 'text', text: content })]
+      : Array.isArray(content)
+        ? content.map(blockOf)
+        : [];
+  const kept = blocks.filter((b): b is Block => b !== null);
+  if (kept.length === 0) return null;
+  return { uuid: str(line.uuid) ?? '', at: str(line.timestamp), role: line.type, blocks: kept };
+}
+
+export async function readTranscript(
+  project: string,
+  session: string,
+  offset: number,
+  limit: number,
+  dir = claudeDir(),
+): Promise<TranscriptPage> {
+  const path = join(projectDir(project, dir), `${safeName(session, SESSION_RE, 'session id')}.jsonl`);
+  if (!existsSync(path)) throw new ApiError('no such session', 404);
+  const entries: TranscriptEntry[] = [];
+  let total = 0;
+  const lines = createInterface({ input: createReadStream(path), crlfDelay: Infinity });
+  for await (const line of lines) {
+    const parsed = parseLines(line)[0];
+    const entry = parsed === undefined ? null : entryOf(parsed);
+    if (entry === null) continue;
+    if (total >= offset && entries.length < limit) entries.push(entry);
+    total += 1;
+  }
+  return { entries, total, next: offset + limit < total ? offset + limit : null };
+}
+
+export function deleteClaudeSession(project: string, session: string, dir = claudeDir()): void {
+  const root = projectDir(project, dir);
+  const id = safeName(session, SESSION_RE, 'session id');
+  const file = join(root, `${id}.jsonl`);
+  if (!existsSync(file)) throw new ApiError('no such session', 404);
+  removeHome(file);
+  removeHome(join(root, id), true);
+}
+
+export interface MemoryFile {
+  name: string;
+  bytes: number;
+  modifiedAt: string;
+}
+
+export interface MemoryListing {
+  files: MemoryFile[];
+  index: string | null;
+}
+
+function memoryDir(project: string, dir: string): string {
+  return join(projectDir(project, dir), 'memory');
+}
+
+function readCapped(path: string): string {
+  const size = statSync(path).size;
+  const text = readRange(path, 0, Math.min(size, FILE_CAP)).toString('utf8');
+  return size > FILE_CAP ? `${text}\n\n… truncated` : text;
+}
+
+function memoryName(name: string): string[] {
+  const segments = name.split('/');
+  const file = segments.at(-1) ?? '';
+  const folders = segments.slice(0, -1);
+  if (folders.length >= MEMORY_DEPTH || !MEMORY_RE.test(file) || folders.some((f) => !FOLDER_RE.test(f)))
+    throw new ApiError('that is not a memory file name', 400);
+  return segments;
+}
+
+function memoryPath(project: string, name: string, dir: string): string {
+  return join(memoryDir(project, dir), ...memoryName(name));
+}
+
+function walkMemory(root: string, folders: string[], out: MemoryFile[]): void {
+  for (const entry of readdirEntries(join(root, ...folders))) {
+    if (out.length >= MEMORY_FILES_MAX) return;
+    const inner = [...folders, entry.name];
+    if (entry.isDirectory() && FOLDER_RE.test(entry.name) && inner.length < MEMORY_DEPTH) walkMemory(root, inner, out);
+    else if (entry.isFile() && MEMORY_RE.test(entry.name) && !(folders.length === 0 && entry.name === 'MEMORY.md')) {
+      const s = statSync(join(root, ...inner));
+      out.push({ name: inner.join('/'), bytes: s.size, modifiedAt: s.mtime.toISOString() });
+    }
+  }
+}
+
+export function listMemory(project: string, dir = claudeDir()): MemoryListing {
+  const path = memoryDir(project, dir);
+  if (!existsSync(path)) return { files: [], index: null };
+  const files: MemoryFile[] = [];
+  walkMemory(path, [], files);
+  files.sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt) || a.name.localeCompare(b.name));
+  const index = join(path, 'MEMORY.md');
+  return { files, index: existsSync(index) ? readCapped(index) : null };
+}
+
+const stampOf = (raw: string | undefined): Date | null => {
+  if (raw === undefined) return null;
+  const at = new Date(raw);
+  return Number.isNaN(at.getTime()) ? null : at;
+};
+
+export function writeMemoryFile(project: string, name: string, text: string, dir = claudeDir(), modifiedAt?: string): MemoryFile {
+  if (text.trim() === '') throw new ApiError('a memory file cannot be empty', 400);
+  if (Buffer.byteLength(text, 'utf8') > MEMORY_MAX)
+    throw new ApiError(`a memory file is at most ${String(MEMORY_MAX)} bytes`, 400);
+  const path = memoryPath(project, name, dir);
+  writeHomeText(path, text, MEMORY_MODE, stampOf(modifiedAt) ?? undefined);
+  const stat = statSync(path);
+  return { name, bytes: stat.size, modifiedAt: stat.mtime.toISOString() };
+}
+
+export function deleteMemoryFile(project: string, name: string, dir = claudeDir()): string {
+  const path = memoryPath(project, name, dir);
+  if (!existsSync(path)) throw new ApiError('no such memory file', 404);
+  removeHome(path);
+  return name;
+}
+
+export function readMemoryFile(project: string, name: string, dir = claudeDir()): string {
+  const path = memoryPath(project, name, dir);
+  if (!existsSync(path)) throw new ApiError('no such memory file', 404);
+  return readCapped(path);
+}