@stage-labs/metro 0.1.0-beta.26 → 0.1.0-beta.261

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

@@ -0,0 +1,123 @@
+import { join } from 'node:path';
+import { errMsg, log } from '@metro-labs/core/log';
+import { existsSync, readFileSync } from '../agent-user/agent-fs.js';
+import { readCrontab, withBlock, writeCrontab } from '../agent-user/crontab.js';
+import { writeHomeText } from '../agent-user/home-fs.js';
+import { listSchedules, parseCronLine, realRunner, type Runner } from '../agent-user/schedules.js';
+import { agentPath, agentUser, type AgentUser } from '../agent-user/user.js';
+
+const BEGIN = '# metro memory routine: begin';
+const END = '# metro memory routine: end';
+const REPLACED = '# replaced by memory-routine: ';
+const OWN_JOB = /memory/i;
+const SCHEDULE = '0 0,12 * * *';
+
+export type MemoryJobState = 'scheduled' | 'own' | 'off' | 'unavailable';
+
+export interface MemoryJob {
+  state: MemoryJobState;
+  job: string | null;
+}
+
+export interface MemoryJobDeps {
+  user?: AgentUser | null;
+  runner?: Runner;
+  cli?: string;
+  port?: string;
+}
+
+let last: MemoryJob = { state: 'unavailable', job: null };
+
+export const memoryJobStatus = (): MemoryJob => ({ ...last });
+
+export const launcherPath = (user: AgentUser): string => join(user.home, '.metro', 'bin', 'memory-routine');
+export const skillPath = (user: AgentUser): string => join(user.home, '.claude', 'skills', 'memory', 'SKILL.md');
+const logPath = (user: AgentUser): string => join(user.home, '.metro', 'memory-routine.log');
+const quoted = (text: string): string => `'${text.replace(/'/g, '\'\\\'\'')}'`;
+
+export function launcherText(user: AgentUser, cli: string, port: string): string {
+  return [
+    '#!/bin/sh',
+    `PATH=${quoted(agentPath(user))}`,
+    'export PATH',
+    ...(port === '' ? [] : [`METRO_WEBHOOK_PORT=${quoted(port)}`, 'export METRO_WEBHOOK_PORT']),
+    'cd "$HOME" || exit 1',
+    `exec node ${quoted(cli)} memory "$@"`,
+    '',
+  ].join('\n');
+}
+
+export const cronLine = (user: AgentUser): string => `${SCHEDULE} ${launcherPath(user)} ${skillPath(user)} >> ${logPath(user)} 2>&1`;
+
+const commandName = (command: string): string => command.split(/\s+/)[0]?.split('/').pop() ?? 'cron';
+
+const ownCommand = (user: AgentUser, line: string): string | null => {
+  const parsed = parseCronLine(line);
+  return parsed === null || parsed.command.includes(launcherPath(user)) || !OWN_JOB.test(parsed.command) ? null : parsed.command;
+};
+
+const replaces = (user: AgentUser, line: string): boolean => OWN_JOB.test(commandName(ownCommand(user, line) ?? ''));
+
+function ownJob(user: AgentUser, runner: Runner, lines: string[]): string | null {
+  const cron = lines.flatMap((line) => {
+    const command = ownCommand(user, line);
+    return command === null || replaces(user, line) ? [] : [commandName(command)];
+  });
+  const timers = listSchedules(null, runner).filter((job) => job.runsAs === user.name && OWN_JOB.test(`${job.name} ${job.command}`));
+  return cron[0] ?? timers[0]?.name ?? null;
+}
+
+const restored = (line: string): string => (line.startsWith(REPLACED) ? line.slice(REPLACED.length) : line);
+
+function marked(user: AgentUser, lines: string[], on: boolean, scheduled: boolean): string[] {
+  if (!on) return lines.map(restored);
+  return lines.map((l) => (scheduled && replaces(user, l) ? `${REPLACED}${l}` : l));
+}
+
+function placeLauncher(path: string, text: string): void {
+  if (existsSync(path) && readFileSync(path, 'utf8') === text) return;
+  writeHomeText(path, text, 0o755);
+}
+
+const envText = (name: string): string => process.env[name]?.trim() ?? '';
+
+function resolved(deps: MemoryJobDeps): Required<MemoryJobDeps> {
+  return {
+    user: deps.user === undefined ? agentUser() : deps.user,
+    runner: deps.runner ?? realRunner,
+    cli: deps.cli ?? envText('METRO_CLI_BIN'),
+    port: deps.port ?? envText('METRO_WEBHOOK_PORT'),
+  };
+}
+
+const stateOf = (scheduled: boolean, own: string | null): MemoryJobState => {
+  if (scheduled) return 'scheduled';
+  return own === null ? 'off' : 'own';
+};
+
+export function ensureMemoryJob(on: boolean, deps: MemoryJobDeps = {}): MemoryJob {
+  const { user, runner, cli, port } = resolved(deps);
+  if (user === null || cli === '') {
+    last = { state: 'unavailable', job: null };
+    return memoryJobStatus();
+  }
+  const lines = readCrontab(user, runner);
+  const own = on ? ownJob(user, runner, lines) : null;
+  const scheduled = on && own === null;
+  const launcher = launcherPath(user);
+  if (scheduled) placeLauncher(launcher, launcherText(user, cli, port));
+  const kept = marked(user, lines, on, scheduled);
+  const next = withBlock(kept, BEGIN, END, scheduled ? [cronLine(user)] : [], 'end', (l) => l.includes(launcher));
+  const changed = writeCrontab(user, runner, lines, next);
+  last = { state: stateOf(scheduled, own), job: own };
+  if (changed) log.info({ ...last, rewritten: kept.filter((l, i) => l !== lines[i]) }, 'memory-routine: updated the memory job');
+  return memoryJobStatus();
+}
+
+export function tryMemoryJob(on: boolean): void {
+  try {
+    ensureMemoryJob(on);
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'memory-routine: could not set up the daily memory job');
+  }
+}

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

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs';
+import { totalmem } from 'node:os';
+import { helperArgv, runningAsMetro } from '../metro-user/privilege.js';
+
+const GIB = 1024 ** 3;
+const RESERVE = 1.5 * GIB;
+const FLOOR = GIB;
+
+export interface ScopeHost {
+  metro: boolean;
+  systemd: boolean;
+  total: number;
+}
+
+const realHost = (): ScopeHost => ({
+  metro: runningAsMetro(),
+  systemd: existsSync('/run/systemd/system'),
+  total: totalmem(),
+});
+
+export function sessionMemoryLimit(total: number): number {
+  const kept = Math.min(Math.floor(total * 0.8), total - RESERVE);
+  return Math.max(FLOOR, Math.floor(kept / (1024 * 1024)) * 1024 * 1024);
+}
+
+export function inSessionScope(command: [string, string[]], host: ScopeHost = realHost()): [string, string[]] {
+  const [file, args] = command;
+  const asAgent = file === 'sudo' && args[0] === '-n' && args[1] === '-u' && args[3] === '--';
+  if (!host.metro || !host.systemd || !asAgent) return command;
+  const limit = sessionMemoryLimit(host.total);
+  return helperArgv(['as-agent-scope', String(limit), String(Math.floor(limit * 0.9)), ...args.slice(4)]);
+}

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

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync, realpathSync } from '../agent-user/agent-fs.js';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { writeHomeText } from '../agent-user/home-fs.js';
+import { agentUser } from '../agent-user/user.js';
+
+const FILE = '.claude.json';
+const FLAG = 'hasCompletedOnboarding';
+
+export type OnboardingMark = 'marked' | 'already' | 'unreadable';
+
+const given = (value: string | undefined): string | undefined =>
+  value !== undefined && value.trim() !== '' ? value.trim() : undefined;
+
+export function claudeConfigPath(env: NodeJS.ProcessEnv = process.env): string {
+  const user = agentUser();
+  if (user !== null) return join(user.home, FILE);
+  return join(given(env.CLAUDE_CONFIG_DIR) ?? given(env.HOME) ?? homedir(), FILE);
+}
+
+function readConfig(path: string): Record<string, unknown> | null {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function markOnboardingDone(path = claudeConfigPath()): OnboardingMark {
+  const config = readConfig(path);
+  if (config === null) return 'unreadable';
+  if (config[FLAG] === true) return 'already';
+  writeHomeText(path, `${JSON.stringify({ ...config, [FLAG]: true }, null, 2)}\n`, 0o600);
+  return 'marked';
+}
+
+const TRUST = 'hasTrustDialogAccepted';
+
+function realDir(dir: string): string {
+  try {
+    return realpathSync(dir);
+  } catch {
+    return dir;
+  }
+}
+
+export function trustFolder(dir: string, path = claudeConfigPath()): OnboardingMark {
+  const config = readConfig(path);
+  if (config === null) return 'unreadable';
+  const key = realDir(dir);
+  const projects = isRecord(config.projects) ? config.projects : {};
+  const project = isRecord(projects[key]) ? projects[key] : {};
+  if (project[TRUST] === true) return 'already';
+  const next = { ...config, projects: { ...projects, [key]: { ...project, [TRUST]: true } } };
+  writeHomeText(path, `${JSON.stringify(next, null, 2)}\n`, 0o600);
+  return 'marked';
+}

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

@@ -0,0 +1,149 @@
+import { execFile } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from '../agent-user/agent-fs.js';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { log } from '@metro-labs/core/log';
+import { agentMarketplaceDir, agentUser, asAgent, claudeBin } from '../agent-user/user.js';
+
+const MARKETPLACE = 'metro';
+const PLUGIN = 'metro@metro';
+const STEP_MS = 120_000;
+const SAID_MAX = 300;
+
+export interface Answer {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+export type Run = (args: string[]) => Promise<Answer>;
+
+export interface PluginInstallDeps {
+  run: Run | null;
+  marketplaceDir: string | null;
+}
+
+export type PluginOutcome = 'skipped' | 'unchanged' | 'installed' | 'updated' | 'failed';
+
+function storeMarketplaceDir(env: NodeJS.ProcessEnv = process.env): string | null {
+  const store = env.METRO_RUNTIME_STORE?.trim() ?? '';
+  if (store === '') return null;
+  const dir = join(store, 'marketplace');
+  return existsSync(join(dir, '.claude-plugin', 'marketplace.json')) ? dir : null;
+}
+
+export function stagedMarketplaceDir(env: NodeJS.ProcessEnv = process.env): string | null {
+  const store = storeMarketplaceDir(env);
+  const user = agentUser();
+  if (store === null || user === null) return store;
+  const copy = agentMarketplaceDir(user);
+  return existsSync(join(copy, '.claude-plugin', 'marketplace.json')) ? copy : null;
+}
+
+export function stagedPluginVersion(dir: string): string | null {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(join(dir, 'plugin', '.claude-plugin', 'plugin.json'), 'utf8'));
+    return isRecord(parsed) && typeof parsed.version === 'string' ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
+const runner =
+  (bin: string): Run =>
+  (args) =>
+    new Promise((resolve) => {
+      execFile(...asAgent(bin, args), { encoding: 'utf8', timeout: STEP_MS, maxBuffer: 4 * 1024 * 1024 }, (err, stdout, stderr) => {
+        const status = err === null ? 0 : typeof (err as { code?: unknown }).code === 'number' ? (err as { code: number }).code : 1;
+        resolve({ status, stdout, stderr });
+      });
+    });
+
+async function findClaude(candidates = agentUser() === null ? ['claude', join(homedir(), '.local', 'bin', 'claude')] : [claudeBin()]): Promise<Run | null> {
+  for (const bin of candidates) {
+    const run = runner(bin);
+    if ((await run(['--version'])).status === 0) return run;
+  }
+  return null;
+}
+
+function listOf(stdout: string): Record<string, unknown>[] {
+  try {
+    const parsed: unknown = JSON.parse(stdout);
+    return Array.isArray(parsed) ? parsed.filter(isRecord) : [];
+  } catch {
+    return [];
+  }
+}
+
+const realish = (path: string): string => {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+};
+
+const samePath = (a: string | null, b: string): boolean => a !== null && realish(a) === realish(b);
+
+async function step(run: Run, args: string[]): Promise<boolean> {
+  const answer = await run(args);
+  if (answer.status === 0) {
+    log.info({ args }, 'plugin: claude');
+    return true;
+  }
+  log.warn({ args, said: `${answer.stderr}${answer.stdout}`.trim().slice(0, SAID_MAX) }, 'plugin: claude refused');
+  return false;
+}
+
+async function marketplacePath(run: Run): Promise<string | null | undefined> {
+  const mine = listOf((await run(['plugin', 'marketplace', 'list', '--json'])).stdout).find((m) => m.name === MARKETPLACE);
+  if (mine === undefined) return undefined;
+  const at = mine.installLocation ?? mine.path;
+  return typeof at === 'string' ? at : null;
+}
+
+async function ensureMarketplace(run: Run, dir: string): Promise<boolean> {
+  const at = await marketplacePath(run);
+  if (at !== undefined && samePath(at, dir)) return true;
+  if (at !== undefined) await step(run, ['plugin', 'marketplace', 'remove', MARKETPLACE]);
+  return step(run, ['plugin', 'marketplace', 'add', dir]);
+}
+
+async function installedVersion(run: Run): Promise<string | null> {
+  const mine = listOf((await run(['plugin', 'list', '--json'])).stdout).find((p) => p.id === PLUGIN);
+  return mine !== undefined && typeof mine.version === 'string' ? mine.version : null;
+}
+
+async function ensureInstalled(run: Run, wanted: string | null): Promise<PluginOutcome> {
+  const have = await installedVersion(run);
+  if (have === null) return (await step(run, ['plugin', 'install', PLUGIN, '-y', '--scope', 'user'])) ? 'installed' : 'failed';
+  if (wanted === null || have === wanted) return 'unchanged';
+  await step(run, ['plugin', 'marketplace', 'update', MARKETPLACE]);
+  return (await step(run, ['plugin', 'update', PLUGIN, '-y'])) ? 'updated' : 'failed';
+}
+
+function explainMissingMarketplace(env: NodeJS.ProcessEnv = process.env): void {
+  const store = env.METRO_RUNTIME_STORE?.trim() ?? '';
+  if (store === '') return;
+  log.warn(
+    { store },
+    'plugin: the runtime store holds no plugin marketplace, so metro cannot install its Claude Code plugin; restart the metro service once so `metro serve` stages it again',
+  );
+}
+
+export async function ensureMetroPlugin(deps?: Partial<PluginInstallDeps>): Promise<PluginOutcome> {
+  const dir = deps?.marketplaceDir === undefined ? stagedMarketplaceDir() : deps.marketplaceDir;
+  if (dir === null) {
+    if (deps?.marketplaceDir === undefined) explainMissingMarketplace();
+    return 'skipped';
+  }
+  const run = deps?.run === undefined ? await findClaude() : deps.run;
+  if (run === null) {
+    log.info('plugin: claude is not on this machine, so metro leaves its Claude Code plugin alone');
+    return 'skipped';
+  }
+  if (!(await ensureMarketplace(run, dir))) return 'failed';
+  return ensureInstalled(run, stagedPluginVersion(dir));
+}

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

@@ -0,0 +1,17 @@
+import { join } from 'node:path';
+import { parseRunnerActivity, type RunnerActivity } from '@metro-labs/core/runner-activity';
+import { readRange } from '../agent-user/agent-fs.js';
+
+const MAX_BYTES = 65_536;
+
+export function readAgentActivity(home: string): RunnerActivity | null {
+  try {
+    const path = join(home, '.metro', 'agent-status.json');
+    const bytes = readRange(path, 0, MAX_BYTES + 1);
+    if (bytes.length > MAX_BYTES) return null;
+    const raw: unknown = JSON.parse(bytes.toString('utf8'));
+    return parseRunnerActivity(raw);
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,50 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { RunnerActivity } from '@metro-labs/core/runner-activity';
+import { ApiError } from '@metro-labs/http/api-error';
+import { asAgent } from '../agent-user/user.js';
+import { readAgentActivity } from './runner-activity.js';
+
+function identity(pid: number): { started: string; zombie: boolean } | null {
+  try {
+    const stat = readFileSync(`/proc/${String(pid)}/stat`, 'utf8');
+    const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+    return { started: fields[19] ?? '', zombie: fields[0] === 'Z' };
+  } catch {
+    return null;
+  }
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return isRecord(err) && err.code === 'EPERM';
+  }
+}
+
+export function sdkAlive(activity: RunnerActivity | null): boolean {
+  if (activity === null) return false;
+  const found = identity(activity.pid);
+  if (found?.zombie === true) return false;
+  if (activity.procStart !== undefined && found !== null && activity.procStart !== found.started) return false;
+  if (activity.procStart === undefined && activity.phase === 'stopped') return false;
+  return pidAlive(activity.pid);
+}
+
+function assertIdentity(activity: RunnerActivity): void {
+  const found = identity(activity.pid);
+  if (activity.pid === process.pid || activity.procStart === undefined || activity.procStart !== found?.started)
+    throw new ApiError('The Agent SDK is still running outside tmux, but its process identity cannot be verified safely. Stop that metro agent process from its terminal.', 503);
+}
+
+export function stopSdkRunner(home: string): void {
+  const activity = readAgentActivity(home);
+  if (activity === null || !sdkAlive(activity)) return;
+  assertIdentity(activity);
+  const run = spawnSync(...asAgent('kill', ['-TERM', String(activity.pid)]), { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if ((run.error !== undefined || run.status !== 0) && sdkAlive(activity))
+    throw new ApiError(`The Agent SDK could not be stopped: ${run.error?.message ?? run.stderr.trim()}`, 503);
+}

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

@@ -0,0 +1,45 @@
+import { agentsDir } from '../agents/files.js';
+import type { CodexMethod } from '../gateway/codex-auth.js';
+import { connectionOf, readModelConfig, routedConnection, type Connection, type ModelConfig } from '../gateway/model-config.js';
+import { readSetupState, writeSetupState } from './setup-state.js';
+
+const RUNNERS = ['cli', 'sdk'] as const;
+export type HarnessRunner = (typeof RUNNERS)[number];
+
+export const SDK_NEEDS_KEY =
+  'The Agent SDK runner needs an API key or a ChatGPT sign-in on every model the Model page lists, the first one and each fallback: use Anthropic with an API key, Amazon Bedrock, OpenRouter, or a signed-in Codex connection (with ChatGPT or with a code). Anthropic does not allow products built on the Agent SDK to use a Claude login, so on a login it runs only where the Metro operator allows it.';
+
+export const isHarnessRunner = (value: unknown): value is HarnessRunner => RUNNERS.some((r) => r === value);
+
+export function harnessRunner(agents = agentsDir()): HarnessRunner {
+  const runner = readSetupState(agents).runner;
+  return isHarnessRunner(runner) ? runner : 'cli';
+}
+
+export function setHarnessRunner(runner: HarnessRunner, agents = agentsDir()): void {
+  writeSetupState(agents, { runner });
+}
+
+export const sdkOnLogin = (agents = agentsDir()): boolean => readSetupState(agents).sdkOnLogin === true;
+
+export function setSdkOnLogin(on: boolean, agents = agentsDir()): void {
+  writeSetupState(agents, { sdkOnLogin: on });
+}
+
+const SDK_ON_CODEX: Record<CodexMethod, boolean> = { chatgpt: true, code: true };
+
+const permitted = (conn: Connection | null): boolean => conn !== null && (conn.apiKey !== '' || (conn.codex !== null && SDK_ON_CODEX[conn.codex.method]));
+
+const servingConnections = (cfg: ModelConfig): (Connection | null)[] => [routedConnection(cfg), ...(cfg.fallbacks ?? []).map((f) => connectionOf(cfg, f.connection))];
+
+const permittedRoute = (cfg: ModelConfig): boolean => servingConnections(cfg).every(permitted);
+
+export const sdkAllowed = (agents = agentsDir(), cfg: ModelConfig = readModelConfig(agents), loginAllowed?: boolean): boolean => permittedRoute(cfg) || (loginAllowed ?? sdkOnLogin(agents));
+
+export const sdkConnectionAllowed = (connection: Connection, agents = agentsDir()): boolean => permitted(connection) || sdkOnLogin(agents);
+
+export function runnerModel(cfg: ModelConfig): string | null {
+  const conn = routedConnection(cfg);
+  if (conn === null || conn.model === '') return null;
+  return conn.provider === 'anthropic' ? conn.model : `${conn.provider}:${conn.model}`;
+}

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

@@ -0,0 +1,48 @@
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { readJson, writeJson } from '@metro-labs/core/secure-fs';
+import { agentsDir } from '../agents/files.js';
+import { existsSync, readFileSync, realpathSync } from '../agent-user/agent-fs.js';
+import { claudeDir } from './files.js';
+
+const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const sessionId = (value: unknown): string | null => typeof value === 'string' && SESSION_ID_RE.test(value) ? value : null;
+
+function sdkSavedSession(home: string): Record<string, unknown> | null {
+  try {
+    const raw: unknown = JSON.parse(readFileSync(join(home, '.metro', 'agent-session.json'), 'utf8'));
+    return isRecord(raw) ? raw : null;
+  } catch (err) {
+    return isRecord(err) && err.code === 'ENOENT' ? {} : null;
+  }
+}
+
+export function sdkPending(home: string): number | null {
+  const state = sdkSavedSession(home);
+  if (state === null) return null;
+  if (state.sessionId !== undefined && state.sessionId !== null && sessionId(state.sessionId) === null) return null;
+  if (state.unanswered === undefined) return 0;
+  return Array.isArray(state.unanswered) ? state.unanswered.length : null;
+}
+
+function projectFolder(home: string, dir: string): string {
+  let cwd = home;
+  try {
+    cwd = realpathSync(home);
+  } catch {
+    cwd = home;
+  }
+  return join(dir, 'projects', cwd.replace(/[^A-Za-z0-9]/g, '-'));
+}
+
+export function continueArgs(home: string, dir = claudeDir(), agents = agentsDir()): string[] {
+  const path = join(agents, 'claude-session.json');
+  const raw = readJson<unknown>(path, null);
+  const state = isRecord(raw) ? raw : {};
+  const project = projectFolder(home, dir);
+  const pinned = sessionId(state.cliSessionId);
+  const id = pinned ?? randomUUID();
+  if (pinned === null) writeJson(path, { ...state, cliSessionId: id });
+  return [existsSync(join(project, `${id}.jsonl`)) ? '--resume' : '--session-id', id];
+}

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

@@ -0,0 +1,75 @@
+import { existsSync, statSync } from '../agent-user/agent-fs.js';
+import { Transform, type Readable } from 'node:stream';
+import { moveHome, receiveHomeFile, removeHome } from '../agent-user/home-fs.js';
+import { join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { isRecord } from '@metro-labs/core/is-record';
+import { claudeDir, PROJECT_RE, safeName, SESSION_RE } from './files.js';
+
+const SESSION_FILE_MAX = 512 * 1024 * 1024;
+const FILE_MODE = 0o644;
+
+export interface SessionFile {
+  id: string;
+  bytes: number;
+}
+
+const transcriptPath = (project: string, session: string, dir: string): string =>
+  join(dir, 'projects', safeName(project, PROJECT_RE, 'Claude project id'), `${safeName(session, SESSION_RE, 'session id')}.jsonl`);
+
+export function sessionFilePath(project: string, session: string, dir = claudeDir()): string {
+  const path = transcriptPath(project, session, dir);
+  if (!existsSync(path)) throw new ApiError('no such session', 404);
+  if (statSync(path).size > SESSION_FILE_MAX) throw new ApiError(`a session file is at most ${String(SESSION_FILE_MAX)} bytes`, 400);
+  return path;
+}
+
+const HEAD_BYTES = 64 * 1024;
+
+function watched(body: Readable, head: Buffer[]): Transform {
+  let total = 0;
+  let kept = 0;
+  const check = new Transform({
+    transform(chunk: Buffer, _enc, done): void {
+      total += chunk.length;
+      if (total > SESSION_FILE_MAX) {
+        done(new ApiError(`a session file is at most ${String(SESSION_FILE_MAX)} bytes`, 413));
+        return;
+      }
+      if (kept < HEAD_BYTES) {
+        head.push(chunk.subarray(0, HEAD_BYTES - kept));
+        kept += chunk.length;
+      }
+      done(null, chunk);
+    },
+  });
+  return body.pipe(check);
+}
+
+export async function receiveSessionFile(project: string, session: string, body: Readable, dir = claudeDir()): Promise<SessionFile> {
+  const path = transcriptPath(project, session, dir);
+  const tmp = `${path}.metro-upload`;
+  const head: Buffer[] = [];
+  try {
+    await receiveHomeFile(tmp, watched(body, head), FILE_MODE);
+  } catch (err) {
+    removeHome(tmp);
+    throw err;
+  }
+  if (!firstLineIsJson(Buffer.concat(head).toString('utf8'))) {
+    removeHome(tmp);
+    throw new ApiError('a session file is JSON lines, one Claude Code entry per line', 400);
+  }
+  moveHome(tmp, path);
+  return { id: safeName(session, SESSION_RE, 'session id'), bytes: statSync(path).size };
+}
+
+function firstLineIsJson(text: string): boolean {
+  const first = text.split('\n').find((line) => line.trim() !== '');
+  if (first === undefined) return false;
+  try {
+    return isRecord(JSON.parse(first));
+  } catch {
+    return false;
+  }
+}