@stage-labs/metro 0.1.0-beta.23 → 0.1.0-beta.231

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/home-fs.ts

@@ -0,0 +1,113 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { createWriteStream, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { writeAtomic } from '@metro-labs/core/secure-fs';
+import { agentUser, asUser, type AgentUser } from './user.js';
+
+const WRITE = [
+  'set -e',
+  'mkdir -p -- "$(dirname -- "$1")"',
+  'tmp=$(mktemp -- "$1.metro-XXXXXX")',
+  'trap \'rm -f -- "$tmp"\' EXIT',
+  'cat > "$tmp"',
+  'chmod -- "$2" "$tmp"',
+  'if [ -n "$3" ]; then touch -d "@$3" -- "$tmp"; fi',
+  'mv -f -- "$tmp" "$1"',
+  'trap - EXIT',
+].join('\n');
+
+const octal = (mode: number): string => mode.toString(8);
+const epoch = (mtime: Date | undefined): string => (mtime === undefined ? '' : String(Math.floor(mtime.getTime() / 1000)));
+
+function runAs(user: AgentUser, script: string, args: string[], input?: string): void {
+  const [file, argv] = asUser(user, 'sh', ['-c', script, 'metro', ...args]);
+  const run = spawnSync(file, argv, { input, encoding: 'utf8', stdio: ['pipe', 'ignore', 'pipe'] });
+  if (run.error !== undefined) throw run.error;
+  if (run.status !== 0) throw new Error(`as ${user.name}: ${run.stderr.trim() || `exit ${String(run.status)}`}`);
+}
+
+export function writeHomeText(path: string, text: string, mode = 0o644, mtime?: Date, user = agentUser()): void {
+  if (user !== null) {
+    runAs(user, WRITE, [path, octal(mode), epoch(mtime)], text);
+    return;
+  }
+  writeAtomic(path, text, mode);
+  if (mtime !== undefined) utimesSync(path, mtime, mtime);
+}
+
+export function writeHomeInPlace(path: string, text: string, mode = 0o644, user = agentUser()): void {
+  if (user !== null) {
+    runAs(user, 'mkdir -p -- "$(dirname -- "$1")"; cat > "$1"; chmod -- "$2" "$1"', [path, octal(mode)], text);
+    return;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, text, { mode });
+}
+
+function filesUnder(root: string, rel = ''): string[] {
+  return readdirSync(join(root, rel), { withFileTypes: true }).flatMap((entry) => {
+    const inner = rel === '' ? entry.name : `${rel}/${entry.name}`;
+    if (entry.isDirectory()) return filesUnder(root, inner);
+    return entry.isFile() ? [inner] : [];
+  });
+}
+
+export function copyIntoHome(from: string, to: string, user = agentUser()): number {
+  removeHome(to, true, user);
+  const files = filesUnder(from);
+  for (const rel of files) {
+    const source = join(from, rel);
+    writeHomeText(join(to, rel), readFileSync(source, 'utf8'), statSync(source).mode & 0o777, undefined, user);
+  }
+  return files.length;
+}
+
+export function removeHome(path: string, recursive = false, user = agentUser()): void {
+  if (user !== null) {
+    runAs(user, recursive ? 'rm -rf -- "$1"' : 'rm -f -- "$1"', [path]);
+    return;
+  }
+  rmSync(path, { recursive, force: true });
+}
+
+export function moveHome(from: string, to: string, user = agentUser()): void {
+  if (user !== null) {
+    runAs(user, 'mv -f -- "$1" "$2"', [from, to]);
+    return;
+  }
+  renameSync(from, to);
+}
+
+async function receiveAs(user: AgentUser, path: string, source: Readable, mode: number): Promise<void> {
+  const [file, argv] = asUser(user, 'sh', ['-c', WRITE, 'metro', path, octal(mode), '']);
+  const child = spawn(file, argv, { stdio: ['pipe', 'ignore', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', (chunk: Buffer) => {
+    stderr += chunk.toString('utf8');
+  });
+  const closed = new Promise<number | null>((resolve, reject) => {
+    child.on('error', reject);
+    child.on('close', resolve);
+  });
+  await pipeline(source, child.stdin);
+  const status = await closed;
+  if (status !== 0) throw new Error(`as ${user.name}: ${stderr.trim() || `exit ${String(status)}`}`);
+}
+
+export async function receiveHomeFile(path: string, source: Readable, mode = 0o600, user = agentUser()): Promise<void> {
+  if (user !== null) {
+    await receiveAs(user, path, source, mode);
+    return;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.metro-${String(process.pid)}.part`;
+  try {
+    await pipeline(source, createWriteStream(tmp, { mode }));
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/job-env.ts

@@ -0,0 +1,39 @@
+import { join } from 'node:path';
+import { log } from '@metro-labs/core/log';
+import { editCrontab, withBlock } from './crontab.js';
+import { writeHomeText } from './home-fs.js';
+import { listSchedules, realRunner, showProps, type Runner } from './schedules.js';
+import type { AgentUser } from './user.js';
+import { removeDropIn, writeDropIn } from './unit-files.js';
+
+const DROP_IN = '11-metro-vault.conf';
+const BEGIN = '# metro vault: begin';
+const END = '# metro vault: end';
+
+const jobEnvFile = (user: AgentUser): string => join(user.home, '.metro', 'vault.env');
+
+export function withCronEnv(lines: string[], env: Record<string, string>): string[] {
+  return withBlock(lines, BEGIN, END, Object.entries(env).map(([k, v]) => `${k}=${v}`), 'top');
+}
+
+function setTimerEnv(user: AgentUser, on: boolean, runner: Runner): void {
+  let changed = false;
+  for (const job of listSchedules(user, runner)) {
+    if (job.kind !== 'timer' || job.runsAs !== user.name) continue;
+    const unit = job.id.slice('timer:'.length);
+    const service = showProps(runner, unit, ['Unit']).Unit ?? unit.replace(/\.timer$/, '.service');
+    if (on) {
+      writeDropIn(service, DROP_IN, `[Service]\nEnvironmentFile=-${jobEnvFile(user)}\n`);
+      changed = true;
+    } else if (removeDropIn(service, DROP_IN)) changed = true;
+  }
+  if (changed) runner.run('systemctl', ['daemon-reload']);
+}
+
+export function exportJobEnv(user: AgentUser, env: Record<string, string>, runner: Runner = realRunner): void {
+  const on = Object.keys(env).length > 0;
+  writeHomeText(jobEnvFile(user), Object.entries(env).map(([k, v]) => `${k}=${v}\n`).join(''), 0o644);
+  editCrontab(user, runner, (lines) => withCronEnv(lines, env));
+  setTimerEnv(user, on, runner);
+  log.info({ on, keys: Object.keys(env).length }, "vault: the agent's scheduled jobs use the vault settings");
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/provision.ts

@@ -0,0 +1,80 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from './agent-fs.js';
+import { join } from 'node:path';
+import { chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { errMsg, log } from '@metro-labs/core/log';
+import { copyIntoHome } from './home-fs.js';
+import { AGENT_NAME, agentMarketplaceDir, agentUser, agentUserExpected, asUser, claudeBin, forgetAgentUser, type AgentUser } from './user.js';
+import { watchAgentView } from './view.js';
+import { mustHelper } from '../metro-user/privilege.js';
+import { stagedPluginVersion } from '../claude/plugin-install.js';
+
+const INSTALL_MS = 10 * 60_000;
+const INSTALLER = 'curl -fsSL https://claude.ai/install.sh | bash';
+
+export type Provisioned = 'off' | 'failed' | 'ready';
+
+function run(file: string, args: string[]): void {
+  const done = spawnSync(file, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if (done.error !== undefined) throw done.error;
+  if (done.status !== 0) throw new Error(`${file} ${args.join(' ')}: ${done.stderr.trim() || `exit ${String(done.status)}`}`);
+}
+
+function openMetroHome(): void {
+  chmodSync(homedir(), 0o711);
+  chmodSync(join(homedir(), '.metro'), 0o700);
+}
+
+function ensureUser(): AgentUser | null {
+  mustHelper(['ensure-agent']);
+  openMetroHome();
+  forgetAgentUser();
+  const user = agentUser();
+  if (user !== null) run(...asUser(user, 'chmod', ['711', user.home]));
+  return user;
+}
+
+function installClaude(user: AgentUser): Promise<void> {
+  if (existsSync(claudeBin(user))) return Promise.resolve();
+  const [file, args] = asUser(user, 'bash', ['-c', INSTALLER]);
+  return new Promise((resolve, reject) => {
+    const child = spawn(file, args, { stdio: ['ignore', 'ignore', 'pipe'], cwd: '/', timeout: INSTALL_MS });
+    let said = '';
+    child.stderr.on('data', (chunk: Buffer) => {
+      said = `${said}${chunk.toString('utf8')}`.slice(-2000);
+    });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0 && existsSync(claudeBin(user))) {
+        log.info({ user: user.name }, 'agent-user: installed Claude Code for the agent user');
+        resolve();
+      } else reject(new Error(`the Claude Code installer failed: ${said.trim() || `exit ${String(code)}`}`));
+    });
+  });
+}
+
+function copyMarketplace(user: AgentUser, env: NodeJS.ProcessEnv): void {
+  const store = env.METRO_RUNTIME_STORE?.trim() ?? '';
+  const from = join(store, 'marketplace');
+  if (store === '' || !existsSync(join(from, '.claude-plugin', 'marketplace.json'))) return;
+  const to = agentMarketplaceDir(user);
+  if (stagedPluginVersion(from) !== null && stagedPluginVersion(from) === stagedPluginVersion(to)) return;
+  const files = copyIntoHome(from, to, user);
+  log.info({ files, version: stagedPluginVersion(from) }, 'agent-user: copied the metro plugin where the agent user can load it');
+}
+
+export async function provisionAgentUser(env: NodeJS.ProcessEnv = process.env): Promise<Provisioned> {
+  if (!agentUserExpected()) return 'off';
+  try {
+    const user = ensureUser();
+    if (user === null) throw new Error(`the user ${AGENT_NAME} could not be found after creating it`);
+    await installClaude(user);
+    copyMarketplace(user, env);
+    watchAgentView();
+    return 'ready';
+  } catch (err) {
+    log.error({ user: AGENT_NAME, err: errMsg(err) }, 'agent-user: could not prepare the agent user; the Claude session stays stopped');
+    return 'failed';
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/schedule-detail.ts

@@ -0,0 +1,99 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, readRange, statSync } from './agent-fs.js';
+import { ApiError } from '@metro-labs/http/api-error';
+import { log } from '@metro-labs/core/log';
+import { listSchedules, realRunner, showProps, type Runner, type ScheduledJob } from './schedules.js';
+import { asUser, type AgentUser } from './user.js';
+
+const LOG_LINES = 80;
+const TAIL_BYTES = 64 * 1024;
+
+export interface JobDetail extends ScheduledJob {
+  definition: string;
+  logs: string;
+  logSource: string | null;
+  script: { path: string; text: string } | null;
+}
+
+const SCRIPT_MAX = 64 * 1024;
+
+function textFile(path: string): string | null {
+  try {
+    const st = statSync(path);
+    if (!st.isFile() || st.size > SCRIPT_MAX) return null;
+    const text = readFileSync(path, 'utf8');
+    return text.includes('\u0000') ? null : text;
+  } catch {
+    return null;
+  }
+}
+
+export function scriptOf(command: string): { path: string; text: string } | null {
+  const words = command.split(/\s+/).filter((w) => w.startsWith('/') && !w.includes('>'));
+  for (const path of words.slice(0, 3)) {
+    const text = textFile(path);
+    if (text !== null) return { path, text };
+  }
+  return null;
+}
+
+function findJob(id: string, user: AgentUser | null, runner: Runner): ScheduledJob {
+  const job = listSchedules(user, runner).find((j) => j.id === id);
+  if (job === undefined) throw new ApiError('no such scheduled job', 404);
+  return job;
+}
+
+const serviceOf = (unit: string, runner: Runner): string => showProps(runner, unit, ['Unit']).Unit ?? unit.replace(/\.timer$/, '.service');
+
+export function logFileOf(command: string): string | null {
+  const m = /(?:^|\s)(?:>>|>)\s*(\/\S+)/.exec(command);
+  return m?.[1] ?? null;
+}
+
+function tail(path: string): string {
+  const size = statSync(path).size;
+  const start = Math.max(0, size - TAIL_BYTES);
+  return readRange(path, start, size - start).toString('utf8').split('\n').slice(-LOG_LINES).join('\n');
+}
+
+function timerDetail(job: ScheduledJob, runner: Runner): JobDetail {
+  const unit = job.id.slice('timer:'.length);
+  const service = serviceOf(unit, runner);
+  return {
+    ...job,
+    definition: runner.run('systemctl', ['cat', unit, service, '--no-pager']).stdout,
+    logs: runner.run('journalctl', ['-u', service, '-n', String(LOG_LINES), '--no-pager', '-o', 'short-iso']).stdout,
+    logSource: `journalctl -u ${service}`,
+    script: scriptOf(job.command),
+  };
+}
+
+function cronDetail(job: ScheduledJob): JobDetail {
+  const file = logFileOf(job.command);
+  const readable = file !== null && existsSync(file) && statSync(file).isFile();
+  return {
+    ...job,
+    definition: `${job.schedule} ${job.command}`,
+    logs: readable ? tail(file) : '',
+    logSource: file,
+    script: scriptOf(job.command),
+  };
+}
+
+export function scheduleDetail(id: string, user: AgentUser | null, runner: Runner = realRunner): JobDetail {
+  const job = findJob(id, user, runner);
+  return job.kind === 'timer' ? timerDetail(job, runner) : cronDetail(job);
+}
+
+export function runNow(id: string, user: AgentUser | null, runner: Runner = realRunner): JobDetail {
+  const job = findJob(id, user, runner);
+  if (job.kind === 'timer') runner.run('systemctl', ['start', '--no-block', serviceOf(job.id.slice('timer:'.length), runner)]);
+  else {
+    if (user === null) throw new ApiError('Claude Code does not run as its own user on this machine', 409);
+    const [file, args] = asUser(user, 'sh', ['-c', `cd "$HOME" && ${job.command}`]);
+    const child = spawn(file, args, { detached: true, stdio: 'ignore', cwd: '/' });
+    child.unref();
+  }
+  log.info({ job: job.name }, 'schedules: run now, from the page');
+  return scheduleDetail(id, user, runner);
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/schedules-api.ts

@@ -0,0 +1,27 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { ApiError } from '@metro-labs/http/api-error';
+import { bodyField, readJsonBody, sessionRoute } from '@metro-labs/http/api-http';
+import { listSchedules } from './schedules.js';
+import { runNow, scheduleDetail } from './schedule-detail.js';
+import { agentUser } from './user.js';
+
+const PATH = '/api/schedules';
+
+const queryId = (req: IncomingMessage): string | null => new URLSearchParams((req.url ?? '').split('?')[1] ?? '').get('id');
+
+async function answer(req: IncomingMessage): Promise<unknown> {
+  const user = agentUser();
+  if (req.method === 'GET') {
+    const id = queryId(req);
+    return id === null ? { agentUser: user?.name ?? null, jobs: listSchedules(user) } : { job: scheduleDetail(id, user) };
+  }
+  const body = await readJsonBody(req);
+  const id = bodyField(body, 'id');
+  if (typeof id !== 'string' || id === '') throw new ApiError('id is required', 400);
+  if (bodyField(body, 'action') !== 'run') throw new ApiError('action must be run', 400);
+  return { job: runNow(id, user) };
+}
+
+export function handleSchedulesRequest(req: IncomingMessage, res: ServerResponse): boolean {
+  return sessionRoute(req, res, { methods: { [PATH]: ['GET', 'POST'] }, admin: true, label: 'schedules-api' }, () => answer(req));
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/schedules.ts

@@ -0,0 +1,144 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { AgentUser } from './user.js';
+import { helperRun, type RunResult } from './unit-files.js';
+
+const UNIT_DIR = '/etc/systemd/system';
+const OWN_UNITS = /^metro(-claude-\d+)?\.(service|scope)$/;
+
+type JobKind = 'timer' | 'cron-agent';
+
+export interface ScheduledJob {
+  id: string;
+  kind: JobKind;
+  name: string;
+  schedule: string;
+  command: string;
+  runsAs: string;
+  next: string | null;
+  last: string | null;
+  lastResult: string | null;
+}
+
+export interface Runner {
+  run: (file: string, args: string[], input?: string) => RunResult;
+}
+
+export const realRunner: Runner = {
+  run: (file, args, input) => {
+    const viaHelper = helperRun(file, args, input);
+    if (viaHelper !== null) return viaHelper;
+    const done = spawnSync(file, args, { encoding: 'utf8', input, stdio: ['pipe', 'pipe', 'pipe'], timeout: 20_000 });
+    return { status: done.error === undefined ? done.status : null, stdout: done.stdout ?? '', stderr: done.stderr ?? '' };
+  },
+};
+
+const stamp = (micros: unknown): string | null =>
+  typeof micros === 'number' && micros > 0 ? new Date(micros / 1000).toISOString() : null;
+
+export function showProps(runner: Runner, unit: string, props: string[]): Record<string, string> {
+  const out = runner.run('systemctl', ['show', unit, '--no-pager', ...props.map((p) => `-p${p}`)]).stdout;
+  const found: Record<string, string> = {};
+  for (const line of out.split('\n')) {
+    const at = line.indexOf('=');
+    if (at > 0) found[line.slice(0, at)] = line.slice(at + 1);
+  }
+  return found;
+}
+
+function execArgv(execStart: string): string[] {
+  const m = /argv\[\]=(.*?) ;/.exec(execStart);
+  return m?.[1] === undefined ? [] : m[1].split(' ').filter((a) => a !== '');
+}
+
+export const calendarOf = (timers: string): string =>
+  /OnCalendar=([^;]*?) ;/.exec(timers)?.[1]?.trim() ?? /(OnUnitActiveUSec|OnBootUSec|OnActiveUSec)=([^;]*?) ;/.exec(timers)?.[0]?.replace(/ ;$/, '') ?? '';
+
+function listTimers(runner: Runner): Record<string, unknown>[] {
+  try {
+    const raw: unknown = JSON.parse(runner.run('systemctl', ['list-timers', '--all', '--output=json', '--no-pager']).stdout);
+    return Array.isArray(raw) ? raw.filter(isRecord) : [];
+  } catch {
+    return [];
+  }
+}
+
+const text = (v: unknown): string => (typeof v === 'string' ? v : '');
+const orRoot = (user: string | undefined): string => (user === undefined || user === '' ? 'root' : user);
+
+function timerJob(runner: Runner, t: Record<string, unknown>): ScheduledJob | null {
+  const unit = text(t.unit);
+  const service = text(t.activates);
+  if (unit === '' || service === '' || OWN_UNITS.test(service)) return null;
+  const timer = showProps(runner, unit, ['FragmentPath', 'TimersCalendar', 'TimersMonotonic']);
+  if (!text(timer.FragmentPath).startsWith(`${UNIT_DIR}/`)) return null;
+  const svc = showProps(runner, service, ['ExecStart', 'User', 'Result']);
+  const command = execArgv(text(svc.ExecStart)).join(' ');
+  return {
+    id: `timer:${unit}`,
+    kind: 'timer',
+    name: unit.replace(/\.timer$/, ''),
+    schedule: calendarOf(`${text(timer.TimersCalendar)} ${text(timer.TimersMonotonic)}`),
+    command,
+    runsAs: orRoot(svc.User),
+    next: stamp(t.next),
+    last: stamp(t.last),
+    lastResult: svc.Result ?? null,
+  };
+}
+
+const timerJobs = (runner: Runner): ScheduledJob[] =>
+  listTimers(runner).flatMap((t) => {
+    const job = timerJob(runner, t);
+    return job === null ? [] : [job];
+  });
+
+export interface CronLine {
+  schedule: string;
+  command: string;
+}
+
+export function parseCronLine(line: string): CronLine | null {
+  const text = line.trim();
+  if (text === '' || text.startsWith('#') || /^[A-Za-z_][A-Za-z0-9_]*=/.test(text)) return null;
+  if (text.startsWith('@')) {
+    const [at = '', ...rest] = text.split(/\s+/);
+    return rest.length === 0 ? null : { schedule: at, command: rest.join(' ') };
+  }
+  const parts = text.split(/\s+/);
+  if (parts.length < 6) return null;
+  return { schedule: parts.slice(0, 5).join(' '), command: parts.slice(5).join(' ') };
+}
+
+const lineId = (kind: JobKind, line: string): string => `${kind}:${createHash('sha256').update(line.trim()).digest('hex').slice(0, 16)}`;
+
+function crontabOf(runner: Runner, user: string): string[] {
+  const out = runner.run('crontab', ['-l', '-u', user]);
+  return out.status === 0 ? out.stdout.split('\n') : [];
+}
+
+function cronJobs(runner: Runner, user: string, kind: JobKind): ScheduledJob[] {
+  return crontabOf(runner, user).flatMap((line): ScheduledJob[] => {
+    const parsed = parseCronLine(line);
+    if (parsed === null) return [];
+    return [{
+      id: lineId(kind, line),
+      kind,
+      name: parsed.command.split(/\s+/)[0]?.split('/').pop() ?? 'cron',
+      schedule: parsed.schedule,
+      command: parsed.command,
+      runsAs: user,
+      next: null,
+      last: null,
+      lastResult: null,
+    }];
+  });
+}
+
+function allJobs(user: AgentUser | null, runner: Runner): ScheduledJob[] {
+  return [...timerJobs(runner), ...(user === null ? [] : cronJobs(runner, user.name, 'cron-agent'))];
+}
+
+export const listSchedules = (user: AgentUser | null, runner: Runner = realRunner): ScheduledJob[] =>
+  allJobs(user, runner).filter((job) => job.runsAs !== 'root');

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/unit-files.ts

@@ -0,0 +1,43 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { mustHelper, rootHelper } from '../metro-user/privilege.js';
+import { agentUser, asUser } from './user.js';
+
+const UNIT_DIR = '/etc/systemd/system';
+
+export interface RunResult {
+  status: number | null;
+  stdout: string;
+  stderr?: string;
+}
+
+export function writeDropIn(service: string, name: string, text: string): void {
+  mustHelper(['dropin-write', service, name], text);
+}
+
+export function removeDropIn(service: string, name: string): boolean {
+  if (!existsSync(join(UNIT_DIR, `${service}.d`, name))) return false;
+  mustHelper(['dropin-remove', service, name]);
+  return true;
+}
+
+function agentCrontab(args: string[], input?: string): RunResult {
+  const at = args.indexOf('-u');
+  const rest = at < 0 ? args : args.filter((_, i) => i !== at && i !== at + 1);
+  const [file, argv] = asUser(agentUser(), 'crontab', rest);
+  const run = spawnSync(file, argv, { encoding: 'utf8', input, stdio: ['pipe', 'pipe', 'pipe'], timeout: 20_000 });
+  return { status: run.error === undefined ? run.status : null, stdout: run.stdout ?? '', stderr: run.stderr ?? '' };
+}
+
+function systemctl(args: string[]): { status: number | null; stdout: string } | null {
+  if (args[0] === 'daemon-reload') return { status: rootHelper(['daemon-reload']).status, stdout: '' };
+  if (args[0] === 'start') return { status: rootHelper(['start-job', args[args.length - 1] ?? '']).status, stdout: '' };
+  return null;
+}
+
+export function helperRun(file: string, args: string[], input?: string): RunResult | null {
+  if (file === 'crontab') return agentCrontab(args, input);
+  if (file === 'systemctl') return systemctl(args);
+  return null;
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/user.ts

@@ -0,0 +1,91 @@
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { runningAsMetro } from '../metro-user/privilege.js';
+
+export const AGENT_NAME = 'agent';
+const AGENT_PATH = ['.local/bin', '/usr/local/sbin', '/usr/local/bin', '/usr/sbin', '/usr/bin', '/sbin', '/bin'];
+
+export interface AgentUser {
+  name: string;
+  uid: number;
+  gid: number;
+  home: string;
+}
+
+export interface UserHost {
+  metro: boolean;
+  lookup: (name: string) => AgentUser | null;
+}
+
+function lookupUser(name: string): AgentUser | null {
+  const run = spawnSync('getent', ['passwd', name], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  if (run.error !== undefined || run.status !== 0) return null;
+  const [, , uid = '', gid = '', , home = ''] = run.stdout.trim().split(':');
+  const u = Number(uid);
+  const g = Number(gid);
+  return Number.isInteger(u) && u > 0 && Number.isInteger(g) && home.startsWith('/') ? { name, uid: u, gid: g, home } : null;
+}
+
+const realHost = (): UserHost => ({ metro: runningAsMetro(), lookup: lookupUser });
+
+export const agentUserExpected = (host: UserHost = realHost()): boolean => host.metro;
+
+let cached: AgentUser | null = null;
+
+export function agentUser(host: UserHost = realHost()): AgentUser | null {
+  if (!agentUserExpected(host)) return null;
+  cached ??= host.lookup(AGENT_NAME);
+  return cached;
+}
+
+export function forgetAgentUser(): void {
+  cached = null;
+}
+
+let extraEnv: Record<string, string> = {};
+
+export function setAgentExtraEnv(env: Record<string, string>): void {
+  extraEnv = { ...env };
+}
+
+export const agentExtraEnv = (): Record<string, string> => ({ ...extraEnv });
+
+export const agentPath = (user: AgentUser): string => AGENT_PATH.map((p) => (p.startsWith('/') ? p : join(user.home, p))).join(':');
+
+function agentEnv(user: AgentUser, extra: Record<string, string> = {}): Record<string, string> {
+  return {
+    HOME: user.home,
+    USER: user.name,
+    LOGNAME: user.name,
+    SHELL: '/bin/bash',
+    LANG: process.env.LANG ?? 'C.UTF-8',
+    TERM: process.env.TERM ?? 'xterm-256color',
+    PATH: agentPath(user),
+    ...extraEnv,
+    ...extra,
+  };
+}
+
+export function asUser(user: AgentUser | null, file: string, args: readonly string[], extra: Record<string, string> = {}): [string, string[]] {
+  if (user === null) return [file, [...args]];
+  const env = Object.entries(agentEnv(user, extra)).map(([k, v]) => `${k}=${v}`);
+  return ['sudo', ['-n', '-u', user.name, '--', 'env', '-i', ...env, file, ...args]];
+}
+
+export const asAgent = (file: string, args: readonly string[], extra: Record<string, string> = {}): [string, string[]] =>
+  asUser(agentUser(), file, args, extra);
+
+export const agentCommand = (command: readonly string[], extra: Record<string, string> = {}): string[] => {
+  const [file = '', ...args] = command;
+  const [bin, argv] = asAgent(file, args, extra);
+  return [bin, ...argv];
+};
+
+export function claudeBin(user = agentUser()): string {
+  return user === null ? 'claude' : join(user.home, '.local', 'bin', 'claude');
+}
+
+export const claudeHome = (user = agentUser()): string | null => (user === null ? null : user.home);
+
+export const agentMarketplaceDir = (user: AgentUser): string => join(user.home, '.metro', 'marketplace');
+export const agentViewDir = (user: AgentUser): string => join(user.home, '.metro', 'agents');