@hypercarrier/rarebit 0.1.0-alpha.5 → 0.2.0

package/src/rarebit-service.mjs

@@ -1,12 +1,15 @@
 import {
   DEFAULT_RAREBIT_SUMMARY_POLICY,
+  DEFAULT_RAREBIT_SUMMARY_PROMPT_GUIDANCE,
   RAREBIT_SUMMARY_WRITABLE_LIFECYCLE_BOUNDARIES,
+  RAREBIT_SUMMARY_PROMPT_IDENTITY_VERSION,
   RAREBIT_SUMMARY_PROMPT_VERSION,
   RAREBIT_TITLE_PROMPT_VERSION,
   composeRarebitSummaryDerivationInput,
   composeRarebitTitlePrompt,
   evaluateRarebitSummaryEligibility,
   measureRarebits,
+  normalizeRarebitSummaryPrompt,
   normalizeRarebitSummaryPolicy,
   normalizeRarebitSummarySynthesis,
   normalizeRarebitTitle,
@@ -25,6 +28,7 @@ import {
   extractRarebitSynthesisReceipt,
   resolveRarebitModelConfiguration,
 } from "./rarebit-model.mjs";
+import { DEFAULT_RAREBIT_MAX_INPUT_TOKENS } from "./rarebit-settings.mjs";
 import {
   RAREBIT_AUTOMATIC_SUMMARY_POLICY_CONTRACT,
   automaticSummaryInhibitionIdentity,
@@ -33,7 +37,25 @@ import {
 export const RAREBIT_TITLE_IMPLEMENTATION_VERSION = "hc-rarebit-title-v4";
 export const RAREBIT_SUMMARY_IMPLEMENTATION_VERSION = "hc-rarebit-summary-v6";
 export const RAREBIT_SUMMARY_SCHEMA_VERSION = 4;
-export const DEFAULT_RAREBIT_MAX_PROMPT_CHARS = 256_000;
+export const RAREBIT_INPUT_CHARS_PER_TOKEN = 4;
+export const DEFAULT_RAREBIT_MAX_PROMPT_CHARS =
+  DEFAULT_RAREBIT_MAX_INPUT_TOKENS * RAREBIT_INPUT_CHARS_PER_TOKEN;
+
+function maxPromptCharsFromConfig(config) {
+  if (config.maxPromptChars !== undefined) {
+    if (!Number.isSafeInteger(config.maxPromptChars) || config.maxPromptChars < 1)
+      throw new RangeError("maxPromptChars must be a positive safe integer");
+    return config.maxPromptChars;
+  }
+  const maxInputTokens =
+    config.maxInputTokens ?? DEFAULT_RAREBIT_MAX_INPUT_TOKENS;
+  if (!Number.isSafeInteger(maxInputTokens) || maxInputTokens < 1)
+    throw new RangeError("maxInputTokens must be a positive safe integer");
+  const maxPromptChars = maxInputTokens * RAREBIT_INPUT_CHARS_PER_TOKEN;
+  if (!Number.isSafeInteger(maxPromptChars))
+    throw new RangeError("maxInputTokens exceeds the supported prompt limit");
+  return maxPromptChars;
+}
 
 function sessionFileFrom(ctx) {
   const sessionFile = ctx?.sessionManager?.getSessionFile?.();
@@ -97,12 +119,34 @@ function machineModelProvenance(value) {
   };
 }
 
+function summaryCacheSessionId(sessionId, promptVersion, summaryPrompt) {
+  const usesBuiltinContract =
+    promptVersion === RAREBIT_SUMMARY_PROMPT_VERSION &&
+    summaryPrompt.guidance === DEFAULT_RAREBIT_SUMMARY_PROMPT_GUIDANCE;
+  if (usesBuiltinContract) return sessionId;
+  const promptIdentity =
+    summaryPrompt.promptIdentity ??
+    sha256({
+      version: RAREBIT_SUMMARY_PROMPT_IDENTITY_VERSION,
+      guidance: summaryPrompt.guidance,
+    });
+  return sha256({
+    version: "rarebit-summary-cache-v1",
+    sessionId,
+    promptVersion,
+    promptIdentity,
+  });
+}
+
 /**
  * Shared imperative summary shell for Pi and CLI adapters. The functional core
  * decides selection, measurement, policy, prompts, and identity; this shell
  * owns only model invocation and append-only derived-record persistence.
  */
 export async function processRarebitSummary(ctx, config = {}) {
+  // Resolve before model selection or job reservation. Invalid prompt config
+  // must fail closed without a provider call or a misleading receipt.
+  const summaryPrompt = normalizeRarebitSummaryPrompt(config.summaryPrompt);
   const branch = ctx?.sessionManager?.getBranch?.() ?? config.branch ?? [];
   const sessionFile = config.sessionFile ?? sessionFileFrom(ctx);
   const sessionId = config.sessionId ?? sessionIdFrom(ctx);
@@ -165,10 +209,13 @@ export async function processRarebitSummary(ctx, config = {}) {
         provenance: { source: "not_required", status: "not_required" },
       };
   const promptVersion = config.promptVersion ?? RAREBIT_SUMMARY_PROMPT_VERSION;
-  const maxPromptChars =
-    config.maxPromptChars ?? DEFAULT_RAREBIT_MAX_PROMPT_CHARS;
-  if (!Number.isInteger(maxPromptChars) || maxPromptChars < 1)
-    throw new RangeError("maxPromptChars must be a positive integer");
+  // Keep the receipt self-describing without persisting the user guidance.
+  // The digest is already part of the job identity and is safe to expose as
+  // provenance beside the stable prompt contract version.
+  const receiptPromptVersion = summaryPrompt.promptIdentity
+    ? `${promptVersion}:${summaryPrompt.promptIdentity}`
+    : promptVersion;
+  const maxPromptChars = maxPromptCharsFromConfig(config);
   const inputCoveragePolicy = {
     strategy: "newest_suffix_with_explicit_omission",
     maxPromptChars,
@@ -183,6 +230,7 @@ export async function processRarebitSummary(ctx, config = {}) {
     inputPolicy: inputCoveragePolicy,
     lifecycleBoundary,
     promptVersion,
+    promptIdentity: summaryPrompt.promptIdentity,
     model: modelResolution.model,
   });
   const jobId = inhibited
@@ -212,7 +260,7 @@ export async function processRarebitSummary(ctx, config = {}) {
     selection: machineSelection(selection),
     model: modelResolution.model,
     modelProvenance: machineModelProvenance(modelResolution.provenance),
-    promptVersion,
+    promptVersion: receiptPromptVersion,
     ...(inhibited ? { automaticSummaryPolicy } : {}),
   };
   if (!sessionFile) {
@@ -273,6 +321,7 @@ export async function processRarebitSummary(ctx, config = {}) {
     }
     const derivationInput = composeRarebitSummaryDerivationInput(selection, {
       promptVersion,
+      summaryPrompt: config.summaryPrompt,
       lifecycleBoundary,
       maxPromptChars,
     });
@@ -312,7 +361,11 @@ export async function processRarebitSummary(ctx, config = {}) {
     const response = await client.complete({
       prompt,
       model: modelResolution.model,
-      cacheSessionId: sessionId,
+      cacheSessionId: summaryCacheSessionId(
+        sessionId,
+        promptVersion,
+        summaryPrompt,
+      ),
     });
     const synthesisResult = normalizeRarebitSummarySynthesis(
       extractModelText(response),

package/src/rarebit-session.mjs

@@ -1,163 +1,17 @@
-import { open, readFile, readdir, stat } from "node:fs/promises";
-import { homedir } from "node:os";
-import { join, resolve, sep } from "node:path";
+import {
+  DEFAULT_PI_SESSION_ROOT,
+  readPiSession,
+  resolvePiSessionFile,
+} from "./pi-session.mjs";
 import {
   RAREBIT_SELECTOR_VERSION,
   measureRarebits,
   selectRarebits,
 } from "./rarebit-core.mjs";
 
-export const DEFAULT_PI_SESSION_ROOT = join(
-  homedir(),
-  ".pi",
-  "agent",
-  "sessions",
-);
+export { DEFAULT_PI_SESSION_ROOT, parseNativeSession, resolveActiveBranch } from "./pi-session.mjs";
 export const RAREBIT_QUERY_SCHEMA_VERSION = 1;
-
-function queryError(message) {
-  const error = new Error(message);
-  error.name = "RarebitQueryError";
-  return error;
-}
-
-async function isRegularFile(path) {
-  try {
-    return (await stat(path)).isFile();
-  } catch (error) {
-    if (error?.code === "ENOENT") return false;
-    throw error;
-  }
-}
-
-async function* jsonlFiles(root) {
-  let entries;
-  try {
-    entries = await readdir(root, { withFileTypes: true });
-  } catch (error) {
-    if (error?.code === "ENOENT") return;
-    throw error;
-  }
-  for (const entry of entries) {
-    const path = join(root, entry.name);
-    if (entry.isDirectory()) yield* jsonlFiles(path);
-    else if (entry.isFile() && entry.name.endsWith(".jsonl")) yield path;
-  }
-}
-
-async function readHeader(path) {
-  const handle = await open(path, "r");
-  try {
-    const buffer = Buffer.alloc(16384);
-    const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
-    const firstLine = buffer
-      .subarray(0, bytesRead)
-      .toString("utf8")
-      .split("\n", 1)[0]
-      ?.trim();
-    if (!firstLine) return null;
-    try {
-      const header = JSON.parse(firstLine);
-      return header?.type === "session" ? header : null;
-    } catch {
-      return null;
-    }
-  } finally {
-    await handle.close();
-  }
-}
-
-function looksLikePath(reference) {
-  return (
-    reference.includes(sep) ||
-    reference.startsWith(".") ||
-    reference.endsWith(".jsonl")
-  );
-}
-
-/** Resolve either an existing JSONL path or one exact Pi Session ID. */
-export async function resolveRarebitSessionFile(
-  reference,
-  { sessionRoot = DEFAULT_PI_SESSION_ROOT } = {},
-) {
-  if (typeof reference !== "string" || !reference.trim())
-    throw queryError("--session requires an exact Pi Session path or ID");
-  const input = reference.trim();
-  const path = resolve(input);
-  if (await isRegularFile(path)) return path;
-  if (looksLikePath(input))
-    throw queryError(`Pi Session file not found: ${input}`);
-  const matches = [];
-  for await (const candidate of jsonlFiles(resolve(sessionRoot))) {
-    const header = await readHeader(candidate);
-    if (header?.id === input) matches.push(candidate);
-  }
-  if (matches.length === 0)
-    throw queryError(`No persisted Pi Session has exact ID ${input}`);
-  if (matches.length > 1)
-    throw queryError(
-      `Pi Session ID ${input} is ambiguous across ${matches.length} files; pass an exact path`,
-    );
-  return resolve(matches[0]);
-}
-
-export function parseNativeSession(content, source = "Pi Session") {
-  const records = [];
-  for (const [index, line] of String(content).split("\n").entries()) {
-    if (!line.trim()) continue;
-    try {
-      records.push(JSON.parse(line));
-    } catch {
-      throw queryError(
-        `${source} contains malformed JSON at line ${index + 1}`,
-      );
-    }
-  }
-  const header = records[0];
-  if (header?.type !== "session" || typeof header.id !== "string" || !header.id)
-    throw queryError(`${source} does not begin with a valid Pi Session header`);
-  const entries = records.slice(1);
-  const byId = new Map();
-  if ((header.version ?? 1) < 2) return { header, entries, byId, linear: true };
-  for (const entry of entries) {
-    if (typeof entry?.id !== "string" || !entry.id)
-      throw queryError(`${source} contains a Session entry without an ID`);
-    if (byId.has(entry.id))
-      throw queryError(
-        `${source} contains duplicate Session entry ID ${entry.id}`,
-      );
-    byId.set(entry.id, entry);
-  }
-  return { header, entries, byId, linear: false };
-}
-
-/** Match Pi's persisted active branch: the final entry is the active leaf. */
-export function resolveActiveBranch(
-  { entries, byId, linear },
-  source = "Pi Session",
-) {
-  if (linear) return entries.slice();
-  const leaf = entries.at(-1);
-  if (!leaf) return [];
-  const reversed = [];
-  const visited = new Set();
-  let current = leaf;
-  while (current) {
-    if (visited.has(current.id))
-      throw queryError(
-        `${source} contains a cycle at Session entry ${current.id}`,
-      );
-    visited.add(current.id);
-    reversed.push(current);
-    if (current.parentId === null || current.parentId === undefined) break;
-    current = byId.get(current.parentId);
-    if (!current)
-      throw queryError(
-        `${source} is missing parent Session entry ${reversed.at(-1).parentId}`,
-      );
-  }
-  return reversed.reverse();
-}
+export const resolveRarebitSessionFile = resolvePiSessionFile;
 
 function sessionProjection(parsed, branch) {
   const selection = selectRarebits(branch);
@@ -181,13 +35,11 @@ function sessionProjection(parsed, branch) {
 }
 
 export async function readRarebitSession(reference, options = {}) {
-  const sessionFile = await resolveRarebitSessionFile(reference, options);
-  const parsed = parseNativeSession(
-    await readFile(sessionFile, "utf8"),
-    sessionFile,
-  );
-  const branch = resolveActiveBranch(parsed, sessionFile);
-  return { sessionFile, parsed, branch, ...sessionProjection(parsed, branch) };
+  const loaded = await readPiSession(reference, options);
+  return {
+    ...loaded,
+    ...sessionProjection(loaded.parsed, loaded.branch),
+  };
 }
 
 /** Metadata-only projection, safe for a dashboard or programmatic inspection. */