@anhlp/alp 0.0.0-beta.1

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

@@ -0,0 +1,39 @@
+export function printer(json: any): (envelope: any) => void;
+/** Reads answers to questions for the user from the terminal, one question at a time. */
+export function answerer(client: any): {
+    accept(event: any): void;
+    close(): void;
+};
+/** Streams a tree until its root is idle; the first Ctrl-C interrupts it, the second detaches. */
+export function follow(client: any, rootId: any, print: any, { untilIdle, interactive }: {
+    untilIdle: any;
+    interactive?: boolean | undefined;
+}): Promise<any>;
+export function run(args: any): Promise<void>;
+export function ps(args: any): Promise<void>;
+export function attach(args: any): Promise<void>;
+/** Steers a running root, prompts an idle one, or resumes a closed one; then follows it until idle. */
+export function send(args: any): Promise<void>;
+export function questions(args: any): Promise<void>;
+export function answer(args: any): Promise<void>;
+/** One tree as text: sessions by depth, then questions, unmerged worktrees and leases. */
+export function renderStatus(status: any, root: any): string;
+/** A live dashboard of every tree, or of one, refreshed every second. */
+export function top(args: any): Promise<void>;
+/** The tree's assignment log: delegations, mail, handoffs, worktrees and questions to the user. */
+export function log(args: any): Promise<void>;
+/** The project board every agent on the project shares: live claims, then decisions and findings. */
+export function board(args: any): Promise<void>;
+export function printPauses({ all, runtimes, parked }: {
+    all: any;
+    runtimes: any;
+    parked: any;
+}, always?: boolean): void;
+/** alp pause: hold delegation and wakes on one runtime, or all; --now also parks running assignments. */
+export function pause(args: any): Promise<void>;
+/** alp resume: lift a pause; parked assignments continue where they stopped. */
+export function resume(args: any): Promise<void>;
+/** alp language: the language the user reads (ALPD §54); new sessions use it. */
+export function recall(args: any): Promise<void>;
+/** alp web: opens the web app alpd serves on 127.0.0.1, with the token in the address (ALPD §61). */
+export function interrupt(args: any): Promise<void>;

package/packages/cli/dist/sessions.js

@@ -0,0 +1,425 @@
+// packages/cli/src/sessions.js
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { parseArgs } from "node:util";
+import { ago, duration, renderLog, renderPs } from "@anhlp/alp-client/render";
+import { isTaskId } from "@anhlp/alp-core/tasks";
+import { connect } from "@anhlp/alp-client/index";
+import { UsageError } from "./usage.js";
+import { start, running, stop } from "./daemon.js";
+import { taskProject } from "./tasks.js";
+function printer(json) {
+  const depth = /* @__PURE__ */ new Map();
+  const agents = /* @__PURE__ */ new Map();
+  const printed = /* @__PURE__ */ new Set();
+  const latest = /* @__PURE__ */ new Map();
+  const line = (sessionId, text) => console.log(`${"  ".repeat(depth.get(sessionId) ?? 0)}${text}`);
+  return (envelope) => {
+    if (json) {
+      console.log(JSON.stringify(envelope));
+      return;
+    }
+    const { sessionId, event } = envelope;
+    if (event.type === "session.opened") {
+      const { session } = event;
+      depth.set(sessionId, session.parentId ? (depth.get(session.parentId) ?? 0) + 1 : 0);
+      agents.set(sessionId, session.agent);
+      line(sessionId, `\u25B8 ${session.agent} (${session.runtime}:${session.model}, ${session.mode}) ${sessionId}`);
+    } else if (event.type === "item") {
+      const { item } = event;
+      latest.set(item.id, { sessionId, item });
+      if (item.kind === "tool_call" && item.status !== "running" && !printed.has(item.id)) {
+        printed.add(item.id);
+        const detail = item.detail.type === "shell" ? item.detail.command : item.name === "alp_delegate" ? `delegate \u2192 ${item.detail.input?.agent}` : item.name;
+        line(sessionId, `  ${item.status === "failed" ? "\u2717" : "\u2713"} ${detail}`);
+      }
+      if (item.kind === "notice") line(sessionId, `  ${item.level === "error" ? "\u203C" : item.level === "warning" ? "!" : "\u2139"} ${item.text}`);
+      if (item.kind === "todo") {
+        line(sessionId, "  tasks:");
+        for (const entry of item.items) line(sessionId, `    ${entry.status === "completed" ? "\u2611" : entry.status === "in_progress" ? "\u25D0" : "\u2610"} ${entry.text}`);
+      }
+    } else if (event.type === "mail") {
+      line(sessionId, `  \u2709 ${event.mail.kind} from ${event.mail.from}`);
+    } else if (event.type === "question") {
+      const { question } = event;
+      line(sessionId, `  ? ${question.agent} asks you [${question.id}]: ${question.body}${question.options?.length ? ` (${question.options.join(" | ")})` : ""}`);
+      line(sessionId, `    answer here, or with: alp answer ${question.id} <text>`);
+    } else if (event.type === "question.resolved") {
+      line(sessionId, `  \u21B3 ${event.questionId} ${event.outcome}${event.answer !== void 0 ? `: ${event.answer}` : ""}`);
+    } else if (event.type === "turn.ended") {
+      for (const [id, entry] of latest) {
+        if (entry.sessionId !== sessionId || printed.has(id) || entry.item.kind !== "assistant_message") continue;
+        printed.add(id);
+        line(sessionId, `  ${agents.get(sessionId) ?? "agent"}: ${entry.item.text.replace(/\n/g, `
+${"  ".repeat((depth.get(sessionId) ?? 0) + 2)}`)}`);
+      }
+      if (event.state !== "completed") line(sessionId, `  turn ${event.state}${event.error ? `: ${event.error.message}` : ""}`);
+    } else if (event.type === "prompt.failed") {
+      line(sessionId, `  prompt failed: ${event.error.message}`);
+    } else if (event.type === "session.failed") {
+      line(sessionId, `  runtime failed: ${event.error.message}`);
+    }
+  };
+}
+function answerer(client) {
+  const waiting = [];
+  let rl;
+  const ask = () => {
+    if (rl || !waiting.length) return;
+    const question = waiting[0];
+    rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(`answer ${question.id}> `, (text) => {
+      rl.close();
+      rl = void 0;
+      waiting.shift();
+      if (text.trim()) client.request("question.answer", { questionId: question.id, text }).catch((error) => console.error(`alp: ${error.message}`));
+      ask();
+    });
+  };
+  return {
+    accept(event) {
+      if (event.type === "question") {
+        waiting.push(event.question);
+        ask();
+      }
+      if (event.type === "question.resolved") {
+        const index = waiting.findIndex((question) => question.id === event.questionId);
+        if (index === 0 && rl) {
+          rl.close();
+          rl = void 0;
+          console.error("");
+        }
+        if (index >= 0) waiting.splice(index, 1);
+        ask();
+      }
+    },
+    close() {
+      rl?.close();
+      rl = void 0;
+    }
+  };
+}
+function follow(client, rootId, print, { untilIdle, interactive = false }) {
+  const answering = interactive ? answerer(client) : void 0;
+  const done = new Promise((resolve, reject) => {
+    let failed = false;
+    let interrupted = false;
+    const finish = () => {
+      process.off("SIGINT", onSignal);
+      answering?.close();
+      resolve(!failed);
+    };
+    const onSignal = () => {
+      if (interrupted) {
+        finish();
+        return;
+      }
+      interrupted = true;
+      console.error("Interrupting\u2026 press Ctrl-C again to detach.");
+      client.request("session.interrupt", { sessionId: rootId }).catch(() => {
+      });
+    };
+    process.on("SIGINT", onSignal);
+    client.onClose((error) => {
+      process.off("SIGINT", onSignal);
+      reject(error);
+    });
+    let rootEnded = false;
+    client.onEvent((envelope) => {
+      print(envelope);
+      answering?.accept(envelope.event);
+      const { sessionId, event } = envelope;
+      if (event.type === "turn.ended") {
+        if (sessionId === rootId) {
+          failed = event.state !== "completed";
+          rootEnded = true;
+        }
+        if (!untilIdle || !rootEnded) return;
+        setTimeout(() => {
+          client.request("session.get", { sessionId: rootId }).then(({ session }) => {
+            if (!session.busy) finish();
+          }, finish);
+        }, 50);
+        return;
+      }
+      if (sessionId !== rootId) return;
+      if (event.type === "turn.started") {
+        rootEnded = false;
+      } else if (event.type === "session.closed" || event.type === "session.failed" || event.type === "prompt.failed") {
+        failed ||= event.type !== "session.closed";
+        finish();
+      }
+    });
+  });
+  done.catch(() => {
+  });
+  return done;
+}
+async function run(args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
+    agent: { type: "string" },
+    team: { type: "string" },
+    profile: { type: "string" },
+    workflow: { type: "string" },
+    model: { type: "string" },
+    mode: { type: "string" },
+    thinking: { type: "string" },
+    project: { type: "string" },
+    json: { type: "boolean" }
+  } });
+  const text = positionals.join(" ").trim();
+  if (!text) throw new UsageError();
+  const teams = [values.team, values.profile, values.workflow].filter(Boolean);
+  if (new Set(teams).size > 1) throw new UsageError();
+  const client = await connect(await start(), { name: "alp-cli", version: "1" });
+  try {
+    const spec = { cwd: path.resolve(values.project ?? process.cwd()), persist: true, agent: values.agent, workflow: teams[0], model: values.model, mode: values.mode, thinking: values.thinking };
+    const sessionId = `cli-${randomUUID()}`;
+    const done = follow(client, sessionId, printer(values.json), { untilIdle: true, interactive: !values.json && process.stdin.isTTY });
+    await client.request("session.create", { sessionId, spec });
+    await client.request("session.prompt", { sessionId, clientMessageId: randomUUID(), content: [{ type: "text", text }] });
+    if (!await done) process.exitCode = 1;
+    await client.request("session.release", { sessionId }).catch(() => {
+    });
+  } finally {
+    client.close();
+  }
+}
+async function ps(args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { all: { type: "boolean" } } });
+  if (positionals.length) throw new UsageError();
+  const client = await running();
+  const [{ sessions }, pauses] = await Promise.all([client.request("session.list", { includeClosed: values.all }), client.request("daemon.pauses")]).finally(() => client.close());
+  printPauses(pauses, false);
+  if (!sessions.length) {
+    console.log(values.all ? "No sessions" : "No live sessions");
+    return;
+  }
+  for (const line of renderPs(sessions)) console.log(line);
+}
+async function attach(args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { json: { type: "boolean" } } });
+  if (positionals.length !== 1) throw new UsageError();
+  const client = await running();
+  try {
+    const done = follow(client, positionals[0], printer(values.json), { untilIdle: false, interactive: !values.json && process.stdin.isTTY });
+    const { session } = await client.request("session.attach", { sessionId: positionals[0] });
+    if (session.id !== positionals[0]) console.error(`Following root ${session.id}`);
+    if (session.status === "idle" || session.status === "running") await done;
+    else console.error(`Session is ${session.lastError?.code ?? session.status}; resume it with: alp send ${session.id} <text>`);
+  } finally {
+    client.close();
+  }
+}
+async function send(args) {
+  const { values, positionals: [sessionId, ...words] } = parseArgs({ args, allowPositionals: true, options: { json: { type: "boolean" } } });
+  const text = words.join(" ").trim();
+  if (!sessionId || !text) throw new UsageError();
+  const client = await connect(await start(), { name: "alp-cli", version: "1" });
+  try {
+    const { session } = await client.request("session.get", { sessionId });
+    if (session.parentId) {
+      await client.request("session.message", { sessionId, text });
+      if (!values.json) console.error(`Sent to ${session.agent} as mail from the user`);
+      return;
+    }
+    const done = follow(client, sessionId, printer(values.json), { untilIdle: true, interactive: !values.json && process.stdin.isTTY });
+    const live = session.status === "idle" || session.status === "running";
+    if (live) await client.request("session.attach", { sessionId, replay: false });
+    else await client.request("session.create", { sessionId, spec: { cwd: session.projectRoot } });
+    const steer = live && !!session.activeTurnId;
+    await client.request("session.prompt", { sessionId, clientMessageId: randomUUID(), delivery: steer ? "steer" : "auto", content: [{ type: "text", text }] });
+    if (!values.json) console.error(steer ? "Steered the running turn" : live ? "Started a turn" : "Resumed the session");
+    if (!await done) process.exitCode = 1;
+    await client.request("session.release", { sessionId }).catch(() => {
+    });
+  } finally {
+    client.close();
+  }
+}
+async function questions(args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { json: { type: "boolean" } } });
+  if (positionals.length) throw new UsageError();
+  const client = await running();
+  const { questions: pending } = await client.request("question.list").finally(() => client.close());
+  if (values.json) {
+    console.log(JSON.stringify(pending));
+    return;
+  }
+  if (!pending.length) {
+    console.log("No questions wait for you");
+    return;
+  }
+  for (const question of pending) {
+    console.log(`${question.id}  ${question.agent}  ${ago(question.askedAt)} ago  root ${question.rootId}`);
+    console.log(`  ${question.body.replace(/\n/g, "\n  ")}`);
+    if (question.options?.length) console.log(`  options: ${question.options.join(" | ")}`);
+  }
+}
+async function answer(args) {
+  const { values, positionals: [questionId, ...words] } = parseArgs({ args, allowPositionals: true, options: { dismiss: { type: "boolean" }, reason: { type: "string" } } });
+  const text = words.join(" ").trim();
+  if (!questionId || (values.dismiss ? text : !text)) throw new UsageError();
+  const client = await running();
+  const result = await client.request("question.answer", values.dismiss ? { questionId, dismiss: true, reason: values.reason } : { questionId, text }).finally(() => client.close());
+  console.log(`${values.dismiss ? "Dismissed" : "Answered"} ${result.questionId}`);
+}
+function renderStatus(status, root) {
+  const lines = [`${root?.title ? `"${root.title}"  ` : ""}${status.rootId}  ${status.sessions[0]?.projectRoot ?? ""}`];
+  const depth = /* @__PURE__ */ new Map();
+  const assignments = new Map(status.assignments.map((assignment) => [assignment.id, assignment]));
+  for (const session of status.sessions) {
+    depth.set(session.id, session.parentId ? (depth.get(session.parentId) ?? 0) + 1 : 0);
+    const assignment = assignments.get(session.id);
+    const where = assignment?.worktree ? `  worktree ${assignment.worktree.branch}` : "";
+    const mail = session.unreadMail ? `  \u2709${session.unreadMail}` : "";
+    lines.push(`${"  ".repeat(depth.get(session.id) + 1)}${session.agent.padEnd(9)} ${session.state.padEnd(14)} idle ${duration(session.idleMs).padEnd(7)} ${session.runtime}:${session.model}  ${session.mode}${where}${mail}`);
+  }
+  for (const question of status.questions) lines.push(`  ? ${question.id} ${question.agent} asks (${ago(question.askedAt)}): ${question.body.split("\n")[0]}`);
+  for (const worktree of status.worktrees) lines.push(`  \u2387 unmerged ${worktree.branch} from ${worktree.agent}: ${worktree.files.length} files${worktree.stat ? ` (${worktree.stat.trim()})` : ""}`);
+  for (const lease of status.leases) lines.push(`  \u26BF ${lease.agent} holds the write lease on ${lease.checkout}`);
+  for (const claim of status.claims ?? []) lines.push(`  \u2691 ${claim.agent} claims ${claim.paths.join(", ")}${claim.task ? ` for ${claim.task}` : ""}: ${claim.body.split("\n")[0].slice(0, 100)}`);
+  return lines.join("\n");
+}
+async function top(args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { once: { type: "boolean" } } });
+  if (positionals.length > 1) throw new UsageError();
+  const client = await running();
+  const frame = async () => {
+    const { sessions } = await client.request("session.list", { rootsOnly: true });
+    const roots = positionals.length ? sessions.filter((session) => session.id === positionals[0]) : sessions;
+    if (positionals.length && !roots.length) throw new Error(`Session ${positionals[0]} is not a live root`);
+    const blocks = [];
+    for (const root of roots) {
+      const { status } = await client.request("session.status", { sessionId: root.id }).catch(() => ({}));
+      if (status) blocks.push(renderStatus(status, root));
+    }
+    return `alp top  ${(/* @__PURE__ */ new Date()).toLocaleTimeString()}  ${roots.length} live ${roots.length === 1 ? "tree" : "trees"}
+
+${blocks.join("\n\n") || "No live sessions"}`;
+  };
+  try {
+    if (values.once || !process.stdout.isTTY) {
+      console.log(await frame());
+      return;
+    }
+    let stop2 = false;
+    process.once("SIGINT", () => {
+      stop2 = true;
+    });
+    while (!stop2) {
+      const text = await frame();
+      process.stdout.write(`\x1B[2J\x1B[H${text}
+
+(Ctrl-C to exit)
+`);
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+    }
+  } finally {
+    client.close();
+  }
+}
+async function log(args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { json: { type: "boolean" } } });
+  if (positionals.length !== 1) throw new UsageError();
+  const client = await running();
+  const { rootId, entries } = await client.request("session.log", { sessionId: positionals[0] }).finally(() => client.close());
+  if (values.json) {
+    for (const entry of entries) console.log(JSON.stringify(entry));
+    return;
+  }
+  if (!entries.length) {
+    console.log(`No assignment log for ${rootId}`);
+    return;
+  }
+  for (const line of renderLog(rootId, entries)) console.log(line);
+}
+async function board(args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { project: { type: "string" }, json: { type: "boolean" } } });
+  if (positionals.length) throw new UsageError();
+  const projectRoot = path.resolve(values.project ?? process.cwd());
+  const client = await running();
+  const { pins } = await client.request("board.list", { projectRoot }).finally(() => client.close());
+  if (values.json) {
+    console.log(JSON.stringify(pins));
+    return;
+  }
+  if (!pins.length) {
+    console.log(`The board for ${projectRoot} is empty`);
+    return;
+  }
+  console.log(`Project board  ${projectRoot}`);
+  for (const pin of pins) {
+    const mark = pin.kind === "claim" ? "\u2691" : pin.kind === "decision" ? "\u25C6" : "\u2022";
+    console.log(`${mark} ${pin.kind.padEnd(8)} ${pin.id}  ${pin.agent}  ${ago(pin.at)} ago${pin.paths ? `  [${pin.paths.join(", ")}]` : ""}`);
+    console.log(`  ${pin.body.replace(/\n/g, "\n  ")}`);
+  }
+}
+function printPauses({ all, runtimes, parked }, always = true) {
+  const line = (name, pause2) => console.log(`\u23F8 ${name} paused since ${pause2.since.slice(0, 16).replace("T", " ")} by ${pause2.by}: ${pause2.reason}${pause2.resetsAt ? `; the limit resets ${pause2.resetsAt}` : ""}${pause2.checkedAt ? `; ${name} last asked ${ago(pause2.checkedAt)} ago` : ""}`);
+  if (all) line("ALP", all);
+  for (const [kind, pause2] of Object.entries(runtimes)) line(kind, pause2);
+  for (const entry of parked) console.log(`  parked ${entry.agent} ${entry.assignmentId} (${entry.runtime}): ${entry.reason}`);
+  if (always && !all && !Object.keys(runtimes).length) console.log("Nothing is paused");
+}
+async function pause(args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { now: { type: "boolean" }, message: { type: "string", short: "m" }, json: { type: "boolean" } } });
+  if (positionals.length > 1 || positionals[0] && !["codex", "claude", "status"].includes(positionals[0])) throw new UsageError();
+  const client = await running();
+  const state = await (positionals[0] === "status" ? client.request("daemon.pauses") : client.request("daemon.pause", { ...positionals[0] ? { runtime: positionals[0] } : {}, now: !!values.now, ...values.message ? { reason: values.message } : {} })).finally(() => client.close());
+  if (values.json) console.log(JSON.stringify(state));
+  else printPauses(state);
+}
+async function resume(args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { json: { type: "boolean" } } });
+  if (positionals.length > 1 || positionals[0] && !["codex", "claude"].includes(positionals[0])) throw new UsageError();
+  const client = await running();
+  const state = await client.request("daemon.resume", positionals[0] ? { runtime: positionals[0] } : {}).finally(() => client.close());
+  if (values.json) console.log(JSON.stringify(state));
+  else printPauses(state);
+}
+async function recall(args) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { project: { type: "string" }, json: { type: "boolean" } } });
+  const [target, ...words] = positionals;
+  const question = words.join(" ").trim();
+  if (!target || !question) throw new UsageError();
+  const byTask = isTaskId(target);
+  const client = await running();
+  const answer2 = await client.request("assignment.recall", {
+    ...byTask ? { taskId: target, projectRoot: await taskProject(values.project) } : { assignmentId: target },
+    question
+  }).finally(() => client.close());
+  if (values.json) {
+    console.log(JSON.stringify(answer2));
+    return;
+  }
+  console.log(`${answer2.agent} (assignment ${answer2.assignmentId}${answer2.taskId ? `, task ${answer2.taskId}` : ""}, finished ${ago(answer2.finishedAt)} ago):`);
+  console.log(answer2.answer);
+}
+async function interrupt(args) {
+  if (args.length !== 1) throw new UsageError();
+  const client = await running();
+  await client.request("session.interrupt", { sessionId: args[0] }).finally(() => client.close());
+  console.log("Interrupted");
+}
+export {
+  answer,
+  answerer,
+  attach,
+  board,
+  follow,
+  interrupt,
+  log,
+  pause,
+  printPauses,
+  printer,
+  ps,
+  questions,
+  recall,
+  renderStatus,
+  resume,
+  run,
+  send,
+  top
+};

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

@@ -0,0 +1,29 @@
+export namespace STATUS_MARK {
+    let open: string;
+    let in_progress: string;
+    let review: string;
+    let closed: string;
+}
+/** The ALP project a task command works on: --project, or the current directory. */
+/** alp permissions: the profile each agent runs with, from .alp/settings.json and $ALP_HOME/settings.json. */
+export function taskProject(directory: any): Promise<string>;
+export function taskRow(task: any, tasks: any): string;
+export function warnUnreadable(errors: any): void;
+/** The project's tasks: open, in progress and in review by default; ready lists what nothing blocks. */
+export function tasksCommand(args: any): Promise<void>;
+/** The GitHub CLI, for gh:pr and gh:run gates. */
+export function gh(args: any, { cwd }: {
+    cwd: any;
+}): Promise<any>;
+/** alp tasks gates: clears GitHub gates that are done and lists the open ones. alp tasks compact: shrinks old closed tasks. */
+export function taskMaintenance([command]: [any], args: any): Promise<void>;
+/** alp tasks export / import: interchange with beads through its JSONL issue format. */
+export function beads(command: any, args: any): Promise<void>;
+/** alp formula: workflow templates that pour into an epic with a task per step. */
+export function formulaCommand([action, ...args]: [any, ...any[]]): Promise<void>;
+export namespace repeated {
+    let type: string;
+    let multiple: boolean;
+}
+export function taskCommand([action, ...args]: [any, ...any[]]): Promise<void>;
+export function printTask(task: any, tasks: any): void;