@hypercarrier/rarebit 0.1.0-alpha.4 → 0.1.0-alpha.6

package/src/piq.mjs

@@ -0,0 +1,265 @@
+import {
+  listSessionBranches,
+  readPiSession,
+  resolveSessionBranch,
+} from "./pi-session.mjs";
+
+export const PIQ_SCHEMA_VERSION = 1;
+const FROM_FLAG = "--from";
+
+function piqError(message) {
+  const error = new Error(message);
+  error.name = "PiQError";
+  return error;
+}
+
+function normalizeDate(value, flag) {
+  if (value === undefined || value === null) return null;
+  if (
+    typeof value !== "string" ||
+    !/^\d{4}-\d{2}-\d{2}(?:$|T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:?\d{2})?)$/.test(value) ||
+    !Number.isFinite(Date.parse(value))
+  )
+    throw piqError(`${flag} requires an ISO-8601 timestamp`);
+  return Date.parse(value);
+}
+
+function timestampOf(entry) {
+  return typeof entry?.timestamp === "string" ? entry.timestamp : null;
+}
+
+function inDateRange(entry, from, to) {
+  const timestamp = timestampOf(entry);
+  if (from === null && to === null) return true;
+  if (!timestamp) return false;
+  const value = Date.parse(timestamp);
+  if (!Number.isFinite(value)) return false;
+  return (from === null || value >= from) && (to === null || value <= to);
+}
+
+function roleMatches(entry, role) {
+  if (!role) return true;
+  const actual = entry?.message?.role;
+  return role === "tool" ? actual === "toolResult" : actual === role;
+}
+
+function entryRecord(entry, order, sessionId, leafId) {
+  // Keep the native object intact. The _piq envelope adds coordinates without
+  // interpreting or dropping fields from newer Pi versions.
+  return {
+    entry,
+    _piq: {
+      schemaVersion: PIQ_SCHEMA_VERSION,
+      kind: "entry",
+      sessionId,
+      branchLeafId: leafId,
+      branchOrder: order,
+    },
+  };
+}
+
+function toolRecords(branch, sessionId, leafId, mode) {
+  const records = [];
+  for (let order = 0; order < branch.length; order += 1) {
+    const entry = branch[order];
+    const messageRole = entry?.message?.role;
+    if (mode !== "tool-results" && messageRole === "assistant") {
+      const content = Array.isArray(entry?.message?.content)
+        ? entry.message.content
+        : [];
+      for (const [blockIndex, tool] of content.entries()) {
+        if (!tool || typeof tool !== "object") continue;
+        if (tool.type !== "toolCall" && tool.type !== "tool_call") continue;
+        records.push({
+          _piq: {
+            schemaVersion: PIQ_SCHEMA_VERSION,
+            kind: "tool-call",
+            sessionId,
+            branchLeafId: leafId,
+            branchOrder: order,
+            blockIndex,
+            entryId: entry.id ?? null,
+            timestamp: timestampOf(entry),
+          },
+          entry,
+          tool,
+        });
+      }
+    }
+    if (mode !== "tool-calls" && messageRole === "toolResult") {
+      records.push({
+        _piq: {
+          schemaVersion: PIQ_SCHEMA_VERSION,
+          kind: "tool-result",
+          sessionId,
+          branchLeafId: leafId,
+          branchOrder: order,
+          entryId: entry.id ?? null,
+          timestamp: timestampOf(entry),
+        },
+        entry,
+        toolResult: entry.message,
+      });
+    }
+  }
+  return records;
+}
+
+function throughCompactionBoundary(branch, compactionId) {
+  if (!compactionId) return branch;
+  const index =
+    compactionId === "latest"
+      ? branch.reduce(
+          (latest, entry, order) =>
+            entry?.type === "compaction" ? order : latest,
+          -1,
+        )
+      : branch.findIndex((entry) => entry?.id === compactionId);
+  if (index < 0)
+    throw piqError(
+      `Branch has no compaction boundary with ID ${compactionId}`,
+    );
+  if (branch[index]?.type !== "compaction")
+    throw piqError(`Session entry ${compactionId} is not a compaction boundary`);
+  return branch.slice(0, index + 1);
+}
+
+export function filterPiSessionEntries(
+  branch,
+  {
+    sessionId = null,
+    leafId = null,
+    role = null,
+    entryId = null,
+    from = null,
+    to = null,
+    throughCompaction = null,
+  } = {},
+) {
+  const bounded = throughCompaction
+    ? throughCompactionBoundary(branch, throughCompaction)
+    : branch;
+  return bounded
+    .map((entry, order) => ({ entry, order }))
+    .filter(({ entry }) =>
+      entryId === null || entryId === undefined ? true : entry.id === entryId,
+    )
+    .filter(({ entry }) => roleMatches(entry, role))
+    .filter(({ entry }) => inDateRange(entry, from, to))
+    .map(({ entry, order }) => entryRecord(entry, order, sessionId, leafId));
+}
+
+export function queryPiSessionEntries(loaded, options = {}) {
+  const from = normalizeDate(options.from, FROM_FLAG);
+  const to = normalizeDate(options.to, "--to");
+  if (from !== null && to !== null && from > to)
+    throw piqError(`${FROM_FLAG} must not be later than --to`);
+  return filterPiSessionEntries(loaded.branch, {
+    ...options,
+    sessionId: loaded.parsed.header.id,
+    leafId: loaded.leafId,
+    from,
+    to,
+    throughCompaction: options.throughCompaction,
+  });
+}
+
+export function queryPiSessionTools(loaded, options = {}) {
+  const from = normalizeDate(options.from, FROM_FLAG);
+  const to = normalizeDate(options.to, "--to");
+  if (from !== null && to !== null && from > to)
+    throw piqError(`${FROM_FLAG} must not be later than --to`);
+  if (
+    options.role &&
+    !["assistant", "toolResult", "tool"].includes(options.role)
+  )
+    throw piqError(
+      `Tool queries support only assistant, toolResult, or tool roles; received ${options.role}`,
+    );
+  const records = toolRecords(
+    throughCompactionBoundary(loaded.branch, options.throughCompaction),
+    loaded.parsed.header.id,
+    loaded.leafId,
+    options.kind === "tool-results"
+      ? "tool-results"
+      : options.kind === "tool-calls"
+        ? "tool-calls"
+        : "both",
+  );
+  return records.filter(({ _piq }) => {
+    const time = Date.parse(_piq.timestamp ?? "");
+    const roleMatches =
+      !options.role ||
+      (options.role === "assistant" && _piq.kind === "tool-call") ||
+      ((options.role === "toolResult" || options.role === "tool") &&
+        _piq.kind === "tool-result");
+    return (
+      roleMatches &&
+      (options.entryId === undefined ||
+        options.entryId === null ||
+        _piq.entryId === options.entryId) &&
+      (from === null || (Number.isFinite(time) && time >= from)) &&
+      (to === null || (Number.isFinite(time) && time <= to))
+    );
+  });
+}
+
+export function queryPiSessionCompactions(loaded, options = {}) {
+  return queryPiSessionEntries(loaded, options).filter(
+    ({ entry }) => entry?.type === "compaction",
+  );
+}
+
+export function queryPiSessionBranches(loaded) {
+  return listSessionBranches(loaded.parsed).map((branch) => ({
+    _piq: {
+      schemaVersion: PIQ_SCHEMA_VERSION,
+      kind: "branch",
+      sessionId: loaded.parsed.header.id,
+      branchLeafId: branch.leafId,
+    },
+    ...branch,
+    entryIds: resolveSessionBranch(
+      loaded.parsed,
+      { leafId: branch.leafId },
+      "Pi Session",
+    ).map((entry) => entry.id ?? null),
+  }));
+}
+
+/** Load once, resolve one explicit/default ancestry, then answer one PiQ. */
+export async function queryPiQ(
+  reference,
+  { kind = "entries", sessionRoot, leafId = null, ...options } = {},
+) {
+  if (kind === "branches" && leafId !== null)
+    throw piqError("Branch listing does not support --leaf");
+  const loaded = await readPiSession(reference, { sessionRoot, leafId });
+  if (kind === "branches") {
+    const unsupported = [
+      "role",
+      "entryId",
+      "f" + "rom",
+      "to",
+      "throughCompaction",
+    ].filter((name) => options[name] !== undefined && options[name] !== null);
+    if (unsupported.length)
+      throw piqError(
+        `Branch listing does not support filters: ${unsupported.join(", ")}`,
+      );
+  }
+  switch (kind) {
+    case "entries":
+      return queryPiSessionEntries(loaded, options);
+    case "tools":
+    case "tool-calls":
+    case "tool-results":
+      return queryPiSessionTools(loaded, { ...options, kind });
+    case "compactions":
+      return queryPiSessionCompactions(loaded, options);
+    case "branches":
+      return queryPiSessionBranches(loaded);
+    default:
+      throw piqError(`Unknown PiQ query: ${kind}`);
+  }
+}

package/src/rarebit-activity.mjs

@@ -1,3 +1,5 @@
+import { getImportedRarebitEntryIds } from "./rarebit-fork-lineage.mjs";
+
 // Native Rarebit selection is the source of these recency coordinates. This
 // module deliberately has no clock or renderer: consumers choose how (and
 // whether) to project an age from an exact active-branch snapshot.
@@ -25,6 +27,10 @@ export function projectRarebitSessionActivity(selection) {
   const occurrences = Array.isArray(selection?.occurrences)
     ? selection.occurrences
     : [];
+  const importedIds = getImportedRarebitEntryIds(selection?.entries);
+  const visibleOccurrences = occurrences.filter(
+    (occurrence) => !importedIds.has(occurrence?.sourceEntryId),
+  );
   return Object.freeze({
     schemaVersion: 1,
     selectorVersion:
@@ -36,11 +42,11 @@ export function projectRarebitSessionActivity(selection) {
         ? selection.manifestHash
         : null,
     latestUser: latest(
-      occurrences,
+      visibleOccurrences,
       (occurrence) => occurrence?.role === "user",
     ),
     latestAgentStop: latest(
-      occurrences,
+      visibleOccurrences,
       (occurrence) =>
         occurrence?.role === "assistant" && occurrence?.outcome === "stop",
     ),

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;
@@ -235,6 +255,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 +338,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);

package/src/rarebit-command.mjs

@@ -29,6 +29,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",

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);
+}