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
6.9 KB
Raw Blame
/**
 * `brain_write_session` (task 3.19): the interactive write-session
 * lifecycle a caller drives operation by operation, answered in the
 * same JSON envelopes the CLI prints. Split from `context-tools.ts`;
 * registration happens through that module's registry, which preserves
 * the public CONTEXT_TOOLS surface.
 */

import { resolveAgentName } from "../../core/config.ts";
import { normalizeAgentArgument } from "../../core/agent-identity.ts";
import {
  WriteSessionRequestError,
  type WriteSessionRequestReason,
  abandonSession,
  approveSession,
  openArtifactSession,
  sessionEnvelope,
} from "../../core/brain/write-session/engine.ts";
import { dispatchSubmit, openPanelSession } from "../../core/brain/write-session/panel.ts";
import { listWriteSessions, readWriteSession } from "../../core/brain/write-session/store.ts";
import type { WriteSessionEnvelope } from "../../core/brain/write-session/types.ts";
import { pageSlice } from "../../core/brain/offset-cursor.ts";
import { cursorOffsetArg } from "./pagination.ts";
import { INVALID_PARAMS, MCPError } from "../protocol.ts";
import { TOOL_ERROR_CODE, type ToolErrorCode } from "../tool-error-codes.ts";
import { type ServerContext } from "../tool-contract.ts";
import { coerceStr, coerceInt, unknownOperationError } from "../coerce.ts";

export async function toolBrainWriteSession(
  ctx: ServerContext,
  args: Record<string, unknown>,
): Promise<Record<string, unknown>> {
  const op = coerceStr(args, "op", true)!;
  const sessionId = coerceStr(args, "session_id", false);
  const requireSessionId = (): string => {
    if (!sessionId) {
      throw new MCPError(INVALID_PARAMS, `brain_write_session: op '${op}' requires session_id`, {
        code: TOOL_ERROR_CODE.sessionIdRequired,
      });
    }
    return sessionId;
  };
  try {
    switch (op) {
      case "open": {
        const kind = coerceStr(args, "kind", false) ?? "artifact";
        const agent =
          normalizeAgentArgument(coerceStr(args, "agent", false) ?? null) ??
          resolveAgentName(ctx.configPath ?? undefined);
        const requireReview = args["require_review"] === true;
        if (kind === "panel") {
          const topic = coerceStr(args, "topic", true)!;
          const personasRaw = args["personas"];
          const personas = Array.isArray(personasRaw)
            ? personasRaw.filter((x): x is string => typeof x === "string")
            : undefined;
          const target = coerceStr(args, "target", false);
          return asRecord(
            openPanelSession(ctx.vault, {
              agent,
              topic,
              requireReview,
              ...(personas && personas.length > 0 ? { personas } : {}),
              ...(target ? { targetPath: target } : {}),
            }),
          );
        }
        if (kind !== "artifact") {
          throw new MCPError(
            INVALID_PARAMS,
            `brain_write_session: kind must be 'artifact' or 'panel', got '${kind}'`,
          );
        }
        const target = coerceStr(args, "target", true)!;
        const intent = coerceStr(args, "intent", false) ?? "create";
        if (intent !== "create" && intent !== "overwrite" && intent !== "merge") {
          throw new MCPError(
            INVALID_PARAMS,
            `brain_write_session: intent must be create|overwrite|merge, got '${intent}'`,
          );
        }
        const schemaType = coerceStr(args, "schema_type", false);
        const prompt = coerceStr(args, "prompt", false);
        const retryCap = args["retry_cap"];
        return asRecord(
          openArtifactSession(ctx.vault, {
            agent,
            targetPath: target,
            intent,
            requireReview,
            ...(schemaType ? { schemaType } : {}),
            ...(prompt ? { prompt } : {}),
            ...(typeof retryCap === "number" ? { retryCap } : {}),
          }),
        );
      }
      case "submit": {
        const id = requireSessionId();
        const text = coerceStr(args, "text", true)!;
        return asRecord(dispatchSubmit(ctx.vault, { sessionId: id, text }));
      }
      case "approve":
        return asRecord(approveSession(ctx.vault, { sessionId: requireSessionId() }));
      case "abandon":
        return asRecord(abandonSession(ctx.vault, { sessionId: requireSessionId() }));
      case "status": {
        const id = requireSessionId();
        const probe = readWriteSession(ctx.vault, id, new Date().toISOString());
        if (probe.error !== null) throw new MCPError(INVALID_PARAMS, probe.error);
        if (probe.session === null) {
          throw new MCPError(INVALID_PARAMS, `unknown write-session: ${id}`, {
            code: WRITE_SESSION_REASON_CODE["unknown-session"],
          });
        }
        return asRecord(sessionEnvelope(probe.session));
      }
      case "list": {
        const limit = coerceInt(args, "limit", 100, 1, 500);
        const offset = cursorOffsetArg("brain_write_session", args);
        const sessions = listWriteSessions(ctx.vault, new Date().toISOString());
        const page = pageSlice(sessions, offset, limit);
        return {
          // `total` counts every session in the list across pages; the
          // page itself is `sessions`.
          total: page.total,
          sessions: page.items.map((rec) => asRecord(sessionEnvelope(rec))),
          next_cursor: page.next_cursor,
        };
      }
      default:
        throw unknownOperationError(
          `brain_write_session: op must be open|submit|approve|abandon|status|list, got '${op}'`,
        );
    }
  } catch (err) {
    if (err instanceof WriteSessionRequestError) {
      // Preserve the {code, path, message} boundary contract: the
      // structured list rides MCPError's data slot, the message stays
      // human-readable prose.
      throw new MCPError(INVALID_PARAMS, err.message, writeSessionErrorData(err));
    }
    throw err;
  }
}

/**
 * The wire code for each session refusal the engine names. Total over the
 * core union, so a new reason fails the type check until it is mapped.
 */
export const WRITE_SESSION_REASON_CODE: Readonly<Record<WriteSessionRequestReason, ToolErrorCode>> =
  Object.freeze({
    "unknown-session": TOOL_ERROR_CODE.writeSessionUnknown,
    "terminal-session": TOOL_ERROR_CODE.writeSessionTerminal,
  });

/**
 * `data` for a request failure: the structured error list when there is
 * one, the precise code when the engine named a reason, nothing otherwise
 * - an absent code is filled by the boundary's `invalid_params` default.
 */
export function writeSessionErrorData(
  err: WriteSessionRequestError,
): Readonly<Record<string, unknown>> | undefined {
  const data = {
    ...(err.errors.length > 0 ? { errors: err.errors } : {}),
    ...(err.reason !== undefined ? { code: WRITE_SESSION_REASON_CODE[err.reason] } : {}),
  };
  return Object.keys(data).length > 0 ? data : undefined;
}

export function asRecord(envelope: WriteSessionEnvelope): Record<string, unknown> {
  return { ...envelope };
}