@anhlp/alp-runtime 0.0.0-beta.1

package/dist/contracts.d.ts

@@ -0,0 +1,163 @@
+import type { ProviderFactories, ProviderRegistry } from './providers.js';
+import type { RuntimeKind, SessionSpec } from './resolve.js';
+import type { Envelope, SessionSnapshot, TreeStatus, UserQuestion } from './events.js';
+import type { Pin } from './board.js';
+import type { LiveEntry } from './live.js';
+import type { ProviderUsage } from './usage.js';
+import type { AcpProvider } from './acp-transport.js';
+import type { AntigravityProvider } from './antigravity-transport.js';
+import type { GitHubRunner } from './github.js';
+export type RuntimeTransport = {
+    request(method: string, params: any): Promise<any>;
+    initialize(): Promise<void>;
+    orchestrationContext?: () => Promise<unknown>;
+    onNotification(listener: (method: string, params: any) => void): void;
+    onFailure(listener: (error: unknown) => void): void;
+    close(): Promise<void>;
+    onRequest?: (listener: (method: string, params: any) => Promise<unknown>) => void;
+};
+export type RuntimeOptions = {
+    /** Native adapter overrides, isolated to this runtime; the legacy transport hook takes precedence. */
+    providers?: ProviderFactories;
+    /** An explicit registry, including custom adapter factories registered by the host. */
+    providerRegistry?: ProviderRegistry;
+    codexCommand?: string;
+    claudeCommand?: string;
+    antigravityCommand?: string;
+    environment?: NodeJS.ProcessEnv;
+    /**
+     * Optional transport factory for tests/custom runtimes.
+     * When omitted, ALP creates CodexTransport, ClaudeTransport, or AntigravityTransport itself.
+     */
+    transport?: (cwd: string, env: NodeJS.ProcessEnv, runtime?: RuntimeKind, 
+    /** The ACP provider, when runtime is acp. */
+    acp?: AcpProvider, 
+    /** The Antigravity provider, when runtime is antigravity. */
+    antigravity?: AntigravityProvider) => RuntimeTransport;
+    /** An assignment with no activity this long is reported stalled; twice this long, it fails. */
+    silentForMs?: number;
+    /** How often main gets a check-in on its running assignments. Default 10 minutes; 0 turns it off. */
+    checkInMs?: number;
+    /** How often the watchdog looks at running assignments; derived from silentForMs and checkInMs when omitted. */
+    watchMs?: number;
+    /** How long alp_ask waits for the requester before returning unanswered. */
+    askTimeoutMs?: number;
+    /** How long alp_ask waits for the user before returning unanswered. Default 30 minutes. */
+    userAskTimeoutMs?: number;
+    /** Directory for per-root-session assignment logs (JSONL). Omitted disables logging. */
+    runLogDir?: string;
+    /** Starter files for projects without ALP; omitted reads the repository templates. */
+    templates?: Record<string, string>;
+    /** Where isolated assignments get their git worktrees. Default: a directory in the temp directory. */
+    worktreeDir?: string;
+    /** Where assignments whose profile has workdir copy get their disposable copies. Default: a directory in the temp directory. */
+    copyDir?: string;
+    /** Where project boards are kept (JSONL per project). Omitted keeps them in memory only. */
+    boardDir?: string;
+    /** The user's skill library and lessons (ALP_HOME). Omitted: only skills inside the project, and project lessons. */
+    libraryDir?: string;
+    /** The language the user reads; omitted, their settings.json's language, else Vietnamese (ALPD §54). */
+    language?: string;
+    /** Where finished assignments' native threads are recorded for alp_recall. Omitted keeps the record in memory. */
+    recallFile?: string;
+    /** Where pauses are kept across restarts. Omitted keeps them in memory. */
+    pauseFile?: string;
+    /**
+     * Resume a runtime a usage limit paused as soon as the runtime says the limit lifted
+     * (ALPD §58). Default true; false tells the user instead, who resumes it.
+     */
+    autoResume?: boolean;
+    /** How often alpd asks a runtime a usage limit paused whether the limit lifted. Default LIMIT_CHECK_MS. */
+    limitCheckMs?: number;
+    /** Where running assignments are kept, so the next alpd continues them (ALPD §31). Omitted keeps them in memory. */
+    liveFile?: string;
+    /** False parks assignments an earlier alpd left running until the user runs alp resume. Default true: they continue. */
+    recoveryResume?: boolean;
+    /** How the previous alpd ended, for what recovered sessions are told. */
+    previousExit?: {
+        kind: 'clean' | 'crash';
+        at?: string;
+    };
+    /** False starts no supervisors, for hosts and tests that do not want them. Default true. */
+    supervisor?: boolean;
+    /** Runs the GitHub CLI for alp_issue. Default: `gh` (or ALP_GH_BIN) on PATH. */
+    github?: GitHubRunner;
+};
+import type { OpenOptions, PromptInput } from '@anhlp/alp-protocol/session';
+export type { OpenOptions, PromptContent, PromptInput } from '@anhlp/alp-protocol/session';
+export type AlpRuntime = {
+    onEvent(listener: (envelope: Envelope) => void): () => void;
+    /** Opens a root session under a client-chosen id. */
+    open(sessionId: string, spec: SessionSpec, options?: OpenOptions): Promise<SessionSnapshot>;
+    /** What a new root would run as, before it opens, and the teams it may choose (ALPD §60). */
+    preview(spec: SessionSpec): Promise<SessionPreview>;
+    /** Failures are reported as prompt.failed, once per clientMessageId. */
+    prompt(sessionId: string, input: PromptInput): Promise<void>;
+    /** Cancels the running turn and closes the whole subtree. */
+    interrupt(sessionId: string): Promise<void>;
+    /** Changes permission mode while idle; undefined keeps the current mode. */
+    configure(sessionId: string, changes: {
+        mode?: string;
+    }): Promise<SessionSnapshot>;
+    close(sessionId: string): Promise<void>;
+    snapshot(sessionId: string): SessionSnapshot | undefined;
+    /** Live sessions, roots before their children. */
+    list(): SessionSnapshot[];
+    /** The live tree containing a session: sessions, assignments, questions, worktrees and leases. */
+    status(sessionId: string): TreeStatus | undefined;
+    /** Questions agents asked the user that wait for an answer. */
+    questions(): UserQuestion[];
+    /** Answers or dismisses a question to the user. */
+    answer(questionId: string, reply: {
+        text?: string;
+        dismiss?: boolean;
+        reason?: string;
+    }): void;
+    /** Mails a note from the user to any live session, such as an assignment the user wants to redirect. */
+    message(sessionId: string, text: string): void;
+    /** The project board: live claims, then decisions and findings, oldest first. */
+    board(projectRoot: string): Promise<Pin[]>;
+    /** Holds delegation and wakes on one runtime, or all; now also parks running assignments there. */
+    pause(input?: {
+        runtime?: RuntimeKind;
+        now?: boolean;
+        reason?: string;
+    }): PauseState;
+    /** Lifts a pause and continues the assignments it parked. Without a runtime, lifts every pause. */
+    resume(input?: {
+        runtime?: RuntimeKind;
+    }): PauseState;
+    /** Current pauses and parked assignments. */
+    pauses(): PauseState;
+    /** Read-only, cached account usage for the web and desktop viewers. */
+    usage(refresh?: boolean): Promise<{
+        providers: Array<ProviderUsage & {
+            pause: Pause | null;
+            parked: number;
+        }>;
+    }>;
+    /** The user asks a finished assignment, or the last one on a task of the project, about its work. */
+    recall(target: {
+        assignmentId?: string;
+        taskId?: string;
+        projectRoot?: string;
+    }, question: string): Promise<RecallAnswer>;
+    /** Assignments an earlier alpd left running, which recover() can continue once their root is open again. */
+    recoverable(): LiveEntry[];
+    /** Continues the assignments an earlier alpd left running in an open root's tree; with continueRoot, the root's own turn too. */
+    recover(rootId: string, options?: {
+        continueRoot?: boolean;
+    }): Promise<RecoveryOutcome[]>;
+    /** Gives up the assignments of a tree whose root cannot be opened again: their tasks go back to open. */
+    abandon(rootId: string, reason: string): Promise<RecoveryOutcome[]>;
+    /** Closes everything; assignments still running stay in the live file, so the next alpd continues them. */
+    shutdown(): Promise<void>;
+};
+import type { SessionPreview } from '@anhlp/alp-protocol/session';
+export type { SessionPreview } from '@anhlp/alp-protocol/session';
+/** The team a viewer starts a root in when neither it nor the project's settings choose one, as Paseo does. */
+export declare const DEFAULT_TEAM = "pho";
+import type { RecoveryOutcome, Pause, PauseState } from '@anhlp/alp-protocol/session';
+export type { RecoveryOutcome, Pause, PauseState } from '@anhlp/alp-protocol/session';
+import type { RecallAnswer } from '@anhlp/alp-protocol/session';
+export type { RecallAnswer } from '@anhlp/alp-protocol/session';

package/dist/contracts.js

@@ -0,0 +1,5 @@
+// packages/runtime/src/contracts.ts
+var DEFAULT_TEAM = "pho";
+export {
+  DEFAULT_TEAM
+};

package/dist/events.d.ts

@@ -0,0 +1 @@
+export type * from '@anhlp/alp-protocol/events';

package/dist/github.d.ts

@@ -0,0 +1,10 @@
+/** Where agents send feedback about ALP itself: its process, tools and agent instructions. */
+export declare const ALP_REPO = "phucanh08/alp";
+/** Runs the GitHub CLI with optional standard input and returns its standard output. Tests replace it. */
+export type GitHubRunner = (args: string[], options: {
+    cwd: string;
+    input?: string;
+}) => Promise<string>;
+export declare const gh: GitHubRunner;
+/** The owner/name of the GitHub repository a project's origin remote points to. */
+export declare function projectRepo(projectRoot: string): Promise<string>;

package/dist/github.js

@@ -0,0 +1,39 @@
+// packages/runtime/src/github.ts
+import { spawn } from "node:child_process";
+import { gitEnvironment } from "./workspace.js";
+var ALP_REPO = "phucanh08/alp";
+function run(command, args, { cwd, input }) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, windowsHide: true, stdio: ["pipe", "pipe", "pipe"], env: gitEnvironment() });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.stdin.on("error", () => {
+    });
+    child.on("error", (error) => reject(error.code === "ENOENT" ? new Error(`${command} is not installed or not on PATH`) : error));
+    child.on("close", (code) => code === 0 ? resolve(stdout) : reject(new Error((stderr || stdout).trim() || `${command} exited with ${code}`)));
+    child.stdin.end(input ?? "");
+  });
+}
+var gh = (args, options) => run(process.env.ALP_GH_BIN ?? "gh", args, options);
+async function projectRepo(projectRoot) {
+  let url;
+  try {
+    url = (await run("git", ["remote", "get-url", "origin"], { cwd: projectRoot })).trim();
+  } catch {
+    throw new Error('This project has no git remote named origin; use target "alp" for feedback about ALP, or tell the user');
+  }
+  const match = /github\.com[:/]([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/.exec(url);
+  if (!match) throw new Error(`The origin remote is not on GitHub (${url}); issues are filed with the GitHub CLI only`);
+  return `${match[1]}/${match[2]}`;
+}
+export {
+  ALP_REPO,
+  gh,
+  projectRepo
+};

package/dist/handoff.d.ts

@@ -0,0 +1,36 @@
+export declare const HANDOFF_OUTCOMES: readonly ["complete", "partial", "blocked", "reconsider"];
+export declare const HANDOFF_LISTS: readonly ["candidate", "scope", "verification", "risks", "discovered"];
+/**
+ * A review's verdict (ALPD §38): each criterion judged with its evidence, findings
+ * by severity, and one result that follows from them, so requesters, tasks and
+ * later a review quorum read every review the same way.
+ */
+export declare const VERDICT_RESULTS: readonly ["pass", "pass_with_findings", "fail", "blocked"];
+export declare const CRITERION_RESULTS: readonly ["pass", "fail", "not_checked"];
+export declare const SEVERITIES: readonly ["critical", "high", "medium", "low"];
+export type Verdict = {
+    result: typeof VERDICT_RESULTS[number];
+    criteria: Array<{
+        criterion: string;
+        result: typeof CRITERION_RESULTS[number];
+        evidence: string;
+    }>;
+    findings?: Array<{
+        severity: typeof SEVERITIES[number];
+        where: string;
+        problem: string;
+        fix?: string;
+    }>;
+};
+export type Handoff = {
+    outcome: typeof HANDOFF_OUTCOMES[number];
+    summary: string;
+    ownership?: string;
+    verdict?: Verdict;
+} & Partial<Record<typeof HANDOFF_LISTS[number], string[]>>;
+/** Returns the normalized handoff, or an error message for the child. */
+/** Returns the verdict, or what is wrong with it; its result must follow from its criteria and findings. */
+export declare function parseVerdict(value: any): Verdict | string;
+/** A verdict in one line: its result and the criteria counts. */
+export declare function verdictLine(verdict: Verdict): string;
+export declare function parseHandoff(args: any): Handoff | string;

package/dist/handoff.js

@@ -0,0 +1,73 @@
+// packages/runtime/src/handoff.ts
+var HANDOFF_OUTCOMES = ["complete", "partial", "blocked", "reconsider"];
+var HANDOFF_LISTS = ["candidate", "scope", "verification", "risks", "discovered"];
+var VERDICT_RESULTS = ["pass", "pass_with_findings", "fail", "blocked"];
+var CRITERION_RESULTS = ["pass", "fail", "not_checked"];
+var SEVERITIES = ["critical", "high", "medium", "low"];
+function parseVerdict(value) {
+  const text = (item) => typeof item === "string" && !!item.trim();
+  const only = (item, keys) => !!item && typeof item === "object" && !Array.isArray(item) && Object.keys(item).every((key) => keys.includes(key));
+  if (!only(value, ["result", "criteria", "findings"])) return "verdict must be an object with result, criteria and findings";
+  if (!VERDICT_RESULTS.includes(value.result)) return `verdict.result must be one of ${VERDICT_RESULTS.join(", ")}`;
+  if (!Array.isArray(value.criteria) || !value.criteria.length || value.criteria.length > 50) return "verdict.criteria must list 1 to 50 criteria";
+  for (const item of value.criteria) {
+    if (!only(item, ["criterion", "result", "evidence"]) || !text(item.criterion) || !text(item.evidence) || !CRITERION_RESULTS.includes(item.result)) {
+      return `each verdict criterion needs criterion, result (${CRITERION_RESULTS.join(", ")}) and evidence`;
+    }
+  }
+  const findings = value.findings ?? [];
+  if (!Array.isArray(findings) || findings.length > 100) return "verdict.findings must be a list of at most 100 findings";
+  for (const item of findings) {
+    if (!only(item, ["severity", "where", "problem", "fix"]) || !SEVERITIES.includes(item.severity) || !text(item.where) || !text(item.problem) || item.fix !== void 0 && !text(item.fix)) {
+      return `each verdict finding needs severity (${SEVERITIES.join(", ")}), where and problem, and optionally fix`;
+    }
+  }
+  const failed = value.criteria.filter((item) => item.result === "fail").length;
+  const serious = findings.filter((item) => item.severity === "critical" || item.severity === "high").length;
+  if (value.result === "fail" && !failed && !serious) return "verdict fail needs a failed criterion or a critical or high finding";
+  if ((value.result === "pass" || value.result === "pass_with_findings") && (failed || serious)) {
+    return `verdict ${value.result} cannot have ${failed ? "a failed criterion" : "a critical or high finding"}; the result is fail`;
+  }
+  if (value.result === "pass" && findings.length) return "verdict pass cannot have findings; use pass_with_findings";
+  if (value.result === "pass_with_findings" && !findings.length) return "verdict pass_with_findings needs findings";
+  return { result: value.result, criteria: value.criteria, ...findings.length ? { findings } : {} };
+}
+function verdictLine(verdict) {
+  const count = (result) => verdict.criteria.filter((item) => item.result === result).length;
+  const parts = [`${count("pass")} passed`, count("fail") ? `${count("fail")} failed` : "", count("not_checked") ? `${count("not_checked")} not checked` : "", verdict.findings?.length ? `${verdict.findings.length} findings` : ""];
+  return `verdict ${verdict.result.toUpperCase()} (${parts.filter(Boolean).join(", ")})`;
+}
+function parseHandoff(args) {
+  if (!args || typeof args !== "object" || Array.isArray(args)) return "Handoff must be an object";
+  const allowed = ["outcome", "summary", "ownership", "verdict", ...HANDOFF_LISTS];
+  if (Object.keys(args).some((key) => !allowed.includes(key))) return "Unknown handoff field";
+  if (!HANDOFF_OUTCOMES.includes(args.outcome)) return `outcome must be one of ${HANDOFF_OUTCOMES.join(", ")}`;
+  if (typeof args.summary !== "string" || !args.summary.trim()) return "summary is required";
+  if (args.ownership !== void 0 && typeof args.ownership !== "string") return "ownership must be a string";
+  const handoff = { outcome: args.outcome, summary: args.summary };
+  for (const key of HANDOFF_LISTS) {
+    if (args[key] === void 0) continue;
+    if (!Array.isArray(args[key]) || args[key].length > 100 || !args[key].every((item) => typeof item === "string" && item.trim())) {
+      return `${key} must be a list of at most 100 nonempty strings`;
+    }
+    handoff[key] = args[key];
+  }
+  if (args.ownership?.trim()) handoff.ownership = args.ownership;
+  if (args.verdict !== void 0) {
+    const verdict = parseVerdict(args.verdict);
+    if (typeof verdict === "string") return verdict;
+    handoff.verdict = verdict;
+  }
+  if (JSON.stringify(handoff).length > 32e3) return "Handoff exceeds 32000 characters; summarize and point to files instead";
+  return handoff;
+}
+export {
+  CRITERION_RESULTS,
+  HANDOFF_LISTS,
+  HANDOFF_OUTCOMES,
+  SEVERITIES,
+  VERDICT_RESULTS,
+  parseHandoff,
+  parseVerdict,
+  verdictLine
+};

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+export { createAlpRuntime, DEFAULT_TEAM } from './runtime.js';
+export type { AlpRuntime, RuntimeOptions, OpenOptions, RuntimeTransport, PromptInput, PromptContent, SessionPreview } from './runtime.js';
+export type { AlpEvent, AlpError, Envelope, SessionSnapshot, TimelineItem, TurnOrigin, AssignmentSnapshot, UserQuestion, TreeStatus, SessionState } from './events.js';
+export { resolveSession, InstructionsAdapter, skillDescription } from './resolve.js';
+export type { SessionSpec, HostMcpServer, ResolvedSession, RuntimeKind } from './resolve.js';
+export { DEFAULT_MODEL, DEFAULT_CLAUDE_MODEL, models, modes, thinkingOptions, thinkingOptionsFor } from './catalog.js';
+export { CodexTransport } from './transport.js';
+export { usageAllows } from './runtime-context.js';
+export { AcpTransport, acpDecision, acpEnv, acpPermission } from './acp-transport.js';
+export type { AcpProvider } from './acp-transport.js';
+export { AntigravityTransport } from './antigravity-transport.js';
+export type { AntigravityProvider } from './antigravity-transport.js';
+export { ClaudeTransport, claudePermissions, claudeSandboxAvailable, skillPlugin, SKILL_PLUGIN, toolShapes as claudeToolShapes } from './claude-transport.js';
+export { MAIL_BATCH_CHARS, MAIL_BODY_CHARS, publicEvent, renderMail, takeBatch, USER } from './mailbox.js';
+export type { MailEvent, MailKind } from './mailbox.js';
+export { createCopy, gitEnvironment, reclaimCopies, reclaimWorktrees, removeCopy } from './workspace.js';
+export { OWN_START, processStartedAt, sameProcessAlive } from './process-info.js';
+export type { Worktree, WorktreeChange } from './workspace.js';
+export { PIN_KINDS, renderBoard, renderPin } from './board.js';
+export { CHOICES, isVietnamese, languageInstruction, words } from './language.js';
+export type { Words } from './language.js';
+export type { Pin, PinKind } from './board.js';
+export { ProviderRegistry, createProviderRegistry } from './providers.js';
+export type { ProviderContext, ProviderFactory, ProviderFactories } from './providers.js';

package/dist/index.js

@@ -0,0 +1,64 @@
+// packages/runtime/src/index.ts
+import { createAlpRuntime, DEFAULT_TEAM } from "./runtime.js";
+import { resolveSession, InstructionsAdapter, skillDescription } from "./resolve.js";
+import { DEFAULT_MODEL, DEFAULT_CLAUDE_MODEL, models, modes, thinkingOptions, thinkingOptionsFor } from "./catalog.js";
+import { CodexTransport } from "./transport.js";
+import { usageAllows } from "./runtime-context.js";
+import { AcpTransport, acpDecision, acpEnv, acpPermission } from "./acp-transport.js";
+import { AntigravityTransport } from "./antigravity-transport.js";
+import { ClaudeTransport, claudePermissions, claudeSandboxAvailable, skillPlugin, SKILL_PLUGIN, toolShapes } from "./claude-transport.js";
+import { MAIL_BATCH_CHARS, MAIL_BODY_CHARS, publicEvent, renderMail, takeBatch, USER } from "./mailbox.js";
+import { createCopy, gitEnvironment, reclaimCopies, reclaimWorktrees, removeCopy } from "./workspace.js";
+import { OWN_START, processStartedAt, sameProcessAlive } from "./process-info.js";
+import { PIN_KINDS, renderBoard, renderPin } from "./board.js";
+import { CHOICES, isVietnamese, languageInstruction, words } from "./language.js";
+import { ProviderRegistry, createProviderRegistry } from "./providers.js";
+export {
+  AcpTransport,
+  AntigravityTransport,
+  CHOICES,
+  ClaudeTransport,
+  CodexTransport,
+  DEFAULT_CLAUDE_MODEL,
+  DEFAULT_MODEL,
+  DEFAULT_TEAM,
+  InstructionsAdapter,
+  MAIL_BATCH_CHARS,
+  MAIL_BODY_CHARS,
+  OWN_START,
+  PIN_KINDS,
+  ProviderRegistry,
+  SKILL_PLUGIN,
+  USER,
+  acpDecision,
+  acpEnv,
+  acpPermission,
+  claudePermissions,
+  claudeSandboxAvailable,
+  toolShapes as claudeToolShapes,
+  createAlpRuntime,
+  createCopy,
+  createProviderRegistry,
+  gitEnvironment,
+  isVietnamese,
+  languageInstruction,
+  models,
+  modes,
+  processStartedAt,
+  publicEvent,
+  reclaimCopies,
+  reclaimWorktrees,
+  removeCopy,
+  renderBoard,
+  renderMail,
+  renderPin,
+  resolveSession,
+  sameProcessAlive,
+  skillDescription,
+  skillPlugin,
+  takeBatch,
+  thinkingOptions,
+  thinkingOptionsFor,
+  usageAllows,
+  words
+};

package/dist/language.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What ALP itself writes for the user, in the user's language (ALPD §54): approvals,
+ * permission and trust questions, and notices. Vietnamese and English are written
+ * out; any other language gets English from ALP while agents write in it.
+ */
+export declare const isVietnamese: (language: string) => boolean;
+declare const en: {
+    approve: string;
+    reject: string;
+    answerLine: (agent: string) => string;
+    skill: (agent: string, replacing: boolean, file: string, roles: string, lessons: string[]) => string;
+    issue: (agent: string, create: boolean, issue: number | undefined, where: string) => string;
+    issueTitle: string;
+    issueLabels: string;
+    trust: (project: string, names: string) => string;
+    trustYes: string;
+    trustNo: string;
+    allowOnce: string;
+    alwaysAllow: string;
+    deny: string;
+    permission: (agent: string, what: string, byRule: boolean, profile: string | undefined, mode: string, always: string | undefined) => string;
+    limitReached: (runtime: string, resetsAt: string | undefined, other: string | undefined, autoResume: boolean, kind: string) => string;
+    limitLifted: (runtime: string, kind: string) => string;
+    usageWarning: (runtime: string, used: string, resetsAt: string | undefined) => string;
+    /** The web app's answer to a Paseo feature ALP has not got yet (ALPD §62). */
+    inDevelopment: string;
+    resumed: (what: string, by: string, parked: boolean) => string;
+    paused: (what: string, reason: string | undefined, runtime: string | undefined, now: boolean) => string;
+};
+export type Words = typeof en;
+export declare function words(language: string): Words;
+/** Every label a choice may be answered with, in any language ALP writes. */
+export declare const CHOICES: {
+    trust: string[];
+    allowOnce: string[];
+    alwaysAllow: string[];
+    deny: string[];
+};
+/** The line every agent reads about the user's language. */
+export declare function languageInstruction(language: string, agent: string, main: boolean): string;
+export {};

package/dist/language.js

@@ -0,0 +1,68 @@
+// packages/runtime/src/language.ts
+var isVietnamese = (language) => /^(vi|vie|vietnamese|tiếng việt|tieng viet)$/i.test(language.trim());
+var en = {
+  approve: "Approve",
+  reject: "Reject",
+  answerLine: (agent) => `Answer Approve or Reject; any other answer goes back to ${agent} as feedback.`,
+  skill: (agent, replacing, file, roles, lessons) => `${agent} proposes a skill distilled from its lessons${replacing ? ", replacing the skill of that name" : ""}. Approve to save it as ${file}. Roles that get it: ${roles}.` + (lessons.length ? ` These lessons move into it and leave the lessons files:
+${lessons.map((lesson) => `- ${lesson}`).join("\n")}` : ""),
+  issue: (agent, create, issue, where) => `${agent} wants to ${create ? `open an issue in ${where}` : `comment on issue #${issue} in ${where}`}. It is posted with your GitHub account, and anyone who can see the repository can read it.`,
+  issueTitle: "Title",
+  issueLabels: "Labels",
+  trust: (project, names) => `This project's hooks run shell commands from ${project} on your machine: ${names}. Trust this workspace's hooks? ALP asks once: after you agree, its hooks run without asking, including hooks added or changed later.`,
+  trustYes: "Trust this workspace",
+  trustNo: "Not now",
+  allowOnce: "Allow once",
+  alwaysAllow: "Always allow",
+  deny: "Deny",
+  permission: (agent, what, byRule, profile, mode, always) => `${agent} wants to ${what}. ` + (byRule ? `Its permission profile ${profile} asks you each time.` : `Its ${mode} mode does not allow that.`) + (always ? ` Always allow adds ${always} to profile ${profile}.` : ""),
+  limitReached: (runtime, resetsAt, other, autoResume, kind) => `${runtime} usage limit reached${resetsAt ? `; it resets ${resetsAt}` : ""}. ALP paused delegation to ${runtime} agents and parked their assignments${other ? `; ${other} agents keep working` : ""}. ${autoResume ? `ALP asks ${runtime} every minute and resumes it as soon as the limit lifts.` : `ALP asks ${runtime} every minute and tells you when the limit lifts; then run alp resume ${kind}.`}`,
+  limitLifted: (runtime, kind) => `${runtime} says its usage limit has lifted. Run alp resume ${kind} to continue its work.`,
+  usageWarning: (runtime, used, resetsAt) => `${runtime} has used ${used} of a usage window${resetsAt ? ` that resets ${resetsAt}` : ""}.`,
+  /** The web app's answer to a Paseo feature ALP has not got yet (ALPD §62). */
+  inDevelopment: "This feature is in development",
+  resumed: (what, by, parked) => `${what} resumed by ${by}.${parked ? " Parked assignments continue." : ""}`,
+  paused: (what, reason, runtime, now) => `${what} paused by the user${reason ? `: ${reason}` : ""}. Delegation${runtime ? ` to ${runtime} agents` : ""} waits${now ? ", and running assignments park where they are" : "; running turns finish"}. alp resume continues.`
+};
+var viWhat = (what) => what.replace(/^run /, "ch\u1EA1y ").replace(/^change files under /, "s\u1EEDa file trong ").replace(/^change files/, "s\u1EEDa file").replace(/^use /, "d\xF9ng ");
+var vi = {
+  approve: "Duy\u1EC7t",
+  reject: "T\u1EEB ch\u1ED1i",
+  answerLine: (agent) => `Ch\u1ECDn Duy\u1EC7t ho\u1EB7c T\u1EEB ch\u1ED1i; c\xE2u tr\u1EA3 l\u1EDDi kh\xE1c s\u1EBD \u0111\u01B0\u1EE3c g\u1EEDi l\u1EA1i cho ${agent} l\xE0m g\xF3p \xFD.`,
+  skill: (agent, replacing, file, roles, lessons) => `${agent} \u0111\u1EC1 xu\u1EA5t m\u1ED9t skill \u0111\xFAc k\u1EBFt t\u1EEB c\xE1c b\xE0i h\u1ECDc${replacing ? ", thay cho skill c\xF9ng t\xEAn" : ""}. Duy\u1EC7t \u0111\u1EC3 l\u01B0u th\xE0nh ${file}. C\xE1c vai \u0111\u01B0\u1EE3c d\xF9ng: ${roles}.` + (lessons.length ? ` C\xE1c b\xE0i h\u1ECDc sau chuy\u1EC3n v\xE0o skill v\xE0 r\u1EDDi kh\u1ECFi file b\xE0i h\u1ECDc:
+${lessons.map((lesson) => `- ${lesson}`).join("\n")}` : ""),
+  issue: (agent, create, issue, where) => `${agent} mu\u1ED1n ${create ? `m\u1EDF m\u1ED9t issue trong ${where}` : `b\xECnh lu\u1EADn v\xE0o issue #${issue} trong ${where}`}. N\u1ED9i dung \u0111\u01B0\u1EE3c \u0111\u0103ng b\u1EB1ng t\xE0i kho\u1EA3n GitHub c\u1EE7a b\u1EA1n, ai xem \u0111\u01B0\u1EE3c repository \u0111\u1EC1u \u0111\u1ECDc \u0111\u01B0\u1EE3c.`,
+  issueTitle: "Ti\xEAu \u0111\u1EC1",
+  issueLabels: "Nh\xE3n",
+  trust: (project, names) => `C\xE1c hook c\u1EE7a project n\xE0y ch\u1EA1y l\u1EC7nh shell t\u1EEB ${project} tr\xEAn m\xE1y c\u1EE7a b\u1EA1n: ${names}. Tin c\u1EADy c\xE1c hook c\u1EE7a workspace n\xE0y? ALP ch\u1EC9 h\u1ECFi m\u1ED9t l\u1EA7n: khi b\u1EA1n \u0111\u1ED3ng \xFD, c\xE1c hook ch\u1EA1y m\xE0 kh\xF4ng h\u1ECFi l\u1EA1i, k\u1EC3 c\u1EA3 hook th\xEAm ho\u1EB7c s\u1EEDa sau n\xE0y.`,
+  trustYes: "Tin c\u1EADy workspace n\xE0y",
+  trustNo: "\u0110\u1EC3 sau",
+  allowOnce: "Cho ph\xE9p l\u1EA7n n\xE0y",
+  alwaysAllow: "Lu\xF4n cho ph\xE9p",
+  deny: "T\u1EEB ch\u1ED1i",
+  permission: (agent, what, byRule, profile, mode, always) => `${agent} mu\u1ED1n ${viWhat(what)}. ` + (byRule ? `H\u1ED3 s\u01A1 quy\u1EC1n ${profile} c\u1EE7a n\xF3 y\xEAu c\u1EA7u h\u1ECFi b\u1EA1n m\u1ED7i l\u1EA7n.` : `Ch\u1EBF \u0111\u1ED9 ${mode} c\u1EE7a n\xF3 kh\xF4ng cho ph\xE9p vi\u1EC7c n\xE0y.`) + (always ? ` Lu\xF4n cho ph\xE9p s\u1EBD th\xEAm ${always} v\xE0o h\u1ED3 s\u01A1 ${profile}.` : ""),
+  limitReached: (runtime, resetsAt, other, autoResume, kind) => `${runtime} \u0111\xE3 h\u1EBFt h\u1EA1n m\u1EE9c s\u1EED d\u1EE5ng${resetsAt ? `; h\u1EA1n m\u1EE9c \u0111\u1EB7t l\u1EA1i l\xFAc ${resetsAt}` : ""}. ALP t\u1EA1m d\u1EEBng giao vi\u1EC7c cho c\xE1c agent ${runtime} v\xE0 t\u1EA1m gi\u1EEF vi\u1EC7c c\u1EE7a ch\xFAng${other ? `; c\xE1c agent ${other} v\u1EABn l\xE0m ti\u1EBFp` : ""}. ${autoResume ? `ALP h\u1ECFi ${runtime} m\u1ED7i ph\xFAt v\xE0 t\u1EF1 ch\u1EA1y l\u1EA1i ngay khi c\xF3 h\u1EA1n m\u1EE9c.` : `ALP h\u1ECFi ${runtime} m\u1ED7i ph\xFAt v\xE0 b\xE1o khi c\xF3 h\u1EA1n m\u1EE9c tr\u1EDF l\u1EA1i; khi \u0111\xF3 ch\u1EA1y alp resume ${kind}.`}`,
+  limitLifted: (runtime, kind) => `${runtime} b\xE1o \u0111\xE3 c\xF3 h\u1EA1n m\u1EE9c tr\u1EDF l\u1EA1i. Ch\u1EA1y alp resume ${kind} \u0111\u1EC3 l\xE0m ti\u1EBFp vi\u1EC7c c\u1EE7a n\xF3.`,
+  usageWarning: (runtime, used, resetsAt) => `${runtime} \u0111\xE3 d\xF9ng ${used} h\u1EA1n m\u1EE9c c\u1EE7a k\u1EF3 n\xE0y${resetsAt ? `, k\u1EF3 \u0111\u1EB7t l\u1EA1i l\xFAc ${resetsAt}` : ""}.`,
+  inDevelopment: "T\xEDnh n\u0103ng \u0111ang ph\xE1t tri\u1EC3n",
+  resumed: (what, by, parked) => `${what} \u0111\xE3 ch\u1EA1y l\u1EA1i, b\u1EDFi ${by}.${parked ? " C\xE1c vi\u1EC7c \u0111ang t\u1EA1m gi\u1EEF \u0111\u01B0\u1EE3c l\xE0m ti\u1EBFp." : ""}`,
+  paused: (what, reason, runtime, now) => `${what} \u0111\xE3 b\u1ECB ng\u01B0\u1EDDi d\xF9ng t\u1EA1m d\u1EEBng${reason ? `: ${reason}` : ""}. Vi\u1EC7c giao${runtime ? ` cho c\xE1c agent ${runtime}` : ""} ph\u1EA3i ch\u1EDD${now ? ", c\xE1c vi\u1EC7c \u0111ang ch\u1EA1y \u0111\u01B0\u1EE3c t\u1EA1m gi\u1EEF t\u1EA1i ch\u1ED7" : "; c\xE1c l\u01B0\u1EE3t \u0111ang ch\u1EA1y v\u1EABn ch\u1EA1y h\u1EBFt"}. Ch\u1EA1y alp resume \u0111\u1EC3 ti\u1EBFp t\u1EE5c.`
+};
+function words(language) {
+  return isVietnamese(language) ? vi : en;
+}
+var CHOICES = {
+  trust: [en.trustYes, vi.trustYes].map((label) => label.toLowerCase()),
+  allowOnce: [en.allowOnce, vi.allowOnce].map((label) => label.toLowerCase()),
+  alwaysAllow: [en.alwaysAllow, vi.alwaysAllow].map((label) => label.toLowerCase()),
+  deny: [en.deny, vi.deny].map((label) => label.toLowerCase())
+};
+function languageInstruction(language, agent, main) {
+  return main ? `The user reads ${language}. Write in ${language} everything the user reads: your replies, questions you ask with alp_ask (and their options), approval requests and what you say about them, gate notes, and the titles and descriptions of tasks you create. Briefs, handoffs and mail between agents may use any language. GitHub issues and comments follow the repository's language; tell the user about them in ${language}.` : agent === "supervisor" ? `The user reads ${language}: main must write everything the user reads in ${language}.` : `The user reads ${language}. A question you put to the user with alp_ask, and its options, must be in ${language}; briefs, handoffs and mail between agents may use any language.`;
+}
+export {
+  CHOICES,
+  isVietnamese,
+  languageInstruction,
+  words
+};

package/dist/live.d.ts

@@ -0,0 +1,48 @@
+import type { RuntimeKind, SessionSpec } from './resolve.js';
+import type { Worktree } from './workspace.js';
+/**
+ * Assignments that are running, kept on disk so the next alpd can continue them
+ * after a crash or a restart (plans/reference/ALPD.md §31). An entry is written once
+ * its native thread exists and removed when the assignment starts to finish, so a
+ * crash while finishing never runs finished work again.
+ */
+export type LiveEntry = {
+    assignmentId: string;
+    rootId: string;
+    /** The requester's session, which must be open again before this one continues. */
+    parentId: string;
+    callId: string;
+    agent: string;
+    /** The project root, whose tasks and board the assignment uses. */
+    project: string;
+    ancestry: string[];
+    runtime: RuntimeKind;
+    /** The model without its runtime prefix, as the session resolved it. */
+    model: string;
+    threadId: string;
+    /** The spec the assignment's session was opened with. */
+    spec: SessionSpec;
+    delegation: boolean;
+    mode: string;
+    isolation: 'shared' | 'worktree';
+    taskId?: string;
+    worktree?: Worktree;
+    /** The requester's directory, when the assignment worked in a disposable copy of it. */
+    copyOf?: string;
+    lease?: string;
+    fingerprint?: string;
+    startedAt: number;
+    /** The brief it was given, repeated to it after a compaction (ALPD §57). */
+    brief?: string;
+    /** The alpd process that wrote the entry; another epoch means an earlier alpd. */
+    epoch: string;
+};
+/** The book of running assignments, in `file` when given, else in memory. */
+export declare function createLiveBook(file?: string): {
+    all: () => LiveEntry[];
+    get: (assignmentId: string) => LiveEntry | undefined;
+    put(entry: LiveEntry): Promise<void>;
+    remove(assignmentId: string): Promise<void>;
+    flush: () => Promise<void>;
+};
+export type LiveBook = ReturnType<typeof createLiveBook>;

package/dist/live.js

@@ -0,0 +1,45 @@
+// packages/runtime/src/live.ts
+import { readFileSync } from "node:fs";
+import { mkdir, rename, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { createLogger } from "@anhlp/alp-core/log";
+var valid = (entry) => !!entry && typeof entry === "object" && ["assignmentId", "rootId", "parentId", "agent", "project", "runtime", "model", "threadId", "mode", "isolation", "epoch"].every((key) => typeof entry[key] === "string") && Array.isArray(entry.ancestry) && !!entry.spec && typeof entry.spec === "object" && typeof entry.startedAt === "number";
+function createLiveBook(file) {
+  let entries = [];
+  if (file) {
+    try {
+      entries = JSON.parse(readFileSync(file, "utf8")).filter(valid);
+    } catch {
+    }
+  }
+  let writes = Promise.resolve();
+  const save = () => {
+    if (!file) return writes;
+    const body = JSON.stringify(entries, null, 2) + "\n";
+    writes = writes.then(async () => {
+      await mkdir(path.dirname(file), { recursive: true, mode: 448 });
+      const temporary = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+      await writeFile(temporary, body, { mode: 384 });
+      await rename(temporary, file);
+    }).catch((error) => createLogger({ component: "runtime" }).error("could not save the live assignments", { code: "ALP_PERSISTENCE_WRITE_FAILED", operation: "live assignments", error }));
+    return writes;
+  };
+  return {
+    all: () => [...entries],
+    get: (assignmentId) => entries.find((entry) => entry.assignmentId === assignmentId),
+    put(entry) {
+      entries = [...entries.filter((existing) => existing.assignmentId !== entry.assignmentId), entry];
+      return save();
+    },
+    remove(assignmentId) {
+      if (!entries.some((entry) => entry.assignmentId === assignmentId)) return writes;
+      entries = entries.filter((entry) => entry.assignmentId !== assignmentId);
+      return save();
+    },
+    flush: () => writes
+  };
+}
+export {
+  createLiveBook
+};