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

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

@@ -9,11 +9,17 @@
 
 var buildShape = require("./session-spawn-mcp-server").buildShape;
 var service = require("./mate-knowledge-service");
+var zod;
+try { zod = require("zod"); } catch (error) { zod = null; }
 
 var MATE_CONTRACT =
   "Your Knowledge is the durable personal and expertise context you own: what you have learned, the material you keep, and your accumulated observations. " +
   "It is yours alone. There are no other Knowledge collections available to you here, and project Logs are a separate, unrelated surface. " +
+  "Use text documents for narrative or multiline Markdown content, and databases for structured records, relationships, filters, and numeric totals. " +
   "Search it when recalling something specific would genuinely change your answer, and read only the records you actually need. " +
+  "Database list and search results are summaries for database discovery, not database row content: discover a database, read its schema, then query_database with stable field ids, typed filters, explicit sorts, bounded pagination, and totals; read individual rows by stable record id. Text search and text-document reads retain their own content and revision semantics. " +
+  "For text edits, use the returned document id and revision, reread after a conflict, and retry with the current revision. " +
+  "Treat errors as failures. A successful revision/id with indexSyncPending or projectionPending means canonical content was saved but indexing is pending: report that exact state, do not claim it is indexed, and do not blindly retry a mutation that could create a duplicate. " +
   "Do not enumerate or restate your Knowledge to the user unasked, and never reproduce whole records as filler.";
 
 var CLAY_CONTRACT =
@@ -56,24 +62,35 @@ var OPERATION = { type: "string", description: "Stable retry id formatted label_
 var FIELD = { type: "object", description: "Field with stable id, name, type, required, and type-specific options or reference target." };
 var FILTER = { type: "object", description: "Validated filter: fieldId, op, and value. Supported ops are eq, neq, contains, gt, gte, lt, lte, empty, not-empty." };
 var SORT = { type: "object", description: "Validated sort with fieldId and asc or desc direction." };
+var FIELD_SCHEMA = zod ? zod.object({ id: zod.string(), name: zod.string(), type: zod.string(), required: zod.boolean().optional(), options: zod.any().optional(), target: zod.string().optional(), targetDatabaseId: zod.string().optional(), archived: zod.boolean().optional() }) : null;
+var FILTER_SCHEMA = zod ? zod.object({ fieldId: zod.string(), op: zod.string(), value: zod.any().optional() }) : null;
+var SORT_SCHEMA = zod ? zod.object({ fieldId: zod.string(), direction: zod.enum(["asc", "desc"]) }) : null;
+var VALUES_SCHEMA = zod ? zod.record(zod.string(), zod.any()) : null;
+var VIEW_SCHEMA = zod ? zod.object({ id: zod.string(), name: zod.string(), columns: zod.array(zod.string()), filters: zod.array(FILTER_SCHEMA || zod.any()).optional(), sorts: zod.array(SORT_SCHEMA || zod.any()).optional(), archived: zod.boolean().optional() }) : null;
+var IMPORT_ROW_SCHEMA = zod ? zod.object({ sourceKey: zod.string(), sourcePayload: zod.any(), values: zod.record(zod.string(), zod.any()) }) : null;
+var IMPORT_ROW = IMPORT_ROW_SCHEMA ? { schema: IMPORT_ROW_SCHEMA, description: "Source row with sourceKey, immutable JSON sourcePayload, and typed values keyed by stable schema field id. Record references use sourceNamespace/sourceKey, including forward references within this batch." } : { type: "object", description: "Source row with sourceKey, immutable JSON sourcePayload, and typed values keyed by stable schema field id. Record references use sourceNamespace/sourceKey, including forward references within this batch." };
+var DOCUMENT_ID = { type: "string", description: "Stable document id returned by a text-document tool." };
+var DOCUMENT_REVISION = { type: "string", description: "Revision returned by the most recent text-document read or mutation; required for updates and restore." };
 
 function databaseTools(bound) {
   return [
-    { name: "list_databases", description: "List canonical Knowledge databases, including archived databases when requested, so the Mate can discover and recover them without relying on summary projection.", inputSchema: buildShape({ archived: { type: "boolean" } }, []), handler: handler(bound, "listDatabases") },
-    { name: "create_database", description: "Create a first-class database in this Mate's Knowledge. Defaults to one required title field and a Table view.", inputSchema: buildShape({ name: { type: "string" }, schema: { type: "array", items: FIELD }, operationId: OPERATION }, ["name", "operationId"]), handler: handler(bound, "createDatabase") },
-    { name: "read_database", description: "Read one Knowledge database's current schema, views, revision, and record count.", inputSchema: buildShape({ databaseId: ID, includeArchived: { type: "boolean" } }, ["databaseId"]), handler: handler(bound, "readDatabase") },
+    { name: "list_databases", description: "Discover canonical Knowledge databases, including archived databases when requested. Results are database summaries only, not row content; read a chosen database before querying it.", inputSchema: buildShape({ archived: { type: "boolean" } }, []), handler: handler(bound, "listDatabases") },
+    { name: "create_database", description: "Create a first-class structured database in this Mate's Knowledge. Define typed fields for values, relationships, and numeric totals; use text documents for narrative or multiline material.", inputSchema: buildShape({ name: { type: "string" }, schema: FIELD_SCHEMA ? { schema: zod.array(FIELD_SCHEMA), description: "Typed field descriptors." } : { type: "array", items: FIELD }, operationId: OPERATION }, ["name", "operationId"]), handler: handler(bound, "createDatabase") },
+    { name: "read_database", description: "Read one discovered Knowledge database by stable database id to obtain its current schema, views, revision, and record count before querying rows.", inputSchema: buildShape({ databaseId: ID, includeArchived: { type: "boolean" } }, ["databaseId"]), handler: handler(bound, "readDatabase") },
     { name: "rename_database", description: "Rename a Knowledge database with optimistic revision checking.", inputSchema: buildShape({ databaseId: ID, name: { type: "string" }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "name", "expectedRevision", "operationId"]), handler: handler(bound, "renameDatabase") },
     { name: "archive_database", description: "Recoverably archive a Knowledge database.", inputSchema: buildShape({ databaseId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "expectedRevision", "operationId"]), handler: handler(bound, "archiveDatabase") },
     { name: "recover_database", description: "Recover an archived Knowledge database.", inputSchema: buildShape({ databaseId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "expectedRevision", "operationId"]), handler: handler(bound, "recoverDatabase") },
-    { name: "update_database_schema", description: "Replace the schema using stable field ids. Exactly one active title field is required; populated fields cannot be removed or change type and should be archived instead.", inputSchema: buildShape({ databaseId: ID, schema: { type: "array", items: FIELD }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "schema", "expectedRevision", "operationId"]), handler: handler(bound, "updateDatabaseSchema") },
-    { name: "save_table_view", description: "Create or revise a persisted Table view with selected columns, validated filters, and deterministic sorts.", inputSchema: buildShape({ databaseId: ID, view: { type: "object", description: "View with stable id, name, columns, filters, and sorts." }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "view", "expectedRevision", "operationId"]), handler: handler(bound, "saveTableView") },
-    { name: "query_database", description: "Query a bounded deterministic page of records using a saved view or explicit validated filters and sorts. Returns count and numeric sums.", inputSchema: buildShape({ databaseId: ID, viewId: ID, filters: { type: "array", items: FILTER }, sorts: { type: "array", items: SORT }, cursor: { type: "string" }, limit: { type: "number" }, archived: { type: "boolean" } }, ["databaseId"]), handler: handler(bound, "queryDatabase") },
-    { name: "create_database_record", description: "Create a typed record. Values are keyed by stable field id; unknown fields and unsafe keys are rejected.", inputSchema: buildShape({ databaseId: ID, values: { type: "object" }, expectedDatabaseRevision: REVISION, operationId: OPERATION }, ["databaseId", "values", "expectedDatabaseRevision", "operationId"]), handler: handler(bound, "createDatabaseRecord") },
+    { name: "update_database_schema", description: "Replace the schema using stable field ids. Exactly one active title field is required; populated fields cannot be removed or change type and should be archived instead.", inputSchema: buildShape({ databaseId: ID, schema: FIELD_SCHEMA ? { schema: zod.array(FIELD_SCHEMA), description: "Complete typed field descriptor array." } : { type: "array", items: FIELD }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "schema", "expectedRevision", "operationId"]), handler: handler(bound, "updateDatabaseSchema") },
+    { name: "save_table_view", description: "Create or revise a persisted Table view with selected columns, validated filters, and deterministic sorts.", inputSchema: buildShape({ databaseId: ID, view: VIEW_SCHEMA ? { schema: VIEW_SCHEMA, description: "View with stable id, name, columns, filters, and sorts." } : { type: "object", description: "View with stable id, name, columns, filters, and sorts." }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "view", "expectedRevision", "operationId"]), handler: handler(bound, "saveTableView") },
+    { name: "query_database", description: "Query a bounded deterministic page using stable field ids, typed validated filters, explicit sorts, and a cursor. Returns only the requested rows plus count and numeric sums for the same filter scope; do not infer totals from one page.", inputSchema: buildShape({ databaseId: ID, viewId: ID, filters: FILTER_SCHEMA ? { schema: zod.array(FILTER_SCHEMA) } : { type: "array", items: FILTER }, sorts: SORT_SCHEMA ? { schema: zod.array(SORT_SCHEMA) } : { type: "array", items: SORT }, cursor: { type: "string" }, limit: { type: "number" }, archived: { type: "boolean" } }, ["databaseId"]), handler: handler(bound, "queryDatabase") },
+    { name: "create_database_record", description: "Create a typed record. Values are keyed by stable field id; unknown fields and unsafe keys are rejected.", inputSchema: buildShape({ databaseId: ID, values: VALUES_SCHEMA ? { schema: VALUES_SCHEMA } : { type: "object" }, expectedDatabaseRevision: REVISION, operationId: OPERATION }, ["databaseId", "values", "expectedDatabaseRevision", "operationId"]), handler: handler(bound, "createDatabaseRecord") },
     { name: "read_database_record", description: "Read one record with its values, revision, attribution, archive state, and bounded history.", inputSchema: buildShape({ databaseId: ID, recordId: ID }, ["databaseId", "recordId"]), handler: handler(bound, "readDatabaseRecord") },
-    { name: "update_database_record", description: "Update selected typed values using the record revision. Edits to other fields made since a prior save are not overwritten.", inputSchema: buildShape({ databaseId: ID, recordId: ID, values: { type: "object" }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "values", "expectedRevision", "operationId"]), handler: handler(bound, "updateDatabaseRecord") },
+    { name: "update_database_record", description: "Update selected typed values using the record revision. Edits to other fields made since a prior save are not overwritten.", inputSchema: buildShape({ databaseId: ID, recordId: ID, values: VALUES_SCHEMA ? { schema: VALUES_SCHEMA } : { type: "object" }, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "values", "expectedRevision", "operationId"]), handler: handler(bound, "updateDatabaseRecord") },
     { name: "archive_database_record", description: "Recoverably archive one record using its current revision.", inputSchema: buildShape({ databaseId: ID, recordId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "expectedRevision", "operationId"]), handler: handler(bound, "archiveDatabaseRecord") },
     { name: "recover_database_record", description: "Recover one archived record using its current revision.", inputSchema: buildShape({ databaseId: ID, recordId: ID, expectedRevision: REVISION, operationId: OPERATION }, ["databaseId", "recordId", "expectedRevision", "operationId"]), handler: handler(bound, "recoverDatabaseRecord") },
     { name: "retry_database_sync", description: "Retry the shared append-only Knowledge summary projection after a canonical database mutation reported projectionPending.", inputSchema: buildShape({ databaseId: ID }, ["databaseId"]), handler: handler(bound, "retryDatabaseSync") },
+    { name: "import_database_records", description: "Import up to 100 source rows (256 KiB per batch) into a discovered database using immutable source identities and typed values. Use sourceNamespace/sourceKey references for same-batch or already-imported cross-database links; replay the exact operation and payload after uncertainty, and reread the current database revision before a stale retry.", inputSchema: buildShape({ databaseId: ID, expectedDatabaseRevision: REVISION, operationId: OPERATION, sourceNamespace: { type: "string", description: "Stable source namespace for this import mapping." }, rows: IMPORT_ROW_SCHEMA ? { schema: zod.array(IMPORT_ROW_SCHEMA), description: "At most 100 source rows and 256 KiB of serialized row JSON." } : { type: "array", description: "At most 100 source rows and 256 KiB of serialized row JSON.", items: IMPORT_ROW } }, ["databaseId", "expectedDatabaseRevision", "operationId", "sourceNamespace", "rows"]), handler: handler(bound, "importDatabaseRecords") },
+    { name: "read_database_import_progress", description: "Read bounded source-to-native record mappings by database id and source namespace. Use returned stable record ids for later corrections; this does not read arbitrary filesystem paths or caller-selected owners.", inputSchema: buildShape({ databaseId: ID, sourceNamespace: { type: "string" }, offset: { type: "number" }, limit: { type: "number", description: "Mapping page size from 1 to 100." } }, ["databaseId", "sourceNamespace"]), handler: handler(bound, "readDatabaseImportProgress") },
   ].map(function (tool) { tool.description = MATE_CONTRACT + " " + tool.description; return tool; });
 }
 
@@ -110,6 +127,36 @@ function mateTools(bound) {
       }, ["ref"]),
       handler: handler(bound, "readKnowledge"),
     },
+    {
+      name: "read_knowledge_document",
+      description: MATE_CONTRACT + " Read the complete current Markdown document by its relative path or stable document id, including its current revision.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, documentId: DOCUMENT_ID }, []),
+      handler: handler(bound, "readKnowledgeDocument"),
+    },
+    {
+      name: "create_knowledge_document",
+      description: MATE_CONTRACT + " Create a new Markdown document at a safe relative path. Use this for narrative or multiline content; it is synchronized into Knowledge search after the canonical save.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, content: { type: "string", description: "Complete Markdown document content." } }, ["name", "content"]),
+      handler: handler(bound, "createKnowledgeDocument"),
+    },
+    {
+      name: "update_knowledge_document",
+      description: MATE_CONTRACT + " Update an existing Markdown document by relative path or stable document id. The current revision is mandatory, and stale writes are rejected.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, documentId: DOCUMENT_ID, content: { type: "string", description: "Complete replacement Markdown document content." }, expectedRevision: DOCUMENT_REVISION }, ["content", "expectedRevision"]),
+      handler: handler(bound, "updateKnowledgeDocument"),
+    },
+    {
+      name: "list_knowledge_document_history",
+      description: MATE_CONTRACT + " List recoverable revisions for one Markdown document by relative path or stable document id.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, documentId: DOCUMENT_ID }, []),
+      handler: handler(bound, "listKnowledgeDocumentHistory"),
+    },
+    {
+      name: "restore_knowledge_document",
+      description: MATE_CONTRACT + " Restore a selected historical Markdown revision. The current revision is mandatory so a concurrent edit cannot be overwritten.",
+      inputSchema: buildShape({ name: { type: "string", description: "Relative Markdown path under this Mate's Knowledge directory." }, documentId: DOCUMENT_ID, version: { type: "string", description: "Version returned by list_knowledge_document_history." }, expectedRevision: DOCUMENT_REVISION }, ["version", "expectedRevision"]),
+      handler: handler(bound, "restoreKnowledgeDocument"),
+    },
   ].concat(databaseTools(bound));
 }
 

package/lib/mate-knowledge-service.js

@@ -15,6 +15,8 @@ var builtinMates = require("./builtin-mates");
 var knowledgeImport = require("./knowledge-import");
 var knowledgeSearch = require("./knowledge-search");
 var mateSync = require("./mate-knowledge-sync");
+var textToolsModule = require("./mate-knowledge-text-tools");
+var mateBoundModule = require("./mate-knowledge-mate-bound");
 
 var MAX_PAGE = 50;
 var DEFAULT_PAGE = 20;
@@ -97,6 +99,7 @@ function attachMateKnowledgeService(ctx) {
   var listMates = context.listMates || function () { return []; };
   var baseDir = context.baseDir;
   var importerCache = new Map();
+  var textTools = textToolsModule.createMateKnowledgeTextTools({ baseDir: baseDir });
 
   function importerForScope(scopeId) {
     if (context.openImporter) return context.openImporter(scopeId);
@@ -379,10 +382,12 @@ function attachMateKnowledgeService(ctx) {
     if (source.session) {
       var manager = project.getSessionManager ? project.getSessionManager() : project.sm;
       if (!manager || !manager.sessions || manager.sessions.get(source.session.localId) !== source.session) return null;
+      if (source.projectOwnerId && source.session.ownerId && source.session.ownerId !== source.projectOwnerId) return null;
+      if (isMultiUser() && (!source.projectOwnerId || source.session.ownerId !== source.projectOwnerId)) return null;
     }
     if (typeof resolveMate !== "function") return null;
     var mate = resolveMate(source.projectOwnerId || null, source.mateId);
-    if (!mate || mate.id !== source.mateId) return null;
+    if (!mate || mate.lifecycleDeletion || mate.id !== source.mateId) return null;
     if (isMultiUser()) {
       if (!source.projectOwnerId) return null;
       if (mate.createdBy !== source.projectOwnerId) return null;
@@ -393,7 +398,7 @@ function attachMateKnowledgeService(ctx) {
 
     var def = mate.builtinKey ? builtinMates.getBuiltinByKey(mate.builtinKey) : null;
     var isClay = !!(mate.builtinKey === "clay" && def && def.hostAgent === true);
-    return { own: own, isClay: isClay, ownerId: source.projectOwnerId || null,
+    return { project: project, own: own, isClay: isClay, ownerId: source.projectOwnerId || null,
       databaseService: typeof project.getKnowledgeDbService === "function" ? project.getKnowledgeDbService() : null,
       actor: { type: "user", userId: source.session && source.session.ownerId || source.projectOwnerId || null, displayName: null } };
   }
@@ -405,12 +410,14 @@ function attachMateKnowledgeService(ctx) {
   // to work through a handler that was created while it was still live.
   function bind(source) {
     var initial = resolve(source);
+    var generation = Number(source && source.session && source.session._sdkQueryGeneration || 0);
     if (!initial) return null;
 
     function revalidate() {
       var current = resolve(source);
+      if (initial.isClay) require("./mate-knowledge-canonical-access").assertCanonicalKnowledgeQuery(source, getProjects().get(source.projectSlug), isMultiUser(), generation, context.findUser);
       if (!current) throw new Error("This Knowledge binding is no longer valid for the current session.");
-      if (current.isClay !== initial.isClay || current.own.scopeId !== initial.own.scopeId || current.databaseService !== initial.databaseService) {
+      if (current.project !== initial.project || current.isClay !== initial.isClay || current.own.scopeId !== initial.own.scopeId || current.databaseService !== initial.databaseService) {
         throw new Error("This Knowledge binding is no longer valid for the current session.");
       }
       return current;
@@ -422,36 +429,10 @@ function attachMateKnowledgeService(ctx) {
   // An ordinary Mate's own scope, and nothing else. There is no argument on
   // any tool that could widen it.
   function createMateBound(revalidate, 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 }));
-    }
-    return {
-      isClay: false,
-      mateId: initial.own.mateId,
-      scopeId: initial.own.scopeId,
-      listKnowledge: function (args) { return listFor(ownScope(), args || {}, false); },
-      searchKnowledge: function (args) { return searchFor(ownScope(), args || {}, false); },
-      readKnowledge: function (args) { return readFor(ownScope(), args || {}, false); },
-      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); },
-    };
+    return mateBoundModule.createMateBound({
+      revalidate: revalidate, initial: initial, textTools: textTools,
+      listFor: listFor, searchFor: searchFor, readFor: readFor,
+    });
   }
 
   // Every Mate belonging to the same user, resolved fresh on each call so a
@@ -467,7 +448,8 @@ function attachMateKnowledgeService(ctx) {
       for (var i = 0; i < listed.length; i++) {
         var entry = listed[i];
         if (!entry || !entry.id || !entry.dir) continue;
-        if (isMultiUser() && ownerId && entry.createdBy && entry.createdBy !== ownerId) continue;
+        var registered = resolveMate(ownerId, entry.id);
+        if (!registered || registered.lifecycleDeletion || isMultiUser() && registered.createdBy !== ownerId) continue;
         var scope = scopeForMate(entry.dir, entry.id, entry.name || null);
         if (!scope) continue;
         out.push(scope);

package/lib/mate-knowledge-text-tools.js

@@ -0,0 +1,106 @@
+// Session-bound text Knowledge mutations for one authorized Mate.
+//
+// This module deliberately uses the existing portable file store and
+// write-through synchronizer. It never accepts a Mate, owner, or filesystem
+// root from a tool caller; the caller supplies only a relative document name
+// or the stable identity returned by the store.
+
+var crypto = require("crypto");
+var path = require("path");
+var knowledgeFiles = require("./knowledge-file-store");
+var mateSync = require("./mate-knowledge-sync");
+
+function metadataRoot(baseDir, mateDir) {
+  var key = crypto.createHash("sha256").update(path.resolve(mateDir)).digest("hex").slice(0, 24);
+  return path.join(baseDir || path.join(mateDir, ".clay"), "knowledge-documents", key);
+}
+
+function failedSync(summary) {
+  if (!summary) return { indexSyncPending: true, syncError: "Knowledge index synchronization returned no result." };
+  if (summary.failed === 0) return { indexSyncPending: false, syncError: null };
+  var error = summary.errors && summary.errors[0];
+  return { indexSyncPending: true, syncError: error && error.message || "Knowledge index synchronization failed." };
+}
+
+function createMateKnowledgeTextTools(options) {
+  var settings = options || {};
+  var stores = new Map();
+
+  function storeFor(mate) {
+    if (!mate || typeof mate.mateDir !== "string") throw new Error("Knowledge text tools require an authorized Mate.");
+    var directory = path.resolve(mate.mateDir);
+    if (!stores.has(directory)) stores.set(directory, knowledgeFiles.createKnowledgeFileStore(directory, { metaDir: metadataRoot(settings.baseDir, directory) }));
+    return stores.get(directory);
+  }
+
+  function find(store, input) {
+    var args = input || {};
+    var hasName = typeof args.name === "string" && args.name.length > 0;
+    var hasId = typeof args.documentId === "string" && args.documentId.length > 0;
+    if (!hasName && !hasId) throw new Error("A document name or stable document id is required.");
+    var item = null;
+    if (hasId) item = store.list().filter(function (entry) { return entry.id === args.documentId; })[0] || null;
+    if (hasId && !item) throw Object.assign(new Error("Knowledge document not found."), { code: "ENOENT" });
+    if (hasName) {
+      var byName = store.read(args.name);
+      if (item && item.id !== byName.id) throw new Error("The document name and id identify different documents.");
+      item = byName;
+    }
+    if (!item) throw Object.assign(new Error("Knowledge document not found."), { code: "ENOENT" });
+    if (hasId && !hasName) item = store.read(item.name);
+    if (item.itemType !== "text") throw Object.assign(new Error("Only Markdown Knowledge documents are writable through these tools."), { code: "READ_ONLY" });
+    return item;
+  }
+
+  function sync(mate, name, actor) {
+    try {
+      var summary = mateSync.syncMateSource({ mateDir: mate.mateDir, fileName: name, baseDir: settings.baseDir, actor: actor });
+      return failedSync(summary);
+    } catch (error) {
+      return { indexSyncPending: true, syncError: error.message || "Knowledge index synchronization failed." };
+    }
+  }
+
+  function read(mate, args) {
+    var item = find(storeFor(mate), args);
+    return { documentId: item.id, name: item.name, content: item.content, revision: item.revision };
+  }
+
+  function create(mate, args, actor) {
+    var input = args || {};
+    if (typeof input.name !== "string" || !input.name) throw new Error("A document name is required to create a Knowledge document.");
+    if (typeof input.content !== "string") throw new Error("Document content is required.");
+    var store = storeFor(mate);
+    var saved = store.save(input.name, input.content, null);
+    return Object.assign({ documentId: saved.id, name: saved.name, revision: saved.revision }, sync(mate, saved.name, actor));
+  }
+
+  function update(mate, args, actor) {
+    var input = args || {};
+    if (typeof input.expectedRevision !== "string" || !input.expectedRevision) throw Object.assign(new Error("A current document revision is required for updates."), { code: "STALE" });
+    if (typeof input.content !== "string") throw new Error("Document content is required.");
+    var store = storeFor(mate);
+    var current = find(store, input);
+    var saved = store.save(current.name, input.content, input.expectedRevision);
+    return Object.assign({ documentId: saved.id, name: saved.name, revision: saved.revision }, sync(mate, saved.name, actor));
+  }
+
+  function history(mate, args) {
+    var current = find(storeFor(mate), args);
+    return { documentId: current.id, name: current.name, versions: storeFor(mate).history(current.id) };
+  }
+
+  function restore(mate, args, actor) {
+    var input = args || {};
+    if (typeof input.expectedRevision !== "string" || !input.expectedRevision) throw Object.assign(new Error("A current document revision is required for restore."), { code: "STALE" });
+    if (typeof input.version !== "string" || !input.version) throw new Error("A history version is required.");
+    var store = storeFor(mate);
+    var current = find(store, input);
+    var restored = store.restore(current.id, input.version, current.name, input.expectedRevision);
+    return Object.assign({ documentId: restored.id, name: restored.name, revision: restored.revision }, sync(mate, restored.name, actor));
+  }
+
+  return { read: read, create: create, update: update, history: history, restore: restore };
+}
+
+module.exports = { createMateKnowledgeTextTools: createMateKnowledgeTextTools };

package/lib/mate-lifecycle-service.js

@@ -0,0 +1,94 @@
+var crypto = require('crypto');
+function attachMateLifecycleService(ctx) {
+  var busy = new Set();
+  function owner(userId) {
+    if (ctx.users.isMultiUser() && (!userId || !ctx.users.findUserById(userId))) throw new Error('Mate owner is unavailable.');
+    return ctx.mates.buildMateCtx(ctx.users.isMultiUser() ? userId : null);
+  }
+  function read(userId, id) {
+    var mate = ctx.mates.getMate(owner(userId), id);
+    if (!mate || ctx.users.isMultiUser() && mate.createdBy !== userId) throw new Error('Mate is unavailable or belongs to another owner.');
+    return mate;
+  }
+  function validateReceipt(userId, id, allowMissing) {
+    var mate = ctx.mates.getMate(owner(userId), id);
+    if (!mate && allowMissing) return;
+    if (!mate || ctx.users.isMultiUser() && mate.createdBy !== userId) throw new Error('Mate receipt access changed.');
+  }
+  function list(userId) {
+    return ctx.mates.getAllMates(owner(userId)).filter(function (mate) { return !ctx.users.isMultiUser() || mate.createdBy === userId; });
+  }
+  function broadcast(userId, message, ws) {
+    var seen = new Set();
+    function send(socket) {
+      if (!socket || seen.has(socket) || socket.readyState !== 1) return;
+      if (ctx.users.isMultiUser() && (!socket._clayUser || socket._clayUser.id !== userId)) return;
+      seen.add(socket); socket.send(JSON.stringify(message));
+    }
+    send(ws);
+    ctx.projects.forEach(function (project) { project.forEachClient(send); });
+  }
+  function update(userId, id, updates, ws, requestId) {
+    var mate = read(userId, id);
+    if (Object.prototype.hasOwnProperty.call(updates, 'lifecycleDeletion')) throw new Error('Mate deletion state is server-managed.');
+    if (busy.has(id) || mate.lifecycleDeletion) throw new Error('Mate deletion is pending.');
+    var updated = ctx.mates.updateMate(owner(userId), id, updates);
+    if (!updated || updated.error) throw new Error(updated && updated.error || 'Mate not found');
+    try {
+      broadcast(userId, { type: 'mate_updated', mate: updated, requestId: requestId }, ws);
+      if (ctx.refresh) ctx.refresh(owner(userId));
+    } catch (error) { error.productControlResult = { persisted: true, retrySafe: false }; throw error; }
+    return updated;
+  }
+  function idle(project) {
+    if (!project) return;
+    if (project.inspectMateLifecycleRuntime && project.inspectMateLifecycleRuntime().some(function (t) { return !t.exited; })) throw new Error('Close the Mate terminals before deletion.');
+    project.getSessionManager().sessions.forEach(function (session) {
+      if (session.isProcessing || session._queryStarting || session.queryInstance || session.worker || session.terminalId || session.runtimeTerminalId || Object.keys(session._mentionSessions || {}).length) throw new Error('Wait for this Mate runtime to become idle before deletion.');
+    });
+  }
+  async function closeRuntime(slug, validate) {
+    var timer;
+    try {
+      return await Promise.race([Promise.resolve().then(function () { if (validate) validate(true); return ctx.removeProject(slug, true); }), new Promise(function (resolve, reject) {
+        timer = setTimeout(function () { reject(new Error('Mate runtime cleanup timed out; deletion remains pending.')); }, 10000);
+      })]);
+    } finally { clearTimeout(timer); }
+  }
+  async function remove(userId, id, validate, ws) {
+    var mate = read(userId, id), slug = 'mate-' + id, project = ctx.projects.get(slug);
+    if (mate.primary || mate.builtinKey === 'clay') throw new Error('Canonical Clay and primary Mates cannot be deleted.');
+    if (busy.has(id)) throw new Error('Another Mate lifecycle operation is applying.');
+    idle(project);
+    if (validate) validate();
+    busy.add(id);
+    var persisted = false, runtimeClosed = false;
+    try {
+      // Retain an owner-visible tombstone until every required cleanup is acknowledged.
+      if (!mate.lifecycleDeletion) mate = ctx.mates.updateMate(owner(userId), id, { lifecycleDeletion: { id: crypto.randomUUID(), runtimeRequired: !!project, runtimeClosed: !project } });
+      if (!mate || mate.error) throw new Error('Could not persist the pending Mate deletion.');
+      persisted = true;
+      if (mate.builtinKey) ctx.users.addDeletedBuiltinKey(userId, mate.builtinKey);
+      if (!project && mate.lifecycleDeletion.runtimeRequired && !mate.lifecycleDeletion.runtimeClosed) throw new Error('Runtime cleanup proof is unavailable; retain the pending deletion for operator recovery.');
+      if (project && await closeRuntime(slug, validate) !== true) throw new Error('Mate runtime cleanup was not acknowledged.');
+      runtimeClosed = true;
+      mate = ctx.mates.updateMate(owner(userId), id, { lifecycleDeletion: Object.assign({}, mate.lifecycleDeletion, { runtimeClosed: true }) });
+      if (!mate || mate.error) throw new Error('Runtime closure proof could not be saved.');
+      if (validate) validate(true);
+      var current = read(userId, id);
+      if (!current.lifecycleDeletion || current.lifecycleDeletion.id !== mate.lifecycleDeletion.id) throw new Error('Mate deletion identity changed.');
+      var result = ctx.mates.deleteMate(owner(userId), id, { strictCleanup: true });
+      if (!result || !result.ok) throw new Error(result && result.error || 'Mate deletion was not persisted.');
+      var definitions = require('./builtin-mates');
+      var available = ctx.mates.getMissingBuiltinKeys(owner(userId)).map(function (key) { var def = definitions.getBuiltinByKey(key); return def && { key: def.key, displayName: def.displayName, bio: def.bio, avatarCustom: def.avatarCustom || '', avatarStyle: def.avatarStyle || 'imprint', avatarColor: def.avatarColor || '' }; }).filter(Boolean);
+      broadcast(userId, { type: 'mate_deleted', mateId: id, availableBuiltins: available }, ws);
+      if (ctx.refresh) ctx.refresh(owner(userId));
+      return { persisted: true, runtimeClosed: true, directoryRemoved: true };
+    } catch (error) {
+      error.productControlResult = { persisted: persisted, runtimeClosed: runtimeClosed, deletionPending: !!ctx.mates.getMate(owner(userId), id), retrySafe: false };
+      throw error;
+    } finally { busy.delete(id); }
+  }
+  return { read: read, validateReceipt: validateReceipt, list: list, update: update, remove: remove };
+}
+module.exports = { attachMateLifecycleService: attachMateLifecycleService };

package/lib/mate-message-delivery.js

@@ -0,0 +1,43 @@
+// Shared Home/Mate delivery. Canonical callers supply an exact live guard and
+// persist delegated provenance before any provider input is admitted.
+async function deliver(ctx, session, text, options) {
+  options = options || {};
+  var guarded = typeof options.revalidate === 'function';
+  function current() {
+    if (ctx.sm.sessions.get(session.localId) !== session) throw new Error('The conversation was deleted or replaced.');
+    if (guarded) {
+      options.revalidate();
+      if (session.taskStopRequested || session._pendingMessageDrainPaused || session._responseRecoveryStopPending || session.abortController && session.abortController.signal.aborted) throw new Error('The conversation is stopped; explicit owner resumption is required.');
+    }
+    return true;
+  }
+  if (guarded) current.exactProductDelivery = true;
+  current();
+  var event = options.event || { type: 'user_message', text: text };
+  if (guarded) {
+    if (ctx.sm.saveSessionFile(session) !== true) throw new Error('The conversation could not be saved; no provider delivery was attempted.');
+    if (ctx.sm.sendAndRecordDurably(session, event) !== true) throw new Error('The delegated message could not be saved; no provider delivery was attempted.');
+    session._mcpForeignInput = true;
+  } else ctx.sm.sendAndRecord(session, event);
+  var attempted = false;
+  try {
+    current();
+    var active = !!session.isProcessing;
+    session.isProcessing = true;
+    if (!active) session.sentToolResults = {};
+    if (options.onRecorded) options.onRecorded(session);
+    var queryText = options.queryText || text;
+    attempted = true;
+    if (session.queryInstance || session.worker && session.messageQueue === 'worker' || active) {
+      if (ctx.sdk.pushMessage(session, queryText, null) === true) return { status: 'queued', persisted: true, delivery: 'accepted', completion: 'pending' };
+      if (active) return { status: 'failed', persisted: true, delivery: 'rejected', retrySafe: false, error: 'The active provider did not accept the message. Inspect before another request.' };
+    }
+    var accepted = await ctx.sdk.startQuery(session, queryText, null, ctx.linuxUser || null, guarded ? current : undefined);
+    return { status: accepted === true ? 'started' : 'failed', persisted: true, delivery: accepted === true ? 'accepted' : 'not_confirmed', completion: 'pending', retrySafe: false };
+  } catch (error) {
+    if (!attempted) session.isProcessing = false;
+    error.productControlResult = { persisted: true, delivery: attempted ? 'unknown' : 'not_attempted', retrySafe: false };
+    throw error;
+  }
+}
+module.exports = { deliver: deliver };

package/lib/mate-ready-creation.js

@@ -4,6 +4,7 @@ var resolveMateIdentityFile = require('./mate-identity-file').resolveMateIdentit
 
 var fs = require("fs");
 var path = require("path");
+var scheduleInput = require("./mate-schedule-input");
 
 function cleanLine(value, maxLength, field) {
   if (typeof value !== "string") throw new Error(field + " is required.");
@@ -27,6 +28,11 @@ function normalize(definition) {
   var identity = typeof definition.identityMarkdown === "string" ? definition.identityMarkdown.replace(/\u0000/g, "").trim() : "";
   if (identity.length < 200) throw new Error("The Mate identity is incomplete.");
   if (identity.length > 30000) throw new Error("The Mate identity is too long.");
+  var scheduleIntent = definition.scheduleIntent || null;
+  if (scheduleIntent) {
+    var scheduleChecked = scheduleInput.normalize(scheduleIntent);
+    scheduleIntent = { message: scheduleChecked.message, scheduleRule: scheduleChecked.rule };
+  }
   return {
     name: cleanLine(definition.name, 80, "Mate name"),
     bio: cleanLine(definition.bio, 280, "Mate bio"),
@@ -37,6 +43,7 @@ function normalize(definition) {
     identityMarkdown: identity,
     vendor: cleanLine(definition.vendor || "claude", 40, "Vendor"),
     model: cleanLine(definition.model, 240, "Mate model"),
+    scheduleIntent: scheduleIntent,
   };
 }
 
@@ -54,6 +61,7 @@ function createReadyMate(mates, mateCtx, definition) {
       vendor: ready.vendor,
       model: ready.model,
       autonomy: ready.autonomy,
+      scheduleIntent: ready.scheduleIntent,
     });
     var mateDir = mates.getMateDir(mateCtx, mate.id);
     var identityPath = resolveMateIdentityFile(mateDir);
@@ -80,7 +88,7 @@ function createReadyMate(mates, mateCtx, definition) {
       vendor: ready.vendor,
       model: ready.model,
       profile: Object.assign({}, mate.profile || {}, { displayName: ready.name, bio: ready.bio }),
-      seedData: Object.assign({}, mate.seedData || {}, { relationship: ready.relationship, activity: ready.activities, communicationStyle: ready.communicationStyle, autonomy: ready.autonomy }),
+      seedData: Object.assign({}, mate.seedData || {}, { relationship: ready.relationship, activity: ready.activities, communicationStyle: ready.communicationStyle, autonomy: ready.autonomy, scheduleIntent: ready.scheduleIntent }),
     });
     mates.backupIdentity(mateDir, ready.identityMarkdown);
     mates.logIdentityChange(mateDir, "clay_interview", ready.identityMarkdown, "");

package/lib/mate-schedule-input.js

@@ -0,0 +1,29 @@
+var rules = require('./schedule-rule');
+function normalize(input, previous) {
+  input = input || {};
+  var message = input.message === undefined && previous ? previous.message : input.message;
+  if (typeof message !== 'string' || !message.trim() || message.length > 1200 || message.indexOf('\u0000') >= 0) throw new Error('A message of 1 to 1200 characters is required.');
+  var source = input.scheduleRule || (previous && previous.rule) || {
+    version: 1, timezone: 'server-local', anchorDate: input.date, time: input.time, recurrence: null,
+  };
+  source = Object.assign({}, source);
+  if (input.date !== undefined) source.anchorDate = input.date;
+  if (input.time !== undefined) source.time = input.time;
+  var checked = rules.validateScheduleRule(source);
+  if (!checked.ok) throw new Error(checked.error);
+  return { message: message.trim(), rule: checked.value };
+}
+function timezone() { return Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC'; }
+function review(value) {
+  var rule = value.rule;
+  var repeat = rule.recurrence ? 'Every ' + rule.recurrence.every + ' ' + rule.recurrence.unit +
+    (rule.recurrence.weekdays ? ' on ' + rule.recurrence.weekdays.map(function (day) { return ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'][day]; }).join(', ') : '') : 'Once';
+  if (rule.recurrenceEnd) repeat += rule.recurrenceEnd.type === 'after' ? ', ' + rule.recurrenceEnd.count + ' deliveries' : ', through ' + rule.recurrenceEnd.date;
+  if (rule.interval) {
+    var ending = rule.interval.end;
+    repeat += '; every ' + rule.interval.every + ' ' + rule.interval.unit;
+    repeat += !ending ? ', until end of day' : ending.type === 'after' ? ', ' + ending.count + ' deliveries per day' : ', until ' + ending.time;
+  }
+  return value.message + '\n' + rule.anchorDate + ' at ' + rule.time + ' (' + timezone() + ')\n' + repeat;
+}
+module.exports = { normalize: normalize, timezone: timezone, review: review };