@anhlp/alp 0.0.0-beta.1

package/packages/cli/dist/tasks.js

@@ -0,0 +1,345 @@
+// packages/cli/src/tasks.js
+import { spawn } from "node:child_process";
+import { access, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { exportBeads, importBeads, parseJsonl } from "@anhlp/alp-core/beads";
+import { findFormula, formulaDirs, listFormulas, pourFormula } from "@anhlp/alp-core/formulas";
+import { describeVerification } from "@anhlp/alp-core/verify";
+import { ago } from "@anhlp/alp-client/render";
+import { parse as toml } from "smol-toml";
+import { addGate, blockersOf, checkGates, childrenOf, closeTask, compactTasks, createTask, describeGate, gateOpen, epicReport, gatesOf, linkTask, listTasks, loadTasks, readyTasks, reopenTask, resolveGate, summarize, TASKS_DIR, updateTask } from "@anhlp/alp-core/tasks";
+import { alpHome } from "@anhlp/alp-client/index";
+import { UsageError } from "./usage.js";
+var STATUS_MARK = { open: "\u25CB", in_progress: "\u25D0", review: "\u25D1", closed: "\u25CF" };
+async function taskProject(directory) {
+  const root = path.resolve(directory ?? process.cwd());
+  try {
+    await access(path.join(root, ".alp"));
+  } catch {
+    throw new Error(`${root} is not an ALP project (no .alp directory); run alp init, or pass --project`);
+  }
+  return root;
+}
+function taskRow(task, tasks) {
+  const row = summarize(task, tasks);
+  const extra = [
+    row.blockedBy ? `blocked by ${row.blockedBy.join(", ")}` : "",
+    row.gates ? `waits on ${row.gates.join("; ")}` : "",
+    row.assignee ? `@${row.assignee}` : "",
+    row.labels ? row.labels.map((label) => `#${label}`).join(" ") : ""
+  ].filter(Boolean).join("  ");
+  return `${STATUS_MARK[task.status]} ${task.id.padEnd(10)} P${task.priority} ${task.type.padEnd(7)} ${task.status.padEnd(11)} ${task.title}${extra ? `  ${extra}` : ""}`;
+}
+function warnUnreadable(errors) {
+  for (const { file, error } of errors) console.error(`alp: skipped ${file}: ${error}`);
+}
+async function tasksCommand(args) {
+  if (args[0] === "gates" || args[0] === "compact") return taskMaintenance([args[0]], args.slice(1));
+  if (args[0] === "export" || args[0] === "import") return beads(args[0], args.slice(1));
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
+    all: { type: "boolean" },
+    status: { type: "string" },
+    label: { type: "string" },
+    project: { type: "string" },
+    json: { type: "boolean" }
+  } });
+  if (positionals.length > 1 || positionals.length && positionals[0] !== "ready") throw new UsageError();
+  const root = await taskProject(values.project);
+  const { tasks, errors } = await loadTasks(root);
+  warnUnreadable(errors);
+  const rows = positionals[0] === "ready" ? readyTasks(tasks) : listTasks(tasks, { status: values.status, label: values.label, all: values.all });
+  if (values.json) {
+    console.log(JSON.stringify(rows));
+    return;
+  }
+  if (!rows.length) {
+    console.log(positionals[0] === "ready" ? "No task is ready" : `No tasks in ${path.join(root, TASKS_DIR)}`);
+    return;
+  }
+  for (const task of rows) console.log(taskRow(task, tasks));
+}
+var gh = (args, { cwd }) => new Promise((resolve, reject) => {
+  const bin = process.env.ALP_GH_BIN ?? "gh";
+  const script = process.platform === "win32" && /\.[cm]?js$/i.test(bin);
+  const child = spawn(script ? process.execPath : bin, script ? [bin, ...args] : args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+  let stdout = "";
+  let stderr = "";
+  child.stdout.on("data", (chunk) => {
+    stdout += chunk;
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk;
+  });
+  child.on("error", (error) => reject(error.code === "ENOENT" ? new Error("gh is not installed or not on PATH") : error));
+  child.on("close", (code) => code === 0 ? resolve(stdout) : reject(new Error(stderr.trim() || `gh exited with ${code}`)));
+});
+async function taskMaintenance([command], args) {
+  const { values, positionals: rest } = parseArgs({ args, allowPositionals: true, options: {
+    project: { type: "string" },
+    json: { type: "boolean" },
+    days: { type: "string" },
+    "dry-run": { type: "boolean" }
+  } });
+  if (rest.length) throw new UsageError();
+  const root = await taskProject(values.project);
+  if (command === "compact") {
+    const days = values.days === void 0 ? 30 : Number(values.days);
+    const changed = await compactTasks(root, { days, dryRun: values["dry-run"] }, "user");
+    if (values.json) {
+      console.log(JSON.stringify(changed));
+      return;
+    }
+    if (!changed.length) {
+      console.log(`No task closed more than ${days} days ago is left to compact`);
+      return;
+    }
+    for (const { id, before, after } of changed) console.log(`${id}  ${before} \u2192 ${after} characters`);
+    console.log(`${values["dry-run"] ? "Would compact" : "Compacted"} ${changed.length} closed ${changed.length === 1 ? "task" : "tasks"}`);
+    return;
+  }
+  const checked = await checkGates(root, gh);
+  const { tasks } = await loadTasks(root);
+  const open = tasks.filter((task) => task.status !== "closed").flatMap((task) => task.gates.filter((gate) => gateOpen(gate)).map((gate) => ({ task, gate })));
+  if (values.json) {
+    console.log(JSON.stringify({ ...checked, open: open.map(({ task, gate }) => ({ task: task.id, ...gate })) }));
+    return;
+  }
+  for (const { task, gate, detail } of checked.cleared) console.log(`\u2713 ${task} ${gate} cleared: ${detail}`);
+  for (const { task, gate, error } of checked.errors) console.error(`alp: could not check ${task} ${gate}: ${error}`);
+  if (!open.length) {
+    console.log("No open gates");
+    return;
+  }
+  for (const { task, gate } of open) {
+    const state = checked.pending.find((entry) => entry.task === task.id && entry.gate === gate.id)?.detail;
+    console.log(`\u23F8 ${task.id} ${describeGate(gate)}${state ? ` (${state})` : ""}  ${task.title}`);
+  }
+}
+async function beads(command, args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
+    project: { type: "string" },
+    output: { type: "string", short: "o" },
+    "dry-run": { type: "boolean" },
+    json: { type: "boolean" }
+  } });
+  const root = await taskProject(values.project);
+  if (command === "export") {
+    if (positionals.length || values["dry-run"]) throw new UsageError();
+    const { tasks, errors: errors2 } = await loadTasks(root);
+    warnUnreadable(errors2);
+    const text = exportBeads(tasks).map((record) => JSON.stringify(record)).join("\n") + (tasks.length ? "\n" : "");
+    if (values.output) {
+      await writeFile(values.output, text);
+      console.error(`Exported ${tasks.length} ${tasks.length === 1 ? "task" : "tasks"} to ${values.output}`);
+    } else {
+      process.stdout.write(text);
+    }
+    return;
+  }
+  if (positionals.length > 1 || values.output) throw new UsageError();
+  const file = positionals[0] ?? path.join(root, ".beads", "issues.jsonl");
+  const { records, errors } = parseJsonl(await readFile(file, "utf8"));
+  const report = await importBeads(root, records, { dryRun: values["dry-run"], by: "user" });
+  report.skipped.push(...errors);
+  if (values.json) {
+    console.log(JSON.stringify(report));
+    return;
+  }
+  const verb = values["dry-run"] ? "Would import" : "Imported";
+  for (const { id, from } of report.created) console.log(`+ ${id}${id !== from ? ` (from ${from})` : ""}`);
+  for (const { id, from } of report.updated) console.log(`~ ${id}${id !== from ? ` (from ${from})` : ""}`);
+  for (const { line, reason } of report.skipped.sort((a, b) => a.line - b.line)) console.error(`alp: skipped line ${line}: ${reason}`);
+  for (const warning of report.warnings) console.error(`alp: ${warning}`);
+  console.log(`${verb} ${file}: ${report.created.length} created, ${report.updated.length} updated, ${report.skipped.length} skipped`);
+}
+async function formulaCommand([action, ...args]) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
+    project: { type: "string" },
+    var: { type: "string", multiple: true },
+    parent: { type: "string" },
+    "dry-run": { type: "boolean" },
+    json: { type: "boolean" }
+  } });
+  const root = await taskProject(values.project);
+  const home = alpHome();
+  if (action === "list") {
+    if (positionals.length) throw new UsageError();
+    const found = await listFormulas(root, home, { toml });
+    if (values.json) {
+      console.log(JSON.stringify(found));
+      return;
+    }
+    if (!found.length) {
+      console.log(`No formulas in ${formulaDirs(root, home).join(", ")}`);
+      return;
+    }
+    for (const entry of found) console.log(entry.error ? `\u2717 ${entry.name}  ${entry.file}: ${entry.error}` : `${entry.name}  ${entry.formula.steps.length} steps${entry.formula.description ? `  ${entry.formula.description.split("\n")[0]}` : ""}`);
+    return;
+  }
+  if (positionals.length !== 1) throw new UsageError();
+  const { formula, file } = await findFormula(root, home, positionals[0], { toml });
+  if (action === "show") {
+    if (values.json) {
+      console.log(JSON.stringify(formula));
+      return;
+    }
+    console.log(`${formula.formula}${formula.version ? ` v${formula.version}` : ""}  ${file}`);
+    if (formula.description) console.log(`  ${formula.description}`);
+    for (const [name, spec] of Object.entries(formula.vars)) console.log(`  --var ${name}=\u2026${spec.required ? " (required)" : spec.default !== void 0 ? ` (default ${spec.default})` : ""}${spec.description ? `  ${spec.description}` : ""}`);
+    for (const step of formula.steps) console.log(`  ${step.id}${step.type === "human" ? " [you]" : step.type !== "task" ? ` [${step.type}]` : ""}: ${step.title}${step.needs.length ? `  after ${step.needs.join(", ")}` : ""}`);
+    return;
+  }
+  if (action !== "pour") throw new UsageError();
+  const given = {};
+  for (const entry of values.var ?? []) {
+    const at = entry.indexOf("=");
+    if (at < 1) throw new UsageError();
+    given[entry.slice(0, at)] = entry.slice(at + 1);
+  }
+  const { epic, tasks } = await pourFormula(root, formula, given, "user", { dryRun: values["dry-run"], ...values.parent ? { parent: values.parent } : {} });
+  if (values.json) {
+    console.log(JSON.stringify({ epic, tasks }));
+    return;
+  }
+  console.log(`${values["dry-run"] ? "Would pour" : "Poured"} ${formula.formula} as ${epic.id}  ${epic.title}`);
+  const all = [epic, ...tasks];
+  for (const task of tasks) console.log(`  ${taskRow(task, all)}`);
+}
+var repeated = { type: "string", multiple: true };
+async function taskCommand([action, ...args]) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
+    description: { type: "string", short: "d" },
+    priority: { type: "string", short: "p" },
+    type: { type: "string", short: "t" },
+    label: { ...repeated, short: "l" },
+    path: repeated,
+    parent: { type: "string" },
+    after: repeated,
+    related: repeated,
+    from: { type: "string" },
+    title: { type: "string" },
+    message: { type: "string", short: "m" },
+    reason: { type: "string" },
+    unverified: { type: "string" },
+    project: { type: "string" },
+    json: { type: "boolean" },
+    human: { type: "string" },
+    timer: { type: "string" },
+    pr: { type: "string" },
+    run: { type: "string" }
+  } });
+  const root = await taskProject(values.project);
+  const fields = {
+    ...values.description !== void 0 ? { description: values.description } : {},
+    ...values.priority !== void 0 ? { priority: values.priority } : {},
+    ...values.type !== void 0 ? { type: values.type } : {},
+    ...values.label ? { labels: values.label } : {},
+    ...values.path ? { paths: values.path } : {}
+  };
+  let task;
+  if (action === "add") {
+    const title = positionals.join(" ").trim();
+    if (!title) throw new UsageError();
+    task = await createTask(root, { title, ...fields, parent: values.parent, blockedBy: values.after, related: values.related, discoveredFrom: values.from }, "user");
+  } else if (action === "show") {
+    if (positionals.length !== 1) throw new UsageError();
+    const { tasks: tasks2, errors } = await loadTasks(root);
+    warnUnreadable(errors);
+    task = tasks2.find((candidate) => candidate.id === positionals[0]);
+    if (!task) throw new Error(`No task ${positionals[0]} in ${path.join(root, TASKS_DIR)}`);
+    if (values.json) {
+      console.log(JSON.stringify(task));
+      return;
+    }
+    printTask(task, tasks2);
+    return;
+  } else if (action === "report") {
+    if (positionals.length !== 1) throw new UsageError();
+    const { tasks: tasks2, errors } = await loadTasks(root);
+    warnUnreadable(errors);
+    const report = epicReport(positionals[0], tasks2);
+    console.log(values.json ? JSON.stringify(report) : report.text);
+    return;
+  } else if (action === "edit") {
+    if (positionals.length !== 1) throw new UsageError();
+    task = await updateTask(root, positionals[0], { ...fields, ...values.title !== void 0 ? { title: values.title } : {}, note: values.message }, "user");
+  } else if (action === "close") {
+    if (positionals.length !== 1) throw new UsageError();
+    task = await closeTask(root, positionals[0], { reason: values.reason, summary: values.message, unverified: values.unverified }, "user");
+  } else if (action === "reopen") {
+    if (positionals.length !== 1) throw new UsageError();
+    task = await reopenTask(root, positionals[0], { note: values.message }, "user");
+  } else if (action === "dep") {
+    const [change, id, ...rest] = positionals;
+    if (!["add", "rm"].includes(change) || !id || rest.length || !(values.after || values.parent || values.related)) throw new UsageError();
+    const links = { ...values.after ? { blockedBy: values.after } : {}, ...values.parent ? { parent: values.parent } : {}, ...values.related ? { related: values.related } : {} };
+    task = await linkTask(root, id, change === "add" ? { add: links } : { remove: links }, "user");
+  } else if (action === "gate") {
+    const [change, id, gate, ...rest] = positionals;
+    const kinds = ["human", "timer", "pr", "run"].filter((kind) => values[kind] !== void 0);
+    if (change === "add" && id && !gate && kinds.length === 1) {
+      const kind = kinds[0];
+      task = await addGate(root, id, kind === "human" ? { kind, note: values.human } : kind === "timer" ? { kind, until: values.timer } : { kind: `gh:${kind}`, ref: values[kind] }, "user");
+    } else if ((change === "clear" || change === "rm") && id && gate && !rest.length && !kinds.length) {
+      task = await resolveGate(root, id, gate, { by: "user", note: values.message, remove: change === "rm" });
+    } else {
+      throw new UsageError();
+    }
+  } else {
+    throw new UsageError();
+  }
+  if (values.json) {
+    console.log(JSON.stringify(task));
+    return;
+  }
+  const { tasks } = await loadTasks(root);
+  console.log(`${{ add: "Created", close: "Closed", reopen: "Reopened" }[action] ?? "Updated"} ${TASKS_DIR}/${task.id}.json`);
+  if (action === "gate") for (const gate of task.gates.filter((entry) => gateOpen(entry))) console.log(`  \u23F8 ${describeGate(gate)}`);
+  console.log(taskRow(task, tasks));
+  if (action === "close" && tasks.some((entry) => entry.parent === task.id)) console.log(`
+${epicReport(task.id, tasks).text}`);
+}
+function printTask(task, tasks) {
+  console.log(`${STATUS_MARK[task.status]} ${task.id}  ${task.title}`);
+  console.log(`  ${task.type}, P${task.priority}, ${task.status}${task.assignee ? ` with ${task.assignee.agent}` : ""}; created by ${task.createdBy} ${ago(task.createdAt)} ago, rev ${task.rev}`);
+  if (task.description) console.log(`
+  ${task.description.replace(/\n/g, "\n  ")}
+`);
+  const blockers = task.status === "closed" ? [] : blockersOf(task, tasks);
+  const relations = [
+    task.parent && `parent ${task.parent}`,
+    task.blockedBy.length && `after ${task.blockedBy.join(", ")}${blockers.length ? ` (open: ${blockers.join(", ")})` : ""}`,
+    task.discoveredFrom && `found during ${task.discoveredFrom}`,
+    task.related.length && `related ${task.related.join(", ")}`
+  ].filter(Boolean);
+  if (relations.length) console.log(`  ${relations.join("; ")}`);
+  for (const gate of task.gates) console.log(`  ${gateOpen(gate) ? "\u23F8" : "\u2713"} gate ${describeGate(gate)}${gate.resolved ? ` (cleared by ${gate.resolved.by}${gate.resolved.note ? `: ${gate.resolved.note}` : ""})` : ""}`);
+  const inherited = gatesOf(task, tasks).filter((label) => label.startsWith("t-"));
+  if (task.status !== "closed" && inherited.length) console.log(`  waits on its parent's gates: ${inherited.join("; ")}`);
+  if (task.compacted) console.log(`  compacted ${task.compacted.at.slice(0, 10)} from ${task.compacted.chars} characters`);
+  if (task.labels.length) console.log(`  labels: ${task.labels.join(", ")}`);
+  if (task.paths.length) console.log(`  paths: ${task.paths.join(", ")}`);
+  for (const child of childrenOf(task.id, tasks)) console.log(`  ${taskRow(child, tasks)}`);
+  if (task.verified) console.log(`  ${task.verified.skipped ? "\u2013" : task.verified.passed ? "\u2713" : "\u2717"} ${describeVerification(task.verified)}${task.verified.where ? ` in the ${task.verified.where}` : ""}, ${ago(task.verified.at)} ago`);
+  if (task.closed) console.log(`  closed ${task.closed.reason} by ${task.closed.by}${task.closed.summary ? `: ${task.closed.summary}` : ""}${task.closed.unverified ? ` (unverified: ${task.closed.unverified})` : ""}`);
+  for (const entry of task.log.slice(-10)) {
+    const { at, by, event, ...detail } = entry;
+    const text = Object.entries(detail).map(([key, value]) => `${key} ${Array.isArray(value) ? value.join(", ") : value}`).join("; ");
+    console.log(`  ${at.slice(0, 16).replace("T", " ")}  ${by} ${event}${text ? `: ${text}` : ""}`);
+  }
+}
+export {
+  STATUS_MARK,
+  beads,
+  formulaCommand,
+  gh,
+  printTask,
+  repeated,
+  taskCommand,
+  taskMaintenance,
+  taskProject,
+  taskRow,
+  tasksCommand,
+  warnUnreadable
+};

package/packages/cli/dist/usage.d.ts

@@ -0,0 +1,3 @@
+export const USAGE: "Usage:\n  alp <init|upgrade|update> [directory]\n  alp setup [directory] [--runtime codex|claude|mix] [--prefer claude|codex]\n            [--claude-model M] [--codex-model M] [--claude-supervisor M] [--codex-supervisor M]\n            [--claude-oracle M] [--codex-oracle M]   write Ph\u1EDF/Cafe's agent profiles to .alp/settings.json\n  alp daemon <start|stop|restart>\n  alp daemon status [--json]             liveness and readiness; exit 0 ready, 3 not running, 4 not ready\n  alp daemon <install|uninstall>         run alpd as a login service that restarts after a crash\n  alp acp                                serve ALP to an editor (Zed, JetBrains) over the Agent Client Protocol on stdio\n  alp web [--print]                      open the local web app alpd serves; --print only prints its address\n  alp web pair [--on|--off]              the link that pairs Paseo's app on another device through the relay; --on or --off turns the relay on or off\n  alp doctor [--project DIR] [--fix] [--json]   check this machine and project; --fix repairs what is safe to\n  alp backup [-o FILE] [--project DIR]... [--no-projects] [--stop] [--json]   sessions, settings, library and tasks in one file\n  alp backup verify <file> [--json] | alp backup list [--json]\n  alp restore <file> [--home-only] [--dry-run] [--stop] [--replace-newer] [--json]   checks the whole backup first; keeps what it replaces\n            alpd must be stopped for both; --stop stops it and starts it again after\n  alp run [--agent A] [--team pho|cafe|ID] [--model M] [--mode read-only|workspace-write|full-access] [--thinking T] [--project DIR] [--json] <prompt>\n  alp ps [--all]\n  alp top [session] [--once]\n  alp attach <session> [--json]\n  alp send <session> [--json] <text>\n  alp questions [--json]\n  alp answer <question> <text> | alp answer <question> --dismiss [--reason R]\n  alp log <session> [--json]\n  alp board [--project DIR] [--json]\n  alp <agents|skills|mcp|hooks> [--project DIR] [--json]   the library: built-in, ~/.alp and project entries\n  alp providers [--json]                    ACP and Antigravity providers in your library\n  alp teams [--project DIR] [--json]         teams sessions run in: members, delegation, house rules\n  alp agent <new|edit> <name> [--project [DIR]] [--from A] [-d text] [--provider P] [--model M] [--thinking T] [--mode M]\n            [--skills a,b] [--mcp a,b] [--hooks a,b] [--instructions FILE]\n  alp team <new|edit> <id> [--project [DIR]] [--from ID] [--label L] [-d text] [--main A] [--member name=role]...\n            [--member-model name=M]... [--member-thinking name=T]... [--delegate owner=a,b]... [--max-peers N]\n            [--supervisor A] [--supervisor-model M] [--supervisor-thinking T] [--no-supervisor] [--rules FILE]\n  alp skill new <name> [--project [DIR]] [--from S] [--file FILE]\n  alp mcp add <name> [--project [DIR]] (--command C [--arg A]... [--env K=V]... [--cwd D] | --url U [--header K=V]...)\n  alp hook add <name> [--project [DIR]] --event E --command C [--blocking] [--timeout SEC] [--match-agent A] [--match-label L]\n  alp provider add <id> --command C [--arg A]... [--env K=V]... [--label L] [-d text] [--models a,b]   an ACP agent; use id antigravity for native agy\n  alp provider edit antigravity --read-only-mode instructions|reject   opt into prompt-only read-only for advisory roles\n  alp <agent|team|skill|mcp|hook|provider> <rm|show> <name> [--project [DIR]] | <cp|mv> <from> <to> [--project [DIR]]\n  alp <mcp|hook|provider> test <name> [--project [DIR]]   list an MCP server's tools; run a hook once; initialize a provider\n            without --project, changes go to your library in ~/.alp; built-in agents and teams are never changed\n  alp trust [--project DIR] | --revoke [--project DIR] | --list [--json]   whether the project's hooks may run\n  alp permissions [--project DIR] [--json]   each agent's permission profile\n  alp permissions check <agent> \"<command>\"  what that agent's profile says about a command\n  alp tasks [ready] [--all] [--status S] [--label L] [--project DIR] [--json]\n  alp tasks gates [--json]                 open gates; checks GitHub ones\n  alp tasks compact [--days 30] [--dry-run]\n  alp tasks export [-o file.jsonl]          as beads JSONL\n  alp tasks import [file.jsonl] [--dry-run]  beads JSONL; default .beads/issues.jsonl\n  alp formula list | show <name> | pour <name> [--var k=v]... [--parent ID] [--dry-run]\n  alp task add <title> [-d text] [-p 0-4] [-t task|bug|feature|chore|epic] [--parent ID] [--after ID]... [-l label]... [--path P]... [--from ID]\n  alp task show <id> [--json]\n  alp task report <epic> [--json]           what an epic came to: tasks, time, rework, verification\n  alp task edit <id> [--title T] [-d text] [-p N] [-t type] [-l label]... [--path P]... [-m note]\n  alp task close <id> [--reason done|wontfix|duplicate|superseded] [-m summary] [--unverified \"why\"]\n  alp verify [--project DIR] [--task ID] [--json]   run the project's verify commands; --task records the result\n  alp task reopen <id> [-m note]\n  alp task dep <add|rm> <id> [--after ID]... [--parent ID] [--related ID]...\n  alp task gate add <id> --human \"question\" | --timer +2h|ISO | --pr N|owner/repo#N | --run N|owner/repo#N\n  alp task gate <clear|rm> <id> <gate> [-m note]\n  alp pause [codex|claude] [--now] [-m reason] | alp pause status   hold delegation; --now parks running assignments\n  alp resume [codex|claude]                  lift a pause; parked assignments continue\n  alp language [name | --reset]              the language agents and ALP write to you in; default Vietnamese\n  alp recall <assignment|task> [--project DIR] [--json] <question>   ask a finished assignment about its work\n  alp interrupt <session>";
+export class UsageError extends Error {
+}

package/packages/cli/dist/usage.js

@@ -0,0 +1,72 @@
+// packages/cli/src/usage.js
+var USAGE = `Usage:
+  alp <init|upgrade|update> [directory]
+  alp setup [directory] [--runtime codex|claude|mix] [--prefer claude|codex]
+            [--claude-model M] [--codex-model M] [--claude-supervisor M] [--codex-supervisor M]
+            [--claude-oracle M] [--codex-oracle M]   write Ph\u1EDF/Cafe's agent profiles to .alp/settings.json
+  alp daemon <start|stop|restart>
+  alp daemon status [--json]             liveness and readiness; exit 0 ready, 3 not running, 4 not ready
+  alp daemon <install|uninstall>         run alpd as a login service that restarts after a crash
+  alp acp                                serve ALP to an editor (Zed, JetBrains) over the Agent Client Protocol on stdio
+  alp web [--print]                      open the local web app alpd serves; --print only prints its address
+  alp web pair [--on|--off]              the link that pairs Paseo's app on another device through the relay; --on or --off turns the relay on or off
+  alp doctor [--project DIR] [--fix] [--json]   check this machine and project; --fix repairs what is safe to
+  alp backup [-o FILE] [--project DIR]... [--no-projects] [--stop] [--json]   sessions, settings, library and tasks in one file
+  alp backup verify <file> [--json] | alp backup list [--json]
+  alp restore <file> [--home-only] [--dry-run] [--stop] [--replace-newer] [--json]   checks the whole backup first; keeps what it replaces
+            alpd must be stopped for both; --stop stops it and starts it again after
+  alp run [--agent A] [--team pho|cafe|ID] [--model M] [--mode read-only|workspace-write|full-access] [--thinking T] [--project DIR] [--json] <prompt>
+  alp ps [--all]
+  alp top [session] [--once]
+  alp attach <session> [--json]
+  alp send <session> [--json] <text>
+  alp questions [--json]
+  alp answer <question> <text> | alp answer <question> --dismiss [--reason R]
+  alp log <session> [--json]
+  alp board [--project DIR] [--json]
+  alp <agents|skills|mcp|hooks> [--project DIR] [--json]   the library: built-in, ~/.alp and project entries
+  alp providers [--json]                    ACP and Antigravity providers in your library
+  alp teams [--project DIR] [--json]         teams sessions run in: members, delegation, house rules
+  alp agent <new|edit> <name> [--project [DIR]] [--from A] [-d text] [--provider P] [--model M] [--thinking T] [--mode M]
+            [--skills a,b] [--mcp a,b] [--hooks a,b] [--instructions FILE]
+  alp team <new|edit> <id> [--project [DIR]] [--from ID] [--label L] [-d text] [--main A] [--member name=role]...
+            [--member-model name=M]... [--member-thinking name=T]... [--delegate owner=a,b]... [--max-peers N]
+            [--supervisor A] [--supervisor-model M] [--supervisor-thinking T] [--no-supervisor] [--rules FILE]
+  alp skill new <name> [--project [DIR]] [--from S] [--file FILE]
+  alp mcp add <name> [--project [DIR]] (--command C [--arg A]... [--env K=V]... [--cwd D] | --url U [--header K=V]...)
+  alp hook add <name> [--project [DIR]] --event E --command C [--blocking] [--timeout SEC] [--match-agent A] [--match-label L]
+  alp provider add <id> --command C [--arg A]... [--env K=V]... [--label L] [-d text] [--models a,b]   an ACP agent; use id antigravity for native agy
+  alp provider edit antigravity --read-only-mode instructions|reject   opt into prompt-only read-only for advisory roles
+  alp <agent|team|skill|mcp|hook|provider> <rm|show> <name> [--project [DIR]] | <cp|mv> <from> <to> [--project [DIR]]
+  alp <mcp|hook|provider> test <name> [--project [DIR]]   list an MCP server's tools; run a hook once; initialize a provider
+            without --project, changes go to your library in ~/.alp; built-in agents and teams are never changed
+  alp trust [--project DIR] | --revoke [--project DIR] | --list [--json]   whether the project's hooks may run
+  alp permissions [--project DIR] [--json]   each agent's permission profile
+  alp permissions check <agent> "<command>"  what that agent's profile says about a command
+  alp tasks [ready] [--all] [--status S] [--label L] [--project DIR] [--json]
+  alp tasks gates [--json]                 open gates; checks GitHub ones
+  alp tasks compact [--days 30] [--dry-run]
+  alp tasks export [-o file.jsonl]          as beads JSONL
+  alp tasks import [file.jsonl] [--dry-run]  beads JSONL; default .beads/issues.jsonl
+  alp formula list | show <name> | pour <name> [--var k=v]... [--parent ID] [--dry-run]
+  alp task add <title> [-d text] [-p 0-4] [-t task|bug|feature|chore|epic] [--parent ID] [--after ID]... [-l label]... [--path P]... [--from ID]
+  alp task show <id> [--json]
+  alp task report <epic> [--json]           what an epic came to: tasks, time, rework, verification
+  alp task edit <id> [--title T] [-d text] [-p N] [-t type] [-l label]... [--path P]... [-m note]
+  alp task close <id> [--reason done|wontfix|duplicate|superseded] [-m summary] [--unverified "why"]
+  alp verify [--project DIR] [--task ID] [--json]   run the project's verify commands; --task records the result
+  alp task reopen <id> [-m note]
+  alp task dep <add|rm> <id> [--after ID]... [--parent ID] [--related ID]...
+  alp task gate add <id> --human "question" | --timer +2h|ISO | --pr N|owner/repo#N | --run N|owner/repo#N
+  alp task gate <clear|rm> <id> <gate> [-m note]
+  alp pause [codex|claude] [--now] [-m reason] | alp pause status   hold delegation; --now parks running assignments
+  alp resume [codex|claude]                  lift a pause; parked assignments continue
+  alp language [name | --reset]              the language agents and ALP write to you in; default Vietnamese
+  alp recall <assignment|task> [--project DIR] [--json] <question>   ask a finished assignment about its work
+  alp interrupt <session>`;
+var UsageError = class extends Error {
+};
+export {
+  USAGE,
+  UsageError
+};

package/packages/client/README.md

@@ -0,0 +1,24 @@
+# @anhlp/alp-client
+
+The ALP RPC client: a portable JSON-RPC engine for Node, browsers and React Native, its
+WebSocket and Node IPC transports, and the Node-only daemon discovery, supervision, services
+and setup helpers.
+
+- `@anhlp/alp-client/portable`: `AlpRpcClient`, errors, `hello`, `createReconnectingClient`,
+  NDJSON framing. No Node built-ins, `process` or `Buffer`; needs no polyfills.
+- `@anhlp/alp-client/websocket`: `connectWebSocket` over the browser's, React Native's or an
+  injected WebSocket. Authentication is the caller's (the gateway's) business.
+- `@anhlp/alp-client` (Node): everything above plus `connect`, `AlpClient`, `connectSocket`,
+  `ensureDaemon`, the private-socket checks and lock helpers, unchanged for existing callers.
+- `@anhlp/alp-client/ipc` (Node): `createSocketTransport` for a Unix socket or named pipe.
+
+Timeouts and aborts end only the caller's wait, and nothing is ever resent after a disconnect.
+See [docs/alp/client-sdk.md](../../docs/alp/client-sdk.md) for the transport contract, the
+request lifecycle, the old-to-new API table and what still waits on the protocol (Task 06) and
+the gateway (Task 08).
+
+`startIntegration` discovers an optional integration's descriptor and starts it detached with `--service`, so the entry writes its own log; discovery and the selected `ALP_HOME` are pinned by tests. Restarting is non-destructive: a daemon left running by an older install is reported as older than the current CLI and is never killed in place.
+
+Build: `npm run build --workspace=@anhlp/alp-client`. Test: `npm run test --workspace=@anhlp/alp-client`.
+
+Public imports use the package root and its explicitly exported subpaths. See [architecture, provider extension, compatibility and release instructions](../../docs/modular-monorepo.md).

package/packages/client/dist/acp-probe.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Starts an ACP provider once and runs initialize (ALPD §46), for `alp provider test`
+ * and the settings screen. It reports who the agent says it is and what it supports;
+ * a provider that needs a login usually says so here, in authMethods. With `discover`,
+ * it also opens a session in `cwd`, as Paseo does, to read the models and modes the agent
+ * offers (ALPD §65); an agent that offers none leaves them out.
+ * @param {{ command: string, args?: string[], env?: Record<string, string>, label?: string, id?: string }} provider
+ * @param {{ cwd?: string, timeoutMs?: number, discover?: boolean }} [options]
+ * @returns {Promise<{ protocolVersion: number, agent?: { name?: string, title?: string, version?: string }, loadSession: boolean, mcpHttp: boolean, authMethods: string[],
+ *   models?: Array<{ id: string, label: string, description?: string }>, currentModel?: string, modes?: Array<{ id: string, label: string, description?: string }>, currentMode?: string }>}
+ */
+export function probeAcp(provider: {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    label?: string;
+    id?: string;
+}, { cwd, timeoutMs, discover }?: {
+    cwd?: string;
+    timeoutMs?: number;
+    discover?: boolean;
+}): Promise<{
+    protocolVersion: number;
+    agent?: {
+        name?: string;
+        title?: string;
+        version?: string;
+    };
+    loadSession: boolean;
+    mcpHttp: boolean;
+    authMethods: string[];
+    models?: Array<{
+        id: string;
+        label: string;
+        description?: string;
+    }>;
+    currentModel?: string;
+    modes?: Array<{
+        id: string;
+        label: string;
+        description?: string;
+    }>;
+    currentMode?: string;
+}>;

package/packages/client/dist/acp-probe.js

@@ -0,0 +1,37 @@
+// packages/client/src/acp-probe.js
+import { stdioSession } from "./mcp-probe.js";
+async function probeAcp(provider, { cwd, timeoutMs = 2e4, discover = false } = {}) {
+  const session = stdioSession({ command: provider.command, args: provider.args ?? [], env: provider.env ?? {} }, cwd, timeoutMs);
+  try {
+    const result = await session.request("initialize", {
+      protocolVersion: 1,
+      clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+      clientInfo: { name: "alp", title: "ALP", version: "1" }
+    });
+    if (result.protocolVersion !== 1) throw new Error(`${provider.label ?? provider.id} speaks ACP version ${result.protocolVersion}; ALP speaks version 1`);
+    const info = result.agentInfo;
+    const offered = discover ? await session.request("session/new", { cwd, mcpServers: [] }) : void 0;
+    const choices = (list) => Array.isArray(list) ? list.filter((item) => typeof (item?.modelId ?? item?.id) === "string").map((item) => ({ id: item.modelId ?? item.id, label: typeof item.name === "string" && item.name ? item.name : item.modelId ?? item.id, ...typeof item.description === "string" && item.description ? { description: item.description } : {} })) : void 0;
+    const config = offered?.configOptions?.find((option) => option.category === "model" && option.type === "select");
+    const modeConfig = offered?.configOptions?.find((option) => option.category === "mode" && option.type === "select");
+    const flatten = (options) => options?.flatMap((option) => option.options ?? [option]).map((option) => ({ ...option, id: option.value }));
+    const modelState = offered?.models ?? (config ? { availableModels: flatten(config.options), currentModelId: config.currentValue } : void 0);
+    const modeState = offered?.modes ?? (modeConfig ? { availableModes: flatten(modeConfig.options), currentModeId: modeConfig.currentValue } : void 0);
+    const models = choices(modelState?.availableModels);
+    const modes = choices(modeState?.availableModes);
+    return {
+      ...models ? { models, ...typeof modelState.currentModelId === "string" ? { currentModel: modelState.currentModelId } : {} } : {},
+      ...modes ? { modes, ...typeof modeState.currentModeId === "string" ? { currentMode: modeState.currentModeId } : {} } : {},
+      protocolVersion: result.protocolVersion,
+      ...info ? { agent: { ...info.name ? { name: info.name } : {}, ...info.title ? { title: info.title } : {}, ...info.version ? { version: info.version } : {} } } : {},
+      loadSession: Boolean(result.agentCapabilities?.loadSession),
+      mcpHttp: Boolean(result.agentCapabilities?.mcpCapabilities?.http),
+      authMethods: (result.authMethods ?? []).map((method) => method?.name ?? method?.id).filter(Boolean)
+    };
+  } finally {
+    await session.close();
+  }
+}
+export {
+  probeAcp
+};

package/packages/client/dist/antigravity-probe.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Probes Antigravity CLI for version, status and available models.
+ * @param {{ command?: string, args?: string[], env?: Record<string, string>, label?: string, id?: string, readOnlyMode?: 'instructions' | 'reject' }} [provider]
+ * @param {{ cwd?: string, timeoutMs?: number }} [options]
+ */
+export function probeAntigravity(provider?: {
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    label?: string;
+    id?: string;
+    readOnlyMode?: "instructions" | "reject";
+}, { cwd, timeoutMs }?: {
+    cwd?: string;
+    timeoutMs?: number;
+}): Promise<{
+    version: string;
+    agent: {
+        name: string;
+        title: string;
+        version: string;
+    };
+    models: {
+        id: any;
+        label: any;
+    }[];
+    currentModel: any;
+    modes: {
+        id: string;
+        label: string;
+        description: string;
+    }[];
+    currentMode: string;
+}>;