Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

11.6 KB
Raw Blame
// Host-owned runtime data is not a build asset; tracing exclusions preserve runtime guards.
import { createHash, randomUUID } from "node:crypto";
import { constants as fsConstants, promises as fs } from "node:fs";
import os from "node:os";
import path from "node:path";
import { withSecurityStoreLock } from "@/lib/security-store-lock";
import { archiveMemoryRecords, readMemoryArchive } from "./memory-archive";
import { ledgerFile, materializeDocuments, MAX_MEMORY_LEDGER_BYTES, readMemoryLedger, seedLedger, writeMemoryLedger } from "./memory-ledger";
import { queryMemoryLedger } from "./memory-query";
import { planMemoryRetention } from "./memory-retention";
import { recordCanBeEffectiveAtOrAfter, recordEffectiveAt, resolveMemoryKey } from "./memory-resolution";
import { collectMemoryTelemetry, type AgentMemoryTelemetry } from "./memory-telemetry";
import type { AgentMemoryDocument, AgentMemoryLedger, AgentMemoryQuery, AgentMemoryRecord, AgentMemoryWriteOptions } from "./memory-types";

export type { AgentMemoryDocument, AgentMemoryKind, AgentMemoryQuery, AgentMemoryRecord, AgentMemorySensitivity, AgentMemoryWriteOptions } from "./memory-types";
export type { AgentMemoryTelemetry } from "./memory-telemetry";
export interface AgentMemorySnapshot { capturedAt: string; user: string; memory: string; schemaVersion?: 1; recordCount?: number; }

const ROOT = path.resolve(/* turbopackIgnore: true */ process.env.OS_AGENT_MEMORY_DIR || path.join(os.homedir(), ".mso", "agent-memory"));
const MAX_LEGACY_DOC_BYTES = 64 * 1024;
const MAX_PROJECTION_BYTES = MAX_MEMORY_LEDGER_BYTES;
const KEY_RE = /^[^\r\n]{1,80}$/;

function principalKey(principal: string): string {
  if (!principal || principal.length > 512) throw new Error("invalid agent memory principal");
  return createHash("sha256").update(principal).digest("hex").slice(0, 32);
}
function dirFor(principal: string): string { return path.join(ROOT, principalKey(principal)); }
function fileFor(principal: string, document: AgentMemoryDocument): string { return path.join(dirFor(principal), document); }

async function readDocument(principal: string, document: AgentMemoryDocument): Promise<string> {
  let handle: Awaited<ReturnType<typeof fs.open>> | null = null;
  try {
    handle = await fs.open(/* turbopackIgnore: true */ fileFor(principal, document), fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
    const stat = await handle.stat();
    if (!stat.isFile() || stat.size > MAX_LEGACY_DOC_BYTES) throw new Error("agent memory document has an invalid file shape");
    if ((stat.mode & 0o077) !== 0) throw new Error("agent memory permissions are too broad; expected 0600");
    if (typeof process.getuid === "function" && stat.uid !== process.getuid()) throw new Error("agent memory is not owned by the MSO user");
    return await handle.readFile("utf8");
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return "";
    throw error;
  } finally { await handle?.close().catch(() => undefined); }
}

async function writeDocument(principal: string, document: AgentMemoryDocument, content: string): Promise<void> {
  if (Buffer.byteLength(content, "utf8") > MAX_PROJECTION_BYTES) throw new Error("agent memory projection exceeds 2 MiB");
  const file = fileFor(principal, document), dir = path.dirname(file), tmp = `${file}.${randomUUID()}.tmp`;
  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
  await fs.chmod(ROOT, 0o700).catch(() => undefined); await fs.chmod(dir, 0o700).catch(() => undefined);
  await fs.writeFile(tmp, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
  await fs.chmod(tmp, 0o600); await fs.rename(tmp, file); await fs.chmod(file, 0o600);
}

function cleanKey(key: string): string {
  const value = key.trim();
  if (!KEY_RE.test(value) || value.startsWith("#")) throw new Error("memory key must be one line, 1-80 characters");
  return value;
}
function cleanValue(value: string): string {
  const clean = value.trim();
  if (!clean || Buffer.byteLength(clean, "utf8") > 8 * 1024) throw new Error("memory value must be 1-8192 bytes");
  return clean;
}
function iso(value: string | undefined, fallback: string, field: string): string {
  if (!value) return fallback;
  const parsed = Date.parse(value);
  if (!Number.isFinite(parsed)) throw new Error(`${field} must be ISO-8601`);
  return new Date(parsed).toISOString();
}
function confidence(value: number | undefined): number {
  const n = value ?? 1;
  if (!Number.isFinite(n) || n < 0 || n > 1) throw new Error("memory confidence must be between 0 and 1");
  return Math.round(n * 1000) / 1000;
}
function dedupeRecords(archived: AgentMemoryRecord[], live: AgentMemoryRecord[]): AgentMemoryRecord[] {
  const byId = new Map<string, AgentMemoryRecord>();
  for (const record of archived) byId.set(record.id, record);
  for (const record of live) byId.set(record.id, record); // live ledger wins after an interrupted archive-before-ledger commit.
  return [...byId.values()];
}

async function legacyDocs(principal: string) { const [user, memory] = await Promise.all([readDocument(principal, "USER.md"), readDocument(principal, "MEMORY.md")]); return { user, memory }; }
async function ledgerForRead(principal: string): Promise<AgentMemoryLedger> {
  const ledger = await readMemoryLedger(dirFor(principal));
  if (ledger) return ledger;
  const docs = await legacyDocs(principal); return seedLedger(docs.user, docs.memory);
}
async function ledgerForQuery(principal: string, query: AgentMemoryQuery): Promise<AgentMemoryLedger> {
  const live = await ledgerForRead(principal);
  if (!query.includeHistory && !query.at) return live;
  const archived = await readMemoryArchive(dirFor(principal));
  if (!archived.records.length) return live;
  return { ...live, records: dedupeRecords(archived.records, live.records) };
}
function snapshotFromLedger(ledger: AgentMemoryLedger, capturedAt = new Date().toISOString()): AgentMemorySnapshot {
  const docs = materializeDocuments(ledger, capturedAt);
  return { capturedAt, user: docs["USER.md"], memory: docs["MEMORY.md"], schemaVersion: 1, recordCount: ledger.records.length };
}
async function persistProjection(principal: string, ledger: AgentMemoryLedger, at: string): Promise<void> {
  const docs = materializeDocuments(ledger, at);
  await writeDocument(principal, "USER.md", docs["USER.md"]); await writeDocument(principal, "MEMORY.md", docs["MEMORY.md"]);
}
async function persistLedgerMutation(principal: string, ledger: AgentMemoryLedger, at: string): Promise<AgentMemoryLedger> {
  const retention = planMemoryRetention(ledger, at);
  if (retention.archiveRecords.length) await archiveMemoryRecords(dirFor(principal), retention.archiveRecords);
  await writeMemoryLedger(dirFor(principal), retention.ledger);
  await persistProjection(principal, retention.ledger, at);
  return retention.ledger;
}

export async function snapshotAgentMemory(principal: string): Promise<AgentMemorySnapshot> {
  const stored = await readMemoryLedger(dirFor(principal));
  if (stored) return snapshotFromLedger(stored);
  const docs = await legacyDocs(principal); return { capturedAt: new Date().toISOString(), ...docs };
}
export const readAgentMemory = snapshotAgentMemory;

export async function rememberAgentMemory(principal: string, document: AgentMemoryDocument, key: string, value: string, options: AgentMemoryWriteOptions = {}): Promise<AgentMemorySnapshot> {
  const safeKey = cleanKey(key), safeValue = cleanValue(value), now = new Date().toISOString();
  const validFrom = iso(options.validFrom, now, "valid_from"), validUntil = options.validUntil ? iso(options.validUntil, now, "valid_until") : undefined;
  if (validUntil && Date.parse(validUntil) <= Date.parse(validFrom)) throw new Error("valid_until must be after valid_from");
  const record: AgentMemoryRecord = {
    id: `mem_${randomUUID()}`, document, key: safeKey, value: safeValue, kind: options.kind ?? "semantic",
    confidence: confidence(options.confidence), sensitivity: options.sensitivity ?? "normal", validFrom,
    ...(validUntil ? { validUntil } : {}), createdAt: now,
    provenance: { authority: options.provenance?.authority ?? "explicit", channel: options.provenance?.channel ?? "system", observedAt: iso(options.provenance?.observedAt, now, "observed_at"), ...(options.provenance?.sessionHash ? { sessionHash: options.provenance.sessionHash } : {}) },
  };
  let result!: AgentMemoryLedger;
  await withSecurityStoreLock(ledgerFile(dirFor(principal)), async () => {
    const stored = await readMemoryLedger(dirFor(principal));
    const current = stored ?? await (async () => { const docs = await legacyDocs(principal); return seedLedger(docs.user, docs.memory, now); })();
    const mode = options.mode ?? "replace";
    // Conservative NOOP: dedupe only an ordinary "replace current value" write.
    // Explicit temporal/provenance timestamps and claims remain append-only evidence.
    if (stored && mode === "replace" && !options.validFrom && !options.validUntil && !options.provenance?.observedAt) {
      const resolved = resolveMemoryKey(current, document, safeKey, now)?.record;
      const same = resolved
        && resolved.value === safeValue
        && resolved.kind === record.kind
        && resolved.confidence === record.confidence
        && resolved.sensitivity === record.sensitivity
        && resolved.provenance.authority === record.provenance.authority
        && resolved.provenance.channel === record.provenance.channel
        && (resolved.provenance.sessionHash ?? "") === (record.provenance.sessionHash ?? "");
      if (same) {
        result = current;
        return;
      }
    }
    if (mode === "replace") {
      let searchable = current.records;
      if (Date.parse(validFrom) < Date.parse(now)) {
        const archived = await readMemoryArchive(dirFor(principal));
        searchable = dedupeRecords(archived.records, current.records);
      }
      const superseded = searchable.filter((row) => row.document === document && row.key === safeKey && recordEffectiveAt(row, validFrom));
      if (superseded.length) record.supersedes = superseded.map((row) => row.id);
      const supersededIds = new Set(superseded.map((row) => row.id));
      for (const row of current.records) {
        if (supersededIds.has(row.id)) { row.supersededAt = validFrom; row.supersededBy = record.id; }
      }
    }
    current.records.push(record); current.updatedAt = now; result = await persistLedgerMutation(principal, current, now);
  });
  return snapshotFromLedger(result, now);
}

export async function forgetAgentMemory(principal: string, document: AgentMemoryDocument, key: string): Promise<AgentMemorySnapshot> {
  const safeKey = cleanKey(key), now = new Date().toISOString(); let result!: AgentMemoryLedger;
  await withSecurityStoreLock(ledgerFile(dirFor(principal)), async () => {
    const current = await readMemoryLedger(dirFor(principal)) ?? await (async () => { const docs = await legacyDocs(principal); return seedLedger(docs.user, docs.memory, now); })();
    for (const row of current.records) {
      if (row.document === document && row.key === safeKey && recordCanBeEffectiveAtOrAfter(row, now)) row.retractedAt = now;
    }
    current.updatedAt = now; result = await persistLedgerMutation(principal, current, now);
  });
  return snapshotFromLedger(result, now);
}

export async function queryAgentMemory(principal: string, query: AgentMemoryQuery = {}) {
  return queryMemoryLedger(await ledgerForQuery(principal, query), query);
}

export async function agentMemoryTelemetry(principal: string): Promise<AgentMemoryTelemetry> {
  const live = await ledgerForRead(principal);
  const archived = await readMemoryArchive(dirFor(principal));
  return collectMemoryTelemetry(live, archived.records, { segmentCount: archived.segmentCount, bytes: archived.bytes });
}