cueloop 0.1.0-alpha.49 → 0.1.0-alpha.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cueloop",
-  "version": "0.1.0-alpha.49",
+  "version": "0.1.0-alpha.50",
   "description": "Terminal review surface for coding agents: annotate plans and diffs, return a verdict, send structured feedback back",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -27,10 +27,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/adapters": "0.1.0-alpha.49",
-    "@cueloop/client": "0.1.0-alpha.49",
-    "@cueloop/daemon": "0.1.0-alpha.49",
-    "@cueloop/schema": "0.1.0-alpha.49"
+    "@cueloop/adapters": "0.1.0-alpha.50",
+    "@cueloop/client": "0.1.0-alpha.50",
+    "@cueloop/daemon": "0.1.0-alpha.50",
+    "@cueloop/schema": "0.1.0-alpha.50"
   },
   "engines": {
     "bun": ">=1.3.0"

package/src/main.ts

@@ -97,6 +97,10 @@ async function main(): Promise<number> {
       const { actionsCommand } = await import("./actions-command");
       return actionsCommand(argv.slice(1));
     }
+    case "refine": {
+      const { refineCommand } = await import("./refine-command");
+      return refineCommand(argv.slice(1));
+    }
     case "review":
       return reviewEntry(argv.slice(1));
     case "review-post": {
@@ -297,6 +301,7 @@ function printHelp(): void {
       "scripting:",
       "  cueloop session <verb> [flags]   script the daemon (create|get|list|wait|annotate|resolve|submit-revision)",
       "  cueloop actions list             list the quick-action vocabulary (for annotate --action)",
+      "  cueloop refine                   mine past reviews into a markdown report + writeback proposals",
       "  cueloop wake <id> [--harness codex --thread <id>]  resume the agent with the verdict (spawn detached)",
       "  cueloop review-post <id> <pr>    post a resolved session's verdict back to the PR",
       "  cueloop daemon                   run the daemon in the foreground",

package/src/refine-command.test.ts

@@ -0,0 +1,117 @@
+/** refine builds a corpus report from stored sessions and skips sessions it has already analyzed on a later run. */
+
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Annotation, ReviewSession, Verdict, VerdictKind } from "@cueloop/schema";
+import { SessionStore } from "@cueloop/daemon/store";
+import { reportsDir } from "@cueloop/daemon/paths";
+import { buildRefineReport, refineCommand } from "./refine-command";
+
+function tempHome(): string {
+  return mkdtempSync(join(tmpdir(), "cueloop-refine-home-"));
+}
+
+function annotation(quote: string, body: string): Annotation {
+  return {
+    id: `a_${quote}`,
+    kind: "comment",
+    anchor: { quote, prefix: "", suffix: "" },
+    body,
+    createdAt: "2026-08-20T10:00:00Z",
+  };
+}
+
+function verdict(kind: VerdictKind): Verdict {
+  return { kind, summary: "", feedback: "", resolvedAt: "2026-08-20T11:00:00Z" };
+}
+
+function session(
+  id: string,
+  overrides: Partial<ReviewSession> & { type?: ReviewSession["artifact"]["type"] } = {},
+): ReviewSession {
+  const { type, ...rest } = overrides;
+  return {
+    schemaVersion: "1",
+    id,
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: type ?? "plan", content: "", meta: {} },
+    revisions: [],
+    annotations: [],
+    verdict: null,
+    status: "pending",
+    createdAt: "2026-08-20T10:00:00Z",
+    ...rest,
+  };
+}
+
+describe("buildRefineReport", () => {
+  test("reports the analyzed and total counts, distributions, and annotations", () => {
+    // Arrange
+    const analyzed = [
+      session("ses_a", { verdict: verdict("approve"), status: "resolved" }),
+      session("ses_b", {
+        type: "diff",
+        verdict: verdict("request_changes"),
+        status: "resolved",
+        annotations: [annotation("skip tests", "please add a regression test")],
+      }),
+    ];
+
+    // Act
+    const markdown = buildRefineReport(analyzed, 3, "2026-08-26T00:00:00.000Z");
+
+    // Assert
+    expect(markdown).toContain("2 sessions analyzed (3 total).");
+    expect(markdown).toContain("- plan: 1");
+    expect(markdown).toContain("- diff: 1");
+    expect(markdown).toContain("- approve: 1");
+    expect(markdown).toContain("- request changes: 1");
+    expect(markdown).toContain("skip tests");
+    expect(markdown).toContain("please add a regression test");
+  });
+
+  test("notes when there are no reviewer annotations", () => {
+    // Act
+    const markdown = buildRefineReport([], 0, "2026-08-26T00:00:00.000Z");
+
+    // Assert
+    expect(markdown).toContain("0 sessions analyzed (0 total).");
+    expect(markdown).toContain("No reviewer annotations in the analyzed sessions.");
+  });
+});
+
+describe("refineCommand", () => {
+  test("writes a report, skips signal-free sessions, and consumes only resolved sessions", async () => {
+    // Arrange
+    const home = tempHome();
+    const store = new SessionStore(home);
+    store.upsert(session("ses_a", { verdict: verdict("approve"), status: "resolved" }));
+    store.upsert(
+      session("ses_b", {
+        verdict: verdict("request_changes"),
+        status: "resolved",
+        annotations: [annotation("wrong file", "this belongs in store.ts")],
+      }),
+    );
+    store.upsert(
+      session("ses_pending", { annotations: [annotation("open point", "still deciding")] }),
+    );
+    store.upsert(session("ses_empty"));
+    const reportPath = join(reportsDir(home), "report.md");
+
+    // Act
+    const firstCode = await refineCommand(["--home", home]);
+
+    // Assert
+    expect(firstCode).toBe(0);
+    expect(readFileSync(reportPath, "utf8")).toContain("3 sessions analyzed (4 total).");
+
+    // Act
+    await refineCommand(["--home", home]);
+
+    // Assert
+    expect(readFileSync(reportPath, "utf8")).toContain("1 sessions analyzed (4 total).");
+  });
+});

package/src/refine-command.ts

@@ -0,0 +1,241 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cueloopHome, reportsDir } from "@cueloop/daemon/paths";
+import { SessionStore } from "@cueloop/daemon/store";
+import {
+  LATEST_REPORT_FILENAME,
+  pruneExpiredReports,
+  resolveCleanupPeriodDays,
+  timestampedReportFilename,
+} from "@cueloop/daemon/retention";
+import { isAgentNote, type Annotation, type ReviewSession } from "@cueloop/schema";
+import { parseArgs, stringFlag } from "./args";
+
+const DEFAULT_SESSION_LIMIT = 200;
+const QUOTE_LIMIT = 60;
+const BODY_LIMIT = 100;
+
+interface AnnotatedEntry {
+  annotation: Annotation;
+  session: ReviewSession;
+}
+
+export async function refineCommand(argv: string[]): Promise<number> {
+  const { flags } = parseArgs(argv);
+  const home = stringFlag(flags, "home") ?? cueloopHome();
+  const limit = parseLimit(stringFlag(flags, "limit"));
+  const nowMs = Date.now();
+
+  const store = new SessionStore(home);
+  store.recover();
+  const all = store.list();
+
+  const seen = readSeen(home);
+  const fresh = all.filter((session) => !seen.has(session.id));
+  const analyzed = fresh.filter(hasReviewSignal).slice(0, limit);
+
+  const markdown = buildRefineReport(analyzed, all.length, new Date(nowMs).toISOString());
+
+  const directory = reportsDir(home);
+  mkdirSync(directory, { recursive: true });
+  pruneExpiredReports(directory, resolveCleanupPeriodDays(), nowMs);
+  const latestPath = join(directory, LATEST_REPORT_FILENAME);
+  const timestampedPath = join(directory, timestampedReportFilename(nowMs));
+  writeFileSync(latestPath, markdown);
+  writeFileSync(timestampedPath, markdown);
+
+  for (const session of analyzed) {
+    if (session.status === "resolved") seen.add(session.id);
+  }
+  writeSeen(home, seen);
+
+  console.log(
+    JSON.stringify(
+      {
+        report: latestPath,
+        timestamped: timestampedPath,
+        analyzed: analyzed.length,
+        total: all.length,
+      },
+      null,
+      2,
+    ),
+  );
+  return 0;
+}
+
+export function buildRefineReport(
+  analyzed: ReviewSession[],
+  totalCount: number,
+  generatedAt: string,
+): string {
+  const entries = flattenReviewAnnotations(analyzed);
+  const lines: string[] = [
+    "# refine report",
+    "",
+    `Generated ${generatedAt}.`,
+    "",
+    `${analyzed.length} sessions analyzed (${totalCount} total).`,
+    "",
+    "## Corpus",
+    "",
+    "By primitive:",
+    ...byCount(analyzed, primitiveLabel).map(([label, count]) => `- ${label}: ${count}`),
+    "",
+    "By verdict:",
+    ...byCount(analyzed, verdictLabel).map(([label, count]) => `- ${label}: ${count}`),
+    "",
+    "## Annotations by kind",
+    "",
+  ];
+
+  if (entries.length === 0) {
+    lines.push("No reviewer annotations in the analyzed sessions.", "");
+  } else {
+    for (const [kind, group] of groupByKind(entries)) {
+      lines.push(`### ${kind} (${group.length})`, "");
+      for (const { annotation, session } of group) {
+        const meta = [
+          session.id,
+          primitiveLabel(session),
+          verdictLabel(session),
+          isoWeek(annotation.createdAt),
+        ].join(" · ");
+        lines.push(
+          `- "${truncate(annotation.anchor.quote, QUOTE_LIMIT)}": ${truncate(annotation.body, BODY_LIMIT)} · ${meta}`,
+        );
+      }
+      lines.push("");
+    }
+  }
+
+  lines.push("## Weekly volume", "");
+  for (const [week, count] of byKey(
+    entries.map((entry) => entry.annotation),
+    (annotation) => isoWeek(annotation.createdAt),
+  )) {
+    lines.push(`- ${week}: ${count}`);
+  }
+  lines.push(
+    "",
+    "## Next",
+    "",
+    "Group the annotations above into named patterns of three or more members.",
+    "Rank each pattern by how often its members sit on a request-changes or comment verdict.",
+    "Draft one writeback per pattern, routed to a skill, AGENTS.md, CLAUDE.md, or memory.",
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+function hasReviewSignal(session: ReviewSession): boolean {
+  return (
+    session.verdict !== null || session.annotations.some((annotation) => !isAgentNote(annotation))
+  );
+}
+
+function flattenReviewAnnotations(sessions: ReviewSession[]): AnnotatedEntry[] {
+  const entries: AnnotatedEntry[] = [];
+  for (const session of sessions) {
+    for (const annotation of session.annotations) {
+      if (!isAgentNote(annotation)) entries.push({ annotation, session });
+    }
+  }
+  return entries;
+}
+
+function groupByKind(entries: AnnotatedEntry[]): [string, AnnotatedEntry[]][] {
+  const groups = new Map<string, AnnotatedEntry[]>();
+  for (const entry of entries) {
+    const group = groups.get(entry.annotation.kind) ?? [];
+    group.push(entry);
+    groups.set(entry.annotation.kind, group);
+  }
+  return [...groups.entries()].toSorted(
+    (left, right) => right[1].length - left[1].length || left[0].localeCompare(right[0]),
+  );
+}
+
+function byCount<T>(items: T[], keyOf: (item: T) => string): [string, number][] {
+  return [...tally(items, keyOf).entries()].toSorted(
+    (left, right) => right[1] - left[1] || left[0].localeCompare(right[0]),
+  );
+}
+
+function byKey<T>(items: T[], keyOf: (item: T) => string): [string, number][] {
+  return [...tally(items, keyOf).entries()].toSorted((left, right) =>
+    left[0].localeCompare(right[0]),
+  );
+}
+
+function tally<T>(items: T[], keyOf: (item: T) => string): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const item of items) {
+    const key = keyOf(item);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return counts;
+}
+
+function primitiveLabel(session: ReviewSession): string {
+  if (session.artifact.type === "diff" && session.artifact.meta.pr) return "pull request";
+  return session.artifact.type;
+}
+
+function verdictLabel(session: ReviewSession): string {
+  switch (session.verdict?.kind) {
+    case "approve":
+      return "approve";
+    case "request_changes":
+      return "request changes";
+    case "comment":
+      return "comment";
+    default:
+      return "none";
+  }
+}
+
+function isoWeek(iso: string): string {
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return "undated";
+  const utc = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+  const weekday = utc.getUTCDay() || 7;
+  utc.setUTCDate(utc.getUTCDate() + 4 - weekday);
+  const yearStart = new Date(Date.UTC(utc.getUTCFullYear(), 0, 1));
+  const week = Math.ceil(((utc.getTime() - yearStart.getTime()) / (24 * 60 * 60 * 1000) + 1) / 7);
+  return `${utc.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
+}
+
+function truncate(text: string, max: number): string {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  return collapsed.length > max ? `${collapsed.slice(0, max - 1)}…` : collapsed;
+}
+
+function parseLimit(raw: string | undefined): number {
+  const value = Number(raw);
+  return Number.isInteger(value) && value > 0 ? value : DEFAULT_SESSION_LIMIT;
+}
+
+interface RefineState {
+  seenSessionIds: string[];
+}
+
+function statePath(home: string): string {
+  return join(home, "refine-state.json");
+}
+
+function readSeen(home: string): Set<string> {
+  try {
+    const parsed = JSON.parse(readFileSync(statePath(home), "utf8")) as Partial<RefineState>;
+    const ids = Array.isArray(parsed.seenSessionIds) ? parsed.seenSessionIds : [];
+    return new Set(ids.filter((id): id is string => typeof id === "string"));
+  } catch {
+    return new Set();
+  }
+}
+
+function writeSeen(home: string, seen: Set<string>): void {
+  const state: RefineState = { seenSessionIds: [...seen] };
+  writeFileSync(statePath(home), JSON.stringify(state, null, 2));
+}