@hypercarrier/rarebit 0.1.0-alpha.1

package/src/rarebit-model.mjs

@@ -0,0 +1,226 @@
+/** Pi-facing model adapter. It is deliberately outside the functional core. */
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function finiteNonNegative(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? value
+    : null;
+}
+
+export function resolveRarebitModelConfiguration(config = {}) {
+  if (config.modelConfigurationError) {
+    return {
+      ok: false,
+      model: null,
+      provenance: {
+        source: "configuration",
+        settingsKey: "rarebit.model",
+        status: "invalid",
+        ...config.modelProvenance,
+      },
+      error: String(config.modelConfigurationError),
+    };
+  }
+  const provider = nonEmptyString(config.model?.provider);
+  const id = nonEmptyString(config.model?.id);
+  if (!provider || !id) {
+    return {
+      ok: false,
+      model: null,
+      provenance: {
+        source: "configuration",
+        settingsKey: "rarebit.model",
+        status: "missing",
+        ...config.modelProvenance,
+      },
+      error:
+        "No Rarebit model resolved; set rarebit.model in Pi settings or inject config.model",
+    };
+  }
+  return {
+    ok: true,
+    model: { provider, id },
+    provenance: {
+      source: "explicit_config",
+      status: "resolved",
+      ...config.modelProvenance,
+    },
+  };
+}
+
+export async function createPiRarebitModelClient(ctx, config = {}) {
+  const { complete, getModel } = config.piAi ?? {};
+  if (typeof complete !== "function")
+    throw new Error(
+      "Pi AI contract is unavailable; load the Rarebit Pi extension or provide modelClient/piAi",
+    );
+  const resolution = resolveRarebitModelConfiguration(config);
+  if (!resolution.ok) throw new Error(resolution.error);
+  const model =
+    ctx?.modelRegistry?.find?.(
+      resolution.model.provider,
+      resolution.model.id,
+    ) ??
+    (typeof getModel === "function"
+      ? getModel(resolution.model.provider, resolution.model.id)
+      : undefined);
+  if (!model)
+    throw new Error(
+      `Pi model not found: ${resolution.model.provider}/${resolution.model.id}`,
+    );
+  const auth = await ctx?.modelRegistry?.getApiKeyAndHeaders?.(model);
+  if (!auth?.ok)
+    throw new Error(
+      auth?.error ??
+        `No request auth for ${resolution.model.provider}/${resolution.model.id}`,
+    );
+  return {
+    async complete(request) {
+      return complete(
+        model,
+        {
+          messages: [
+            {
+              role: "user",
+              content: [{ type: "text", text: request.prompt }],
+              timestamp: Date.now(),
+            },
+          ],
+        },
+        {
+          apiKey: auth.apiKey,
+          headers: auth.headers,
+          env: auth.env,
+          reasoningEffort: "low",
+          sessionId: nonEmptyString(request.cacheSessionId),
+        },
+      );
+    },
+  };
+}
+
+function firstNumber(response, paths) {
+  for (const [source, get] of paths) {
+    const value = finiteNonNegative(get(response));
+    if (value !== null) return { value, source };
+  }
+  return { value: null, source: null };
+}
+
+function firstString(response, paths) {
+  for (const [source, get] of paths) {
+    const value = nonEmptyString(get(response));
+    if (value) return { value, source };
+  }
+  return { value: null, source: null };
+}
+
+/** A bounded, machine-only provider receipt. Prompts and raw responses never enter it. */
+export function extractRarebitSynthesisReceipt(
+  response,
+  {
+    requestedModel,
+    startedAt,
+    completedAt,
+    durationMs,
+    outcome = "response",
+  } = {},
+) {
+  const fields = {
+    inputTokens: firstNumber(response, [
+      ["response.usage.input", (r) => r?.usage?.input],
+      ["response.usage.input_tokens", (r) => r?.usage?.input_tokens],
+      ["response.usage.prompt_tokens", (r) => r?.usage?.prompt_tokens],
+    ]),
+    outputTokens: firstNumber(response, [
+      ["response.usage.output", (r) => r?.usage?.output],
+      ["response.usage.output_tokens", (r) => r?.usage?.output_tokens],
+      ["response.usage.completion_tokens", (r) => r?.usage?.completion_tokens],
+    ]),
+    totalTokens: firstNumber(response, [
+      ["response.usage.totalTokens", (r) => r?.usage?.totalTokens],
+      ["response.usage.total_tokens", (r) => r?.usage?.total_tokens],
+    ]),
+    cacheReadTokens: firstNumber(response, [
+      ["response.usage.cacheRead", (r) => r?.usage?.cacheRead],
+      ["response.usage.cached_tokens", (r) => r?.usage?.cached_tokens],
+    ]),
+    cacheWriteTokens: firstNumber(response, [
+      ["response.usage.cacheWrite", (r) => r?.usage?.cacheWrite],
+    ]),
+    reasoningTokens: firstNumber(response, [
+      ["response.usage.reasoning", (r) => r?.usage?.reasoning],
+      [
+        "response.usage.output_tokens_details.reasoning_tokens",
+        (r) => r?.usage?.output_tokens_details?.reasoning_tokens,
+      ],
+    ]),
+    estimatedCostUsd: firstNumber(response, [
+      ["response.usage.cost.total", (r) => r?.usage?.cost?.total],
+      ["response.usage.total_cost", (r) => r?.usage?.total_cost],
+    ]),
+  };
+  const measured = Object.values(fields).filter(
+    ({ value }) => value !== null,
+  ).length;
+  const availability =
+    measured === 0
+      ? "unavailable"
+      : fields.inputTokens.value !== null &&
+          fields.outputTokens.value !== null &&
+          fields.totalTokens.value !== null
+        ? "reported"
+        : "partial";
+  const responseId = firstString(response, [
+    ["response.responseId", (r) => r?.responseId],
+    ["response.id", (r) => r?.id],
+  ]);
+  const requestId = firstString(response, [
+    ["response.requestId", (r) => r?.requestId],
+  ]);
+  const responseProvider = firstString(response, [
+    ["response.provider", (r) => r?.provider],
+  ]);
+  const responseModel = firstString(response, [
+    ["response.responseModel", (r) => r?.responseModel],
+    ["response.model", (r) => r?.model],
+  ]);
+  return {
+    schemaVersion: 1,
+    kind: "rarebit_model_synthesis",
+    outcome,
+    requestedModel: requestedModel ?? null,
+    timing: {
+      startedAt: startedAt ?? null,
+      completedAt: completedAt ?? null,
+      durationMs: finiteNonNegative(durationMs),
+      provenance: "local_monotonic_clock",
+    },
+    provider: {
+      responseProvider: responseProvider.value,
+      responseProviderSource: responseProvider.source,
+      responseModel: responseModel.value,
+      responseModelSource: responseModel.source,
+      responseId: responseId.value,
+      responseIdSource: responseId.source,
+      requestId: requestId.value,
+      requestIdSource: requestId.source,
+    },
+    usage: {
+      availability,
+      inputTokens: fields.inputTokens.value,
+      outputTokens: fields.outputTokens.value,
+      totalTokens: fields.totalTokens.value,
+      cacheReadTokens: fields.cacheReadTokens.value,
+      cacheWriteTokens: fields.cacheWriteTokens.value,
+      reasoningTokens: fields.reasoningTokens.value,
+      estimatedCostUsd: fields.estimatedCostUsd.value,
+      provenance: Object.fromEntries(
+        Object.entries(fields).map(([name, field]) => [name, field.source]),
+      ),
+    },
+  };
+}

package/src/rarebit-recall.mjs

@@ -0,0 +1,182 @@
+import { constants } from "node:fs";
+import { access, chmod, mkdtemp, open, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+
+import { selectRarebits } from "./rarebit-core.mjs";
+
+export const RAREBIT_RECALL_SCHEMA_VERSION = 1;
+export const RAREBIT_CONVERSATION_SCHEMA_VERSION = 1;
+export const RAREBIT_RECALL_DETAILED_FILENAME = "rarebit-evidence.json";
+export const RAREBIT_RECALL_CONVERSATION_FILENAME = "rarebit-conversation.json";
+
+function requiredSessionIdentity(ctx) {
+  const sessionFile = ctx?.sessionManager?.getSessionFile?.();
+  if (typeof sessionFile !== "string" || !sessionFile.trim()) {
+    throw new Error("the current Pi Session has no persisted JSONL file");
+  }
+  const sessionId = ctx?.sessionManager?.getHeader?.()?.id ?? ctx?.sessionId;
+  if (typeof sessionId !== "string" || !sessionId.trim()) {
+    throw new Error("the current Pi Session has no stable ID");
+  }
+  return { sessionId, sessionFile: resolve(sessionFile) };
+}
+
+function activeBranchFrom(ctx) {
+  const branch = ctx?.sessionManager?.getBranch?.();
+  if (!Array.isArray(branch)) {
+    throw new Error("the current Pi Session active branch is unavailable");
+  }
+  return branch;
+}
+
+function recallDocument({ sessionId, sessionFile, branch, selection, now }) {
+  return {
+    schemaVersion: RAREBIT_RECALL_SCHEMA_VERSION,
+    type: "rarebit_message_recall",
+    createdAt: now().toISOString(),
+    evidenceAuthority: {
+      type: "pi_session_jsonl",
+      path: sessionFile,
+    },
+    session: {
+      id: sessionId,
+      activeBranch: {
+        leafEntryId: branch.at(-1)?.id ?? null,
+        entryIds: branch.map((entry) => entry?.id ?? null),
+      },
+    },
+    selection: {
+      selectorVersion: selection.manifest.selectorVersion,
+      manifestHash: selection.manifestHash,
+      occurrenceCount: selection.occurrences.length,
+      uniquePayloadCount: selection.payloads.length,
+      occurrences: selection.occurrences.map(
+        ({
+          occurrenceId,
+          sourceEntryId,
+          order,
+          timestamp,
+          role,
+          outcome,
+          contentHash,
+          text,
+        }) => ({
+          occurrenceId,
+          sourceEntryId,
+          order,
+          timestamp,
+          role,
+          outcome,
+          contentHash,
+          text,
+        }),
+      ),
+    },
+  };
+}
+
+function conversationHour(timestamp) {
+  if (typeof timestamp !== "string") return null;
+  const value = new Date(timestamp);
+  if (Number.isNaN(value.getTime())) return null;
+  return `${value.toISOString().slice(0, 13)}:00Z`;
+}
+
+function conversationDocument(selection) {
+  const byHour = new Map();
+  for (const occurrence of selection.occurrences) {
+    const hour = conversationHour(occurrence.timestamp);
+    let bucket = byHour.get(hour);
+    if (!bucket) {
+      bucket = { hour, messages: [] };
+      byHour.set(hour, bucket);
+    }
+    bucket.messages.push({
+      role: occurrence.role === "user" ? "user" : "agent",
+      content: occurrence.text,
+    });
+  }
+  const hours = [...byHour.values()].sort((left, right) => {
+    if (left.hour === null) return right.hour === null ? 0 : 1;
+    if (right.hour === null) return -1;
+    return left.hour.localeCompare(right.hour);
+  });
+  return {
+    schemaVersion: RAREBIT_CONVERSATION_SCHEMA_VERSION,
+    type: "rarebit_conversation",
+    timeZone: "UTC",
+    hours,
+  };
+}
+
+async function writePrivateJson(path, document) {
+  const handle = await open(path, "wx", 0o600);
+  try {
+    await handle.writeFile(`${JSON.stringify(document, null, 2)}\n`, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await chmod(path, 0o600);
+}
+
+/**
+ * Materialize an exact, active-branch Rarebit evidence projection for one
+ * one-off Recall. The native Session remains authority; this bundle is
+ * an ephemeral, private transport artifact and is never written to the repo.
+ */
+export async function materializeRarebitRecall(
+  ctx,
+  {
+    tempRoot = tmpdir(),
+    now = () => new Date(),
+    writeJson = writePrivateJson,
+  } = {},
+) {
+  const { sessionId, sessionFile } = requiredSessionIdentity(ctx);
+  await access(sessionFile, constants.R_OK);
+  const branch = activeBranchFrom(ctx);
+  const selection = selectRarebits(branch);
+  const root = resolve(tempRoot);
+  const directory = await mkdtemp(join(root, "hc-rarebit-recall-"));
+  const conversationPath = join(
+    directory,
+    RAREBIT_RECALL_CONVERSATION_FILENAME,
+  );
+  const detailedPath = join(directory, RAREBIT_RECALL_DETAILED_FILENAME);
+
+  try {
+    await chmod(directory, 0o700);
+    const detailed = recallDocument({
+      sessionId,
+      sessionFile,
+      branch,
+      selection,
+      now,
+    });
+    const conversation = conversationDocument(selection);
+    await writeJson(conversationPath, conversation);
+    await writeJson(detailedPath, detailed);
+    if (!isAbsolute(conversationPath) || !isAbsolute(detailedPath)) {
+      throw new Error(
+        "Rarebit recall materialization did not produce absolute paths",
+      );
+    }
+    return {
+      conversationPath,
+      detailedPath,
+      directory,
+      sessionId,
+      sessionFile,
+      branchLeafId: detailed.session.activeBranch.leafEntryId,
+      selectedMessageCount: selection.occurrences.length,
+      selectorVersion: selection.manifest.selectorVersion,
+      manifestHash: selection.manifestHash,
+      discard: () => rm(directory, { recursive: true, force: true }),
+    };
+  } catch (error) {
+    await rm(directory, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+}