@staix/agent-hub 0.24.0 → 0.25.0

package/src/cli/study-output.ts

@@ -0,0 +1,71 @@
+// Human output for `ahub study draft|revise|approve|approve-protocol|close|show`. Pure: the hub's parsed JSON in, spans out, no I/O. `--json` is the caller's branch and prints the same text.
+// A campaign is named by ids, revisions, states and counts. The hub already stubs private campaigns, tasks and sources; this file never asks for a question, scope, path or excerpt.
+import { blank, grid, heading, pair, s } from "./sdlc-output.ts";
+import type { Span, Tone } from "./console-state.ts";
+
+const list = (value: unknown): any[] => Array.isArray(value) ? value : [];
+const count = (value: unknown): number => typeof value === "number" && Number.isFinite(value) ? value : 0;
+const STATUS_TONE: Record<string, Tone | undefined> = { approved: undefined, draft: "attention", superseded: "muted", closed: "muted" };
+
+/** `ahub study show` with no id: one page of campaigns of this project, with the command that continues it when the hub says there is more. */
+export function renderStudyList(page: unknown, columns?: number): Span[][] {
+  const campaigns = list((page as any)?.campaigns), next = typeof (page as any)?.next === "string" ? (page as any).next as string : undefined;
+  if (!campaigns.length) return [[s("no research campaigns in this project; a planner or you draft one with `ahub study draft <parent> <contract.json>`", "muted")]];
+  const out: Span[][] = [...heading(`Research campaigns (${campaigns.length}${next ? ", more follow" : ""})`, columns)];
+  out.push(...grid(["ID", "REV", "STATUS", "PARENT", "UNITS"], campaigns.map((row: any) => [
+    s(row.id, "issueRef"), s(`r${count(row.revision)}`), s(row.status, STATUS_TONE[row.status]), s(`#${count(row.parentTaskId)}`, "taskRef"), s(count(row.unitCount)),
+  ]), columns));
+  if (next) out.push(blank, [s(`more campaigns: ahub study show --after ${next}`, "muted")]);
+  return out;
+}
+
+const SUPPORT_TONE: Record<string, Tone | undefined> = { enforceable: undefined, supported: undefined, advisory: "muted", unavailable: "attention", unsupported: "attention", unknown: "attention" };
+
+/** `ahub study show <id>`: the coverage and stop projection the hub computed. Held work is said first, with every reason. */
+export function renderStudyShow(projection: unknown, columns?: number): Span[][] {
+  const p = projection as any, units = list(p?.units), rounds = list(p?.discoveryRounds), reasons = list(p?.reasons);
+  const out: Span[][] = [...heading(`Research campaign ${p?.id ?? "?"}, revision ${count(p?.revision)}${p?.held ? ", dispatch HELD" : ""}`, columns)];
+  for (const reason of reasons) out.push(...pair("held", reason, columns, 8, "attention"));
+  if (p?.sharedPeerLedger) out.push(...pair("budget", "one run ledger is shared by the peers", columns, 8, "muted"));
+  if (rounds.length) out.push(...pair("rounds", rounds.map((round: any) => `${count(round.round)}: ${round.complete ? "discovery complete" : "discovery open"}`).join(", "), columns, 8));
+  out.push(blank);
+  if (!units.length) return [...out, [s("no units", "muted")]];
+  out.push(...grid(["UNIT", "ROUND", "TASK", "STATE", "PURPOSE", "HANDOFF", "SOURCES"], units.map((unit: any) => {
+    const handoff = unit.handoff ?? {};
+    const evidence = handoff.insufficientEvidence ? "insufficient evidence" : handoff.complete ? "complete" : handoff.present ? "incomplete" : "none";
+    const covered = list(unit.sourceIds).length;
+    const note = [unit.intentionalIndependentCheck ? "independent check" : "", list(unit.duplicateSourceIds).length ? `${list(unit.duplicateSourceIds).length} duplicated` : ""].filter(Boolean).join(", ");
+    return [s(unit.unitId, "issueRef"), s(count(unit.round)), s(unit.taskId == null ? "-" : `#${unit.taskId}`, "taskRef"), s(unit.state), s(unit.purpose), s(evidence, handoff.complete || handoff.insufficientEvidence ? undefined : "attention"),
+      s(covered ? `${list(handoff.coveredSourceIds).length}/${covered} covered${note ? `, ${note}` : ""}` : note || "-", "muted")];
+  }), columns));
+  // Every resource of a unit is shown whenever the campaign names a budget, with its support state: a limit the ledger does not carry (`null`) is a placeholder, not a reason to hide a row that says
+  // `unavailable` or `advisory`. A campaign that names no budget has nothing to say (its `tokens` row reads `unavailable` whatever the ledger is), so the hub's `budgetNamed` decides, not the values.
+  const budgeted = units.flatMap((unit: any) => Object.entries(unit.budget ?? {}).filter(([, value]: [string, any]) => value && typeof value === "object").map(([name, value]: [string, any]) => ({ unit: unit.unitId, name, value })));
+  if (budgeted.length && p?.budgetNamed === true) {
+    out.push(blank, ...heading("Budget", columns));
+    out.push(...grid(["UNIT", "RESOURCE", "SUPPORT", "USED", "LIMIT"], budgeted.map(({ unit, name, value }) => [
+      s(unit, "issueRef"), s(name), s(value.support, SUPPORT_TONE[value.support]), s(value.used === null || value.used === undefined ? "-" : value.used), s(value.limit === null || value.limit === undefined ? "-" : value.limit),
+    ]), columns));
+  }
+  return out;
+}
+
+const VERB: Record<string, string> = { draft: "drafted", revise: "drafted as the next revision", approve: "approved", close: "closed" };
+
+/** The receipt of a draft, revision, approval or close. */
+export function renderStudyReceipt(op: string, receipt: unknown, columns?: number): Span[][] {
+  const r = receipt as any, units = list(r?.units);
+  if (op === "approve_protocol") {
+    const hash = (value: unknown) => typeof value === "string" && value.length === 64 && /^[a-f0-9]{64}$/.test(value) ? value : "unknown";
+    const by = typeof r?.approvedBy === "string" && /^[a-z][a-z0-9_-]{0,63}$/.test(r.approvedBy) ? r.approvedBy : "unknown";
+    const at = typeof r?.approvedAt === "number" && Number.isFinite(r.approvedAt) && r.approvedAt >= 0 && r.approvedAt <= 8_640_000_000_000_000
+      ? new Date(r.approvedAt).toISOString().slice(0, 19).replace("T", " ") + " UTC" : "unknown";
+    return [...heading("Research protocol approval", columns), ...pair("protocol hash", hash(r?.protocolHash), columns, 16),
+      ...pair("evaluator hash", hash(r?.evaluatorHash), columns, 16), ...pair("approved by", by, columns, 16), ...pair("approved at", at, columns, 16)];
+  }
+  const out: Span[][] = [...heading(`Research campaign ${r?.id ?? "?"} revision ${count(r?.revision)} ${VERB[op] ?? op}`, columns)];
+  out.push(...pair("status", r?.status, columns, 8, STATUS_TONE[r?.status]), ...pair("parent", `#${count(r?.parentTaskId)}`, columns, 8, "taskRef"), ...pair("units", count(r?.unitCount), columns, 8));
+  if (units.length) out.push(blank, ...grid(["UNIT", "TASK", "ROUND"], units.map((unit: any) => [s(unit.unitId, "issueRef"), s(`#${count(unit.taskId)}`, "taskRef"), s(count(unit.round))]), columns));
+  if (op === "draft" || op === "revise") out.push(blank, [s(`nothing is dispatched until you approve: ahub study approve ${r?.id} ${count(r?.revision)}`, "muted")]);
+  return out;
+}

package/src/cli/study.ts

@@ -0,0 +1,58 @@
+// Argument parsing for `ahub study` (#601). Pure: argv in, one request description or a usage line out, so the I/O in main.ts stays a thin dispatcher and every form is testable without a daemon.
+export const STUDY_USAGE = "usage: ahub study draft <parent> <contract.json> | revise <id> <revision> <contract.json> | approve <id> <revision> | approve-protocol <hash> | close <id> <revision> --reason <text> | show [<id> | --after <id>] [--json] [--color=auto|always|never]";
+
+export type StudyRequest =
+  | { op: "draft"; parentTaskId: number; file: string }
+  | { op: "revise"; id: string; revision: number; file: string }
+  | { op: "approve"; id: string; revision: number }
+  | { op: "approve_protocol"; hash: string }
+  | { op: "close"; id: string; revision: number; reason: string }
+  | { op: "show"; id?: string; after?: string };
+
+const ID = /^rc-[a-f0-9]{12}$/, INT = /^[1-9]\d{0,8}$/;
+
+/** `operands` is argv with the presentation flags (`--json`, `--color=`) already removed by `splitPresentation`. `--reason` takes the rest of the words, as `task cancel --reason` does. */
+export function parseStudyArgs(operands: readonly string[]): StudyRequest | { usage: string } {
+  const usage = (detail?: string) => ({ usage: detail ? `${detail}\n${STUDY_USAGE}` : STUDY_USAGE });
+  const [sub, ...rest] = operands;
+  const id = (value: string | undefined) => value !== undefined && ID.test(value) ? value : undefined;
+  const int = (value: string | undefined) => value !== undefined && INT.test(value) ? Number(value) : undefined;
+  if (sub === "approve-protocol") {
+    if (rest.length !== 1) return usage();
+    const hash = rest[0];
+    return hash?.length === 64 && /^[a-f0-9]{64}$/.test(hash) ? { op: "approve_protocol", hash } : usage("a protocol hash is 64 lowercase hexadecimal characters");
+  }
+  if (sub === "show") {
+    // `--after <id>` continues a list from the cursor a previous page printed; it has no meaning with an id, which shows one campaign.
+    if (rest[0] === "--after") {
+      if (rest.length !== 2) return usage();
+      return id(rest[1]) ? { op: "show", after: rest[1]! } : usage("a campaign id looks like rc-0123456789ab");
+    }
+    if (rest.length > 1) return usage();
+    if (rest[0] === undefined) return { op: "show" };
+    return id(rest[0]) ? { op: "show", id: rest[0] } : usage("a campaign id looks like rc-0123456789ab");
+  }
+  if (sub === "draft") {
+    const parent = int(rest[0]);
+    if (parent === undefined || !rest[1] || rest.length !== 2) return usage();
+    return { op: "draft", parentTaskId: parent, file: rest[1] };
+  }
+  if (sub === "revise") {
+    const revision = int(rest[1]);
+    if (!id(rest[0]) || revision === undefined || !rest[2] || rest.length !== 3) return usage();
+    return { op: "revise", id: rest[0]!, revision, file: rest[2] };
+  }
+  if (sub === "approve") {
+    const revision = int(rest[1]);
+    if (!id(rest[0]) || revision === undefined || rest.length !== 2) return usage();
+    return { op: "approve", id: rest[0]!, revision };
+  }
+  if (sub === "close") {
+    const revision = int(rest[1]);
+    const at = rest.indexOf("--reason");
+    if (!id(rest[0]) || revision === undefined || at !== 2) return usage();
+    const reason = rest.slice(at + 1).join(" ").trim();
+    return reason ? { op: "close", id: rest[0]!, revision, reason } : usage("study close needs a reason");
+  }
+  return usage();
+}

package/src/cli/task-output.ts

@@ -104,6 +104,7 @@ function taskBlock(task: any, columns: number | undefined, now: number, detail:
     ...pair("class", dash(task?.class), columns, w, undefined, "  "), ...pair("owner", taskHolderText(task, "owner"), columns, w, undefined, "  "), ...pair("reviewer", taskHolderText(task, "reviewer"), columns, w, undefined, "  "));
   if (task?.planner !== undefined) out.push(...pair("planner", taskHolderText(task, "planner"), columns, w, undefined, "  "));
   if (task?.reserved) out.push(...pair("reserved", task.reserved, columns, w, undefined, "  "));
+  if (task?.handoffOrigin) out.push(...pair("from", `project ${task.handoffOrigin.projectId}, handed off by ${task.handoffOrigin.peer}${typeof task.handoffOrigin.task === "number" ? ` (their task #${task.handoffOrigin.task})` : ""}`, columns, w, "attention", "  "));
   out.push(...pair("after", ids(task?.deps), columns, w, undefined, "  "));
   if (typeof task?.release === "number") out.push(...pair("release", `#${task.release}`, columns, w, undefined, "  "));
   if (typeof task?.rank === "number" || typeof task?.priority === "number") out.push(...pair("planning", [typeof task.rank === "number" ? `rank ${task.rank}` : "", typeof task.priority === "number" ? `priority P${task.priority}` : "", task.pinned ? "pinned" : ""].filter(Boolean).join(", "), columns, w, undefined, "  "));