@mikeargento/bitgraph-mcp 0.5.0 → 0.5.2

package/src/server.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * @mikeargento/bitgraph-mcp: tool definitions.
@@ -49,10 +49,10 @@ import {
   type SetOutcome,
 } from "./format.js";
 import { expandPaths, fusedDigestFor, scanFile, type ScannedFile } from "./scan.js";
-import { SLOT_TTL_SECONDS, TASK_INSTRUCTIONS, beginTask, decodeTaskToken, sealTask } from "./task.js";
+import { SLOT_TTL_SECONDS, TASK_INSTRUCTIONS, beginTask, decodeTaskToken, sealTask, writeProofBeside } from "./task.js";
 import type { BitGraphProof } from "./types.js";
 
-export const SERVER_VERSION = "0.5.0";
+export const SERVER_VERSION = "0.5.2";
 
 const SCAN_CONCURRENCY = 4;
 /** Paths per call; a directory counts once and expands to its files. */
@@ -332,7 +332,7 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
     },
     {
       instructions:
-        "BitGraph gives a file's bytes a causal position in a public ledger bracketed by Ethereum anchors. bitgraph_record makes ONE BitGraph of everything in a call, files and folders alike: a single file is fused on its own; two or more become one set under one slot, one position, every file's new fused bytes listed by digest in the committed artifact. " +
+        "BitGraph gives a file's bytes a causal position in a public sequence bracketed by Ethereum anchors. bitgraph_record makes ONE BitGraph of everything in a call, files and folders alike: a single file is fused on its own; two or more become one set under one slot, one position, every file's new fused bytes listed by digest in the committed artifact. " +
         "Files are read on this machine and never uploaded or modified; the new bytes are virtual and never written. Recordings are permanent: only make BitGraphs of files the user asked for, and never generate content just to record it. bitgraph_check and bitgraph_get_proof are read-only. " +
         "To do work INSIDE a BitGraph, call bitgraph_open BEFORE starting: it returns a position and its commitment; put the commitment string into the task, seal the task with bitgraph_commit within 120 seconds, then record the outputs with bitgraph_record. The task then could not have existed before the position's floor block, and the outputs sit after it.",
     }
@@ -343,11 +343,11 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
     {
       title: "Make a BitGraph",
       description:
-        "Make a BitGraph of files or folders. Everything in one call becomes ONE BitGraph, the way a drop on the site works: a single file is fused on its own slot; two or more files become a set under a single slot in the BitGraph ledger (bitgraph.ing), one position for all of them. " +
+        "Make a BitGraph of files or folders. Everything in one call becomes ONE BitGraph, the way a drop on the site works: a single file is fused on its own slot; two or more files become a set under a single slot on BitGraph (bitgraph.ing), one position for all of them. " +
         "On this machine each file is read once for its SHA-256 (the origin) and a hasher state; an unused slot is allocated before any new file exists; every file's new fused bytes (the original plus a registered placement carrying the slot's commitment: a 48-byte trailer for JPEG, PNG, GIF, TIFF and TIFF-based raws, BMP, WebP, WAV and AVI, a small tar container with the original first for everything else) are hashed from that state without being written or held; and for a set the canonical list of those digests (above 2,000 files, a Merkle root over it) is committed under the same slot. " +
         "Files are never modified and never uploaded: only digests, the committed artifact and slot records leave the machine. " +
         "Give file paths, directory paths, or both (absolute paths preferred): a directory is every regular file under it, recursively, with hidden entries and symbolic links left out. " +
-        "Files BitGraph still indexes (recorded before 2026-09-08) are NOT made again by default; they come back as 'on record' with their earliest position. BitGraph does not index new proofs, so a file may already have a BitGraph its holder keeps. Pass again=true to make a new BitGraph regardless. " +
+        "Files already on record are NOT made again by default; they come back as 'on record' with their earliest position. A file can also hold a BitGraph its holder keeps, which no lookup sees. Pass again=true to make a new BitGraph regardless. " +
         "Positions are permanent and the proof comes back to you to keep, so only BitGraph files the user asked to, and never generate content just to record it. " +
         "Returns one outcome per file: 'fused' (for a set, its row, one of N, and the set's position and proof page; for a single file, its own position and Frame), 'on record', or 'not fused' (with the reason). Keep the proof beside the files; BitGraph does not index it. " +
         "Use bitgraph_check instead when the user only wants to know whether files are on record.",
@@ -361,7 +361,7 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
           .boolean()
           .default(false)
           .describe(
-            "false (default): files BitGraph still indexes are returned as-is, nothing made. true: put every file in the set regardless. Outcomes are per unique file content: two paths with identical bytes are one member."
+            "false (default): files already on record are returned as-is, nothing made. true: put every file in the set regardless. Outcomes are per unique file content: two paths with identical bytes are one member."
           ),
         response_format: responseFormatSchema,
       },
@@ -413,7 +413,7 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
         const unique = [...byDigest.keys()];
 
         // 4. What is on record already.
-        report(0, 1, "checking the ledger");
+        report(0, 1, "checking BitGraph's copy");
         const checked = await batchCheck(config, unique.map(toUrlSafeB64));
         const existing = new Map<string, Array<{ proof: BitGraphProof }>>();
         for (const d of unique) {
@@ -651,12 +651,29 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
         const counter = sealed.proof.commit?.counter ?? null;
         const epoch = sealed.proof.commit?.epochId ?? null;
         const floor = sealed.proof.commit?.slotAnchor?.blockNumber ?? null;
-        const structured = { outcome: "sealed", slot_counter: state.slot.counter, counter, epoch: epoch ? toUrlSafeB64(epoch) : null, floor_block: floor, artifact_digest: toUrlSafeB64(sealed.artifactDigestB64), commitment_offsets: sealed.offsets, proof: sealed.proof };
+        /* The proof goes beside the sealed file, written here, whole. Given
+         * only a digest there is no file to put it beside, so it is handed
+         * back with the one instruction that matters. */
+        let proofPath: string | null = null;
+        let proofNote = "";
+        if (path !== undefined) {
+          try {
+            proofPath = await writeProofBeside(path, sealed.proof);
+            proofNote = `The proof is written at ${proofPath}, whole; leave it as written. `;
+          } catch (err) {
+            proofNote = `The proof could not be written beside the file (${errorText(err)}); save the JSON below whole and unedited, every field. `;
+          }
+        } else {
+          proofNote = "Save the JSON below as a file beside the task bytes, whole and unedited, every field, including environment.attestation.reportB64, the long base64 string, copied exactly: a proof missing slotAllocation, environment, or the attestation cannot be verified. ";
+        }
+        const structured = { outcome: "sealed", slot_counter: state.slot.counter, counter, epoch: epoch ? toUrlSafeB64(epoch) : null, floor_block: floor, artifact_digest: toUrlSafeB64(sealed.artifactDigestB64), commitment_offsets: sealed.offsets, proof_path: proofPath, instructions: proofNote.trim(), proof: sealed.proof };
         if (response_format === "json") return ok(JSON.stringify(structured, null, 2), structured);
         return ok(
           `Sealed the task at position ${counter ?? "?"} (slot ${state.slot.counter}).${floor !== null ? ` Not before block ${floor}.` : ""} ` +
-            (sealed.offsets !== null ? `The commitment string was found in the task bytes at offset ${sealed.offsets[0]}. ` : "The task bytes were not read here; a verifier looks for the commitment string in them. ") +
-            "Keep the proof beside the task bytes, and record the outputs with bitgraph_record when they exist.\n\n```json\n" + JSON.stringify(sealed.proof, null, 2) + "\n```",
+            (sealed.offsets !== null ? `The commitment string was found in the sealed bytes at offset ${sealed.offsets[0]}. ` : "The bytes were not read here; a verifier looks for the commitment string in them. ") +
+            proofNote +
+            "Record the outputs with bitgraph_record when they exist." +
+            (proofPath === null ? "\n\n```json\n" + JSON.stringify(sealed.proof, null, 2) + "\n```" : ""),
           structured
         );
       } catch (err) {
@@ -670,7 +687,7 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
     {
       title: "Check for BitGraphs",
       description:
-        "Check whether files or digests are on record in the BitGraph ledger, without recording anything. " +
+        "Check whether files or digests are on record in BitGraph's copy, without recording anything. " +
         `Accepts file paths and directory paths (every regular file under them, up to ${MAX_CHECK_FILES} in all; hashed locally, only digests are sent) and/or raw SHA-256 digests in standard or URL-safe base64. ` +
         "Returns, per item: on_record (the bytes are on record, as an exact recording, as the original a new file was made from, or as a member of a set), every position by counter, and the proof page URL. " +
         "Read-only. Use bitgraph_record to BitGraph files that turn out not to be on record.",

package/src/task.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * A position BEFORE the work: the task form of the stdio server.
@@ -157,7 +157,31 @@ async function recover(config: ApiConfig, artifactDigestB64: string, slot: SlotA
 }
 
 export const TASK_INSTRUCTIONS =
-  "You hold a position and its commitment, and no work exists yet. Put the commitment string into the task before you run it: in the prompt or request you are about to send, as a seed, as a line in the document, as text that must appear in the output. " +
-  `Then call bitgraph_commit with this fuse_token and the path of the task file (or the SHA-256 of its bytes), within ${SLOT_TTL_SECONDS} seconds of opening: that seals the task under the position before its output exists. ` +
-  "Keep those exact bytes: a verifier recomputes the commitment from the proof and looks for the string inside them. " +
-  "When the output exists, record it with bitgraph_record; it will sit at a later position. What a stranger can then check: the task could not have existed before the position's floor block, and the output was recorded after it.";
+  "You hold a position and its commitment, and no work exists yet. Put the commitment string INSIDE THE OUTPUT you are about to make whenever its format can hold text (SVG, HTML, code, JSON, Markdown, CSV, a document): as a comment, a field, a line that stays in the file. " +
+  `When the output exists, call bitgraph_commit with this fuse_token and the output file's path, within ${SLOT_TTL_SECONDS} seconds of opening: the output itself is sealed under the position, and the proof is written beside it. ` +
+  "If the output cannot hold text (a PNG, audio, video) or will take longer than that to make, put the commitment into a task file instead (the exact prompt or request you send), seal that file the same way, and when the output exists record it with bitgraph_record: the task is sealed before the output existed, and the output is recorded after. " +
+  "Keep the exact bytes that were sealed unchanged: a verifier recomputes the commitment from the proof and looks for the string inside them. " +
+  "Leave the proof file as written, whole, every field, environment.attestation.reportB64 included: a proof missing slotAllocation, environment, or the attestation cannot be verified.";
+
+/**
+ * Write a sealed task's proof beside the file it is about, whole, and say
+ * where. `make_task.txt` gets `make_task.proof.json`; a name already taken
+ * gets the position's counter in it rather than being overwritten.
+ *
+ * ⚠️ THE SERVER WRITES IT, NOT THE AGENT. Handed the JSON to save, an agent
+ * tidied it and dropped slotAllocation and environment, and the signature
+ * had no body left to be checked against (Grok, 2026-09-13). A file this
+ * process writes is the proof exactly as the boundary returned it.
+ */
+export async function writeProofBeside(sealedPath: string, proof: BitGraphProof): Promise<string> {
+  const { writeFile, access } = await import("node:fs/promises");
+  const { basename, dirname, extname, join } = await import("node:path");
+  const dir = dirname(sealedPath);
+  const base = basename(sealedPath);
+  const stem = extname(base) === "" ? base : base.slice(0, -extname(base).length);
+  const counter = proof.commit?.counter ?? "0";
+  let target = join(dir, `${stem}.proof.json`);
+  if (await access(target).then(() => true).catch(() => false)) target = join(dir, `${stem}.proof.${counter}.json`);
+  await writeFile(target, JSON.stringify(proof, null, 2) + "\n", { flag: "wx" });
+  return target;
+}

package/src/types.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+// Copyright (c) 2024-2026 Argento Computing Inc. Licensed under the MIT License. See LICENSE.
 
 /**
  * @mikeargento/bitgraph-mcp: wire types.