@anhlp/alp-core 0.0.0-beta.1

package/src/teams.js

@@ -0,0 +1,170 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { AlpError } from './errors.js';
+import { builtinText, optionalText } from './resolver.js';
+import { settingsKeys, unknownMessage } from './validation.js';
+
+/**
+ * Teams (ALPD §42): a main agent, its members, who may delegate to whom, and the
+ * house rules every member follows. Phở and Cafe ship as built-in teams; the user's
+ * library (ALP_HOME/teams) and the project (.alp/teams) add teams or override one by
+ * its id, the later layer replacing the team whole.
+ */
+
+export const BUILTIN_TEAMS = ['pho', 'cafe'];
+export const TEAM_SETTINGS = ['$schema', 'label', 'description', 'main', 'members', 'delegation', 'maxPeers', 'supervisor', 'oracleModels', 'oracleThinking', 'modelSetup'];
+export const TEAM_ROLES = ['lead', 'peer', 'advisor', 'reviewer'];
+const MEMBER_SETTINGS = ['role', 'model', 'thinking'];
+const SUPERVISOR_SETTINGS = ['agent', 'model', 'thinking'];
+
+/** Names of teams before they were renamed; settings and resumed sessions may still carry them. */
+const aliases = { smart: 'pho', supervised: 'cafe' };
+/** The team an id selects, accepting the old names. */
+export const teamOf = id => aliases[id] ?? id;
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const nonempty = value => typeof value === 'string' && value.trim().length > 0;
+const validName = name => typeof name === 'string' && /^[\w.-]+$/.test(name) && name !== '.' && name !== '..';
+
+function keys(value, known, check, where) {
+  const { unknown } = settingsKeys(value, known);
+  check(!unknown.length, unknown.length ? `${where}${unknownMessage(unknown[0], known)}` : '');
+}
+
+/** Checks a team.json; the delegation graph must name members and stay acyclic. */
+export function validateTeam(config, source) {
+  const check = (ok, message) => { if (!ok) throw new AlpError('INVALID_TEAM', `${source}: ${message}`); };
+  check(object(config), 'expected an object');
+  keys(config, TEAM_SETTINGS, check, '');
+  if (config.modelSetup !== undefined) {
+    const setup = config.modelSetup;
+    check(object(setup) && ['default', 'custom'].includes(setup.mode), 'modelSetup.mode must be default or custom');
+    keys(setup, ['mode', 'preset'], check, 'modelSetup: ');
+    if (setup.mode === 'default') check(['claude', 'codex', 'opencode', 'antigravity', 'mix'].includes(setup.preset), 'modelSetup.preset must name a preset');
+    else check(setup.preset === undefined, 'custom modelSetup has no preset');
+  }
+  check(nonempty(config.label), 'label must be a nonempty string');
+  if (config.description !== undefined) check(typeof config.description === 'string', 'description must be a string');
+  check(validName(config.main), 'main must name an agent');
+  check(object(config.members), 'members must map agent names to { role, model, thinking }');
+  check(Object.hasOwn(config.members, config.main), `members must include main (${config.main})`);
+  for (const [name, member] of Object.entries(config.members)) {
+    const where = `members.${name}`;
+    check(validName(name) && object(member), `${where} must be an object under an agent name`);
+    keys(member, MEMBER_SETTINGS, check, `${where}: `);
+    if (name === config.main) check(member.role === undefined || member.role === 'main', `${where}.role: main's role is main`);
+    else check(TEAM_ROLES.includes(member.role), `${where}.role must be one of ${TEAM_ROLES.join(', ')}`);
+    for (const key of ['model', 'thinking']) if (member[key] !== undefined) check(nonempty(member[key]), `${where}.${key} must be a nonempty string`);
+  }
+  check(object(config.delegation), 'delegation must map members to the members they may delegate to');
+  for (const [owner, targets] of Object.entries(config.delegation)) {
+    check(Object.hasOwn(config.members, owner), `delegation.${owner}: not a member`);
+    check(Array.isArray(targets) && new Set(targets).size === targets.length, `delegation.${owner} must list members once each`);
+    for (const target of targets) check(Object.hasOwn(config.members, target) && target !== config.main, `delegation.${owner}: ${target} is not a member main can be assigned to`);
+  }
+  const visiting = new Set();
+  const visited = new Set();
+  const visit = owner => {
+    check(!visiting.has(owner), `delegation cycle at '${owner}'`);
+    if (visited.has(owner)) return;
+    visiting.add(owner);
+    for (const target of config.delegation[owner] ?? []) visit(target);
+    visiting.delete(owner);
+    visited.add(owner);
+  };
+  for (const owner of Object.keys(config.delegation)) visit(owner);
+  if (config.oracleModels !== undefined) {
+    check(Array.isArray(config.oracleModels) && config.oracleModels.length > 0, 'oracleModels must list runtime-prefixed models');
+    check(config.oracleModels.every(model => typeof model === 'string' && /^(codex|claude|antigravity|acp):[^\s]+$/.test(model)) && new Set(config.oracleModels).size === config.oracleModels.length, 'oracleModels must list each model once');
+  }
+  if (config.oracleThinking !== undefined) {
+    check(object(config.oracleThinking), 'oracleThinking must map providers to effort');
+    for (const [provider, effort] of Object.entries(config.oracleThinking)) check((['codex', 'claude', 'antigravity', 'acp'].includes(provider) || /^(codex|claude|antigravity|acp):[^\s]+$/.test(provider)) && ['none', 'off', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra', 'ultracode'].includes(effort), 'oracleThinking requires a provider or model ID and a supported effort');
+  }
+  if (config.maxPeers !== undefined) check(Number.isSafeInteger(config.maxPeers) && config.maxPeers >= 1, 'maxPeers must be a positive integer');
+  if (config.supervisor !== undefined && config.supervisor !== false) {
+    check(object(config.supervisor), 'supervisor must be false or { agent, model, thinking }');
+    keys(config.supervisor, SUPERVISOR_SETTINGS, check, 'supervisor: ');
+    check(validName(config.supervisor.agent), 'supervisor.agent must name an agent');
+    check(!Object.hasOwn(config.members, config.supervisor.agent), 'supervisor.agent watches the team and cannot be a member');
+    for (const key of ['model', 'thinking']) if (config.supervisor[key] !== undefined) check(nonempty(config.supervisor[key]), `supervisor.${key} must be a nonempty string`);
+  }
+  return config;
+}
+
+async function directories(directory) {
+  try { return (await readdir(directory, { withFileTypes: true })).filter(entry => entry.isDirectory() && validName(entry.name)).map(entry => entry.name).sort(); }
+  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+}
+
+/**
+ * Where each team comes from: built in, then the library, then the project. A team
+ * directory counts only with a team.json. `root` may be undefined outside a project.
+ * @returns {Promise<Map<string, { source: 'builtin' | 'library' | 'project', directory?: string, overrides?: 'builtin' | 'library' }>>}
+ */
+export async function teamSources(root, { library, templates } = {}) {
+  const found = new Map();
+  for (const id of BUILTIN_TEAMS) if (await builtinText(`teams/${id}/team.json`, templates) !== undefined) found.set(id, { source: 'builtin' });
+  const layer = async (directory, source) => {
+    for (const id of await directories(directory)) {
+      if ((await optionalText(path.join(directory, id, 'team.json'))) === undefined) continue;
+      const previous = found.get(id);
+      found.set(id, { source, directory: path.join(directory, id), ...(previous ? { overrides: previous.source } : {}) });
+    }
+  };
+  if (library) await layer(path.join(library, 'teams'), 'library');
+  // Without a project, only the built-ins and the library apply.
+  if (root !== undefined) await layer(path.join(path.resolve(root), '.alp', 'teams'), 'project');
+  return found;
+}
+
+/**
+ * A team by id, with its house rules.
+ * @returns {Promise<{ id: string, source: 'builtin' | 'library' | 'project', label: string, description?: string, main: string,
+ *   members: Record<string, { role?: string, model?: string, thinking?: string }>, delegation: Record<string, string[]>,
+ *   oracleThinking?: Record<string, string>, oracleModels?: string[], maxPeers?: number, supervisor: false | { agent: string, model?: string, thinking?: string }, houseRules: string }>}
+ */
+export async function resolveTeam(root, id, { library, templates } = {}) {
+  const team = teamOf(id);
+  const sources = await teamSources(root, { library, templates });
+  const found = sources.get(team);
+  if (!found) throw new AlpError('TEAM_NOT_FOUND', `Team '${id}' not found; teams: ${[...sources.keys()].join(', ')}`);
+  const where = found.directory ? path.join(found.directory, 'team.json') : `built-in teams/${team}/team.json`;
+  const text = found.directory ? await optionalText(where) : await builtinText(`teams/${team}/team.json`, templates);
+  let config;
+  try { config = JSON.parse(text ?? ''); }
+  catch (cause) { throw new AlpError('INVALID_TEAM', `${where}: ${cause.message}`, { cause }); }
+  validateTeam(config, where);
+  const houseRules = (found.directory ? await optionalText(path.join(found.directory, 'HOUSE_RULES.md')) : await builtinText(`teams/${team}/HOUSE_RULES.md`, templates)) ?? '';
+  return {
+    id: team, source: found.source, label: config.label,
+    ...(config.description !== undefined ? { description: config.description } : {}),
+    main: config.main, members: config.members, delegation: config.delegation,
+    ...(config.maxPeers !== undefined ? { maxPeers: config.maxPeers } : {}),
+    supervisor: config.supervisor ?? false,
+    oracleModels: config.oracleModels,
+    oracleThinking: config.oracleThinking,
+    ...(config.modelSetup ? { modelSetup: config.modelSetup } : {}),
+    houseRules: houseRules.trim(),
+  };
+}
+
+/**
+ * Every team a project can use, in order: built-in, library, project; with what each overrides.
+ * A team that does not load is listed with its error.
+ * @param {string | undefined} root
+ * @param {{ library?: string, templates?: Record<string, string> }} [options]
+ * @returns {Promise<Array<{ id: string, source: 'builtin' | 'library' | 'project', label?: string, description?: string, overrides?: 'builtin' | 'library', path?: string, error?: string }>>}
+ */
+export async function listTeams(root, options = {}) {
+  /** @type {Array<{ id: string, source: 'builtin' | 'library' | 'project', label?: string, description?: string, overrides?: 'builtin' | 'library', path?: string, error?: string }>} */
+  const rows = [];
+  for (const [id, source] of await teamSources(root, options)) {
+    let team;
+    try { team = await resolveTeam(root, id, options); }
+    catch (error) { rows.push({ id, source: source.source, ...(source.overrides ? { overrides: source.overrides } : {}), error: error.message }); continue; }
+    rows.push({ id, source: source.source, label: team.label, ...(team.description !== undefined ? { description: team.description } : {}), ...(source.overrides ? { overrides: source.overrides } : {}), ...(source.directory ? { path: source.directory } : {}) });
+  }
+  const rank = { builtin: 0, library: 1, project: 2 };
+  return rows.sort((a, b) => rank[a.source] - rank[b.source] || (BUILTIN_TEAMS.indexOf(a.id) + 1 || 99) - (BUILTIN_TEAMS.indexOf(b.id) + 1 || 99) || a.id.localeCompare(b.id));
+}

package/src/template-path.js

@@ -0,0 +1,8 @@
+import { existsSync } from 'node:fs';
+
+/** Source packages carry templates beside src; legacy bundles live one directory deeper. */
+export function shippedTemplateRoot() {
+  const packaged = new URL('../templates/', import.meta.url);
+  const candidates = [packaged, new URL('../../templates/', import.meta.url), new URL('../../../templates/', import.meta.url), new URL('../../../../templates/', import.meta.url), new URL('../../../../../templates/', import.meta.url)];
+  return candidates.find(candidate => existsSync(candidate)) ?? packaged;
+}

package/src/trust.js

@@ -0,0 +1,59 @@
+import { mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import { moveFile } from './atomic.js';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+
+/**
+ * Which workspaces' hooks the user trusts (ALPD §45). A project's hooks come with its
+ * repository, so ALP asks the user once per project before running them; once the user
+ * agrees, that project's hooks run from then on, including hooks added or changed later.
+ * Hooks in the user's library are always trusted. Kept in $ALP_HOME/state/trust.json.
+ */
+
+const file = home => path.join(home, 'state', 'trust.json');
+/** One key per workspace, however its path was spelled. */
+const key = root => realpath(path.resolve(root)).catch(() => path.resolve(root));
+
+async function load(home) {
+  try {
+    const value = JSON.parse(await readFile(file(home), 'utf8'));
+    return value && typeof value === 'object' && value.projects && typeof value.projects === 'object' ? value : { projects: {} };
+  } catch (error) {
+    if (error.code === 'ENOENT' || error instanceof SyntaxError) return { projects: {} };
+    throw error;
+  }
+}
+
+async function store(home, value) {
+  await mkdir(path.dirname(file(home)), { recursive: true });
+  const temporary = `${file(home)}.${randomUUID().slice(0, 8)}.tmp`;
+  await writeFile(temporary, JSON.stringify(value, null, 2) + '\n');
+  await moveFile(temporary, file(home));
+}
+
+/** Whether the user trusts this project's hooks. */
+export async function isTrusted(home, projectRoot) {
+  return Object.hasOwn((await load(home)).projects, await key(projectRoot));
+}
+
+/** Records that the user trusts this project's hooks; `by` says how they agreed. */
+export async function trustProject(home, projectRoot, by = 'user') {
+  const value = await load(home);
+  value.projects[await key(projectRoot)] = { trustedAt: new Date().toISOString(), by };
+  await store(home, value);
+}
+
+/** Forgets a project's trust: ALP asks again before its hooks run. Returns whether it was trusted. */
+export async function revokeProject(home, projectRoot) {
+  const value = await load(home);
+  const root = await key(projectRoot);
+  if (!Object.hasOwn(value.projects, root)) return false;
+  delete value.projects[root];
+  await store(home, value);
+  return true;
+}
+
+/** Every trusted project, with when and how the user agreed. */
+export async function trustedProjects(home) {
+  return Object.entries((await load(home)).projects).map(([root, entry]) => ({ root, ...entry })).sort((a, b) => a.root.localeCompare(b.root));
+}

package/src/types.d.ts

@@ -0,0 +1,51 @@
+export interface AgentModelConfig { provider?: 'codex' | 'claude' | 'acp' | 'antigravity'; model?: string; effort?: string }
+export type AutoCompact = 'auto' | number;
+export type AgentProfilesConfig = {
+  /** "provider:model", "provider:*" for any model of that provider, or the earlier object form. */
+  profiles?: Array<string | AgentModelConfig>;
+  autocompact?: AutoCompact;
+  claude?: AgentModelConfig;
+  codex?: AgentModelConfig;
+} & AgentModelConfig;
+/** Disk configuration; no provider SDK types. */
+export interface RawSettings {
+  templateDefaults?: Record<string, Record<string, string>>;
+  team?: Record<string, Record<string, AgentProfilesConfig>>;
+  /** Legacy settings key; use team. */
+  profile?: Record<string, Record<string, AgentProfilesConfig>>;
+  defaultAgent?: string;
+  workflow?: { mode?: 'pho' | 'cafe' | 'smart' | 'supervised'; maxPeers?: number; supervisor?: boolean };
+  delegation?: Record<string, string[]>;
+  runtime?: { provider?: string; model?: string; reasoning?: string };
+}
+export interface RawMcpServer {
+  command?: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  url?: string;
+  headers?: Record<string, string>;
+}
+export interface RawMcpConfig { mcpServers?: Record<string, RawMcpServer> }
+export interface ResolvedResource { name: string; path: string }
+export interface ResolvedMcpConfig { mcpServers: Record<string, RawMcpServer> }
+/** JSON-serializable adapter input. All filesystem resource paths/cwd are absolute. */
+export interface ResolvedAgent {
+  name: string;
+  projectRoot: string;
+  instructions: { project: string; agent: string };
+  skills: ResolvedResource[];
+  hooks: ResolvedResource[];
+  mcp: ResolvedMcpConfig;
+  runtime: { provider?: string; model?: string; reasoning?: string };
+  /** The part of runtime that settings.json sets for every agent; it comes before a team's or the agent's choice. */
+  projectRuntime?: { provider?: string; model?: string; reasoning?: string };
+  /** Where the agent is defined: ALP's built-ins, the user's library, or the project (ALPD §41). */
+  source?: 'builtin' | 'library' | 'project';
+  /** The permission mode the agent runs in unless its caller asks for another. */
+  mode?: 'read-only' | 'workspace-write' | 'full-access';
+  description?: string;
+  /** The context window it works in before its runtime compacts, in tokens; absent: the model's (ALPD §57). */
+  context?: number;
+  autocompact?: AutoCompact;
+}

package/src/upgrade.js

@@ -0,0 +1,195 @@
+import { shippedTemplateRoot } from './template-path.js';
+import { projectProfiles, normalizeAgentProfiles, syncTemplateProfiles } from './profiles.js';
+import { readFile, writeFile, mkdir, mkdtemp, lstat, readdir, rename, rm, rmdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createHash } from 'node:crypto';
+import { initProject } from './init.js';
+import { validateSettings } from './validation.js';
+import { resolveDelegation } from './delegation.js';
+
+const legacy = {
+  'ALP.md': '# Project instructions\n\nAdd project-wide instructions here.\n',
+  '.alp/agents/main/AGENT.md': '# Main agent\n\nHelp with tasks in this project.\n',
+};
+// SHA-256 of shipped role definitions after CRLF normalization. Custom
+// definitions do not match and remain untouched. Keep historical IDs immutable.
+const teamV1 = {
+  'ALP.md': ['c2785aac6538d10e79bd6fb59b11066ccdec77287edf950fad59aa57bf3417f1', '0875293195d35d965effb70bb150d1edbc789f66f72c545f7760dea4346b1a9a'],
+  '.alp/agents/main/AGENT.md': ['15d217cbc5ede782790d1086124598d9a2b5ff13bcf971a37231962fcef1b47c', 'e7201a1ed7800d7500b5c8091bd8a435aa9d5138f247c2b02b8bf76299387c90', '5001b807bbb686aa1a3b7ecadf9501428909e052e8231281454fd41cbe0ebf27', '90f9903fcc97ddf6336e1a28b81103dddc60a6038dcf74d326be8998862cb022', '9085ab906e2744a4151ae5c63dd66a545115cd4c876be1fd80f0a0ed4e623da8', 'fb55cfb0852d07592090de2c49e6c5c2b57936cbffc823dd24767c2db5e5f7fb'],
+  '.alp/agents/lead/AGENT.md': ['c259b085a3c102445f97e5c7d402ca68347bcc1a9b02d6ab96e02be6d8b6f9af', '2eef2a4474f757cd89b35b50638a1b23fe49a54c26bf0dedb24a96d7117ddd92', '6c71393c9b3aa655c4731bda96396ea3ec0d4da62cddb3ad50d1a24113416b77', 'a382f0faa724e23a0ba9c212205978aa3fef87c3aecdf8823fba136e04568487', '547e3f8fc354b22c7beb3432182d68f4de1f24938375c8bfb167ae8afbf97de2'],
+  '.alp/agents/peer/AGENT.md': ['f3dcf16c8c899a5378a468e922ca3956fd72cbb3e3798ed1109f11e01aa8f476', '39ccf3317eba3003faad77ebad4489fae3eb3c4d89258a03f619d1d3d65af0b7', 'c59e45e8f22eb0daca9b8b5e1b19e90666156807f160e75a21eca48b5fee1102', '9623dbf76eda598f6267629e993663c149acb0efd253f3900a4ee1eda8f2f9e7'],
+  '.alp/agents/oracle/AGENT.md': ['cdce1babcd587a190dc94a32a951ed70ce2c75f99c205a4049df940851ac7059'],
+  '.alp/agents/reviewer/AGENT.md': ['6eab9f918c79335a0665bf4e3a3a26b66258684d6725c4c95637e70e8d355123'],
+};
+/** Profiles' names before 0.4. */
+const renamedProfiles = { smart: 'pho', supervised: 'cafe' };
+
+/** A skill directory's regular files by relative path, CRLF-normalized; undefined when absent or not plain files. */
+async function skillFiles(directory) {
+  const files = new Map();
+  async function walk(relative) {
+    for (const entry of await readdir(path.join(directory, relative), { withFileTypes: true })) {
+      const name = relative ? `${relative}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) { if (!await walk(name)) return false; }
+      else if (entry.isFile()) files.set(name, (await readFile(path.join(directory, name), 'utf8')).replaceAll('\r\n', '\n'));
+      else return false;
+    }
+    return true;
+  }
+  try {
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.isSymbolicLink()) return undefined;
+    return await walk('') ? files : undefined;
+  } catch (error) {
+    if (error.code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+/** Explicit migration of the original scaffold; custom instructions remain owned by the user. */
+export async function upgradeProject(projectRoot, { library, templates } = {}) {
+  const root = path.resolve(projectRoot);
+  // Validate before creating files or changing settings.
+  let settingsText;
+  try { settingsText = await readFile(path.join(root, '.alp/settings.json'), 'utf8'); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const settings = settingsText === undefined ? undefined : JSON.parse(settingsText);
+  if (settings !== undefined) validateSettings(settings, '.alp/settings.json');
+  await resolveDelegation(root);
+  const result = { ...await initProject(root, { library, templates, syncProfiles: false }), updated: [], removed: [], customSkills: [], customInstructions: [], backup: undefined };
+  async function backupPath(name) {
+    if (!result.backup) {
+      const backups = path.join(root, '.alp/backups');
+      await mkdir(backups, { recursive: true });
+      result.backup = await mkdtemp(path.join(backups, 'upgrade-'));
+    }
+    const backup = path.join(result.backup, name);
+    await mkdir(path.dirname(backup), { recursive: true });
+    return backup;
+  }
+  async function replace(name, before, after) {
+    const target = path.join(root, name);
+    if (!(await lstat(target)).isFile() || await readFile(target, 'utf8') !== before) throw new Error(`File changed during upgrade: ${target}`);
+    const backup = await backupPath(name);
+    await writeFile(backup, before, { flag: 'wx' });
+    await writeFile(target, after);
+    result.updated.push(name);
+  }
+  for (const name of ['ALP.md']) {
+    const current = await readFile(path.join(root, name), 'utf8');
+    const template = name === 'ALP.md' ? 'ALP.md' : name.slice('.alp/'.length);
+    const desired = await readFile(new URL(`${template}`, shippedTemplateRoot()), 'utf8');
+    const normalized = current.replaceAll('\r\n', '\n');
+    const known = normalized === legacy[name] || teamV1[name]?.includes(createHash('sha256').update(normalized).digest('hex'));
+    if (current !== desired && known) await replace(name, current, desired);
+    else if (current !== desired) result.customInstructions.push(name);
+  }
+  const oldGraph = settings?.delegation;
+  const shippedGraph = oldGraph && Object.keys(oldGraph).length === 2 && JSON.stringify(oldGraph.main) === '["lead"]' && JSON.stringify(oldGraph.lead) === '["peer"]';
+  if (settings !== undefined) {
+    let next = structuredClone(settings);
+    if (next.workflow === undefined && (oldGraph === undefined || shippedGraph)) {
+      if (shippedGraph) delete next.delegation;
+      next.workflow = { mode: shippedGraph ? 'cafe' : 'pho', maxPeers: 2 };
+    } else if (Object.hasOwn(renamedProfiles, next.workflow?.mode)) next.workflow.mode = renamedProfiles[next.workflow.mode];
+    next.team = next.team || next.profile
+      ? { ...(next.profile ?? {}), ...(next.team ?? {}) }
+      : await projectProfiles({ root, library, templates, runtime: next.runtime });
+    delete next.profile;
+    for (const profile of Object.values(next.team ?? {})) {
+      for (const [name, config] of Object.entries(profile)) profile[name] = normalizeAgentProfiles(config, name);
+    }
+    next = await syncTemplateProfiles(next, { root, library, templates });
+    validateSettings(next, '.alp/settings.json');
+    if (JSON.stringify(next) !== JSON.stringify(settings)) await replace('.alp/settings.json', settingsText, JSON.stringify(next, null, 2) + '\n');
+  }
+  // Skills now come from the user's library; archive project copies that still match what ALP shipped.
+  const shipped = JSON.parse(await readFile(new URL('role-skills.json', shippedTemplateRoot()), 'utf8'));
+  for (const [role, skills] of Object.entries(shipped)) {
+    for (const skill of skills) {
+      const relative = `.alp/agents/${role}/skills/${skill}`;
+      const files = await skillFiles(path.join(root, relative));
+      if (!files) continue;
+      const template = await skillFiles(fileURLToPath(new URL(`skills/${skill}`, shippedTemplateRoot())));
+      const same = template && files.size === template.size && [...files].every(([name, text]) => template.get(name) === text);
+      if (!same) { result.customSkills.push(relative); continue; }
+      for (const name of files.keys()) await rename(path.join(root, relative, name), await backupPath(`${relative}/${name}`));
+      await rm(path.join(root, relative), { recursive: true });
+      result.removed.push(relative);
+    }
+  }
+  // Retire only the exact previously shipped router; archive it outside discovery.
+  for (const role of ['main', 'lead', 'peer']) {
+    const relative = `.alp/agents/${role}/skills/ask-alp`;
+    const directory = path.join(root, relative);
+    try {
+      const info = await lstat(directory);
+      if (!info.isDirectory() || info.isSymbolicLink()) { result.customSkills.push(relative); continue; }
+      const names = await readdir(directory);
+      const file = path.join(directory, 'SKILL.md');
+      if (names.length !== 1 || names[0] !== 'SKILL.md' || !(await lstat(file)).isFile()) { result.customSkills.push(relative); continue; }
+      const content = await readFile(file, 'utf8');
+      const hash = createHash('sha256').update(content.replaceAll('\r\n', '\n')).digest('hex');
+      if (hash !== 'f38128fafa2e8a75a0237a2fda9a71fc92ed3f1e0e62878db50e5a07376f2108') { result.customSkills.push(relative); continue; }
+      await rename(file, await backupPath(`${relative}/SKILL.md`));
+      await rmdir(directory);
+      result.removed.push(relative);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+  await retireAgentCopies(root, result, backupPath, replace);
+  return result;
+}
+
+const known = (name, text) => {
+  const normalized = text.replaceAll('\r\n', '\n');
+  return normalized === legacy[name] || teamV1[name]?.includes(createHash('sha256').update(normalized).digest('hex'));
+};
+
+/** An agent directory's entries apart from AGENT.md, when they hold nothing: an empty .mcp.json and empty skills/ and hooks/. */
+async function onlyInstructions(directory) {
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    if (entry.name === 'AGENT.md' && entry.isFile()) continue;
+    if (entry.name === '.mcp.json' && entry.isFile()) {
+      try { const mcp = JSON.parse(await readFile(path.join(directory, entry.name), 'utf8')); if (!Object.keys(mcp.mcpServers ?? {}).length && Object.keys(mcp).every(key => key === 'mcpServers')) continue; } catch {}
+      return false;
+    }
+    if ((entry.name === 'skills' || entry.name === 'hooks') && entry.isDirectory() && !(await readdir(path.join(directory, entry.name))).length) continue;
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Projects used to get a copy of each built-in agent (ALPD §41). A copy that is still
+ * what ALP shipped, with nothing added, is backed up and removed, so the project uses
+ * the built-in and its updates. A shipped copy the user added skills, MCP servers or
+ * hooks to stays as the project's override, with its instructions brought up to date;
+ * customized instructions stay as they are.
+ */
+async function retireAgentCopies(root, result, backupPath, replace) {
+  for (const name of ['main', 'lead', 'peer', 'oracle', 'reviewer', 'supervisor']) {
+    const relative = `.alp/agents/${name}`;
+    const directory = path.join(root, relative);
+    const info = await lstat(directory).catch(() => undefined);
+    if (!info?.isDirectory() || info.isSymbolicLink()) continue;
+    const file = `${relative}/AGENT.md`;
+    const current = await readFile(path.join(root, file), 'utf8').catch(() => undefined);
+    if (current === undefined) continue;
+    const desired = await readFile(new URL(`agents/${name}/AGENT.md`, shippedTemplateRoot()), 'utf8');
+    const shipped = current === desired || known(file, current);
+    if (!shipped) { result.customInstructions.push(file); continue; }
+    if (await onlyInstructions(directory)) {
+      // Its empty skills/ and hooks/ go; its files go to the backup, beside any skills archived above.
+      for (const entry of await readdir(directory, { withFileTypes: true })) {
+        if (entry.isDirectory()) await rmdir(path.join(directory, entry.name));
+        else await rename(path.join(directory, entry.name), await backupPath(`${relative}/${entry.name}`));
+      }
+      await rmdir(directory);
+      result.removed.push(relative);
+    } else if (current !== desired) {
+      await replace(file, current, desired);
+    }
+  }
+  await rmdir(path.join(root, '.alp/agents')).catch(() => {});
+}

package/src/user-settings.d.ts

@@ -0,0 +1,6 @@
+export const DEFAULT_LANGUAGE: string;
+export const LANGUAGE_CHARS: number;
+export function userLanguage(home?: string): Promise<string>;
+export function languageSetting(home: string): Promise<{ language: string | null; applies: string; default: string }>;
+export function setLanguage(home: string | undefined, language: string | null): Promise<{ language: string | null; applies: string; default: string }>;
+export function setWebRelay(home: string, patch: { enabled?: boolean; endpoint?: string; useTls?: boolean }): Promise<{ enabled?: boolean; endpoint?: string; useTls?: boolean }>;

package/src/user-settings.js

@@ -0,0 +1,76 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { moveFile } from './atomic.js';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { AlpError } from './errors.js';
+import { validateUserSettings } from './validation.js';
+
+/**
+ * The user's own settings in $ALP_HOME/settings.json that ALP and its screens edit
+ * (ALPD §54). The language is the one everything the user reads is written in:
+ * agents' messages and questions, approvals, and ALP's own notices.
+ */
+
+/** The language ALP and its agents write in for the user when none is set. */
+export const DEFAULT_LANGUAGE = 'Vietnamese';
+export const LANGUAGE_CHARS = 40;
+
+async function readSettings(home) {
+  const file = path.join(home, 'settings.json');
+  let text;
+  try { text = await readFile(file, 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT') return { file, settings: {} }; throw error; }
+  let settings;
+  try { settings = JSON.parse(text); }
+  catch (cause) { throw new AlpError('INVALID_SETTINGS', `${file}: ${cause.message}`, { cause }); }
+  return { file, settings: validateUserSettings(settings, file) };
+}
+
+/** The user's language: their setting, else Vietnamese. A broken settings file falls back too. */
+export async function userLanguage(home) {
+  if (!home) return DEFAULT_LANGUAGE;
+  try { return (await readSettings(home)).settings.language ?? DEFAULT_LANGUAGE; }
+  catch { return DEFAULT_LANGUAGE; }
+}
+
+/** What the settings screen shows: the language set, if any, and the one that applies. */
+export async function languageSetting(home) {
+  const { settings } = await readSettings(home);
+  return { language: settings.language ?? null, applies: settings.language ?? DEFAULT_LANGUAGE, default: DEFAULT_LANGUAGE };
+}
+
+/**
+ * Sets the user's language, or clears it with null so the default applies. Other keys
+ * of settings.json are kept as they are.
+ */
+export async function setLanguage(home, language) {
+  if (!home) throw new AlpError('INVALID_SCOPE', 'No library: ALP_HOME is not set');
+  if (language !== null && (typeof language !== 'string' || !language.trim() || language.trim().length > LANGUAGE_CHARS)) {
+    throw new AlpError('INVALID_SETTINGS', `A language is a name of at most ${LANGUAGE_CHARS} characters, such as Vietnamese or English`);
+  }
+  const { file, settings } = await readSettings(home);
+  const next = { ...settings };
+  if (language === null) delete next.language; else next.language = language.trim();
+  validateUserSettings(next, file);
+  await mkdir(home, { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${randomUUID().slice(0, 8)}.tmp`;
+  await writeFile(temporary, JSON.stringify(next, null, 2) + '\n');
+  await moveFile(temporary, file);
+  return languageSetting(home);
+}
+
+/**
+ * Changes the relay setting under web (ALPD §64), keeping everything else in settings.json.
+ * @param {string} home
+ * @param {{ enabled?: boolean, endpoint?: string, useTls?: boolean }} patch
+ */
+export async function setWebRelay(home, patch) {
+  const { file, settings } = await readSettings(home);
+  const next = { ...settings, web: { ...settings.web, relay: { ...settings.web?.relay, ...patch } } };
+  validateUserSettings(next, file);
+  await mkdir(home, { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${randomUUID().slice(0, 8)}.tmp`;
+  await writeFile(temporary, JSON.stringify(next, null, 2) + '\n');
+  await moveFile(temporary, file);
+  return next.web.relay;
+}

package/src/validation.d.ts

@@ -0,0 +1,17 @@
+export const PROJECT_SETTINGS: string[];
+export const USER_SETTINGS: string[];
+export const RETIRED_SETTINGS: { project: Record<string, string>; user: Record<string, string> };
+export function settingsKeys(settings: unknown, known: string[], retired?: Record<string, string>): { unknown: Array<{ key: string; suggestion?: string }>; retired: Array<{ key: string; instead: string }> };
+export function settingsWarnings(settings: unknown, scope: 'project' | 'user'): string[];
+export function validateSettings(settings: unknown, source: string): { provider?: string; model?: string; reasoning?: string };
+export function validateUserSettings(settings: unknown, source: string): { language?: string; permissions?: unknown; limits?: { autoResume?: boolean }; recovery?: { autoResume?: boolean } };
+export function normalizeMcp(raw: unknown, directory: string, source: string): { mcpServers: Record<string, Record<string, unknown>> };
+export function validateResolvedAgent(agent: unknown): unknown;
+export const AGENT_SETTINGS: string[];
+export const CONTEXT_TOKENS: { min: number; max: number };
+export function validateAgentConfig(config: unknown, source: string): { description?: string; provider?: string; model?: string; thinking?: string; mode?: 'read-only' | 'workspace-write' | 'full-access'; skills?: string[]; mcp?: string[]; hooks?: string[] };
+export const HOOK_SETTINGS: string[];
+export const HOOK_EVENTS: string[];
+export const BLOCKING_HOOK_EVENTS: string[];
+export function validateHook(config: unknown, source: string): { description?: string; event: string; command: string; blocking?: boolean; timeoutSec?: number; match?: { agent?: string; label?: string } };
+export function unknownMessage(unknown: { key: string; suggestion?: string }, known: string[]): string;