@stage-labs/metro 0.1.0-beta.21 → 0.1.0-beta.210

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

@@ -0,0 +1,273 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, rmSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from '../agent-user/agent-fs.js';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { readJson, writeAtomic, writeJson } from '@metro-labs/core/secure-fs';
+import { agentsDir } from '../agents/files.js';
+import { writeHomeText } from '../agent-user/home-fs.js';
+import { claudeDir } from './files.js';
+import { stagedMarketplaceDir } from './plugin-install.js';
+import { readModelConfig, routedConnection, type ModelConfig } from '../gateway/model-config.js';
+
+export const PRIVACY_ENV: Record<string, string> = {
+  DISABLE_TELEMETRY: '1',
+  DISABLE_ERROR_REPORTING: '1',
+  CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+  CLAUDE_CODE_GB_DISK_CACHE_WHEN_TELEMETRY_OFF: '1',
+};
+export const RETENTION_DAYS = 7;
+const SKILL_NAME = 'metro-orchestrator';
+const STATE_FILE = 'claude-setup.json';
+const GUIDANCE = 'orchestrator.md';
+const SYSTEM_PROMPT_FILE = 'system-prompt.md';
+export const SYSTEM_PROMPT_MAX = 64 * 1024;
+
+const WORKER_AGENT = `---
+name: worker
+description: Default execution agent for delegated work. Full tool access and maximum reasoning effort. Use for any substantive task the orchestrator main thread cannot perform itself - reading and writing code, running commands, research, analysis.
+effort: xhigh
+---
+
+You are a worker agent. The main thread that dispatched you is an orchestrator with no file, shell or network access; it can only delegate and relay messages. That means you are where the actual work happens, and the quality of your output is the quality of the result.
+
+Work to completion. Do not hand back a partial answer with a suggestion that someone else finish it; there is no one else. If part of the task is genuinely blocked, complete every other part in full and say plainly what you left undone and why. Before you finish, read your own last paragraph: if it is a plan, a question or a promise about work you have not done, do that work now.
+
+Keep the change to what the task asks for. A pre-existing bug, a performance problem or behaviour the task does not mention is a follow-up to report at the end, not something to fix now, unless the requested behaviour cannot work without it. Where the task is ambiguous, build the reading its wording and the surrounding code support best, and state that assumption. Commit tests only where the task asks for them or the repository already keeps tests for that kind of change, sized like the neighbouring test files; scratch checks you used to verify yourself need not be kept. This is about extras only: every behaviour the task does ask for, implement completely.
+
+Never call AskUserQuestion or ExitPlanMode. They are blocked by policy, because nobody is watching the terminal around the clock and a blocking prompt stalls indefinitely. When you hit an ambiguity: do everything that does not depend on it, then choose the most reasonable interpretation, state the assumption explicitly in your report, and continue.
+
+Your final message is a report to the orchestrator, not a message to a human. It gets relayed onward, so make it self-contained and concise. Lead with the outcome. Include concrete evidence, command output, file paths with line numbers, test results, for anything you claim to have verified. Report failures faithfully: if a test failed, say so and show the output; if you skipped a step, say that too.
+`;
+
+export interface SetupDeps {
+  dir?: string;
+  agents?: string;
+  guidance?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+export type Placed = 'written' | 'present' | 'updated' | 'missing';
+export type SettingsOutcome = 'written' | 'unchanged' | 'unreadable';
+
+export interface SetupReport {
+  privacy: boolean;
+  guard: 'plugin';
+  worker: Placed;
+  skill: Placed;
+  settings: SettingsOutcome;
+}
+
+export interface SetupStatus {
+  privacy: boolean;
+  permissionMode: PermissionMode;
+  systemPrompt: string;
+  guard: 'plugin';
+  worker: boolean;
+  skill: boolean;
+  privacyApplied: boolean;
+  retentionDays: number | null;
+}
+
+const statePath = (agents: string): string => join(agents, STATE_FILE);
+
+const PERMISSION_MODES = ['auto', 'bypass'] as const;
+export type PermissionMode = (typeof PERMISSION_MODES)[number];
+
+function readState(agents: string): Record<string, unknown> {
+  const raw = readJson<unknown>(statePath(agents), null);
+  return isRecord(raw) ? raw : {};
+}
+
+function writeState(agents: string, patch: Record<string, unknown>): void {
+  mkdirSync(agents, { recursive: true });
+  writeJson(statePath(agents), { ...readState(agents), ...patch });
+}
+
+const privacyEnabled = (agents = agentsDir()): boolean => readState(agents).privacy !== false;
+
+export function setPrivacy(enabled: boolean, agents = agentsDir()): void {
+  writeState(agents, { privacy: enabled });
+}
+
+export const isPermissionMode = (value: unknown): value is PermissionMode => PERMISSION_MODES.some((m) => m === value);
+
+export function permissionMode(agents = agentsDir()): PermissionMode {
+  const mode = readState(agents).permissionMode;
+  return isPermissionMode(mode) ? mode : 'auto';
+}
+
+export function setPermissionMode(mode: PermissionMode, agents = agentsDir()): void {
+  writeState(agents, { permissionMode: mode });
+}
+
+const promptPath = (agents: string): string => join(agents, SYSTEM_PROMPT_FILE);
+
+export function systemPrompt(agents = agentsDir()): string {
+  const path = promptPath(agents);
+  if (!existsSync(path)) return '';
+  return readFileSync(path, 'utf8').trim();
+}
+
+export function setSystemPrompt(text: string, agents = agentsDir()): void {
+  const trimmed = text.trim();
+  if (trimmed === '') {
+    rmSync(promptPath(agents), { force: true });
+    return;
+  }
+  writeAtomic(promptPath(agents), `${trimmed}\n`, 0o600);
+}
+
+function guidancePath(env: NodeJS.ProcessEnv = process.env): string {
+  const staged = stagedMarketplaceDir(env);
+  if (staged !== null) {
+    const path = join(staged, 'plugin', GUIDANCE);
+    if (existsSync(path)) return path;
+  }
+  return fileURLToPath(new URL(`../../../../plugin/${GUIDANCE}`, import.meta.url));
+}
+
+const PRIOR_WORKER: ReadonlySet<string> = new Set(['08a0cd8710df285d6512245246bb8b658b7cfc7f3e89490514ee5376779eb2ef']);
+const PRIOR_SKILL: ReadonlySet<string> = new Set([
+  '0b3d122ed95beff09d579cf912cd4238e1db524c41fce4b314de57d6ff5908ad',
+  '36f4fb57f231a119d717b5e3d6ccb654f94960fcca708683f376679aead8df25',
+  '3840bc50253e51f431691376cf29a925b8245d87b77b8b20804a159e378a6e67',
+  'e6b59eba825b4568dfa9ace5049fd9568a2e10d731719976ad2657084fd4e5f9',
+]);
+
+const digest = (text: string): string => createHash('sha256').update(text).digest('hex');
+
+export function placeFile(path: string, text: string, prior: ReadonlySet<string> = new Set()): Placed {
+  if (!existsSync(path)) {
+    writeHomeText(path, text, 0o644);
+    return 'written';
+  }
+  const current = readFileSync(path, 'utf8');
+  if (current === text || !prior.has(digest(current))) return 'present';
+  writeHomeText(path, text, 0o644);
+  return 'updated';
+}
+
+function readSettings(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;
+  }
+}
+
+function withPrivacy(settings: Record<string, unknown>, enabled: boolean): Record<string, unknown> {
+  const current = isRecord(settings.env) ? settings.env : {};
+  if (enabled)
+    return { ...settings, env: { ...current, ...PRIVACY_ENV }, cleanupPeriodDays: settings.cleanupPeriodDays ?? RETENTION_DAYS };
+  const env = Object.fromEntries(Object.entries(current).filter(([key]) => !(key in PRIVACY_ENV)));
+  const rest = Object.fromEntries(Object.entries(settings).filter(([key]) => key !== 'env'));
+  return Object.keys(env).length === 0 ? rest : { ...rest, env };
+}
+
+function mergeSettings(dir: string, change: (settings: Record<string, unknown>) => Record<string, unknown>): SettingsOutcome {
+  const path = join(dir, 'settings.json');
+  const current = readSettings(path);
+  if (current === null) return 'unreadable';
+  const next = change(current);
+  if (existsSync(path) && JSON.stringify(next) === JSON.stringify(current)) return 'unchanged';
+  writeHomeText(path, `${JSON.stringify(next, null, 2)}\n`, existsSync(path) ? statSync(path).mode & 0o777 : 0o644);
+  return 'written';
+}
+
+function applyPrivacy(dir: string, enabled: boolean): SettingsOutcome {
+  return mergeSettings(dir, (current) => withPrivacy(current, enabled));
+}
+
+const skillPath = (dir: string): string => join(dir, 'skills', SKILL_NAME, 'SKILL.md');
+const workerPath = (dir: string): string => join(dir, 'agents', 'worker.md');
+
+function placeSkill(dir: string, guidance: string): Placed {
+  if (!existsSync(guidance)) return 'missing';
+  return placeFile(skillPath(dir), readFileSync(guidance, 'utf8'), PRIOR_SKILL);
+}
+
+const written = (placed: Placed): boolean => placed === 'written' || placed === 'updated';
+
+export function ensureClaudeSetup(deps: SetupDeps = {}): SetupReport {
+  const dir = deps.dir ?? claudeDir();
+  const agents = deps.agents ?? agentsDir();
+  const privacy = privacyEnabled(agents);
+  const report: SetupReport = {
+    privacy,
+    guard: 'plugin',
+    worker: placeFile(workerPath(dir), WORKER_AGENT, PRIOR_WORKER),
+    skill: placeSkill(dir, deps.guidance ?? guidancePath(deps.env)),
+    settings: applyPrivacy(dir, privacy),
+  };
+  syncAvailableModelsQuietly({ ...deps, dir, agents });
+  if (written(report.worker) || written(report.skill) || report.settings === 'written')
+    log.info(report, 'claude-setup: applied the Claude Code setup for a metro box');
+  if (report.settings === 'unreadable') log.warn({ path: join(dir, 'settings.json') }, 'claude-setup: settings.json is not valid JSON, so the privacy settings were not written');
+  return report;
+}
+
+export function claudeSetupStatus(deps: SetupDeps = {}): SetupStatus {
+  const dir = deps.dir ?? claudeDir();
+  const settings = readSettings(join(dir, 'settings.json'));
+  const env = settings !== null && isRecord(settings.env) ? settings.env : {};
+  const days = settings?.cleanupPeriodDays;
+  return {
+    privacy: privacyEnabled(deps.agents ?? agentsDir()),
+    permissionMode: permissionMode(deps.agents ?? agentsDir()),
+    systemPrompt: systemPrompt(deps.agents ?? agentsDir()),
+    guard: 'plugin',
+    worker: existsSync(workerPath(dir)),
+    skill: existsSync(skillPath(dir)),
+    privacyApplied: Object.keys(PRIVACY_ENV).every((key) => env[key] === '1'),
+    retentionDays: typeof days === 'number' ? days : null,
+  };
+}
+
+export function tryClaudeSetup(deps: SetupDeps = {}): void {
+  try {
+    ensureClaudeSetup(deps);
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'claude-setup: could not apply the Claude Code setup');
+  }
+}
+
+const MODELS_KEY = 'availableModels';
+const ENFORCE_KEY = 'enforceAvailableModels';
+
+export function routeOf(cfg: ModelConfig): string | null {
+  const conn = routedConnection(cfg);
+  if (conn === null || conn.provider === 'anthropic' || conn.model === '') return null;
+  return `${conn.provider}:${conn.model}`;
+}
+
+function withAvailableModels(settings: Record<string, unknown>, route: string | null, metroWrote: boolean): Record<string, unknown> {
+  if (route !== null) return { ...settings, [MODELS_KEY]: [route], [ENFORCE_KEY]: true };
+  if (!metroWrote) return settings;
+  return Object.fromEntries(Object.entries(settings).filter(([key]) => key !== MODELS_KEY && key !== ENFORCE_KEY));
+}
+
+export function syncAvailableModels(cfg: ModelConfig, deps: SetupDeps = {}): SettingsOutcome {
+  const dir = deps.dir ?? claudeDir();
+  const agents = deps.agents ?? agentsDir();
+  const route = routeOf(cfg);
+  const state = readJson<unknown>(statePath(agents), null);
+  const metroWrote = isRecord(state) && state.modelsByMetro === true;
+  return mergeSettings(dir, (current) => {
+    mkdirSync(agents, { recursive: true });
+    writeJson(statePath(agents), { ...(isRecord(state) ? state : {}), modelsByMetro: route !== null });
+    return withAvailableModels(current, route, metroWrote);
+  });
+}
+
+export function syncAvailableModelsQuietly(deps: SetupDeps = {}, cfg?: ModelConfig): void {
+  try {
+    syncAvailableModels(cfg ?? readModelConfig(deps.agents ?? agentsDir()), deps);
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'claude-setup: could not sync the model allowlist');
+  }
+}

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

@@ -0,0 +1,120 @@
+import { existsSync, readdirNames, readFileSync, statSync } from '../agent-user/agent-fs.js';
+import { basename, dirname, join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { claudeDir } from './files.js';
+import { removeHome, writeHomeText } from '../agent-user/home-fs.js';
+
+const SKILL_MAX = 256 * 1024;
+const SKILL_NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const FILE = 'SKILL.md';
+const DEFAULT_MODE = 0o644;
+const SUMMARY_MAX = 300;
+
+export interface ClaudeSkill {
+  id: string;
+  name: string;
+  title: string;
+  description: string;
+  path: string;
+  editable: boolean;
+  updatedAt: string | null;
+}
+
+const frontmatterField = (text: string, field: string): string => {
+  const head = text.startsWith('---') ? text.slice(3, text.indexOf('\n---', 3)) : '';
+  for (const line of head.split('\n')) {
+    const at = line.indexOf(':');
+    if (at > 0 && line.slice(0, at).trim() === field) return line.slice(at + 1).trim().replace(/^["']|["']$/g, '').slice(0, SUMMARY_MAX);
+  }
+  return '';
+};
+
+function entryOf(name: string, path: string): ClaudeSkill {
+  const stat = statSync(path);
+  const editable = stat.size <= SKILL_MAX;
+  const text = editable ? readFileSync(path, 'utf8') : '';
+  return {
+    id: `user:${name}`,
+    name,
+    title: frontmatterField(text, 'name') || name,
+    description: frontmatterField(text, 'description'),
+    path,
+    editable,
+    updatedAt: stat.mtime.toISOString(),
+  };
+}
+
+const userSkillsRoot = (dir: string): string => join(dir, 'skills');
+
+function isFolder(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function listClaudeSkills(dir = claudeDir()): ClaudeSkill[] {
+  const root = userSkillsRoot(dir);
+  if (!existsSync(root)) return [];
+  const out: ClaudeSkill[] = [];
+  for (const name of readdirNames(root)) {
+    if (!SKILL_NAME_RE.test(name) || !isFolder(join(root, name))) continue;
+    const path = join(root, name, FILE);
+    if (existsSync(path)) out.push(entryOf(name, path));
+  }
+  return out.sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? '') || a.name.localeCompare(b.name));
+}
+
+function found(id: string, dir: string): ClaudeSkill {
+  const skill = listClaudeSkills(dir).find((entry) => entry.id === id);
+  if (skill === undefined) throw new ApiError('no such skill', 404);
+  return skill;
+}
+
+export function readClaudeSkill(id: string, dir = claudeDir()): ClaudeSkill & { text: string } {
+  const skill = found(id, dir);
+  return { ...skill, text: skill.editable ? readFileSync(skill.path, 'utf8') : '' };
+}
+
+function assertText(text: string): void {
+  if (text.length > SKILL_MAX) throw new ApiError('that is more text than a skill may hold', 413);
+  if (text.trim() === '') throw new ApiError('a skill needs some text', 400);
+}
+
+export function writeClaudeSkill(
+  id: string,
+  text: string,
+  seenAt: string | null | undefined,
+  dir = claudeDir(),
+): ClaudeSkill {
+  const skill = found(id, dir);
+  if (!skill.editable) throw new ApiError('that skill is too large to edit here', 409);
+  assertText(text);
+  if (seenAt !== undefined && seenAt !== skill.updatedAt)
+    throw new ApiError('that skill changed on disk since you opened it; reload it before saving', 409);
+  writeHomeText(skill.path, text, DEFAULT_MODE);
+  return entryOf(skill.name, skill.path);
+}
+
+const skillTemplate = (name: string): string =>
+  ['---', `name: ${name}`, 'description: what this skill does, and when Claude should reach for it', '---', '', `# ${name}`, '', 'Write the instructions here.', ''].join('\n');
+
+export function createClaudeSkill(name: string, text: string | undefined, dir = claudeDir()): ClaudeSkill {
+  if (typeof name !== 'string' || !SKILL_NAME_RE.test(name))
+    throw new ApiError('a skill name is lowercase letters, digits and dashes, up to 64 characters', 400);
+  const path = join(userSkillsRoot(dir), name, FILE);
+  if (existsSync(path)) throw new ApiError('a skill by that name already lives there', 409);
+  const body = text === undefined || text.trim() === '' ? skillTemplate(name) : text;
+  assertText(body);
+  writeHomeText(path, body, DEFAULT_MODE);
+  return entryOf(name, path);
+}
+
+export function deleteClaudeSkill(id: string, dir = claudeDir()): string {
+  const skill = found(id, dir);
+  const folder = dirname(skill.path);
+  if (basename(folder) !== skill.name) throw new ApiError('that skill does not live in its own folder', 409);
+  removeHome(folder, true);
+  return id;
+}

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

@@ -0,0 +1,113 @@
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { sessionRunning, stopSession, type SessionDeps } from './session.js';
+import { agentUser, asAgent, claudeBin } from '../agent-user/user.js';
+
+const LATEST_URL = 'https://registry.npmjs.org/@anthropic-ai/claude-code/latest';
+const VERSION_RE = /(\d+)\.(\d+)\.(\d+)/;
+const CACHE_MS = 10 * 60_000;
+const INSTALL_TIMEOUT_MS = 5 * 60_000;
+const TAIL = 400;
+
+export interface VersionDeps {
+  claude?: string;
+  fetchImpl?: typeof fetch;
+  session?: SessionDeps;
+  now?: () => number;
+}
+
+export interface ClaudeVersion {
+  installed: string | null;
+  latest: string | null;
+  newer: boolean;
+}
+
+let cached: { latest: string | null; at: number } | null = null;
+
+function candidates(deps: VersionDeps): string[] {
+  if (deps.claude !== undefined) return [deps.claude];
+  return agentUser() === null ? ['claude', join(homedir(), '.local', 'bin', 'claude')] : [claudeBin()];
+}
+
+const parse = (text: string): string | null => {
+  const m = VERSION_RE.exec(text);
+  return m === null ? null : `${m[1] ?? ''}.${m[2] ?? ''}.${m[3] ?? ''}`;
+};
+
+function probe(bin: string): string | null {
+  const run = spawnSync(...asAgent(bin, ['--version']), { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  return run.error === undefined && run.status === 0 && typeof run.stdout === 'string' ? parse(run.stdout) : null;
+}
+
+function located(deps: VersionDeps): { bin: string; installed: string } | null {
+  for (const bin of candidates(deps)) {
+    const installed = probe(bin);
+    if (installed !== null) return { bin, installed };
+  }
+  return null;
+}
+
+export function newerThan(a: string, b: string): boolean {
+  const left = a.split('.').map(Number);
+  const right = b.split('.').map(Number);
+  for (let i = 0; i < 3; i += 1) {
+    const d = (left[i] ?? 0) - (right[i] ?? 0);
+    if (d !== 0) return d > 0;
+  }
+  return false;
+}
+
+async function latestClaudeVersion(deps: VersionDeps = {}): Promise<string | null> {
+  const now = (deps.now ?? Date.now)();
+  if (cached !== null && now - cached.at < CACHE_MS) return cached.latest;
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  let latest: string | null = null;
+  try {
+    const res = await fetchImpl(LATEST_URL, { headers: { accept: 'application/json' }, redirect: 'manual' });
+    const body: unknown = res.ok ? await res.json() : null;
+    latest = isRecord(body) && typeof body.version === 'string' ? parse(body.version) : null;
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'claude-version: could not read the latest version from npm');
+  }
+  cached = { latest, at: now };
+  return latest;
+}
+
+export function forgetClaudeVersion(): void {
+  cached = null;
+}
+
+export async function claudeVersion(deps: VersionDeps = {}): Promise<ClaudeVersion> {
+  const installed = located(deps)?.installed ?? null;
+  const latest = await latestClaudeVersion(deps);
+  return { installed, latest, newer: installed !== null && latest !== null && newerThan(latest, installed) };
+}
+
+function install(bin: string): void {
+  const run = spawnSync(...asAgent(bin, ['install', 'latest']), { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: INSTALL_TIMEOUT_MS });
+  if (run.error !== undefined) throw new ApiError(`claude install latest failed: ${errMsg(run.error)}`, 502);
+  if (run.status === 0) return;
+  const said = `${run.stderr ?? ''}${run.stdout ?? ''}`.trim().slice(-TAIL);
+  throw new ApiError(`claude install latest failed: ${said}`, 502);
+}
+
+function restartIfChanged(changed: boolean, session: SessionDeps): boolean {
+  if (!changed || !sessionRunning(session.tmux ?? 'tmux')) return false;
+  stopSession(session);
+  return true;
+}
+
+export async function updateClaude(deps: VersionDeps = {}): Promise<ClaudeVersion & { restarted: boolean }> {
+  const found = located(deps);
+  if (found === null) throw new ApiError('Claude Code is not installed on this machine', 404);
+  install(found.bin);
+  forgetClaudeVersion();
+  const after = await claudeVersion(deps);
+  const restarted = restartIfChanged(after.installed !== null && after.installed !== found.installed, deps.session ?? {});
+  log.info({ from: found.installed, to: after.installed, restarted }, 'claude-version: Claude Code updated');
+  return { ...after, restarted };
+}