@anhlp/alp-runtime 0.0.0-beta.1

package/src/board-domain.ts

@@ -0,0 +1,185 @@
+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, type Pin, type PinKind } from './board.js';
+import { plainObject, toolResult } from './tool-results.js';
+import type { RuntimeOptions } from './contracts.js';
+import type { Session } from './session-state.js';
+import type { AlpEvent } from './events.js';
+import type { MailEvent } from './mailbox.js';
+
+type BoardContext = {
+  options: RuntimeOptions;
+  sessions: Map<string, Session>;
+  boards: Map<string, Promise<Pin[]>>;
+  loadedBoards: Map<string, Pin[]>;
+  rootOf(sessionId: string): string;
+  lineage(sessionId: string): string[];
+  runLog(rootId: string, entry: Record<string, unknown>): void;
+  emit(sessionId: string, event: AlpEvent): void;
+  post(sessionId: string, event: Omit<MailEvent, 'id'>): MailEvent;
+  steerMail(sessionId: string, session: Session): Promise<void>;
+};
+
+/** Shared project boards retain their original write ordering and session ownership. */
+export function createBoardDomain({ options, sessions, boards, loadedBoards, rootOf, lineage, runLog, emit, post, steerMail }: BoardContext) {
+  const boardFile = (project: string) => path.join(options.boardDir!, `${createHash('sha256').update(project).digest('hex').slice(0, 16)}.jsonl`);
+  let boardWrites = Promise.resolve();
+
+  /** Live claims, then the most recent decisions and findings. */
+  function prune(pins: Pin[]) {
+    const notes = pins.filter(pin => pin.kind !== 'claim' && live(pin));
+    return [...pins.filter(pin => pin.kind === 'claim' && live(pin)), ...notes.slice(-BOARD_KEEP)];
+  }
+
+  /** A board from an earlier daemon keeps its decisions and findings; its claims ended with their sessions. */
+  function boardOf(project: string) {
+    let board = boards.get(project);
+    if (!board) {
+      board = (async () => {
+        if (!options.boardDir) return [];
+        const text = await readFile(boardFile(project), 'utf8').catch(() => '');
+        const pins = new Map<string, Pin>();
+        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 = new Date().toISOString();
+        for (const pin of pins.values()) if (pin.kind === 'claim' && !pin.released) pin.released = now;
+        const kept = prune([...pins.values()]);
+        // Compact the file to what is kept.
+        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: string, entry: object) {
+    if (!options.boardDir) return;
+    const line = `${JSON.stringify(entry)}\n`;
+    boardWrites = boardWrites.then(() => mkdir(options.boardDir!, { recursive: true })).then(() => appendFile(boardFile(project), line)).catch(() => {});
+  }
+
+  /** Whether two sessions are in one line of delegation, where a claim is shared. */
+  const related = (a: string, b: string) => lineage(a).includes(b) || lineage(b).includes(a);
+
+  /** Live claims of agents outside this session's line of delegation that overlap `paths`. */
+  function claimConflicts(sessionId: string, pins: Pin[], paths: string[]) {
+    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 } : {}) }));
+  }
+
+  /** The task a session works on: its own assignment's, or the nearest requester's. */
+  function taskOf(sessionId: string) {
+    for (const id of lineage(sessionId)) {
+      const parent = sessions.get(id)?.parent;
+      const taskId = parent ? sessions.get(parent)?.assignments.get(id)?.taskId : undefined;
+      if (taskId) return taskId;
+    }
+    return undefined;
+  }
+
+  /** Pins to the project board `pins` (from boardOf) and tells agents at work on the project. */
+  function addPin(sessionId: string, session: Session, pins: Pin[], fields: Pick<Pin, 'kind' | 'body' | 'paths' | 'task'>) {
+    const project = session.mapping.agent.projectRoot;
+    const pin: 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: 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 });
+    // Agents at work on the project read it in their running turn; idle ones see it on alp_board or their next assignment.
+    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: string, session: Session, args: unknown) {
+    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` });
+    }
+    // A claim reserves files to change; a read-only session changes none.
+    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: string[] | undefined;
+    if (args.paths !== undefined || args.kind === 'claim') {
+      const normalized = normalizePaths(args.paths, project, session.spec.writeRoot ? [session.spec.writeRoot] : undefined);
+      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) : undefined;
+    const pin = addPin(sessionId, session, pins, { kind: args.kind as PinKind, body: args.body, ...(paths ? { paths } : {}), ...(task ? { task } : {}) });
+    return toolResult(true, { pinned: pin.id, kind: pin.kind, ...(paths ? { paths } : {}), ...(task ? { task } : {}) });
+  }
+
+  async function boardTool(session: Session, args: unknown) {
+    if (!plainObject(args, ['kinds', 'limit']) || (args.kinds !== undefined && (!Array.isArray(args.kinds) || !args.kinds.every((kind: unknown) => PIN_KINDS.includes(kind as PinKind)))) || (args.limit !== undefined && (!Number.isSafeInteger(args.limit) || args.limit < 1))) {
+      return toolResult(false, { error: 'kinds lists claim, decision or finding; limit is a positive integer' });
+    }
+    const kinds: string[] = 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) => pin;
+    return toolResult(true, { claims: claims.map(view), notes: notes.map(view) });
+  }
+
+  async function unpinTool(sessionId: string, session: Session, args: unknown) {
+    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: Pin, reason: 'unpinned' | 'session_ended') {
+    pin.released = 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)));
+  }
+
+  /** A session's claims end with it. */
+  function releaseClaims(sessionId: string, project: string) {
+    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 };
+}

package/src/board.ts

@@ -0,0 +1,80 @@
+import path from 'node:path';
+import { realpathSync } from 'node:fs';
+
+/**
+ * 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 const PIN_KINDS = ['claim', 'decision', 'finding'] as const;
+import type { PinKind, Pin } from '@anhlp/alp-protocol/dto';
+export type { PinKind, Pin } from '@anhlp/alp-protocol/dto';
+
+
+export const PIN_BODY_CHARS = 2000;
+export const PIN_PATHS = 50;
+/** Decisions and findings kept per project; live claims are always kept. */
+export const BOARD_KEEP = 200;
+const DIGEST_CHARS = 3000;
+
+/** Resolve symlinked parents even for a file an assignment has not created yet. */
+function canonicalPath(file: string): string {
+  try { return realpathSync(file); } catch {
+    const parent = path.dirname(file);
+    return parent === file ? file : path.join(canonicalPath(parent), path.basename(file));
+  }
+}
+const containsPath = (outer: string, inner: string) => {
+  const relative = path.relative(outer, inner);
+  return !relative || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+};
+
+/** Normalized project-relative paths, or absolute paths in a declared external write root. */
+export function normalizePaths(paths: unknown, project: string, roots: string[] = [project]): string[] | string {
+  if (!Array.isArray(paths) || !paths.length || paths.length > PIN_PATHS) return `paths must list 1 to ${PIN_PATHS} files or directories`;
+  const normalized: string[] = [];
+  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)];
+}
+
+/** Two paths overlap when one is the other or contains it; '.' is the whole project. */
+const contains = (outer: string, inner: string) => path.isAbsolute(outer) === path.isAbsolute(inner) && (outer === '.' || inner === outer || inner.startsWith(outer.endsWith('/') ? outer : `${outer}/`));
+
+export function overlapping(a: string[], b: string[]) {
+  return a.filter(left => b.some(right => contains(left, right) || contains(right, left)));
+}
+
+export const live = (pin: Pin) => !pin.released;
+
+export function renderPin(pin: 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}`;
+}
+
+/** What an agent should know before it starts: live claims, then recent decisions and findings. */
+export function renderBoard(pins: Pin[], 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('- … more on alp_board');
+      break;
+    }
+    lines.push(line);
+    size += line.length;
+  }
+  return lines.join('\n');
+}

package/src/catalog.ts

@@ -0,0 +1,32 @@
+/** Models, modes and thinking options the runtime accepts; viewers render them as-is. */
+import { MODELS } from '@anhlp/alp-core/models';
+
+export const DEFAULT_MODEL = 'gpt-5.6-sol';
+export const DEFAULT_CLAUDE_MODEL = 'sonnet';
+export const DEFAULT_ANTIGRAVITY_MODEL = 'gemini-3.8-flash-high';
+// Main's and the supervisor's models and effort come from the session's team: templates/teams/<id>/team.json (ALPD §42).
+/** Oracle runs on one of these; main may consult both for two opinions. */
+export const ORACLE_MODELS = ['claude:claude-fable-5-1', 'codex:gpt-6-astra'];
+export const ORACLE_THINKING = 'high';
+export const modes = [{ id: 'read-only', label: 'Read only' }, { id: 'workspace-write', label: 'Workspace write' }, { id: 'full-access', label: 'Full access' }];
+const modeRank: Record<string, number> = { 'read-only': 0, 'workspace-write': 1, 'full-access': 2 };
+/** Whether a session in `mode` may run with `requested`; a child never exceeds its requester. */
+export const withinMode = (requested: string, mode: string) => (modeRank[requested] ?? 3) <= (modeRank[mode] ?? -1);
+export const writes = (mode: string) => mode !== 'read-only';
+const option = (id: string) => ({ id, label: id });
+const options = (ids: string[]) => ids.map(option);
+export const thinkingOptions = options(['none', 'off', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra', 'ultracode']);
+
+const model = (runtime: 'codex' | 'claude' | 'antigravity', id: string, label: string, description: string, modelThinkingOptions: Array<{ id: string; label: string }>, defaultThinkingOptionId?: string) => ({
+  id: `${runtime}:${id}`,
+  label: `${runtime === 'codex' ? 'Codex' : runtime === 'claude' ? 'Claude Code' : 'Antigravity'} · ${label}`,
+  description,
+  thinkingOptions: modelThinkingOptions,
+  ...(defaultThinkingOptionId ? { defaultThinkingOptionId } : {}),
+});
+
+export const models = MODELS.map(entry => model(entry.runtime as 'codex' | 'claude' | 'antigravity', entry.id, entry.label, entry.description, options(entry.efforts), entry.effort));
+
+export function thinkingOptionsFor(runtime: 'codex' | 'claude' | 'antigravity', nativeModel: string) {
+  return models.find(candidate => candidate.id === `${runtime}:${nativeModel}`)?.thinkingOptions ?? thinkingOptions;
+}