@hypercarrier/rarebit 0.1.0-alpha.5 → 0.2.0

package/src/rarebit-cli.mjs

@@ -12,12 +12,19 @@ import {
   queryRarebits,
   readRarebitSession,
 } from "./rarebit-session.mjs";
+import {
+  buildRarebitForkPlan,
+  createRarebitForkEntries,
+  sessionFilenameFor,
+  writeRarebitForkFile,
+} from "./rarebit-fork.mjs";
 
 export const RAREBIT_CLI_USAGE = `Usage:
   rarebit query --session <exact-path-or-id> --json
   rarebit extract --session <exact-path-or-id> --json
   rarebit summarize --session <exact-path-or-id> [--force] [--model-command <executable> [--model-arg <arg>]] --json
   rarebit title --session <exact-path-or-id> [--date YYYY-MM-DD] [--model-command <executable> [--model-arg <arg>]] --json
+  rarebit fork <exact-source-path-or-id> [--max-token-length <tokens>] [--no-launch] [--json]
 
 Normal summarize/title resolve rarebit.model from Pi settings. The optional model-command
 adapter receives one prompt on stdin and must write only model text to stdout.
@@ -33,11 +40,11 @@ function requiredValue(argv, index, flag) {
 export function parseRarebitCliArgs(argv) {
   if (argv.includes("--help") || argv.includes("-h")) return { help: true };
   const [command, ...rest] = argv;
-  if (!new Set(["query", "extract", "summarize", "title"]).has(command))
+  if (!new Set(["query", "extract", "summarize", "title", "fork"]).has(command))
     throw new Error(
       "First argument must be query, extract, summarize, or title",
     );
-  const options = { command, modelArgs: [], json: false, force: false };
+  const options = { command, modelArgs: [], json: false, force: false, noLaunch: false };
   for (let index = 0; index < rest.length; index += 1) {
     const argument = rest[index];
     switch (argument) {
@@ -45,6 +52,17 @@ export function parseRarebitCliArgs(argv) {
         options.session = requiredValue(rest, index, argument);
         index += 1;
         break;
+      case "--max-token-length":
+        options.maxTokenLength = Number(requiredValue(rest, index, argument));
+        index += 1;
+        break;
+      case "--model":
+        options.model = requiredValue(rest, index, argument);
+        index += 1;
+        break;
+      case "--no-launch":
+        options.noLaunch = true;
+        break;
       case "--model-command":
         options.modelCommand = requiredValue(rest, index, argument);
         index += 1;
@@ -64,11 +82,13 @@ export function parseRarebitCliArgs(argv) {
         options.force = true;
         break;
       default:
-        throw new Error(`Unknown argument: ${argument}`);
+        if (command === "fork" && !argument.startsWith("--") && !options.session) options.session = argument;
+        else throw new Error(`Unknown argument: ${argument}`);
     }
   }
-  if (!options.session) throw new Error("--session is required");
-  if (!options.json) throw new Error("--json is required");
+  if (!options.session) throw new Error(command === "fork" ? "fork requires an exact source Session path or ID" : "--session is required");
+  if (options.maxTokenLength !== undefined && (!Number.isSafeInteger(options.maxTokenLength) || options.maxTokenLength < 1)) throw new Error("--max-token-length must be a positive integer");
+  if (!options.json && command !== "fork") throw new Error("--json is required");
   if (options.force && command !== "summarize")
     throw new Error("--force only applies to summarize");
   return options;
@@ -185,6 +205,7 @@ export async function readRarebitCliSettings({
       rawRefs: [globalPath, projectPath],
     },
     summaryPolicy: resolved.summaryPolicy,
+    summaryPrompt: resolved.summaryPrompt,
     autoTitle: resolved.autoTitle,
   };
 }
@@ -235,6 +256,79 @@ async function modelRuntime(options, dependencies) {
   };
 }
 
+async function resolveForkTarget({ cwd, explicitModel, agentDir, resolveTarget }) {
+  if (resolveTarget) return resolveTarget({ cwd, explicitModel, agentDir });
+  const {
+    ModelRuntime,
+    SessionManager,
+    SettingsManager,
+    createAgentSession,
+  } = await import("@earendil-works/pi-coding-agent");
+  const settings = SettingsManager.create(cwd, agentDir);
+  const runtime = await ModelRuntime.create({ allowModelNetwork: false });
+  let targetModel;
+  if (explicitModel) {
+    const [provider, ...idParts] = explicitModel.split("/");
+    const id = idParts.join("/");
+    targetModel = runtime.getModel(provider, id);
+  } else {
+    const provider = settings.getDefaultProvider();
+    const id = settings.getDefaultModel();
+    targetModel = provider && id ? runtime.getModel(provider, id) : undefined;
+    if (!targetModel) targetModel = (await runtime.getAvailable())[0];
+  }
+  if (!targetModel?.provider || !targetModel?.id || !Number.isFinite(targetModel.contextWindow))
+    throw new Error("Cannot resolve the target Pi model and context window before forking; set Pi's default model or pass --model provider/model");
+  const global = settings.getGlobalSettings();
+  const project = settings.getProjectSettings();
+  const key = `${targetModel.provider}/${targetModel.id}`;
+  const overrides = { ...(global.compaction?.modelOverrides ?? {}), ...(project.compaction?.modelOverrides ?? {}) };
+  const reserveTokens = overrides[key]?.reserveTokens ?? settings.getCompactionReserveTokens();
+  const { session } = await createAgentSession({
+    cwd,
+    agentDir,
+    model: targetModel,
+    modelRuntime: runtime,
+    settingsManager: settings,
+    sessionManager: SessionManager.inMemory(cwd),
+  });
+  try {
+    const promptOverheadTokens = Math.ceil(String(session.agent.state.systemPrompt ?? "").length / 4);
+    const toolOverheadTokens = Math.ceil(JSON.stringify(session.agent.state.tools ?? []).length / 4);
+    return { model: targetModel, reserveTokens, promptOverheadTokens, toolOverheadTokens };
+  } finally {
+    session.dispose();
+  }
+}
+
+export async function runPiFork({ session, maxTokenLength, cwd = process.cwd(), piCommand = "pi", noLaunch = false, model, agentDir, resolveTarget, spawnProcess = spawn } = {}) {
+  const loaded = await readRarebitSession(session);
+  const target = await resolveForkTarget({ cwd, explicitModel: model, agentDir, resolveTarget });
+  const targetModel = target.model;
+  const plan = buildRarebitForkPlan({
+    header: loaded.parsed.header,
+    sessionFile: loaded.sessionFile,
+    cwd,
+    branch: loaded.branch,
+    targetCwd: cwd,
+    maxTokenLength,
+    targetModel,
+    reserveTokens: target.reserveTokens,
+    promptOverheadTokens: target.promptOverheadTokens,
+    toolOverheadTokens: target.toolOverheadTokens,
+  });
+  const { SessionManager } = await import("@earendil-works/pi-coding-agent");
+  const destinationManager = SessionManager.create(cwd);
+  const destination = sessionFilenameFor({ sessionDir: destinationManager.getSessionDir(), forkCreatedAt: plan.forkCreatedAt, sessionId: destinationManager.getSessionId() });
+  const built = createRarebitForkEntries(plan, { sessionId: destinationManager.getSessionId() });
+  await writeRarebitForkFile(destination, built);
+  const result = { operation: "fork", session: destination, sourceSessionId: loaded.session.id, ...plan.omission, headroom: plan.headroom, launched: false };
+  if (noLaunch) return result;
+  const child = spawnProcess(piCommand, ["--session", destination], { cwd, stdio: "inherit", shell: false, env: process.env });
+  const exit = await new Promise((resolve, reject) => { child.on("error", reject); child.on("close", (code, signal) => resolve({ code, signal })); });
+  return { ...result, launched: true, exitCode: exit.code, signal: exit.signal };
+}
+
 export async function runRarebitCli(options, dependencies = {}) {
   const runtimeDependencies = {
     readSettings: dependencies.readSettings ?? readRarebitCliSettings,
@@ -245,6 +339,9 @@ export async function runRarebitCli(options, dependencies = {}) {
   };
   if (options.command === "query") return queryRarebits(options.session);
   if (options.command === "extract") return extractRarebits(options.session);
+  if (options.command === "fork") {
+    return runPiFork({ session: options.session, maxTokenLength: options.maxTokenLength, noLaunch: options.noLaunch, piCommand: dependencies.piCommand, model: options.model, agentDir: dependencies.agentDir, resolveTarget: dependencies.resolveTarget, spawnProcess: dependencies.spawnProcess });
+  }
 
   const loaded = await readRarebitSession(options.session);
   const runtime = await modelRuntime(options, runtimeDependencies);
@@ -255,6 +352,7 @@ export async function runRarebitCli(options, dependencies = {}) {
         model: runtime.model,
         modelProvenance: runtime.modelProvenance,
         summaryPolicy: runtime.summaryPolicy,
+        summaryPrompt: runtime.summaryPrompt,
         forceSynthesis: options.force === true,
         allowExternalSession: true,
         rarebitRoot: dependencies.rarebitRoot,

package/src/rarebit-command.mjs

@@ -17,8 +17,23 @@ const rest = (usage) => ({
 
 export const RAREBIT_COMMAND_GRAMMAR = Object.freeze({
   name: "rarebit",
-  defaultSubcommand: "status",
+  defaultSubcommand: "menu",
   subcommands: Object.freeze([
+    {
+      name: "menu",
+      description: "Open the interactive Rarebit command palette",
+      forms: [[]],
+    },
+    {
+      name: "settings",
+      description: "Open interactive Rarebit settings",
+      forms: [[], [literal("global", "Edit global Pi settings")], [literal("project", "Edit trusted project settings")]],
+    },
+    {
+      name: "help",
+      description: "Show Rarebit command help",
+      forms: [[]],
+    },
     {
       name: "status",
       description: "Show effective Rarebit configuration",
@@ -29,6 +44,14 @@ export const RAREBIT_COMMAND_GRAMMAR = Object.freeze({
       description: "Recall active-branch Rarebit messages with a prompt",
       forms: [[rest("<prompt...>")]],
     },
+    {
+      name: "fork",
+      description: "Open a bounded Rarebit fork without starting a model turn",
+      forms: [
+        [],
+        [literal("--max-token-length", "Imported Rarebit token budget"), number("<positive tokens>", (value) => Number.isSafeInteger(value) && value > 0)],
+      ],
+    },
     {
       name: "config",
       description: "Show or override summary policy for this process",
@@ -65,6 +88,11 @@ export const RAREBIT_COMMAND_GRAMMAR = Object.freeze({
       usageNote: "use Pi's native /name for a literal title",
       forms: [[]],
     },
+    {
+      name: "recap",
+      description: "Show the current Recap in the TUI",
+      forms: [[]],
+    },
     {
       name: "summarize",
       description: "Force a Rarebit Summary materialization",

package/src/rarebit-core.mjs

@@ -7,6 +7,16 @@ import { createHash } from "node:crypto";
 export const RAREBIT_SELECTOR_VERSION = "rarebit-selector-v1";
 export const RAREBIT_MEASUREMENT_VERSION = "rarebit-prose-chars-div4-v1";
 export const RAREBIT_SUMMARY_PROMPT_VERSION = "rarebit-summary-v6";
+export const RAREBIT_SUMMARY_PROMPT_IDENTITY_VERSION =
+  "rarebit-summary-prompt-v1";
+// User guidance is a UTF-16 string in JavaScript. Bound it before any Summary
+// provider work so a malformed settings value cannot create an unbounded job.
+export const MAX_RAREBIT_SUMMARY_PROMPT_CHARS = 64_000;
+// Receipts have a 48 KiB protocol limit. Keep the configurable Summary field
+// well below that limit even when the model returns multi-byte text.
+export const MAX_RAREBIT_SUMMARY_CHARS = 8_000;
+export const DEFAULT_RAREBIT_SUMMARY_PROMPT_GUIDANCE =
+  "The summary is free-form prose. State when evidence is uncertain, confusing, contradictory, or importantly missing instead of inventing a coherent account.";
 export const RAREBIT_TITLE_PROMPT_VERSION = "rarebit-title-v1";
 export const RAREBIT_JOB_IDENTITY_VERSION = "rarebit-job-identity-v2";
 
@@ -274,12 +284,50 @@ function semanticMessages(selection) {
   }));
 }
 
+/**
+ * Resolve the bounded Summary style contract. The setting is a scalar prompt
+ * fragment. The fixed evidence and status contract remains in this module.
+ * The normalized identity is used by the service to prevent a changed prompt
+ * from reusing an older receipt.
+ */
+export function normalizeRarebitSummaryPrompt(value) {
+  if (value === undefined) {
+    return {
+      guidance: DEFAULT_RAREBIT_SUMMARY_PROMPT_GUIDANCE,
+      promptIdentity: null,
+    };
+  }
+  if (typeof value !== "string")
+    throw new TypeError("summary_prompt must be a string");
+  const guidance = value.replace(/\r\n?/g, "\n").trim();
+  if (!guidance) throw new TypeError("summary_prompt must not be blank");
+  if (guidance.length > MAX_RAREBIT_SUMMARY_PROMPT_CHARS)
+    throw new RangeError(
+      `summary_prompt must not exceed ${MAX_RAREBIT_SUMMARY_PROMPT_CHARS} UTF-16 characters`,
+    );
+  if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/.test(guidance))
+    throw new TypeError("summary_prompt contains unsafe control characters");
+  return {
+    guidance,
+    promptIdentity:
+      guidance === DEFAULT_RAREBIT_SUMMARY_PROMPT_GUIDANCE
+        ? null
+        : sha256({
+            version: RAREBIT_SUMMARY_PROMPT_IDENTITY_VERSION,
+            guidance,
+          }),
+  };
+}
+
 function summaryPromptParts(messages, {
   lifecycleBoundary,
   omittedMessageCount = 0,
   omittedTextChars = 0,
+  summaryPrompt,
 } = {}) {
   const ownerRequest = lifecycleBoundary === "owner_request";
+  const resolvedPrompt = normalizeRarebitSummaryPrompt(summaryPrompt);
+  const styleLine = resolvedPrompt.guidance;
   const omission =
     omittedMessageCount > 0 || omittedTextChars > 0
       ? {
@@ -294,7 +342,7 @@ function summaryPromptParts(messages, {
     "You are the HyperCarrier Rarebit summarizer.",
     "Summarize only what is explicitly stated in the ordered Rarebit evidence stream below.",
     "If an omission record appears, it is authoritative: earlier evidence is unavailable to you. Do not infer what was trimmed, and state when important missing evidence makes the account uncertain or confusing.",
-    "The summary is free-form prose. State when evidence is uncertain, confusing, contradictory, or importantly missing instead of inventing a coherent account.",
+    styleLine,
     "Identify every active, non-superseded request visible in the supplied evidence, not only the last turn. Explicit cancellation, replacement, supersession, and later resolution make an earlier request inactive.",
     "Selected evidence contains only user and assistant message prose at Rarebit continuation or stop boundaries. Tool-call inputs, tool results, hidden reasoning, and transport records are deliberately absent.",
     "Absence of a tool transcript is unobservable and must never by itself imply that work was not performed.",
@@ -328,27 +376,32 @@ export function composeRarebitSummaryDerivationInput(
     promptVersion = RAREBIT_SUMMARY_PROMPT_VERSION,
     lifecycleBoundary = "manual",
     maxPromptChars = Number.MAX_SAFE_INTEGER,
+    summaryPrompt,
   } = {},
 ) {
-  void promptVersion;
   if (
     !RAREBIT_SUMMARY_WRITABLE_LIFECYCLE_BOUNDARIES.includes(lifecycleBoundary)
   )
     throw new TypeError("Unsupported Summary lifecycle boundary");
   if (!Number.isInteger(maxPromptChars) || maxPromptChars < 1)
     throw new RangeError("maxPromptChars must be a positive integer");
+  const resolvedPrompt = normalizeRarebitSummaryPrompt(summaryPrompt);
 
   const allMessages = semanticMessages(selection);
   let messages = allMessages.slice();
   let omittedMessageCount = 0;
   let omittedTextChars = 0;
-  let prompt = renderSummaryPrompt(messages, { lifecycleBoundary });
+  let prompt = renderSummaryPrompt(messages, {
+    lifecycleBoundary,
+    summaryPrompt,
+  });
   while (prompt.length > maxPromptChars && messages.length > 1) {
     messages.shift();
     omittedMessageCount += 1;
     prompt = renderSummaryPrompt(messages, {
       lifecycleBoundary,
       omittedMessageCount,
+      summaryPrompt,
     });
   }
   if (prompt.length > maxPromptChars && messages.length === 1) {
@@ -363,6 +416,7 @@ export function composeRarebitSummaryDerivationInput(
         lifecycleBoundary,
         omittedMessageCount,
         omittedTextChars: removed,
+        summaryPrompt,
       });
       if (candidatePrompt.length <= maxPromptChars) {
         best = { messages: candidate, prompt: candidatePrompt, removed };
@@ -377,6 +431,8 @@ export function composeRarebitSummaryDerivationInput(
   }
   return {
     prompt,
+    promptIdentity: resolvedPrompt.promptIdentity,
+    promptVersion,
     coverage: {
       totalMessageCount: allMessages.length,
       includedMessageCount: messages.length,
@@ -425,17 +481,35 @@ function compactLine(value) {
     .trim();
 }
 
-export function normalizeRarebitSummary(value, { maxChars = 2_000 } = {}) {
+function preserveProseLayout(value) {
+  return String(value ?? "")
+    .replace(/\r\n?/g, "\n")
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, "")
+    .replace(/[\u2028\u2029]/g, "\n")
+    .trim();
+}
+
+export function normalizeRarebitSummary(
+  value,
+  { maxChars = MAX_RAREBIT_SUMMARY_CHARS } = {},
+) {
   if (!Number.isInteger(maxChars) || maxChars < 1)
     throw new RangeError("maxChars must be a positive integer");
-  const compact = compactLine(value);
-  if (!compact) throw new Error("Summary model returned no usable summary");
-  return compact.slice(0, maxChars).trimEnd();
+  if (maxChars > MAX_RAREBIT_SUMMARY_CHARS)
+    throw new RangeError(
+      `maxChars must not exceed ${MAX_RAREBIT_SUMMARY_CHARS}`,
+    );
+  const normalized = preserveProseLayout(value);
+  if (!normalized) throw new Error("Summary model returned no usable summary");
+  if (normalized.length <= maxChars) return normalized;
+  throw new RangeError(
+    `Summary model returned ${normalized.length} characters; configured limit is ${maxChars}`,
+  );
 }
 
 export function normalizeRarebitSummarySynthesis(
   value,
-  { maxChars = 2_000 } = {},
+  { maxChars = MAX_RAREBIT_SUMMARY_CHARS } = {},
 ) {
   let synthesis;
   try {
@@ -456,7 +530,9 @@ export function normalizeRarebitSummarySynthesis(
   if (!RAREBIT_SESSION_STATUS_REASONS[status].includes(reason))
     throw new TypeError("Summary model response has an illegal statusReason");
   return {
-    summary: normalizeRarebitSummary(synthesis.summary, { maxChars }),
+    summary: normalizeRarebitSummary(synthesis.summary, {
+      maxChars,
+    }),
     sessionStatus: status,
     statusReason: reason,
   };
@@ -501,6 +577,7 @@ export function rarebitJobIdentity({
   selection,
   policy = null,
   promptVersion,
+  promptIdentity = null,
   model = null,
 } = {}) {
   if (!new Set(["summary", "title"]).has(operation))
@@ -520,6 +597,7 @@ export function rarebitJobIdentity({
     selectionManifestHash: selection.manifestHash,
     policy: policy === null ? null : normalizeRarebitSummaryPolicy(policy),
     promptVersion: promptVersion ?? null,
+    promptIdentity: promptIdentity ?? null,
     model,
   });
 }

package/src/rarebit-fork-lineage.mjs

@@ -0,0 +1,69 @@
+export const RAREBIT_FORK_LINEAGE_SCHEMA_VERSION = 1;
+export const RAREBIT_FORK_ENTRY_MARKER_VERSION = "rarebit-fork-entry/1";
+export const RAREBIT_FORK_LINEAGE_CUSTOM_TYPE = "rarebit-fork-lineage";
+export const RAREBIT_FORK_OPENING_MARKER = "rarebit-fork-opening-v1";
+
+function validMarker(marker) {
+  return (
+    marker &&
+    typeof marker === "object" &&
+    marker.version === RAREBIT_FORK_ENTRY_MARKER_VERSION &&
+    (marker.kind === "seed" || marker.kind === "import")
+  );
+}
+
+function entriesWithIds(entries) {
+  return (Array.isArray(entries) ? entries : []).filter(
+    (entry) => typeof entry?.id === "string" && entry.id,
+  );
+}
+
+function lineageRecords(entries) {
+  return (Array.isArray(entries) ? entries : []).filter(
+    (entry) =>
+      entry?.type === "custom" &&
+      entry.customType === RAREBIT_FORK_LINEAGE_CUSTOM_TYPE &&
+      entry.data?.schemaVersion === RAREBIT_FORK_LINEAGE_SCHEMA_VERSION,
+  );
+}
+
+/**
+ * Return only destination entry IDs present in the supplied entries. This
+ * intentionally does not resolve parentSession or return source ancestor IDs,
+ * so bounded head/tail consumers can classify a marker without a full scan.
+ */
+export function getImportedRarebitEntryIds(entries) {
+  const supplied = new Set(entriesWithIds(entries).map((entry) => entry.id));
+  const ids = new Set();
+  for (const entry of entriesWithIds(entries)) {
+    if (validMarker(entry.rarebitFork)) ids.add(entry.id);
+  }
+  for (const record of lineageRecords(entries)) {
+    const data = record.data;
+    const imported = Array.isArray(data.importedEntryIds)
+      ? data.importedEntryIds
+      : [];
+    for (const id of [data.opening?.seedEntryId, ...imported]) {
+      if (typeof id === "string" && supplied.has(id)) ids.add(id);
+    }
+  }
+  return ids;
+}
+
+export function getRarebitForkSeedEntryIds(entries) {
+  const supplied = new Set(entriesWithIds(entries).map((entry) => entry.id));
+  const ids = new Set();
+  for (const entry of entriesWithIds(entries)) {
+    if (validMarker(entry.rarebitFork) && entry.rarebitFork.kind === "seed")
+      ids.add(entry.id);
+  }
+  for (const record of lineageRecords(entries)) {
+    const id = record.data.opening?.seedEntryId;
+    if (typeof id === "string" && supplied.has(id)) ids.add(id);
+  }
+  return ids;
+}
+
+export function getRarebitForkLineageRecords(entries) {
+  return lineageRecords(entries).map((entry) => entry.data);
+}