clay-server 3.8.1 → 4.0.0-beta.10

package/lib/project-logs-versioning.js

@@ -0,0 +1,128 @@
+// Comment review and revision control for Project Logs.
+//
+// Split from project-logs-store.js so the store stays inside the module size
+// limit. Everything here is Project Driver territory: reviewing a user comment
+// and moving the canonical record between revisions. The authorization layer
+// decides who may call these; this module only guarantees the record shape.
+
+var logsSchema = require("./project-logs-schema");
+var logsSnapshot = require("./project-logs-snapshot");
+var logsComments = require("./project-logs-comments");
+var recordStore = require("./knowledge-record-store");
+
+function attachVersioning(ctx) {
+  var read = ctx.read;
+  var requireLive = ctx.requireLive;
+  var findChain = ctx.findChain;
+  var appendRevision = ctx.appendRevision;
+  var nextSnapshot = ctx.nextSnapshot;
+  var cleanText = ctx.cleanText;
+  var MAX_LINKS = ctx.maxLinks;
+  var MAX_RESPONSE_CHARS = ctx.maxResponseChars;
+  var scopeId = ctx.scopeId;
+  var store = ctx.store;
+  var normalizeAuthor = ctx.normalizeAuthor;
+
+  // Review a user comment. `clarify` and `decline` resolve the comment and
+  // create no canonical revision. `incorporate` appends exactly one record that
+  // both resolves the comment and carries the new canonical snapshot, so the
+  // two can never drift apart.
+  function review(ref, input, author) {
+    var located = requireLive(ref);
+    var data = input || {};
+    if (!logsComments.isAction(data.action)) {
+      throw new Error("A review action is required: " + logsComments.ACTIONS.join(", "));
+    }
+    var entry = read(ref, false);
+    var target = null;
+    for (var i = 0; i < entry.comments.length; i++) {
+      if (entry.comments[i].id === data.commentId) { target = entry.comments[i]; break; }
+    }
+    if (!target) throw new Error("Comment not found on this entry.");
+    if (target.review) throw new Error("That comment has already been reviewed.");
+
+    var response = cleanText(data.response || "", MAX_RESPONSE_CHARS);
+    if (data.action !== "incorporate" && !response) {
+      throw new Error("A " + data.action + " review requires a response explaining the decision.");
+    }
+
+    if (data.action !== "incorporate") {
+      store.append({
+        id: recordStore.newRecordId(),
+        rootId: located.rootId,
+        op: "review",
+        scope: scopeId,
+        action: data.action,
+        commentId: data.commentId,
+        response: response,
+        author: normalizeAuthor(author),
+        at: Date.now(),
+      });
+      return read(ref, false);
+    }
+
+    var validated = logsSchema.validateRevision(data);
+    var current = logsSnapshot.cloneSnapshot(entry);
+    var snapshot = nextSnapshot(current, validated, data);
+    if (logsSnapshot.sameSnapshot(current, snapshot)) {
+      throw new Error("Incorporating a comment requires an actual canonical change.");
+    }
+    appendRevision(located.rootId, "review", snapshot, author, {
+      action: "incorporate",
+      commentId: data.commentId,
+      response: response,
+    });
+    return read(ref, false);
+  }
+
+  // Restore an earlier revision by appending a new one. Later history is never
+  // erased: a revert is itself a revision, with the source recorded.
+  function revert(ref, revision, reason, author) {
+    var located = requireLive(ref);
+    var target = Number(revision);
+    if (!Number.isInteger(target) || target < 1) throw new Error("A revision number is required.");
+    var trimmedReason = cleanText(reason || "", MAX_RESPONSE_CHARS);
+    if (!trimmedReason) throw new Error("A revert requires a reason.");
+
+    var history = logsSnapshot.revisions(located.chain, MAX_LINKS);
+    if (target > history.revisions.length) {
+      throw new Error("This entry has only " + history.revisions.length + " revisions.");
+    }
+    var source = history.revisions[target - 1];
+    var current = history.revisions[history.revisions.length - 1];
+    if (logsSnapshot.sameSnapshot(current.snapshot, source.snapshot)) {
+      throw new Error("Revision " + target + " is identical to the current one.");
+    }
+    appendRevision(located.rootId, "revert", logsSnapshot.cloneSnapshot(source.snapshot), author, {
+      revertedFrom: target,
+      reason: trimmedReason,
+    });
+    return read(ref, false);
+  }
+
+  // The exact reconstructed snapshot as of one revision.
+  function readRevision(ref, revision) {
+    var located = findChain(ref);
+    if (!located) throw new Error("Log entry not found.");
+    var target = Number(revision);
+    if (!Number.isInteger(target) || target < 1) throw new Error("A revision number is required.");
+    var history = logsSnapshot.revisions(located.chain, MAX_LINKS);
+    if (target > history.revisions.length) {
+      throw new Error("This entry has only " + history.revisions.length + " revisions.");
+    }
+    var found = history.revisions[target - 1];
+    var described = logsSnapshot.describeRevision(found);
+    described.ref = ref;
+    described.snapshot = found.snapshot;
+    return described;
+  }
+
+
+  return {
+    review: review,
+    revert: revert,
+    readRevision: readRevision,
+  };
+}
+
+module.exports = { attachVersioning: attachVersioning };

package/lib/project-logs.js

@@ -0,0 +1,347 @@
+// Project Logs message handling and session-bound MCP wiring.
+//
+// Every capability here is derived server-side. The WebSocket path binds from
+// ws._clayUser plus this project's own slug, and the MCP path binds from the
+// exact live session object. Neither accepts identity or project scope from
+// the message, so a client cannot widen its own reach by asking.
+//
+// Authorship is split deliberately. Canonical entries are created and revised
+// only by this project's agent sessions through `clay-logs`; a connected human
+// reads the ledger and appends attributed comments. That keeps the log an
+// honest record of the work rather than a shared wiki.
+
+var logsMcp = require("./project-logs-mcp-server");
+
+var LIST_LIMIT = 50;
+var MAX_NOTICE_TITLE_CHARS = 160;
+var MAX_NOTICE_SUMMARY_CHARS = 240;
+
+// Canonical writes that move the ledger forward. A plain comment, a
+// clarification, and a decline are participation, not revisions, so they never
+// notify.
+var NOTIFYING_OPS = ["create", "update", "link", "incorporate", "revert"];
+
+function clip(value, max) {
+  if (typeof value !== "string") return "";
+  return value.length > max ? value.substring(0, max) : value;
+}
+
+// Bounded ledger metadata only. No body, no comment text, no author identity
+// beyond the vendor that wrote it.
+function updateNotice(entry, op) {
+  return {
+    type: "project_log_updated",
+    ref: entry.ref,
+    revision: entry.revisions,
+    op: op,
+    category: entry.category,
+    priority: entry.priority,
+    title: clip(entry.title, MAX_NOTICE_TITLE_CHARS),
+    summary: clip(entry.summary, MAX_NOTICE_SUMMARY_CHARS),
+    at: entry.updatedAt,
+    vendor: (entry.updatedBy && entry.updatedBy.vendor) || null,
+  };
+}
+
+var SYSTEM_PROMPT_LABEL = "--- Project Logs (durable project record; manage via clay-logs tools) ---";
+
+function parseJsonArray(value) {
+  if (Array.isArray(value)) return value;
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  var parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch (e) {
+    throw new Error("Expected a JSON array.");
+  }
+  if (!Array.isArray(parsed)) throw new Error("Expected a JSON array.");
+  return parsed;
+}
+
+// The tool surface accepts JSON-encoded arrays because MCP shapes are flat
+// scalars. The service and store only ever see real arrays.
+function coerceToolArgs(args) {
+  var out = Object.assign({}, args || {});
+  if (out.tags !== undefined) out.tags = parseJsonArray(out.tags);
+  if (out.links !== undefined) out.links = parseJsonArray(out.links);
+  return out;
+}
+
+var HANDLED_TYPES = [
+  "project_logs_list",
+  "project_log_read",
+  "project_log_comment",
+  // Retired human mutations. Still claimed so an older client gets an
+  // explicit refusal rather than silence.
+  "project_log_create",
+  "project_log_update",
+];
+
+var RETIRED_TYPES = ["project_log_create", "project_log_update"];
+
+function attachProjectLogs(ctx) {
+  var service = ctx.service;
+  var sm = ctx.sm;
+  var slug = ctx.projectSlug;
+  var isMate = ctx.isMate === true;
+  var mateId = ctx.mateId || null;
+  var sendTo = ctx.sendTo;
+  var getClients = ctx.getClients || function () { return []; };
+  var getProjectOwnerId = ctx.getProjectOwnerId || function () { return null; };
+
+  // Every socket in this project's client set passed the project access check
+  // at WebSocket upgrade, so a broadcast here is already scoped to authorized
+  // human users of this project. Nothing is read from any payload. Pane
+  // connections are excluded, matching how sticky notes broadcast.
+  function broadcastUpdate(entry, op) {
+    if (isMate || !entry) return;
+    if (NOTIFYING_OPS.indexOf(op) === -1) return;
+    var notice = updateNotice(entry, op);
+    var clients = getClients();
+    for (var client of clients) {
+      if (!client || client.readyState !== 1 || client._clayPane) continue;
+      sendTo(client, notice);
+    }
+  }
+
+  // Wrap a canonical write so a successful one notifies. A throw never reaches
+  // here, so a failed or no-op write is silent.
+  function notifying(op, run) {
+    return function (args) {
+      var result = run(args);
+      broadcastUpdate(result, op);
+      return result;
+    };
+  }
+
+  // --- Bindings --------------------------------------------------------
+
+  function sessionBinding(session) {
+    if (!service) return null;
+    if (isMate) {
+      if (!mateId) return null;
+      if (session && (!sm || !sm.sessions || sm.sessions.get(session.localId) !== session)) return null;
+      return service.bindMate({
+        projectSlug: slug,
+        projectOwnerId: getProjectOwnerId(),
+        isMate: true,
+        mateId: mateId,
+        session: session || null,
+      });
+    }
+    if (!session) return null;
+    return service.bindProjectSession({ projectSlug: slug, session: session });
+  }
+
+  function userBinding(ws) {
+    if (!service || isMate) return null;
+    return service.bindUser({ projectSlug: slug, user: (ws && ws._clayUser) || null });
+  }
+
+  // --- WebSocket surface -----------------------------------------------
+
+  function fail(ws, requestId, message) {
+    sendTo(ws, { type: "project_logs_error", requestId: requestId || null, message: message });
+  }
+
+  // Search already returns the ledger row shape, so a query needs no per-hit
+  // read and neither path dumps a record body into the list.
+  // Returns both the rows and this project's live category vocabulary, so the
+  // filter is populated solely from what this project actually uses.
+  function listEntries(bound, query, category) {
+    if (query) {
+      var hits = bound.searchLogs({ query: query, kind: category, limit: LIST_LIMIT });
+      return { entries: hits.results, categories: hits.categories || [] };
+    }
+    var listed = bound.listLogs({ kind: category, limit: LIST_LIMIT });
+    return { entries: listed.entries, categories: listed.categories || [] };
+  }
+
+  function handleLogsMessage(ws, msg) {
+    if (!msg || typeof msg.type !== "string") return false;
+    if (HANDLED_TYPES.indexOf(msg.type) === -1) return false;
+
+    var requestId = typeof msg.requestId === "string" ? msg.requestId : null;
+    if (isMate) {
+      fail(ws, requestId, "Project Logs are available in projects, not in Mate conversations.");
+      return true;
+    }
+
+    // Canonical authorship belongs to the project's agent sessions. A human
+    // asking to create or revise is refused before any binding is attempted,
+    // so no privilege level can reach the canonical writers.
+    if (RETIRED_TYPES.indexOf(msg.type) !== -1) {
+      fail(ws, requestId, "Project Logs are written by this project's agent sessions. Add a comment instead.");
+      return true;
+    }
+
+    var bound = userBinding(ws);
+    if (!bound) {
+      fail(ws, requestId, "Project Logs are not available for this project.");
+      return true;
+    }
+
+    try {
+      if (msg.type === "project_logs_list") {
+        var query = typeof msg.query === "string" ? msg.query.trim() : "";
+        // A view preference, not an authorization input: the store validates it.
+        var category = typeof msg.category === "string" && msg.category ? msg.category : null;
+        var listing = listEntries(bound, query, category);
+        sendTo(ws, {
+          type: "project_logs_state",
+          requestId: requestId,
+          entries: listing.entries,
+          categories: listing.categories,
+        });
+        return true;
+      }
+
+      if (msg.type === "project_log_read") {
+        sendTo(ws, { type: "project_log_entry", requestId: requestId, entry: bound.readLog({ ref: msg.ref }) });
+        return true;
+      }
+
+      if (msg.type === "project_log_comment") {
+        var commented = bound.commentLog({ ref: msg.ref, body: msg.body });
+        sendTo(ws, { type: "project_log_commented", requestId: requestId, entry: commented });
+        return true;
+      }
+    } catch (e) {
+      fail(ws, requestId, (e && e.message) || "Project Logs could not complete the request.");
+      return true;
+    }
+
+    return false;
+  }
+
+  // --- MCP surface ------------------------------------------------------
+
+  function toolHandlers(bound) {
+    if (!bound) return null;
+    return {
+      listLogs: function (args) { return bound.listLogs(args || {}); },
+      searchLogs: function (args) { return bound.searchLogs(args || {}); },
+      readLog: function (args) { return bound.readLog(args || {}); },
+      logHistory: function (args) { return bound.logHistory(args || {}); },
+      readLogRevision: function (args) { return bound.readLogRevision(args || {}); },
+      listLogFeedback: function (args) { return bound.listLogFeedback(args || {}); },
+      reviewLogComment: function (args) {
+        var request = coerceToolArgs(args);
+        var result = bound.reviewLogComment(request);
+        // Only an incorporation is a canonical revision; clarify and decline
+        // resolve a comment and change nothing.
+        if (request && request.action === "incorporate") broadcastUpdate(result, "incorporate");
+        return result;
+      },
+      revertLog: notifying("revert", function (args) { return bound.revertLog(args || {}); }),
+      createLog: notifying("create", function (args) { return bound.createLog(coerceToolArgs(args)); }),
+      updateLog: notifying("update", function (args) { return bound.updateLog(coerceToolArgs(args)); }),
+      linkLog: notifying("link", function (args) { return bound.linkLog(coerceToolArgs(args)); }),
+    };
+  }
+
+  // A Mate project advertises tools only when the registry confirms
+  // authoritative builtin Clay, and then only the read-only cross-project set.
+  function includeGlobal() {
+    if (!isMate) return false;
+    var projectBound = sessionBinding(null);
+    return !!(projectBound && projectBound.isClay === true);
+  }
+
+  function getToolDefs(session) {
+    if (!service) return [];
+    if (isMate && !includeGlobal()) return [];
+    var bound = session ? sessionBinding(session) : null;
+    if (session && !bound) return [];
+    return logsMcp.getToolDefs(toolHandlers(bound), isMate);
+  }
+
+  function createMcpServer(adapter, session) {
+    if (!service) return null;
+    if (isMate && !includeGlobal()) return null;
+    if (!isMate && session && !sessionBinding(session)) {
+      // A session that cannot bind still gets the fail-closed descriptor
+      // rather than a silently missing server.
+      return logsMcp.createMcpServer(adapter, null, false);
+    }
+    var bound = session ? sessionBinding(session) : null;
+    return logsMcp.createMcpServer(adapter, toolHandlers(bound), isMate);
+  }
+
+  function getDynamicToolDefs(session) {
+    return getToolDefs(session).map(function (tool) {
+      tool.permissionName = "mcp__clay-logs__" + tool.name;
+      return tool;
+    });
+  }
+
+  function getBridgeTools(session, normalizeSchema) {
+    if (!session) return [];
+    var defs = getToolDefs(session);
+    var tools = [];
+    for (var i = 0; i < defs.length; i++) {
+      tools.push({
+        server: "clay-logs",
+        name: defs[i].name,
+        description: defs[i].description || defs[i].name,
+        inputSchema: normalizeSchema(defs[i].inputSchema),
+      });
+    }
+    return tools;
+  }
+
+  function callBridgeTool(session, toolName, args) {
+    if (!session) return Promise.reject(new Error("Project Logs require a valid session."));
+    var defs = getToolDefs(session);
+    for (var i = 0; i < defs.length; i++) {
+      if (defs[i].name === toolName) return Promise.resolve(defs[i].handler(args || {}));
+    }
+    return Promise.reject(new Error("Project Logs tool not found: " + toolName));
+  }
+
+  // A count only. The comment bodies stay in the tool, so a pending queue is
+  // discoverable on the next turn without dumping the discussion into context
+  // and without starting a turn of its own.
+  function pendingFeedbackSignal(session) {
+    if (!session) return "";
+    var bound = sessionBinding(session);
+    if (!bound || typeof bound.listLogFeedback !== "function") return "";
+    var total = 0;
+    try {
+      total = bound.listLogFeedback({ limit: 1 }).total || 0;
+    } catch (e) {
+      return "";
+    }
+    if (!total) return "";
+    return "\n" + total + (total === 1 ? " comment awaits" : " comments await") +
+      " your review. Call list_log_feedback to see them.";
+  }
+
+  function getSystemPrompt(session) {
+    if (isMate || !service) return "";
+    if (session && !sessionBinding(session)) return "";
+    return SYSTEM_PROMPT_LABEL + "\n" + logsMcp.LOGS_CONTRACT +
+      "\n" + logsMcp.LEARNING_CONTRACT +
+      "\n" + logsMcp.REVIEW_CONTRACT + pendingFeedbackSignal(session);
+  }
+
+  return {
+    handleLogsMessage: handleLogsMessage,
+    createMcpServer: createMcpServer,
+    getToolDefs: getToolDefs,
+    getDynamicToolDefs: getDynamicToolDefs,
+    getBridgeTools: getBridgeTools,
+    callBridgeTool: callBridgeTool,
+    getSystemPrompt: getSystemPrompt,
+  };
+}
+
+module.exports = {
+  SYSTEM_PROMPT_LABEL: SYSTEM_PROMPT_LABEL,
+  NOTIFYING_OPS: NOTIFYING_OPS,
+  updateNotice: updateNotice,
+  HANDLED_TYPES: HANDLED_TYPES,
+  RETIRED_TYPES: RETIRED_TYPES,
+  attachProjectLogs: attachProjectLogs,
+  coerceToolArgs: coerceToolArgs,
+};

package/lib/project-mate-creation-proposal.js

@@ -0,0 +1,120 @@
+var mateCreationMcp = require("./mate-creation-mcp-server");
+var selectCatalogModel = require("./project-models").selectCatalogModel;
+
+function attachMateCreationProposal(ctx) {
+  var pending = {};
+
+  function clean(value, maxLength) {
+    if (typeof value !== "string") return "";
+    return value.replace(/\u0000/g, "").trim().slice(0, maxLength);
+  }
+
+  function publicProposal(source) {
+    return {
+      proposalId: source.proposalId,
+      name: clean(source.name, 80),
+      bio: clean(source.bio, 280),
+      relationship: clean(source.relationship, 120),
+      activities: Array.isArray(source.activities) ? source.activities.slice(0, 12) : [],
+      communicationStyle: Array.isArray(source.communicationStyle) ? source.communicationStyle.slice(0, 12) : [],
+      autonomy: clean(source.autonomy, 500),
+      identityMarkdown: clean(source.identityMarkdown, 30000),
+    };
+  }
+
+  function record(session, event) {
+    if (typeof ctx.recordSessionEvent === "function") ctx.recordSessionEvent(session, event);
+  }
+
+  function validateBoundSession(session) {
+    var projectOwnerId = typeof ctx.getProjectOwnerId === "function" ? ctx.getProjectOwnerId() : null;
+    var ownerValid = typeof ctx.isMultiUser === "function" && ctx.isMultiUser() ? !!(session && session.ownerId && (!projectOwnerId || session.ownerId === projectOwnerId)) : !!(session && !session.ownerId);
+    return !!(session && ctx.isMate === true && ctx.isHostAgent === true && session.mateCreationMode === true
+      && ownerValid);
+  }
+
+  function hasInterviewAnswer(session) {
+    var history = session && Array.isArray(session.history) ? session.history : [];
+    for (var i = history.length - 1; i >= 0; i--) if (history[i] && history[i].type === "ask_user_answered") return true;
+    return false;
+  }
+
+  function getToolDefs(boundSession) {
+    if (!boundSession || boundSession.mateCreationMode !== true) return [];
+    return mateCreationMcp.getToolDefs(function (definition) {
+      if (!validateBoundSession(boundSession)) return Promise.resolve({ action: "error", error: "Mate proposals require an owned Clay creation interview." });
+      if (!hasInterviewAnswer(boundSession)) return Promise.resolve({ action: "error", error: "Interview the user before proposing a Mate." });
+      return new Promise(function (resolve) {
+        var proposalId = "mp_" + Date.now() + "_" + Math.random().toString(36).slice(2, 8);
+        definition.proposalId = proposalId;
+        pending[proposalId] = { resolve: resolve, definition: definition, session: boundSession };
+        record(boundSession, { type: "mate_creation_proposal", proposal: publicProposal(definition) });
+      });
+    });
+  }
+
+  function createMcpServer(adapter, boundSession) {
+    return adapter.createToolServer({ name: "clay-mate-creation", version: "1.0.0", tools: getToolDefs(boundSession) });
+  }
+
+  function getBridgeTools(boundSession, normalizeSchema) {
+    if (!boundSession) return [];
+    return getToolDefs(boundSession).map(function (tool) {
+      return { server: "clay-mate-creation", name: tool.name, description: tool.description || tool.name, inputSchema: normalizeSchema(tool.inputSchema) };
+    });
+  }
+
+  function callBridgeTool(boundSession, toolName, args) {
+    var tools = getToolDefs(boundSession);
+    for (var i = 0; i < tools.length; i++) if (tools[i].name === toolName) return Promise.resolve(tools[i].handler(args || {}));
+    return Promise.reject(new Error("Session tool not found: clay-mate-creation/" + toolName));
+  }
+
+  function handleHomeMessage(ws, msg, session) {
+    var entry = msg && msg.proposalId ? pending[msg.proposalId] : null;
+    if (!entry || entry.session !== session || !validateBoundSession(session)) return false;
+    delete pending[msg.proposalId];
+    if (msg.action !== "create") {
+      record(session, { type: "mate_creation_proposal_resolved", proposalId: msg.proposalId, action: "cancel" });
+      entry.resolve({ action: "cancel" });
+      return true;
+    }
+    if (typeof ctx.createReadyMate !== "function") {
+      var unavailable = "Mate creation is unavailable.";
+      record(session, { type: "mate_creation_proposal_resolved", proposalId: msg.proposalId, action: "error", error: unavailable });
+      entry.resolve({ action: "error", error: unavailable });
+      return true;
+    }
+    var vendor = session.vendor || "claude";
+    if (typeof ctx.getVendorModelCatalog !== "function") {
+      var catalogUnavailable = "The Mate model catalog is unavailable.";
+      record(session, { type: "mate_creation_proposal_resolved", proposalId: msg.proposalId, action: "error", error: catalogUnavailable });
+      entry.resolve({ action: "error", error: catalogUnavailable });
+      return true;
+    }
+    Promise.resolve(ctx.getVendorModelCatalog(ws, vendor)).then(function (catalog) {
+      var selected = catalog && catalog.status === "ready" ? selectCatalogModel(catalog.models || [], catalog.defaultModel, "deep") : null;
+      if (!selected) throw new Error((catalog && catalog.error) || "No high-capability Mate model is available for " + vendor + ".");
+      return ctx.createReadyMate(ws, session.ownerId || null, Object.assign({}, entry.definition, { vendor: vendor, model: selected.value }));
+    }).then(function (mate) {
+      session.homeMateCreationPhase = "created";
+      record(session, { type: "mate_creation_proposal_resolved", proposalId: msg.proposalId, action: "create", mateId: mate.id, mateName: (mate.profile && mate.profile.displayName) || mate.name || "Mate" });
+      entry.resolve({ action: "create", mateId: mate.id });
+    }).catch(function (error) {
+      var text = error && error.message ? error.message : "The Mate could not be created.";
+      record(session, { type: "mate_creation_proposal_resolved", proposalId: msg.proposalId, action: "error", error: text });
+      entry.resolve({ action: "error", error: text });
+    });
+    return true;
+  }
+
+  return {
+    createMcpServer: createMcpServer,
+    getToolDefs: getToolDefs,
+    getBridgeTools: getBridgeTools,
+    callBridgeTool: callBridgeTool,
+    handleHomeMessage: handleHomeMessage,
+  };
+}
+
+module.exports = { attachMateCreationProposal: attachMateCreationProposal };

package/lib/project-mate-interaction.js

@@ -1,6 +1,18 @@
 var fs = require("fs");
 var path = require("path");
 var crypto = require("crypto");
+var mateSync = require("./mate-knowledge-sync");
+
+// Mirror a Mate-owned journal into the Clay-wide Knowledge backend after the
+// legacy append has already succeeded. Reconciling the whole journal keeps the
+// new scope current whether the write added, rewrote, or removed lines.
+function mirrorMateJournal(mateDir, fileName, job) {
+  mateSync.syncQuietly({
+    mateDir: mateDir,
+    fileName: fileName,
+    actor: { type: "agent", vendor: (job && job.vendor) || null, sessionKey: (job && job.sessionKey) || null },
+  });
+}
 
 function attachMateInteraction(ctx) {
   var cwd = ctx.cwd;
@@ -278,6 +290,7 @@ function attachMateInteraction(ctx) {
         fs.mkdirSync(knowledgeDir, { recursive: true });
         var digestFile = path.join(knowledgeDir, "session-digests.jsonl");
         fs.appendFileSync(digestFile, JSON.stringify(digestObj) + "\n");
+        mirrorMateJournal(mateDir, "session-digests.jsonl", job);
       } catch (e) {
         console.error("[digest-worker] Write failed for " + job.mateId + ":", e.message);
       }
@@ -302,6 +315,7 @@ function attachMateInteraction(ctx) {
             }));
           }
           fs.appendFileSync(obsFile, obsLines.join("\n") + "\n");
+          mirrorMateJournal(mateDir, "user-observations.jsonl", job);
         } catch (e) {
           console.error("[digest-worker] Observations write failed for " + job.mateId + ":", e.message);
         }