@mikeargento/bitgraph-mcp 0.4.1 → 0.5.1

package/src/server.ts

@@ -49,9 +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, writeProofBeside } from "./task.js";
 import type { BitGraphProof } from "./types.js";
 
-export const SERVER_VERSION = "0.4.1";
+export const SERVER_VERSION = "0.5.1";
 
 const SCAN_CONCURRENCY = 4;
 /** Paths per call; a directory counts once and expands to its files. */
@@ -332,7 +333,8 @@ 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. " +
-        "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.",
+        "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.",
     }
   );
 
@@ -345,9 +347,9 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
         "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 already on record (recorded, or the origin of a fused file) are NOT made again by default; they come back as 'on record' with their earliest position. Pass again=true to make a new BitGraph of them deliberately. " +
-        "BitGraphs are permanent: the ledger has 10-year retention and no deletes, 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). A lookup by any file's own digest finds its BitGraph. " +
+        "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. " +
+        "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.",
       inputSchema: {
         paths: z
@@ -359,7 +361,7 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
           .boolean()
           .default(false)
           .describe(
-            "false (default): files already on record are returned as-is, nothing made. true: put every file in the set even if its bytes are already on record. Outcomes are per unique file content: two paths with identical bytes are one member."
+            "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."
           ),
         response_format: responseFormatSchema,
       },
@@ -591,6 +593,95 @@ export function buildServer(deps: ServerDeps = {}): McpServer {
     }
   );
 
+  server.registerTool(
+    "bitgraph_open",
+    {
+      title: "Open a position before the work",
+      description:
+        "Ask for a BitGraph position BEFORE starting a task, so the task can be done inside the BitGraph. Returns a fuse_token, the position, its floor block, and the slot's commitment as a string. " +
+        "Put the commitment string into the task before running it (the prompt or request you send, a seed, a line in the document, text that must appear in the output), then call bitgraph_commit with the fuse_token and the task file's path within " + SLOT_TTL_SECONDS + " seconds. " +
+        "What that gives a stranger: the task could not have existed before the floor block (the commitment did not exist before the position did), and the outputs, recorded afterwards with bitgraph_record, sit at later positions. " +
+        "Nothing about the task is sent here; only its digest is, at commit. Positions are permanent: open one only when a task is about to run.",
+      inputSchema: {
+        response_format: responseFormatSchema,
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+    async ({ response_format }) => {
+      const config = configFromEnv();
+      try {
+        const b = await beginTask(config);
+        const structured = { outcome: "opened", task: true, slot_counter: b.slotCounter, epoch: b.epoch, commitment: b.commitment, commitment_base64: b.commitmentB64, floor: b.floor, fuse_token: b.token, expires_in_seconds: SLOT_TTL_SECONDS, instructions: TASK_INSTRUCTIONS };
+        if (response_format === "json") return ok(JSON.stringify(structured, null, 2), structured);
+        return ok(
+          `Opened position ${b.slotCounter} before any work exists. Floor: ${b.floor ? `not before block ${b.floor.block}` : "the sealed proof will carry the signed floor"}.\n\n` +
+            `Commitment (put this string into the task): ${b.commitment}\n\n${TASK_INSTRUCTIONS}\n\n` +
+            "```json\n" + JSON.stringify({ fuse_token: b.token, commitment: b.commitment, slot_counter: b.slotCounter, epoch: b.epoch, floor: b.floor }, null, 2) + "\n```",
+          structured
+        );
+      } catch (err) {
+        return fail(errorText(err));
+      }
+    }
+  );
+
+  server.registerTool(
+    "bitgraph_commit",
+    {
+      title: "Seal the task under its position",
+      description:
+        "Step two of doing work inside a BitGraph: seal the task bytes that carry the commitment under the position bitgraph_open returned. Give the fuse_token and the path of the task file (the exact request, prompt or document that contains the commitment string), or its SHA-256 (base64) when the bytes are elsewhere. " +
+        "With a path, the file is read on this machine, the commitment string is looked for inside it BEFORE anything is sent (a task that does not carry it is refused and the slot stays held), and only the digest travels. " +
+        "Returns the proof: keep it beside the task bytes. Then record the outputs with bitgraph_record. Must be called within " + SLOT_TTL_SECONDS + " seconds of bitgraph_open.",
+      inputSchema: {
+        fuse_token: z.string().min(1).max(8000).describe("The fuse_token bitgraph_open returned."),
+        path: z.string().min(1).optional().describe("Path of the task file that contains the commitment string."),
+        digest: z.string().min(1).max(100).optional().describe("Instead of a path: SHA-256 of the task bytes, base64 (either form)."),
+        response_format: responseFormatSchema,
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+    async ({ fuse_token, path, digest, response_format }) => {
+      const config = configFromEnv();
+      const state = decodeTaskToken(fuse_token);
+      if (state === null) return fail("Error: fuse_token is not one issued by bitgraph_open.");
+      if (path === undefined && digest === undefined) return fail("Error: give the task file's path, or its SHA-256 digest.");
+      try {
+        const sealed = await sealTask(config, state, path !== undefined ? { path } : { digestB64: fromUrlSafeB64(digest!.trim()) });
+        const counter = sealed.proof.commit?.counter ?? null;
+        const epoch = sealed.proof.commit?.epochId ?? null;
+        const floor = sealed.proof.commit?.slotAnchor?.blockNumber ?? null;
+        /* 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: a proof missing slotAllocation or environment 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 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) {
+        return fail(errorText(err));
+      }
+    }
+  );
+
   server.registerTool(
     "bitgraph_check",
     {

package/src/task.ts

@@ -0,0 +1,187 @@
+// Copyright (c) 2024-2026 Mike Argento. Licensed under the MIT License. See LICENSE.
+
+/**
+ * A position BEFORE the work: the task form of the stdio server.
+ *
+ * bitgraph_open with no files asks the site's own /api/fuse/allocate for a
+ * slot and returns its commitment, and nothing else. The caller puts the
+ * commitment into the task it is about to run (the prompt, the request, a
+ * seed, a line in the document) and, within the slot's life, commits the
+ * digest of those task bytes under the slot with the inline marker
+ * (bitgraph-fuse/1, title base64url): a verifier recomputes the commitment
+ * from the slot record and finds its base64url text inside the bytes.
+ * Outputs are recorded afterwards with bitgraph_record and sit later.
+ *
+ * The slot allocation and the commit go through the same two site routes
+ * the core package's fuse() uses; the recovery rule is the core's (read back
+ * by digest, refuse a proof under any other slot).
+ */
+import { readFile } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { bytesToBase64, computeSlotCommitment, findCommitment, inlineAttribution, verifyProofIntegrity, ENCODING_BASE64URL } from "@mikeargento/bitgraph-verify";
+import type { BitGraphProof, SlotAllocation } from "@mikeargento/bitgraph-verify";
+import { ApiError, type ApiConfig } from "./api.js";
+import { toUrlSafeB64 } from "./encoding.js";
+
+export const SLOT_TTL_SECONDS = 120;
+const CHAIN = "bitgraph:main";
+const B64_32 = /^[A-Za-z0-9+/]{43}=$/;
+const B64_64 = /^[A-Za-z0-9+/]{86}==$/;
+
+export interface TaskState {
+  v: 1;
+  task: true;
+  slot: SlotAllocation;
+}
+
+function isSlotRecord(x: unknown): x is SlotAllocation {
+  if (x === null || typeof x !== "object" || Array.isArray(x)) return false;
+  const s = x as Record<string, unknown>;
+  return s.version === "bitgraph/slot/1" && typeof s.nonceB64 === "string" && B64_32.test(s.nonceB64) && typeof s.counter === "string" && /^(0|[1-9][0-9]*)$/.test(s.counter)
+    && typeof s.epochId === "string" && typeof s.publicKeyB64 === "string" && typeof s.signatureB64 === "string" && B64_64.test(s.signatureB64) && s.chainId === CHAIN;
+}
+
+export function encodeTaskToken(state: TaskState): string {
+  return Buffer.from(JSON.stringify(state), "utf8").toString("base64url");
+}
+
+export function decodeTaskToken(token: string): TaskState | null {
+  let parsed: unknown;
+  try { parsed = JSON.parse(Buffer.from(token, "base64url").toString("utf8")); } catch { return null; }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const s = parsed as Record<string, unknown>;
+  if (s.v !== 1 || s.task !== true || !isSlotRecord(s.slot)) return null;
+  return { v: 1, task: true, slot: s.slot };
+}
+
+async function post(config: ApiConfig, path: string, body: unknown, timeoutMs: number): Promise<{ status: number; json: unknown; retryAfterSec: number | null }> {
+  const headers: Record<string, string> = { "content-type": "application/json", accept: "application/json" };
+  if (config.apiKey) headers["authorization"] = `Bearer ${config.apiKey}`;
+  const res = await fetch(`${config.baseUrl}${path}`, { method: "POST", headers, body: JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs) });
+  let json: unknown = null;
+  try { json = await res.json(); } catch { /* non-JSON */ }
+  const raw = res.headers.get("retry-after");
+  const retry = raw !== null ? Number.parseInt(raw, 10) : NaN;
+  return { status: res.status, json, retryAfterSec: Number.isFinite(retry) ? retry : null };
+}
+
+const messageOf = (json: unknown, fallback: string): string => {
+  const e = (json as { error?: unknown } | null)?.error;
+  return typeof e === "string" ? e : fallback;
+};
+
+export interface Begun {
+  token: string;
+  /** Unpadded base64url: the string to put into the task. */
+  commitment: string;
+  commitmentB64: string;
+  slotCounter: string;
+  epoch: string;
+  floor: { block: number } | null;
+}
+
+/** Step one of the task form: a held slot and its commitment, before any work exists. */
+export async function beginTask(config: ApiConfig): Promise<Begun> {
+  const r = await post(config, "/api/fuse/allocate", {}, 20_000);
+  if (r.status !== 200) throw new ApiError(r.status, messageOf(r.json, `allocation refused (${r.status})`), r.retryAfterSec);
+  const slot = (r.json as { slot?: unknown } | null)?.slot;
+  if (!isSlotRecord(slot)) throw new ApiError(502, "the allocation response is not a slot record on bitgraph:main");
+  const commitmentB64 = bytesToBase64(computeSlotCommitment(slot));
+  let floor: Begun["floor"] = null;
+  try {
+    const res = await fetch(`${config.baseUrl}/api/proofs/anchors?counter=${encodeURIComponent(slot.counter)}&epoch=${encodeURIComponent(slot.epochId)}&before=1`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+    const data = res.status === 200 ? ((await res.json()) as { anchors?: Array<{ commit?: { anchor?: { blockNumber?: number } } }> }) : null;
+    const b = data?.anchors?.[0]?.commit?.anchor?.blockNumber;
+    if (typeof b === "number") floor = { block: b };
+  } catch { floor = null; }
+  return { token: encodeTaskToken({ v: 1, task: true, slot }), commitment: toUrlSafeB64(commitmentB64), commitmentB64, slotCounter: slot.counter, epoch: toUrlSafeB64(slot.epochId), floor };
+}
+
+export interface SealedTask {
+  proof: BitGraphProof;
+  artifactDigestB64: string;
+  /** Byte offsets of the commitment string inside the task bytes, when the bytes were given. */
+  offsets: number[] | null;
+}
+
+/**
+ * Step two: the task bytes (a path, or the bytes themselves) sealed under
+ * the held slot with the inline marker. When the bytes are in hand the
+ * commitment is looked for BEFORE the commit, so a task that does not carry
+ * it is refused without spending the slot.
+ */
+export async function sealTask(config: ApiConfig, state: TaskState, task: { path: string } | { bytes: Uint8Array } | { digestB64: string }): Promise<SealedTask> {
+  const { slot } = state;
+  const commitment = computeSlotCommitment(slot);
+  let bytes: Uint8Array | null = null;
+  let artifactDigestB64: string;
+  if ("digestB64" in task) {
+    if (!B64_32.test(task.digestB64)) throw new ApiError(400, "artifact digest must be a base64 SHA-256");
+    artifactDigestB64 = task.digestB64;
+  } else {
+    bytes = "path" in task ? new Uint8Array(await readFile(task.path)) : task.bytes;
+    artifactDigestB64 = createHash("sha256").update(bytes).digest("base64");
+  }
+  const offsets = bytes === null ? null : findCommitment(bytes, commitment, ENCODING_BASE64URL);
+  if (offsets !== null && offsets.length === 0) {
+    throw new ApiError(400, `the task bytes do not contain the commitment string ${toUrlSafeB64(bytesToBase64(commitment))}; put it in before sealing. Nothing was committed and the slot is still held.`);
+  }
+  const attribution = inlineAttribution();
+  const r = await post(config, "/api/fuse/commit", { digests: [{ digestB64: artifactDigestB64, hashAlg: "sha256" }], slotId: slot.nonceB64, slot, chainId: CHAIN, attribution }, 40_000);
+  let proof: BitGraphProof | null = null;
+  if (r.status === 200) proof = ((r.json as { proof?: BitGraphProof } | null)?.proof ?? null);
+  else if (r.status === 409 || r.status === 503) proof = await recover(config, artifactDigestB64, slot);
+  if (proof === null) throw new ApiError(r.status, messageOf(r.json, `commit refused (${r.status})`), r.retryAfterSec);
+  if (proof.artifact?.digestB64 !== artifactDigestB64 || proof.commit?.nonceB64 !== slot.nonceB64 || proof.slotAllocation?.nonceB64 !== slot.nonceB64) throw new ApiError(502, "the boundary returned a proof under a different slot; nothing is labelled sealed");
+  const a = proof.attribution;
+  if (a?.name !== attribution.name || a?.title !== attribution.title || a?.message !== undefined) throw new ApiError(502, "the returned proof does not carry the inline marker that was sent; nothing is labelled sealed");
+  const integrity = await verifyProofIntegrity({ proof });
+  if (!integrity.valid) throw new ApiError(502, `the returned proof does not verify: ${integrity.reason ?? "unknown reason"}`);
+  return { proof, artifactDigestB64, offsets };
+}
+
+async function recover(config: ApiConfig, artifactDigestB64: string, slot: SlotAllocation): Promise<BitGraphProof | null> {
+  for (let attempt = 0; attempt < 4; attempt++) {
+    if (attempt > 0) await new Promise((r) => setTimeout(r, 1500));
+    try {
+      const res = await fetch(`${config.baseUrl}/api/proofs/${encodeURIComponent(toUrlSafeB64(artifactDigestB64))}`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(15_000) });
+      if (res.status !== 200) continue;
+      const j = (await res.json()) as { proofs?: Array<{ proof?: BitGraphProof }> } | null;
+      for (const e of j?.proofs ?? []) {
+        const p = e.proof;
+        if (p && p.artifact?.digestB64 === artifactDigestB64 && p.commit?.nonceB64 === slot.nonceB64) return p;
+      }
+    } catch { /* try again */ }
+  }
+  return null;
+}
+
+export const TASK_INSTRUCTIONS =
+  "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: a proof missing slotAllocation or environment 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;
+}