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
7.4 KB
Raw Blame
/**
 * The progress spine at the MCP boundary (nothing-runs-unwatched, U2).
 *
 * A client asks for liveness by putting a token on the request:
 * `params._meta.progressToken`. Until this module `handleToolsCall` read
 * exactly two keys from `params` - `name` and `arguments` - so the token
 * was accepted by the wire and then discarded without a word. That is the
 * silent drop this release exists to remove, and there are only two
 * honest answers to it: carry the events, or say why they cannot be
 * carried.
 *
 * Which answer a transport gives is decided by whether it can write an
 * unsolicited frame at all, not by a flag. stdio reads and writes a
 * newline-delimited duplex stream, so it hands the server a notification
 * writer and the events go out ahead of the response. The HTTP transport
 * answers one request with one response and closes
 * (`res.end` in `http.ts`), so it hands over nothing, and a token that
 * arrives there is refused by name with
 * {@link PROGRESS_REASON.transportSingleResponse} rather than accepted
 * and dropped - accepting it would advertise liveness support that does
 * not exist.
 *
 * The refusal rides on `result._meta`, which is where MCP reserves room
 * for implementation metadata, and it is the exact reciprocal of where
 * the request carried the token. The two alternatives are both wrong for
 * reasons this repository has already written down: `structuredContent`
 * is validated against the tool's `outputSchema`, so a transport fact
 * there would break the contract a caller parses, and `content[0].text`
 * is that same payload rendered - the advisory rail's rule that a
 * machine-readable stream is not a place to put a remark applies
 * verbatim. `_meta` is absent entirely when no token was sent, so a
 * client that did not ask sees a byte-identical response.
 */

import {
  PROGRESS_KIND,
  PROGRESS_SCHEMA,
  type ProgressEvent,
  type ProgressReason,
  type ProgressSink,
} from "../core/brain/progress.ts";
import { INVALID_PARAMS, JSONRPC_VERSION, MCPError } from "./protocol.ts";
import type { JsonRpcNotification } from "./protocol.ts";

/** Spec method name for a progress notification. */
export const PROGRESS_NOTIFICATION_METHOD = "notifications/progress";

/**
 * The `_meta` member both directions of this feature travel under.
 * Namespaced because `_meta` is a shared extension point: a key without a
 * prefix would collide with the next implementation that wants one.
 */
export const PROGRESS_META_KEY = "open-second-brain/progress";

/**
 * The member of a `tools/call` request's params and of its result that
 * namespaced extensions ride on.
 */
export const META_MEMBER = "_meta";

/**
 * What the MCP specification allows a progress token to be: a string or
 * an integer. Deliberately not `number` - a fractional token is a client
 * defect, and coercing it would hand back a value the client cannot match
 * to the request it sent.
 */
export type ProgressToken = string | number;

/**
 * Why no progress could be carried, addressed to the token that asked.
 *
 * A distinct shape from {@link ProgressEvent} rather than a `refused`
 * event with invented fields: the refusal happens before any operation
 * has spoken, so there is no `operation`, no `stage` and no count to
 * report, and filling those in with zeroes would describe a run that
 * never started.
 */
export interface ProgressRefusal {
  readonly schema: typeof PROGRESS_SCHEMA;
  readonly kind: typeof PROGRESS_KIND.refused;
  readonly reason: ProgressReason;
  readonly progressToken: ProgressToken;
}

/** Names the JSON shape of a rejected value, for an error that must say what was wrong. */
function describeValue(value: unknown): string {
  if (value === null) return "null";
  if (Array.isArray(value)) return "array";
  if (typeof value === "number") return Number.isInteger(value) ? "number" : "fractional number";
  return typeof value;
}

/**
 * The client's progress token, or `undefined` when it asked for none.
 *
 * Throws {@link MCPError} rather than coercing or ignoring: a token the
 * server silently rewrote could not be matched back to the request that
 * carried it, and a token the server silently dropped is the defect this
 * module exists to remove. An absent `_meta`, and a `_meta` carrying
 * other members but no `progressToken`, both mean "nobody asked" and are
 * not errors.
 */
export function readProgressToken(params: Record<string, unknown>): ProgressToken | undefined {
  const meta = params[META_MEMBER];
  if (meta === undefined) return undefined;
  if (typeof meta !== "object" || meta === null || Array.isArray(meta)) {
    throw new MCPError(
      INVALID_PARAMS,
      `tools/call _meta must be an object, got ${describeValue(meta)}`,
    );
  }
  const token = (meta as Record<string, unknown>)["progressToken"];
  if (token === undefined) return undefined;
  if (typeof token === "string") return token;
  if (typeof token === "number" && Number.isInteger(token)) return token;
  throw new MCPError(
    INVALID_PARAMS,
    `tools/call _meta.progressToken must be a string or an integer, got ${describeValue(token)}`,
  );
}

/**
 * One `notifications/progress` frame.
 *
 * `progress` and `total` are the spec's own numeric fields, so a client
 * that knows nothing about this repository still renders a bar; the typed
 * event travels beside them under {@link PROGRESS_META_KEY}, so a client
 * that does gets the stage identifier and the operation name without the
 * server having to render a sentence for either.
 */
export function progressNotification(
  token: ProgressToken,
  event: ProgressEvent,
): JsonRpcNotification {
  return {
    jsonrpc: JSONRPC_VERSION,
    method: PROGRESS_NOTIFICATION_METHOD,
    params: {
      progressToken: token,
      progress: event.completed,
      ...(event.total === undefined ? {} : { total: event.total }),
      _meta: { [PROGRESS_META_KEY]: event },
    },
  };
}

/**
 * A sink that turns each event into a notification frame, or `undefined`
 * when there is nothing to turn them into - no token, or no writer.
 *
 * Synchronous by construction, because the spine's sink is: `dream` and
 * its peers are synchronous functions and cannot await a write inside
 * their own loops.
 */
export function progressSink(
  token: ProgressToken | undefined,
  send: ((notification: JsonRpcNotification) => void) | undefined,
): ProgressSink | undefined {
  if (token === undefined || send === undefined) return undefined;
  return (event: ProgressEvent) => send(progressNotification(token, event));
}

/** The typed refusal a single-response transport answers a token with. */
export function progressRefusal(token: ProgressToken, reason: ProgressReason): ProgressRefusal {
  return {
    schema: PROGRESS_SCHEMA,
    kind: PROGRESS_KIND.refused,
    reason,
    progressToken: token,
  };
}

/**
 * Attach a refusal to a `tools/call` result, merged into any `_meta` the
 * result already carries (an error result's code, for one). With no refusal the result
 * is returned untouched - not cloned with an empty `_meta` - so a call
 * that asked for no progress is byte-identical to the one the previous
 * release answered.
 */
export function withProgressRefusal(
  result: Record<string, unknown>,
  refusal: ProgressRefusal | undefined,
): Record<string, unknown> {
  if (refusal === undefined) return result;
  const existing = result[META_MEMBER] as Readonly<Record<string, unknown>> | undefined;
  return { ...result, [META_MEMBER]: { ...existing, [PROGRESS_META_KEY]: refusal } };
}