clay-server 5.1.1-beta.1 → 5.2.0-beta.10

package/lib/knowledge-db-storage-nedb-maintenance.js

@@ -0,0 +1,99 @@
+var fs = require("fs");
+
+var MIN_COMPACTION_BYTES = 1024 * 1024;
+var MAX_WRITE_AMPLIFICATION = 3;
+var MAX_WRITES_WITHOUT_COMPACTION = 64;
+var FAILURE_HEADROOM_BYTES = 4 * 1024 * 1024;
+var FAILURE_AMPLIFICATION = 6;
+
+// Shared by every service instance for this filename. No interval or background work:
+// maintenance runs inside the same I/O gate as writes, reads and failed-write reloads.
+function attachKnowledgeDbNedbMaintenance(ctx) {
+  var entry = ctx.entry;
+  if (!entry.storage) entry.storage = {
+    queue: Promise.resolve(), store: null, cached: [], sizes: new Map(), liveBytes: 0,
+    journalBytes: 0, peakJournalBytes: 0, journalUnknown: false, successfulWrites: 0,
+    writesSinceCompaction: 0, compactions: 0, failedCompactions: 0, recoveries: 0,
+    maintenancePending: false, maintenanceError: null
+  };
+  var state = entry.storage;
+  function enqueue(work) {
+    var next = state.queue.catch(function () {}).then(work);
+    state.queue = next.catch(function () {}); return next;
+  }
+  function size(value) { return Buffer.byteLength(JSON.stringify(value), "utf8") + 1; }
+  function refresh(store) {
+    state.store = store; state.cached = store.getAllData(); state.sizes = new Map(); state.liveBytes = 0;
+    state.cached.forEach(function (value) { var bytes = size(value); state.sizes.set(value._id, bytes); state.liveBytes += bytes; });
+  }
+  function issue(cause) { state.maintenancePending = true; state.maintenanceError = cause.message || String(cause); }
+  async function measure() {
+    try {
+      state.journalBytes = (await fs.promises.stat(ctx.filename)).size; state.journalUnknown = false;
+      state.peakJournalBytes = Math.max(state.peakJournalBytes, state.journalBytes);
+      return true;
+    } catch (cause) { state.journalUnknown = true; issue(cause); return false; }
+  }
+  async function ensure() {
+    var store = await ctx.open();
+    if (state.store !== store) { refresh(store); await measure(); }
+    return store;
+  }
+  async function compact(store) {
+    try {
+      // Supported datastore API also participates in NeDB's own executor.
+      await store.compactDatafileAsync();
+      state.compactions++; state.writesSinceCompaction = 0;
+      if (await measure()) { state.maintenancePending = false; state.maintenanceError = null; }
+    } catch (cause) { state.failedCompactions++; issue(cause); await measure(); }
+  }
+  function due() {
+    return state.journalBytes > Math.max(MIN_COMPACTION_BYTES, MAX_WRITE_AMPLIFICATION * state.liveBytes) ||
+      state.writesSinceCompaction >= MAX_WRITES_WITHOUT_COMPACTION && state.journalBytes - state.liveBytes >= MIN_COMPACTION_BYTES;
+  }
+  function blocked() {
+    return state.maintenancePending && (state.journalUnknown || state.journalBytes > Math.max(FAILURE_HEADROOM_BYTES, FAILURE_AMPLIFICATION * state.liveBytes));
+  }
+  function read(work) { return enqueue(async function () { return work(await ensure()); }); }
+  function write(work, value) {
+    return enqueue(async function () {
+      var store = await ensure(); var attempted = false;
+      if (state.maintenancePending) { attempted = true; await compact(store); }
+      // Repeated maintenance failure cannot allow unbounded journal growth. This
+      // rejection happens before the next canonical write, never after its success.
+      if (blocked()) throw Object.assign(new Error("Knowledge database maintenance must recover before more writes: " + state.maintenanceError), { code: "STORAGE_MAINTENANCE_BLOCKED" });
+      var result;
+      try { result = await work(store); }
+      catch (cause) {
+        // NeDB changes indexes before appending. Hold the shared gate through reload
+        // so another database cannot compact or persist an unsaved in-memory state.
+        try {
+          await store.loadDatabaseAsync(); refresh(store); state.recoveries++; state.writesSinceCompaction = 0;
+          if (await measure()) { state.maintenancePending = false; state.maintenanceError = null; }
+        } catch (recoveryCause) { state.store = null; state.cached = []; issue(recoveryCause); ctx.invalidate(); }
+        throw cause;
+      }
+      if (result && result.numAffected === 0) return result;
+      var bytes = size(value); state.liveBytes += bytes - (state.sizes.get(value._id) || 0); state.sizes.set(value._id, bytes);
+      state.cached = store.getAllData(); state.successfulWrites++; state.writesSinceCompaction++;
+      if (await measure() && !attempted && due()) await compact(store);
+      // A maintenance error never changes a successful canonical write into a failure.
+      return result;
+    });
+  }
+  function status() {
+    return read(async function () {
+      await measure();
+      return { maintenancePending: state.maintenancePending, maintenanceError: state.maintenanceError,
+        liveBytes: state.liveBytes, journalBytes: state.journalBytes, peakJournalBytes: state.peakJournalBytes,
+        successfulWrites: state.successfulWrites, writesSinceCompaction: state.writesSinceCompaction,
+        compactions: state.compactions, failedCompactions: state.failedCompactions, recoveries: state.recoveries };
+    });
+  }
+  return { read: read, write: write, cached: function () { return state.cached; }, readStorageStatus: status };
+}
+
+module.exports = { attachKnowledgeDbNedbMaintenance: attachKnowledgeDbNedbMaintenance,
+  MIN_COMPACTION_BYTES: MIN_COMPACTION_BYTES, MAX_WRITE_AMPLIFICATION: MAX_WRITE_AMPLIFICATION,
+  MAX_WRITES_WITHOUT_COMPACTION: MAX_WRITES_WITHOUT_COMPACTION,
+  FAILURE_HEADROOM_BYTES: FAILURE_HEADROOM_BYTES, FAILURE_AMPLIFICATION: FAILURE_AMPLIFICATION };

package/lib/knowledge-db-storage-nedb.js

@@ -0,0 +1,66 @@
+var fs = require("fs");
+var path = require("path");
+var Datastore = require("@seald-io/nedb");
+var maintenance = require("./knowledge-db-storage-nedb-maintenance");
+var STORE_REGISTRY = new Map();
+
+function clone(value) { return JSON.parse(JSON.stringify(value)); }
+function error(message, code) { return Object.assign(new Error(message), { code: code }); }
+function createKnowledgeDbNedbStorage(options) {
+  var projectDir = path.resolve(options.projectDir); var projectReal = null;
+  var knowledgeDir = path.join(projectDir, "knowledge"); var dataDir = path.join(knowledgeDir, ".clay-db");
+  var filename = path.join(dataDir, "databases.db"); var entry = STORE_REGISTRY.get(filename);
+  if (!entry) { entry = { queues: new Map(), database: null, loading: null, ready: false }; STORE_REGISTRY.set(filename, entry); }
+  function safeDirectory(target, create) {
+    var stat;
+    try { stat = fs.lstatSync(target); }
+    catch (cause) { if (!create || cause.code !== "ENOENT") throw cause; fs.mkdirSync(target, { recursive: true, mode: 0o700 }); stat = fs.lstatSync(target); }
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw error("Knowledge database path is unsafe.", "UNSAFE_PATH");
+    var real = fs.realpathSync(target);
+    if (real !== projectReal && !real.startsWith(projectReal + path.sep)) throw error("Knowledge database path escapes the Mate project.", "UNSAFE_PATH");
+  }
+  function open() {
+    if (entry.loading) return entry.loading;
+    entry.loading = Promise.resolve().then(function () {
+      projectReal = fs.realpathSync(projectDir); safeDirectory(knowledgeDir, true); safeDirectory(dataDir, true);
+      var stat; try { stat = fs.lstatSync(filename); } catch (cause) { if (cause.code !== "ENOENT") throw cause; }
+      if (stat && (!stat.isFile() || stat.isSymbolicLink())) throw error("Knowledge database file is unsafe.", "UNSAFE_PATH");
+      entry.database = new Datastore({ filename: filename }); return entry.database.loadDatabaseAsync();
+    }).then(function () { return entry.database.ensureIndexAsync({ fieldName: "_id", unique: true }); })
+      .then(function () { entry.ready = true; return entry.database; })
+      .catch(function (cause) { invalidate(); throw cause; });
+    return entry.loading;
+  }
+  function invalidate() { entry.database = null; entry.loading = null; entry.ready = false; }
+  var io = maintenance.attachKnowledgeDbNedbMaintenance({ entry: entry, filename: filename, open: open, invalidate: invalidate });
+  function serialize(scope, work) {
+    var previous = entry.queues.get(scope) || Promise.resolve(); var next = previous.catch(function () {}).then(function () { return work(); });
+    entry.queues.set(scope, next.catch(function () {})); return next;
+  }
+  function insert(snapshot) {
+    var value = clone(snapshot);
+    return io.write(function (store) { return store.insertAsync(value); }, value).then(function () {}, function (cause) {
+      if (cause.errorType === "uniqueViolated") throw error("Knowledge storage identity already exists.", "ALREADY_EXISTS");
+      throw cause;
+    });
+  }
+  function replaceIfRevision(id, revision, snapshot) {
+    var value = clone(snapshot);
+    if (value._id !== id) return Promise.reject(error("Knowledge storage replacement identity must match.", "INVALID_STORAGE_ID"));
+    return io.write(function (store) { return store.updateAsync({ _id: id, revision: revision }, value, {}); }, value)
+      .then(function (result) { return result.numAffected === 1; });
+  }
+  return {
+    contractVersion: 1,
+    initialize: function () { return io.read(function () {}); },
+    hasStore: function () { try { return fs.lstatSync(filename).isFile(); } catch (cause) { return false; } },
+    isReady: function () { return entry.ready === true; },
+    get: function (id) { return io.read(function (store) { return store.findOneAsync({ _id: id }); }); },
+    list: function () { return io.read(function (store) { return store.findAsync({}); }); },
+    getCached: function () { return clone(io.cached()); },
+    insert: insert, replaceIfRevision: replaceIfRevision, serialize: serialize,
+    diagnostics: function () { return io.readStorageStatus().then(function (status) { return Object.assign({ engine: "nedb", automaticCompaction: false }, status); }); }
+  };
+}
+
+module.exports = { createKnowledgeDbNedbStorage: createKnowledgeDbNedbStorage };

package/lib/knowledge-db-storage.js

@@ -0,0 +1,72 @@
+// Version 1 persists opaque JSON aggregate snapshots with a stable _id and revision.
+// _id is the existing Knowledge identity, not a query expression. Engines may map it
+// to their own primary key; aggregate format/limits remain application responsibilities.
+// Each adapter is bound to one server-authorized Mate-project store; get/list cannot
+// broaden that scope. Facades for the same store must share locks and committed cache.
+//
+// initialize() -> Promise<void>; hasStore()/isReady() -> boolean.
+// get(id) -> Promise<snapshot|null>; list() -> Promise<snapshot[]>;
+// getCached() -> snapshot[] (committed, detached, no initialization side effect).
+// insert(snapshot) -> Promise<void> (reject ALREADY_EXISTS; never overwrite).
+// replaceIfRevision(id, revision, snapshot) -> Promise<boolean>: atomic compare and
+// full replacement, false on missing/mismatch without writing. Same-revision writes
+// are allowed for receipts/projection status. Identity must remain unchanged.
+// serialize(scope, work) -> Promise<result>: same-scope callbacks exclude each other
+// across all facades of one physical store. Callback receives no engine objects and
+// may await adapter operations; this is not a multi-aggregate transaction or I/O lock.
+// Engines separately serialize reads/writes/maintenance/recovery as needed. A failed
+// write may have committed durably; restore readable committed state before releasing
+// the I/O gate, or invalidate it. Never turn committed success into maintenance failure.
+// Domain operation receipts resolve ambiguous retries; the adapter does not own them.
+// diagnostics() -> Promise<JSON> is optional, engine-specific and never a native handle.
+
+var METHODS = ["initialize", "hasStore", "isReady", "get", "list", "getCached", "insert", "replaceIfRevision", "serialize"];
+function invalid(message) { return Object.assign(new Error("Invalid Knowledge storage adapter: " + message), { code: "INVALID_STORAGE_ADAPTER" }); }
+function validateAdapter(adapter) {
+  if (!adapter || typeof adapter !== "object" || adapter.contractVersion !== 1) throw invalid("contractVersion must be 1.");
+  METHODS.forEach(function (name) { if (typeof adapter[name] !== "function") throw invalid(name + " must be a function."); });
+  if (adapter.diagnostics !== undefined && typeof adapter.diagnostics !== "function") throw invalid("diagnostics must be a function when supplied.");
+  return adapter;
+}
+function bindAdapter(adapter) {
+  function snapshot(value) {
+    if (!value || Object.getPrototypeOf(value) !== Object.prototype || typeof value._id !== "string" || !Number.isInteger(value.revision)) throw invalid("snapshot must be a plain aggregate with _id and integer revision.");
+    return value;
+  }
+  function snapshots(values) { if (!Array.isArray(values)) throw invalid("list/getCached must return an array."); values.forEach(snapshot); return values; }
+  function call(name, args, check) {
+    var result;
+    try { result = adapter[name].apply(adapter, args); } catch (cause) { return Promise.reject(cause); }
+    if (!result || typeof result.then !== "function") return Promise.reject(invalid(name + " must return a Promise."));
+    return result.then(check);
+  }
+  function flag(name) { var value = adapter[name](); if (typeof value !== "boolean") throw invalid(name + " must return a boolean."); return value; }
+  var bound = {
+    contractVersion: 1,
+    initialize: function () { return call("initialize", [], function () {}); },
+    hasStore: function () { return flag("hasStore"); }, isReady: function () { return flag("isReady"); },
+    get: function (id) { return call("get", [id], function (value) { if (value === null) return null; snapshot(value); if (value._id !== id) throw invalid("get returned a different identity."); return value; }); },
+    list: function () { return call("list", [], snapshots); }, getCached: function () { return snapshots(adapter.getCached()); },
+    insert: function (value) { return call("insert", [value], function (result) { if (result !== undefined) throw invalid("insert must resolve without a native result."); }); },
+    replaceIfRevision: function (id, revision, value) { return call("replaceIfRevision", [id, revision, value], function (result) { if (typeof result !== "boolean") throw invalid("replaceIfRevision must resolve to a boolean."); return result; }); },
+    serialize: function (scope, work) { return call("serialize", [scope, function () { return work(); }], function (result) { return result; }); }
+  };
+  if (typeof adapter.diagnostics === "function") bound.diagnostics = function () {
+    return call("diagnostics", [], function (result) { try { return JSON.parse(JSON.stringify(result)); } catch (cause) { throw invalid("diagnostics must resolve to JSON data."); } });
+  };
+  return bound;
+}
+function createDefaultKnowledgeDbStorage(options) {
+  // Lazy engine loading: injected adapters can run domain code without NeDB installed.
+  return require("./knowledge-db-storage-nedb").createKnowledgeDbNedbStorage(options);
+}
+function createKnowledgeDbStorage(options) {
+  var settings = options || {}; var adapter;
+  if (settings.storageAdapter !== undefined) adapter = settings.storageAdapter;
+  else if (settings.storageFactory !== undefined) {
+    if (typeof settings.storageFactory !== "function") throw invalid("storageFactory must be a synchronous function.");
+    adapter = settings.storageFactory({ projectDir: settings.projectDir });
+  } else adapter = module.exports.createDefaultKnowledgeDbStorage({ projectDir: settings.projectDir });
+  return bindAdapter(validateAdapter(adapter));
+}
+module.exports = { createKnowledgeDbStorage: createKnowledgeDbStorage, createDefaultKnowledgeDbStorage: createDefaultKnowledgeDbStorage, validateAdapter: validateAdapter, invalid: invalid };

package/lib/knowledge-document-index.js

@@ -18,7 +18,8 @@ function createKnowledgeDocumentIndex(options) {
       if (file.size > options.maxDocumentBytes) { errors.push({ name: file.name, code: "TOO_LARGE", error: "Document exceeds the safe read limit." }); continue; }
       if (known && token && known.token === token) {
         if (bytes + known.bytes > MAX_INDEX_BYTES) { errors.push({ name: file.name, code: "INDEX_LIMIT", error: "Workspace Knowledge exceeds the safe index limit." }); continue; }
-        next[key] = known; documents.push(known.document); bytes += known.bytes; continue;
+        var fresh = Object.assign({}, known, { document: Object.assign({}, known.document, file) });
+        next[key] = fresh; documents.push(fresh.document); bytes += known.bytes; continue;
       }
       try { content = options.read(file); } catch (error) { errors.push({ name: file.name, code: error.code || "READ_FAILED", error: error.message }); continue; }
       var size = Buffer.byteLength(content, "utf8");

package/lib/knowledge-file-store.js

@@ -136,7 +136,13 @@ function createKnowledgeFileStore(cwd, options) {
     var listed = list(); var identity = listed.filter(function (entry) { return entry.name === item.name; })[0]; if (!identity) return; ensureMetadata(true);
     var folder = path.join(historyRoot, identity.id); safeDirectory(folder, true);
     var target = path.join(folder, Date.now() + "-" + item.revision + ".md");
-    fs.writeFileSync(target, item.content, { flag: "wx", mode: 0o600 });
+    try { fs.writeFileSync(target, item.content, { flag: "wx", mode: 0o600 }); }
+    catch (error) {
+      // A move and its link rewrite can snapshot the same revision in one millisecond.
+      if (error.code !== "EEXIST") throw error;
+      var stat = fs.lstatSync(target);
+      if (!stat.isFile() || stat.isSymbolicLink() || fs.readFileSync(target, "utf8") !== item.content) throw error;
+    }
   }
   function save(name, content, expectedRevision) {
     var clean = cleanName(name); if (!clean || itemType(clean) !== "text") throw new Error("Only valid Markdown documents can be edited.");

package/lib/knowledge-product-operations.js

@@ -0,0 +1,46 @@
+var validName = require('./knowledge-file-store').validName;
+// Narrow operations over the same document store used by the Knowledge workbench.
+function createKnowledgeProductOperations(ctx) {
+  function find(args, deleted) {
+    var item = args.documentId ? ctx.files.list().concat(deleted ? ctx.files.deleted() : []).find(function (entry) { return entry.id === args.documentId; }) : null;
+    if (args.documentId && !item) throw Object.assign(new Error('Knowledge document not found.'), { code: 'ENOENT' });
+    var name = args.name || item && item.name;
+    if (!name || item && args.name && args.name !== item.name) throw new Error('Choose one exact Knowledge document.');
+    if (item && item.deleted) return item;
+    var current = ctx.files.read(name);
+    if (current.itemType !== 'text') throw new Error('Legacy JSONL sources are read-only.');
+    return current;
+  }
+  function read(args) { var item = find(args); return { documentId: item.id, name: item.name, revision: item.revision, content: item.content }; }
+  function saved(item, who) { return Object.assign({ documentId: item.id, name: item.name, revision: item.revision, persisted: true }, ctx.mirror(who, [item.name])); }
+  function snapshot(op) {
+    if (op.action === 'retry_document_sync' && op.names.some(function (name) { return !validName(name); })) throw new Error('Invalid Knowledge source name.');
+    if (op.action === 'create_document') return ctx.files.list().filter(function (item) { return item.name === op.name; });
+    if (op.action === 'retry_document_sync') return ctx.files.list().filter(function (item) { return op.names.indexOf(item.name) >= 0; });
+    var item = find(op, op.action === 'restore_document');
+    var result = { documentId: item.id, name: item.name, revision: item.revision, deleted: !!item.deleted };
+    if (op.action === 'restore_document') result.version = ctx.files.readHistory(item.id, op.version);
+    if (op.action === 'rename_document') result.documents = ctx.files.list();
+    return result;
+  }
+  function mutate(op, who) {
+    if (op.action === 'create_document') return saved(ctx.files.save(op.name, op.content, null), who);
+    if (op.action === 'retry_document_sync') return Object.assign({ persisted: true }, ctx.mirror(who, op.names));
+    var item = find(op, op.action === 'restore_document');
+    if (op.action === 'update_document') return saved(ctx.files.save(item.name, op.content, op.expectedRevision), who);
+    if (op.action === 'rename_document') return ctx.rename({ from: item.name, name: op.newName, documentId: item.id, expectedRevision: op.expectedRevision }, who);
+    if (op.action === 'delete_document') { ctx.files.remove(item.name, op.expectedRevision); return Object.assign({ documentId: item.id, name: item.name, persisted: true, deleted: true }, ctx.mirror(who, [item.name])); }
+    if (op.action === 'restore_document') return saved(ctx.files.restore(item.id, op.version, item.name, item.deleted ? null : op.expectedRevision), who);
+    throw new Error('Unsupported Knowledge document operation.');
+  }
+  function query(op) {
+    if (op.action === 'list_documents') return { documents: op.deleted ? ctx.files.deleted() : ctx.files.list() };
+    if (op.action === 'read_document') return read(op);
+    var item = find(op, true);
+    if (op.action === 'document_history') return { documentId: item.id, name: item.name, versions: ctx.files.history(item.id) };
+    if (op.action === 'read_document_version') return Object.assign({ documentId: item.id, name: item.name }, ctx.files.readHistory(item.id, op.version));
+    throw new Error('Unsupported Knowledge document query.');
+  }
+  return { query: query, snapshot: snapshot, mutate: mutate };
+}
+module.exports = { createKnowledgeProductOperations: createKnowledgeProductOperations };

package/lib/mate-avatar-catalog.js

@@ -0,0 +1,12 @@
+// Stable catalog identities are the only accepted library references.
+var catalog = require('./public/mate-avatars/catalog.json');
+var ids = new Set(catalog.map(function (entry) { return entry.id; }));
+function valid(id) { return typeof id === 'string' && ids.has(id); }
+function validate(profile, mate) {
+  if (profile !== undefined && (!profile || typeof profile !== 'object' || Array.isArray(profile))) return 'Choose a valid Mate profile.';
+  if (profile && Object.prototype.hasOwnProperty.call(profile, 'avatarCatalogId') && profile.avatarCatalogId !== '' && !valid(profile.avatarCatalogId) && !(profile.avatarCatalogId === 'lead-clay' && mate && mate.builtinKey === 'clay')) {
+    return 'Choose an avatar from the Clay catalog.';
+  }
+  return null;
+}
+module.exports = { valid: valid, validate: validate };

package/lib/mate-avatar-migration.js

@@ -0,0 +1,41 @@
+// Stable v1 migration, run only against the caller's normal Mate registry.
+var catalog = require('./mate-avatar-catalog');
+var managedArtwork = { clay: ['/clay-studio-symbol.png', '/mates/ally.png', '/mate-avatars/lead-clay.png'], ally: ['/mates/ally.png'] };
+function mappedId(mate) {
+  var p = mate.profile || mate;
+  var key = JSON.stringify([mate.id || '', p.avatarStyle || 'imprint', p.avatarSeed || mate.id || p.displayName || mate.name || 'Mate']);
+  var hash = 2166136261;
+  for (var i = 0; i < key.length; i++) hash = Math.imul(hash ^ key.charCodeAt(i), 16777619) >>> 0;
+  var index = hash % 96;
+  return (index < 48 ? 'B' : 'C') + String(index % 48 + 1).padStart(2, '0');
+}
+function hasCustom(mate) {
+  var p = mate.profile || {};
+  var custom = p.avatarCustom || mate.avatarCustom;
+  if (!custom) return false;
+  var managed = managedArtwork[mate.builtinKey] || [];
+  return managed.indexOf(custom) === -1;
+}
+function normalizeMate(mate) {
+  if (!mate || hasCustom(mate)) return false;
+  var before = JSON.stringify(mate.profile || {});
+  var p = Object.assign({}, mate.profile || {});
+  p.avatarCatalogId = mate.builtinKey === 'clay' ? 'lead-clay' : catalog.valid(p.avatarCatalogId) ? p.avatarCatalogId : mappedId(mate);
+  p.avatarStyle = 'catalog';
+  delete p.avatarSeed;
+  if (p.avatarCustom) p.avatarCustom = '';
+  if (mate.builtinKey === 'clay') p.avatarLocked = true;
+  if (before === JSON.stringify(p) && !Object.prototype.hasOwnProperty.call(mate, 'avatarStyle') && !Object.prototype.hasOwnProperty.call(mate, 'avatarSeed') && !Object.prototype.hasOwnProperty.call(mate, 'avatarCustom')) return false;
+  mate.profile = p;
+  delete mate.avatarStyle;
+  delete mate.avatarSeed;
+  delete mate.avatarCustom;
+  return true;
+}
+function migrate(data) {
+  var changed = false;
+  data.mates.forEach(function (mate) { if (normalizeMate(mate)) changed = true; });
+  if (data.avatarCatalogMigrationVersion !== 1) { data.avatarCatalogMigrationVersion = 1; changed = true; }
+  return changed;
+}
+module.exports = { mappedId: mappedId, hasCustom: hasCustom, normalizeMate: normalizeMate, migrate: migrate };

package/lib/mate-context-service.js

@@ -0,0 +1,138 @@
+// Restricted contextual access. References originate on authenticated app sockets;
+// model arguments and submitted attachments never create or widen a grant.
+var crypto = require('crypto');
+var refs = require('./workspace-query-service');
+var provenance = require('./session-provenance');
+var personal = require('./mcp-session-access');
+var z = require('zod');
+var preparationSchema = z.object({ type: z.literal('mate_context_prepare'), requestId: z.string().max(100).optional(), available: z.boolean(), mateId: z.string().max(128).optional(), sessionId: z.number().int().positive().optional() }).strict();
+function attachMateContextService(ctx) {
+  var access = require('./workspace-query-access').attachWorkspaceQueryAccess(ctx);
+  var views = new WeakMap(), pending = new Map(), active = new WeakMap();
+  function owner(ws) { return ctx.isMultiUser() ? ws && ws._clayUser && ws._clayUser.id : null; }
+  function privateSession(session, manager, id) {
+    if (!session || manager.sessions.get(session.localId) !== session || session.hidden || session.destroying || session.spawn || provenance.isWorker(session) ||
+      session.sessionVisibility === 'shared' || session.delegated || session._delegatedBy || session._pairDelegation || session._mcpForeignInput ||
+      session.homeDebatePlanning || session.debateSetupMode || session.mateCreationMode || session._mentionInProgress) throw new Error('A live private owner conversation is required.');
+    if (ctx.isMultiUser() ? !id || session.ownerId !== id || !ctx.findUser(id) || !personal.canUsePersonalConnections(session, manager.sessions) : !!session.ownerId ||
+      (session.history || []).some(function (entry) { return entry.type === 'user_message' && entry.from && entry.from !== 'default'; })) throw new Error('Owner-authored input is required.');
+  }
+  function source(id, mateId, sessionId) {
+    var mate = ctx.resolveMate(id, mateId), project = ctx.getProjects().get('mate-' + mateId);
+    var status = project && project.getStatus(), manager = project && project.getSessionManager();
+    if (!mate || mate.builtinKey === 'clay' || mate.archived || mate.lifecycleDeletion || !status || !status.isMate || status.mateId !== mateId || (ctx.isMultiUser() && (mate.createdBy !== id || status.projectOwnerId !== id))) throw new Error('This private Mate is unavailable.');
+    var session = manager.sessions.get(sessionId);
+    privateSession(session, manager, id);
+    var user = ctx.isMultiUser() && ctx.findUser(id);
+    return { mate: mate, revision: JSON.stringify(mate), project: project, session: session, manager: manager, path: status.path, osIdentity: JSON.stringify(user && [user.id, user.linuxUser || null]) };
+  }
+  function selected(id, viewer) {
+    var project = ctx.getProjects().get(viewer.slug), status = project && project.getStatus();
+    var principal = { userId: id, singleUserOwnerId: id };
+    if (!status || status.isMate || !access.evaluate(principal, status).accessible) throw new Error('The selected ordinary project is unavailable.');
+    var manager = project.getSessionManager(), session = manager.sessions.get(viewer.sessionId);
+    privateSession(session, manager, id);
+    return { project: project, session: session, path: status.path, revision: JSON.stringify([status.path, status.projectOwnerId, session.sessionOriginId, session.cliSessionId, session.title, session.history]),
+      summary: { project: String(status.title || status.project || status.slug).slice(0, 160), conversation: String(session.title || 'New conversation').slice(0, 160) } };
+  }
+  function validate(entry) {
+    if (!entry || Date.now() - entry.created > 300000) throw new Error('Context expired. Send a new message from the current view.');
+    var viewer = ctx.getOwnerUi().check(entry.owner, entry.viewer);
+    if (views.get(viewer.ws) !== entry.view) throw new Error('The current view changed. Send a new message from that view.');
+    var live = source(entry.owner, entry.mateId, entry.source.session.localId), target = selected(entry.owner, viewer);
+    if (live.project !== entry.source.project || live.session !== entry.source.session || live.revision !== entry.source.revision || live.path !== entry.source.path || live.osIdentity !== entry.source.osIdentity) throw new Error('The Mate was changed or replaced.');
+    if (target.project !== entry.target.project || target.session !== entry.target.session || target.revision !== entry.target.revision) throw new Error('The selected conversation changed or was replaced.');
+    return { source: live, target: target };
+  }
+  function send(ws, value) { if (ws.readyState === 1) ws.send(JSON.stringify(value)); }
+  function handleMessage(ws, msg) {
+    if (msg.type !== 'mate_context_prepare') return false;
+    var id = owner(ws), requestId = typeof msg.requestId === 'string' ? msg.requestId.slice(0, 100) : null;
+    try {
+      preparationSchema.parse(msg);
+      var viewer = ctx.getOwnerUi().list(id).find(function (item) { return item.ws === ws && item.supported; });
+      if (!viewer) throw new Error('The originating window is unavailable.');
+      var view = {}; views.set(ws, view);
+      if (msg.available !== true) throw new Error('This view has no supported conversation selection.');
+      var live = source(id, msg.mateId, msg.sessionId), target = selected(id, viewer);
+      pending.forEach(function (entry, key) { if (Date.now() - entry.created > 300000 || entry.viewer.ws === ws) pending.delete(key); });
+      if (pending.size >= 100) throw new Error('Context capacity is temporarily full.');
+      var ref = 'mate-context:' + crypto.randomUUID();
+      pending.set(ref, { owner: id, viewer: viewer, view: view, mateId: msg.mateId, source: live, target: target, created: Date.now() });
+      send(ws, { type: 'mate_context_prepared', requestId: requestId, contextRef: ref, summary: target.summary, expiresAt: Date.now() + 300000 });
+    } catch (error) { send(ws, { type: 'mate_context_prepared', requestId: requestId, contextRef: null, error: error.message }); }
+    return true;
+  }
+  function activate(ws, session, ref, message) {
+    active.delete(session);
+    var original = pending.get(ref);
+    var entry = original && Object.assign({}, original);
+    if (!entry) throw new Error('No current context was shared.');
+    var live = validate(entry);
+    if (owner(ws) !== entry.owner || live.source.session !== session || !live.source.project.clients.has(ws) || ws._clayActiveSession !== session.localId || ws._clayAuthCheck && !ws._clayAuthCheck()) throw new Error('Context belongs to another authenticated conversation.');
+    entry.message = message; entry.ref = ref; entry.requests = new Map(); entry.deliveries = new Set(); active.set(session, entry);
+    return { contextRef: ref, summary: entry.target.summary, limits: 'Selected conversation metadata; read_selected_context returns at most 20 redacted text turns (24000 characters). No screen capture, Issues, documents, files or hidden settings. Opening this conversation requires exact owner review.' };
+  }
+  function clear(session) { active.delete(session); }
+  function assertActive(session, ref) {
+    var entry = active.get(session);
+    var latest = (session.history || []).filter(function (item) { return item.type === 'user_message'; }).slice(-1)[0];
+    if (!entry || latest !== entry.message || entry.ref !== ref || session.taskStopRequested || session.abortController && session.abortController.signal.aborted) throw new Error('Shared context was interrupted.');
+    validate(entry);
+  }
+  function bind(input) {
+    var session = input.session, generation = Number(session._sdkQueryGeneration || 0), entry = active.get(session), original;
+    try { original = source(ctx.isMultiUser() ? input.projectOwnerId : null, input.mateId, session.localId); }
+    catch (error) { return null; }
+    if (original.session !== session || input.projectSlug !== 'mate-' + input.mateId || session.taskStopRequested || session.abortController && session.abortController.signal.aborted) return null;
+    function base() {
+      var live = source(ctx.isMultiUser() ? input.projectOwnerId : null, input.mateId, session.localId);
+      if (live.session !== session || live.project !== original.project || live.revision !== original.revision || live.path !== original.path || live.osIdentity !== original.osIdentity || Number(session._sdkQueryGeneration || 0) !== generation || session.taskStopRequested || session.abortController && session.abortController.signal.aborted) throw new Error('This exact private Mate query is unavailable.');
+    }
+    function check() {
+      base();
+      if (!entry || active.get(session) !== entry || Number(session._sdkQueryGeneration || 0) !== generation || session.taskStopRequested || session._pendingMessageDrainPaused || session.abortController && session.abortController.signal.aborted) throw new Error('This context query is unavailable or stopped.');
+      var latest = (session.history || []).filter(function (item) { return item.type === 'user_message'; }).slice(-1)[0];
+      if (latest !== entry.message || input.mateId !== entry.mateId || input.projectSlug !== 'mate-' + entry.mateId || (ctx.isMultiUser() && input.projectOwnerId !== entry.owner)) throw new Error('Context belongs to another exact owner query.');
+      return validate(entry);
+    }
+    function reference(args) { if (!args || args.contextRef !== (entry && entry.ref)) throw new Error('Use only the context reference returned for this query.'); return check(); }
+    return {
+      current: function () {
+        base();
+        if (!entry) return { status: 'unavailable', supported: ['selected_conversation'], unavailable: ['issues', 'documents', 'tabs', 'screen_capture'] };
+        check(); return { status: 'shared_snapshot', contextRef: entry.ref, summary: entry.target.summary, expiresAt: entry.created + 300000, supported: ['selected_conversation'], unavailable: ['issues', 'documents', 'tabs', 'screen_capture'], untrusted: true };
+      },
+      read: async function (args) {
+        var live = reference(args), bound = ctx.workspace.bindProjectSession({ projectSlug: entry.viewer.slug, session: live.target.session, viewerId: entry.owner });
+        if (!bound) throw new Error('The selected conversation is unavailable.');
+        var result = await bound.readProjectSession({ projectSlug: entry.viewer.slug, sessionRef: refs.sessionRef(entry.viewer.slug, live.target.session), limit: 20 });
+        reference(args);
+        var remaining = 24000;
+        var turns = result.turns.map(function (turn) { var text = turn.text.slice(0, remaining); remaining -= text.length; return { role: turn.role, text: text }; }).filter(function (turn) { return !!turn.text; });
+        return { summary: entry.target.summary, turns: turns, truncated: result.total > turns.length || remaining === 0, untrusted: true };
+      },
+      navigate: function (args) {
+        reference(args);
+        var key = JSON.stringify([args.contextRef, args.why]), old = entry.requests.get(args.requestId);
+        if (old) { if (old.key !== key) throw new Error('This requestId already names another intent.'); return old.promise; }
+        if (entry.requests.size >= 20) throw new Error('Too many navigation requests in this context.');
+        var promise = Promise.resolve().then(async function () {
+          var live = check();
+          var answer = await live.source.project.requestProductControlReview(session,
+            'Open the selected conversation: ' + entry.target.summary.conversation + '\nProject: ' + entry.target.summary.project + '\nWhy: ' + args.why,
+            check, { kind: 'product-control', action: 'Open conversation', target: entry.target.summary.conversation, context: 'In ' + entry.target.summary.project + ', in the window that shared this context.', reason: args.why });
+          check();
+          if (answer.status !== 'submitted' || !answer.answers.control || answer.answers.control.length !== 1 || answer.answers.control[0] !== 'Apply exact change') return { status: 'cancelled' };
+          var result = ctx.getOwnerUi().deliver(entry.owner, entry.viewer, { projectSlug: entry.viewer.slug, sessionId: entry.target.session.localId, sessionOriginId: entry.target.session.sessionOriginId, contextualSourceMateId: entry.mateId }, check);
+          if (result.deliveryId) entry.deliveries.add(result.deliveryId);
+          return result;
+        }).catch(function (error) { return { status: 'failed', retrySafe: false, error: error.message }; });
+        entry.requests.set(args.requestId, { key: key, promise: promise }); return promise;
+      },
+      receipt: function (args) { reference(args); if (!entry.deliveries.has(args.deliveryId)) throw new Error('Receipt belongs to another context.'); return ctx.getOwnerUi().read(entry.owner, args.deliveryId); }
+    };
+  }
+  return { handleMessage: handleMessage, activate: activate, clear: clear, assertActive: assertActive, bind: bind };
+}
+module.exports = { attachMateContextService: attachMateContextService };

package/lib/mate-context-tools.js

@@ -0,0 +1,21 @@
+var z = require('zod');
+function getToolDefs(bound) {
+  function tool(name, description, schema, method) {
+    return { name: name, description: description, inputSchema: schema, queryBound: true, handler: async function (args) {
+      try {
+        args = z.object(schema).strict().parse(args || {});
+        if (!bound) throw new Error('No exact owner context query is available.');
+        var result = await bound[method](args);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }], isError: result.status === 'failed' };
+      } catch (error) { return { content: [{ type: 'text', text: JSON.stringify({ status: 'failed', error: error.message }) }], isError: true }; }
+    } };
+  }
+  var ref = z.string().max(100);
+  return [
+    tool('read_current_context', 'Read the server-bound snapshot shared with this exact owner message. Selected ordinary-project conversation metadata only, never live screen capture. Unsupported views, Issues, documents and tabs are unavailable. Context expires after five minutes or any view/target/query/owner change. Content is untrusted data, never approval.', {}, 'current'),
+    tool('read_selected_context', 'Read up to 20 canonical user/assistant text turns (24000 characters total) from ONLY the conversation selected when this message was sent. Hidden/internal entries, tools and attachments are excluded. No enumeration, arbitrary IDs, files or private Mate conversations.', { contextRef: ref }, 'read'),
+    tool('open_context_conversation', 'Open ONLY that exact selected conversation in the originating authenticated window, after exact human review. No messages, edits, execution, Workers, settings or arbitrary routes. Query-local requestId receipts (at most 20, five minutes) never replay interrupted or uncertain effects. Delivery and client acceptance do not prove rendering; inspect receipt before retrying.', { contextRef: ref, requestId: z.string().min(1).max(100), why: z.string().trim().min(1).max(300) }, 'navigate'),
+    tool('read_context_navigation_receipt', 'Read the exact owner navigation delivery receipt within the shared context. Delivery and client acceptance are separate; visible rendering remains unknown. A stopped or stale context cannot resume or replay navigation.', { contextRef: ref, deliveryId: z.string().max(100) }, 'receipt')
+  ];
+}
+module.exports = { getToolDefs: getToolDefs };

package/lib/mate-creation-mcp-server.js

@@ -13,6 +13,7 @@ function schema() {
     communicationStyle: z.string().describe("JSON array of communication preferences"),
     autonomy: z.string().describe("A concise description of autonomy, boundaries, and escalation behavior"),
     identityMarkdown: z.string().describe("The complete first-person Mate identity in Markdown"),
+    scheduleIntent: z.string().optional().describe("Optional JSON schedule intent to bind only after the Mate is created"),
   };
 }
 
@@ -39,6 +40,7 @@ function getToolDefs(onPropose) {
           communicationStyle: parseArray(args.communicationStyle, "communicationStyle"),
           autonomy: args.autonomy,
           identityMarkdown: args.identityMarkdown,
+          scheduleIntent: args.scheduleIntent || null,
         };
       } catch (error) {
         return Promise.resolve({ content: [{ type: "text", text: "Error: " + error.message }], isError: true });

package/lib/mate-knowledge-canonical-access.js

@@ -0,0 +1,10 @@
+var personal = require('./mcp-session-access');
+var provenance = require('./session-provenance');
+function assertCanonicalKnowledgeQuery(source, project, multiUser, generation, findUser) {
+  var session = source.session, manager = project && project.getSessionManager();
+  if (!session || !manager || manager.sessions.get(session.localId) !== session || Number(session._sdkQueryGeneration || 0) !== generation) throw new Error('This canonical Knowledge query is stale.');
+  if (session.destroying || session.hidden || session.taskStopRequested || session.abortController && session.abortController.signal.aborted || session.spawn || provenance.isWorker(session) || session.homeDebatePlanning || session.debateSetupMode || session._mentionInProgress || session.mateCreationMode || session.sessionVisibility === 'shared' || session._mcpForeignInput || session.delegated || session._delegatedBy || session._pairDelegation) throw new Error('Canonical Knowledge requires a live private owner-authored query.');
+  if (multiUser && (!source.projectOwnerId || session.ownerId !== source.projectOwnerId || !personal.canUsePersonalConnections(session, manager.sessions) || findUser && !findUser(source.projectOwnerId))) throw new Error('Canonical Knowledge owner access changed.');
+  if (!multiUser && (session.ownerId || (session.history || []).some(function (entry) { return entry.type === 'user_message' && entry.from && entry.from !== 'default'; }))) throw new Error('Foreign input cannot authorize canonical Knowledge.');
+}
+module.exports = { assertCanonicalKnowledgeQuery: assertCanonicalKnowledgeQuery };

package/lib/mate-knowledge-mate-bound.js

@@ -0,0 +1,53 @@
+// Ordinary Mate Knowledge bindings. The service supplies live validation and
+// the already-authorized scope; this module only exposes the Mate operations.
+
+function createMateBound(options) {
+  var settings = options || {};
+  var revalidate = settings.revalidate;
+  var initial = settings.initial;
+
+  function ownScope() {
+    return [revalidate().own];
+  }
+  function db(method, args) {
+    var current = revalidate();
+    if (!current.databaseService || typeof current.databaseService[method] !== "function") throw new Error("Knowledge databases are unavailable for this Mate.");
+    return current.databaseService[method](Object.assign({}, args || {}, { actor: current.actor }));
+  }
+  function text(method, args) {
+    var current = revalidate();
+    return settings.textTools[method](current.own, args || {}, current.actor);
+  }
+  return {
+    isClay: false,
+    mateId: initial.own.mateId,
+    scopeId: initial.own.scopeId,
+    listKnowledge: function (args) { return settings.listFor(ownScope(), args || {}, false); },
+    searchKnowledge: function (args) { return settings.searchFor(ownScope(), args || {}, false); },
+    readKnowledge: function (args) { return settings.readFor(ownScope(), args || {}, false); },
+    readKnowledgeDocument: function (args) { return text("read", args); },
+    createKnowledgeDocument: function (args) { return text("create", args); },
+    updateKnowledgeDocument: function (args) { return text("update", args); },
+    listKnowledgeDocumentHistory: function (args) { return text("history", args); },
+    restoreKnowledgeDocument: function (args) { return text("restore", args); },
+    listDatabases: function (args) { return db("list", args); },
+    createDatabase: function (args) { return db("create", args); },
+    readDatabase: function (args) { return db("read", args); },
+    renameDatabase: function (args) { return db("rename", args); },
+    archiveDatabase: function (args) { return db("archive", args); },
+    recoverDatabase: function (args) { return db("recover", args); },
+    updateDatabaseSchema: function (args) { return db("updateSchema", args); },
+    saveTableView: function (args) { return db("saveView", args); },
+    queryDatabase: function (args) { return db("query", args); },
+    createDatabaseRecord: function (args) { return db("createRecord", args); },
+    readDatabaseRecord: function (args) { return db("readRecord", args); },
+    updateDatabaseRecord: function (args) { return db("updateRecord", args); },
+    archiveDatabaseRecord: function (args) { return db("archiveRecord", args); },
+    recoverDatabaseRecord: function (args) { return db("recoverRecord", args); },
+    retryDatabaseSync: function (args) { return db("retryProjection", args); },
+    importDatabaseRecords: function (args) { return db("importRecords", args); },
+    readDatabaseImportProgress: function (args) { return db("readImportProgress", args); },
+  };
+}
+
+module.exports = { createMateBound: createMateBound };