Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
16.0 KB
Raw Blame
/**
 * `_meta.progressToken` at the MCP boundary (nothing-runs-unwatched, U2).
 *
 * Before this unit `handleToolsCall` read exactly two keys from `params`
 * - `name` and `arguments` - so a client's progress token was accepted by
 * the wire and then discarded without a word. These tests pin the four
 * facts that replace that silence:
 *
 *   - stdio, which can write an unsolicited frame, carries the token as
 *     `notifications/progress` frames emitted BEFORE the response frame;
 *   - HTTP, which writes one response and closes, refuses the token by
 *     name rather than accepting it and dropping the events;
 *   - a call with no token is byte-identical to the call the previous
 *     release made, which is what makes the feature additive;
 *   - a tool that dispatches on a `view` argument hands the sink to the
 *     view it dispatched to, rather than dropping it one link short of
 *     the pass that had something to report.
 */

import { afterEach, beforeEach, describe, expect, test } from "bun:test";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { PassThrough } from "node:stream";

import {
  JSONRPC_VERSION,
  MCPServer,
  PROTOCOL_VERSION,
  serveStdio,
  serveStdioFromString,
  startHttp,
} from "../../src/mcp/index.ts";
import {
  PROGRESS_META_KEY,
  PROGRESS_NOTIFICATION_METHOD,
  withProgressRefusal,
} from "../../src/mcp/progress.ts";
import {
  isProgressKind,
  PROGRESS_KIND,
  PROGRESS_REASON,
  PROGRESS_SCHEMA,
} from "../../src/core/brain/progress.ts";
import { bootstrapBrain } from "../../src/core/brain/init.ts";

interface JsonObject {
  readonly [key: string]: any;
}

let vault: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "o2b-mcp-progress-"));
  bootstrapBrain(vault);
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
});

const INITIALIZE = {
  jsonrpc: JSONRPC_VERSION,
  id: 1,
  method: "initialize",
  params: { protocolVersion: PROTOCOL_VERSION },
};

/** A `tools/call` for the one tool wired to the progress spine today. */
function dreamCall(id: number, token?: string | number): JsonObject {
  return {
    jsonrpc: JSONRPC_VERSION,
    id,
    method: "tools/call",
    params: {
      name: "brain_dream",
      arguments: { dry_run: true },
      ...(token === undefined ? {} : { _meta: { progressToken: token } }),
    },
  };
}

/**
 * One response frame with the only member a rerun cannot reproduce
 * NORMALISED rather than removed.
 *
 * `run_id` is derived from the wall clock, and it appears twice: once in
 * `structuredContent` and again inside `content`, which is that same
 * payload rendered. So the id is replaced wherever it occurs and every
 * other byte of both members is still compared.
 *
 * The earlier form deleted `content` outright, and deleting it excused
 * the entire rendered payload an MCP client displays: an independent
 * review replaced that array wholesale whenever a progress token was
 * present and this file stayed green. A frame with no run id to
 * normalise is a defect in the response, not a frame to compare loosely,
 * so it throws.
 */
function normalizeRunId(frame: JsonObject | undefined): string {
  const runId = (frame?.["result"] as JsonObject | undefined)?.["structuredContent"]?.["run_id"];
  if (typeof runId !== "string" || runId.length === 0) {
    throw new TypeError(`response frame carries no run_id to normalise: ${JSON.stringify(frame)}`);
  }
  return JSON.stringify(frame).split(runId).join("<run-id>");
}

function lines(out: string): JsonObject[] {
  return out
    .split("\n")
    .filter((l) => l.trim() !== "")
    .map((l) => JSON.parse(l) as JsonObject);
}

describe("stdio carries a progress token", () => {
  test("a valid token yields progress frames before the response frame", async () => {
    const input = JSON.stringify(INITIALIZE) + "\n" + JSON.stringify(dreamCall(2, "tok-42")) + "\n";
    const frames = lines(await serveStdioFromString({ vault }, input));

    const responseIndex = frames.findIndex((f) => f["id"] === 2);
    expect(responseIndex).toBeGreaterThan(-1);
    const notifications = frames.filter((f) => f["method"] === PROGRESS_NOTIFICATION_METHOD);
    expect(notifications.length).toBeGreaterThan(0);

    // Every notification precedes the response it belongs to.
    for (const n of notifications) expect(frames.indexOf(n)).toBeLessThan(responseIndex);

    const first = notifications[0]!;
    expect(first["jsonrpc"]).toBe(JSONRPC_VERSION);
    expect(first["id"]).toBeUndefined();
    const params = first["params"] as JsonObject;
    expect(params["progressToken"]).toBe("tok-42");
    expect(typeof params["progress"]).toBe("number");
    const event = (params["_meta"] as JsonObject)[PROGRESS_META_KEY] as JsonObject;
    expect(event["schema"]).toBe(PROGRESS_SCHEMA);
    expect(event["operation"]).toBe("dream");
    expect(event["kind"]).toBe(PROGRESS_KIND.started);
    expect(typeof event["stage"]).toBe("string");
  });

  test("an integer token is accepted and echoed back unchanged", async () => {
    const input = JSON.stringify(INITIALIZE) + "\n" + JSON.stringify(dreamCall(2, 7)) + "\n";
    const frames = lines(await serveStdioFromString({ vault }, input));
    const notifications = frames.filter((f) => f["method"] === PROGRESS_NOTIFICATION_METHOD);
    expect(notifications.length).toBeGreaterThan(0);
    expect((notifications[0]!["params"] as JsonObject)["progressToken"]).toBe(7);
  });

  test("the response frame is identical with and without a token", async () => {
    const withToken = lines(
      await serveStdioFromString(
        { vault },
        JSON.stringify(INITIALIZE) + "\n" + JSON.stringify(dreamCall(2, "tok")) + "\n",
      ),
    ).find((f) => f["id"] === 2);
    const without = lines(
      await serveStdioFromString(
        { vault },
        JSON.stringify(INITIALIZE) + "\n" + JSON.stringify(dreamCall(2)) + "\n",
      ),
    ).find((f) => f["id"] === 2);

    // The rendered payload is what a client displays, so the comparison
    // is worthless if both frames happen to carry nothing there.
    const content = (withToken?.["result"] as JsonObject | undefined)?.["content"] as
      | ReadonlyArray<JsonObject>
      | undefined;
    expect(content?.length).toBeGreaterThan(0);
    expect(normalizeRunId(withToken)).toBe(normalizeRunId(without));
  });

  test("no token produces no notification frames at all", async () => {
    const frames = lines(
      await serveStdioFromString(
        { vault },
        JSON.stringify(INITIALIZE) + "\n" + JSON.stringify(dreamCall(2)) + "\n",
      ),
    );
    expect(frames.filter((f) => f["method"] !== undefined)).toEqual([]);
    expect(frames.every((f) => f["id"] !== undefined)).toBe(true);
  });

  test("two concurrent calls keep per-request adjacency on a real stream", async () => {
    // The production loop dispatches read-classified calls concurrently,
    // so two progress-carrying calls can emit between each other's
    // notifications: cross-request interleaving is legal (clients
    // correlate by token). What must hold is adjacency - ALL of a
    // request's notifications precede ITS response - and frame
    // atomicity on the shared stream.
    const stdin = new PassThrough();
    const chunks: string[] = [];
    const stdout = new PassThrough();
    stdout.on("data", (c: Buffer) => chunks.push(c.toString("utf8")));

    const briefCall = (id: number, token: string): JsonObject => ({
      jsonrpc: JSONRPC_VERSION,
      id,
      method: "tools/call",
      params: {
        name: "brain_brief",
        arguments: { view: "operator" },
        _meta: { progressToken: token },
      },
    });

    const done = serveStdio({ vault }, { stdin, stdout });
    stdin.write(JSON.stringify(INITIALIZE) + "\n");
    stdin.write(JSON.stringify(briefCall(2, "tok-a")) + "\n");
    stdin.write(JSON.stringify(briefCall(3, "tok-b")) + "\n");
    stdin.end();
    await done;

    // Frame atomicity: the shared stream still splits into clean frames.
    const frames = lines(chunks.join(""));
    const response2 = frames.findIndex((f) => f["id"] === 2);
    const response3 = frames.findIndex((f) => f["id"] === 3);
    expect(response2).toBeGreaterThan(-1);
    expect(response3).toBeGreaterThan(-1);
    const notifications = frames
      .map((f, index) => ({ f, index }))
      .filter(({ f }) => f["method"] === PROGRESS_NOTIFICATION_METHOD);
    expect(notifications.length).toBeGreaterThan(0);
    for (const { f, index } of notifications) {
      const token = (f["params"] as JsonObject)["progressToken"];
      expect(index).toBeLessThan(token === "tok-a" ? response2 : response3);
    }
    for (const chunk of chunks) expect(chunk.endsWith("\n")).toBe(true);
  });

  test("a progress frame never interleaves inside a response frame on a real stream", async () => {
    const stdin = new PassThrough();
    const chunks: string[] = [];
    const stdout = new PassThrough();
    stdout.on("data", (c: Buffer) => chunks.push(c.toString("utf8")));

    const done = serveStdio({ vault }, { stdin, stdout });
    stdin.write(JSON.stringify(INITIALIZE) + "\n");
    stdin.write(JSON.stringify(dreamCall(2, "tok")) + "\n");
    stdin.end();
    await done;

    // Every write is exactly one newline-terminated frame: joining the
    // chunks and splitting on "\n" must parse cleanly, and the last
    // progress frame must precede the response.
    const frames = lines(chunks.join(""));
    const responseIndex = frames.findIndex((f) => f["id"] === 2);
    const progressIndexes = frames
      .map((f, i) => (f["method"] === PROGRESS_NOTIFICATION_METHOD ? i : -1))
      .filter((i) => i !== -1);
    expect(progressIndexes.length).toBeGreaterThan(0);
    expect(Math.max(...progressIndexes)).toBeLessThan(responseIndex);
    for (const chunk of chunks) expect(chunk.endsWith("\n")).toBe(true);
  });
});

/**
 * The view dispatcher, from the outside.
 *
 * `dispatchByView` routes a consolidated tool's `view` argument to its
 * per-view handler, and it used to call `handler(ctx, args)` - dropping
 * the sink on the floor. Restoring that one-line defect left the whole
 * of `tests/mcp` plus the progress suites at 882 pass / 0 fail, because
 * no test sent a progress token through a dispatched tool. This block
 * is that test: `brain_brief view=operator` is the consumer that made
 * the fix necessary, since it runs a dry-run consolidation pass and is
 * the slow half of an operator summary on a large vault.
 */
describe("a dispatched view carries the sink", () => {
  function briefCall(id: number, token?: string): JsonObject {
    return {
      jsonrpc: JSONRPC_VERSION,
      id,
      method: "tools/call",
      params: {
        name: "brain_brief",
        arguments: { view: "operator" },
        ...(token === undefined ? {} : { _meta: { progressToken: token } }),
      },
    };
  }

  test("brain_brief view=operator emits progress frames for its dream pass", async () => {
    const frames = lines(
      await serveStdioFromString(
        { vault },
        JSON.stringify(INITIALIZE) + "\n" + JSON.stringify(briefCall(2, "tok-brief")) + "\n",
      ),
    );
    const responseIndex = frames.findIndex((f) => f["id"] === 2);
    expect(responseIndex).toBeGreaterThan(-1);
    expect(frames[responseIndex]?.["error"]).toBeUndefined();

    const notifications = frames.filter((f) => f["method"] === PROGRESS_NOTIFICATION_METHOD);
    // The assertion the dropped sink fails: a dispatcher that swallows it
    // produces a response and no frames at all, which is exactly what a
    // hung run looks like.
    expect(notifications.length).toBeGreaterThan(0);
    for (const n of notifications) expect(frames.indexOf(n)).toBeLessThan(responseIndex);

    const params = notifications[0]!["params"] as JsonObject;
    expect(params["progressToken"]).toBe("tok-brief");
    const event = (params["_meta"] as JsonObject)[PROGRESS_META_KEY] as JsonObject;
    expect(event["schema"]).toBe(PROGRESS_SCHEMA);
    // The operation naming the pass the sink reached, not merely "some
    // frames arrived": the dispatcher's job is to hand the sink to the
    // handler that runs the long half.
    expect(event["operation"]).toBe("dream");
    expect(isProgressKind(event["kind"])).toBe(true);
  });

  test("the same view with no token emits nothing", async () => {
    // The negative control for the test above: the frames it counts are
    // caused by the token, not by the tool being noisy.
    const frames = lines(
      await serveStdioFromString(
        { vault },
        JSON.stringify(INITIALIZE) + "\n" + JSON.stringify(briefCall(2)) + "\n",
      ),
    );
    expect(frames.filter((f) => f["method"] !== undefined)).toEqual([]);
  });
});

describe("a malformed progress token is refused by name", () => {
  const server = (): MCPServer => new MCPServer({ vault });

  test.each([
    [true, "boolean"],
    [null, "null"],
    [{}, "object"],
    [[], "array"],
    [1.5, "fractional"],
  ] as ReadonlyArray<readonly [unknown, string]>)(
    "%p is refused naming what was wrong",
    async (token, expected) => {
      const res = await server().handleRequest({
        jsonrpc: JSONRPC_VERSION,
        id: 3,
        method: "tools/call",
        params: { name: "brain_dream", arguments: {}, _meta: { progressToken: token } },
      });
      expect(res?.error?.code).toBe(-32602);
      expect(res?.error?.message).toContain("_meta.progressToken");
      expect(res?.error?.message).toContain(expected);
    },
  );

  test("a non-object _meta is refused naming _meta", async () => {
    const res = await server().handleRequest({
      jsonrpc: JSONRPC_VERSION,
      id: 4,
      method: "tools/call",
      params: { name: "brain_dream", arguments: {}, _meta: "nope" },
    });
    expect(res?.error?.code).toBe(-32602);
    expect(res?.error?.message).toContain("_meta");
  });

  test("a _meta without a progressToken is not a token and not an error", async () => {
    const res = await server().handleRequest({
      jsonrpc: JSONRPC_VERSION,
      id: 5,
      method: "tools/call",
      params: { name: "brain_dream", arguments: { dry_run: true }, _meta: { other: 1 } },
    });
    expect(res?.error).toBeUndefined();
    const result = res?.result as JsonObject | undefined;
    expect(result?.["_meta"]).toBeUndefined();
  });
});

describe("HTTP refuses a progress token by name", () => {
  test("the refusal rides on result._meta and no progress frames are sent", async () => {
    const handle = await startHttp({ vault }, { host: "127.0.0.1", port: 0 });
    try {
      const res = await fetch(handle.url, {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify(dreamCall(2, "tok-http")),
      });
      const body = (await res.json()) as JsonObject;
      const refusal = (body["result"]["_meta"] as JsonObject)[PROGRESS_META_KEY] as JsonObject;
      expect(refusal["schema"]).toBe(PROGRESS_SCHEMA);
      expect(refusal["kind"]).toBe(PROGRESS_KIND.refused);
      expect(refusal["reason"]).toBe(PROGRESS_REASON.transportSingleResponse);
      expect(refusal["progressToken"]).toBe("tok-http");
      // One response, no notification frames anywhere in the body.
      expect(JSON.stringify(body)).not.toContain(PROGRESS_NOTIFICATION_METHOD);
    } finally {
      await handle.close();
    }
  });

  test("a call with no token carries no _meta at all", async () => {
    const handle = await startHttp({ vault }, { host: "127.0.0.1", port: 0 });
    try {
      const res = await fetch(handle.url, {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify(dreamCall(2)),
      });
      const body = (await res.json()) as JsonObject;
      expect(body["result"]["_meta"]).toBeUndefined();
    } finally {
      await handle.close();
    }
  });
});

describe("withProgressRefusal", () => {
  // The merge beside an error code is covered end to end by
  // tool-error-envelope.test.ts; this pins the no-refusal identity, which
  // keeps a call that asked for no progress byte-identical.
  test("no refusal returns the very same result object", () => {
    const ok = { content: [], isError: false };
    expect(withProgressRefusal(ok, undefined)).toBe(ok);
  });
});