nexus-agents 2.77.13 → 2.79.0

package/dist/chunk-PQHVC4BD.js

@@ -0,0 +1,639 @@
+// ../nexus-memory/dist/index.js
+import Database from "better-sqlite3";
+import Database2 from "better-sqlite3";
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+var KEY_SUMMARY_LIMIT = 120;
+var PAYLOAD_SUMMARY_LIMIT = 240;
+var counters = /* @__PURE__ */ new Map();
+var listeners = /* @__PURE__ */ new Set();
+function isAuditMode() {
+  return process.env["NEXUS_MEMORY_AUDIT_MODE"] === "audit";
+}
+function counterKey(domain, op) {
+  return `${domain}::${op}`;
+}
+function truncate(value, limit) {
+  let s;
+  if (typeof value === "string") {
+    s = value;
+  } else if (value === void 0) {
+    s = "<undefined>";
+  } else if (value === null) {
+    s = "<null>";
+  } else {
+    try {
+      s = JSON.stringify(value);
+    } catch {
+      s = "<unserializable>";
+    }
+  }
+  return s.length > limit ? `${s.slice(0, limit - 1)}\u2026` : s;
+}
+function updateCounter(event) {
+  const ck = counterKey(event.domain, event.op);
+  const existing = counters.get(ck);
+  const hitDelta = event.hit === true ? 1 : 0;
+  counters.set(ck, {
+    domain: event.domain,
+    op: event.op,
+    count: (existing?.count ?? 0) + 1,
+    hitCount: (existing?.hitCount ?? 0) + hitDelta,
+    totalDurationMs: (existing?.totalDurationMs ?? 0) + event.durationMs,
+    maxDurationMs: Math.max(existing?.maxDurationMs ?? 0, event.durationMs)
+  });
+}
+function buildPublicEvent(event, audit) {
+  return {
+    domain: event.domain,
+    op: event.op,
+    durationMs: event.durationMs,
+    ...event.cli !== void 0 && { cli: event.cli },
+    ...event.hit !== void 0 && { hit: event.hit },
+    ...audit && event.key !== void 0 && {
+      keySummary: truncate(event.key, KEY_SUMMARY_LIMIT)
+    },
+    ...audit && event.payload !== void 0 && {
+      payloadSummary: truncate(event.payload, PAYLOAD_SUMMARY_LIMIT)
+    },
+    ...audit && event.result !== void 0 && {
+      resultSummary: truncate(event.result, PAYLOAD_SUMMARY_LIMIT)
+    }
+  };
+}
+function recordMemoryEvent(event) {
+  updateCounter(event);
+  const publicEvent = buildPublicEvent(event, isAuditMode());
+  for (const listener of listeners) {
+    try {
+      listener(publicEvent);
+    } catch {
+    }
+  }
+}
+function getMemoryEventCounters() {
+  return [...counters.values()];
+}
+function subscribeToMemoryEvents(listener) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+function resetMemoryTelemetry() {
+  counters.clear();
+  listeners.clear();
+}
+var MemoryValidationError = class extends Error {
+  constructor(domain, cause) {
+    super(`nexus-memory: write rejected for domain "${domain}": ${String(cause)}`);
+    this.name = "MemoryValidationError";
+  }
+};
+function buildInMemoryRow(value, meta) {
+  return {
+    value,
+    ...meta?.cli !== void 0 && { cli: meta.cli },
+    ...meta?.source !== void 0 && { source: meta.source },
+    timestamp: meta?.timestamp ?? Date.now(),
+    ...meta?.trustTier !== void 0 && { trustTier: meta.trustTier }
+  };
+}
+function applyInMemoryFilter(values, filter) {
+  let out = values;
+  if (filter?.where !== void 0) {
+    const where = filter.where;
+    out = out.filter((v) => {
+      for (const [k, expected] of Object.entries(where)) {
+        if (v[k] !== expected) return false;
+      }
+      return true;
+    });
+  }
+  if (filter?.orderBy !== void 0) {
+    const orderBy = filter.orderBy;
+    const dir = filter.orderDir === "desc" ? -1 : 1;
+    out = [...out].sort((a, b) => {
+      const av = a[orderBy];
+      const bv = b[orderBy];
+      if (av === bv) return 0;
+      if (av === void 0 || av === null) return 1;
+      if (bv === void 0 || bv === null) return -1;
+      return (av < bv ? -1 : 1) * dir;
+    });
+  }
+  if (filter?.limit !== void 0) {
+    out = out.slice(0, filter.limit);
+  }
+  return out;
+}
+var InMemoryBackend = class {
+  domain;
+  rows = /* @__PURE__ */ new Map();
+  schema;
+  closed = false;
+  constructor(options) {
+    this.domain = options.domain;
+    if (options.schema !== void 0) {
+      this.schema = options.schema;
+    }
+  }
+  async read(key) {
+    this.assertOpen();
+    const start = Date.now();
+    const row = this.rows.get(key);
+    recordMemoryEvent({
+      domain: this.domain,
+      op: "read",
+      hit: row !== void 0,
+      durationMs: Date.now() - start,
+      key,
+      result: row?.value
+    });
+    return Promise.resolve(row?.value);
+  }
+  validate(value) {
+    if (this.schema === void 0) return;
+    const result = this.schema.safeParse(value);
+    if (!result.success) {
+      throw new MemoryValidationError(this.domain, result.error);
+    }
+  }
+  async write(key, value, meta) {
+    this.assertOpen();
+    const start = Date.now();
+    this.validate(value);
+    this.rows.set(key, buildInMemoryRow(value, meta));
+    recordMemoryEvent({
+      domain: this.domain,
+      op: "write",
+      ...meta?.cli !== void 0 && { cli: meta.cli },
+      durationMs: Date.now() - start,
+      key,
+      payload: value
+    });
+    return Promise.resolve();
+  }
+  async query(filter) {
+    this.assertOpen();
+    const start = Date.now();
+    let rows = [...this.rows.values()];
+    if (filter?.cli !== void 0) {
+      rows = rows.filter((r) => r.cli === filter.cli);
+    }
+    const values = applyInMemoryFilter(
+      rows.map((r) => r.value),
+      filter
+    );
+    recordMemoryEvent({
+      domain: this.domain,
+      op: "query",
+      hit: values.length > 0,
+      ...filter?.cli !== void 0 && { cli: filter.cli },
+      durationMs: Date.now() - start,
+      key: filter,
+      result: { count: values.length }
+    });
+    return Promise.resolve(values);
+  }
+  async delete(key) {
+    this.assertOpen();
+    const start = Date.now();
+    const removed = this.rows.delete(key);
+    recordMemoryEvent({
+      domain: this.domain,
+      op: "delete",
+      hit: removed,
+      durationMs: Date.now() - start,
+      key
+    });
+    return Promise.resolve(removed);
+  }
+  async stats() {
+    this.assertOpen();
+    const start = Date.now();
+    const timestamps = [...this.rows.values()].map((r) => r.timestamp);
+    const result = {
+      domain: this.domain,
+      count: this.rows.size,
+      oldestTimestamp: timestamps.length > 0 ? Math.min(...timestamps) : null,
+      newestTimestamp: timestamps.length > 0 ? Math.max(...timestamps) : null
+    };
+    recordMemoryEvent({
+      domain: this.domain,
+      op: "stats",
+      durationMs: Date.now() - start,
+      result
+    });
+    return Promise.resolve(result);
+  }
+  async close() {
+    this.closed = true;
+    this.rows.clear();
+    return Promise.resolve();
+  }
+  assertOpen() {
+    if (this.closed) {
+      throw new Error(`nexus-memory: backend "${this.domain}" is closed`);
+    }
+  }
+};
+function buildWriteRow(key, value, meta) {
+  return {
+    key: keyToString(key),
+    value: JSON.stringify(value),
+    cli: meta?.cli ?? null,
+    source: meta?.source ?? null,
+    timestamp: meta?.timestamp ?? Date.now(),
+    trust_tier: meta?.trustTier ?? null
+  };
+}
+function keyToString(key) {
+  if (typeof key === "string") return key;
+  if (typeof key === "number" || typeof key === "boolean") return String(key);
+  return JSON.stringify(key);
+}
+function applyQueryFilter(values, filter) {
+  let out = values;
+  if (filter?.where !== void 0) {
+    const where = filter.where;
+    out = out.filter((v) => {
+      for (const [k, expected] of Object.entries(where)) {
+        if (v[k] !== expected) return false;
+      }
+      return true;
+    });
+  }
+  if (filter?.orderBy !== void 0) {
+    const orderBy = filter.orderBy;
+    const dir = filter.orderDir === "desc" ? -1 : 1;
+    out = [...out].sort((a, b) => {
+      const av = a[orderBy];
+      const bv = b[orderBy];
+      if (av === bv) return 0;
+      if (av === void 0 || av === null) return 1;
+      if (bv === void 0 || bv === null) return -1;
+      return (av < bv ? -1 : 1) * dir;
+    });
+  }
+  if (filter?.limit !== void 0) {
+    out = out.slice(0, filter.limit);
+  }
+  return out;
+}
+var SqliteBackend = class {
+  domain;
+  db;
+  ownsDb;
+  schema;
+  stmts;
+  closed = false;
+  constructor(options) {
+    this.domain = options.domain;
+    if (options.db !== void 0) {
+      this.db = options.db;
+      this.ownsDb = false;
+    } else {
+      const db = new Database(options.dbPath);
+      db.pragma("journal_mode = WAL");
+      this.db = db;
+      this.ownsDb = true;
+    }
+    if (options.schema !== void 0) {
+      this.schema = options.schema;
+    }
+    this.ensureTable();
+    this.stmts = this.prepareStatements();
+  }
+  ensureTable() {
+    if (!/^[a-z][a-z0-9_]{0,63}$/i.test(this.domain)) {
+      throw new Error(
+        `nexus-memory: invalid domain "${this.domain}" \u2014 must match [a-zA-Z][a-zA-Z0-9_]{0,63}`
+      );
+    }
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.domain} (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        cli TEXT,
+        source TEXT,
+        timestamp INTEGER NOT NULL,
+        trust_tier INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS ${this.domain}_cli ON ${this.domain}(cli);
+      CREATE INDEX IF NOT EXISTS ${this.domain}_timestamp ON ${this.domain}(timestamp);
+    `);
+  }
+  prepareStatements() {
+    return {
+      read: this.db.prepare(
+        `SELECT key, value, cli, source, timestamp, trust_tier FROM ${this.domain} WHERE key = ?`
+      ),
+      write: this.db.prepare(
+        `INSERT INTO ${this.domain} (key, value, cli, source, timestamp, trust_tier)
+         VALUES (@key, @value, @cli, @source, @timestamp, @trust_tier)
+         ON CONFLICT(key) DO UPDATE SET
+           value = excluded.value,
+           cli = excluded.cli,
+           source = excluded.source,
+           timestamp = excluded.timestamp,
+           trust_tier = excluded.trust_tier`
+      ),
+      delete: this.db.prepare(`DELETE FROM ${this.domain} WHERE key = ?`),
+      count: this.db.prepare(`SELECT COUNT(*) AS count FROM ${this.domain}`),
+      bounds: this.db.prepare(
+        `SELECT MIN(timestamp) AS oldest, MAX(timestamp) AS newest FROM ${this.domain}`
+      ),
+      queryAll: this.db.prepare(
+        `SELECT key, value, cli, source, timestamp, trust_tier FROM ${this.domain}`
+      )
+    };
+  }
+  async read(key) {
+    this.assertOpen();
+    const start = Date.now();
+    const row = this.stmts.read.get(keyToString(key));
+    const value = row !== void 0 ? JSON.parse(row.value) : void 0;
+    recordMemoryEvent({
+      domain: this.domain,
+      op: "read",
+      hit: value !== void 0,
+      ...row?.cli !== null && row?.cli !== void 0 && { cli: row.cli },
+      durationMs: Date.now() - start,
+      key,
+      result: value
+    });
+    return Promise.resolve(value);
+  }
+  validate(value) {
+    if (this.schema === void 0) return;
+    const result = this.schema.safeParse(value);
+    if (!result.success) {
+      throw new MemoryValidationError(this.domain, result.error);
+    }
+  }
+  async write(key, value, meta) {
+    this.assertOpen();
+    const start = Date.now();
+    this.validate(value);
+    this.stmts.write.run(buildWriteRow(key, value, meta));
+    recordMemoryEvent({
+      domain: this.domain,
+      op: "write",
+      ...meta?.cli !== void 0 && { cli: meta.cli },
+      durationMs: Date.now() - start,
+      key,
+      payload: value
+    });
+    return Promise.resolve();
+  }
+  async query(filter) {
+    this.assertOpen();
+    const start = Date.now();
+    let rows = this.stmts.queryAll.all();
+    if (filter?.cli !== void 0) {
+      rows = rows.filter((r) => r.cli === filter.cli);
+    }
+    let values = rows.map((r) => JSON.parse(r.value));
+    values = applyQueryFilter(values, filter);
+    recordMemoryEvent({
+      domain: this.domain,
+      op: "query",
+      hit: values.length > 0,
+      ...filter?.cli !== void 0 && { cli: filter.cli },
+      durationMs: Date.now() - start,
+      key: filter,
+      result: { count: values.length }
+    });
+    return Promise.resolve(values);
+  }
+  async delete(key) {
+    this.assertOpen();
+    const start = Date.now();
+    const result = this.stmts.delete.run(keyToString(key));
+    const removed = result.changes > 0;
+    recordMemoryEvent({
+      domain: this.domain,
+      op: "delete",
+      hit: removed,
+      durationMs: Date.now() - start,
+      key
+    });
+    return Promise.resolve(removed);
+  }
+  async stats() {
+    this.assertOpen();
+    const start = Date.now();
+    const countRow = this.stmts.count.get();
+    const boundsRow = this.stmts.bounds.get();
+    const result = {
+      domain: this.domain,
+      count: countRow.count,
+      oldestTimestamp: boundsRow.oldest,
+      newestTimestamp: boundsRow.newest
+    };
+    recordMemoryEvent({
+      domain: this.domain,
+      op: "stats",
+      durationMs: Date.now() - start,
+      result
+    });
+    return Promise.resolve(result);
+  }
+  async close() {
+    if (this.closed) return Promise.resolve();
+    this.closed = true;
+    if (this.ownsDb) this.db.close();
+    return Promise.resolve();
+  }
+  assertOpen() {
+    if (this.closed) {
+      throw new Error(`nexus-memory: backend "${this.domain}" is closed`);
+    }
+  }
+};
+var MemoryRegistry = class {
+  backends = /* @__PURE__ */ new Map();
+  db;
+  closed = false;
+  constructor(options = {}) {
+    if (options.dbPath !== void 0) {
+      const db = new Database2(options.dbPath);
+      db.pragma("journal_mode = WAL");
+      this.db = db;
+    }
+  }
+  /**
+   * Register a backend for `domain`. Throws on duplicate domain.
+   *
+   * When the registry has a `dbPath`, the new backend is SQLite-backed
+   * and shares the registry's connection. Otherwise, an `InMemoryBackend`
+   * is created (used for tests).
+   */
+  register(options) {
+    this.assertOpen();
+    if (this.backends.has(options.domain)) {
+      throw new Error(`nexus-memory: domain "${options.domain}" already registered`);
+    }
+    const backend = this.db !== void 0 ? new SqliteBackend({
+      domain: options.domain,
+      dbPath: "<shared>",
+      // unused when db is supplied
+      db: this.db,
+      ...options.schema !== void 0 && { schema: options.schema }
+    }) : new InMemoryBackend({
+      domain: options.domain,
+      ...options.schema !== void 0 && { schema: options.schema }
+    });
+    this.backends.set(options.domain, backend);
+    return backend;
+  }
+  /**
+   * Attach an externally-managed {@link IMemoryBackend}. Use this when the
+   * backend owns its own storage (e.g., a pre-existing SQLite file under
+   * `~/.nexus-agents/memory/agentic.db`) and you want it discoverable
+   * through the registry without changing its persistence.
+   *
+   * Phase 5–7 of the memory-unification epic use this to bring the
+   * tool-memory backends (`agentic`, `adaptive`, `typed`, `belief`),
+   * OutcomeStore, SICA, skills, etc. under a unified observability
+   * contract without rewriting their internals. Each attached backend
+   * still owns its own `.db` (or JSONL, etc.) until a follow-up migration
+   * folds the storage in fully.
+   */
+  attach(domain, backend) {
+    this.assertOpen();
+    if (this.backends.has(domain)) {
+      throw new Error(`nexus-memory: domain "${domain}" already registered`);
+    }
+    this.backends.set(domain, backend);
+    return backend;
+  }
+  /**
+   * Get a previously-registered backend. Returns `undefined` if the
+   * domain isn't registered — callers should treat that as "not yet
+   * migrated to the unified contract."
+   */
+  get(domain) {
+    this.assertOpen();
+    const backend = this.backends.get(domain);
+    return backend;
+  }
+  /** List all registered domains. Useful for `memory_stats`-style readers. */
+  domains() {
+    return [...this.backends.keys()];
+  }
+  /**
+   * Close every registered backend and the shared SQLite handle. After
+   * `close()` the registry rejects all further operations.
+   */
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    for (const backend of this.backends.values()) {
+      await backend.close();
+    }
+    this.backends.clear();
+    if (this.db !== void 0) this.db.close();
+  }
+  assertOpen() {
+    if (this.closed) {
+      throw new Error("nexus-memory: registry is closed");
+    }
+  }
+};
+var sharedRegistry = null;
+function getMemoryRegistry() {
+  if (sharedRegistry === null) {
+    const dbPath = resolveDefaultDbPath();
+    sharedRegistry = new MemoryRegistry({ dbPath });
+  }
+  return sharedRegistry;
+}
+function setMemoryRegistry(registry) {
+  sharedRegistry = registry;
+}
+async function closeMemoryRegistry() {
+  if (sharedRegistry !== null) {
+    await sharedRegistry.close();
+    sharedRegistry = null;
+  }
+}
+function resolveDefaultDbPath() {
+  const root = process.env["NEXUS_DATA_DIR"] ?? `${process.env["HOME"] ?? "/tmp"}/.nexus-agents`;
+  return `${root}/memory/memory.db`;
+}
+function createInMemoryMemoryRegistry() {
+  return new MemoryRegistry({
+    /* no dbPath → InMemoryBackend per domain */
+  });
+}
+function createSqliteMemoryRegistry(dbPath) {
+  return new MemoryRegistry({ dbPath });
+}
+var importers = /* @__PURE__ */ new Map();
+function registerImporter(importer) {
+  if (importers.has(importer.id)) {
+    throw new Error(`nexus-memory: importer "${importer.id}" already registered`);
+  }
+  importers.set(importer.id, importer);
+}
+function resetImporters() {
+  importers.clear();
+}
+function listImporters() {
+  return [...importers.keys()];
+}
+async function runImporters(registry, options) {
+  mkdirSync(options.markerDir, { recursive: true });
+  const runs = [];
+  const errors = [];
+  for (const importer of importers.values()) {
+    const marker = join(options.markerDir, `.imported-${importer.id}`);
+    if (options.force !== true && existsSync(marker)) continue;
+    try {
+      const run = await importer.run(registry);
+      writeMarker(marker, run);
+      runs.push(run);
+    } catch (err) {
+      errors.push({ id: importer.id, error: err instanceof Error ? err : new Error(String(err)) });
+    }
+  }
+  return { runs, errors };
+}
+function writeMarker(path, run) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(
+    path,
+    JSON.stringify({ ...run, completedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2),
+    "utf-8"
+  );
+}
+function backupSourceFile(sourcePath) {
+  if (!existsSync(sourcePath)) return null;
+  const backup = `${sourcePath}.bak.${String(Date.now())}`;
+  renameSync(sourcePath, backup);
+  return backup;
+}
+
+export {
+  recordMemoryEvent,
+  getMemoryEventCounters,
+  subscribeToMemoryEvents,
+  resetMemoryTelemetry,
+  MemoryValidationError,
+  InMemoryBackend,
+  SqliteBackend,
+  MemoryRegistry,
+  getMemoryRegistry,
+  setMemoryRegistry,
+  closeMemoryRegistry,
+  createInMemoryMemoryRegistry,
+  createSqliteMemoryRegistry,
+  registerImporter,
+  resetImporters,
+  listImporters,
+  runImporters,
+  backupSourceFile
+};
+//# sourceMappingURL=chunk-PQHVC4BD.js.map