@stage-labs/metro 0.1.0-beta.30 → 0.1.0-beta.301

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

@@ -0,0 +1,382 @@
+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 { continueArgs, sdkPending } from './session-continuity.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, readModelConfig, routedConnection } from '../gateway/model-config.js';
+import { claudeDir } from './files.js';
+import { harnessRunner, isHarnessRunner, sdkAllowed, SDK_NEEDS_KEY, type HarnessRunner } from './runner.js';
+import { claudeAccount, claudeInstalled } from './login.js';
+import { trustFolder } from './onboarding.js';
+import { inSessionScope } from './memory.js';
+import { channelState, forgetChannelState, noteChannelState, type ChannelState } from './channel-check.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 WARNING = 'WARNING: Loading development channels';
+const CONFIRM_POLL_MS = 500;
+const CONFIRM_WAIT_MS = 60_000;
+const WATCH_MS = 15_000;
+const STRIKE_WINDOW_MS = 60_000;
+const MAX_STRIKES = 5;
+const PAUSE_MS = 30 * 60_000;
+
+export interface SessionDeps {
+  tmux?: string;
+  metro?: string[];
+  runner?: string[];
+  home?: string;
+  agents?: string;
+  signedIn?: () => boolean;
+  now?: () => number;
+  version?: string;
+  prepare?: (runner: HarnessRunner) => Promise<void>;
+}
+
+export interface SessionStatus {
+  name: string;
+  running: boolean;
+  runner?: HarnessRunner;
+  activity?: RunnerActivity | null;
+  autostart: boolean;
+  blocked: string | null;
+  lastStartedAt: string | null;
+  lastError: string | null;
+  channels?: ChannelState | null;
+}
+
+export interface SessionSnapshot {
+  running: boolean;
+  runner: HarnessRunner | null;
+  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 sessionRunner(deps: SessionDeps = {}): HarnessRunner {
+  const agents = deps.agents ?? agentsDir();
+  const runner = readState(agents).runner;
+  return isHarnessRunner(runner) ? runner : harnessRunner(agents);
+}
+
+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 runner, permissions or prompt and start it again.', 409);
+}
+
+export function assertSdkDrained(deps: SessionDeps = {}): void {
+  if (sdkPending(sessionHome(deps)) !== 0)
+    throw new ApiError('The Agent SDK still has chat messages it has not answered, or its saved state cannot be read. Start it so it answers them (fix the Model page first if it cannot start), stop it, then switch runners.', 409);
+}
+
+let changing = false;
+
+export async function withSessionChange<T>(run: () => Promise<T>): Promise<T> {
+  if (changing) throw new ApiError('A session change is already being prepared. Try again when it finishes.', 409);
+  changing = true;
+  try {
+    return await run();
+  } finally {
+    changing = false;
+  }
+}
+
+export async function prepareSessionRunner(runner: HarnessRunner, deps: SessionDeps = {}): Promise<void> {
+  if (deps.prepare !== undefined) return deps.prepare(runner);
+  const [bin = 'metro', ...args] = metroCli(['agent', '--prepare', runner]);
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(...asAgent(bin, args), { stdio: ['ignore', 'ignore', 'pipe'], timeout: 16 * 60_000 });
+    let error = '';
+    child.stderr.on('data', (chunk: Buffer) => { error = (error + chunk.toString()).slice(-2000); });
+    child.on('error', (err) => { reject(new ApiError(`Runner preparation failed: ${errMsg(err)}`, 503)); });
+    child.on('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new ApiError(`Runner preparation failed. The runner choice was not changed. ${error.trim()}`, 503));
+    });
+  });
+}
+
+function metroCommand(deps: SessionDeps, home: string): string[] {
+  if (harnessRunner(deps.agents ?? agentsDir()) === 'sdk') return metroCli(['agent'], deps.runner);
+  return [...metroCli(['claude'], deps.metro), ...continueArgs(home, claudeDir(), deps.agents)];
+}
+
+function credentialReady(deps: SessionDeps): string | null {
+  const signedIn = deps.signedIn ?? (() => claudeAccount().signedIn);
+  if (signedIn()) return null;
+  try {
+    const cfg = readModelConfig(deps.agents ?? agentsDir());
+    const conn = routedConnection(cfg);
+    if (conn !== null && notReady(cfg) === null && (conn.provider !== 'anthropic' || conn.apiKey !== '')) return null;
+  } catch (err) {
+    return `the Model page is not readable (${errMsg(err)})`;
+  }
+  return 'Claude Code is not signed in and the Model page routes nowhere 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;
+  const agents = deps.agents ?? agentsDir();
+  if (harnessRunner(agents) === 'sdk' && !sdkAllowed(agents)) return SDK_NEEDS_KEY;
+  if (listAgentFiles(agents).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 (deps.metro === undefined && !claudeInstalled()) return 'Claude Code is not installed on this machine';
+  if (!tmuxOk(deps.tmux ?? 'tmux', ['-V'])) return 'tmux is not installed on this machine';
+  return credentialReady(deps);
+}
+
+function capturePane(tmux: string): string {
+  const run = spawnSync(...asAgent(tmux, ['capture-pane', '-p', '-t', SESSION_NAME]), { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  return run.error === undefined && run.status === 0 ? run.stdout : '';
+}
+
+function noteLaunchLines(pane: string, seen: Set<string>): void {
+  for (const line of pane.split('\n').map((l) => l.trim()))
+    if (line.startsWith('metro claude:') && !seen.has(line)) {
+      seen.add(line);
+      log.info({ line }, 'claude-session: metro claude said');
+    }
+}
+
+function confirmChannels(tmux: string, home: string, startedAt: number): void {
+  const until = startedAt + CONFIRM_WAIT_MS;
+  const seen = new Set<string>();
+  let confirmed = false;
+  let checked = false;
+  const tick = (): void => {
+    const pane = capturePane(tmux);
+    noteLaunchLines(pane, seen);
+    checked ||= noteChannelState(home, startedAt);
+    if (!confirmed && pane.includes(WARNING) && pane.includes('server:metro')) {
+      spawnSync(...asAgent(tmux, ['send-keys', '-t', SESSION_NAME, 'Enter']), { stdio: 'ignore' });
+      log.info('claude-session: confirmed the development channels dialog for server:metro');
+      confirmed = true;
+    }
+    if (Date.now() < until && sessionRunning(tmux)) setTimeout(tick, CONFIRM_POLL_MS).unref();
+  };
+  setTimeout(tick, CONFIRM_POLL_MS).unref();
+}
+
+function recordStart(deps: SessionDeps, tmux: string, now: number, run: { error?: Error; status: number | null; stderr: string }): void {
+  memory.lastStartedAt = now;
+  forgetChannelState();
+  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;
+  const agents = deps.agents ?? agentsDir();
+  writeState(agents, { version: deps.version ?? METRO_VERSION, runner: harnessRunner(agents) });
+  confirmChannels(tmux, sessionHome(deps), now);
+}
+
+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 {
+  if (changing) throw new ApiError('A runner change is being prepared. Start the session after it finishes.', 409);
+  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 trusted = trustFolder(home);
+  const [command = 'metro', ...args] = metroCommand(deps, home);
+  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, tmux, now, run);
+  if (memory.lastError === null) log.info({ home, trusted, command: [command, ...args].join(' ') }, 'claude-session: started Claude Code 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 sessionLive = (deps: SessionDeps = {}): boolean =>
+  sessionRunning(deps.tmux ?? 'tmux') || sdkAlive(readAgentActivity(sessionHome(deps)));
+
+export function sessionSnapshot(deps: SessionDeps = {}): SessionSnapshot {
+  const activity = readAgentActivity(sessionHome(deps));
+  const sdk = sdkAlive(activity);
+  const tmux = sessionRunning(deps.tmux ?? 'tmux');
+  const runner = sdk ? 'sdk' : tmux ? readState(deps.agents ?? agentsDir()).runner : null;
+  return {
+    running: tmux || sdk,
+    runner: isHarnessRunner(runner) ? runner : null,
+    activity,
+    lastStartedAt: memory.lastStartedAt === null ? null : new Date(memory.lastStartedAt).toISOString(),
+  };
+}
+
+export function sessionStatus(deps: SessionDeps = {}): SessionStatus {
+  const snapshot = sessionSnapshot(deps);
+  return {
+    name: SESSION_NAME,
+    ...snapshot,
+    runner: snapshot.runner ?? sessionRunner(deps),
+    autostart: autostartEnabled(deps.agents ?? agentsDir()),
+    blocked: sessionBlocked(deps),
+    lastError: memory.lastError,
+    channels: channelState(),
+  };
+}
+
+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: Claude Code 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';
+  if (changing) return 'blocked';
+  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 plugin 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: Claude Code 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,161 @@
+import type { IncomingMessage } from 'node:http';
+import { log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { ApiError } from '@metro-labs/http/api-error';
+import { readJsonBody, type ApiSession } 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 { harnessRunner, isHarnessRunner, sdkAllowed, sdkOnLogin, SDK_NEEDS_KEY, setHarnessRunner, setSdkOnLogin, type HarnessRunner } from './runner.js';
+import { assertSdkDrained, assertSessionStopped, prepareSessionRunner, setAutostart, withSessionChange, type SessionDeps } from './session.js';
+import { tryMemoryJob } from './memory-routine.js';
+
+const SETUP_BODY_MAX = SYSTEM_PROMPT_MAX * 2;
+const OPERATOR_ONLY = 'only the Metro operator can allow the Agent SDK on a Claude login';
+
+export interface SetupApiDeps {
+  session?: SessionDeps;
+  setup?: SetupDeps;
+  liveEvents?: (on: boolean) => void;
+  memoryJob?: (on: boolean) => void;
+}
+
+interface SetupChange {
+  privacy?: boolean;
+  permissionMode?: PermissionMode;
+  runner?: HarnessRunner;
+  sdkOnLogin?: boolean;
+  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 runnerChange(raw: unknown): HarnessRunner | undefined {
+  if (raw === undefined) return undefined;
+  if (!isHarnessRunner(raw)) throw new ApiError('runner must be cli or sdk', 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),
+    runner: runnerChange(body.runner),
+    sdkOnLogin: flagChange(body.sdkOnLogin, 'sdkOnLogin'),
+    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 checkRunnerChange(change: SetupChange, session: ApiSession, agents: string | undefined): void {
+  if (change.sdkOnLogin !== undefined && session.operator !== true) throw new ApiError(OPERATOR_ONLY, 403);
+  if (change.runner === 'sdk' && !sdkAllowed(agents, undefined, change.sdkOnLogin ?? sdkOnLogin(agents))) throw new ApiError(SDK_NEEDS_KEY, 403);
+}
+
+function nextRunner(change: SetupChange, agents: string | undefined): HarnessRunner {
+  const runner = change.runner ?? harnessRunner(agents);
+  return runner === 'sdk' && change.sdkOnLogin === false && !sdkAllowed(agents, undefined, false) ? 'cli' : runner;
+}
+
+function changesSession(change: SetupChange, agents: string | undefined): boolean {
+  return nextRunner(change, agents) !== harnessRunner(agents)
+    || (change.permissionMode !== undefined && change.permissionMode !== permissionMode(agents))
+    || (change.systemPrompt !== undefined && change.systemPrompt.trim() !== systemPrompt(agents));
+}
+
+function saveSessionSettings(change: SetupChange, runner: HarnessRunner, agents: string | undefined): void {
+  if (change.sdkOnLogin !== undefined && change.sdkOnLogin !== sdkOnLogin(agents)) {
+    setSdkOnLogin(change.sdkOnLogin, agents);
+    log.info({ on: change.sdkOnLogin }, 'claude-setup: the operator changed whether the Agent SDK may run on this box’s Claude login');
+  }
+  if (runner !== harnessRunner(agents)) {
+    setAutostart(false, agents);
+    setHarnessRunner(runner, agents);
+  }
+  if (change.permissionMode !== undefined) setPermissionMode(change.permissionMode, agents);
+  if (change.systemPrompt !== undefined) setSystemPrompt(change.systemPrompt, agents);
+}
+
+function checkStoppedChange(change: SetupChange, deps: SetupApiDeps): HarnessRunner {
+  const agents = deps.setup?.agents;
+  const session = { ...deps.session, agents: deps.session?.agents ?? agents };
+  const runner = nextRunner(change, agents);
+  if (changesSession(change, agents)) assertSessionStopped(session);
+  if (runner !== harnessRunner(agents) && harnessRunner(agents) === 'sdk') assertSdkDrained(session);
+  return runner;
+}
+
+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);
+}
+
+async function applySetupChange(change: SetupChange, session: ApiSession, deps: SetupApiDeps, req: IncomingMessage): Promise<void> {
+  const setup = deps.setup ?? {};
+  checkRunnerChange(change, session, setup.agents);
+  const runner = checkStoppedChange(change, deps);
+  if (runner !== harnessRunner(setup.agents)) {
+    await prepareSessionRunner(runner, deps.session);
+    checkRunnerChange(change, session, setup.agents);
+    if (checkStoppedChange(change, deps) !== runner) throw new ApiError('The model setup changed during preparation. Choose the runner again.', 409);
+  }
+  if (req.socket.destroyed) throw new ApiError('The request disconnected during preparation. The runner choice was not changed.', 409);
+  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);
+  saveSessionSettings(change, runner, setup.agents);
+  ensureClaudeSetup(setup);
+}
+
+export async function setupAnswer(req: IncomingMessage, deps: SetupApiDeps, session: ApiSession): 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));
+  await withSessionChange(() => applySetupChange(change, session, deps, req));
+  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 });
+}