@hypercarrier/rarebit 0.1.0-alpha.6 → 0.2.1

package/test/rarebit-v020.test.mjs

@@ -0,0 +1,299 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import {
+  DEFAULT_RAREBIT_SUMMARY_PROMPT_GUIDANCE,
+  RAREBIT_SUMMARY_PROMPT_VERSION,
+  composeRarebitSummaryDerivationInput,
+  composeRarebitSummaryPrompt,
+  normalizeRarebitSummaryPrompt,
+  rarebitJobIdentity,
+  selectRarebits,
+  sha256,
+} from "../src/rarebit-core.mjs";
+import { processRarebitSummary } from "../src/rarebit-service.mjs";
+import { extractRarebitSynthesisReceipt } from "../src/rarebit-model.mjs";
+import { resolveRarebitSettings } from "../src/rarebit-settings.mjs";
+import {
+  RAREBIT_SETTINGS_FIELDS,
+  readRarebitSettingsDocument,
+  saveRarebitSettingsDocument,
+} from "../src/rarebit-settings-ui.mjs";
+import {
+  createRarebitRecapController,
+  RAREBIT_RECAP_WIDGET_KEY,
+} from "../src/rarebit-recap.mjs";
+
+const entry = (id, message) => ({
+  type: "message",
+  id,
+  timestamp: "2026-09-27T00:00:00.000Z",
+  message,
+});
+
+function branch() {
+  return [
+    entry("u1", { role: "user", content: "Investigate the deployment issue." }),
+    entry("a1", { role: "assistant", stopReason: "stop", content: "I found the failing check." }),
+  ];
+}
+
+async function fixture() {
+  const root = await mkdtemp(join(tmpdir(), "rarebit-v020-prompt-"));
+  await mkdir(join(root, "agent"), { recursive: true });
+  await writeFile(join(root, "agent", "settings.json"), "{}\n");
+  const sessionRoot = join(root, "sessions");
+  const rarebitRoot = join(root, "rarebit");
+  await mkdir(sessionRoot, { recursive: true });
+  const sessionFile = join(sessionRoot, "trace.jsonl");
+  await writeFile(sessionFile, '{"type":"session","id":"prompt-contract"}\n');
+  return { root, sessionRoot, rarebitRoot, sessionFile };
+}
+
+function recapContext(summary, setWidget) {
+  const branch = [
+    entry("recap-u", { role: "user", content: "Read the current deployment state." }),
+    entry("recap-a", { role: "assistant", stopReason: "stop", content: "The deployment is complete." }),
+  ];
+  const selection = selectRarebits(branch);
+  const observedAt = "2026-09-27T00:00:00.000Z";
+  const model = { provider: "fixture", id: "summary" };
+  const receipt = {
+    schemaVersion: 4, type: "rarebit_summary", status: "ok", jobId: sha256("recap-v020-job"),
+    sessionId: "recap-v020-session",
+    branch: { leafId: "recap-a", entryCount: branch.length, pathHash: sha256(branch.map((item) => item.id)) },
+    selection: { manifestHash: selection.manifestHash, selectorVersion: selection.manifest.selectorVersion,
+      occurrenceCount: selection.occurrences.length, uniquePayloadCount: selection.payloads.length,
+      latestUserSourceEntryId: "recap-u" },
+    sessionStatus: "finished", statusReason: "all_requests_accomplished", observedAt, summary,
+    lifecycleBoundary: "agent_settled", implementationVersion: "hc-rarebit-summary-v7", synthesisMode: "forced",
+    inputCoveragePolicy: { strategy: "newest_suffix_with_explicit_omission", maxPromptChars: 10_000 },
+    promptVersion: "rarebit-summary-v8", model, modelProvenance: { source: "test", status: "resolved" },
+    inputCoverage: { totalMessageCount: selection.occurrences.length, includedMessageCount: selection.occurrences.length,
+      omittedMessageCount: 0, omittedTextChars: 0, promptChars: 500, complete: true },
+    synthesis: extractRarebitSynthesisReceipt({}, { requestedModel: model, startedAt: observedAt, completedAt: observedAt, durationMs: 0 }),
+  };
+  return {
+    ctx: {
+      mode: "tui",
+      hasUI: true,
+      ui: { setWidget },
+      sessionManager: {
+        getHeader: () => ({ id: receipt.sessionId }),
+        getSessionFile: () => "/tmp/rarebit-v020-recap-session.jsonl",
+        getBranch: () => branch,
+      },
+    },
+    current: {
+      receipt,
+      artifactState: {
+        syncState: "assessment_current",
+        applicability: "exact_selection",
+        receiptRef: { jobId: receipt.jobId },
+        projection: { status: receipt.sessionStatus },
+      },
+    },
+  };
+}
+
+test("the default summary prompt keeps the current style and has no custom identity", () => {
+  const selection = selectRarebits(branch());
+  const normalized = normalizeRarebitSummaryPrompt();
+  const derivation = composeRarebitSummaryDerivationInput(selection);
+
+  assert.equal(normalized.guidance, DEFAULT_RAREBIT_SUMMARY_PROMPT_GUIDANCE);
+  assert.equal(normalized.promptIdentity, null);
+  assert.equal(derivation.promptIdentity, null);
+  assert.match(derivation.prompt, new RegExp(DEFAULT_RAREBIT_SUMMARY_PROMPT_GUIDANCE));
+  assert.equal(derivation.prompt, composeRarebitSummaryPrompt(selection));
+});
+
+test("a custom summary_prompt changes prose and job identity", () => {
+  const selection = selectRarebits(branch());
+  const summaryPrompt = "Use short factual bullets and state uncertainty.";
+  const normalized = normalizeRarebitSummaryPrompt(summaryPrompt);
+  const custom = composeRarebitSummaryDerivationInput(selection, { summaryPrompt });
+  const defaultIdentity = rarebitJobIdentity({
+    operation: "summary",
+    sessionId: "prompt-contract",
+    branch: { leafId: "a1", entryCount: 2, pathHash: "path" },
+    selection,
+    promptVersion: RAREBIT_SUMMARY_PROMPT_VERSION,
+    promptIdentity: null,
+  });
+  const customIdentity = rarebitJobIdentity({
+    operation: "summary",
+    sessionId: "prompt-contract",
+    branch: { leafId: "a1", entryCount: 2, pathHash: "path" },
+    selection,
+    promptVersion: RAREBIT_SUMMARY_PROMPT_VERSION,
+    promptIdentity: custom.promptIdentity,
+  });
+
+  assert.equal(normalized.promptIdentity, custom.promptIdentity);
+  assert.ok(custom.promptIdentity);
+  assert.match(custom.prompt, /Use short factual bullets and state uncertainty/);
+  assert.notEqual(custom.prompt, composeRarebitSummaryPrompt(selection));
+  assert.notEqual(customIdentity, defaultIdentity);
+});
+
+test("summary_prompt accepts only a nonblank scalar string", () => {
+  assert.throws(() => normalizeRarebitSummaryPrompt({ guidance: "custom" }), /summary_prompt/);
+  assert.throws(() => normalizeRarebitSummaryPrompt("   "), /summary_prompt/);
+  assert.throws(() => normalizeRarebitSummaryPrompt(42), /summary_prompt/);
+});
+
+test("settings resolve and round-trip the scalar summary_prompt without changing other namespaces", async () => {
+  const f = await fixture();
+  await writeFile(f.root + "/agent/settings.json", JSON.stringify({
+    theme: "dark",
+    other_extension: { keep: true },
+    rarebit: { model: "fixture/summary", summary_prompt: "Use an incident timeline." },
+  }, null, 2));
+  const resolved = resolveRarebitSettings({
+    rarebit: { model: "fixture/summary", summary_prompt: "Use an incident timeline." },
+  });
+  assert.equal(resolved.summaryPrompt, "Use an incident timeline.");
+  assert.equal(
+    RAREBIT_SETTINGS_FIELDS.some((field) => field.path?.join(".") === "summary_prompt"),
+    true,
+  );
+
+  const document = await readRarebitSettingsDocument({ agentDir: f.root + "/agent" });
+  await saveRarebitSettingsDocument(document, {
+    ...document.namespace,
+    summary_prompt: "Use an incident timeline with explicit uncertainty.",
+  });
+  const saved = JSON.parse(await readFile(f.root + "/agent/settings.json", "utf8"));
+  assert.equal(saved.theme, "dark");
+  assert.deepEqual(saved.other_extension, { keep: true });
+  assert.equal(saved.rarebit.summary_prompt, "Use an incident timeline with explicit uncertainty.");
+});
+
+test("invalid summary_prompt input fails before the provider or durable receipt", async () => {
+  const f = await fixture();
+  const calls = [];
+  const ctx = {
+    sessionManager: {
+      getHeader: () => ({ id: "prompt-contract" }),
+      getSessionFile: () => f.sessionFile,
+      getBranch: branch,
+    },
+  };
+
+  await assert.rejects(
+    processRarebitSummary(ctx, {
+      sessionRoot: f.sessionRoot,
+      rarebitRoot: f.rarebitRoot,
+      forceSynthesis: true,
+      model: { provider: "fixture", id: "summary" },
+      summaryPrompt: { guidance: "   " },
+      modelClient: { complete: async (request) => { calls.push(request); return "{}"; } },
+    }),
+    /summary_prompt/,
+  );
+  assert.equal(calls.length, 0);
+});
+
+test("custom summary_prompt reaches the provider and prevents reuse of the default receipt", async () => {
+  const f = await fixture();
+  const requests = [];
+  const ctx = {
+    sessionManager: {
+      getHeader: () => ({ id: "prompt-contract" }),
+      getSessionFile: () => f.sessionFile,
+      getBranch: branch,
+    },
+  };
+  const common = {
+    sessionRoot: f.sessionRoot,
+    rarebitRoot: f.rarebitRoot,
+    forceSynthesis: true,
+    model: { provider: "fixture", id: "summary" },
+    modelClient: {
+      complete: async (request) => {
+        requests.push(request);
+        return {
+          text: JSON.stringify({
+            summary: "The deployment issue is recorded.",
+            sessionStatus: "finished",
+            statusReason: "all_requests_accomplished",
+          }),
+        };
+      },
+    },
+  };
+  const first = await processRarebitSummary(ctx, common);
+  const second = await processRarebitSummary(ctx, {
+    ...common,
+    summaryPrompt: "Use a terse incident report with explicit uncertainty.",
+  });
+
+  assert.equal(first.record.status, "ok");
+  assert.equal(second.record.status, "ok");
+  assert.equal(requests.length, 2);
+  assert.doesNotMatch(requests[0].prompt, /terse incident report/);
+  assert.match(requests[1].prompt, /terse incident report/);
+  assert.notEqual(first.record.jobId, second.record.jobId);
+});
+
+test("Recap renders the full multiline Summary through a themed human-only widget", async () => {
+  const summary = Array.from({ length: 24 }, (_, index) => `line-${index + 1} FULL_RECAP_TAIL_${index + 1}`).join("\n");
+  const widgets = [];
+  const { ctx, current } = recapContext(summary, (...args) => widgets.push(args));
+  let modelCalls = 0;
+  let sessionWrites = 0;
+  const controller = createRarebitRecapController({
+    readCurrent: async () => current,
+  });
+
+  const shown = await controller.showExisting({
+    ...ctx,
+    modelClient: { complete: async () => { modelCalls += 1; } },
+    sessionManager: {
+      ...ctx.sessionManager,
+      appendMessage: () => { sessionWrites += 1; },
+    },
+  });
+  assert.equal(shown.shown, true);
+  assert.equal(widgets[0][0], RAREBIT_RECAP_WIDGET_KEY);
+  assert.equal(typeof widgets[0][1], "function");
+
+  const themed = widgets[0][1]({}, {
+    bold: (value) => value,
+    fg: (tone, value) => `[${tone}]${value}`,
+  });
+  const rendered = themed.render(200).join("\n");
+  assert.match(rendered, /Recap/);
+  assert.match(rendered, /line-1 FULL_RECAP_TAIL_1/);
+  assert.match(rendered, /line-24 FULL_RECAP_TAIL_24/);
+  assert.doesNotMatch(rendered, /recap expand/i);
+  assert.match(rendered, /\[muted\]|\[dim\]/);
+  assert.equal(modelCalls, 0);
+  assert.equal(sessionWrites, 0);
+
+  const refreshed = widgets[0][1]({}, {
+    bold: (value) => value,
+    fg: (tone, value) => `{${tone}}${value}`,
+  });
+  assert.match(refreshed.render(200).join("\n"), /\{muted\}|\{dim\}/);
+});
+
+test("Recap drops an async display when the Session changes before the widget factory resolves", async () => {
+  const widgets = [];
+  const first = recapContext("first Summary", (...args) => widgets.push(args));
+  const second = recapContext("second Summary", (...args) => widgets.push(args));
+  let releaseRead;
+  const readCurrent = new Promise((resolve) => { releaseRead = resolve; });
+  const controller = createRarebitRecapController({ readCurrent: async () => readCurrent });
+  const pending = controller.showExisting(first.ctx);
+  controller.invalidate(second.ctx, 2);
+  releaseRead(first.current);
+  const result = await pending;
+  assert.equal(result.shown, false);
+  assert.equal(result.reason, "stale");
+  assert.equal(widgets.some((call) => call[0] === RAREBIT_RECAP_WIDGET_KEY && call[1]), false);
+});

package/test/recap-read-checkpoint.test.mjs

@@ -0,0 +1,126 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { createRarebitRecapController } from "../src/rarebit-recap.mjs";
+import { recapIsRead, recapReadCheckpoint } from "../src/rarebit-read-checkpoint.mjs";
+import { selectRarebits, composeRarebitSummaryDerivationInput, sha256 } from "../src/rarebit-core.mjs";
+import { extractRarebitSynthesisReceipt } from "../src/rarebit-model.mjs";
+import { processRarebitSummary } from "../src/rarebit-service.mjs";
+
+test("read validation uses native-entry chronology when non-Rarebit records separate occurrences", () => {
+  const entries = [
+    { id: "u1", type: "message", message: { role: "user", content: "first" } },
+    { id: "tool", type: "message", message: { role: "toolResult", content: "ignored" } },
+    { id: "u2", type: "message", message: { role: "user", content: "second" } },
+  ];
+  const selection = selectRarebits(entries);
+  const hash = selectRarebits(entries).manifestHash;
+  const branch = [...entries,
+    { id: "recap", type: "custom", customType: "rarebit-recap", data: { version: 1, jobId: "job", coveredEntryId: "u2", selectionHash: hash } },
+    { id: "read", type: "custom", customType: "rarebit-recap-read", data: { version: 1, recapEntryId: "recap", jobId: "job", coveredEntryId: "u2", selectionHash: hash } },
+  ];
+  assert.equal(recapReadCheckpoint(branch, selection).coveredEntryId, "u2");
+});
+
+test("forged and out-of-order read markers do not acknowledge a Recap", () => {
+  const evidence = { id: "u", type: "message", message: { role: "user", content: "request" } };
+  const selection = selectRarebits([evidence]);
+  const recap = { id: "recap", type: "custom", customType: "rarebit-recap", data: {
+    version: 1, jobId: "job", coveredEntryId: "u", selectionHash: selection.manifestHash,
+  } };
+  const invalid = [
+    { ...recap, id: "read", customType: "rarebit-recap-read", data: { ...recap.data, recapEntryId: "recap" } },
+    evidence,
+    recap,
+  ];
+  assert.equal(recapIsRead(invalid, recap), false);
+  assert.equal(recapReadCheckpoint(invalid, selection), null);
+});
+
+test("scrollable Recap persists read coverage across resume without acknowledging later updates", async () => {
+  const root = await mkdtemp(join(tmpdir(), "rarebit-read-test-"));
+  try {
+    const manager = SessionManager.create(root, root);
+    manager.appendMessage({ role: "user", content: "Synthetic request: repair the renderer", timestamp: 1 });
+    manager.appendMessage({ role: "assistant", content: [{ type: "text", text: "Renderer repaired. Approval still required." }],
+      stopReason: "stop", api: "openai-completions", provider: "fixture", model: "fixture", timestamp: 2,
+      usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } } });
+    const selection = selectRarebits(manager.getBranch());
+    const observedAt = "1970-01-01T00:00:00.000Z";
+    const latestUser = selection.occurrences.filter((item) => item.role === "user").at(-1);
+    const receipt = {
+      schemaVersion: 4, type: "rarebit_summary", status: "ok", jobId: sha256("synthetic-recap"),
+      sessionId: manager.getHeader().id,
+      branch: { leafId: manager.getBranch().at(-1).id, entryCount: manager.getBranch().length, pathHash: sha256(manager.getBranch().map((item) => item.id)) },
+      observedAt, selection: { manifestHash: selection.manifestHash, selectorVersion: selection.manifest.selectorVersion,
+        occurrenceCount: selection.occurrences.length, uniquePayloadCount: selection.payloads.length, latestUserSourceEntryId: latestUser.sourceEntryId },
+      lifecycleBoundary: "agent_settled", implementationVersion: "hc-rarebit-summary-v7", synthesisMode: "forced",
+      inputCoveragePolicy: { strategy: "newest_suffix_with_explicit_omission", maxPromptChars: 10_000 },
+      promptVersion: "rarebit-summary-v8", model: { provider: "fixture", id: "summary" },
+      modelProvenance: { source: "test", status: "resolved" },
+      summary: "🧪界 Renderer repaired; approval needed.", sessionStatus: "needs_attention", statusReason: "approval",
+      inputCoverage: { totalMessageCount: selection.occurrences.length, includedMessageCount: selection.occurrences.length,
+        omittedMessageCount: 0, omittedTextChars: 0, promptChars: 100, complete: true },
+      synthesis: extractRarebitSynthesisReceipt({}, { requestedModel: { provider: "fixture", id: "summary" },
+        startedAt: observedAt, completedAt: observedAt, durationMs: 0 }),
+    };
+    const widgets = [];
+    const ctx = { mode: "tui", ui: { setWidget: (...args) => widgets.push(args) }, sessionManager: manager };
+    const controller = createRarebitRecapController({
+      appendEntry: (type, data) => manager.appendCustomEntry(type, data),
+      readCurrent: async () => ({ receipt, artifactState: { syncState: "assessment_current", applicability: "exact_selection",
+        receiptRef: { jobId: receipt.jobId }, projection: { status: receipt.sessionStatus } } }),
+    });
+    assert.equal((await controller.showExisting(ctx)).shown, true);
+    assert.ok(!widgets.some(([, content]) => content), "no pinned recap widget");
+    const recap = manager.getBranch().at(-1);
+    const component = controller.renderEntry(recap, {}, { fg: (_color, text) => text });
+    const wideRender = component.render(80);
+    assert.match(wideRender.join("\n"), /🧪界 Renderer repaired; approval needed/);
+    assert.match(wideRender.join("\n"), /got it/);
+    assert.equal(receipt.summary, "🧪界 Renderer repaired; approval needed.", "rendering does not trim stored Summary prose");
+    for (const width of [0, 1, 2, 4, 8])
+      assert.ok(component.render(width).every((line) => visibleWidth(line) <= width), `Recap rows stay within ${width} columns`);
+    manager.appendMessage({ role: "user", content: "Synthetic later update: also fix resize", timestamp: 3 });
+    controller.updateContext(ctx);
+    assert.equal(controller.acknowledge(ctx).acknowledged, true);
+    assert.equal(controller.acknowledge(ctx).reason, "already_read");
+    assert.match(component.render(80).join("\n"), /✓ got it/);
+
+    const resumed = SessionManager.open(manager.getSessionFile(), root);
+    const branch = resumed.getBranch();
+    const loadedSelection = selectRarebits(branch);
+    const checkpoint = recapReadCheckpoint(branch, loadedSelection);
+    assert.equal(checkpoint.coveredEntryId, selection.occurrences.at(-1).sourceEntryId);
+    const input = composeRarebitSummaryDerivationInput(loadedSelection, { readCheckpoint: checkpoint });
+    const lines = input.prompt.split("BEGIN_RAREBIT_MESSAGES_JSONL\n")[1].split("\nEND_RAREBIT_MESSAGES_JSONL")[0].split("\n").map(JSON.parse);
+    assert.equal(lines.findIndex((line) => line.type === "recap_read"), 2);
+    assert.match(lines[3].text, /also fix resize/);
+    assert.match(input.prompt, /Acknowledgement does not resolve requests/);
+    assert.match(input.prompt, /at most 300 characters/);
+    assert.equal(loadedSelection.occurrences.length, 3, "UI state stays out of conversation prose");
+
+    let providerPrompt;
+    const result = await processRarebitSummary({ sessionManager: resumed }, {
+      sessionRoot: root, rarebitRoot: join(root, "receipts"), forceSynthesis: true,
+      model: { provider: "fixture", id: "fixture" },
+      modelClient: { complete: async ({ prompt }) => {
+        providerPrompt = prompt;
+        return JSON.stringify({ summary: "Resize repair newly requested; renderer approval remains open.", sessionStatus: "needs_attention", statusReason: "approval" });
+      } },
+    });
+    assert.equal(result.record.status, "ok");
+    assert.match(providerPrompt, /"type":"recap_read"/);
+    assert.ok(result.record.summary.length <= 300);
+
+    // Navigating away from the read marker and into a sibling branch must not
+    // carry the checkpoint from a different conversation path.
+    resumed.branch(selection.occurrences.at(-1).sourceEntryId);
+    resumed.appendMessage({ role: "user", content: "Synthetic sibling update", timestamp: 4 });
+    assert.equal(recapReadCheckpoint(resumed.getBranch(), selectRarebits(resumed.getBranch())), null);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});

package/test/summary-attention-independent.test.mjs

@@ -108,7 +108,7 @@ test("v4 synthesis validates legal status/reason combinations without rigid sect
       }),
     ),
     {
-      summary: "Any free-form prose with controls removed",
+      summary: "Any free-form prose\nwith controls removed",
       sessionStatus: "needs_attention",
       statusReason: "unfinished",
     },