@hypercarrier/rarebit 0.1.0-alpha.1

package/AGENTS.md

@@ -0,0 +1,14 @@
+# Rarebit contributor guidance
+
+Rarebit is a standalone Pi package in a sharing-stage public alpha. Native Pi
+Session JSONL is historical evidence authority. Rarebit selections and sidecars
+must not replace it or claim Task, Project, runtime, or delivery truth.
+
+Keep the public surface small. Test CLI behavior, package boundaries, and Pi
+installation paths. Do not add private-helper mocks, export-count tests,
+coverage targets, or tautological snapshots. Run `npm ci`, `npm test`, and
+`npm run verify:package` before a release candidate.
+
+Do not record Session prose, provider credentials, Recall bundles, or private
+paths in issues, fixtures, logs, or release records. `README.md` owns user
+setup and privacy guidance. `RUNBOOK.md` owns operator recovery details.

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0-alpha.1 — 2026-08-02
+
+First standalone public-alpha candidate. It preserves the committed Rarebit
+source from HyperCarrier commit `945533d41e6c1f88718d12b744bc96202afbac21`.
+The package name is `@hypercarrier/rarebit` and the CLI is `rarebit`.
+
+This is an unstable alpha. Public APIs, CLI output, sidecar details, and visual
+marks can change before a stable release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HyperCarrier contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# Rarebit
+
+`@hypercarrier/rarebit` recovers decision-bearing conversational evidence from
+one persisted Pi Session. It deterministically selects readable user messages
+and assistant continuation or stop prose on the active branch. It excludes tool
+payloads, tool results, and hidden reasoning.
+
+Rarebit is public alpha software. Its CLI output, exports, sidecar protocol,
+and visual language can change. It is not a Task, Project, runtime, priority,
+attention, or delivery authority. Native Pi Session JSONL remains the evidence
+authority.
+
+## Install
+
+Use Node 22 or later and Pi 0.83 or later. Install it in Pi from npm:
+
+```sh
+pi install npm:@hypercarrier/rarebit@0.1.0-alpha.1
+pi list
+```
+
+For a local checkout, Pi loads a directory without copying it:
+
+```sh
+pi install /absolute/path/to/rarebit
+pi list
+```
+
+The package imports Pi's bundled `@earendil-works/pi-ai` as a peer dependency.
+Do not install or bundle a second Pi core. Pi packages execute with your user
+permissions, so review source before installation.
+
+To use the CLI in a normal Node project, install it and invoke the local bin
+with npm:
+
+```sh
+npm install @hypercarrier/rarebit@0.1.0-alpha.1
+npm exec -- rarebit --help
+```
+
+## First query and extract
+
+Give the CLI an exact Session JSONL path or supported Pi Session identifier.
+`query` returns metadata only. `extract` returns selected raw Session prose.
+
+```sh
+npm exec -- rarebit query --session /absolute/path/to/session.jsonl --json
+npm exec -- rarebit extract --session /absolute/path/to/session.jsonl --json
+```
+
+The Pi extension adds `/rarebit` controls after installation. It has `status`,
+`config`, `auto-title`, `title`, `summarize`, and `recall` subcommands.
+
+## Model setup and optional derivations
+
+Summary and Title use a dedicated configured model. They never inherit Pi's
+interactive `defaultModel`. Put this in global Pi settings, or in a trusted
+project's `.pi/settings.json`:
+
+```json
+{
+  "rarebit": {
+    "model": "provider/model",
+    "min_total_length": 80000,
+    "max_rarebit_ratio": 0.4,
+    "auto_title": true
+  }
+}
+```
+
+Then request explicit model work when you want it:
+
+```sh
+npm exec -- rarebit summarize --session /absolute/path/to/session.jsonl --json --force
+npm exec -- rarebit title --session /absolute/path/to/session.jsonl --json
+```
+
+A Summary is a lossy assessment of an identified selection. It can report only
+Session-scoped appearance, not completed Project or Task work. A Title is a
+mutable label proposal, not Session identity. Automatic Summary work runs only
+at persisted direct-input or settled-agent boundaries and only when its policy
+permits it.
+
+## Privacy, local data, and provider egress
+
+Rarebit reads Pi Session JSONL locally and does not modify it. `extract` prints
+selected raw prose, so handle its output as sensitive.
+
+Summary and Title send selected Rarebit prose to the provider and model that you
+configure. When input exceeds the fixed limit, Rarebit sends a newest suffix
+with an explicit omission marker. It does not send tool inputs, tool results,
+hidden reasoning, provider credentials, or HTTP headers as Rarebit content.
+
+Derived receipts live below `~/.pi/agent/rarebit/materializations-v4/`; job
+leases live below `~/.pi/agent/rarebit/jobs-v4/`. These directories use mode
+0700 and their files use mode 0600. Receipts retain compact metadata but no
+selected prose, prompt, provider response body, headers, or credentials. They
+remain until you remove them. Session JSONL retention is controlled by Pi.
+
+## First Recall
+
+Run `/rarebit recall <prompt>` in a Pi Session. Rarebit writes the exact active
+branch selection to two private files: a conversation view and detailed
+lineage evidence. It then sends one atomic user message. The message contains
+your exact request and absolute pointers to both files.
+
+When Pi is idle, that message starts one turn. When Pi is busy, it queues one
+steering message. Recall does not send a second follow-up, add a custom Session
+entry, or create a durable Recall receipt.
+
+The temporary directory is mode 0700 and its JSON files are mode 0600. The
+files remain after the request so Pi can read them; delete the directory after
+the turn no longer needs it. Both files and the persisted Pi envelope are
+sensitive. Do not put their paths or content in a ticket.
+
+## Update, uninstall, and rollback
+
+Pin alpha versions for reproducible installs:
+
+```sh
+pi install npm:@hypercarrier/rarebit@0.1.0-alpha.1
+pi update npm:@hypercarrier/rarebit
+pi remove npm:@hypercarrier/rarebit
+```
+
+To roll back, reinstall a known version with `pi install npm:@hypercarrier/rarebit@<version>`.
+Removal stops package loading. It does not alter Pi Session JSONL or delete
+Rarebit sidecars, job leases, or Recall temp files. Remove retained local data
+only after you review it.
+
+## Compatibility and support
+
+This alpha supports Node 22+ and Pi 0.83+. It works as a deterministic CLI
+without a model. Summary, Title, and the Pi extension require a compatible Pi
+installation and configured provider credentials.
+
+Report security issues privately as described in [SECURITY.md](SECURITY.md).
+Use https://github.com/deephbz/rarebit/issues for normal support. Include no
+Session prose, credentials, or Recall files in public reports.
+
+See [RUNBOOK.md](RUNBOOK.md) for recovery and sidecar details, and
+[VISUAL-LANGUAGE.md](VISUAL-LANGUAGE.md) for evidence-mark meaning.

package/RUNBOOK.md

@@ -0,0 +1,36 @@
+# Rarebit runbook
+
+Set `rarebit.model` in global Pi settings or in a trusted Project's
+`.pi/settings.json`. It must be `provider/model` or an object with `provider`
+and `id`. Rarebit fails closed when it is missing or invalid. It does not use
+Pi's interactive `defaultModel`.
+
+Run `pi update npm:@hypercarrier/rarebit` to update an npm installation. Run
+`pi remove npm:@hypercarrier/rarebit` to stop loading it. These commands do not
+modify native Sessions or remove Rarebit retained data.
+
+Inspect derived state without treating it as a transcript:
+
+```sh
+npm exec -- rarebit query --session <exact-session.jsonl> --json
+npm exec -- rarebit extract --session <exact-session.jsonl> --json
+```
+
+The current protocol reads only `materializations-v4`. A `rarebit_head` is the
+fenced semantic-current pointer. Do not select the physical last JSONL line.
+
+If a crash leaves an adjacent `.commit-lock`, first verify no Rarebit writer for
+that Session is alive. Then remove only that lock. Age alone does not authorize
+removal.
+
+Automatic summaries require both the configured minimum estimated length and
+maximum selected-prose ratio. `npm exec -- rarebit summarize --force` and
+`/rarebit summarize` are explicit requests. The receipt records input coverage.
+
+Selected evidence contains user messages.
+
+Recall bundles are private OS-temp files with selected content. One user
+message contains the exact request and both private file pointers. When Pi is
+idle it starts one turn. When Pi is busy it queues one steering message. Delete
+the bundle after that turn no longer needs it. Do not put its paths or contents
+in a ticket.

package/SECURITY.md

@@ -0,0 +1,11 @@
+# Security
+
+Report a security issue privately through GitHub Security Advisories for
+`deephbz/rarebit`. Do not put credentials, Session content, or Recall files in
+a public issue.
+
+For non-sensitive help, use the GitHub issue tracker:
+https://github.com/deephbz/rarebit/issues
+
+This alpha has no response-time commitment. Include the Rarebit version, Pi
+version, Node version, and safe reproduction steps.

package/VISUAL-LANGUAGE.md

@@ -0,0 +1,89 @@
+# Rarebit visual language
+
+Status: first-version implementation; awaiting cross-surface real-trace ratification
+
+This file is the canonical visual guidance shipped with the Rarebit extension. A fork may deliberately replace it. The typed roles, statuses, and reasons in [`src/types.d.ts`](src/types.d.ts) remain the semantic machine contract; [`src/rarebit-visual-language.mjs`](src/rarebit-visual-language.mjs) owns the executable marks, labels, tones, and source-pending attention gate. This document owns perceptual intent and the human-review projection of that mapping. It does not claim every consumer already conforms.
+
+## Marker grammar and preview
+
+This single table is the human-review projection and preview of the executable marker grammar. It uses inline HTML, so there is no second authored preview document. Renderers that preserve raw HTML and `style` attributes show the color column; restrictive renderers retain the monochrome-safe column.
+
+The scopes are deliberately different: Session-history events are repeatable, time- or sequence-anchored evidence; a Summary status snapshot is one as-of assessment and never becomes an event on that axis.
+
+<table aria-label="Official Rarebit marker grammar and preview">
+  <thead>
+    <tr>
+      <th>Scope</th>
+      <th>Meaning</th>
+      <th>Color</th>
+      <th>Monochrome</th>
+      <th>Salience</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td rowspan="4">Session-history event</td>
+      <td>User message</td>
+      <td><span style="color: #15803d; font-size: 1.35em">□</span> user message</td>
+      <td>□ user message</td>
+      <td>standard</td>
+    </tr>
+    <tr>
+      <td>Agent continuation</td>
+      <td><span style="color: #2563eb; font-size: 1.1em">•</span> agent continues</td>
+      <td>• agent continues</td>
+      <td>smaller</td>
+    </tr>
+    <tr>
+      <td>Agent stop</td>
+      <td><span style="color: #334155; font-size: 1.35em">●</span> agent stops</td>
+      <td>● agent stops</td>
+      <td>larger</td>
+    </tr>
+    <tr>
+      <td>Exceptional terminal</td>
+      <td><span style="color: #b91c1c; font-size: 1.25em">×</span> terminal error</td>
+      <td>× terminal error</td>
+      <td>diagnostic</td>
+    </tr>
+    <tr>
+      <td rowspan="5">Summary status snapshot</td>
+      <td><code>user_requested</code></td>
+      <td><span style="color: #334155">request recorded</span></td>
+      <td>request recorded</td>
+      <td>ordinary</td>
+    </tr>
+    <tr>
+      <td><code>finished</code></td>
+      <td><span style="color: #334155">appears finished</span></td>
+      <td>appears finished</td>
+      <td>ordinary</td>
+    </tr>
+    <tr>
+      <td><code>needs_attention</code></td>
+      <td><span style="color: #9a3412; background: #fff7ed">◆!</span> needs you</td>
+      <td>◆! needs you</td>
+      <td>attention</td>
+    </tr>
+    <tr>
+      <td><code>ineligible</code></td>
+      <td><span style="color: #71717a; font-weight: 300">ineligible</span></td>
+      <td><span style="font-weight: 300">ineligible</span></td>
+      <td>muted</td>
+    </tr>
+    <tr>
+      <td><code>error</code></td>
+      <td><span style="color: #b91c1c">×</span> error</td>
+      <td>× error</td>
+      <td>diagnostic</td>
+    </tr>
+  </tbody>
+</table>
+
+There is one user-message category, and every selected user message uses the same visual role. The smaller solid continuation dot means work continues. The larger solid stop circle marks a reported response boundary, not verified completion. Supporting intervals paint first, then continuations, stops and errors, and user messages last. Selection adds a halo without replacing the canonical mark.
+
+Summary reasons such as `decision`, `blocker`, or `unfinished` are secondary text, never new colors or shapes. Summary prose uses normal body styling. Attention is the only Summary result with a high-salience mark or optional sound. Finished has no green, checkmark, or success treatment because it is an appearance-level Session assessment, not proof that a Task, Project, tool run, or delivery succeeded. Error is diagnostic and never produces the attention sound.
+
+Synchronization and applicability qualify a result; they are not additional statuses. Append `· source pending` when applicable, expose detailed sync/applicability in an inspector, and withhold the attention mark and sound until readable native evidence confirms a current result. Never publish `syncing` as a Summary status. Consumers support only the current package projection and don't translate unsupported receipt shapes into visual meaning.
+
+Every mark has an accessible text label. Do not rely on color, hover, or sound. A muted monochrome snapshot may use lighter weight or terminal `dim`, but its text must remain readable and meet WCAG 2.2 AA where applicable. Terminal renderers preserve the monochrome mark and label with the closest theme-safe ANSI treatment. Consumers import the package mapping rather than inventing another one, cite this file for perceptual intent, and keep application layout local.

package/bin/rarebit.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import {
+  RAREBIT_CLI_USAGE,
+  parseRarebitCliArgs,
+  runRarebitCli,
+} from "../src/rarebit-cli.mjs";
+
+try {
+  const options = parseRarebitCliArgs(process.argv.slice(2));
+  if (options.help) process.stdout.write(`${RAREBIT_CLI_USAGE}\n`);
+  else
+    process.stdout.write(
+      `${JSON.stringify(await runRarebitCli(options), null, 2)}\n`,
+    );
+} catch (error) {
+  process.stderr.write(
+    `${error?.message ?? String(error)}\n${RAREBIT_CLI_USAGE}\n`,
+  );
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "@hypercarrier/rarebit",
+  "version": "0.1.0-alpha.1",
+  "description": "Sparse, provenance-bearing conversational evidence recovery for Pi sessions.",
+  "license": "MIT",
+  "author": "HyperCarrier contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deephbz/rarebit.git"
+  },
+  "homepage": "https://github.com/deephbz/rarebit#readme",
+  "bugs": {
+    "url": "https://github.com/deephbz/rarebit/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "rarebit",
+    "pi",
+    "session"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "types": "./src/types.d.ts",
+  "bin": {
+    "rarebit": "./bin/rarebit.mjs"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "test:e2e:summary-cache": "node scripts/e2e-summary-cache.mjs",
+    "test:e2e:recall": "node scripts/e2e-recall-pi083.mjs",
+    "verify:package": "node scripts/verify-package.mjs"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*"
+  },
+  "devDependencies": {
+    "ajv": "^6.15.0",
+    "typescript": "^5.9.3"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension.mjs"
+    ]
+  },
+  "exports": {
+    ".": {
+      "types": "./src/types.d.ts",
+      "import": "./src/index.mjs"
+    },
+    "./core": {
+      "types": "./src/types.d.ts",
+      "import": "./src/rarebit-core.mjs"
+    },
+    "./session": {
+      "types": "./src/types.d.ts",
+      "import": "./src/rarebit-session.mjs"
+    },
+    "./service": {
+      "types": "./src/types.d.ts",
+      "import": "./src/rarebit-service.mjs"
+    },
+    "./artifact-state": {
+      "types": "./src/types.d.ts",
+      "import": "./src/rarebit-artifact-state.mjs"
+    },
+    "./visual-language": {
+      "types": "./src/types.d.ts",
+      "import": "./src/rarebit-visual-language.mjs"
+    },
+    "./extension": {
+      "types": "./src/types.d.ts",
+      "import": "./src/extension.mjs"
+    },
+    "./types": "./src/types.d.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "bin/rarebit.mjs",
+    "src",
+    "schemas",
+    "scripts",
+    "test",
+    "README.md",
+    "RUNBOOK.md",
+    "VISUAL-LANGUAGE.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "SECURITY.md"
+  ]
+}