@anhlp/alp-runtime 0.0.0-beta.1

package/dist/board-domain.js

@@ -0,0 +1,157 @@
+// packages/runtime/src/board-domain.ts
+import { createHash, randomUUID } from "node:crypto";
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { moveFile } from "@anhlp/alp-core/atomic";
+import path from "node:path";
+import { BOARD_KEEP, live, normalizePaths, overlapping, PIN_BODY_CHARS, PIN_KINDS, renderPin } from "./board.js";
+import { plainObject, toolResult } from "./tool-results.js";
+function createBoardDomain({ options, sessions, boards, loadedBoards, rootOf, lineage, runLog, emit, post, steerMail }) {
+  const boardFile = (project) => path.join(options.boardDir, `${createHash("sha256").update(project).digest("hex").slice(0, 16)}.jsonl`);
+  let boardWrites = Promise.resolve();
+  function prune(pins) {
+    const notes = pins.filter((pin) => pin.kind !== "claim" && live(pin));
+    return [...pins.filter((pin) => pin.kind === "claim" && live(pin)), ...notes.slice(-BOARD_KEEP)];
+  }
+  function boardOf(project) {
+    let board = boards.get(project);
+    if (!board) {
+      board = (async () => {
+        if (!options.boardDir) return [];
+        const text = await readFile(boardFile(project), "utf8").catch(() => "");
+        const pins = /* @__PURE__ */ new Map();
+        for (const line of text.split("\n").filter(Boolean)) {
+          try {
+            const entry = JSON.parse(line);
+            if (entry.pin?.id) pins.set(entry.pin.id, entry.pin);
+            else if (entry.release && pins.has(entry.release)) pins.get(entry.release).released = entry.at;
+          } catch {
+          }
+        }
+        const now = (/* @__PURE__ */ new Date()).toISOString();
+        for (const pin of pins.values()) if (pin.kind === "claim" && !pin.released) pin.released = now;
+        const kept = prune([...pins.values()]);
+        boardWrites = boardWrites.then(async () => {
+          await mkdir(options.boardDir, { recursive: true });
+          const temporary = `${boardFile(project)}.${randomUUID().slice(0, 8)}.tmp`;
+          await writeFile(temporary, kept.map((pin) => JSON.stringify({ pin })).join("\n") + (kept.length ? "\n" : ""));
+          await moveFile(temporary, boardFile(project));
+        }).catch(() => {
+        });
+        loadedBoards.set(project, kept);
+        return kept;
+      })();
+      boards.set(project, board);
+    }
+    return board;
+  }
+  function saveBoard(project, entry) {
+    if (!options.boardDir) return;
+    const line = `${JSON.stringify(entry)}
+`;
+    boardWrites = boardWrites.then(() => mkdir(options.boardDir, { recursive: true })).then(() => appendFile(boardFile(project), line)).catch(() => {
+    });
+  }
+  const related = (a, b) => lineage(a).includes(b) || lineage(b).includes(a);
+  function claimConflicts(sessionId, pins, paths) {
+    return pins.filter((pin) => pin.kind === "claim" && live(pin) && pin.sessionId !== sessionId && !related(sessionId, pin.sessionId) && overlapping(paths, pin.paths ?? []).length).map((pin) => ({ pinId: pin.id, agent: pin.agent, sessionId: pin.sessionId, paths: overlapping(pin.paths ?? [], paths), body: pin.body, at: pin.at, ...pin.task ? { task: pin.task } : {} }));
+  }
+  function taskOf(sessionId) {
+    for (const id of lineage(sessionId)) {
+      const parent = sessions.get(id)?.parent;
+      const taskId = parent ? sessions.get(parent)?.assignments.get(id)?.taskId : void 0;
+      if (taskId) return taskId;
+    }
+    return void 0;
+  }
+  function addPin(sessionId, session, pins, fields) {
+    const project = session.mapping.agent.projectRoot;
+    const pin = {
+      id: `p-${randomUUID().slice(0, 8)}`,
+      project,
+      kind: fields.kind,
+      body: fields.body,
+      ...fields.paths ? { paths: fields.paths } : {},
+      ...fields.task ? { task: fields.task } : {},
+      agent: session.mapping.agent.name,
+      sessionId,
+      rootId: rootOf(sessionId),
+      at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const kept = prune([...pins, pin]);
+    pins.splice(0, pins.length, ...kept);
+    saveBoard(project, { pin });
+    runLog(pin.rootId, { event: "board.pin", pinId: pin.id, kind: pin.kind, agent: pin.agent, body: pin.body, ...pin.paths ? { paths: pin.paths } : {}, ...pin.task ? { task: pin.task } : {} });
+    emit(sessionId, { type: "pin", pin });
+    for (const [id, other] of sessions) {
+      if (id === sessionId || other.closed || !other.active || other.mapping.agent.projectRoot !== project) continue;
+      post(id, { kind: "board", from: pin.agent, assignment: pin.id, body: renderPin(pin), passive: true });
+      if (!other.pending) void steerMail(id, other);
+    }
+    return pin;
+  }
+  async function pinTool(sessionId, session, args) {
+    if (!plainObject(args, ["kind", "body", "paths"]) || !PIN_KINDS.includes(args.kind) || typeof args.body !== "string" || !args.body.trim() || args.body.length > PIN_BODY_CHARS) {
+      return toolResult(false, { error: `A pin needs kind (${PIN_KINDS.join(", ")}) and a body of at most ${PIN_BODY_CHARS} characters` });
+    }
+    if (args.kind === "claim" && session.mapping.mode === "read-only") return toolResult(false, { error: "A read-only session changes no files and cannot claim paths; pin a decision or finding instead" });
+    const project = session.mapping.agent.projectRoot;
+    let paths;
+    if (args.paths !== void 0 || args.kind === "claim") {
+      const normalized = normalizePaths(args.paths, project, session.spec.writeRoot ? [session.spec.writeRoot] : void 0);
+      if (typeof normalized === "string") return toolResult(false, { error: normalized });
+      paths = normalized;
+    }
+    const pins = await boardOf(project);
+    if (session.closed) return toolResult(false, { error: "Session closed" });
+    if (args.kind === "claim") {
+      const conflicts = claimConflicts(sessionId, pins, paths);
+      if (conflicts.length) {
+        return toolResult(false, {
+          error: "Another agent has claimed overlapping paths; do not edit them. Ask your requester, or claim other paths.",
+          conflicts
+        });
+      }
+    }
+    const task = args.kind === "claim" ? taskOf(sessionId) : void 0;
+    const pin = addPin(sessionId, session, pins, { kind: args.kind, body: args.body, ...paths ? { paths } : {}, ...task ? { task } : {} });
+    return toolResult(true, { pinned: pin.id, kind: pin.kind, ...paths ? { paths } : {}, ...task ? { task } : {} });
+  }
+  async function boardTool(session, args) {
+    if (!plainObject(args, ["kinds", "limit"]) || args.kinds !== void 0 && (!Array.isArray(args.kinds) || !args.kinds.every((kind) => PIN_KINDS.includes(kind))) || args.limit !== void 0 && (!Number.isSafeInteger(args.limit) || args.limit < 1)) {
+      return toolResult(false, { error: "kinds lists claim, decision or finding; limit is a positive integer" });
+    }
+    const kinds = args.kinds ?? [...PIN_KINDS];
+    const pins = (await boardOf(session.mapping.agent.projectRoot)).filter((pin) => live(pin) && kinds.includes(pin.kind));
+    const claims = pins.filter((pin) => pin.kind === "claim");
+    const notes = pins.filter((pin) => pin.kind !== "claim").slice(-(args.limit ?? 30));
+    const view = ({ project: _project, rootId: _root, released: _released, ...pin }) => pin;
+    return toolResult(true, { claims: claims.map(view), notes: notes.map(view) });
+  }
+  async function unpinTool(sessionId, session, args) {
+    if (!plainObject(args, ["pinId"]) || typeof args.pinId !== "string") return toolResult(false, { error: "pinId is required" });
+    const pins = await boardOf(session.mapping.agent.projectRoot);
+    const pin = pins.find((candidate) => candidate.id === args.pinId && live(candidate));
+    if (!pin) return toolResult(false, { error: "No such pin on this board" });
+    if (pin.sessionId !== sessionId) return toolResult(false, { error: `Only ${pin.agent}, who pinned it, can take it down` });
+    release(pin, "unpinned");
+    return toolResult(true, { unpinned: pin.id });
+  }
+  function release(pin, reason) {
+    pin.released = (/* @__PURE__ */ new Date()).toISOString();
+    saveBoard(pin.project, { release: pin.id, at: pin.released });
+    runLog(pin.rootId, { event: "board.unpin", pinId: pin.id, agent: pin.agent, reason });
+    if (sessions.has(pin.sessionId)) emit(pin.sessionId, { type: "unpin", pinId: pin.id, reason });
+    void boardOf(pin.project).then((pins) => pins.splice(0, pins.length, ...prune(pins)));
+  }
+  function releaseClaims(sessionId, project) {
+    const board = boards.get(project);
+    if (!board) return;
+    void board.then((pins) => {
+      for (const pin of [...pins]) if (pin.kind === "claim" && live(pin) && pin.sessionId === sessionId) release(pin, "session_ended");
+    });
+  }
+  return { boardOf, claimConflicts, taskOf, addPin, pinTool, boardTool, unpinTool, releaseClaims, flush: () => boardWrites };
+}
+export {
+  createBoardDomain
+};

package/dist/board.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The project board (plans/reference/ALPD.md §18): one group channel per project that every
+ * agent working on it shares, across trees. Agents pin claims (paths they are changing),
+ * decisions (the approach everyone follows) and findings (what others need to know), so
+ * agents working independently neither edit each other's files nor pursue different ideas.
+ * These helpers stay pure; storage and delivery live in the runtime.
+ */
+export declare const PIN_KINDS: readonly ["claim", "decision", "finding"];
+import type { Pin } from '@anhlp/alp-protocol/dto';
+export type { PinKind, Pin } from '@anhlp/alp-protocol/dto';
+export declare const PIN_BODY_CHARS = 2000;
+export declare const PIN_PATHS = 50;
+/** Decisions and findings kept per project; live claims are always kept. */
+export declare const BOARD_KEEP = 200;
+/** Normalized project-relative paths, or absolute paths in a declared external write root. */
+export declare function normalizePaths(paths: unknown, project: string, roots?: string[]): string[] | string;
+export declare function overlapping(a: string[], b: string[]): string[];
+export declare const live: (pin: Pin) => boolean;
+export declare function renderPin(pin: Pin): string;
+/** What an agent should know before it starts: live claims, then recent decisions and findings. */
+export declare function renderBoard(pins: Pin[], limit?: number): string;

package/dist/board.js

@@ -0,0 +1,69 @@
+// packages/runtime/src/board.ts
+import path from "node:path";
+import { realpathSync } from "node:fs";
+var PIN_KINDS = ["claim", "decision", "finding"];
+var PIN_BODY_CHARS = 2e3;
+var PIN_PATHS = 50;
+var BOARD_KEEP = 200;
+var DIGEST_CHARS = 3e3;
+function canonicalPath(file) {
+  try {
+    return realpathSync(file);
+  } catch {
+    const parent = path.dirname(file);
+    return parent === file ? file : path.join(canonicalPath(parent), path.basename(file));
+  }
+}
+var containsPath = (outer, inner) => {
+  const relative = path.relative(outer, inner);
+  return !relative || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+};
+function normalizePaths(paths, project, roots = [project]) {
+  if (!Array.isArray(paths) || !paths.length || paths.length > PIN_PATHS) return `paths must list 1 to ${PIN_PATHS} files or directories`;
+  const normalized = [];
+  for (const entry of paths) {
+    if (typeof entry !== "string" || !entry.trim()) return "paths must be nonempty strings";
+    const absolute = canonicalPath(path.resolve(project, entry.trim()));
+    if (!roots.some((root) => containsPath(canonicalPath(root), absolute))) return `${entry} is outside the project or declared write root`;
+    const relative = path.relative(canonicalPath(project), absolute).split(path.sep).join("/");
+    normalized.push(relative === "" ? "." : relative === ".." || relative.startsWith("../") || path.isAbsolute(relative) ? absolute.split(path.sep).join("/") : relative);
+  }
+  return [...new Set(normalized)];
+}
+var contains = (outer, inner) => path.isAbsolute(outer) === path.isAbsolute(inner) && (outer === "." || inner === outer || inner.startsWith(outer.endsWith("/") ? outer : `${outer}/`));
+function overlapping(a, b) {
+  return a.filter((left) => b.some((right) => contains(left, right) || contains(right, left)));
+}
+var live = (pin) => !pin.released;
+function renderPin(pin) {
+  const where = pin.paths?.length ? ` [${pin.paths.join(", ")}]` : "";
+  return `${pin.kind} ${pin.id} by ${pin.agent}${pin.task ? ` for task ${pin.task}` : ""}${where}: ${pin.body}`;
+}
+function renderBoard(pins, limit = DIGEST_CHARS) {
+  const claims = pins.filter((pin) => pin.kind === "claim" && live(pin));
+  const notes = pins.filter((pin) => pin.kind !== "claim" && live(pin)).reverse();
+  if (!claims.length && !notes.length) return "";
+  const lines = ["Project board (shared by every agent on this project; read more with alp_board):"];
+  let size = lines[0].length;
+  for (const pin of [...claims, ...notes]) {
+    const line = `- ${renderPin(pin)}`;
+    if (size + line.length > limit) {
+      lines.push("- \u2026 more on alp_board");
+      break;
+    }
+    lines.push(line);
+    size += line.length;
+  }
+  return lines.join("\n");
+}
+export {
+  BOARD_KEEP,
+  PIN_BODY_CHARS,
+  PIN_KINDS,
+  PIN_PATHS,
+  live,
+  normalizePaths,
+  overlapping,
+  renderBoard,
+  renderPin
+};

package/dist/catalog.d.ts

@@ -0,0 +1,31 @@
+export declare const DEFAULT_MODEL = "gpt-5.6-sol";
+export declare const DEFAULT_CLAUDE_MODEL = "sonnet";
+export declare const DEFAULT_ANTIGRAVITY_MODEL = "gemini-3.8-flash-high";
+/** Oracle runs on one of these; main may consult both for two opinions. */
+export declare const ORACLE_MODELS: string[];
+export declare const ORACLE_THINKING = "high";
+export declare const modes: {
+    id: string;
+    label: string;
+}[];
+/** Whether a session in `mode` may run with `requested`; a child never exceeds its requester. */
+export declare const withinMode: (requested: string, mode: string) => boolean;
+export declare const writes: (mode: string) => boolean;
+export declare const thinkingOptions: {
+    id: string;
+    label: string;
+}[];
+export declare const models: {
+    defaultThinkingOptionId?: string | undefined;
+    id: string;
+    label: string;
+    description: string;
+    thinkingOptions: {
+        id: string;
+        label: string;
+    }[];
+}[];
+export declare function thinkingOptionsFor(runtime: 'codex' | 'claude' | 'antigravity', nativeModel: string): {
+    id: string;
+    label: string;
+}[];

package/dist/catalog.js

@@ -0,0 +1,38 @@
+// packages/runtime/src/catalog.ts
+import { MODELS } from "@anhlp/alp-core/models";
+var DEFAULT_MODEL = "gpt-5.6-sol";
+var DEFAULT_CLAUDE_MODEL = "sonnet";
+var DEFAULT_ANTIGRAVITY_MODEL = "gemini-3.8-flash-high";
+var ORACLE_MODELS = ["claude:claude-fable-5-1", "codex:gpt-6-astra"];
+var ORACLE_THINKING = "high";
+var modes = [{ id: "read-only", label: "Read only" }, { id: "workspace-write", label: "Workspace write" }, { id: "full-access", label: "Full access" }];
+var modeRank = { "read-only": 0, "workspace-write": 1, "full-access": 2 };
+var withinMode = (requested, mode) => (modeRank[requested] ?? 3) <= (modeRank[mode] ?? -1);
+var writes = (mode) => mode !== "read-only";
+var option = (id) => ({ id, label: id });
+var options = (ids) => ids.map(option);
+var thinkingOptions = options(["none", "off", "low", "medium", "high", "xhigh", "max", "ultra", "ultracode"]);
+var model = (runtime, id, label, description, modelThinkingOptions, defaultThinkingOptionId) => ({
+  id: `${runtime}:${id}`,
+  label: `${runtime === "codex" ? "Codex" : runtime === "claude" ? "Claude Code" : "Antigravity"} \xB7 ${label}`,
+  description,
+  thinkingOptions: modelThinkingOptions,
+  ...defaultThinkingOptionId ? { defaultThinkingOptionId } : {}
+});
+var models = MODELS.map((entry) => model(entry.runtime, entry.id, entry.label, entry.description, options(entry.efforts), entry.effort));
+function thinkingOptionsFor(runtime, nativeModel) {
+  return models.find((candidate) => candidate.id === `${runtime}:${nativeModel}`)?.thinkingOptions ?? thinkingOptions;
+}
+export {
+  DEFAULT_ANTIGRAVITY_MODEL,
+  DEFAULT_CLAUDE_MODEL,
+  DEFAULT_MODEL,
+  ORACLE_MODELS,
+  ORACLE_THINKING,
+  models,
+  modes,
+  thinkingOptions,
+  thinkingOptionsFor,
+  withinMode,
+  writes
+};

package/dist/claude-transport.d.ts

@@ -0,0 +1,157 @@
+import { z } from 'zod';
+export declare const toolShapes: Record<string, Record<string, z.ZodType>>;
+type Listener = (method: string, params: any) => void;
+type RequestHandler = (method: string, params: any) => Promise<unknown>;
+/** The plugin name ALP's skills are loaded under, so Claude Code calls them alp:<name>. */
+export declare const SKILL_PLUGIN = "alp";
+/**
+ * A Claude Code plugin in `directory` holding the given skills, linked to their own
+ * directories so an edit to a skill reaches the next session (ALPD §59).
+ */
+export declare function skillPlugin(directory: string, skills: Array<{
+    name: string;
+    path: string;
+}>): string;
+type PermissionRules = {
+    allow: string[];
+    ask?: string[];
+    deny: string[];
+    beyondMode?: 'refuse' | 'ask';
+    /** The OS sandbox ALP puts Bash in, and the directory it may write besides temp files. */
+    floor?: 'read-only' | 'workspace-write';
+    floorRoot?: string;
+};
+/** Whether Claude Code can sandbox Bash here: Seatbelt on macOS, bubblewrap and socat on Linux. ALP_CLAUDE_SANDBOX=0 turns it off, =1 claims it (tests). */
+export declare function claudeSandboxAvailable(): boolean;
+/** What ALP asks the user for a permission Claude would otherwise not have. */
+export type PermissionRequest = {
+    tool: string;
+    input: Record<string, unknown>;
+    reason: 'rule' | 'mode';
+    rule?: string;
+};
+export type PermissionAnswer = {
+    allow: boolean;
+    always?: boolean;
+    message?: string;
+};
+/** Claude's permission mode for an ALP mode; full-access skips every permission check. */
+export declare const claudePermissionMode: (sandbox: string) => "default" | "acceptEdits" | "bypassPermissions";
+export declare function claudePermissions(sandbox: string, currentSandbox?: () => string, rules?: PermissionRules | null, ask?: (request: PermissionRequest) => Promise<PermissionAnswer>): {
+    canUseTool: (name: string, input: Record<string, unknown>, context?: {
+        decisionReasonType?: string;
+        suggestions?: unknown;
+    }) => Promise<{
+        behavior: string;
+        message: string;
+    } | {
+        updatedPermissions?: {
+            type: string;
+            rules: {
+                ruleContent?: string | undefined;
+                toolName: string;
+            }[];
+            behavior: string;
+            destination: string;
+        }[] | undefined;
+        behavior: string;
+        updatedInput: Record<string, unknown>;
+        message?: undefined;
+    }>;
+    sandbox?: {
+        filesystem?: {
+            denyWrite: string[];
+        } | undefined;
+        enabled: boolean;
+        autoAllowBashIfSandboxed: boolean;
+        allowUnsandboxedCommands: boolean;
+    } | undefined;
+    settings?: {
+        permissions: {
+            ask: string[];
+        };
+    } | undefined;
+    disallowedTools: string[];
+    allowedTools?: string[] | undefined;
+    tools?: string[] | undefined;
+    permissionMode: string;
+    allowDangerouslySkipPermissions: boolean;
+};
+/** Whether Claude's last rate limit report means requests are refused: rejected, with no overage to fall back on. */
+export declare const claudeLimited: (info?: {
+    status: string;
+    overageStatus?: string;
+}) => boolean;
+/** Maps Claude Agent SDK streaming sessions to the normalized runtime protocol. */
+export declare class ClaudeTransport {
+    private readonly command;
+    private readonly cwd;
+    private readonly env;
+    private listeners;
+    private failures;
+    private requestHandler?;
+    /** Whether the workspace had a .claude directory before a sandboxed session started. */
+    private claudeDirectory?;
+    private input;
+    private query?;
+    private pump?;
+    private config?;
+    private threadId;
+    private activeTurn?;
+    private closed;
+    private assistantText;
+    private toolCalls;
+    /** The last rate limit Claude reported, and whether the running turn hit one. */
+    private rateLimit?;
+    private limitedTurn;
+    /** The model's context window and the fill at which Claude compacts it, as Claude reports them (ALPD §57). */
+    private contextWindow?;
+    private compactAt?;
+    /** The compaction running now, from its start to its boundary. */
+    private compaction?;
+    /** The plugin directory that loads the agent's skills, removed on close. */
+    private skillDirectory?;
+    constructor(command: string, cwd: string, env: NodeJS.ProcessEnv);
+    orchestrationContext(): Promise<{
+        runtime: string;
+        observedAt: string;
+        catalogAvailable: boolean;
+        models: {
+            id: string;
+            label: string;
+            description: string;
+            thinking: string[] | undefined;
+        }[];
+        usage: {
+            available: boolean;
+            plan?: undefined;
+            windows?: undefined;
+        } | {
+            available: boolean;
+            plan: any;
+            windows: {
+                name: string;
+                usedPercent: any;
+                remainingPercent: number | null;
+                resetsAt: any;
+            }[];
+        };
+    }>;
+    initialize(): Promise<void>;
+    /** The plan's usage windows before a session starts, from a Claude process that sends no prompt and is closed after. */
+    private probeUsage;
+    onNotification(listener: Listener): () => boolean;
+    onFailure(listener: (error: Error) => void): () => boolean;
+    onRequest(handler: RequestHandler): void;
+    request(method: string, params: any): Promise<any>;
+    private start;
+    /** Reads the window and the compaction threshold Claude resolved for this session, before any turn. */
+    private measureContext;
+    private convertMcp;
+    private consume;
+    private handle;
+    private emit;
+    private fail;
+    close(): Promise<void>;
+}
+export {};