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
13.4 KB
Raw Blame
/**
 * `brain_generation_reports` - inbound, opt-in LLM generation tracing
 * (Hindsight brain-loop ops, t_281c3edc).
 *
 * Open Second Brain's kernel never calls an LLM; the agent owns
 * generation. After it fulfils a handoff (write-session step,
 * context-pack consume, or dream-stage proposal) it can report the real
 * usage back through action `record`, which lands as a `generation_report`
 * continuity record correlated to the paths and ids the kernel owns.
 * Actions `list` and `summary` read the records and join them to memory
 * paths. `record` is gated (default off): a per-call `enable` flag or the
 * `generation_trace_enabled` config opens it; otherwise nothing is built
 * or written. Only `prompt_hash` + counts are stored, never the prompt.
 *
 * Registration happens through the brain-tools aggregator, which
 * preserves the public BRAIN_TOOLS surface.
 */

import { resolveGenerationTraceEnabled } from "../../core/config.ts";
import {
  emitGenerationReport,
  isGenerationHandoffKind,
  listGenerationReports,
  summarizeGenerationReports,
  type GenerationHandoffKind,
  type GenerationReportFilter,
  type GenerationUsage,
} from "../../core/brain/generation-reports.ts";
import { isCanonicalUtcTimestamp } from "../../core/brain/continuity/store.ts";
import type { ContinuitySourceRef } from "../../core/brain/continuity/types.ts";
import { pageSlice } from "../../core/brain/offset-cursor.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import type { ServerContext, ToolDefinition } from "../tool-contract.ts";
import { vaultPathField } from "../vault-path-field.ts";
import { MCP_PREVIEW_BUDGET } from "../preview-budget.ts";
import { coercePositiveInteger, optionalStringArg, requiredStringArg } from "./shared.ts";
import { cursorOffsetArg, CURSOR_SCHEMA } from "./pagination.ts";
import { unknownOperationError } from "../coerce.ts";

const TOOL = "brain_generation_reports";

async function toolBrainGenerationReports(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const action = optionalStringArg(TOOL, args, "action");
  if (action === "record") return recordAction(ctx, args);
  if (action === "list") {
    const filter = readFilter(args);
    const offset = cursorOffsetArg(TOOL, args);
    // The full filtered set is read and one page is cut here, so `total`
    // stays the exact count matching the filter across all pages and the
    // walk continues through `next_cursor` (null when exhausted).
    const reports = listGenerationReports(ctx.vault, { ...filter, limit: undefined });
    const page = pageSlice(reports, offset, filter.limit ?? Math.max(reports.length, 1));
    return {
      vault_path: vaultPathField(ctx),
      total: page.total,
      reports: page.items,
      next_cursor: page.next_cursor,
    };
  }
  if (action === "summary") {
    return { ...summarizeGenerationReports(ctx.vault, readFilter(args)) };
  }
  throw unknownOperationError(`${TOOL}: action must be record, list, or summary`);
}

function recordAction(ctx: ServerContext, args: Record<string, unknown>): Record<string, unknown> {
  const handoffKind = handoffKindArg(args["handoff_kind"]);
  const ref = requiredStringArg(TOOL, args, "ref");
  const agent = requiredStringArg(TOOL, args, "agent");
  const prompt = requiredStringArg(TOOL, args, "prompt");

  // Validate `created_at` here rather than relying on the store guard:
  // `emitGenerationReport` is fail-open (a throwing build returns null),
  // so a malformed timestamp would silently report `recorded: false`
  // instead of the INVALID_PARAMS the caller needs.
  const createdAt = optionalStringArg(TOOL, args, "created_at");
  if (createdAt !== undefined && !isCanonicalUtcTimestamp(createdAt)) {
    throw new MCPError(
      INVALID_PARAMS,
      `${TOOL}: created_at must be a canonical UTC ISO-8601 timestamp ` +
        `(e.g. 2026-07-06T15:00:00Z or 2026-07-06T15:00:00.000Z)`,
    );
  }

  // Opt-in: per-call enable wins, else the config gate. Off => nothing written.
  const enabled =
    args["enable"] === true || resolveGenerationTraceEnabled(ctx.configPath ?? undefined);

  const record = emitGenerationReport(
    ctx.vault,
    {
      handoff: { kind: handoffKind, ref },
      agent,
      prompt,
      ...(optionalStringArg(TOOL, args, "scope") !== undefined
        ? { scope: optionalStringArg(TOOL, args, "scope") }
        : {}),
      ...(optionalStringArg(TOOL, args, "provider") !== undefined
        ? { provider: optionalStringArg(TOOL, args, "provider") }
        : {}),
      ...(optionalStringArg(TOOL, args, "model") !== undefined
        ? { model: optionalStringArg(TOOL, args, "model") }
        : {}),
      ...(optionalStringArg(TOOL, args, "finish_reason") !== undefined
        ? { finishReason: optionalStringArg(TOOL, args, "finish_reason") }
        : {}),
      ...(coercePositiveInteger(TOOL, "latency_ms", args["latency_ms"]) !== undefined
        ? { latencyMs: coercePositiveInteger(TOOL, "latency_ms", args["latency_ms"]) }
        : {}),
      ...(usageArg(args["usage"]) !== undefined ? { usage: usageArg(args["usage"]) } : {}),
      ...(sourceRefArgs(args["source_refs"]).length > 0
        ? { sourceRefs: sourceRefArgs(args["source_refs"]) }
        : {}),
      ...(optionalStringArg(TOOL, args, "created_at") !== undefined
        ? { createdAt: optionalStringArg(TOOL, args, "created_at") }
        : {}),
    },
    enabled,
  );

  return record !== null
    ? { vault_path: vaultPathField(ctx), recorded: true, id: record.id }
    : { vault_path: vaultPathField(ctx), recorded: false, reason: "disabled" };
}

function readFilter(args: Record<string, unknown>): GenerationReportFilter {
  const handoff = optionalStringArg(TOOL, args, "handoff_kind");
  if (handoff !== undefined && !isGenerationHandoffKind(handoff)) {
    throw new MCPError(
      INVALID_PARAMS,
      `${TOOL}: handoff_kind must be write_session, context_pack, or dream_stage`,
    );
  }
  const limit = coercePositiveInteger(TOOL, "limit", args["limit"]);
  return {
    ...(handoff !== undefined ? { handoffKind: handoff as GenerationHandoffKind } : {}),
    ...(optionalStringArg(TOOL, args, "agent") !== undefined
      ? { agent: optionalStringArg(TOOL, args, "agent") }
      : {}),
    ...(optionalStringArg(TOOL, args, "since") !== undefined
      ? { since: optionalStringArg(TOOL, args, "since") }
      : {}),
    ...(optionalStringArg(TOOL, args, "until") !== undefined
      ? { until: optionalStringArg(TOOL, args, "until") }
      : {}),
    ...(limit !== undefined ? { limit } : {}),
  };
}

function handoffKindArg(raw: unknown): GenerationHandoffKind {
  if (typeof raw !== "string" || raw.trim().length === 0) {
    throw new MCPError(INVALID_PARAMS, `${TOOL}: handoff_kind is required for record`);
  }
  const value = raw.trim();
  if (!isGenerationHandoffKind(value)) {
    throw new MCPError(
      INVALID_PARAMS,
      `${TOOL}: handoff_kind must be write_session, context_pack, or dream_stage`,
    );
  }
  return value;
}

function usageArg(raw: unknown): GenerationUsage | undefined {
  if (raw === undefined || raw === null) return undefined;
  if (typeof raw !== "object" || Array.isArray(raw)) {
    throw new MCPError(INVALID_PARAMS, `${TOOL}: usage must be an object`);
  }
  const obj = raw as Record<string, unknown>;
  const usage: GenerationUsage = {
    ...(numberArg(obj["input_tokens"], "usage.input_tokens") !== undefined
      ? { inputTokens: numberArg(obj["input_tokens"], "usage.input_tokens") }
      : {}),
    ...(numberArg(obj["output_tokens"], "usage.output_tokens") !== undefined
      ? { outputTokens: numberArg(obj["output_tokens"], "usage.output_tokens") }
      : {}),
    ...(numberArg(obj["cached_tokens"], "usage.cached_tokens") !== undefined
      ? { cachedTokens: numberArg(obj["cached_tokens"], "usage.cached_tokens") }
      : {}),
    ...(numberArg(obj["total_tokens"], "usage.total_tokens") !== undefined
      ? { totalTokens: numberArg(obj["total_tokens"], "usage.total_tokens") }
      : {}),
  };
  return Object.keys(usage).length > 0 ? usage : undefined;
}

function numberArg(raw: unknown, key: string): number | undefined {
  if (raw === undefined || raw === null) return undefined;
  if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0) {
    throw new MCPError(INVALID_PARAMS, `${TOOL}: ${key} must be a non-negative integer`);
  }
  return raw;
}

function sourceRefArgs(raw: unknown): ReadonlyArray<ContinuitySourceRef> {
  if (raw === undefined || raw === null) return [];
  if (!Array.isArray(raw)) {
    throw new MCPError(INVALID_PARAMS, `${TOOL}: source_refs must be an array`);
  }
  return raw.map((entry, index) => {
    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
      throw new MCPError(INVALID_PARAMS, `${TOOL}: source_refs[${index}] must be an object`);
    }
    const obj = entry as Record<string, unknown>;
    const id = obj["id"];
    if (typeof id !== "string" || id.trim().length === 0) {
      throw new MCPError(INVALID_PARAMS, `${TOOL}: source_refs[${index}].id must be a string`);
    }
    const ref: ContinuitySourceRef = {
      id: id.trim(),
      ...(typeof obj["path"] === "string" && obj["path"].trim().length > 0
        ? { path: obj["path"].trim() }
        : {}),
      ...(typeof obj["kind"] === "string" && obj["kind"].trim().length > 0
        ? { kind: obj["kind"].trim() }
        : {}),
    };
    return ref;
  });
}

export const GENERATION_TOOLS: ReadonlyArray<ToolDefinition> = Object.freeze([
  {
    name: TOOL,
    kind: "write",
    previewBudget: MCP_PREVIEW_BUDGET,
    description:
      "Inbound, opt-in LLM generation tracing; the kernel never calls an LLM. action=record posts a generation's usage for a handoff, gated default-off via enable or generation_trace_enabled, storing prompt_hash + token counts only, never the prompt. action=list/summary read and join to memory paths.",
    inputSchema: {
      type: "object",
      properties: {
        action: {
          type: "string",
          enum: ["record", "list", "summary"],
          description: "record an inbound report, or list/summary the stored reports.",
        },
        handoff_kind: {
          type: "string",
          enum: ["write_session", "context_pack", "dream_stage"],
          description:
            "record: which handoff this generation fulfilled. Also filters list/summary.",
        },
        ref: {
          type: "string",
          description: "record: the handoff id (session id, receipt id, run id).",
        },
        agent: {
          type: "string",
          description: "record: reporting agent; also filters list/summary.",
        },
        prompt: {
          type: "string",
          description:
            "record: the exact handoff prompt. Hashed and counted only - never stored as raw text.",
        },
        enable: {
          type: "boolean",
          description: "record: open the gate for this single call even if the config gate is off.",
        },
        scope: { type: "string", description: "record: optional scope label." },
        provider: { type: "string", description: "record: opaque agent-reported provider." },
        model: { type: "string", description: "record: opaque agent-reported model." },
        finish_reason: { type: "string", description: "record: optional finish reason." },
        latency_ms: { type: "integer", minimum: 1, description: "record: optional latency in ms." },
        usage: {
          type: "object",
          description:
            "record: optional agent-reported token usage (input_tokens, output_tokens, cached_tokens, total_tokens).",
          properties: {
            input_tokens: {
              type: "integer",
              minimum: 0,
              description: "Prompt tokens the provider billed.",
            },
            output_tokens: {
              type: "integer",
              minimum: 0,
              description: "Completion tokens the provider billed.",
            },
            cached_tokens: {
              type: "integer",
              minimum: 0,
              description: "Prompt tokens served from the provider's cache.",
            },
            total_tokens: {
              type: "integer",
              minimum: 0,
              description: "Provider-reported total; stored as given, never recomputed.",
            },
          },
          additionalProperties: false,
        },
        source_refs: {
          type: "array",
          description:
            "record: artifact join refs ({id, path?, kind?}) - e.g. the memory paths this generation produced or consumed.",
          items: {
            type: "object",
            properties: {
              id: { type: "string", description: "Identifier of the joined artifact. Required." },
              path: { type: "string", description: "Optional vault path of the artifact." },
              kind: { type: "string", description: "Optional artifact kind label." },
            },
            required: ["id"],
            additionalProperties: false,
          },
        },
        created_at: {
          type: "string",
          description: "record: optional ISO timestamp (defaults to now).",
        },
        since: { type: "string", description: "list/summary: inclusive ISO lower bound." },
        until: { type: "string", description: "list/summary: inclusive ISO upper bound." },
        limit: { type: "integer", minimum: 1, description: "list: maximum record count." },
        cursor: CURSOR_SCHEMA,
      },
      required: ["action"],
      additionalProperties: false,
    },
    handler: toolBrainGenerationReports,
  },
]);