clay-server 3.8.1 → 4.0.0-beta.10

package/lib/project-logs-schema.js

@@ -0,0 +1,259 @@
+// Vocabulary and validation for Project Logs.
+//
+// Extracted from project-logs-store.js so the store stays focused on records
+// and stays inside the module size limit.
+//
+// Two independent axes, deliberately:
+//   category - what kind of record this is, a project-local vocabulary
+//   priority - how much it matters, a stable global enum
+// Conflating them is what made "an urgent decision" unrepresentable before.
+//
+// Category is NOT a global enum. Every project evolves its own vocabulary: an
+// agent reuses an established category when one fits and coins a new one when
+// the project needs a durable distinction it does not yet have. What is fixed
+// is only the shape of a category label, not the set of labels. The seeds
+// below are guidance for a project with no history yet, never a whitelist.
+
+// Suggested starting points, surfaced in tool guidance only.
+var SEED_CATEGORIES = [
+  "decision",
+  "security",
+  "idea",
+  "operations",
+  "incident",
+  "investigation",
+  "progress",
+  "reference",
+];
+
+var MAX_CATEGORY_CHARS = 32;
+// Letters and digits in any script, so a project can keep its vocabulary in the
+// language it actually works in. Normalization runs server-side only, so this
+// depends on Node's Unicode property escapes and never on a browser baseline.
+var CATEGORY_PATTERN = /^[\p{L}\p{N}]+(?:-[\p{L}\p{N}]+)*$/u;
+var CATEGORY_STRIP = /[^\p{L}\p{N}-]/gu;
+
+// Length is counted in code points, not UTF-16 units, so a CJK or Hangul label
+// is bounded the same way a Latin one is.
+function codePointLength(value) {
+  return Array.from(value).length;
+}
+
+// Deterministic normalization to a lowercase, hyphen-separated label. Anything
+// that cannot be reduced to a safe label is rejected rather than silently
+// coerced, so a caller is told when its input was unusable instead of getting a
+// surprising slug.
+//
+// Path and identity shapes are refused outright: a category is dry metadata and
+// must never be able to carry a slug, a path segment, or a user id.
+function normalizeCategory(value) {
+  if (typeof value !== "string") throw new Error("A log category must be a string.");
+  var raw = value.normalize("NFC").trim();
+  if (!raw) throw new Error("A log category is required.");
+  if (codePointLength(raw) > MAX_CATEGORY_CHARS * 2) {
+    throw new Error("A log category must be " + MAX_CATEGORY_CHARS + " characters or fewer.");
+  }
+  if (/[\/\\]/.test(raw) || raw.indexOf("..") !== -1) {
+    throw new Error("A log category cannot contain path characters.");
+  }
+  var slug = raw
+    .toLowerCase()
+    .replace(/[_\s]+/g, "-")
+    .replace(CATEGORY_STRIP, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  if (!slug) throw new Error("A log category must contain letters or digits: " + value);
+  if (codePointLength(slug) > MAX_CATEGORY_CHARS) {
+    throw new Error("A log category must be " + MAX_CATEGORY_CHARS + " characters or fewer.");
+  }
+  if (!CATEGORY_PATTERN.test(slug)) throw new Error("Invalid log category: " + value);
+  return slug;
+}
+
+// Non-throwing form for reading stored records, where a corrupt on-disk value
+// should make that record unusable rather than break the whole projection.
+// Filters deliberately do NOT use this: a caller that supplies a malformed
+// category is told so.
+function safeCategory(value) {
+  try {
+    return normalizeCategory(value);
+  } catch (e) {
+    return null;
+  }
+}
+
+var PRIORITIES = ["normal", "important", "urgent"];
+var DEFAULT_PRIORITY = "normal";
+
+var MAX_SUMMARY_CHARS = 400;
+
+function isPriority(value) {
+  return PRIORITIES.indexOf(value) !== -1;
+}
+
+function normalizePriority(value) {
+  return isPriority(value) ? value : DEFAULT_PRIORITY;
+}
+
+// A summary for an entry written before summaries existed. Deterministic and
+// derived from stored content only, so the same record always yields the same
+// text and nothing is invented.
+function fallbackSummary(entry) {
+  if (!entry) return "";
+  if (typeof entry.summary === "string" && entry.summary.trim()) {
+    return entry.summary.trim().substring(0, MAX_SUMMARY_CHARS);
+  }
+  // Prefer the first line of prose. A leading Markdown heading usually just
+  // restates the title, so it is only used when there is nothing else.
+  var body = typeof entry.body === "string" ? entry.body : "";
+  var lines = body.split("\n");
+  var heading = "";
+  var firstLine = "";
+  for (var i = 0; i < lines.length; i++) {
+    var raw = lines[i].trim();
+    if (!raw) continue;
+    var isHeading = raw.charAt(0) === "#";
+    var line = raw.replace(/^#+\s*/, "").replace(/^[-*>]\s*/, "").trim();
+    if (!line) continue;
+    if (isHeading) {
+      if (!heading) heading = line;
+      continue;
+    }
+    firstLine = line;
+    break;
+  }
+  if (!firstLine) firstLine = heading;
+  if (!firstLine) return "";
+  return firstLine.length > MAX_SUMMARY_CHARS
+    ? firstLine.substring(0, MAX_SUMMARY_CHARS)
+    : firstLine;
+}
+
+// Validation for a new agent-written record. Category, title, and summary are
+// all required: a log without a summary cannot be understood from a list, and
+// that is the whole point of the surface.
+function validateNewRecord(input) {
+  var data = input || {};
+  var category = normalizeCategory(data.category || data.kind);
+  if (typeof data.title !== "string" || !data.title.trim()) throw new Error("A log title is required.");
+  if (typeof data.summary !== "string" || !data.summary.trim()) {
+    throw new Error("A one or two sentence summary is required so the entry is understandable from a list.");
+  }
+  // A mistyped priority is refused rather than silently downgraded to normal:
+  // an agent that meant "urgent" must not get "normal" without being told.
+  if (data.priority !== undefined && data.priority !== null && !isPriority(data.priority)) {
+    throw new Error("Unknown log priority: " + data.priority);
+  }
+  return {
+    category: category,
+    priority: normalizePriority(data.priority),
+  };
+}
+
+// Validation for a revision. The category may move to another writable value
+// or stay on its legacy one; nothing is required, but nothing may be emptied.
+function validateRevision(input) {
+  var data = input || {};
+  var out = {};
+  if (data.category !== undefined || data.kind !== undefined) {
+    out.category = normalizeCategory(data.category || data.kind);
+  }
+  if (data.priority !== undefined) {
+    if (!isPriority(data.priority)) throw new Error("Unknown log priority: " + data.priority);
+    out.priority = data.priority;
+  }
+  if (data.title !== undefined) {
+    if (typeof data.title !== "string" || !data.title.trim()) throw new Error("A log title cannot be emptied.");
+    out.title = data.title;
+  }
+  if (data.summary !== undefined) {
+    if (typeof data.summary !== "string" || !data.summary.trim()) throw new Error("A log summary cannot be emptied.");
+    out.summary = data.summary;
+  }
+  return out;
+}
+
+
+// --- Normalization -------------------------------------------------------
+//
+// Moved here from project-logs-store.js so the store stays inside the module
+// size limit. These are pure text and shape helpers with no record semantics.
+
+var MAX_TAGS = 12;
+var MAX_TAG_CHARS = 40;
+var MAX_LINKS = 20;
+var MAX_LINK_CHARS = 200;
+
+function cleanText(value, max) {
+  if (typeof value !== "string") return "";
+  var text = value.replace(/\u0000/g, "").trim();
+  return text.length > max ? text.substring(0, max) : text;
+}
+
+function cleanLine(value, max) {
+  return cleanText(value, max).replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function normalizeAuthor(author) {
+  var source = author || {};
+  var type = source.type === "user" ? "user" : "session";
+  return {
+    type: type,
+    userId: source.userId ? cleanLine(String(source.userId), 120) : null,
+    displayName: cleanLine(source.displayName || "", 120) || null,
+    sessionKey: source.sessionKey ? cleanLine(String(source.sessionKey), 200) : null,
+    vendor: cleanLine(source.vendor || "", 40) || null,
+  };
+}
+
+function normalizeTags(tags) {
+  if (!Array.isArray(tags)) return [];
+  var out = [];
+  for (var i = 0; i < tags.length && out.length < MAX_TAGS; i++) {
+    var tag = cleanLine(String(tags[i] == null ? "" : tags[i]), MAX_TAG_CHARS).toLowerCase();
+    if (tag && out.indexOf(tag) === -1) out.push(tag);
+  }
+  return out;
+}
+
+function normalizeLinks(links) {
+  if (!Array.isArray(links)) return [];
+  var out = [];
+  for (var i = 0; i < links.length && out.length < MAX_LINKS; i++) {
+    var raw = links[i];
+    var value = typeof raw === "string" ? { ref: raw } : (raw || {});
+    var ref = cleanLine(String(value.ref || value.sessionRef || ""), MAX_LINK_CHARS);
+    if (!ref) continue;
+    var label = cleanLine(value.label || "", MAX_LINK_CHARS) || null;
+    var duplicate = false;
+    for (var j = 0; j < out.length; j++) {
+      if (out[j].ref === ref) { duplicate = true; break; }
+    }
+    if (!duplicate) out.push({ ref: ref, label: label });
+  }
+  return out;
+}
+
+module.exports = {
+  SEED_CATEGORIES: SEED_CATEGORIES,
+  MAX_CATEGORY_CHARS: MAX_CATEGORY_CHARS,
+  CATEGORY_PATTERN: CATEGORY_PATTERN,
+  codePointLength: codePointLength,
+  normalizeCategory: normalizeCategory,
+  safeCategory: safeCategory,
+  PRIORITIES: PRIORITIES,
+  DEFAULT_PRIORITY: DEFAULT_PRIORITY,
+  MAX_SUMMARY_CHARS: MAX_SUMMARY_CHARS,
+  isPriority: isPriority,
+  normalizePriority: normalizePriority,
+  fallbackSummary: fallbackSummary,
+  MAX_TAGS: MAX_TAGS,
+  MAX_LINKS: MAX_LINKS,
+  cleanText: cleanText,
+  cleanLine: cleanLine,
+  normalizeAuthor: normalizeAuthor,
+  normalizeTags: normalizeTags,
+  normalizeLinks: normalizeLinks,
+  validateNewRecord: validateNewRecord,
+  validateRevision: validateRevision,
+};

package/lib/project-logs-service.js

@@ -0,0 +1,357 @@
+// Authorization and binding layer for Project Logs.
+//
+// Modeled on workspace-query-service.js: a caller never states who it is.
+// Every binder re-derives the principal from authoritative server state and
+// returns null when anything fails to line up, so an unbound or stale caller
+// gets no capability rather than a degraded one.
+//
+// Product rules enforced here:
+//   - Project Logs are project records. Mate projects have none.
+//   - Ordinary Mates cannot reach project Logs at all.
+//   - Authoritative builtin Clay may read Logs, and only for projects the
+//     owning user is authorized to see. It may never write.
+//   - A project session is bound to exactly its own project's Logs.
+//   - Canonical authorship belongs to Project Driver sessions alone. A human,
+//     however privileged, may read and comment but may never create or revise
+//     a canonical entry: the log is the agent's record of the work.
+//   - Members of a shared project read each other's entries and comments with
+//     attribution.
+//   - A worktree resolves to its parent project for both authorization and
+//     storage, so worktree work never forks project knowledge.
+
+var builtinMates = require("./builtin-mates");
+var logsStore = require("./project-logs-store");
+
+function readOnly() {
+  throw new Error("Project Logs are read-only for builtin Clay.");
+}
+
+// Canonical entries are written by the project's own agent sessions. A human
+// participates by commenting, which is a separate, append-only surface.
+function agentOnly() {
+  throw new Error("Project Logs are written by this project's agent sessions. Add a comment instead.");
+}
+
+// Reviewing feedback and moving the record between revisions are the Driver's
+// judgement calls. A human cannot review their own comment into the record,
+// and Clay cannot review another project's.
+function driverOnly() {
+  throw new Error("Only this project's agent sessions can review feedback or change revisions.");
+}
+
+// Bounded discovery of comments still waiting on the Driver. The store owns the
+// one-pass scan over every live entry, so nothing here imposes a ceiling that
+// could hide a pending comment on an older record.
+function attachProjectLogsService(ctx) {
+  var context = ctx || {};
+  var getProjects = context.getProjects;
+  var isMultiUser = context.isMultiUser;
+  var resolveMate = context.resolveMate;
+  var canAccessProject = context.canAccessProject;
+  var findUserById = context.findUserById || function () { return null; };
+  var storeCache = new Map();
+
+  var openStore = context.openStore || function (cwd) {
+    if (!storeCache.has(cwd)) {
+      storeCache.set(cwd, logsStore.createProjectLogsStore({ cwd: cwd, baseDir: context.baseDir }));
+    }
+    return storeCache.get(cwd);
+  };
+
+  function projectFor(slug) {
+    if (!slug || typeof slug !== "string") return null;
+    var projects = getProjects();
+    return (projects && projects.get(slug)) || null;
+  }
+
+  // A worktree inherits its parent's visibility, so authorization is decided
+  // against the parent whenever the parent is registered.
+  function effectiveStatus(status) {
+    if (!status || status.isWorktree !== true || !status.parentSlug) return status;
+    var parent = projectFor(status.parentSlug);
+    if (!parent) return status;
+    var parentStatus = parent.getStatus();
+    return parentStatus || status;
+  }
+
+  function ownsProject(principal, status) {
+    if (!status) return false;
+    if (isMultiUser()) return !!principal.userId && status.projectOwnerId === principal.userId;
+    return !status.projectOwnerId || (!!principal.singleUserOwnerId && status.projectOwnerId === principal.singleUserOwnerId);
+  }
+
+  function authorizedProject(principal, status) {
+    if (!status) return false;
+    if (status.isMate === true) return false;
+    var governing = effectiveStatus(status);
+    if (ownsProject(principal, governing)) return true;
+    if (isMultiUser() && principal.userId && typeof canAccessProject === "function") {
+      return canAccessProject(principal.userId, governing) === true;
+    }
+    return false;
+  }
+
+  // Open the store for the governing project. When a worktree's parent is
+  // registered, its path is authoritative, so worktree Logs are shared without
+  // depending on a Git subprocess. The store's own root resolution remains the
+  // fallback for unregistered parents and for subdirectories of a checkout.
+  function storeForStatus(status) {
+    var governing = effectiveStatus(status);
+    if (!governing || !governing.path) throw new Error("Project Logs are unavailable for this project.");
+    return openStore(governing.path);
+  }
+
+  function statusFor(principal, slug) {
+    var project = projectFor(slug);
+    if (!project) throw new Error("Project not found.");
+    var status = project.getStatus();
+    if (!authorizedProject(principal, status)) throw new Error("Project Logs are not available for this project.");
+    return status;
+  }
+
+  function displayNameFor(userId) {
+    if (!userId) return null;
+    var user = findUserById(userId);
+    if (!user) return null;
+    return user.displayName || user.username || null;
+  }
+
+  function sessionAuthor(session) {
+    return {
+      type: "session",
+      userId: session.ownerId || null,
+      displayName: displayNameFor(session.ownerId),
+      sessionKey: session.cliSessionId || "local:" + session.localId,
+      vendor: session.vendor || null,
+    };
+  }
+
+  function userAuthor(user) {
+    return {
+      type: "user",
+      userId: (user && user.id) || null,
+      displayName: (user && (user.displayName || user.username)) || null,
+      sessionKey: null,
+      vendor: null,
+    };
+  }
+
+  // --- Binders ---------------------------------------------------------
+
+  // Exact session object identity, not a caller-supplied session id. A session
+  // handed in from a stale or forged reference is rejected even when its
+  // localId matches a live session.
+  function resolveProjectSession(source) {
+    if (!source || !source.projectSlug || !source.session) return null;
+    var project = projectFor(source.projectSlug);
+    if (!project) return null;
+    var status = project.getStatus();
+    if (!status || status.isMate === true) return null;
+    var manager = project.getSessionManager ? project.getSessionManager() : project.sm;
+    if (!manager || !manager.sessions || manager.sessions.get(source.session.localId) !== source.session) return null;
+
+    var principal;
+    if (isMultiUser()) {
+      // Fail closed: an unattributed session in multi-user mode gets nothing.
+      if (!source.session.ownerId) return null;
+      principal = { userId: source.session.ownerId, singleUserOwnerId: null };
+    } else {
+      if (source.session.ownerId && status.projectOwnerId && source.session.ownerId !== status.projectOwnerId) return null;
+      principal = { userId: null, singleUserOwnerId: source.session.ownerId || status.projectOwnerId || null };
+    }
+    if (!authorizedProject(principal, status)) return null;
+
+    principal.kind = "session";
+    principal.projectSlug = source.projectSlug;
+    principal.isClay = false;
+    return { principal: principal, status: status, author: sessionAuthor(source.session) };
+  }
+
+  // A tool handler captured earlier stays valid only while its exact source
+  // still resolves. Session identity and project authorization are both
+  // re-derived on every call, so a session dropped from the manager, or
+  // replaced by a different object with the same id, loses the capability
+  // immediately rather than continuing to work through a captured handler.
+  function bindProjectSession(source) {
+    var initial = resolveProjectSession(source);
+    if (!initial) return null;
+    function revalidate() {
+      var current = resolveProjectSession(source);
+      if (!current || current.principal.projectSlug !== initial.principal.projectSlug) {
+        throw new Error("This Project Logs binding is no longer valid for the current session.");
+      }
+      return current;
+    }
+    return createProjectBound(initial, revalidate);
+  }
+
+  function bindUser(source) {
+    if (!source || !source.projectSlug) return null;
+    var project = projectFor(source.projectSlug);
+    if (!project) return null;
+    var status = project.getStatus();
+    if (!status || status.isMate === true) return null;
+    var user = source.user || null;
+
+    var principal;
+    if (isMultiUser()) {
+      if (!user || !user.id) return null;
+      principal = { userId: user.id, singleUserOwnerId: null };
+    } else {
+      principal = { userId: null, singleUserOwnerId: (user && user.id) || status.projectOwnerId || null };
+    }
+    if (!authorizedProject(principal, status)) return null;
+
+    principal.kind = "user";
+    principal.projectSlug = source.projectSlug;
+    principal.isClay = false;
+    var envelope = { principal: principal, status: status, author: userAuthor(user) };
+    return createProjectBound(envelope, function () { return envelope; });
+  }
+
+  // Ordinary Mates get null. Only the authoritative builtin Clay host agent,
+  // confirmed against the server Mate registry rather than a project flag,
+  // receives a read-only cross-project binding.
+  function resolveMateSource(source) {
+    if (!source || source.isMate !== true || !source.mateId || typeof resolveMate !== "function") return null;
+    var sourceProject = projectFor(source.projectSlug);
+    if (!sourceProject) return null;
+    var sourceStatus = sourceProject.getStatus();
+    if (!sourceStatus || sourceStatus.isMate !== true) return null;
+    if (sourceStatus.mateId !== source.mateId || sourceStatus.projectOwnerId !== source.projectOwnerId) return null;
+    if (source.session) {
+      var manager = sourceProject.getSessionManager ? sourceProject.getSessionManager() : sourceProject.sm;
+      if (!manager || !manager.sessions || manager.sessions.get(source.session.localId) !== source.session) return null;
+    }
+    var mate = resolveMate(source.projectOwnerId || null, source.mateId);
+    if (!mate || mate.id !== source.mateId) return null;
+    if (isMultiUser() && (!source.projectOwnerId || mate.createdBy !== source.projectOwnerId)) return null;
+
+    var def = mate.builtinKey ? builtinMates.getBuiltinByKey(mate.builtinKey) : null;
+    var isClay = !!(mate.builtinKey === "clay" && def && def.hostAgent === true);
+    if (!isClay) return null;
+    if (isMultiUser() && !source.projectOwnerId) return null;
+
+    return {
+      kind: "clay",
+      userId: isMultiUser() ? source.projectOwnerId : null,
+      singleUserOwnerId: isMultiUser() ? null : (source.projectOwnerId || null),
+      projectSlug: null,
+      mateId: mate.id,
+      isClay: true,
+    };
+  }
+
+  // Clay keeps its authoritative registry and user authorization checks on
+  // every call, so a Mate that is deleted, demoted out of builtin Clay, or
+  // reassigned to another user loses the read view immediately.
+  function bindMate(source) {
+    var initial = resolveMateSource(source);
+    if (!initial) return null;
+    function revalidate() {
+      var current = resolveMateSource(source);
+      if (!current || current.mateId !== initial.mateId || current.userId !== initial.userId) {
+        throw new Error("This Project Logs binding is no longer valid for the current session.");
+      }
+      return current;
+    }
+    return createClayBound(revalidate);
+  }
+
+  // --- Bound capability surfaces ---------------------------------------
+
+  function createProjectBound(initial, revalidate) {
+    var store = storeForStatus(initial.status);
+
+    // Identity, authorization, and the target store are all re-derived per
+    // call. revalidate() re-checks exact session identity where there is one;
+    // the project authorization check then catches a visibility change.
+    function live() {
+      var current = revalidate();
+      var project = projectFor(current.principal.projectSlug);
+      if (!project) throw new Error("Project not found.");
+      var currentStatus = project.getStatus();
+      if (!authorizedProject(current.principal, currentStatus)) throw new Error("Project Logs are not available for this project.");
+      return storeForStatus(currentStatus);
+    }
+
+    function author() {
+      return revalidate().author;
+    }
+
+    // A session may write canonically; a user may only comment. The capability
+    // is decided by the binder that produced this envelope, never by a flag on
+    // the request.
+    var canonical = initial.principal.kind === "session";
+    return {
+      isClay: false,
+      canWrite: canonical,
+      canComment: true,
+      projectSlug: initial.principal.projectSlug,
+      scopeId: store.scopeId,
+      root: store.root,
+      author: initial.author,
+      listLogs: function (args) { return live().list(args || {}); },
+      searchLogs: function (args) { return live().search(args || {}); },
+      readLog: function (args) {
+        var entry = live().read(args && args.ref, false);
+        if (!entry) throw new Error("Log entry not found.");
+        return entry;
+      },
+      logHistory: function (args) { return live().history(args && args.ref, args || {}); },
+      commentLog: function (args) { return live().comment(args && args.ref, args || {}, author()); },
+      readLogRevision: function (args) { return live().readRevision(args && args.ref, args && args.revision); },
+      listLogFeedback: canonical ? function (args) { return live().feedback(args || {}); } : driverOnly,
+      reviewLogComment: canonical ? function (args) { return live().review(args && args.ref, args || {}, author()); } : driverOnly,
+      revertLog: canonical
+        ? function (args) { return live().revert(args && args.ref, args && args.revision, args && args.reason, author()); }
+        : driverOnly,
+      createLog: canonical ? function (args) { return live().create(args || {}, author()); } : agentOnly,
+      updateLog: canonical ? function (args) { return live().update(args && args.ref, args || {}, author()); } : agentOnly,
+      linkLog: canonical ? function (args) { return live().link(args && args.ref, args && args.links, author()); } : agentOnly,
+      removeLog: canonical ? function (args) { return live().remove(args && args.ref, author()); } : agentOnly,
+    };
+  }
+
+  function createClayBound(revalidate) {
+    function target(args) {
+      var principal = revalidate();
+      var slug = args && args.projectSlug;
+      if (!slug) throw new Error("An exact project slug is required.");
+      return storeForStatus(statusFor(principal, slug));
+    }
+
+    return {
+      isClay: true,
+      canWrite: false,
+      canComment: false,
+      projectSlug: null,
+      author: null,
+      listLogs: function (args) { return target(args).list(args || {}); },
+      searchLogs: function (args) { return target(args).search(args || {}); },
+      readLog: function (args) {
+        var entry = target(args).read(args && args.ref, false);
+        if (!entry) throw new Error("Log entry not found.");
+        return entry;
+      },
+      logHistory: function (args) { return target(args).history(args && args.ref, args || {}); },
+      commentLog: readOnly,
+      readLogRevision: function (args) { return target(args).readRevision(args && args.ref, args && args.revision); },
+      listLogFeedback: readOnly,
+      reviewLogComment: readOnly,
+      revertLog: readOnly,
+      createLog: readOnly,
+      updateLog: readOnly,
+      linkLog: readOnly,
+      removeLog: readOnly,
+    };
+  }
+
+  return {
+    bindProjectSession: bindProjectSession,
+    bindUser: bindUser,
+    bindMate: bindMate,
+  };
+}
+
+module.exports = { attachProjectLogsService: attachProjectLogsService };