@anhlp/alp-core 0.0.0-beta.1

package/src/profiles.js

@@ -0,0 +1,139 @@
+import path from 'node:path';
+import os from 'node:os';
+import { createHash } from 'node:crypto';
+import { MODELS } from './models.js';
+import { resolveTeam, teamSources } from './teams.js';
+
+export const userLibrary = () => process.env.ALP_HOME ?? path.join(os.homedir(), '.alp');
+/** Accept the original provider map as well as the model list.
+ * @param {import('./types.js').AgentProfilesConfig | undefined} config
+ * @returns {Array<import('./types.js').AgentModelConfig>}
+ */
+export const oracleProfiles = config => config?.profiles ?? [config?.claude, config?.codex].filter(Boolean);
+
+/** The choices for any agent, accepting the earlier single-model configuration.
+ * @param {import('./types.js').AgentProfilesConfig | undefined} config
+ * @param {string} name
+ * @returns {Array<import('./types.js').AgentModelConfig>}
+ */
+export const agentProfiles = (config, name) => {
+  if (!config) return [];
+  if (name === 'oracle') return oracleProfiles(config).map(parseProfile);
+  const { autocompact, ...legacy } = config;
+  return (config.profiles ?? [legacy]).map(parseProfile);
+};
+
+/** A profile is "provider:model[:effort]", "provider:*" (any model the provider has), or the earlier { provider, model, effort }. */
+export const parseProfile = profile => {
+  if (typeof profile !== 'string') return profile;
+  const [provider, model, effort] = profile.split(':');
+  return { provider, model, ...(effort ? { effort } : {}) };
+};
+/** The string form of a profile: "provider:model", with ":effort" when it has one. */
+export const profileString = profile => `${profileModel(profile)}${profile.effort ? `:${profile.effort}` : ''}`;
+/** The efforts a runtime-prefixed model takes, for the models ALP knows; undefined for others. */
+export const modelEfforts = id => MODELS.find(model => `${model.runtime}:${model.id}` === id)?.efforts;
+/** An effort the model takes: the one wanted, or else the model's own default. */
+export const fitEffort = (id, effort) => {
+  const efforts = modelEfforts(id);
+  if (!efforts?.length || efforts.includes(effort)) return effort;
+  return MODELS.find(model => `${model.runtime}:${model.id}` === id)?.effort ?? efforts[0];
+};
+/** Whether a profile stands for every model of its provider. */
+export const anyModel = profile => profile?.model === '*';
+/** Whether a runtime-prefixed model is one a profile list offers. */
+export const offers = (profiles, model) => profiles.some(profile => anyModel(profile) ? model.startsWith(`${profile.provider}:`) && model.length > profile.provider.length + 1 : profileModel(profile) === model);
+
+/** Only a matching model supplies effort for an explicit choice; otherwise use the first default.
+ * @param {Array<import('./types.js').AgentModelConfig>} profiles
+ * @param {string | undefined} model
+ */
+export const selectedProfile = (profiles, model) => model === undefined ? profiles.find(config => !anyModel(config)) : profiles.find(config => !anyModel(config) && (!config.model || profileModel(config) === model || (!model.includes(':') && config.model === model)));
+
+/** Migrate complete choices while leaving legacy partial overrides readable. */
+export function normalizeAgentProfiles(config, name) {
+  // The earlier object form becomes "provider:model:effort", which says the same.
+  if (config.profiles) return { ...config, profiles: config.profiles.map(profile => typeof profile === 'string' ? profile : profileString(profile)), autocompact: config.autocompact ?? 'auto' };
+  const profiles = agentProfiles(config, name);
+  if (!profiles.length || profiles.some(profile => !profile.model)) return config;
+  return { profiles: profiles.map(profile => profileString({ ...profile, provider: profile.provider ?? profile.model.split(':')[0] })), autocompact: config.autocompact ?? 'auto' };
+}
+
+export const profileModel = config => config?.model ? config.model.includes(':') ? config.model : `${config.provider}:${config.model}` : undefined;
+
+const withEffort = (model, effort) => {
+  if (model.startsWith('acp:') || model.startsWith('antigravity:')) return model;
+  const fitted = fitEffort(model, effort);
+  return fitted ? `${model}:${fitted}` : model;
+};
+
+/** Snapshot current user team choices into editable project profiles. */
+export async function projectProfiles({ root, library = userLibrary(), templates, runtime, teamIds } = {}) {
+  const profiles = {};
+  for (const id of (await teamSources(root, { library, templates })).keys()) {
+    if (teamIds && !teamIds.includes(id)) continue;
+    const team = await resolveTeam(root, id, { library, templates });
+    const fallback = team.members[team.main].model ?? 'codex:gpt-6.1-sol';
+    const profile = {};
+    for (const [name, member] of Object.entries(team.members)) {
+      if (name === 'oracle') continue;
+      const chosen = runtime?.model ? (runtime.model.includes(':') ? runtime.model : `${runtime.provider ?? 'codex'}:${runtime.model}`) : runtime?.provider ? (runtime.provider === 'claude' ? 'claude:claude-opus-5-5' : 'codex:gpt-6.1-sol') : member.model ?? fallback;
+      profile[name] = { profiles: [withEffort(chosen, runtime?.reasoning ?? member.thinking ?? team.members[team.main].thinking ?? 'medium')], autocompact: 'auto' };
+    }
+    if (team.supervisor) profile[team.supervisor.agent] = { profiles: [withEffort(team.supervisor.model ?? fallback, team.supervisor.thinking ?? 'medium')], autocompact: 'auto' };
+    if (team.members.oracle) profile.oracle = { profiles: (team.oracleModels ?? ['claude:claude-fable-5-1', 'codex:gpt-6-astra'])
+      .map(model => withEffort(model, team.oracleThinking?.[model] ?? team.oracleThinking?.[model.split(':')[0]] ?? 'high')), autocompact: 'auto' };
+    profiles[id] = profile;
+  }
+  return profiles;
+}
+
+/** Apply per-project agent choices without replacing the team's graph or rules. */
+export function applyProfile(team, profile) {
+  if (!profile) return team;
+  const next = structuredClone(team);
+  for (const [name, config] of Object.entries(profile)) {
+    if (name === 'oracle') {
+      const lenses = oracleProfiles(config).map(parseProfile);
+      next.oracleModels = lenses.map(profileModel);
+      const efforts = lenses.filter(lens => lens.effort);
+      if (efforts.length) next.oracleThinking = { ...next.oracleThinking, ...Object.fromEntries(efforts.map(lens => [profileModel(lens), lens.effort])) };
+    } else {
+      const target = next.members[name] ?? (next.supervisor && next.supervisor.agent === name ? next.supervisor : undefined);
+      if (!target) throw new Error(`team.${team.id}.${name}: agent is not in this team`);
+      const first = agentProfiles(config, name).find(profile => !anyModel(profile));
+      if (first?.model) target.model = profileModel(first);
+      if (first?.effort) target.thinking = first.effort;
+    }
+  }
+  return next;
+}
+
+/** Fingerprints let generated defaults follow templates without replacing hand-edited project choices. */
+export const profileFingerprint = (config, name) => createHash('sha256').update(JSON.stringify(agentProfiles(config, name).map(profileString))).digest('hex');
+export const profileDefaults = profiles => Object.fromEntries(Object.entries(profiles).map(([team, agents]) => [team, Object.fromEntries(Object.entries(agents).map(([name, config]) => [name, profileFingerprint(config, name)]))]));
+
+/** Refresh only inherited profiles; older scaffolds are recognized by their shipped defaults. */
+export async function syncTemplateProfiles(settings, options = {}) {
+  const defaults = await projectProfiles({ ...options, runtime: options.replaceModels ? undefined : settings.runtime });
+  const legacy = settings.templateDefaults ? undefined : await projectProfiles({ templates: options.templates, library: '', runtime: settings.runtime });
+  const previous = settings.templateDefaults ?? profileDefaults(legacy);
+  const next = structuredClone(settings);
+  next.team = { ...(next.profile ?? {}), ...(next.team ?? {}) };
+  delete next.profile;
+  for (const id of new Set([...Object.keys(previous), ...Object.keys(defaults)])) {
+    if (options.teamIds && !options.teamIds.includes(id)) continue;
+    const desired = defaults[id] ?? {};
+    const current = next.team[id] ?? {};
+    for (const name of new Set([...Object.keys(previous[id] ?? {}), ...(options.replaceModels ? Object.keys(current) : []), ...Object.keys(desired)])) {
+      const config = current[name];
+      if (!options.replaceModels && config && profileFingerprint(config, name) !== previous[id]?.[name]) continue;
+      if (desired[name]) current[name] = { ...desired[name], autocompact: config?.autocompact ?? desired[name].autocompact };
+      else delete current[name];
+    }
+    if (Object.keys(current).length) next.team[id] = current;
+    else delete next.team[id];
+  }
+  next.templateDefaults = options.teamIds ? { ...previous, ...profileDefaults(defaults) } : profileDefaults(defaults);
+  return next;
+}

package/src/promptsafe.d.ts

@@ -0,0 +1 @@
+export function promptSafe<T>(text: T): T;

package/src/promptsafe.js

@@ -0,0 +1,19 @@
+/**
+ * Text another agent wrote, or a command printed, reaches an agent's prompt through
+ * mail, handoffs, the board, recall answers, task text and tool results. A literal
+ * system-reminder tag in it could pose as the harness, so ALP strips those tags
+ * before such text enters a prompt (plans/reference/ALPD.md §32). Stripping repeats
+ * until nothing changes, so a tag nested inside another cannot survive.
+ */
+
+const TAG = /<\s*\/?\s*system-reminder\b[^>]*>/gi;
+
+/** `text` without system-reminder open or close tags. */
+export function promptSafe(text) {
+  if (typeof text !== 'string') return text;
+  for (let current = text; ;) {
+    const next = current.replace(TAG, '');
+    if (next === current) return next;
+    current = next;
+  }
+}

package/src/providers.js

@@ -0,0 +1,122 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { AlpError } from './errors.js';
+import { settingsKeys, unknownMessage } from './validation.js';
+
+/**
+ * ACP providers (ALPD §46): agents that speak the Agent Client Protocol, such as Gemini
+ * CLI or opencode, defined in the user's library as providers/<id>.json. An agent runs
+ * on one with `provider: "<id>"` in its agent.json, or with the model `acp:<id>` or
+ * `acp:<id>/<model>`. Providers live only in the library: a project's would run a
+ * command from its repository on the user's machine.
+ *
+ *   { "kind": "acp", "label": "Gemini", "command": "gemini", "args": ["--experimental-acp"],
+ *     "env": {}, "models": [{ "id": "gemini-2.5-pro" }] }
+ *
+ * The web app's Providers screen (ALPD §65) adds `enabled` (false turns it off), `additionalModels`
+ * (added to the models the agent reports, where `models` replaces them) and `params`, which
+ * Paseo's catalog carries and ALP keeps without using.
+ */
+
+export const PROVIDER_SETTINGS = ['$schema', 'kind', 'label', 'description', 'command', 'args', 'env', 'models', 'additionalModels', 'enabled', 'params', 'readOnlyMode'];
+/** Runtimes ALP has built in; no provider takes their names. */
+export const BUILTIN_RUNTIMES = ['codex', 'claude', 'acp', 'antigravity'];
+/** Names no provider takes: the runtimes, and `alp`, which the web app lists ALP's teams under. */
+export const RESERVED_PROVIDERS = [...BUILTIN_RUNTIMES, 'alp'];
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const nonempty = value => typeof value === 'string' && value.trim().length > 0;
+const validId = id => typeof id === 'string' && /^[\w.-]+$/.test(id) && id !== '.' && id !== '..';
+
+/** Checks a provider definition. */
+export function validateProvider(config, source, id) {
+  const check = (ok, message) => { if (!ok) throw new AlpError('INVALID_PROVIDER', `${source}: ${message}`); };
+  if (id !== undefined) check(validId(id) && (!RESERVED_PROVIDERS.includes(id) || (id === 'antigravity' && config?.kind === 'antigravity')), `'${id}' cannot name a provider: ${RESERVED_PROVIDERS.join(', ')} are taken`);
+  check(object(config), 'expected an object');
+  const { unknown } = settingsKeys(config, PROVIDER_SETTINGS);
+  check(!unknown.length, unknown.length ? unknownMessage(unknown[0], PROVIDER_SETTINGS) : '');
+  check(['acp', 'antigravity'].includes(config.kind), 'kind must be "acp" or "antigravity"');
+  if (config.kind === 'antigravity' && id !== undefined) check(id === 'antigravity', 'Antigravity must use provider ID antigravity');
+  if (config.readOnlyMode !== undefined) check(config.kind === 'antigravity' && ['instructions', 'reject'].includes(config.readOnlyMode), 'readOnlyMode is only for Antigravity and must be "instructions" or "reject"');
+  for (const key of ['label', 'description']) if (config[key] !== undefined) check(typeof config[key] === 'string', `${key} must be a string`);
+  check(nonempty(config.command), 'command must be a nonempty string');
+  if (config.args !== undefined) check(Array.isArray(config.args) && config.args.every(arg => typeof arg === 'string'), 'args must be a list of strings');
+  if (config.env !== undefined) check(object(config.env) && Object.values(config.env).every(value => typeof value === 'string'), 'env must map names to strings');
+  for (const key of ['models', 'additionalModels']) {
+    if (config[key] === undefined) continue;
+    check(Array.isArray(config[key]) && config[key].every(model => object(model) && nonempty(model.id) && !/\s/.test(model.id) &&
+      Object.keys(model).every(field => ['id', 'label', 'description'].includes(field)) &&
+      ['label', 'description'].every(field => model[field] === undefined || typeof model[field] === 'string')), `${key} must list { id, label?, description? }`);
+    check(new Set(config[key].map(model => model.id)).size === config[key].length, `${key} lists an id twice`);
+  }
+  if (config.enabled !== undefined) check(typeof config.enabled === 'boolean', 'enabled must be true or false');
+  if (config.params !== undefined) check(object(config.params), 'params must be an object');
+  return config;
+}
+
+/**
+ * A provider of the library, with its id; undefined when there is none.
+ * @returns {Promise<{ id: string, kind: 'acp' | 'antigravity', label: string, description?: string, command: string, args: string[], env: Record<string, string>, models?: Array<{ id: string, label?: string, description?: string }>, additionalModels?: Array<{ id: string, label?: string, description?: string }>, enabled?: boolean, params?: Record<string, unknown>, readOnlyMode?: 'instructions' | 'reject' } | undefined>}
+ */
+export async function loadProvider(library, id) {
+  if (!library || !validId(id) || (RESERVED_PROVIDERS.includes(id) && id !== 'antigravity')) return undefined;
+  const file = path.join(library, 'providers', `${id}.json`);
+  let text;
+  try { text = await readFile(file, 'utf8'); } catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+  let config;
+  try { config = JSON.parse(text); } catch (cause) { throw new AlpError('INVALID_PROVIDER', `${file}: ${cause.message}`, { cause }); }
+  validateProvider(config, file, id);
+  // A relative command path is the provider file's; a bare name is looked up on PATH.
+  const command = /[\\/]/.test(config.command) ? path.resolve(path.dirname(file), config.command) : config.command;
+  return { id, ...config, label: config.label ?? id, command, args: config.args ?? [], env: config.env ?? {} };
+}
+
+/** Every provider of the library, by id. */
+export async function listProviders(library) {
+  if (!library) return [];
+  let names = [];
+  try { names = await readdir(path.join(library, 'providers')); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  const providers = [];
+  for (const name of names.filter(name => name.endsWith('.json')).sort()) {
+    const provider = await loadProvider(library, name.slice(0, -5));
+    if (provider) providers.push(provider);
+  }
+  return providers;
+}
+
+/**
+ * Splits an ACP model id, `<provider>` or `<provider>/<model>`, as resolveSession keeps it
+ * after the `acp:` prefix.
+ */
+export function acpModel(model) {
+  const slash = model.indexOf('/');
+  return slash < 0 ? { provider: model, model: undefined } : { provider: model.slice(0, slash), model: model.slice(slash + 1) || undefined };
+}
+
+/**
+ * How to start a command without a shell. On Windows a bare name installed with npm is a
+ * `<name>.cmd` shim, which spawn refuses to run without one; its target runs instead: the
+ * native executable it calls, or the Node script, under this Node. A bare name with an .exe or
+ * .com on PATH, any other command, and every command elsewhere are returned as they are.
+ * @param {string} command @param {string[]} [args] @param {Record<string, string | undefined>} [env]
+ * @returns {{ command: string, args: string[] }}
+ */
+export function launchCommand(command, args = [], env = process.env) {
+  if (process.platform !== 'win32' || /[\\/]/.test(command) || path.extname(command)) return { command, args };
+  const key = Object.keys(env).find(name => name.toUpperCase() === 'PATH');
+  for (const directory of (key ? env[key] ?? '' : '').split(';').filter(Boolean)) {
+    if (['.exe', '.com'].some(extension => existsSync(path.join(directory, command + extension)))) break;
+    const shim = path.join(directory, `${command}.cmd`);
+    if (!existsSync(shim)) continue;
+    // npm's cmd-shim ends with `"%dp0%\<target>" %*`, or `"%_prog%" [node flags] "%dp0%\<script>" %*`
+    // for a Node script. Anything else (a hand-written batch file) stays refused by spawn, as before.
+    const text = readFileSync(shim, 'utf8');
+    const script = /"%_prog%"((?:\s+[^\s"]+)*)\s+"%~?dp0%\\?([^"]+)"\s+%\*/i.exec(text);
+    if (script) return { command: process.execPath, args: [...script[1].split(/\s+/).filter(Boolean), path.join(directory, script[2]), ...args] };
+    const native = /^\s*"%~?dp0%\\?([^"]+\.(?:exe|com))"\s+%\*/im.exec(text);
+    if (native) return { command: path.join(directory, native[1]), args };
+    break;
+  }
+  return { command, args };
+}

package/src/resolver.js

@@ -0,0 +1,238 @@
+import { shippedTemplateRoot } from './template-path.js';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { AlpError } from './errors.js';
+import { validateAgentConfig, validateHook, validateSettings, normalizeMcp, validateResolvedAgent } from './validation.js';
+import { librarySkills } from './library.js';
+export { AlpError } from './errors.js';
+
+export async function optionalText(file) {
+  try { return await readFile(file, 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT') return undefined; throw error; }
+}
+
+export async function jsonObject(file, code) {
+  const text = await optionalText(file);
+  if (text === undefined) return {};
+  try {
+    const value = JSON.parse(text);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('expected a JSON object');
+    return value;
+  } catch (cause) { throw new AlpError(code, `${file}: ${cause.message}`, { cause }); }
+}
+
+async function entries(directory) {
+  try { return (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name)); }
+  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+}
+
+/** The agents ALP ships; their files come from the package's templates. */
+export const BUILTIN_AGENTS = ['main', 'lead', 'peer', 'oracle', 'reviewer', 'supervisor'];
+/**
+ * The package's templates directory, found when first needed. Paseo re-bundles plugin
+ * code where import.meta.url is no URL, so this must not run when the module loads;
+ * there, bundles pass `templates` instead.
+ */
+const templateRoot = () => { try { return shippedTemplateRoot(); } catch { return undefined; } };
+const validName = name => typeof name === 'string' && /^[\w.-]+$/.test(name) && name !== '.' && name !== '..';
+
+/** A shipped template file, from `templates` when given (bundles embed them), else from the package. */
+export async function builtinText(relative, templates) {
+  if (templates) return templates[relative];
+  const root = templateRoot();
+  if (!root) return undefined;
+  try { return await readFile(new URL(relative, root), 'utf8'); }
+  catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return undefined; throw error; }
+}
+
+/**
+ * Where each agent comes from (ALPD §41): ALP's built-ins, then the user's library
+ * (`library`, ALP_HOME), then the project's `.alp/agents`. A later layer replaces an
+ * agent of the same name entirely.
+ * @returns {Promise<Map<string, { source: 'builtin' | 'library' | 'project', directory?: string, overrides?: 'builtin' | 'library' }>>}
+ */
+export async function agentSources(root, { library, templates } = {}) {
+  const found = new Map();
+  for (const name of BUILTIN_AGENTS) if (await builtinText(`agents/${name}/AGENT.md`, templates) !== undefined) found.set(name, { source: 'builtin' });
+  const layer = async (directory, source) => {
+    for (const entry of await entries(directory)) {
+      if (!entry.isDirectory() || !validName(entry.name)) continue;
+      // A library entry needs its instructions; a project directory always counts, as before, and reports a missing AGENT.md when used.
+      if (source === 'library' && (await optionalText(path.join(directory, entry.name, 'AGENT.md'))) === undefined) continue;
+      const previous = found.get(entry.name);
+      found.set(entry.name, { source, directory: path.join(directory, entry.name), ...(previous ? { overrides: previous.source } : {}) });
+    }
+  };
+  if (library) await layer(path.join(library, 'agents'), 'library');
+  // Without a project, only the built-ins and the library apply.
+  if (root !== undefined) await layer(path.join(path.resolve(root), '.alp', 'agents'), 'project');
+  return found;
+}
+
+export async function discoverAgents(root, options = {}) {
+  return [...(await agentSources(root, options)).keys()].sort((a, b) => a.localeCompare(b));
+}
+
+/** What a library kind holds, and the file that defines each entry. */
+const KINDS = {
+  skills: name => path.join(name, 'SKILL.md'),
+  mcp: name => `${name}.json`,
+  hooks: name => `${name}.json`,
+  // ACP providers (ALPD §46) live only in the library.
+  providers: name => `${name}.json`,
+};
+export const LIBRARY_KINDS = ['agents', ...Object.keys(KINDS)];
+
+/**
+ * Every entry of one kind with where it comes from (ALPD §41): `agents`, `skills`, `mcp`
+ * or `hooks`. A project entry overrides a library one of the same name. `usedBy` lists
+ * the agents that name a skill, MCP server or hook; for skills it includes the roles
+ * role-skills.json gives it.
+ * @returns {Promise<Array<{ name: string, source: 'builtin' | 'library' | 'project', path?: string, overrides?: 'builtin' | 'library', description?: string, usedBy?: string[] }>>}
+ */
+export async function libraryEntries(kind, projectRoot, { library, templates } = {}) {
+  const root = projectRoot === undefined ? undefined : path.resolve(projectRoot);
+  if (kind === 'agents') {
+    const rows = [];
+    for (const [name, source] of await agentSources(root, { library, templates })) {
+      const text = source.directory ? await optionalText(path.join(source.directory, 'agent.json')) : await builtinText(`agents/${name}/agent.json`, templates);
+      let description;
+      try { description = text === undefined ? undefined : JSON.parse(text).description; } catch {}
+      rows.push({ name, source: source.source, ...(source.directory ? { path: source.directory } : {}), ...(source.overrides ? { overrides: source.overrides } : {}), ...(typeof description === 'string' ? { description } : {}) });
+    }
+    return rows.sort((a, b) => a.name.localeCompare(b.name));
+  }
+  const file = KINDS[kind];
+  if (!file) throw new AlpError('INVALID_KIND', `Unknown library kind '${kind}'; use one of ${LIBRARY_KINDS.join(', ')}`);
+  const found = new Map();
+  const layer = async (directory, source) => {
+    for (const entry of await entries(directory)) {
+      const name = kind === 'skills' ? (entry.isDirectory() ? entry.name : undefined) : (entry.isFile() && entry.name.endsWith('.json') ? entry.name.slice(0, -5) : undefined);
+      if (!name || !validName(name)) continue;
+      const entryPath = path.join(directory, file(name));
+      if (!(await stat(entryPath).then(info => info.isFile(), () => false))) continue;
+      const previous = found.get(name);
+      found.set(name, { name, source, path: entryPath, ...(previous ? { overrides: previous.source } : {}) });
+    }
+  };
+  if (library) await layer(path.join(library, kind), 'library');
+  if (root !== undefined && kind !== 'providers') await layer(path.join(root, '.alp', kind), 'project');
+  // Who uses each entry: the agents naming it in agent.json, and for skills the roles given it.
+  const users = new Map();
+  const use = (name, agent) => users.set(name, [...new Set([...(users.get(name) ?? []), agent])]);
+  for (const [agent, source] of await agentSources(root, { library, templates })) {
+    const text = source.directory ? await optionalText(path.join(source.directory, 'agent.json')) : await builtinText(`agents/${agent}/agent.json`, templates);
+    try {
+      const config = text === undefined ? {} : JSON.parse(text);
+      // An agent names its provider, or the list of each other kind.
+      for (const name of kind === 'providers' ? [config.provider].filter(Boolean) : config[kind] ?? []) use(name, agent);
+    } catch {}
+  }
+  if (kind === 'skills' && library) {
+    try { for (const [role, names] of Object.entries(JSON.parse((await optionalText(path.join(library, 'role-skills.json'))) ?? '{}'))) for (const name of Array.isArray(names) ? names : []) use(name, role); } catch {}
+  }
+  return [...found.values()].map(row => ({ ...row, ...(users.has(row.name) ? { usedBy: users.get(row.name).sort() } : {}) })).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** A named entry of a library kind (skills, mcp, hooks): the project's first, then the library's. */
+async function namedEntry(root, library, kind, name, file) {
+  const candidates = [path.join(root, '.alp', kind, file(name)), ...(library ? [path.join(library, kind, file(name))] : [])];
+  for (const candidate of candidates) if (await stat(candidate).then(info => info.isFile(), () => false)) return candidate;
+  return undefined;
+}
+
+/**
+ * `library` is the user's library (ALP_HOME): its agents and the skills, MCP servers and
+ * hooks agents name. The agent's own skills/ directory replaces a skill of the same name.
+ * @returns {Promise<import('./types.js').ResolvedAgent>}
+ */
+export async function resolveAgent(projectRoot, { agent, library, templates } = {}) {
+  const root = path.resolve(projectRoot);
+  const settingsPath = path.join(root, '.alp', 'settings.json');
+  const settings = await jsonObject(settingsPath, 'INVALID_SETTINGS');
+  const projectRuntime = validateSettings(settings, settingsPath);
+  const name = agent ?? settings.defaultAgent ?? 'main';
+  if (typeof name !== 'string' || !name.trim() || name === '.' || name === '..' || /[\\/\x00]/.test(name)) {
+    throw new AlpError('INVALID_AGENT', 'Agent name must be a single nonempty directory name');
+  }
+  const source = (await agentSources(root, { library, templates })).get(name);
+  if (!source) throw new AlpError('AGENT_NOT_FOUND', `Agent '${name}' not found: it is not built in, nor under ${library ? `${path.join(library, 'agents')} or ` : ''}${path.join(root, '.alp', 'agents')}`);
+  const directory = source.directory;
+  const agentPath = directory ? path.join(directory, 'AGENT.md') : `built-in agents/${name}/AGENT.md`;
+  const instructions = directory ? await optionalText(agentPath) : await builtinText(`agents/${name}/AGENT.md`, templates);
+  if (instructions === undefined) throw new AlpError('AGENT_INSTRUCTIONS_MISSING', `Missing ${agentPath}`);
+  const configPath = directory ? path.join(directory, 'agent.json') : `built-in agents/${name}/agent.json`;
+  const configText = directory ? await optionalText(configPath) : await builtinText(`agents/${name}/agent.json`, templates);
+  let config = {};
+  if (configText !== undefined) {
+    try { config = JSON.parse(configText); }
+    catch (cause) { throw new AlpError('INVALID_AGENT_CONFIG', `${configPath}: ${cause.message}`, { cause }); }
+  }
+  validateAgentConfig(config, configPath);
+
+  // The role's library skills; a project skill of the same name in .alp/skills replaces one.
+  const skills = [];
+  for (const skill of library ? await librarySkills(library, name) : []) {
+    skills.push({ name: skill.name, path: (await namedEntry(root, undefined, 'skills', skill.name, entry => path.join(entry, 'SKILL.md'))) ?? skill.path });
+  }
+  const addSkill = (skillName, skillPath) => {
+    const shadowed = skills.findIndex(skill => skill.name === skillName);
+    if (shadowed >= 0) skills.splice(shadowed, 1);
+    skills.push({ name: skillName, path: skillPath });
+  };
+  for (const skillName of config.skills ?? []) {
+    const skillPath = await namedEntry(root, library, 'skills', skillName, entry => path.join(entry, 'SKILL.md'));
+    if (!skillPath) throw new AlpError('SKILL_NOT_FOUND', `${configPath}: skill '${skillName}' is neither in ${path.join(root, '.alp', 'skills')} nor in the library`);
+    addSkill(skillName, skillPath);
+  }
+  if (directory) {
+    for (const entry of await entries(path.join(directory, 'skills'))) {
+      if (!entry.isDirectory()) continue;
+      const skillPath = path.join(directory, 'skills', entry.name, 'SKILL.md');
+      try { if ((await stat(skillPath)).isFile()) addSkill(entry.name, skillPath); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+  }
+  skills.sort((a, b) => a.name.localeCompare(b.name));
+
+  const hooks = directory ? (await entries(path.join(directory, 'hooks'))).filter(e => e.isFile()).map(e => ({ name: e.name, path: path.join(directory, 'hooks', e.name) })) : [];
+  for (const hookName of config.hooks ?? []) {
+    const hookPath = await namedEntry(root, library, 'hooks', hookName, entry => `${entry}.json`);
+    if (!hookPath) throw new AlpError('HOOK_NOT_FOUND', `${configPath}: hook '${hookName}' is neither in ${path.join(root, '.alp', 'hooks')} nor in the library`);
+    validateHook(await jsonObject(hookPath, 'INVALID_HOOK'), hookPath);
+    hooks.push({ name: hookName, path: hookPath });
+  }
+
+  // Named MCP servers first, then the agent's own .mcp.json; a name used twice is an error.
+  const servers = {};
+  for (const serverName of config.mcp ?? []) {
+    const serverPath = await namedEntry(root, library, 'mcp', serverName, entry => `${entry}.json`);
+    if (!serverPath) throw new AlpError('MCP_NOT_FOUND', `${configPath}: MCP server '${serverName}' is neither in ${path.join(root, '.alp', 'mcp')} nor in the library`);
+    const definition = await jsonObject(serverPath, 'INVALID_MCP');
+    Object.assign(servers, normalizeMcp({ mcpServers: { [serverName]: definition } }, path.dirname(serverPath), serverPath).mcpServers);
+  }
+  const mcpPath = directory ? path.join(directory, '.mcp.json') : undefined;
+  const own = mcpPath ? normalizeMcp(await jsonObject(mcpPath, 'INVALID_MCP'), directory, mcpPath).mcpServers : {};
+  for (const [serverName, server] of Object.entries(own)) {
+    if (Object.hasOwn(servers, serverName)) throw new AlpError('INVALID_MCP', `${mcpPath}: MCP server '${serverName}' is also named in ${configPath}`);
+    servers[serverName] = server;
+  }
+
+  // settings.json's runtime is the project's choice for every agent, so it comes before the agent's own (ALPD §42).
+  const runtime = {
+    ...(config.provider !== undefined ? { provider: config.provider } : {}),
+    ...(config.model !== undefined ? { model: config.model } : {}),
+    ...(config.thinking !== undefined ? { reasoning: config.thinking } : {}),
+    ...projectRuntime,
+  };
+  return validateResolvedAgent({
+    name, projectRoot: root, source: source.source,
+    instructions: { project: (await optionalText(path.join(root, 'ALP.md'))) ?? '', agent: instructions },
+    skills, hooks, runtime, projectRuntime: { ...projectRuntime },
+    ...(config.mode !== undefined ? { mode: config.mode } : {}),
+    ...(config.description !== undefined ? { description: config.description } : {}),
+    ...(typeof config.context === 'number' ? { context: config.context } : {}),
+    ...(config.autocompact !== undefined ? { autocompact: config.autocompact } : {}),
+    mcp: { mcpServers: servers },
+  });
+}

package/src/safe-path.js

@@ -0,0 +1,20 @@
+import { lstat } from 'node:fs/promises';
+import path from 'node:path';
+import { AlpError } from './errors.js';
+
+/** Preflight static repository paths. Does not isolate concurrent same-user processes. */
+export async function assertNoSymlinks(directory, relative) {
+  const root = path.resolve(directory);
+  const target = path.resolve(root, relative);
+  const tail = path.relative(root, target);
+  if (tail === '..' || tail.startsWith(`..${path.sep}`) || path.isAbsolute(tail)) {
+    throw new AlpError('UNSAFE_PATH', 'Path escapes its scope');
+  }
+  let current = root;
+  for (const part of ['', ...tail.split(path.sep).filter(Boolean)]) {
+    if (part) current = path.join(current, part);
+    const info = await lstat(current).catch(error => { if (error.code !== 'ENOENT') throw error; });
+    if (!info) return;
+    if (info.isSymbolicLink()) throw new AlpError('UNSAFE_PATH', `Refusing symlink in scoped path: ${current}`);
+  }
+}

package/src/shell.js

@@ -0,0 +1,28 @@
+import { execFile, spawn } from 'node:child_process';
+
+/**
+ * Starts `command` through the platform's shell: /bin/sh -c in its own process group, or on
+ * Windows cmd.exe /d /s /c with the line quoted whole (cmd strips only the outermost quotes,
+ * and Node would otherwise escape the quotes inside it).
+ * @param {string} command
+ * @param {import('node:child_process').SpawnOptions} options
+ */
+export function spawnShell(command, options) {
+  if (process.platform !== 'win32') return spawn('/bin/sh', ['-c', command], { ...options, detached: true });
+  return spawn(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `"${command}"`], { ...options, windowsHide: true, windowsVerbatimArguments: true });
+}
+
+/**
+ * Signals a command `spawnShell` started and everything it started. Windows has no signals and
+ * cmd.exe's children outlive it, so there the whole tree is ended at once by the first signal
+ * and no cleanup runs.
+ * @param {import('node:child_process').ChildProcess} child
+ * @param {NodeJS.Signals} name
+ */
+export function signalShell(child, name) {
+  if (process.platform === 'win32') {
+    if (name === 'SIGTERM') execFile('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true }, () => {});
+    return;
+  }
+  try { process.kill(-child.pid, name); } catch { child.kill(name); }
+}

package/src/state-schema.d.ts

@@ -0,0 +1,9 @@
+export const STATE_SCHEMA: number;
+export const OLDEST_STATE_SCHEMA: number;
+export function stateDir(home: string): string;
+export function schemaFile(home: string): string;
+export function migrationFile(home: string): string;
+export type StateSchemaInfo = { schema: number; fresh: boolean; marked: boolean; by?: string };
+export function readStateSchema(home: string): Promise<StateSchemaInfo>;
+export function assertStateSupported(info: StateSchemaInfo, home: string): StateSchemaInfo;
+export function writeStateSchema(home: string, schema: number, by?: string): Promise<void>;

package/src/state-schema.js

@@ -0,0 +1,60 @@
+import { readdir, readFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { AlpError } from './errors.js';
+import { writeAtomic } from './atomic.js';
+
+/**
+ * The version of alpd's durable state in $ALP_HOME/state (plans/reference/ALPD.md §68).
+ * `state/schema.json` names it; a state directory without one holds schema 1, the format
+ * every ALP before 0.11 wrote. An ALP that finds a newer schema than it knows refuses to
+ * open the state and changes nothing in it; an older one is migrated forward at start.
+ *
+ * 1: session records, receipts and timelines as of ALPD §66; timeline lines may lack a cursor.
+ * 2: every timeline line carries its cursor.
+ */
+export const STATE_SCHEMA = 2;
+export const OLDEST_STATE_SCHEMA = 1;
+
+export const stateDir = home => path.join(home, 'state');
+export const schemaFile = home => path.join(stateDir(home), 'schema.json');
+export const migrationFile = home => path.join(stateDir(home), 'migration.json');
+
+/** Directories whose entries mean the state holds data, so a missing marker means schema 1, not a fresh home. */
+const DATA = ['sessions', 'timeline', 'receipts'];
+
+/**
+ * What the state directory says about its schema. `fresh` when it holds no data and no marker.
+ * An unreadable marker is an error: ALP does not guess which format the data is in.
+ * @param {string} home
+ * @returns {Promise<{ schema: number, fresh: boolean, marked: boolean, by?: string }>}
+ */
+export async function readStateSchema(home) {
+  let text;
+  try { text = await readFile(schemaFile(home), 'utf8'); }
+  catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    for (const name of DATA) {
+      const entries = await readdir(path.join(stateDir(home), name)).catch(error => { if (error?.code === 'ENOENT') return []; throw error; });
+      if (entries.some(entry => !entry.endsWith('.tmp'))) return { schema: 1, fresh: false, marked: false };
+    }
+    return { schema: STATE_SCHEMA, fresh: true, marked: false };
+  }
+  let marker;
+  try { marker = JSON.parse(text); } catch {}
+  if (!marker || !Number.isSafeInteger(marker.schema) || marker.schema < 1) {
+    throw new AlpError('STATE_SCHEMA_UNREADABLE', `${schemaFile(home)} does not name a state schema; ALP does not open state whose format it cannot tell. Restore a backup, or put back the file`);
+  }
+  return { schema: marker.schema, fresh: false, marked: true, ...(typeof marker.by === 'string' ? { by: marker.by } : {}) };
+}
+
+/** Refuses state written in a schema this ALP does not know, before anything touches it. */
+export function assertStateSupported(info, home) {
+  if (info.schema <= STATE_SCHEMA) return info;
+  throw new AlpError('STATE_SCHEMA_TOO_NEW', `${stateDir(home)} holds state schema ${info.schema}${info.by ? `, written by ${info.by}` : ''}; this ALP knows schema ${STATE_SCHEMA} at most and leaves it untouched. Run that ALP version or a newer one, or replace it with a backup made for this version: alp restore FILE --replace-newer (docs/alp/data-recovery.md)`);
+}
+
+/** Records the schema the state is now in; written atomically. */
+export async function writeStateSchema(home, schema, by) {
+  await mkdir(stateDir(home), { recursive: true, mode: 0o700 });
+  await writeAtomic(schemaFile(home), JSON.stringify({ schema, by, at: new Date().toISOString() }) + '\n');
+}