@hypercarrier/rarebit 0.1.0-alpha.2 → 0.1.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.1.0-alpha.3 — 2026-08-02
+
+- Recall now sends one human-readable Markdown user message with the exact request and local private JSON evidence references. Idle and busy steer behavior remains unchanged, and JSON files remain machine authority.
+
 ## 0.1.0-alpha.2 — 2026-08-02
 
 First promoted OIDC prerelease candidate. This corrective release has no

package/README.md

@@ -15,7 +15,7 @@ authority.
 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.2
+pi install npm:@hypercarrier/rarebit@0.1.0-alpha.3
 pi list
 ```
 
@@ -34,7 +34,7 @@ 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.2
+npm install @hypercarrier/rarebit@0.1.0-alpha.3
 npm exec -- rarebit --help
 ```
 
@@ -101,8 +101,8 @@ remain until you remove them. Session JSONL retention is controlled by Pi.
 
 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.
+lineage evidence. It then sends one atomic, human-readable Markdown user
+message containing 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
@@ -110,7 +110,7 @@ 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
+the turn no longer needs it. Both files and the persisted Pi message are
 sensitive. Do not put their paths or content in a ticket.
 
 ## Update, uninstall, and rollback
@@ -118,7 +118,7 @@ sensitive. Do not put their paths or content in a ticket.
 Pin alpha versions for reproducible installs:
 
 ```sh
-pi install npm:@hypercarrier/rarebit@0.1.0-alpha.2
+pi install npm:@hypercarrier/rarebit@0.1.0-alpha.3
 pi update npm:@hypercarrier/rarebit
 pi remove npm:@hypercarrier/rarebit
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypercarrier/rarebit",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "description": "Sparse, provenance-bearing conversational evidence recovery for Pi sessions.",
   "license": "MIT",
   "author": "HyperCarrier contributors",

package/scripts/e2e-recall-pi083.mjs

@@ -15,6 +15,55 @@ async function waitFor(predicate, label, timeout = 2_000) {
   }
 }
 
+function expectedRecallMarkdown(conversationPath, detailedPath, request) {
+  return `# Rarebit Recall
+
+*Use these local private evidence files to recover historical context for this turn.*
+
+## How to use this bundle
+
+1. Treat **Current request** below as the exact current user request.
+2. Read **Conversation** first for meaning.
+3. Use **Detailed evidence** only for source, Session, branch, or lineage facts.
+4. Answer the current request using this evidence.
+
+## Local private evidence files
+
+**Conversation** — \`rarebit_conversation/v1\`
+
+\`\`\`text
+${conversationPath}
+\`\`\`
+
+**Detailed evidence** — \`rarebit_message_recall/v1\`
+
+\`\`\`text
+${detailedPath}
+\`\`\`
+
+## Current request
+
+\`\`\`text
+${request}
+\`\`\``;
+}
+
+function conversationPathFrom(message) {
+  const match = message.match(
+    /\*\*Conversation\*\* — `rarebit_conversation\/v1`\n\n```text\n([^\n]*rarebit-conversation\.json)\n```/,
+  );
+  assert.ok(match, "Recall Markdown must contain the fenced conversation path");
+  return match[1];
+}
+
+function detailedPathFrom(message) {
+  const match = message.match(
+    /\*\*Detailed evidence\*\* — `rarebit_message_recall\/v1`\n\n```text\n([^\n]*rarebit-evidence\.json)\n```/,
+  );
+  assert.ok(match, "Recall Markdown must contain the fenced detailed path");
+  return match[1];
+}
+
 const root =
   process.env.PI_CODING_AGENT_ROOT ??
   resolve(
@@ -107,11 +156,20 @@ try {
     .filter((entry) => JSON.stringify(entry).includes("exact idle request"));
   assert.equal(userEntries.length, 1);
   const message = userEntries[0].message ?? userEntries[0];
-  const envelope = JSON.parse(message.content[0].text);
-  recallDirectories.push(dirname(envelope.files.conversation.path));
-  assert.equal(envelope.request.text, "exact idle request");
-  await access(envelope.files.conversation.path);
-  await access(envelope.files.detailedEvidence.path);
+  const idleMessageText = message.content[0].text;
+  const idleConversationPath = conversationPathFrom(idleMessageText);
+  const idleDetailedPath = detailedPathFrom(idleMessageText);
+  assert.equal(
+    idleMessageText,
+    expectedRecallMarkdown(
+      idleConversationPath,
+      idleDetailedPath,
+      "exact idle request",
+    ),
+  );
+  recallDirectories.push(dirname(idleConversationPath));
+  await access(idleConversationPath);
+  await access(idleDetailedPath);
   assert.equal(
     manager
       .getBranch()
@@ -141,29 +199,29 @@ try {
   assert.equal(queued.steering.length, 1);
   assert.equal(queued.followUp?.length ?? 0, 0);
   const queuedMessage = queued.steering[0];
-  const busyEnvelope = JSON.parse(
+  const busyMessageText =
     typeof queuedMessage === "string"
       ? queuedMessage
-      : (queuedMessage.content?.[0]?.text ?? queuedMessage.content),
+      : (queuedMessage.content?.[0]?.text ?? queuedMessage.content);
+  const busyConversationPath = conversationPathFrom(busyMessageText);
+  const busyDetailedPath = detailedPathFrom(busyMessageText);
+  assert.equal(
+    busyMessageText,
+    expectedRecallMarkdown(
+      busyConversationPath,
+      busyDetailedPath,
+      "exact busy request",
+    ),
   );
-  recallDirectories.push(dirname(busyEnvelope.files.conversation.path));
-  await access(busyEnvelope.files.conversation.path);
-  await access(busyEnvelope.files.detailedEvidence.path);
-  assert.equal(busyEnvelope.request.text, "exact busy request");
+  recallDirectories.push(dirname(busyConversationPath));
+  await access(busyConversationPath);
+  await access(busyDetailedPath);
   releaseBusy();
   await busyRun;
   await session.agent.waitForIdle();
   assert.equal(provider.state.callCount, 4);
   const recallCount = (texts) =>
-    texts
-      .map((text) => {
-        try {
-          return JSON.parse(text);
-        } catch {
-          return null;
-        }
-      })
-      .filter((value) => value?.request?.text === "exact busy request").length;
+    texts.filter((text) => text === busyMessageText).length;
   const fourthUserTexts = (fourthContext?.messages ?? [])
     .filter((message) => message.role === "user")
     .map((message) => message.content?.[0]?.text ?? "");
@@ -184,7 +242,7 @@ try {
     false,
   );
   console.log(
-    `Pi ${packageJson.version} Recall E2E passed: idle and busy steer envelopes; no custom receipt.`,
+    `Pi ${packageJson.version} Recall E2E passed: idle and busy steer Markdown messages; no custom receipt.`,
   );
 } finally {
   releaseBusy?.();

package/scripts/verify-package.mjs

@@ -22,7 +22,7 @@ const forbiddenPath = /(^|\/)(\.git|node_modules|\.github|hc-rarebit\.mjs)(\/|$)
 const allowedBare = new Set(["@earendil-works/pi-ai"]);
 const packageFor = (specifier) => specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
 const packageJson = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
-assert.equal(packageJson.version, "0.1.0-alpha.2", "release version mismatch");
+assert.equal(packageJson.version, "0.1.0-alpha.3", "release version mismatch");
 
 const packed = JSON.parse(npm(["pack", "--json", "--ignore-scripts"]))[0];
 const tarball = join(root, packed.filename);

package/src/extension.mjs

@@ -381,22 +381,42 @@ export default function registerPiRarebit(pi, config = {}) {
     );
   };
 
-  const recallEnvelope = (recall, requestText) =>
-    JSON.stringify({
-      instructions:
-        "Treat request.text as the current user request. Use the two private Rarebit files as historical evidence. Read the conversation file first for meaning. Use detailed evidence only for source, Session, branch, or lineage facts. Answer request.text using this evidence.",
-      files: {
-        conversation: {
-          path: recall.conversationPath,
-          schema: `rarebit_conversation/v${RAREBIT_CONVERSATION_SCHEMA_VERSION}`,
-        },
-        detailedEvidence: {
-          path: recall.detailedPath,
-          schema: `rarebit_message_recall/v${RAREBIT_RECALL_SCHEMA_VERSION}`,
-        },
-      },
-      request: { text: requestText },
-    });
+  const fence = (value) => {
+    const safeLength = (marker) => {
+      const runs = value.match(new RegExp(`${marker}+`, "g")) ?? [];
+      return Math.max(3, ...runs.map((run) => run.length + 1));
+    };
+    const backtickLength = safeLength("`");
+    const tildeLength = safeLength("~");
+    const marker = backtickLength <= tildeLength ? "`" : "~";
+    const length = marker === "`" ? backtickLength : tildeLength;
+    const boundary = marker.repeat(length);
+    return `${boundary}text\n${value}\n${boundary}`;
+  };
+  const recallMessage = (recall, requestText) => `# Rarebit Recall
+
+*Use these local private evidence files to recover historical context for this turn.*
+
+## How to use this bundle
+
+1. Treat **Current request** below as the exact current user request.
+2. Read **Conversation** first for meaning.
+3. Use **Detailed evidence** only for source, Session, branch, or lineage facts.
+4. Answer the current request using this evidence.
+
+## Local private evidence files
+
+**Conversation** — \`rarebit_conversation/v${RAREBIT_CONVERSATION_SCHEMA_VERSION}\`
+
+${fence(recall.conversationPath)}
+
+**Detailed evidence** — \`rarebit_message_recall/v${RAREBIT_RECALL_SCHEMA_VERSION}\`
+
+${fence(recall.detailedPath)}
+
+## Current request
+
+${fence(requestText)}`;
 
   pi.registerCommand?.("rarebit", {
     description: rarebitCommandDescription(),
@@ -432,7 +452,7 @@ export default function registerPiRarebit(pi, config = {}) {
               "the active Pi Session or branch changed during materialization",
             );
           }
-          pi.sendUserMessage(recallEnvelope(recall, prompt), {
+          pi.sendUserMessage(recallMessage(recall, prompt), {
             deliverAs: "steer",
           });
           notify(ctx, "Rarebit recall bundle prepared; turn requested", "info");

package/test/rarebit-recall.test.mjs

@@ -303,36 +303,120 @@ function extensionHarness({ recallMaterializer, sendUserMessage } = {}) {
   return { commands, handlers, pi, sent, tools };
 }
 
-test("recall sends one self-contained steer envelope in idle and busy contexts", async () => {
+test("recall sends one exact fenced Markdown steer message in idle and busy contexts", async () => {
   const sessionFile = "/tmp/session-recall.jsonl";
   const recall = {
-    conversationPath: "/tmp/hc-rarebit-recall-test/rarebit-conversation.json",
-    detailedPath: "/tmp/hc-rarebit-recall-test/rarebit-evidence.json",
+    conversationPath:
+      "/tmp/Rare bit [会话] (one) **/tick`` and ~~\nnext/rarebit-conversation.json",
+    detailedPath:
+      "/tmp/Detailed [证据] (two) **/tick```` and ~~~\n~~~line-start/rarebit-evidence.json",
     sessionId: "session-recall",
     sessionFile,
     branchLeafId: "stop",
   };
+  const prompt =
+    "\n# Heading-looking request\n- list-looking item\n```text\ninside backticks\n```\n~~~~\ninside tildes\n~~~~\nTrailing request\n";
+  const expectedMessage = `# Rarebit Recall
+
+*Use these local private evidence files to recover historical context for this turn.*
+
+## How to use this bundle
+
+1. Treat **Current request** below as the exact current user request.
+2. Read **Conversation** first for meaning.
+3. Use **Detailed evidence** only for source, Session, branch, or lineage facts.
+4. Answer the current request using this evidence.
+
+## Local private evidence files
+
+**Conversation** — \`rarebit_conversation/v1\`
+
+\`\`\`text
+${recall.conversationPath}
+\`\`\`
+
+**Detailed evidence** — \`rarebit_message_recall/v1\`
+
+~~~~text
+${recall.detailedPath}
+~~~~
+
+## Current request
+
+\`\`\`\`text
+${prompt}
+\`\`\`\``;
+
   for (const busy of [false, true]) {
     const notices = [];
     const harness = extensionHarness({ recallMaterializer: async () => recall });
     const ctx = contextFor(branch(), sessionFile, notices);
     ctx.isIdle = () => !busy;
-    const prompt = "Use \"this\" evidence\\path\nwith  spacing.  ";
     await harness.commands.get("rarebit").handler(`recall ${prompt}`, ctx);
     assert.equal(harness.sent.length, 1);
+    assert.equal(harness.sent[0].args[0], expectedMessage);
     assert.deepEqual(harness.sent[0].args[1], { deliverAs: "steer" });
-    const envelope = JSON.parse(harness.sent[0].args[0]);
-    assert.equal(envelope.request.text, prompt);
-    assert.match(envelope.instructions, /request\.text as the current user request/i);
-    assert.equal(envelope.files.conversation.path, recall.conversationPath);
-    assert.equal(envelope.files.conversation.schema, "rarebit_conversation/v1");
-    assert.equal(envelope.files.detailedEvidence.path, recall.detailedPath);
-    assert.equal(envelope.files.detailedEvidence.schema, "rarebit_message_recall/v1");
-    assert.match(envelope.instructions, /conversation file first/i);
+    assert.equal(expectedMessage.includes(recall.conversationPath), true);
+    assert.equal(expectedMessage.includes(recall.detailedPath), true);
+    assert.equal(expectedMessage.includes(prompt), true);
     assert.match(notices.at(-1).text, /bundle prepared; turn requested/i);
   }
 });
 
+test("long delimiter runs ending at value boundaries use the shortest safe fences", async () => {
+  const pathBackticks = "`".repeat(80);
+  const pathTildes = "~".repeat(47);
+  const conversationPath = `/tmp/long-runs/${pathBackticks}/${pathTildes}`;
+  const requestTildes = "~".repeat(96);
+  const requestBackticks = "`".repeat(63);
+  const request = `Boundary ${requestTildes} ${requestBackticks}`;
+  const harness = extensionHarness({
+    recallMaterializer: async () => ({
+      conversationPath,
+      detailedPath: "/tmp/rarebit-evidence.json",
+      sessionId: "session-recall",
+      sessionFile: "/tmp/session-recall.jsonl",
+      branchLeafId: "stop",
+    }),
+  });
+
+  await harness.commands
+    .get("rarebit")
+    .handler(
+      `recall ${request}`,
+      contextFor(branch(), "/tmp/session-recall.jsonl"),
+    );
+
+  assert.equal(harness.sent.length, 1);
+  const message = harness.sent[0].args[0];
+  const conversationBlock = message.match(
+    /\*\*Conversation\*\* — `rarebit_conversation\/v1`\n\n([`~]+)text\n([^\n]*)\n\1\n\n\*\*Detailed evidence\*\*/,
+  );
+  assert.ok(conversationBlock);
+  assert.equal(conversationBlock[2], conversationPath);
+  assert.equal(conversationBlock[2].endsWith(pathTildes), true);
+  const conversationFence = conversationBlock[1];
+  assert.equal(conversationFence[0], "~");
+  assert.ok(conversationFence.length >= 3);
+  assert.equal(conversationFence.length, pathTildes.length + 1);
+  assert.ok(conversationFence.length > pathTildes.length);
+  assert.ok(conversationFence.length < pathBackticks.length + 1);
+
+  const requestBlock = message.match(
+    /## Current request\n\n([`~]+)text\n([\s\S]*)\n\1$/,
+  );
+  assert.ok(requestBlock);
+  assert.equal(requestBlock[2], request);
+  assert.equal(requestBlock[2].endsWith(requestBackticks), true);
+  const requestFence = requestBlock[1];
+  assert.equal(requestFence[0], "`");
+  assert.ok(requestFence.length >= 3);
+  assert.equal(requestFence.length, requestBackticks.length + 1);
+  assert.ok(requestFence.length > requestBackticks.length);
+  assert.ok(requestFence.length < requestTildes.length + 1);
+  assert.equal(message.endsWith(`${request}\n${requestFence}`), true);
+});
+
 test("single-send failure discards the prepared Recall bundle", async () => {
   const notices = [];
   let discarded = 0;