@hypercarrier/rarebit 0.1.0-alpha.6 → 0.2.1

package/src/types.d.ts

@@ -1,5 +1,47 @@
 export type RarebitModel = { provider: string; id: string };
 
+export type RarebitDiagnosticsSettings = {
+  summaryTriggered: boolean;
+  summaryUpdated: boolean;
+};
+export type RarebitRecapSettings = {
+  enabled: boolean;
+  delayMs: number;
+  timezone: string;
+};
+export type RarebitResolvedSettings = {
+  model?: RarebitModel;
+  modelConfigurationError?: string;
+  summaryPolicy: RarebitSummaryPolicy;
+  autoTitle: boolean;
+  summaryPrompt?: unknown;
+  maxInputTokens: number;
+  diagnostics: RarebitDiagnosticsSettings;
+  recap: RarebitRecapSettings;
+};
+export const DEFAULT_RAREBIT_RECAP_DELAY_MS: 60000;
+export const DEFAULT_RAREBIT_RECAP_TIMEZONE: "host";
+export const DEFAULT_RAREBIT_MAX_INPUT_TOKENS: 64000;
+export const MAX_RAREBIT_INPUT_TOKENS: number;
+export const DEFAULT_RAREBIT_DIAGNOSTICS: Readonly<RarebitDiagnosticsSettings>;
+export const RAREBIT_SUMMARY_PROMPT_IDENTITY_VERSION: "rarebit-summary-prompt-v1";
+export const MAX_RAREBIT_SUMMARY_PROMPT_CHARS: 64000;
+export const DEFAULT_RAREBIT_SUMMARY_PROMPT_GUIDANCE: string;
+export const MAX_RAREBIT_SUMMARY_CHARS: 8000;
+export function normalizeRarebitSummaryPrompt(value?: unknown): {
+  guidance: string;
+  promptIdentity: string | null;
+};
+export function mergeRarebitSettings(
+  globalSettings?: Record<string, unknown>,
+  projectSettings?: Record<string, unknown>,
+): Record<string, unknown>;
+export function normalizeRarebitRecapTimezone(value?: unknown): string;
+export function resolveRarebitSettings(
+  globalSettings?: Record<string, unknown>,
+  projectSettings?: Record<string, unknown>,
+): RarebitResolvedSettings;
+
 /** Seeded destination entries, including the generated fork notice. */
 export function getImportedRarebitEntryIds(entries: readonly unknown[]): Set<string>;
 export const RAREBIT_FORK_LINEAGE_SCHEMA_VERSION: 1;
@@ -227,22 +269,33 @@ export function composeRarebitSummaryDerivationInput(
   selection: ReturnType<typeof selectRarebits>,
   options?: {
     promptVersion?: string;
+    summaryPrompt?: unknown;
     lifecycleBoundary?: "owner_request" | "agent_settled" | "manual";
     maxPromptChars?: number;
-  },
-): { prompt: string; coverage: RarebitSummaryInputCoverage };
+    readCheckpoint?: { coveredEntryId: string } | null;
+  }): {
+  prompt: string;
+  promptIdentity: string | null;
+  promptVersion: string;
+  coverage: RarebitSummaryInputCoverage;
+};
 export function composeRarebitSummaryPrompt(
   selection: ReturnType<typeof selectRarebits>,
   options?: {
     promptVersion?: string;
+    summaryPrompt?: unknown;
     lifecycleBoundary?: "owner_request" | "agent_settled" | "manual";
     maxPromptChars?: number;
+    readCheckpoint?: { coveredEntryId: string } | null;
   },
 ): string;
 export function composeRarebitTitlePrompt(
   selection: ReturnType<typeof selectRarebits>,
 ): string;
-export function normalizeRarebitSummary(value: unknown): string;
+export function normalizeRarebitSummary(
+  value: unknown,
+  options?: { maxChars?: number },
+): string;
 export function normalizeRarebitSummarySynthesis(
   value: unknown,
   options?: { maxChars?: number },
@@ -329,7 +382,8 @@ type RarebitSummaryReceiptCommon = {
   implementationVersion:
     | "hc-rarebit-summary-v4"
     | "hc-rarebit-summary-v5"
-    | "hc-rarebit-summary-v6";
+    | "hc-rarebit-summary-v6"
+    | "hc-rarebit-summary-v7";
   synthesisMode: "forced" | "automatic";
   inputCoveragePolicy: RarebitInputCoveragePolicy;
   promptVersion: string;
@@ -394,12 +448,18 @@ export type RarebitNativeObservation =
   | { availability: "missing" | "unreadable" };
 
 export const RAREBIT_SUMMARY_SCHEMA_VERSION: 4;
-export const RAREBIT_SUMMARY_IMPLEMENTATION_VERSION: "hc-rarebit-summary-v6";
+export const RAREBIT_SUMMARY_IMPLEMENTATION_VERSION: "hc-rarebit-summary-v7";
+export const RAREBIT_INPUT_CHARS_PER_TOKEN: 4;
+export const DEFAULT_RAREBIT_MAX_PROMPT_CHARS: 256000;
 export function processRarebitSummary(
   ctx: unknown,
   config?: {
     model?: RarebitModel;
     summaryPolicy?: RarebitSummaryPolicy;
+    summaryPrompt?: unknown;
+    maxInputTokens?: number;
+    maxPromptChars?: number;
+    diagnostics?: RarebitDiagnosticsSettings;
     forceSynthesis?: boolean;
     // New derivation accepts only evidence-transition or explicit boundaries;
     // RarebitSummaryReceiptV4 retains session_start for historical reads.

package/test/lifecycle-contract-independent.test.mjs

@@ -532,6 +532,7 @@ test("TUI notices state input cardinality, clearly estimated trigger tokens, and
       rarebitRoot: join(root, "rarebit"),
       summaryPolicy: { minTotalLength: 0, maxRarebitRatio: 1 },
       model: { provider: "test-provider", id: "cheap-model" },
+      diagnostics: { summaryTriggered: true, summaryUpdated: true },
       modelClient: {
         complete: async () => ({
           text: JSON.stringify({
@@ -588,6 +589,7 @@ test("updated notice never substitutes the local estimate for absent provider us
       rarebitRoot: join(root, "rarebit"),
       summaryPolicy: { minTotalLength: 0, maxRarebitRatio: 1 },
       model: { provider: "requested-provider", id: "requested-model" },
+      diagnostics: { summaryTriggered: true, summaryUpdated: true },
       modelClient: {
         complete: async () => ({
           text: JSON.stringify({

package/test/package-artifact-identity.test.mjs

@@ -0,0 +1,54 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const verifier = join(root, "scripts/verify-package.mjs");
+
+function syntheticTarball(field, value) {
+  const work = mkdtempSync(join(tmpdir(), "rarebit-artifact-test-"));
+  const packageDir = join(work, "package");
+  execFileSync("mkdir", ["-p", packageDir]);
+  const packageJson = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+  packageJson[field] = value;
+  writeFileSync(join(packageDir, "package.json"), `${JSON.stringify(packageJson)}\n`);
+  const tarball = join(work, `${field}.tgz`);
+  execFileSync("tar", ["-czf", tarball, "-C", work, "package"]);
+  return { work, tarball };
+}
+
+function runVerifier(tarball) {
+  return spawnSync(process.execPath, [verifier], {
+    cwd: root,
+    env: { ...process.env, RELEASE_TARBALL: tarball },
+    encoding: "utf8",
+  });
+}
+
+test("rejects packed name and version changes against selected source", () => {
+  for (const [field, value] of [["name", "invalid-name"], ["version", "0.0.0-invalid-test"]]) {
+    const fixture = syntheticTarball(field, value);
+    try {
+      const result = runVerifier(fixture.tarball);
+      assert.notEqual(result.status, 0, `${field} mutation was accepted`);
+      assert.match(`${result.stdout}\n${result.stderr}`, /packed package (name|version) differs from selected source/);
+    } finally {
+      rmSync(fixture.work, { recursive: true, force: true });
+    }
+  }
+});
+
+test("accepts the normal packed artifact", () => {
+  const filename = JSON.parse(execFileSync("npm", ["pack", "--json", "--ignore-scripts"], { cwd: root, encoding: "utf8" }))[0].filename;
+  const tarball = join(root, filename);
+  try {
+    const result = runVerifier(tarball);
+    assert.equal(result.status, 0, result.stderr);
+  } finally {
+    rmSync(tarball, { force: true });
+  }
+});

package/test/rarebit-artifact-state.test.mjs

@@ -285,12 +285,18 @@ test("only agent_settled ends an active request generation; exact start/manual c
     });
     assert.equal(state.syncState, "request_current");
   }
+  const exact = [owner, continuation];
+  const settled = receipt({ occurrences: exact, boundary: "agent_settled", observedAt: "2026-07-25T10:03:00.000Z" });
+  const newerManual = receipt({ occurrences: exact, boundary: "manual", observedAt: "2026-07-25T10:04:00.000Z" });
+  const promoted = projectRarebitArtifactState({
+    native: native(exact),
+    materialization: { availability: "available", records: [settled, newerManual] },
+  });
+  assert.equal(promoted.syncState, "assessment_current");
+  assert.equal(promoted.receiptRef.lifecycleBoundary, "manual");
   const manualOnly = projectRarebitArtifactState({
     native: native([owner]),
-    materialization: {
-      availability: "available",
-      records: [receipt({ boundary: "manual" })],
-    },
+    materialization: { availability: "available", records: [receipt({ boundary: "manual" })] },
   });
   assert.equal(manualOnly.syncState, "assessment_current");
 });

package/test/rarebit-command.test.mjs

@@ -14,11 +14,11 @@ const values = (prefix) =>
 test("one grammar derives command description and usage", () => {
   assert.equal(
     rarebitCommandDescription(),
-    "Rarebit status/recall/fork/config/auto-title/title/summarize",
+    "Rarebit menu/settings/help/status/recall/fork/config/auto-title/title/recap/got-it/summarize",
   );
   assert.equal(
     rarebitCommandUsage(),
-    "Usage: /rarebit [status|recall|fork|config|auto-title|title|summarize]",
+    "Usage: /rarebit [menu|settings|help|status|recall|fork|config|auto-title|title|recap|got-it|summarize]",
   );
   assert.equal(
     rarebitCommandUsage("config"),
@@ -41,7 +41,7 @@ test("one grammar derives command description and usage", () => {
 test("parser accepts exactly the command grammar", () => {
   assert.deepEqual(parseRarebitCommand(""), {
     ok: true,
-    subcommand: "status",
+    subcommand: "menu",
     arguments: [],
   });
   assert.equal(parseRarebitCommand("fork").ok, true);
@@ -53,6 +53,8 @@ test("parser accepts exactly the command grammar", () => {
   assert.equal(parseRarebitCommand("auto-title off").ok, true);
   assert.equal(parseRarebitCommand("title").ok, true);
   assert.equal(parseRarebitCommand("summarize").ok, true);
+  assert.equal(parseRarebitCommand("got-it").ok, true);
+  assert.equal(parseRarebitCommand("got-it now").ok, false);
   assert.deepEqual(
     parseRarebitCommand(
       "recall Review the evidence, then  continue exactly.  ",
@@ -93,15 +95,20 @@ test("parser accepts exactly the command grammar", () => {
 
 test("autocomplete covers subcommands and discrete nested arguments", () => {
   assert.deepEqual(values(""), [
+    "menu",
+    "settings",
+    "help",
     "status",
     "recall",
     "fork",
     "config",
     "auto-title",
     "title",
+    "recap",
+    "got-it",
     "summarize",
   ]);
-  assert.deepEqual(values("s"), ["status", "summarize"]);
+  assert.deepEqual(values("s"), ["settings", "status", "summarize"]);
   assert.deepEqual(values("config "), [
     "config max_rarebit_ratio ",
     "config min_total_length ",

package/test/rarebit-core.test.mjs

@@ -160,6 +160,56 @@ test("bounded Summary input retains newest evidence and declares every omission"
   assert.equal(DEFAULT_RAREBIT_MAX_PROMPT_CHARS, 256_000);
 });
 
+test("read checkpoints stay metadata beside a retained evidence suffix and do not replace pending approval", () => {
+  const selection = selectRarebits([
+    entry("early", { role: "user", content: `EARLY-${"e".repeat(5_000)}` }),
+    entry("approval", { role: "assistant", stopReason: "stop", content: `${"p".repeat(5_000)}-APPROVAL-STILL-NEEDED` }),
+  ]);
+  const input = composeRarebitSummaryDerivationInput(selection, {
+    maxPromptChars: 6_000,
+    readCheckpoint: { coveredEntryId: "approval", coveredOrder: 1 },
+  });
+  const lines = input.prompt.split("BEGIN_RAREBIT_MESSAGES_JSONL\n")[1].split("\nEND_RAREBIT_MESSAGES_JSONL")[0].split("\n").map(JSON.parse);
+  assert.ok(input.prompt.length <= 6_000);
+  assert.equal(input.coverage.totalMessageCount, 2);
+  assert.equal(input.coverage.includedMessageCount, 1);
+  assert.ok(lines.some((line) => line.type === "recap_read"));
+  assert.ok(lines.some((line) => line.text?.includes("APPROVAL-STILL-NEEDED")));
+  assert.doesNotMatch(input.prompt, /EARLY-/);
+  assert.match(input.prompt, /omitted|trimmed/);
+});
+
+test("read boundaries stay before, at, or after the retained evidence suffix", () => {
+  const selection = selectRarebits(Array.from({ length: 4 }, (_, index) =>
+    entry(`u${index}`, { role: "user", content: `evidence-${index}-${"x".repeat(1_200)}` })));
+  for (const coveredIndex of [0, 1, 3]) {
+    const input = composeRarebitSummaryDerivationInput(selection, {
+      maxPromptChars: 7_500,
+      readCheckpoint: { coveredEntryId: `u${coveredIndex}`, coveredOrder: coveredIndex },
+    });
+    const body = input.prompt.split("BEGIN_RAREBIT_MESSAGES_JSONL\n")[1].split("\nEND_RAREBIT_MESSAGES_JSONL")[0];
+    const lines = body.split("\n").map(JSON.parse);
+    const ordered = lines.filter((line) => !line.omitted);
+    const readIndex = ordered.findIndex((line) => line.type === "recap_read");
+    const evidence = ordered.filter((line) => line.type !== "recap_read");
+    assert.ok(input.coverage.omittedMessageCount > 0);
+    assert.ok(input.prompt.length <= 7_500);
+    if (coveredIndex === 0) assert.equal(readIndex, 0, "a boundary before the suffix leads it");
+    if (coveredIndex === 1) assert.equal(readIndex, 1, "a boundary at the first retained message follows it");
+    if (coveredIndex === 3) assert.equal(readIndex, evidence.length, "a boundary after the suffix follows all retained messages");
+  }
+});
+
+test("fixed prompt overflow preserves evidence when even empty trimmed input cannot fit", () => {
+  const text = "PENDING-APPROVAL-" + "x".repeat(500);
+  const selection = selectRarebits([entry("u", { role: "user", content: text })]);
+  const input = composeRarebitSummaryDerivationInput(selection, { maxPromptChars: 3_100 });
+  assert.ok(input.prompt.length > 3_100);
+  assert.equal(input.coverage.omittedTextChars, 0);
+  assert.match(input.prompt, /PENDING-APPROVAL/);
+  assert.doesNotMatch(input.prompt, /leading characters.*trimmed/);
+});
+
 test("one oversized newest message is tail-bounded with an explicit character omission", () => {
   const selection = selectRarebits([
     entry("huge", {