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
18.0 KB
Raw Blame
/**
 * Write-session engine (Agent Write Contract Suite, t_bc36a8a2).
 *
 * The lifecycle the calling agent drives:
 *
 *   open  -> `needs-llm-step` envelope (prompt + schema hints +
 *            collision metadata when the target is occupied)
 *   submit-> `done` (validated, committed atomically)
 *          | `needs-correction` (machine-readable errors + compact
 *            correction prompt; session state preserved)
 *          | `needs-review` (validated, parked for operator approve)
 *          | `failed` (retry cap exhausted - terminal)
 *   approve / abandon -> operator-side terminal transitions.
 *
 * Hard rules, enforced here and only here:
 *   - OSB never generates content; every artifact byte comes from the
 *     caller. Fail-closed: nothing lands unless validation is clean.
 *   - `create` intent NEVER overwrites; `overwrite` replaces;
 *     `merge` appends a session-stamped delimited section - existing
 *     bytes are preserved verbatim in both non-destructive modes.
 *   - Every terminal transition appends exactly one `write-session`
 *     audit event through the existing log chokepoint.
 */

import { existsSync, mkdirSync, readFileSync } from "node:fs";
import { dirname, join } from "node:path";

import { atomicWriteFileSync } from "../../fs-atomic.ts";
import { ensureInsideVault, realVaultRelative } from "../../path-safety.ts";
import { checkWriteBinding } from "../../write-binding/index.ts";
import { assertStandingRulesNotTargeted } from "../standing-rules.ts";
import { appendLogEvent } from "../log.ts";
import { loadSchemaPack } from "../schema-pack.ts";
import { BRAIN_LOG_EVENT_KIND } from "../types.ts";
import { createWriteSession, readWriteSession, saveWriteSession } from "./store.ts";
import {
  buildCorrectionPrompt,
  inspectExistingTarget,
  validateArtifact,
  validateTargetPath,
  writeSessionLaneRefusal,
} from "./validate.ts";
import {
  isTerminalWriteSessionStatus,
  type ExistingTargetInfo,
  type WriteSessionEnvelope,
  type WriteSessionError,
  type WriteSessionIntent,
  type WriteSessionRecord,
} from "./types.ts";
import { assertVaultIdentityForWrite } from "../vault-identity.ts";

export const DEFAULT_RETRY_CAP = 3;
export const DEFAULT_TTL_MS = 24 * 3600 * 1000;

/**
 * Why a request named a session that cannot take it, for the two refusals
 * a caller can act on without reading prose: the id names no session, or
 * the session already ended. Every other request failure carries none.
 */
export type WriteSessionRequestReason = "unknown-session" | "terminal-session";

export interface WriteSessionRequestErrorOptions {
  readonly reason?: WriteSessionRequestReason;
}

/** Structured request failure - carries the machine-readable errors. */
export class WriteSessionRequestError extends Error {
  readonly errors: ReadonlyArray<WriteSessionError>;
  readonly reason?: WriteSessionRequestReason;

  constructor(
    message: string,
    errors: ReadonlyArray<WriteSessionError> = [],
    options: WriteSessionRequestErrorOptions = {},
  ) {
    super(message);
    this.name = "WriteSessionRequestError";
    this.errors = errors;
    if (options.reason !== undefined) this.reason = options.reason;
  }
}

export interface OpenArtifactSessionInput {
  readonly agent: string;
  readonly targetPath: string;
  /** Operator/agent-supplied generation instruction; a default is built. */
  readonly prompt?: string;
  readonly schemaType?: string | null;
  readonly intent?: WriteSessionIntent;
  readonly requireReview?: boolean;
  readonly retryCap?: number;
  readonly ttlMs?: number;
  /** ISO timestamp; fixtures pass a constant for determinism. */
  readonly now?: string;
}

/** Open an artifact session; throws {@link WriteSessionRequestError} on a bad target. */
export function openArtifactSession(
  vault: string,
  input: OpenArtifactSessionInput,
): WriteSessionEnvelope {
  const targetErrors = validateTargetPath(input.targetPath);
  if (targetErrors.length > 0) {
    throw new WriteSessionRequestError(
      `target rejected: ${targetErrors[0]!.message}`,
      targetErrors,
    );
  }
  const now = resolveNow(input.now);
  const schemaType = input.schemaType?.trim() || null;
  const expiresAt = new Date(Date.parse(now) + normalizeTtlMs(input.ttlMs)).toISOString();
  const retryCap = normalizeRetryCap(input.retryCap);
  const record = createWriteSession(vault, now, (id) =>
    Object.freeze({
      id,
      kind: "artifact" as const,
      status: "needs-llm-step" as const,
      step: "artifact",
      agent: input.agent.trim() || "unknown",
      createdAt: now,
      updatedAt: now,
      expiresAt,
      attempts: 0,
      retryCap,
      targetPath: input.targetPath,
      intent: input.intent ?? ("create" as const),
      requireReview: input.requireReview === true,
      prompt: input.prompt?.trim() || buildArtifactPrompt(input.targetPath, schemaType),
      schemaType,
      topic: null,
      personas: [],
      responses: {},
      pendingArtifact: null,
      lastErrors: [],
      failReason: null,
    }),
  );
  return sessionEnvelope(record, inspectExistingTarget(vault, record.targetPath));
}

export interface SubmitToSessionInput {
  readonly sessionId: string;
  readonly artifact: string;
  readonly now?: string;
}

/**
 * Submit the current step's text. Artifact sessions validate + commit;
 * panel sessions are routed by the caller through the panel module
 * (which reuses {@link acceptArtifactSubmission} semantics per step).
 */
export function submitToSession(vault: string, input: SubmitToSessionInput): WriteSessionEnvelope {
  const now = resolveNow(input.now);
  const session = loadLiveSession(vault, input.sessionId, now);
  if (session.kind !== "artifact") {
    throw new WriteSessionRequestError(
      `session ${session.id} is a '${session.kind}' session - submit through its kind-specific surface`,
    );
  }

  // Collision guard runs at COMMIT time, not just open time: the target
  // may have appeared between open and submit (another device, another
  // agent). `create` intent treats an occupied target as an error.
  const errors: WriteSessionError[] = [
    ...validateArtifactForSession(vault, session, input.artifact),
  ];
  if (session.intent === "create" && inspectExistingTarget(vault, session.targetPath) !== null) {
    errors.push(
      Object.freeze({
        code: "target-exists",
        path: "target",
        message:
          `${session.targetPath} already exists; reopen the session with overwrite or merge intent ` +
          "(or abandon)",
      }),
    );
  }

  if (errors.length > 0) {
    return recordFailedAttempt(vault, session, errors, now);
  }
  if (session.requireReview) {
    const parked: WriteSessionRecord = Object.freeze({
      ...session,
      status: "needs-review" as const,
      updatedAt: now,
      pendingArtifact: input.artifact,
      lastErrors: [],
      prompt: "Awaiting operator review - no further generation needed.",
    });
    saveWriteSession(vault, parked);
    return sessionEnvelope(parked);
  }
  return commitArtifact(vault, session, input.artifact, now);
}

export interface SessionOpInput {
  readonly sessionId: string;
  readonly now?: string;
}

/** Operator-side approval of a `needs-review` session. */
export function approveSession(vault: string, input: SessionOpInput): WriteSessionEnvelope {
  const now = resolveNow(input.now);
  const session = loadLiveSession(vault, input.sessionId, now);
  if (session.status !== "needs-review" || session.pendingArtifact === null) {
    throw new WriteSessionRequestError(
      `session ${session.id} is not awaiting review (status: ${session.status})`,
    );
  }
  return commitArtifact(vault, session, session.pendingArtifact, now);
}

/** Terminal abandon; safe on any non-terminal session. */
export function abandonSession(vault: string, input: SessionOpInput): WriteSessionEnvelope {
  const now = resolveNow(input.now);
  const session = loadLiveSession(vault, input.sessionId, now);
  const abandoned: WriteSessionRecord = Object.freeze({
    ...session,
    status: "failed" as const,
    updatedAt: now,
    failReason: "abandoned",
    pendingArtifact: null,
  });
  saveWriteSession(vault, abandoned);
  auditTerminal(vault, abandoned, now);
  return sessionEnvelope(abandoned);
}

/** Envelope view of a session record (status/list surfaces). */
export function sessionEnvelope(
  session: WriteSessionRecord,
  existing: ExistingTargetInfo | null = null,
): WriteSessionEnvelope {
  return Object.freeze({
    status: session.status,
    session_id: session.id,
    kind: session.kind,
    step: session.step,
    prompt: session.prompt,
    schema_hints: buildSchemaHints(session),
    errors: session.lastErrors,
    attempts_left: Math.max(0, session.retryCap - session.attempts),
    expires_at: session.expiresAt,
    target_path: session.targetPath,
    existing,
  });
}

// ----- Shared internals (panel module reuses these) -------------------------

export function resolveNow(now: string | undefined): string {
  if (now === undefined) return new Date().toISOString();
  const ts = Date.parse(now);
  if (Number.isNaN(ts)) {
    throw new WriteSessionRequestError(`invalid 'now' timestamp: ${now}`);
  }
  return new Date(ts).toISOString();
}

/** TTL must be a positive integer; reject before any date arithmetic. */
function normalizeTtlMs(ttlMs: number | undefined): number {
  if (ttlMs === undefined) return DEFAULT_TTL_MS;
  if (!Number.isFinite(ttlMs) || !Number.isInteger(ttlMs) || ttlMs < 1) {
    throw new WriteSessionRequestError(`ttlMs must be a positive integer, got: ${ttlMs}`);
  }
  return ttlMs;
}

function normalizeRetryCap(cap: number | undefined): number {
  if (cap === undefined) return DEFAULT_RETRY_CAP;
  if (!Number.isInteger(cap) || cap < 1 || cap > 20) {
    throw new WriteSessionRequestError(`retry cap must be an integer in [1, 20], got: ${cap}`);
  }
  return cap;
}

/**
 * Load a session that can still accept operations. An expired-on-read
 * session is persisted as failed (the lazy-TTL transform becomes
 * durable the moment anyone touches the session) and then refused.
 */
export function loadLiveSession(vault: string, id: string, now: string): WriteSessionRecord {
  const probe = readWriteSession(vault, id, now);
  if (probe.error !== null) {
    throw new WriteSessionRequestError(probe.error);
  }
  if (probe.session === null) {
    throw new WriteSessionRequestError(`unknown write-session: ${id}`, [], {
      reason: "unknown-session",
    });
  }
  const session = probe.session;
  if (isTerminalWriteSessionStatus(session.status)) {
    if (probe.expiredOnRead) {
      // The TTL transform fired on THIS read (disk record was still
      // non-terminal): make the expiry durable + audited exactly once.
      // A record already terminal on disk skips both.
      saveWriteSession(vault, session);
      auditTerminal(vault, session, now);
    }
    throw new WriteSessionRequestError(
      `write-session ${id} is terminal (${session.status}${
        session.failReason ? `/${session.failReason}` : ""
      })`,
      [],
      { reason: "terminal-session" },
    );
  }
  return session;
}

export function validateArtifactForSession(
  vault: string,
  session: WriteSessionRecord,
  artifact: string,
): ReadonlyArray<WriteSessionError> {
  return validateArtifact(artifact, {
    schemaType: session.schemaType,
    vocabulary: loadSchemaPack(vault).vocabulary,
  });
}

/** Failed attempt bookkeeping shared by artifact and panel steps. */
export function recordFailedAttempt(
  vault: string,
  session: WriteSessionRecord,
  errors: ReadonlyArray<WriteSessionError>,
  now: string,
): WriteSessionEnvelope {
  const attempts = session.attempts + 1;
  if (attempts >= session.retryCap) {
    const failed: WriteSessionRecord = Object.freeze({
      ...session,
      status: "failed" as const,
      attempts,
      updatedAt: now,
      lastErrors: errors,
      failReason: "retry-cap",
      pendingArtifact: null,
    });
    saveWriteSession(vault, failed);
    auditTerminal(vault, failed, now);
    return sessionEnvelope(failed);
  }
  const corrected: WriteSessionRecord = Object.freeze({
    ...session,
    status: "needs-correction" as const,
    attempts,
    updatedAt: now,
    lastErrors: errors,
    prompt: buildCorrectionPrompt(errors),
  });
  saveWriteSession(vault, corrected);
  return sessionEnvelope(corrected);
}

/** Validated commit + terminal bookkeeping (artifact and panel share it). */
export function commitArtifact(
  vault: string,
  session: WriteSessionRecord,
  artifact: string,
  now: string,
): WriteSessionEnvelope {
  // Vault-identity write guard (context-integrity-gates, Unit J).
  assertVaultIdentityForWrite(vault);

  // Last-line-of-defense containment: `validateTargetPath` runs at open
  // time and is purely lexical (it rejects `..`/backslashes/NUL but is
  // blind to symlinked ancestors), and the persisted session record is
  // decoupled from that check. Re-resolve at the write chokepoint so a
  // target that lands outside the vault - e.g. `Brain/<symlink>/x.md`
  // whose ancestor links out - is rejected before any mkdir/read/write.
  const absolute = ensureInsideVault(join(vault, session.targetPath), vault);
  assertCommitTargetGoverned(vault, session.targetPath);
  // Last-line-of-defense collision guard: submit-time checks cannot
  // cover the window between a needs-review park and the operator's
  // approve - if the target appeared meanwhile, `create` must still
  // refuse to overwrite at the write chokepoint itself.
  if (session.intent === "create" && existsSync(absolute)) {
    return recordFailedAttempt(
      vault,
      session,
      [
        Object.freeze({
          code: "target-exists",
          path: "target",
          message:
            `${session.targetPath} already exists; reopen the session with overwrite or merge intent ` +
            "(or abandon)",
        }),
      ],
      now,
    );
  }
  const body = artifact.endsWith("\n") ? artifact : `${artifact}\n`;
  mkdirSync(dirname(absolute), { recursive: true });
  if (session.intent === "merge" && existsSync(absolute)) {
    const existing = readFileSync(absolute, "utf8").replace(/\s+$/u, "");
    const merged = `${existing}\n\n<!-- o2b:ws-merge ${session.id} -->\n\n${body}`;
    atomicWriteFileSync(absolute, merged);
  } else {
    atomicWriteFileSync(absolute, body);
  }
  const done: WriteSessionRecord = Object.freeze({
    ...session,
    status: "done" as const,
    updatedAt: now,
    pendingArtifact: null,
    lastErrors: [],
    prompt: "Committed - no further generation needed.",
  });
  saveWriteSession(vault, done);
  auditTerminal(vault, done, now);
  return sessionEnvelope(done);
}

/**
 * The governance walls a commit re-runs at the write chokepoint, on top of
 * containment. The open-time lane check reads the path as spelled; a
 * symlinked folder can still carry the bytes somewhere else under
 * `Brain/`, and the session record outlives the check. So: the standing
 * rules file is refused by identity (a symlink to it is the same file),
 * the real landing path must sit in a write-session lane too, and the
 * operator's write binding must admit it. A landing path that cannot be
 * resolved (a file used as a folder, a symlink loop, an unreadable
 * folder) is refused rather than guessed at.
 */
function assertCommitTargetGoverned(vault: string, targetPath: string): void {
  assertStandingRulesNotTargeted(vault, targetPath, "brain_write_session");
  let landsAt: string | null;
  try {
    landsAt = realVaultRelative(vault, targetPath);
  } catch (exc) {
    const code = (exc as NodeJS.ErrnoException)?.code ?? "unknown";
    const error = Object.freeze({
      code: "target-unresolvable",
      path: "target",
      message: `${targetPath} cannot be resolved on disk (${code}); nothing was written`,
    });
    throw new WriteSessionRequestError(error.message, [error]);
  }
  if (landsAt === null) {
    const error = Object.freeze({
      code: "target-outside-brain",
      path: "target",
      message: `${targetPath} resolves outside the vault; nothing was written`,
    });
    throw new WriteSessionRequestError(error.message, [error]);
  }
  const landedRefusal = writeSessionLaneRefusal(landsAt);
  if (landedRefusal !== null) {
    const error = Object.freeze({
      ...landedRefusal,
      message:
        landsAt === targetPath
          ? landedRefusal.message
          : `${targetPath} resolves to ${landsAt}: ${landedRefusal.message}`,
    });
    throw new WriteSessionRequestError(error.message, [error]);
  }
  const bindingRefusal = checkWriteBinding(vault, targetPath);
  if (bindingRefusal !== null) {
    const error = Object.freeze({
      code: bindingRefusal.code,
      path: "target",
      message: bindingRefusal.message,
    });
    throw new WriteSessionRequestError(error.message, [error]);
  }
}

function buildArtifactPrompt(targetPath: string, schemaType: string | null): string {
  const schemaLine = schemaType ? ` The frontmatter must declare \`type: ${schemaType}\`.` : "";
  return (
    `Produce the complete markdown artifact for ${targetPath}. ` +
    "Start with a YAML frontmatter block (at minimum a `kind` key), follow with a heading and the body." +
    schemaLine +
    " Submit the full file content - it is validated before anything is written."
  );
}

function buildSchemaHints(session: WriteSessionRecord): ReadonlyArray<string> {
  const hints = [
    "frontmatter: required YAML block with at least one key",
    "format: UTF-8 markdown, no raw control characters",
  ];
  if (session.schemaType) hints.push(`type: ${session.schemaType} (frontmatter 'type' key)`);
  return Object.freeze(hints);
}

/** One audit row per terminal transition through the log chokepoint. */
export function auditTerminal(vault: string, session: WriteSessionRecord, now: string): void {
  appendLogEvent(vault, {
    timestamp: now.replace(/\.\d{3}Z$/u, "Z"),
    eventType: BRAIN_LOG_EVENT_KIND.writeSession,
    agent: session.agent,
    body: {
      session_id: session.id,
      kind: session.kind,
      status: session.status,
      target: session.targetPath,
      attempts: String(session.attempts),
      review: session.requireReview ? "required" : "not-required",
      ...(session.failReason ? { reason: session.failReason } : {}),
    },
  });
}