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

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

@@ -0,0 +1,303 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { ApiError } from '@metro-labs/http/api-error';
+import type { RunnerActivity } from '@metro-labs/core/runner-activity';
+import { readAgentActivity } from './runner-activity.js';
+import { sdkAlive, stopSdkRunner } from './runner-process.js';
+import { syncAgentView } from '../agent-user/view.js';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { readJson, writeJson } from '@metro-labs/core/secure-fs';
+import { METRO_VERSION } from '@metro-labs/core/version';
+import { agentsDir, listAgentFiles } from '../agents/files.js';
+import { notReady, primaryRoute, type ModelSetup } from '../gateway/model-config.js';
+import { effectiveSetup } from '../gateway/effective.js';
+import { claudeAccount, claudeInstalled, forgetClaudeChecks } from './login.js';
+import { inSessionScope } from './memory.js';
+import { runningAsRoot } from '../metro-user/privilege.js';
+import { agentExtraEnv, agentUser, agentUserExpected, agentViewDir, asAgent, claudeHome } from '../agent-user/user.js';
+
+function sessionEnv(): Record<string, string> {
+  const user = agentUser();
+  if (user === null) return {};
+  const port = process.env.METRO_WEBHOOK_PORT?.trim() ?? '';
+  return { ...agentExtraEnv(), METRO_AGENTS_DIR: agentViewDir(user), ...(port === '' ? {} : { METRO_WEBHOOK_PORT: port }) };
+}
+
+const SESSION_NAME = 'metro';
+const STATE_FILE = 'claude-session.json';
+const WATCH_MS = 15_000;
+const STRIKE_WINDOW_MS = 60_000;
+const MAX_STRIKES = 5;
+const PAUSE_MS = 30 * 60_000;
+const PREPARE_MS = 16 * 60_000;
+
+export interface SessionDeps {
+  tmux?: string;
+  metro?: string[];
+  home?: string;
+  agents?: string;
+  signedIn?: () => boolean;
+  model?: () => ModelSetup;
+  now?: () => number;
+  version?: string;
+}
+
+export interface SessionStatus {
+  name: string;
+  running: boolean;
+  activity?: RunnerActivity | null;
+  autostart: boolean;
+  blocked: string | null;
+  lastStartedAt: string | null;
+  lastError: string | null;
+}
+
+export interface SessionSnapshot {
+  running: boolean;
+  activity: RunnerActivity | null;
+  lastStartedAt: string | null;
+}
+
+interface Memory {
+  lastStartedAt: number | null;
+  lastError: string | null;
+  strikes: number;
+  pausedUntil: number;
+}
+
+const memory: Memory = { lastStartedAt: null, lastError: null, strikes: 0, pausedUntil: 0 };
+
+const statePath = (agents: string): string => join(agents, STATE_FILE);
+
+function readState(agents: string): Record<string, unknown> {
+  const raw = readJson<unknown>(statePath(agents), null);
+  return isRecord(raw) ? raw : {};
+}
+
+const writeState = (agents: string, patch: Record<string, unknown>): void => {
+  writeJson(statePath(agents), { ...readState(agents), ...patch });
+};
+
+export const autostartEnabled = (agents = agentsDir()): boolean => readState(agents).autostart !== false;
+
+export function setAutostart(enabled: boolean, agents = agentsDir()): void {
+  writeState(agents, { autostart: enabled });
+}
+
+function startedVersion(agents = agentsDir()): string | null {
+  const version = readState(agents).version;
+  return typeof version === 'string' ? version : null;
+}
+
+function tmuxOk(tmux: string, args: string[]): boolean {
+  const run = spawnSync(...asAgent(tmux, args), { stdio: 'ignore' });
+  return run.error === undefined && run.status === 0;
+}
+
+export const sessionRunning = (tmux = 'tmux'): boolean => tmuxOk(tmux, ['has-session', '-t', SESSION_NAME]);
+
+export const tmuxServerUp = (tmux = 'tmux'): boolean => tmuxOk(tmux, ['list-sessions']);
+
+export function metroCli(args: string[], fixed?: string[]): string[] {
+  const bin = process.env.METRO_CLI_BIN?.trim() ?? '';
+  const runtime = agentUser() === null ? process.execPath : 'node';
+  const base = fixed ?? (bin === '' ? ['metro', ...args] : [runtime, bin, ...args]);
+  const env = Object.entries(sessionEnv()).map(([k, v]) => `${k}=${v}`);
+  return env.length === 0 || fixed !== undefined ? base : ['env', ...env, ...base];
+}
+
+const sessionHome = (deps: SessionDeps): string => deps.home ?? claudeHome() ?? homedir();
+
+export function assertSessionStopped(deps: SessionDeps = {}): void {
+  if (sessionLive(deps)) throw new ApiError('The session is running. Let it finish its work, stop it, then change its permissions or prompt and start it again.', 409);
+}
+
+export function prepareRunnerStore(): Promise<void> {
+  const [bin = 'metro', ...args] = metroCli(['agent', '--prepare']);
+  return new Promise<void>((resolve, reject) => {
+    const child = spawn(...asAgent(bin, args), { stdio: ['ignore', 'ignore', 'pipe'], cwd: '/', timeout: PREPARE_MS });
+    let said = '';
+    child.stderr.on('data', (chunk: Buffer) => {
+      said = (said + chunk.toString('utf8')).slice(-2000);
+    });
+    child.on('error', (err) => {
+      forgetClaudeChecks();
+      reject(err);
+    });
+    child.on('close', (code) => {
+      forgetClaudeChecks();
+      if (code === 0) resolve();
+      else reject(new Error(`metro agent --prepare failed: ${said.trim() || `exit ${String(code)}`}`));
+    });
+  });
+}
+
+const loginNotRuledOut = (): boolean => claudeAccount().signedIn || !claudeInstalled();
+
+function credentialReady(deps: SessionDeps): string | null {
+  const signedIn = deps.signedIn ?? loginNotRuledOut;
+  if (signedIn()) return null;
+  try {
+    const primary = primaryRoute((deps.model ?? (() => effectiveSetup(deps.agents ?? agentsDir())))());
+    if (primary !== null && notReady(primary) === null && (primary.connection.provider !== 'anthropic' || primary.connection.apiKey !== '')) return null;
+  } catch (err) {
+    return `the model setup is not readable (${errMsg(err)})`;
+  }
+  return 'Claude Code is not signed in and the organization routes this agent to no model yet';
+}
+
+const agentUserMissing = (deps: SessionDeps): boolean =>
+  deps.metro === undefined && agentUserExpected() && agentUser() === null;
+
+const ROOT_REFUSED = 'Metro runs as root; reinstall it as the metro user';
+
+export function sessionBlocked(deps: SessionDeps = {}): string | null {
+  if (runningAsRoot()) return ROOT_REFUSED;
+  if (listAgentFiles(deps.agents ?? agentsDir()).length === 0) return 'no agent on this machine yet';
+  return launchBlocked(deps);
+}
+
+function launchBlocked(deps: SessionDeps): string | null {
+  if (agentUserMissing(deps))
+    return 'Claude Code runs as the user agent here, and that user is not ready yet; see the log';
+  if (!tmuxOk(deps.tmux ?? 'tmux', ['-V'])) return 'tmux is not installed on this machine';
+  return credentialReady(deps);
+}
+
+function recordStart(deps: SessionDeps, now: number, run: { error?: Error; status: number | null; stderr: string }): void {
+  memory.lastStartedAt = now;
+  if (run.error !== undefined || run.status !== 0) {
+    memory.lastError = run.error === undefined ? `tmux new-session exited ${String(run.status)}: ${run.stderr.trim()}` : errMsg(run.error);
+    log.warn({ err: memory.lastError }, 'claude-session: tmux could not start');
+    return;
+  }
+  memory.lastError = null;
+  writeState(deps.agents ?? agentsDir(), { version: deps.version ?? METRO_VERSION });
+}
+
+function tmuxLaunch(deps: SessionDeps, tmux: string, args: string[]): [string, string[]] {
+  const launch = asAgent(tmux, args);
+  return deps.tmux === undefined && !tmuxServerUp(tmux) ? inSessionScope(launch) : launch;
+}
+
+export function startSession(deps: SessionDeps = {}): SessionStatus {
+  const status = sessionStatus(deps);
+  if (status.running) return status;
+  if (status.blocked !== null) throw new ApiError(`Cannot start the session: ${status.blocked}`, 409);
+  syncAgentView(undefined, deps.agents);
+  const tmux = deps.tmux ?? 'tmux';
+  const home = sessionHome(deps);
+  const now = (deps.now ?? Date.now)();
+  const [command = 'metro', ...args] = metroCli(['agent'], deps.metro);
+  const tmuxArgs = ['new-session', '-d', '-s', SESSION_NAME, '-c', home, '-x', '200', '-y', '50', command, ...args];
+  const launch = tmuxLaunch(deps, tmux, tmuxArgs);
+  const run = spawnSync(...launch, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], cwd: '/' });
+  recordStart(deps, now, run);
+  if (memory.lastError === null) log.info({ home, command: [command, ...args].join(' ') }, 'claude-session: started the Agent SDK runner in tmux');
+  return sessionStatus(deps);
+}
+
+export function stopSession(deps: SessionDeps = {}, cancelActive = false): SessionStatus {
+  if (!stopSdkRunner(sessionHome(deps), cancelActive))
+    spawnSync(...asAgent(deps.tmux ?? 'tmux', ['kill-session', '-t', SESSION_NAME]), { stdio: 'ignore' });
+  return sessionStatus(deps);
+}
+
+export const runnerAlive = (deps: SessionDeps = {}): boolean => sdkAlive(readAgentActivity(sessionHome(deps)));
+
+export const sessionLive = (deps: SessionDeps = {}): boolean => sessionRunning(deps.tmux ?? 'tmux') || runnerAlive(deps);
+
+export function sessionSnapshot(deps: SessionDeps = {}): SessionSnapshot {
+  const activity = readAgentActivity(sessionHome(deps));
+  return {
+    running: sdkAlive(activity) || sessionRunning(deps.tmux ?? 'tmux'),
+    activity,
+    lastStartedAt: memory.lastStartedAt === null ? null : new Date(memory.lastStartedAt).toISOString(),
+  };
+}
+
+export function sessionStatus(deps: SessionDeps = {}): SessionStatus {
+  return {
+    name: SESSION_NAME,
+    ...sessionSnapshot(deps),
+    autostart: autostartEnabled(deps.agents ?? agentsDir()),
+    blocked: sessionBlocked(deps),
+    lastError: memory.lastError,
+  };
+}
+
+function strike(now: number): boolean {
+  if (memory.lastStartedAt !== null && now - memory.lastStartedAt < STRIKE_WINDOW_MS) memory.strikes += 1;
+  else memory.strikes = 1;
+  if (memory.strikes < MAX_STRIKES) return false;
+  memory.pausedUntil = now + PAUSE_MS;
+  memory.strikes = 0;
+  log.warn({ pauseMinutes: PAUSE_MS / 60_000 }, 'claude-session: the session keeps exiting right after starting; not restarting it for a while');
+  return true;
+}
+
+export type Ensured = 'started' | 'restarted' | 'running' | 'blocked' | 'off' | 'paused';
+
+function holdsBack(deps: SessionDeps, now: number): Ensured | null {
+  if (now < memory.pausedUntil) return 'paused';
+  if (sessionBlocked(deps) !== null) return 'blocked';
+  return strike(now) ? 'paused' : null;
+}
+
+interface Resolved {
+  now: number;
+  agents: string;
+  version: string;
+  tmux: string;
+}
+
+const resolved = (deps: SessionDeps): Resolved => ({
+  now: (deps.now ?? Date.now)(),
+  agents: deps.agents ?? agentsDir(),
+  version: deps.version ?? METRO_VERSION,
+  tmux: deps.tmux ?? 'tmux',
+});
+
+function situation(r: Resolved): 'running' | 'stale' | 'absent' {
+  if (!sessionRunning(r.tmux)) return 'absent';
+  return startedVersion(r.agents) === r.version ? 'running' : 'stale';
+}
+
+export function ensureSession(deps: SessionDeps = {}): Ensured {
+  const r = resolved(deps);
+  if (!autostartEnabled(r.agents)) return 'off';
+  const found = situation(r);
+  if (found === 'running' || (found === 'absent' && sessionLive(deps))) return 'running';
+  const held = holdsBack(deps, r.now);
+  if (held !== null) return held;
+  if (found === 'stale') {
+    log.info({ was: startedVersion(r.agents), now: r.version }, 'claude-session: restarting the session an older metro started, so the new hooks and flags load');
+    stopSession(deps);
+  }
+  startSession(deps);
+  return found === 'stale' ? 'restarted' : 'started';
+}
+
+let watcher: ReturnType<typeof setInterval> | null = null;
+
+export function watchSession(deps: SessionDeps = {}, everyMs = WATCH_MS): void {
+  if (watcher !== null) return;
+  const tick = (): void => {
+    try {
+      const outcome = ensureSession(deps);
+      if (outcome === 'started' || outcome === 'restarted') log.info({ outcome }, 'claude-session: the Agent SDK runner is up');
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'claude-session: check failed');
+    }
+  };
+  watcher = setInterval(tick, everyMs);
+  watcher.unref();
+  setTimeout(tick, 1_000).unref();
+}
+
+export function unwatchSession(): void {
+  if (watcher !== null) clearInterval(watcher);
+  watcher = null;
+}

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

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync, realpathSync, statSync } from '../agent-user/agent-fs.js';
+import { join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { claudeDir, listClaudeProjects } from './files.js';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg } from '@metro-labs/core/log';
+import { writeHomeText } from '../agent-user/home-fs.js';
+
+export const SETTINGS_MAX = 256 * 1024;
+const USER_ID = 'user';
+const LOCAL_SUFFIX = '.local';
+
+type SettingsScope = 'user' | 'project' | 'local';
+
+export interface ClaudeSettingsFile {
+  id: string;
+  scope: SettingsScope;
+  label: string;
+  path: string;
+  exists: boolean;
+  editable: boolean;
+  text: string;
+  modifiedAt: string | null;
+}
+
+const missing = (id: string, scope: SettingsScope, label: string, path: string): ClaudeSettingsFile => ({
+  id,
+  scope,
+  label,
+  path,
+  exists: false,
+  editable: true,
+  text: '',
+  modifiedAt: null,
+});
+
+function entryOf(id: string, scope: SettingsScope, label: string, path: string): ClaudeSettingsFile {
+  if (!existsSync(path)) return missing(id, scope, label, path);
+  const stat = statSync(path);
+  const editable = stat.size <= SETTINGS_MAX;
+  return {
+    id,
+    scope,
+    label,
+    path,
+    exists: true,
+    editable,
+    text: editable ? readFileSync(path, 'utf8') : '',
+    modifiedAt: stat.mtime.toISOString(),
+  };
+}
+
+const PROJECT_FILES: [string, SettingsScope, string][] = [
+  ['', 'project', 'settings.json'],
+  [LOCAL_SUFFIX, 'local', 'settings.local.json'],
+];
+
+function projectEntries(dir: string): ClaudeSettingsFile[] {
+  const out: ClaudeSettingsFile[] = [];
+  for (const project of listClaudeProjects(dir)) {
+    const cwd = project.cwd;
+    if (cwd === null) continue;
+    for (const [suffix, scope, name] of PROJECT_FILES) {
+      const path = join(cwd, '.claude', name);
+      if (existsSync(path)) out.push(entryOf(`${project.id}${suffix}`, scope, cwd, path));
+    }
+  }
+  return out;
+}
+
+const sameFile = (a: string, b: string): boolean => {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return a === b;
+  }
+};
+
+export function listClaudeSettings(dir = claudeDir()): ClaudeSettingsFile[] {
+  const user = entryOf(USER_ID, 'user', 'This machine', join(dir, 'settings.json'));
+  return [user, ...projectEntries(dir).filter((p) => !sameFile(p.path, user.path))];
+}
+
+function assertSettingsJson(text: string): void {
+  if (text.length > SETTINGS_MAX) throw new ApiError('that is more text than a settings file may hold', 413);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new ApiError(`that is not valid JSON: ${errMsg(err)}`, 400);
+  }
+  if (!isRecord(parsed)) throw new ApiError('Claude Code settings must be a JSON object', 400);
+}
+
+export function writeClaudeSettings(
+  id: string,
+  text: string,
+  seenAt: string | null | undefined,
+  dir = claudeDir(),
+): ClaudeSettingsFile {
+  const target = listClaudeSettings(dir).find((file) => file.id === id);
+  if (target === undefined) throw new ApiError('no such settings file', 404);
+  if (!target.editable) throw new ApiError('that settings file is too large to edit here', 409);
+  assertSettingsJson(text);
+  if (seenAt !== undefined && seenAt !== target.modifiedAt)
+    throw new ApiError('that file changed on disk since you opened it; reload it before saving', 409);
+  writeHomeText(target.path, text, existsSync(target.path) ? statSync(target.path).mode & 0o777 : 0o644);
+  return entryOf(target.id, target.scope, target.label, target.path);
+}

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

@@ -0,0 +1,114 @@
+import type { IncomingMessage } from 'node:http';
+import { isRecord } from '@metro-labs/core/is-record';
+import { ApiError } from '@metro-labs/http/api-error';
+import { readJsonBody } from '@metro-labs/http/api-http';
+import {
+  claudeSetupStatus,
+  ensureClaudeSetup,
+  isPermissionMode,
+  liveEvents,
+  permissionMode,
+  setLiveEvents,
+  setMemoryRoutine,
+  setPermissionMode,
+  setPrivacy,
+  setSystemPrompt,
+  systemPrompt,
+  SYSTEM_PROMPT_MAX,
+  type PermissionMode,
+  type SetupDeps,
+} from './setup.js';
+import { assertSessionStopped, type SessionDeps } from './session.js';
+import { tryMemoryJob } from './memory-routine.js';
+
+const SETUP_BODY_MAX = SYSTEM_PROMPT_MAX * 2;
+
+export interface SetupApiDeps {
+  session?: SessionDeps;
+  setup?: SetupDeps;
+  liveEvents?: (on: boolean) => void;
+  memoryJob?: (on: boolean) => void;
+}
+
+interface SetupChange {
+  privacy?: boolean;
+  permissionMode?: PermissionMode;
+  systemPrompt?: string;
+  liveEvents?: boolean;
+  memoryRoutine?: boolean;
+}
+
+function promptChange(raw: unknown): string | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== 'string') throw new ApiError('systemPrompt must be text', 400);
+  if (Buffer.byteLength(raw) > SYSTEM_PROMPT_MAX) throw new ApiError(`systemPrompt must be under ${String(SYSTEM_PROMPT_MAX / 1024)} KiB`, 400);
+  return raw;
+}
+
+function flagChange(raw: unknown, name: string): boolean | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== 'boolean') throw new ApiError(`${name} must be true or false`, 400);
+  return raw;
+}
+
+function modeChange(raw: unknown): PermissionMode | undefined {
+  if (raw === undefined) return undefined;
+  if (!isPermissionMode(raw)) throw new ApiError('permissionMode must be auto or bypass', 400);
+  return raw;
+}
+
+function setupChange(body: unknown): SetupChange {
+  if (!isRecord(body)) throw new ApiError('a body is required', 400);
+  const change: SetupChange = {
+    privacy: flagChange(body.privacy, 'privacy'),
+    permissionMode: modeChange(body.permissionMode),
+    systemPrompt: promptChange(body.systemPrompt),
+    liveEvents: flagChange(body.liveEvents, 'liveEvents'),
+    memoryRoutine: flagChange(body.memoryRoutine, 'memoryRoutine'),
+  };
+  const given = Object.fromEntries(Object.entries(change).filter(([, value]) => value !== undefined)) as SetupChange;
+  if (Object.keys(given).length === 0) throw new ApiError('nothing to change', 400);
+  return given;
+}
+
+function changesSession(change: SetupChange, agents: string | undefined): boolean {
+  return (change.permissionMode !== undefined && change.permissionMode !== permissionMode(agents))
+    || (change.systemPrompt !== undefined && change.systemPrompt.trim() !== systemPrompt(agents));
+}
+
+function applyLiveEvents(on: boolean, deps: SetupApiDeps): void {
+  const agents = deps.setup?.agents;
+  if (on !== liveEvents(agents)) setLiveEvents(on, agents);
+  deps.liveEvents?.(on);
+}
+
+function applyMemoryRoutine(on: boolean, deps: SetupApiDeps): void {
+  setMemoryRoutine(on, deps.setup?.agents);
+  (deps.memoryJob ?? tryMemoryJob)(on);
+}
+
+function saveSessionSettings(change: SetupChange, deps: SetupApiDeps): void {
+  const agents = deps.setup?.agents;
+  if (changesSession(change, agents)) assertSessionStopped({ ...deps.session, agents: deps.session?.agents ?? agents });
+  if (change.permissionMode !== undefined) setPermissionMode(change.permissionMode, agents);
+  if (change.systemPrompt !== undefined) setSystemPrompt(change.systemPrompt, agents);
+}
+
+function applySetupChange(change: SetupChange, deps: SetupApiDeps): void {
+  const setup = deps.setup ?? {};
+  saveSessionSettings(change, deps);
+  if (change.privacy !== undefined) setPrivacy(change.privacy, setup.agents);
+  if (change.liveEvents !== undefined) applyLiveEvents(change.liveEvents, deps);
+  if (change.memoryRoutine !== undefined) applyMemoryRoutine(change.memoryRoutine, deps);
+  ensureClaudeSetup(setup);
+}
+
+export async function setupAnswer(req: IncomingMessage, deps: SetupApiDeps): Promise<unknown> {
+  const setup = deps.setup ?? {};
+  const method = req.method ?? 'GET';
+  if (method === 'GET') return claudeSetupStatus(setup);
+  if (method !== 'POST') throw new ApiError('method not allowed', 405);
+  const change = setupChange(await readJsonBody(req, SETUP_BODY_MAX));
+  applySetupChange(change, deps);
+  return claudeSetupStatus(setup);
+}

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

@@ -0,0 +1,18 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { readJson, writeJson } from '@metro-labs/core/secure-fs';
+
+const STATE_FILE = 'claude-setup.json';
+
+const statePath = (agents: string): string => join(agents, STATE_FILE);
+
+export function readSetupState(agents: string): Record<string, unknown> {
+  const raw = readJson<unknown>(statePath(agents), null);
+  return isRecord(raw) ? raw : {};
+}
+
+export function writeSetupState(agents: string, patch: Record<string, unknown>): void {
+  mkdirSync(agents, { recursive: true });
+  writeJson(statePath(agents), { ...readSetupState(agents), ...patch });
+}