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.9 KB
Raw Blame
/**
 * Write-session store (Agent Write Contract Suite, t_bc36a8a2).
 *
 * One JSON file per session under `Brain/.sessions/write/<id>.json`,
 * consistent with the `Brain/.payloads/` convention: dot-prefixed,
 * vault-synced, machine-owned. snake_case on disk, camelCase in TS,
 * atomic writes through `fs-atomic`.
 *
 * TTL is LAZY: expiry is evaluated on read (an expired non-terminal
 * session reads as terminal `failed`/`expired`), and
 * {@link sweepWriteSessions} deletes terminal and expired files. No
 * daemon, no background timer - the same pattern as every other OSB
 * maintenance surface.
 *
 * Tolerant reads: a corrupted session file surfaces as a probe error
 * (never a throw), mirroring `readGitState` / the log parser.
 */

import { join } from "node:path";

import {
  isTerminalWriteSessionStatus,
  type WriteSessionError,
  type WriteSessionIntent,
  type WriteSessionKind,
  type WriteSessionPersona,
  type WriteSessionProbe,
  type WriteSessionRecord,
  type WriteSessionStatus,
} from "./types.ts";
import {
  assertLaneWrite,
  lanePageExists,
  lanePagesInStore,
  listLaneFiles,
  readLaneText,
  removeLanePage,
  writeLaneText,
} from "../../store/lane-pages.ts";
import { deviceMintTag } from "../record-name.ts";

/** Session ids are lowercase slugs - the grammar doubles as path safety. */
const SESSION_ID_RE = /^ws-[a-z0-9][a-z0-9-]*$/;

const STATUS_SET: ReadonlySet<string> = new Set([
  "needs-llm-step",
  "needs-correction",
  "needs-review",
  "done",
  "failed",
]);

const KIND_SET: ReadonlySet<string> = new Set(["artifact", "panel"]);
const INTENT_SET: ReadonlySet<string> = new Set(["create", "overwrite", "merge"]);

export function isWriteSessionId(value: unknown): value is string {
  return typeof value === "string" && SESSION_ID_RE.test(value);
}

/** Session directory inside the vault. */
export function writeSessionDir(vault: string): string {
  return join(vault, "Brain", ".sessions", "write");
}

/** Path of one session file; the id grammar is enforced first. */
export function writeSessionPath(vault: string, id: string): string {
  if (!isWriteSessionId(id)) {
    throw new Error(`invalid write-session id: ${JSON.stringify(id)}`);
  }
  return join(writeSessionDir(vault), `${id}.json`);
}

/**
 * Allocate a collision-free session id from the supplied timestamp.
 * `ws-<yyyymmdd>-<hhmmss>` (plus this device's tag once switched, see
 * `deviceMintTag`) with `-2`, `-3`, ... suffixes when a session landed in
 * the same second - deterministic for fixture callers.
 */
export function allocateWriteSessionId(vault: string, nowIso: string): string {
  const ts = Date.parse(nowIso);
  if (Number.isNaN(ts)) {
    throw new Error(`invalid session timestamp: ${nowIso}`);
  }
  const iso = new Date(ts).toISOString();
  const second = `ws-${iso.slice(0, 10).replaceAll("-", "")}-${iso.slice(11, 19).replaceAll(":", "")}`;
  // Once switched the id carries this device's tag: two synced devices
  // starting a session in the same second would otherwise write one entry.
  const tag = lanePagesInStore(vault) ? deviceMintTag() : null;
  const stem = tag === null ? second : `${second}-${tag}`;
  if (!lanePageExists(vault, join(writeSessionDir(vault), `${stem}.json`))) return stem;
  for (let n = 2; n < 10_000; n++) {
    const candidate = `${stem}-${n}`;
    if (!lanePageExists(vault, join(writeSessionDir(vault), `${candidate}.json`))) return candidate;
  }
  throw new Error(`could not allocate a write-session id for ${stem}`);
}

function serializeRecord(record: WriteSessionRecord): string {
  return (
    JSON.stringify(
      {
        id: record.id,
        kind: record.kind,
        status: record.status,
        step: record.step,
        agent: record.agent,
        created_at: record.createdAt,
        updated_at: record.updatedAt,
        expires_at: record.expiresAt,
        attempts: record.attempts,
        retry_cap: record.retryCap,
        target_path: record.targetPath,
        intent: record.intent,
        require_review: record.requireReview,
        prompt: record.prompt,
        schema_type: record.schemaType,
        topic: record.topic,
        personas: record.personas.map((p) => ({ slug: p.slug, lens: p.lens, prompt: p.prompt })),
        responses: record.responses,
        pending_artifact: record.pendingArtifact,
        last_errors: record.lastErrors.map((e) => ({
          code: e.code,
          path: e.path,
          message: e.message,
        })),
        fail_reason: record.failReason,
      },
      null,
      2,
    ) + "\n"
  );
}

function str(rec: Record<string, unknown>, key: string): string {
  return typeof rec[key] === "string" ? (rec[key] as string) : "";
}

function parsePersonas(raw: unknown): ReadonlyArray<WriteSessionPersona> {
  if (!Array.isArray(raw)) return Object.freeze([]);
  const personas: WriteSessionPersona[] = [];
  for (const item of raw) {
    if (typeof item !== "object" || item === null) continue;
    const p = item as Record<string, unknown>;
    if (typeof p["slug"] !== "string" || p["slug"] === "") continue;
    personas.push(
      Object.freeze({ slug: p["slug"], lens: str(p, "lens"), prompt: str(p, "prompt") }),
    );
  }
  return Object.freeze(personas);
}

function parseErrors(raw: unknown): ReadonlyArray<WriteSessionError> {
  if (!Array.isArray(raw)) return Object.freeze([]);
  const errors: WriteSessionError[] = [];
  for (const item of raw) {
    if (typeof item !== "object" || item === null) continue;
    const e = item as Record<string, unknown>;
    if (typeof e["code"] !== "string") continue;
    errors.push(
      Object.freeze({ code: e["code"], path: str(e, "path"), message: str(e, "message") }),
    );
  }
  return Object.freeze(errors);
}

function parseResponses(raw: unknown): Readonly<Record<string, string>> {
  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return Object.freeze({});
  const out: Record<string, string> = {};
  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
    if (typeof value === "string") out[key] = value;
  }
  return Object.freeze(out);
}

function isIsoDateString(value: unknown): value is string {
  return typeof value === "string" && !Number.isNaN(Date.parse(value));
}

function isCounter(value: unknown): value is number {
  return typeof value === "number" && Number.isInteger(value) && value >= 0;
}

/**
 * Fail-closed: a valid-JSON record missing required structure reads as
 * malformed (error probe), never as a live session with defaulted
 * fields - a corrupted store entry must not become writable state.
 */
function parseRecord(raw: unknown): WriteSessionRecord | null {
  if (typeof raw !== "object" || raw === null) return null;
  const rec = raw as Record<string, unknown>;
  if (!isWriteSessionId(rec["id"])) return null;
  if (!KIND_SET.has(String(rec["kind"]))) return null;
  if (!STATUS_SET.has(String(rec["status"]))) return null;
  if (typeof rec["step"] !== "string" || rec["step"] === "") return null;
  if (typeof rec["agent"] !== "string" || rec["agent"] === "") return null;
  if (!isIsoDateString(rec["created_at"])) return null;
  if (!isIsoDateString(rec["updated_at"])) return null;
  if (!isIsoDateString(rec["expires_at"])) return null;
  if (typeof rec["target_path"] !== "string" || rec["target_path"] === "") return null;
  if (!isCounter(rec["attempts"])) return null;
  if (!isCounter(rec["retry_cap"])) return null;
  const intent = INTENT_SET.has(String(rec["intent"]))
    ? (rec["intent"] as WriteSessionIntent)
    : "create";
  return Object.freeze({
    id: rec["id"] as string,
    kind: rec["kind"] as WriteSessionKind,
    status: rec["status"] as WriteSessionStatus,
    step: str(rec, "step"),
    agent: str(rec, "agent"),
    createdAt: str(rec, "created_at"),
    updatedAt: str(rec, "updated_at"),
    expiresAt: str(rec, "expires_at"),
    attempts: typeof rec["attempts"] === "number" ? rec["attempts"] : 0,
    retryCap: typeof rec["retry_cap"] === "number" ? rec["retry_cap"] : 0,
    targetPath: str(rec, "target_path"),
    intent,
    requireReview: rec["require_review"] === true,
    prompt: str(rec, "prompt"),
    schemaType: typeof rec["schema_type"] === "string" ? rec["schema_type"] : null,
    topic: typeof rec["topic"] === "string" ? rec["topic"] : null,
    personas: parsePersonas(rec["personas"]),
    responses: parseResponses(rec["responses"]),
    pendingArtifact: typeof rec["pending_artifact"] === "string" ? rec["pending_artifact"] : null,
    lastErrors: parseErrors(rec["last_errors"]),
    failReason: typeof rec["fail_reason"] === "string" ? rec["fail_reason"] : null,
  });
}

/**
 * Lazy-TTL view: a non-terminal session whose `expiresAt` is in the
 * past reads as terminal `failed`/`expired`. The transform is pure -
 * the file is not rewritten on read; `sweepWriteSessions` owns cleanup.
 */
function applyTtl(record: WriteSessionRecord, nowIso: string): WriteSessionRecord {
  if (isTerminalWriteSessionStatus(record.status)) return record;
  const expires = Date.parse(record.expiresAt);
  const now = Date.parse(nowIso);
  if (Number.isNaN(expires) || Number.isNaN(now) || now < expires) return record;
  return Object.freeze({ ...record, status: "failed" as const, failReason: "expired" });
}

/** Persist a session record atomically (updates an EXISTING session). */
export function saveWriteSession(vault: string, record: WriteSessionRecord): void {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertLaneWrite(vault);
  writeLaneText(vault, writeSessionPath(vault, record.id), serializeRecord(record));
}

/**
 * Allocate an id and persist a NEW session in one step. The first save
 * goes through an exclusive create (hardlink-based, fails on EEXIST),
 * so two concurrent openers in the same second can never claim the
 * same id - the loser simply retries with the next suffix. This closes
 * the check-then-use window a bare `allocate + save` pair would have.
 */
export function createWriteSession(
  vault: string,
  nowIso: string,
  build: (id: string) => WriteSessionRecord,
): WriteSessionRecord {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertLaneWrite(vault);
  for (let attempt = 0; attempt < 10_000; attempt++) {
    const id = allocateWriteSessionId(vault, nowIso);
    const record = build(id);
    try {
      writeLaneText(vault, writeSessionPath(vault, id), serializeRecord(record), {
        exclusive: true,
      });
      return record;
    } catch (exc) {
      if ((exc as NodeJS.ErrnoException).code === "EEXIST") continue;
      throw exc;
    }
  }
  throw new Error("could not create a write-session: id space exhausted for this second");
}

/**
 * Read one session. Missing file: `{session: null, error: null}`.
 * Malformed JSON or an invalid record: `{session: null, error}` so the
 * engine can report the corruption instead of crashing.
 */
export function readWriteSession(vault: string, id: string, nowIso: string): WriteSessionProbe {
  if (!isWriteSessionId(id)) {
    return Object.freeze({
      session: null,
      error: `invalid write-session id: ${id}`,
      expiredOnRead: false,
    });
  }
  const path = writeSessionPath(vault, id);
  // Read once: a session removed meanwhile (a sweep, a delete) is missing,
  // never a corrupt one.
  const text = readLaneText(vault, path);
  if (text === null) {
    return Object.freeze({ session: null, error: null, expiredOnRead: false });
  }
  let raw: unknown;
  try {
    raw = JSON.parse(text);
  } catch (exc) {
    return Object.freeze({
      session: null,
      error: `write-session file is not valid JSON: ${(exc as Error).message}`,
      expiredOnRead: false,
    });
  }
  const record = parseRecord(raw);
  if (record === null) {
    return Object.freeze({
      session: null,
      error: `write-session record is malformed (${id})`,
      expiredOnRead: false,
    });
  }
  const view = applyTtl(record, nowIso);
  return Object.freeze({ session: view, error: null, expiredOnRead: view !== record });
}

/** All readable sessions, sorted by created_at then id. Corrupt files are skipped. */
export function listWriteSessions(
  vault: string,
  nowIso: string,
): ReadonlyArray<WriteSessionRecord> {
  // `listLaneFiles` answers [] for a missing folder in both modes.
  const dir = writeSessionDir(vault);
  const sessions: WriteSessionRecord[] = [];
  for (const name of listLaneFiles(vault, dir, "")) {
    if (!name.endsWith(".json")) continue;
    const probe = readWriteSession(vault, name.slice(0, -".json".length), nowIso);
    if (probe.session !== null) sessions.push(probe.session);
  }
  sessions.sort((a, b) =>
    a.createdAt === b.createdAt ? a.id.localeCompare(b.id) : a.createdAt.localeCompare(b.createdAt),
  );
  return Object.freeze(sessions);
}

/** Remove one session file (idempotent). */
export function deleteWriteSession(vault: string, id: string): void {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertLaneWrite(vault);
  removeLanePage(vault, writeSessionPath(vault, id));
}

export interface SweepWriteSessionsResult {
  readonly removed: number;
  readonly kept: number;
}

/**
 * Delete terminal (done/failed) and expired session files. Corrupt
 * files are also removed - they can never transition anywhere.
 */
export function sweepWriteSessions(vault: string, nowIso: string): SweepWriteSessionsResult {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertLaneWrite(vault);
  const dir = writeSessionDir(vault);
  let removed = 0;
  let kept = 0;
  for (const name of listLaneFiles(vault, dir, "")) {
    if (!name.endsWith(".json")) continue;
    const id = name.slice(0, -".json".length);
    if (!isWriteSessionId(id)) {
      // A *.json name outside the id grammar can never become a live
      // session - it is corrupt by definition; sweep owns its removal.
      removeLanePage(vault, join(dir, name));
      removed += 1;
      continue;
    }
    const probe = readWriteSession(vault, id, nowIso);
    if (probe.session === null || isTerminalWriteSessionStatus(probe.session.status)) {
      removeLanePage(vault, join(dir, name));
      removed += 1;
    } else {
      kept += 1;
    }
  }
  return Object.freeze({ removed, kept });
}