@anhlp/alp-core 0.0.0-beta.1

package/dist/permissions.js

@@ -0,0 +1,229 @@
+// packages/core/src/permissions.js
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { moveFile } from "./atomic.js";
+import { AlpError } from "./errors.js";
+var BASES = ["read-only", "workspace-write", "full-access"];
+var RANK = { "read-only": 0, "workspace-write": 1, "full-access": 2 };
+var ADVISORS = ["oracle", "reviewer", "supervisor"];
+var MAX_RULES = 200;
+var NAME = /^[\w.-]{1,64}$/;
+var RULE = /^([A-Za-z][\w-]*)(?:\((.*)\))?$/s;
+var TOOLS = ["Bash", "Read", "Edit", "Write", "MultiEdit", "NotebookEdit", "Glob", "Grep", "WebFetch", "WebSearch", "Skill"];
+var own = (value, key) => Object.hasOwn(value, key) ? value[key] : void 0;
+var setOwn = (value, key, entry) => Object.defineProperty(value, key, { value: entry, enumerable: true, writable: true, configurable: true });
+var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var fail = (source, message) => {
+  throw new AlpError("INVALID_SETTINGS", `${source}: ${message}`);
+};
+function parseRule(rule, source = "rule") {
+  if (typeof rule !== "string" || rule.length > 500) fail(source, "a rule is text of at most 500 characters");
+  const match = RULE.exec(rule.trim());
+  if (!match) fail(source, `${JSON.stringify(rule)} is not Tool or Tool(specifier)`);
+  const [, tool, specifier] = match;
+  if (!TOOLS.includes(tool) && !/^mcp__[\w-]+(__[\w-]+)?$/.test(tool)) fail(source, `${JSON.stringify(rule)} names unknown tool ${tool}; use ${TOOLS.join(", ")} or mcp__<server>__<tool>`);
+  if (specifier !== void 0 && !specifier.trim()) fail(source, `${JSON.stringify(rule)} has an empty specifier`);
+  return { tool, ...specifier !== void 0 && specifier.trim() !== "*" ? { specifier: specifier.trim() } : {} };
+}
+function validatePermissions(value, source) {
+  if (value === void 0) return { profiles: {}, agents: {} };
+  if (!object(value)) fail(source, "permissions must be an object");
+  for (const key of Object.keys(value)) if (!["profiles", "agents"].includes(key)) fail(source, `unsupported permissions field '${key}'`);
+  const profiles = {};
+  if (value.profiles !== void 0) {
+    if (!object(value.profiles)) fail(source, "permissions.profiles must be an object");
+    for (const [name, profile] of Object.entries(value.profiles)) {
+      const where = `permissions.profiles.${name}`;
+      if (!NAME.test(name)) fail(source, `${where}: a profile name has letters, digits, dots, dashes and underscores`);
+      if (!object(profile)) fail(source, `${where} must be an object`);
+      for (const key of Object.keys(profile)) if (!["base", "allow", "ask", "deny", "beyondMode", "workdir"].includes(key)) fail(source, `${where}: unsupported field '${key}'`);
+      if (profile.workdir !== void 0 && profile.workdir !== "copy") fail(source, `${where}.workdir must be copy`);
+      if (profile.workdir === "copy" && profile.base !== void 0 && profile.base !== "read-only") fail(source, `${where}: workdir copy is for read-only profiles; writers use worktree isolation`);
+      if (profile.base !== void 0 && !BASES.includes(profile.base)) fail(source, `${where}.base must be ${BASES.join(", ")}`);
+      if (profile.beyondMode !== void 0 && !["refuse", "ask"].includes(profile.beyondMode)) fail(source, `${where}.beyondMode must be refuse or ask`);
+      const rules = {};
+      for (const kind of ["allow", "ask", "deny"]) {
+        const list = profile[kind] ?? [];
+        if (!Array.isArray(list) || list.length > MAX_RULES) fail(source, `${where}.${kind} must list at most ${MAX_RULES} rules`);
+        for (const rule of list) parseRule(rule, `${source}: ${where}.${kind}`);
+        rules[kind] = list.map((rule) => rule.trim());
+      }
+      setOwn(profiles, name, { ...profile.base ? { base: profile.base } : {}, ...profile.beyondMode ? { beyondMode: profile.beyondMode } : {}, ...profile.workdir ? { workdir: profile.workdir } : {}, ...rules });
+    }
+  }
+  const agents = {};
+  if (value.agents !== void 0) {
+    if (!object(value.agents)) fail(source, "permissions.agents must be an object");
+    for (const [agent, profile] of Object.entries(value.agents)) {
+      if (typeof profile !== "string" || !NAME.test(profile)) fail(source, `permissions.agents.${agent} must name a profile`);
+      setOwn(agents, agent, profile);
+    }
+  }
+  return { profiles, agents };
+}
+async function settingsPermissions(file) {
+  let text;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return { profiles: {}, agents: {} };
+    throw error;
+  }
+  let settings;
+  try {
+    settings = JSON.parse(text);
+  } catch (error) {
+    fail(file, `invalid JSON: ${error.message}`);
+  }
+  if (!object(settings)) fail(file, "expected an object");
+  return validatePermissions(settings.permissions, file);
+}
+async function profileFor(projectRoot, home, agent) {
+  const project = await settingsPermissions(path.join(projectRoot, ".alp", "settings.json"));
+  const user = home ? await settingsPermissions(path.join(home, "settings.json")) : { profiles: {}, agents: {} };
+  const name = own(project.agents, agent) ?? own(user.agents, agent);
+  const advisor = ADVISORS.includes(agent);
+  if (!name) return advisor ? { name: "read-only", base: "read-only", allow: [], ask: [], deny: [], beyondMode: "refuse" } : null;
+  const defined = [own(project.profiles, name), own(user.profiles, name)].filter(Boolean);
+  if (!defined.length && !BASES.includes(name)) {
+    throw new AlpError("INVALID_SETTINGS", `permissions.agents.${agent} names profile '${name}', which no settings file defines`);
+  }
+  const base = defined.find((profile) => profile.base)?.base ?? (BASES.includes(name) ? name : advisor ? "read-only" : "full-access");
+  const copy = defined.some((profile) => profile.workdir === "copy");
+  if (copy && base !== "read-only") throw new AlpError("INVALID_SETTINGS", `Profile '${name}' has workdir copy, which needs base read-only`);
+  if (advisor && base !== "read-only") throw new AlpError("INVALID_SETTINGS", `${agent} is an advisor; its profile '${name}' must have base read-only`);
+  return {
+    name,
+    base,
+    allow: [...new Set(defined.flatMap((profile) => profile.allow ?? []))],
+    ask: [...new Set(defined.flatMap((profile) => profile.ask ?? []))],
+    deny: [...new Set(defined.flatMap((profile) => profile.deny ?? []))],
+    beyondMode: defined.find((profile) => profile.beyondMode)?.beyondMode ?? "refuse",
+    ...copy ? { workdir: "copy" } : {}
+  };
+}
+async function addAllowRule(projectRoot, home, profileName, rule) {
+  parseRule(rule);
+  for (const file of [path.join(projectRoot, ".alp", "settings.json"), ...home ? [path.join(home, "settings.json")] : []]) {
+    let settings;
+    try {
+      settings = JSON.parse(await readFile(file, "utf8"));
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw error;
+    }
+    const profile = settings?.permissions?.profiles?.[profileName];
+    if (!object(profile)) continue;
+    profile.allow = [.../* @__PURE__ */ new Set([...profile.allow ?? [], rule])];
+    validatePermissions(settings.permissions, file);
+    const temporary = `${file}.${randomUUID().slice(0, 8)}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(settings, null, 2)}
+`);
+    await moveFile(temporary, file);
+    return file;
+  }
+  throw new AlpError("INVALID_SETTINGS", `No settings file defines profile ${profileName}`);
+}
+var capMode = (mode, base) => (RANK[mode] ?? 0) <= (RANK[base] ?? 0) ? mode : base;
+function unwrapShell(command) {
+  const match = /^(?:\/\S*\/)?(?:ba|z|da)?sh\s+-l?c\s+(['"])([\s\S]*)\1\s*$/.exec(command.trim());
+  if (!match) return command.trim();
+  return match[1] === "'" ? match[2].replace(/'\\''/g, "'") : match[2].replace(/\\(["\\$`])/g, "$1");
+}
+function simpleCommands(line) {
+  const parts = [];
+  let current = "";
+  let quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    if (quote) {
+      if (char === "\\" && quote === '"') {
+        current += char + (line[++i] ?? "");
+        continue;
+      }
+      if (char === quote) quote = null;
+      if (quote === '"' && (char === "`" || char === "$" && line[i + 1] === "(")) return null;
+      current += char;
+      continue;
+    }
+    if (char === "\\") {
+      current += char + (line[++i] ?? "");
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      current += char;
+      continue;
+    }
+    if (char === "`" || char === "$" && line[i + 1] === "(" || (char === "<" || char === ">") && line[i + 1] === "(") return null;
+    const two = line.slice(i, i + 2);
+    if (two === ">&" || two === "<&" || two === "&>") {
+      current += two;
+      i++;
+      continue;
+    }
+    if (two === "&&" || two === "||") {
+      parts.push(current);
+      current = "";
+      i++;
+      continue;
+    }
+    if (char === ";" || char === "|" || char === "\n" || char === "&") {
+      parts.push(current);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (quote) return null;
+  parts.push(current);
+  return parts.map((part) => part.trim()).filter(Boolean);
+}
+function covers(specifier, command) {
+  if (specifier === void 0) return true;
+  const normalized = command.replace(/\s+/g, " ");
+  if (specifier.endsWith(":*") || specifier.endsWith(" *")) {
+    const prefix = specifier.slice(0, -2).trim().replace(/\s+/g, " ");
+    return normalized === prefix || normalized.startsWith(`${prefix} `);
+  }
+  if (specifier.endsWith("*")) return normalized.startsWith(specifier.slice(0, -1).replace(/\s+/g, " "));
+  return normalized === specifier.replace(/\s+/g, " ");
+}
+function redirects(command) {
+  const unquoted = command.replace(/'[^']*'|"(?:[^"\\]|\\.)*"/g, '""');
+  for (const match of unquoted.matchAll(/(?:\d*|&)>>?\s*(&?)(\S*)/g)) {
+    if (match[1] === "&" && /^\d+$/.test(match[2])) continue;
+    if (match[2] === "/dev/null") continue;
+    return true;
+  }
+  return false;
+}
+var bashRules = (rules) => rules.map((rule) => parseRule(rule)).filter((rule) => rule.tool === "Bash");
+function commandDecision(profile, command) {
+  const line = unwrapShell(command);
+  const parts = simpleCommands(line);
+  const deny = bashRules(profile.deny);
+  if (deny.some((rule) => rule.specifier === void 0)) return "deny";
+  if (!parts) return deny.length ? "deny" : (profile.ask ?? []).length ? "ask" : void 0;
+  if (parts.some((part) => deny.some((rule) => covers(rule.specifier, part)))) return "deny";
+  const ask = bashRules(profile.ask ?? []);
+  if (ask.some((rule) => rule.specifier === void 0) || parts.some((part) => ask.some((rule) => covers(rule.specifier, part)))) return "ask";
+  const allow = bashRules(profile.allow);
+  if (parts.every((part) => !redirects(part) && allow.some((rule) => covers(rule.specifier, part)))) return "allow";
+  return void 0;
+}
+export {
+  ADVISORS,
+  BASES,
+  MAX_RULES,
+  TOOLS,
+  addAllowRule,
+  capMode,
+  commandDecision,
+  parseRule,
+  profileFor,
+  simpleCommands,
+  unwrapShell,
+  validatePermissions
+};

package/dist/profiles.d.ts

@@ -0,0 +1,27 @@
+/** Migrate complete choices while leaving legacy partial overrides readable. */
+export function normalizeAgentProfiles(config: any, name: any): any;
+/** Snapshot current user team choices into editable project profiles. */
+export function projectProfiles({ root, library, templates, runtime, teamIds }?: {
+    library?: string | undefined;
+}): Promise<{}>;
+/** Apply per-project agent choices without replacing the team's graph or rules. */
+export function applyProfile(team: any, profile: any): any;
+/** Refresh only inherited profiles; older scaffolds are recognized by their shipped defaults. */
+export function syncTemplateProfiles(settings: any, options?: {}): Promise<any>;
+export function userLibrary(): string;
+export function oracleProfiles(config: import("./types.js").AgentProfilesConfig | undefined): Array<import("./types.js").AgentModelConfig>;
+export function agentProfiles(config: import("./types.js").AgentProfilesConfig | undefined, name: string): Array<import("./types.js").AgentModelConfig>;
+export function parseProfile(profile: any): any;
+export function profileString(profile: any): string;
+export function modelEfforts(id: any): string[] | undefined;
+export function fitEffort(id: any, effort: any): any;
+export function anyModel(profile: any): boolean;
+export function offers(profiles: any, model: any): any;
+export function selectedProfile(profiles: Array<import("./types.js").AgentModelConfig>, model: string | undefined): import("./types.js").AgentModelConfig | undefined;
+export function profileModel(config: any): any;
+export function profileFingerprint(config: any, name: any): string;
+export function profileDefaults(profiles: any): {
+    [k: string]: {
+        [k: string]: string;
+    };
+};

package/dist/profiles.js

@@ -0,0 +1,122 @@
+// packages/core/src/profiles.js
+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";
+var userLibrary = () => process.env.ALP_HOME ?? path.join(os.homedir(), ".alp");
+var oracleProfiles = (config) => config?.profiles ?? [config?.claude, config?.codex].filter(Boolean);
+var agentProfiles = (config, name) => {
+  if (!config) return [];
+  if (name === "oracle") return oracleProfiles(config).map(parseProfile);
+  const { autocompact, ...legacy } = config;
+  return (config.profiles ?? [legacy]).map(parseProfile);
+};
+var parseProfile = (profile) => {
+  if (typeof profile !== "string") return profile;
+  const [provider, model, effort] = profile.split(":");
+  return { provider, model, ...effort ? { effort } : {} };
+};
+var profileString = (profile) => `${profileModel(profile)}${profile.effort ? `:${profile.effort}` : ""}`;
+var modelEfforts = (id) => MODELS.find((model) => `${model.runtime}:${model.id}` === id)?.efforts;
+var 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];
+};
+var anyModel = (profile) => profile?.model === "*";
+var offers = (profiles, model) => profiles.some((profile) => anyModel(profile) ? model.startsWith(`${profile.provider}:`) && model.length > profile.provider.length + 1 : profileModel(profile) === model);
+var selectedProfile = (profiles, model) => model === void 0 ? profiles.find((config) => !anyModel(config)) : profiles.find((config) => !anyModel(config) && (!config.model || profileModel(config) === model || !model.includes(":") && config.model === model));
+function normalizeAgentProfiles(config, name) {
+  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" };
+}
+var profileModel = (config) => config?.model ? config.model.includes(":") ? config.model : `${config.provider}:${config.model}` : void 0;
+var withEffort = (model, effort) => {
+  if (model.startsWith("acp:") || model.startsWith("antigravity:")) return model;
+  const fitted = fitEffort(model, effort);
+  return fitted ? `${model}:${fitted}` : model;
+};
+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;
+}
+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 : void 0);
+      if (!target) throw new Error(`team.${team.id}.${name}: agent is not in this team`);
+      const first = agentProfiles(config, name).find((profile2) => !anyModel(profile2));
+      if (first?.model) target.model = profileModel(first);
+      if (first?.effort) target.thinking = first.effort;
+    }
+  }
+  return next;
+}
+var profileFingerprint = (config, name) => createHash("sha256").update(JSON.stringify(agentProfiles(config, name).map(profileString))).digest("hex");
+var profileDefaults = (profiles) => Object.fromEntries(Object.entries(profiles).map(([team, agents]) => [team, Object.fromEntries(Object.entries(agents).map(([name, config]) => [name, profileFingerprint(config, name)]))]));
+async function syncTemplateProfiles(settings, options = {}) {
+  const defaults = await projectProfiles({ ...options, runtime: options.replaceModels ? void 0 : settings.runtime });
+  const legacy = settings.templateDefaults ? void 0 : 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 /* @__PURE__ */ 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 /* @__PURE__ */ 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;
+}
+export {
+  agentProfiles,
+  anyModel,
+  applyProfile,
+  fitEffort,
+  modelEfforts,
+  normalizeAgentProfiles,
+  offers,
+  oracleProfiles,
+  parseProfile,
+  profileDefaults,
+  profileFingerprint,
+  profileModel,
+  profileString,
+  projectProfiles,
+  selectedProfile,
+  syncTemplateProfiles,
+  userLibrary
+};

package/dist/promptsafe.d.ts

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

package/dist/promptsafe.js

@@ -0,0 +1,13 @@
+// packages/core/src/promptsafe.js
+var TAG = /<\s*\/?\s*system-reminder\b[^>]*>/gi;
+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;
+  }
+}
+export {
+  promptSafe
+};

package/dist/providers.d.ts

@@ -0,0 +1,90 @@
+/** Checks a provider definition. */
+export function validateProvider(config: any, source: any, id: any): any;
+/**
+ * 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 function loadProvider(library: any, id: any): 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>;
+/** Every provider of the library, by id. */
+export function listProviders(library: any): 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";
+}[]>;
+/**
+ * Splits an ACP model id, `<provider>` or `<provider>/<model>`, as resolveSession keeps it
+ * after the `acp:` prefix.
+ */
+export function acpModel(model: any): {
+    provider: any;
+    model: any;
+};
+/**
+ * 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: string, args?: string[], env?: Record<string, string | undefined>): {
+    command: string;
+    args: string[];
+};
+/**
+ * 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: string[];
+/** Runtimes ALP has built in; no provider takes their names. */
+export const BUILTIN_RUNTIMES: string[];
+/** Names no provider takes: the runtimes, and `alp`, which the web app lists ALP's teams under. */
+export const RESERVED_PROVIDERS: string[];

package/dist/providers.js

@@ -0,0 +1,101 @@
+// packages/core/src/providers.js
+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";
+var PROVIDER_SETTINGS = ["$schema", "kind", "label", "description", "command", "args", "env", "models", "additionalModels", "enabled", "params", "readOnlyMode"];
+var BUILTIN_RUNTIMES = ["codex", "claude", "acp", "antigravity"];
+var RESERVED_PROVIDERS = [...BUILTIN_RUNTIMES, "alp"];
+var object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var nonempty = (value) => typeof value === "string" && value.trim().length > 0;
+var validId = (id) => typeof id === "string" && /^[\w.-]+$/.test(id) && id !== "." && id !== "..";
+function validateProvider(config, source, id) {
+  const check = (ok, message) => {
+    if (!ok) throw new AlpError("INVALID_PROVIDER", `${source}: ${message}`);
+  };
+  if (id !== void 0) 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 !== void 0) check(id === "antigravity", "Antigravity must use provider ID antigravity");
+  if (config.readOnlyMode !== void 0) 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] !== void 0) check(typeof config[key] === "string", `${key} must be a string`);
+  check(nonempty(config.command), "command must be a nonempty string");
+  if (config.args !== void 0) check(Array.isArray(config.args) && config.args.every((arg) => typeof arg === "string"), "args must be a list of strings");
+  if (config.env !== void 0) 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] === void 0) 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] === void 0 || 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 !== void 0) check(typeof config.enabled === "boolean", "enabled must be true or false");
+  if (config.params !== void 0) check(object(config.params), "params must be an object");
+  return config;
+}
+async function loadProvider(library, id) {
+  if (!library || !validId(id) || RESERVED_PROVIDERS.includes(id) && id !== "antigravity") return void 0;
+  const file = path.join(library, "providers", `${id}.json`);
+  let text;
+  try {
+    text = await readFile(file, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    throw error;
+  }
+  let config;
+  try {
+    config = JSON.parse(text);
+  } catch (cause) {
+    throw new AlpError("INVALID_PROVIDER", `${file}: ${cause.message}`, { cause });
+  }
+  validateProvider(config, file, id);
+  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 ?? {} };
+}
+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((name2) => name2.endsWith(".json")).sort()) {
+    const provider = await loadProvider(library, name.slice(0, -5));
+    if (provider) providers.push(provider);
+  }
+  return providers;
+}
+function acpModel(model) {
+  const slash = model.indexOf("/");
+  return slash < 0 ? { provider: model, model: void 0 } : { provider: model.slice(0, slash), model: model.slice(slash + 1) || void 0 };
+}
+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;
+    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 };
+}
+export {
+  BUILTIN_RUNTIMES,
+  PROVIDER_SETTINGS,
+  RESERVED_PROVIDERS,
+  acpModel,
+  launchCommand,
+  listProviders,
+  loadProvider,
+  validateProvider
+};

package/dist/resolver.d.ts

@@ -0,0 +1,41 @@
+export function optionalText(file: any): Promise<string | undefined>;
+export function jsonObject(file: any, code: any): Promise<any>;
+/** A shipped template file, from `templates` when given (bundles embed them), else from the package. */
+export function builtinText(relative: any, templates: any): Promise<any>;
+/**
+ * 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 function agentSources(root: any, { library, templates }?: {}): Promise<Map<string, {
+    source: "builtin" | "library" | "project";
+    directory?: string;
+    overrides?: "builtin" | "library";
+}>>;
+export function discoverAgents(root: any, options?: {}): Promise<string[]>;
+/**
+ * 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 function libraryEntries(kind: any, projectRoot: any, { library, templates }?: {}): Promise<Array<{
+    name: string;
+    source: "builtin" | "library" | "project";
+    path?: string;
+    overrides?: "builtin" | "library";
+    description?: string;
+    usedBy?: string[];
+}>>;
+/**
+ * `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 function resolveAgent(projectRoot: any, { agent, library, templates }?: {}): Promise<import("./types.js").ResolvedAgent>;
+export { AlpError } from "./errors.js";
+/** The agents ALP ships; their files come from the package's templates. */
+export const BUILTIN_AGENTS: string[];
+export const LIBRARY_KINDS: string[];