@anhlp/alp-runtime 0.0.0-beta.1

package/dist/resolve.js

@@ -0,0 +1,238 @@
+// packages/runtime/src/resolve.ts
+import path from "node:path";
+import { access, readFile, stat } from "node:fs/promises";
+import { resolveWorkflow } from "@anhlp/alp-core/workflow";
+import { initProject } from "@anhlp/alp-core/init";
+import { profileModel, agentProfiles, selectedProfile } from "@anhlp/alp-core/profiles";
+import { jsonObject, resolveAgent } from "@anhlp/alp-core/resolver";
+import { resolveTeam, teamOf } from "@anhlp/alp-core/teams";
+import { loadHooks } from "@anhlp/alp-core/hooks";
+import { acpModel, loadProvider } from "@anhlp/alp-core/providers";
+import { ensureLibrary } from "@anhlp/alp-core/library";
+import { compileAgent } from "@anhlp/alp-core/adapter";
+import { capMode, profileFor } from "@anhlp/alp-core/permissions";
+import { userLanguage } from "@anhlp/alp-core/user-settings";
+import { claudeSandboxAvailable } from "./claude-transport.js";
+import { DEFAULT_ANTIGRAVITY_MODEL, DEFAULT_CLAUDE_MODEL, DEFAULT_MODEL, ORACLE_MODELS, ORACLE_THINKING, models, modes, thinkingOptions, thinkingOptionsFor } from "./catalog.js";
+async function exists(target) {
+  try {
+    await access(target);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+var SKILL_DESCRIPTION_CHARS = 400;
+async function skillDescription(file) {
+  const text = await readFile(file, "utf8").catch(() => "");
+  const front = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1] ?? "";
+  const match = /^description:[ \t]*(.*(?:\r?\n[ \t]+.*)*)/m.exec(front)?.[1] ?? "";
+  const flat = match.replace(/^[>|][-+]?/, "").replace(/\s+/g, " ").trim().replace(/^(['"])(.*)\1$/, "$2");
+  return flat.length > SKILL_DESCRIPTION_CHARS ? `${flat.slice(0, SKILL_DESCRIPTION_CHARS - 1)}\u2026` : flat;
+}
+var InstructionsAdapter = class {
+  id = "native";
+  // ALP runs an agent's hooks itself, at its own events (ALPD §45).
+  capabilities() {
+    return { instructions: "emulated", skills: "emulated", hooks: "emulated", mcp: "native" };
+  }
+  async compile(agent) {
+    const listed = await Promise.all(agent.skills.map(async (skill) => {
+      const description = await skillDescription(skill.path);
+      return `- ${skill.name} (${skill.path})${description ? `: ${description}` : ""}`;
+    }));
+    const skills = listed.length ? "Your skills: methods written for kinds of work. Before you start work that a skill's description matches, read its SKILL.md and follow it; say which skill you use.\n" + listed.join("\n") : "";
+    return { adapterId: this.id, agentName: agent.name, projectRoot: agent.projectRoot, material: {
+      instructions: [agent.instructions.project, agent.instructions.agent, skills].filter(Boolean).join("\n\n"),
+      mcp: agent.mcp,
+      runtime: agent.runtime
+    } };
+  }
+};
+var LESSONS_FILE = "lessons.md";
+var LESSON_CHARS = 6e3;
+async function lessons(file) {
+  const text = (await readFile(file, "utf8").catch(() => "")).trim();
+  return text.length > LESSON_CHARS ? `\u2026
+${text.slice(-LESSON_CHARS)}` : text;
+}
+var READ_ONLY_AGENTS = ["oracle", "reviewer", "supervisor"];
+async function resolveSession(spec, options = {}) {
+  if (!path.isAbsolute(spec.cwd) || !(await stat(spec.cwd)).isDirectory()) throw new Error("Session cwd must be an existing absolute directory");
+  if (spec.workdir !== void 0 && (!path.isAbsolute(spec.workdir) || !(await stat(spec.workdir)).isDirectory())) throw new Error("Session workdir must be an existing absolute directory");
+  const starter = options.templates ? { templates: options.templates } : {};
+  if (options.initialize !== false) {
+    const settingsFile = path.join(spec.cwd, ".alp", "settings.json");
+    const scaffoldMissing = !await exists(path.join(spec.cwd, "ALP.md")) || !await exists(settingsFile);
+    if (scaffoldMissing) await initProject(spec.cwd, { ...starter, library: options.library });
+    else if (!spec.restore) {
+      const settings = await jsonObject(settingsFile, "INVALID_SETTINGS");
+      await initProject(spec.cwd, { ...starter, library: options.library, onlyManagedProfiles: true, teamIds: [teamOf(spec.workflow ?? settings.workflow?.mode ?? "custom")] });
+    }
+  }
+  if (options.library) await ensureLibrary(options.library, options.templates ? { templates: options.templates } : {});
+  const restored = spec.restore;
+  if (restored && spec.agent !== void 0 && spec.agent !== restored.agent) throw new Error("Cannot resume a thread as a different ALP agent");
+  const { team, ...workflow } = await resolveWorkflow(spec.cwd, spec.workflow, restored?.workflow, { library: options.library, templates: options.templates });
+  const agent = await resolveAgent(spec.cwd, { agent: spec.agent ?? restored?.agent, library: options.library, templates: options.templates });
+  const oracleModels = team?.oracleModels ?? ORACLE_MODELS;
+  if (agent.name === "oracle" && !restored && !oracleModels.includes(spec.model ?? "")) throw new Error(`Oracle runs on ${oracleModels.join(" or ")}; choose one`);
+  const projectSettings = await jsonObject(path.join(spec.cwd, ".alp/settings.json"), "INVALID_SETTINGS");
+  const profile = (projectSettings.team ?? projectSettings.profile)?.[workflow.mode]?.[agent.name];
+  const modelProfiles = Object.fromEntries(Object.entries((projectSettings.team ?? projectSettings.profile)?.[workflow.mode] ?? {}).map(([name, config]) => [name, agentProfiles(config, name)]));
+  const requestedModel = restored?.model ? `${restored.runtime ?? agent.runtime.provider ?? "codex"}:${restored.model}` : spec.model;
+  const profileChoice = selectedProfile(modelProfiles[agent.name] ?? [], requestedModel);
+  const projectModel = profileModel(profileChoice);
+  const compiled = await compileAgent(new InstructionsAdapter(), agent);
+  const base = team ?? await resolveTeam(void 0, "pho", { templates: options.templates });
+  const main = base.main;
+  const member = Object.hasOwn(base.members, agent.name) && (team || agent.name === main) ? base.members[agent.name] : void 0;
+  const sameModel = (id) => id === void 0 || restored?.model === void 0 || `${restored.runtime}:${restored.model}` === id || restored.model === id;
+  const teamChoice = member && !agent.projectRuntime?.model && !agent.projectRuntime?.provider && spec.model === void 0 && sameModel(member.model) ? member : void 0;
+  let runtimeKind = restored?.runtime ?? profileChoice?.provider ?? (teamChoice?.model ? void 0 : agent.runtime.provider) ?? "codex";
+  let model = restored?.model ?? spec.model ?? projectModel ?? teamChoice?.model ?? agent.runtime.model ?? (runtimeKind === "claude" ? DEFAULT_CLAUDE_MODEL : DEFAULT_MODEL);
+  if (model.startsWith("codex:")) {
+    runtimeKind = "codex";
+    model = model.slice("codex:".length);
+  }
+  if (model.startsWith("claude:")) {
+    runtimeKind = "claude";
+    model = model.slice("claude:".length);
+  }
+  if (model.startsWith("codex/")) {
+    runtimeKind = "codex";
+    model = model.slice("codex/".length);
+  }
+  if (model.startsWith("claude/")) {
+    runtimeKind = "claude";
+    model = model.slice("claude/".length);
+  }
+  if (model.startsWith("antigravity:")) {
+    runtimeKind = "antigravity";
+    model = model.slice("antigravity:".length);
+  }
+  if (model.startsWith("antigravity/")) {
+    runtimeKind = "antigravity";
+    model = model.slice("antigravity/".length);
+  }
+  if (model.startsWith("acp:")) {
+    const raw = model.slice("acp:".length);
+    if (raw.startsWith("antigravity/") || raw === "antigravity") {
+      runtimeKind = "antigravity";
+      model = raw.startsWith("antigravity/") ? raw.slice("antigravity/".length) : "";
+    } else {
+      runtimeKind = "acp";
+      model = raw;
+    }
+  }
+  if (runtimeKind === "antigravity") {
+    if (!model.trim() || model === DEFAULT_MODEL) model = DEFAULT_ANTIGRAVITY_MODEL;
+  }
+  if (!["codex", "claude", "acp", "antigravity"].includes(runtimeKind)) {
+    model = model === DEFAULT_MODEL && agent.runtime.model !== DEFAULT_MODEL ? runtimeKind : `${runtimeKind}/${model}`;
+    runtimeKind = "acp";
+  }
+  if (restored?.runtime && runtimeKind !== restored.runtime) throw new Error("Cannot resume a thread with a different runtime provider");
+  let acp;
+  if (runtimeKind === "acp") {
+    const { provider: id, model: native } = acpModel(model);
+    acp = await loadProvider(options.library, id);
+    if (!acp) throw new Error(`No ACP provider '${id}': add one to your library with alp provider add ${id}, or name codex or claude`);
+    if (acp.enabled === false) throw new Error(`ACP provider '${id}' is turned off; turn it on in the web app's Providers settings or in providers/${id}.json`);
+    const listed = [...acp.models ?? [], ...acp.additionalModels ?? []];
+    if (native && acp.models && !listed.some((candidate) => candidate.id === native)) throw new Error(`ACP provider '${id}' lists no model '${native}'`);
+    if (spec.copy) throw new Error("A review copy cannot run on an ACP agent: ALP cannot keep its commands inside the copy");
+  }
+  let antigravity;
+  if (runtimeKind === "antigravity") {
+    const provider = await loadProvider(options.library, "antigravity");
+    if (provider && provider.kind === "antigravity") {
+      antigravity = provider;
+      if (antigravity.enabled === false) throw new Error("Antigravity provider 'antigravity' is turned off; turn it on in the web app's Providers settings or in providers/antigravity.json");
+    }
+  }
+  const permissions = await profileFor(agent.projectRoot, options.library, agent.name);
+  const requested = spec.mode ?? agent.mode ?? (agent.name === main ? "full-access" : "read-only");
+  const mode = permissions ? capMode(requested, permissions.base) : requested;
+  if (runtimeKind === "antigravity") {
+    if (mode !== "full-access" && !(mode === "read-only" && antigravity?.readOnlyMode === "instructions")) throw new Error('Antigravity currently supports only full-access; read-only requires explicit readOnlyMode: "instructions" and is not sandboxed');
+    if (spec.copy || permissions?.workdir === "copy") throw new Error("Antigravity cannot enforce isolation for a review copy");
+    if (permissions && (permissions.deny.length || permissions.ask.length || permissions.allow.length || permissions.beyondMode === "ask")) {
+      throw new Error("Antigravity cannot enforce custom permission rules");
+    }
+  }
+  const availableThinking = ["acp", "antigravity"].includes(runtimeKind) ? [] : thinkingOptionsFor(runtimeKind, model);
+  const preferred = ["acp", "antigravity"].includes(runtimeKind) ? "none" : spec.thinking ?? profileChoice?.effort ?? agent.projectRuntime?.reasoning ?? (agent.name === "oracle" ? team?.oracleThinking?.[`${runtimeKind}:${model}`] ?? team?.oracleThinking?.[runtimeKind] : void 0) ?? teamChoice?.thinking ?? agent.runtime.reasoning ?? (agent.name === "oracle" ? ORACLE_THINKING : availableThinking.length ? "medium" : "none");
+  const thinking = spec.thinking === void 0 && availableThinking.length && !availableThinking.some((candidate) => candidate.id === preferred) ? models.find((candidate) => candidate.id === `${runtimeKind}:${model}`)?.defaultThinkingOptionId ?? availableThinking[0].id : preferred;
+  if (!model.trim()) throw new Error("Model must be nonempty");
+  if (!modes.some((m) => m.id === mode)) throw new Error(`Unsupported mode '${mode}'`);
+  if (spec.copy && runtimeKind === "claude" && !claudeSandboxAvailable()) throw new Error("A review copy on Claude needs its Bash sandbox (Seatbelt on macOS; bubblewrap and socat on Linux)");
+  if (!thinkingOptions.some((m) => m.id === thinking)) throw new Error(`Unsupported thinking option '${thinking}'`);
+  if (availableThinking.length && !availableThinking.some((candidate) => candidate.id === thinking)) throw new Error(`Thinking option '${thinking}' is unsupported by ${runtimeKind}:${model}`);
+  const mcp = {};
+  for (const [name, value] of Object.entries(compiled.material.mcp.mcpServers)) {
+    const { headers, ...rest } = value;
+    Object.defineProperty(mcp, name, { value: { ...rest, ...headers ? { http_headers: headers } : {} }, enumerable: true, writable: true });
+  }
+  for (const [name, value] of Object.entries(spec.mcpServers ?? {})) {
+    if (Object.hasOwn(mcp, name)) throw new Error(`MCP server name collision: '${name}'`);
+    if (value.type === "sse") throw new Error(`SSE MCP server '${name}' is unsupported by this runtime`);
+    const server = value.type === "stdio" ? { command: value.command, args: value.args ?? [], env: value.env ?? {} } : { url: value.url, http_headers: value.headers ?? {} };
+    Object.defineProperty(mcp, name, { value: server, enumerable: true, writable: true });
+  }
+  let learned = "";
+  const supervisorAgent = team?.supervisor ? team.supervisor.agent : void 0;
+  if ([main, supervisorAgent].includes(agent.name) && workflow.supervisor) {
+    const user = options.library ? await lessons(path.join(options.library, LESSONS_FILE)) : "";
+    const project = await lessons(path.join(agent.projectRoot, ".alp", LESSONS_FILE));
+    if (user || project) {
+      learned = "Lessons main recorded after earlier supervisor reviews. Follow them; they are the user's process, not a task." + (user ? `
+
+For every project:
+${user}` : "") + (project ? `
+
+For this project:
+${project}` : "");
+    }
+  }
+  const houseRules = base.houseRules;
+  const hooks = await loadHooks(agent);
+  return {
+    agent,
+    workflow,
+    team,
+    oracleModels,
+    modelProfiles,
+    houseRules,
+    hooks,
+    runtimeKind,
+    model,
+    ...acp ? { acp } : {},
+    ...antigravity ? { antigravity } : {},
+    mode,
+    permissions,
+    thinking,
+    threadId: restored?.threadId,
+    workdir: spec.workdir ?? agent.projectRoot,
+    copy: Boolean(spec.copy && spec.workdir),
+    ...spec.copy && spec.copyOf ? { copyOf: spec.copyOf } : {},
+    instructions: [compiled.material.instructions, learned, spec.systemPrompt].filter(Boolean).join("\n\n"),
+    mcp,
+    env: { ...spec.env },
+    persist: spec.persist ?? false,
+    keepThread: spec.keepThread ?? false,
+    // ALPD §57: the window the agent works in before its runtime compacts; absent, the model's.
+    ...agent.context ? { context: agent.context } : {},
+    autocompact: typeof profile?.autocompact === "number" ? profile.autocompact : typeof agent.autocompact === "number" ? agent.autocompact : void 0,
+    // ALPD §54: the language everything the user reads is written in.
+    language: options.language ?? await userLanguage(options.library)
+  };
+}
+export {
+  InstructionsAdapter,
+  LESSONS_FILE,
+  READ_ONLY_AGENTS,
+  resolveSession,
+  skillDescription
+};

package/dist/runtime-context.d.ts

@@ -0,0 +1,43 @@
+export declare const COMPACT_SHARE = 0.9;
+/** Bounded optional reads. Never expose account identifiers or credentials. */
+export declare function optionalRead<T>(read: () => Promise<T>, timeout?: number): Promise<T | undefined>;
+export declare function codexUsage(result: any): {
+    available: boolean;
+    ordinaryUsageAllowed?: undefined;
+    limits?: undefined;
+} | {
+    available: boolean;
+    ordinaryUsageAllowed: any;
+    limits: {
+        name: any;
+        model: any;
+        plan: any;
+        windows: {
+            usedPercent: any;
+            remainingPercent: number | null;
+            windowMinutes: any;
+            resetsAt: any;
+        }[];
+        spendControlReached: any;
+    }[];
+};
+export declare function claudeUsage(result: any): {
+    available: boolean;
+    plan?: undefined;
+    windows?: undefined;
+} | {
+    available: boolean;
+    plan: any;
+    windows: {
+        name: string;
+        usedPercent: any;
+        remainingPercent: number | null;
+        resetsAt: any;
+    }[];
+};
+/**
+ * Whether a runtime's usage report (codexUsage or claudeUsage) lets it work again (ALPD §58):
+ * true when every window has room, false when one is used up or spending is capped, and
+ * undefined when the report says nothing either way.
+ */
+export declare function usageAllows(usage: any): boolean | undefined;

package/dist/runtime-context.js

@@ -0,0 +1,61 @@
+// packages/runtime/src/runtime-context.ts
+var COMPACT_SHARE = 0.9;
+async function optionalRead(read, timeout = 1500) {
+  let timer;
+  try {
+    return await Promise.race([Promise.resolve().then(read).catch(() => void 0), new Promise((resolve) => {
+      timer = setTimeout(() => resolve(void 0), timeout);
+    })]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function codexUsage(result) {
+  if (!result?.rateLimits) return { available: false };
+  const clean = (limit) => ({
+    name: limit?.limitName ?? null,
+    model: limit?.normalModelSlug ?? null,
+    plan: limit?.planType ?? null,
+    windows: [limit?.primary, limit?.secondary].filter(Boolean).map((window) => ({
+      usedPercent: window.usedPercent,
+      remainingPercent: typeof window.usedPercent === "number" ? Math.max(0, 100 - window.usedPercent) : null,
+      windowMinutes: window.windowDurationMins,
+      resetsAt: window.resetsAt
+    })),
+    spendControlReached: limit?.spendControlReached ?? null
+  });
+  return {
+    available: true,
+    ordinaryUsageAllowed: result.ordinaryUsageAllowed ?? null,
+    limits: Object.values(result.rateLimitsByLimitId ?? { default: result.rateLimits }).map(clean)
+  };
+}
+function claudeUsage(result) {
+  if (!result) return { available: false };
+  return {
+    available: result.rate_limits_available === true,
+    plan: result.subscription_type ?? null,
+    windows: Object.entries(result.rate_limits ?? {}).flatMap(([name, window]) => window && "utilization" in window ? [{
+      name,
+      usedPercent: window.utilization,
+      remainingPercent: typeof window.utilization === "number" ? Math.max(0, 100 - window.utilization) : null,
+      resetsAt: window.resets_at
+    }] : [])
+  };
+}
+function usageAllows(usage) {
+  if (!usage?.available) return void 0;
+  const limits = Array.isArray(usage.limits) ? usage.limits : [];
+  if (limits.some((limit) => limit?.spendControlReached === true)) return false;
+  const windows = limits.length ? limits.flatMap((limit) => limit?.windows ?? []) : usage.windows ?? [];
+  const known = windows.filter((window) => typeof window?.usedPercent === "number");
+  if (!known.length) return void 0;
+  return known.every((window) => window.usedPercent < 100);
+}
+export {
+  COMPACT_SHARE,
+  claudeUsage,
+  codexUsage,
+  optionalRead,
+  usageAllows
+};

package/dist/runtime.d.ts

@@ -0,0 +1,4 @@
+import { type RuntimeOptions, type AlpRuntime } from './contracts.js';
+export type { RuntimeTransport, RuntimeOptions, OpenOptions, PromptContent, PromptInput, AlpRuntime, SessionPreview, RecoveryOutcome, Pause, PauseState, RecallAnswer } from './contracts.js';
+export { DEFAULT_TEAM } from './contracts.js';
+export declare function createAlpRuntime(options?: RuntimeOptions): AlpRuntime;