@hypercarrier/rarebit 0.1.0-alpha.5 → 0.2.0

package/src/pi-session.mjs

@@ -0,0 +1,237 @@
+import { open, readFile, readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+
+export const DEFAULT_PI_SESSION_ROOT = join(
+  homedir(),
+  ".pi",
+  "agent",
+  "sessions",
+);
+
+function queryError(message) {
+  const error = new Error(message);
+  error.name = "PiSessionQueryError";
+  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 one exact path or one unambiguous persisted Session ID. */
+export async function resolvePiSessionFile(
+  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]);
+}
+
+/** Parse native JSONL without normalizing away unknown evidence fields. */
+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 ||
+    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 version = header.version ?? 1;
+  if (typeof version !== "number" || !Number.isInteger(version) || version < 1)
+    throw queryError(`${source} has an invalid Session version`);
+  const byId = new Map();
+  const linear = version < 2;
+  if (!linear) {
+    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 };
+}
+
+function ancestryFromLeaf(parsed, leaf, source) {
+  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;
+    if (typeof current.parentId !== "string" || !current.parentId)
+      throw queryError(`${source} contains an invalid parent ID at ${current.id}`);
+    current = parsed.byId.get(current.parentId);
+    if (!current)
+      throw queryError(
+        `${source} is missing parent Session entry ${reversed.at(-1).parentId}`,
+      );
+  }
+  return reversed.reverse();
+}
+
+/** Resolve the persisted active branch. The final entry is Pi's default leaf. */
+export function resolveActiveBranch(parsed, source = "Pi Session") {
+  if (parsed.linear) return parsed.entries.slice();
+  const leaf = parsed.entries.at(-1);
+  return leaf ? ancestryFromLeaf(parsed, leaf, source) : [];
+}
+
+/** Resolve one explicit leaf, or the native default leaf when omitted. */
+export function resolveSessionBranch(
+  parsed,
+  { leafId = null } = {},
+  source = "Pi Session",
+) {
+  if (parsed.linear) {
+    if (leafId !== null && leafId !== undefined)
+      throw queryError(
+        `${source} uses a linear format and has no explicit branch leaf`,
+      );
+    return parsed.entries.slice();
+  }
+  const leaf =
+    leafId === null || leafId === undefined
+      ? parsed.entries.at(-1)
+      : parsed.byId.get(leafId);
+  if (!leaf) {
+    if (leafId === null || leafId === undefined) return [];
+    throw queryError(`${source} has no Session entry with leaf ID ${leafId}`);
+  }
+  return ancestryFromLeaf(parsed, leaf, source);
+}
+
+function childIds(parsed) {
+  const children = new Set();
+  if (parsed.linear) return children;
+  for (const entry of parsed.entries) {
+    if (entry.parentId !== null && entry.parentId !== undefined) {
+      if (!parsed.byId.has(entry.parentId)) continue;
+      children.add(entry.parentId);
+    }
+  }
+  return children;
+}
+
+/** Return every persisted leaf in file order; no timestamp-based inference. */
+export function listSessionBranches(parsed, source = "Pi Session") {
+  if (parsed.linear) {
+    return parsed.entries.length
+      ? [{ leafId: null, entryCount: parsed.entries.length }]
+      : [];
+  }
+  // Validate every connected component before looking for leaves. A cycle has
+  // no leaf and must remain an explicit error instead of an empty branch list.
+  for (const entry of parsed.entries) ancestryFromLeaf(parsed, entry, source);
+  const children = childIds(parsed);
+  return parsed.entries
+    .filter((entry) => !children.has(entry.id))
+    .map((entry) => ({
+      leafId: entry.id,
+      entryCount: ancestryFromLeaf(parsed, entry, source).length,
+    }));
+}
+
+export async function readPiSession(reference, options = {}) {
+  const sessionFile = await resolvePiSessionFile(reference, options);
+  const parsed = parseNativeSession(
+    await readFile(sessionFile, "utf8"),
+    sessionFile,
+  );
+  const branch = resolveSessionBranch(
+    parsed,
+    { leafId: options.leafId ?? null },
+    sessionFile,
+  );
+  return {
+    sessionFile,
+    parsed,
+    branch,
+    leafId: parsed.linear ? null : (branch.at(-1)?.id ?? null),
+  };
+}

package/src/piq-cli.mjs

@@ -0,0 +1,96 @@
+import { queryPiQ } from "./piq.mjs";
+
+const FROM_FLAG = "--from";
+
+export const PIQ_CLI_USAGE = `Usage:
+  piq <entries|branches|tools|tool-calls|tool-results|compactions> --session <exact-path-or-id> [options]
+
+Options:
+  --leaf <entry-id>                 Read one explicit branch leaf (default: native active leaf)
+  --entry-id <entry-id>             Restrict entries or tools to one native entry ID
+  --role <role>                     Restrict entries to a native message role
+  --from <ISO-8601>                 Include evidence at or after this timestamp
+  --to <ISO-8601>                   Include evidence at or before this timestamp
+  --through-compaction <entry-id>  Stop the branch at this compaction boundary (or latest)
+
+PiQ writes one JSON object per result line. It never writes the source Session.`;
+
+function value(argv, index, flag) {
+  const next = argv[index + 1];
+  if (!next || next.startsWith("--")) throw new Error(`${flag} requires a value`);
+  return next;
+}
+
+export function parsePiQCliArgs(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) return { help: true };
+  const [first, ...rest] = argv;
+  const commands = new Set([
+    "entries",
+    "branches",
+    "tools",
+    "tool-calls",
+    "tool-results",
+    "compactions",
+  ]);
+  const kind = commands.has(first) ? first : "entries";
+  const args = commands.has(first) ? rest : argv;
+  const options = { kind };
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    switch (argument) {
+      case "--session":
+        options.session = value(args, index, argument);
+        index += 1;
+        break;
+      case "--leaf":
+        options.leafId = value(args, index, argument);
+        index += 1;
+        break;
+      case "--entry-id":
+        options.entryId = value(args, index, argument);
+        index += 1;
+        break;
+      case "--role":
+        options.role = value(args, index, argument);
+        index += 1;
+        break;
+      case FROM_FLAG:
+        options.from = value(args, index, argument);
+        index += 1;
+        break;
+      case "--to":
+        options.to = value(args, index, argument);
+        index += 1;
+        break;
+      case "--through-compaction":
+        options.throughCompaction = value(args, index, argument);
+        index += 1;
+        break;
+      case "--session-root":
+        options.sessionRoot = value(args, index, argument);
+        index += 1;
+        break;
+      case "--jsonl":
+      case "--json":
+        break;
+      default:
+        throw new Error(`Unknown argument: ${argument}`);
+    }
+  }
+  if (!options.session) throw new Error("--session is required");
+  return options;
+}
+
+export async function runPiQCli(options, dependencies = {}) {
+  const query = dependencies.query ?? queryPiQ;
+  return query(options.session, {
+    kind: options.kind,
+    leafId: options.leafId,
+    sessionRoot: options.sessionRoot,
+    entryId: options.entryId,
+    role: options.role,
+    from: options.from,
+    to: options.to,
+    throughCompaction: options.throughCompaction,
+  });
+}

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",
     ),