clay-server 4.1.0-beta.6 → 4.1.0-beta.7

package/lib/issues-service.js

@@ -0,0 +1,339 @@
+// Authorization and capability bindings for the Phase 1 Issues backend.
+
+var issuesStore = require("./issues-store");
+var schema = require("./issues-schema");
+var provenance = require("./session-provenance");
+var commitVerification = require("./issues-commit-verification");
+var accessScope = require("./project-logs-access-scope").attachProjectLogsAccessScope;
+
+var PUBLIC_FIELDS = { title: true, summary: true, body: true, resolutionSummary: true,
+  type: true, priority: true, status: true, closeReason: true };
+
+function clone(value) { return value == null ? value : JSON.parse(JSON.stringify(value)); }
+
+function attachIssuesService(ctx) {
+  var context = ctx || {};
+  var projects = context.getProjects;
+  var multiUser = context.isMultiUser || function () { return false; };
+  var findUserById = context.findUserById || function () { return null; };
+  var stores = new Map();
+  var verify = commitVerification.injectedVerifier(context.verifyCommit);
+  var scope;
+
+  function projectFor(slug) {
+    var list = typeof projects === "function" ? projects() : null;
+    return typeof slug === "string" && list && typeof list.get === "function" ? list.get(slug) || null : null;
+  }
+
+  function statusFor(project) {
+    var status;
+    if (!project || typeof project.getStatus !== "function") return null;
+    try { status = project.getStatus(); } catch (e) { return null; }
+    if (!status || typeof status !== "object" || Array.isArray(status)) return null;
+    if (typeof status.slug !== "string" || !status.slug || typeof status.path !== "string" || !status.path) return null;
+    if (typeof status.projectKnowledgeId !== "string" || !status.projectKnowledgeId) return null;
+    if (status.projectOwnerId != null && typeof status.projectOwnerId !== "string") return null;
+    if (status.isWorktree === true && (typeof status.changeSetId !== "string" || !status.changeSetId || typeof status.parentSlug !== "string" || !status.parentSlug)) return null;
+    return status;
+  }
+
+  function governingStatus(status) {
+    if (!status || status.isWorktree !== true) return status;
+    return statusFor(projectFor(status.parentSlug));
+  }
+
+  function ownerKnown(status) {
+    return !multiUser() || !!status.projectOwnerId && !!findUserById(status.projectOwnerId);
+  }
+
+  function openStore(status) {
+    var governing = governingStatus(status);
+    if (!governing || !governing.path || !governing.projectKnowledgeId) throw new Error("Issues are unavailable for this project.");
+    var key = governing.projectKnowledgeId;
+    if (!stores.has(key)) stores.set(key, issuesStore.createIssuesStore({ projectKnowledgeId: key, baseDir: context.baseDir }));
+    return stores.get(key);
+  }
+
+  function issueContext(status) {
+    if (!status || status.isWorktree !== true || !status.changeSetId) return null;
+    return { kind: "worktree", changeSetId: status.changeSetId, branch: status.branch || null,
+      baseCommit: status.baseCommit || null, headCommit: status.headCommit || null };
+  }
+
+  function author(user, type, session) {
+    return { type: type, userId: user ? user.id || null : null,
+      displayName: user && (user.displayName || user.username) || null,
+      sessionKey: session ? session.cliSessionId || "local:" + session.localId : null,
+      sessionOriginId: session ? session.sessionOriginId || null : null,
+      vendor: session ? session.vendor || null : null, at: Date.now() };
+  }
+
+  function cleanPublic(input, controls, allowCloseReason) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("Issue arguments are required.");
+    var keys = Object.keys(input);
+    var result = {};
+    for (var i = 0; i < keys.length; i++) {
+      var key = keys[i];
+      if (Object.prototype.hasOwnProperty.call(controls, key)) continue;
+      if (!Object.prototype.hasOwnProperty.call(PUBLIC_FIELDS, key) || (key === "closeReason" && !allowCloseReason)) throw new Error("Unknown or server-owned issue field: " + key + ".");
+      result[key] = input[key];
+    }
+    return result;
+  }
+
+  function osUsersEnabled() {
+    return typeof context.osUsersEnabled === "function" ? context.osUsersEnabled() === true : context.osUsersEnabled === true;
+  }
+
+  function osIdentity(state) {
+    if (!osUsersEnabled()) return null;
+    var identity = typeof context.getOsUserInfoForActor === "function" ? context.getOsUserInfoForActor(state.user) : null;
+    if (!identity || typeof identity !== "object") throw new Error("An OS identity is required for commit verification.");
+    return clone(identity);
+  }
+
+  scope = accessScope({ projectFor: projectFor, isMultiUser: multiUser,
+    canAccessProject: context.canAccessProject, hasFullProjectAccess: context.hasFullProjectAccess,
+    openStore: function () { return null; } });
+
+  function bindingState(project, session, userId, originId) {
+    var status = statusFor(project);
+    if (!status || status.isMate === true) return null;
+    var governing = governingStatus(status);
+    if (!governing || !ownerKnown(governing)) return null;
+    var user = null;
+    if (multiUser()) {
+      if (!userId || !(user = findUserById(userId))) return null;
+    } else {
+      user = userId ? findUserById(userId) : null;
+      if (!user) user = { id: userId || status.projectOwnerId || null };
+    }
+    if (session) {
+      var manager = project.getSessionManager ? project.getSessionManager() : project.sm;
+      if (!manager || !manager.sessions || manager.sessions.get(session.localId) !== session) return null;
+      if ((session.ownerId || null) !== (userId || null) || (session.sessionOriginId || null) !== originId) return null;
+      if (multiUser() && !session.ownerId) return null;
+      if (provenance.isWorker(session) || session.hidden === true || session.delegated === true || session._pairDelegation || session._delegatedBy) return null;
+    }
+    var principal = multiUser() ? { userId: user.id, singleUserOwnerId: null }
+      : { userId: null, singleUserOwnerId: user.id || status.projectOwnerId || null };
+    var authorization;
+    try { authorization = scope.projectAuthorization(principal, status); } catch (e) { return null; }
+    if (!authorization.allowed || (authorization.worktreeOnly && !status.changeSetId)) return null;
+    principal.isProjectOwner = scope.ownsProject(principal, governing);
+    return { project: project, status: status, session: session, user: user,
+      principal: principal, worktreeOnly: authorization.worktreeOnly };
+  }
+
+  function bind(source, isSession) {
+    if (!source || typeof source.projectSlug !== "string") return null;
+    var initialSlug = source.projectSlug;
+    var initialProject = projectFor(initialSlug);
+    var initialSession = isSession ? source.session : null;
+    if (!initialProject || (isSession && !initialSession)) return null;
+    if (initialSession) provenance.ensureOrigin(initialSession);
+    var initialUserId = initialSession ? initialSession.ownerId || null : source.userId || null;
+    var initialOrigin = initialSession ? initialSession.sessionOriginId || null : null;
+    var initial = bindingState(initialProject, initialSession, initialUserId, initialOrigin);
+    if (!initial) return null;
+
+    function current() {
+      if (projectFor(initialSlug) !== initialProject) throw new Error("This Issues binding is no longer valid.");
+      var live = bindingState(initialProject, initialSession, initialUserId, initialOrigin);
+      if (!live) throw new Error("This Issues binding is no longer valid.");
+      return live;
+    }
+
+    function visibleIssue(store, ref, state) {
+      var result = store.read(ref);
+      if (state.worktreeOnly && (!result.context || result.context.changeSetId !== state.status.changeSetId)) throw new Error("Issue not found.");
+      return result;
+    }
+    function scopedIssue(store, ref, state) {
+      var result = store.read(ref, true);
+      if (state.worktreeOnly && (!result.context || result.context.changeSetId !== state.status.changeSetId)) throw new Error("Issue not found.");
+      return result;
+    }
+
+    function scopedOptions(state, args) {
+      var result = Object.assign({}, args || {});
+      if (state.worktreeOnly) {
+        if (!state.status.changeSetId) throw new Error("Issues are unavailable without a change set.");
+        result.changeSetId = state.status.changeSetId;
+      }
+      return result;
+    }
+
+    function operation(state, needsIdentity) {
+      var governing = governingStatus(state.status);
+      return { project: state.project, session: state.session, userId: state.user.id || null,
+        path: state.status.path, knowledgeId: governing.projectKnowledgeId,
+        changeSetId: state.status.changeSetId || null, worktreeOnly: state.worktreeOnly,
+        recordContext: clone(issueContext(state.status)),
+        actor: clone(author(state.user, state.session ? "session" : "user", state.session)),
+        osIdentity: needsIdentity ? osIdentity(state) : null };
+    }
+
+    function recheck(before, needsIdentity) {
+      var fresh = current();
+      var governing = governingStatus(fresh.status);
+      var liveIdentity = needsIdentity ? osIdentity(fresh) : null;
+      if (fresh.project !== before.project || fresh.session !== before.session || (fresh.user.id || null) !== before.userId ||
+          fresh.status.path !== before.path || !governing || governing.projectKnowledgeId !== before.knowledgeId ||
+          (fresh.status.changeSetId || null) !== before.changeSetId || fresh.worktreeOnly !== before.worktreeOnly ||
+          JSON.stringify(liveIdentity) !== JSON.stringify(before.osIdentity)) throw new Error("Issue authorization changed during the operation.");
+      return fresh;
+    }
+
+    function evidence(before, sha) {
+      return verify(before.path, sha, before.knowledgeId, before.osIdentity).then(function (proof) {
+        var normalized = schema.normalizeVerifiedCommit(proof);
+        if (normalized.repository !== before.knowledgeId) throw new Error("Verified commit evidence belongs to a different repository.");
+        return normalized;
+      });
+    }
+
+    return {
+      linkWorkSession: function (args, session) {
+        var state = current();
+        var manager = state.project.getSessionManager();
+        if (!args || !Number.isInteger(args.expectedRevision)) throw new Error("expectedRevision is required.");
+        if (!session || manager.sessions.get(session.localId) !== session || provenance.isWorker(session) || session.hidden === true ||
+            session.delegated === true || session._pairDelegation || session._delegatedBy ||
+            (session.ownerId || null) !== (state.user.id || null)) throw new Error("Invalid work session.");
+        provenance.ensureOrigin(session);
+        var target = openStore(state.status);
+        var entry = visibleIssue(target, args.ref, state);
+        if (entry.revision !== args.expectedRevision) throw new Error("Issue revision conflict.");
+        if (entry.status === "resolved" || entry.status === "closed") throw new Error("Reopen this issue before starting work.");
+        var links = entry.linkedWorkSessions || [];
+        if (links.some(function (link) { return link.sessionId === session.sessionOriginId; })) return entry;
+        var link = { sessionId: session.sessionOriginId, role: "driver", issueRevision: args.expectedRevision };
+        if (args.requestId !== undefined) link.requestId = schema.text(args.requestId, "work request id", 200, true);
+        return target.update(args.ref, { linkedWorkSessions: links.concat([link]), status: "in_progress" }, args.expectedRevision, author(state.user, "user", null));
+      },
+      resolveWorkSession: function (args) {
+        var state = current();
+        var entry = visibleIssue(openStore(state.status), args.ref, state);
+        if (!(entry.linkedWorkSessions || []).some(function (link) { return link.sessionId === args.sessionOriginId; })) throw new Error("Work session unavailable.");
+        var found = null;
+        state.project.getSessionManager().sessions.forEach(function (session) {
+          if (session.sessionOriginId === args.sessionOriginId && (session.ownerId || null) === (state.user.id || null) &&
+              !provenance.isWorker(session) && session.hidden !== true && session.delegated !== true && !session._pairDelegation && !session._delegatedBy) found = session;
+        });
+        if (!found) throw new Error("Work session unavailable.");
+        return found;
+      },
+      scopeId: "project/" + governingStatus(initial.status).projectKnowledgeId + "/issues",
+      canComment: true,
+      canDelete: initial.principal.isProjectOwner === true,
+      listIssues: function (args) { var state = current(); return openStore(state.status).list(scopedOptions(state, args)); },
+      searchIssues: function (args) { var state = current(); return openStore(state.status).search(scopedOptions(state, args)); },
+      readIssue: function (args) { var state = current(); return visibleIssue(openStore(state.status), args && args.ref, state); },
+      readIssueTombstone: function (args) { var state = current(); return scopedIssue(openStore(state.status), args && args.ref, state); },
+      issueHistory: function (args) { var state = current(); var store = openStore(state.status); var history = store.history(args && args.ref); if (state.worktreeOnly) { var historical = scopedIssue(store, args && args.ref, state); if (!historical.context || historical.context.changeSetId !== state.status.changeSetId) throw new Error("Issue not found."); } return history; },
+      readIssueRevision: function (args) { var state = current(); var store = openStore(state.status); visibleIssue(store, args && args.ref, state); return store.readRevision(args.ref, args.revision); },
+      commentIssue: function (args) { var state = current(); var target = openStore(state.status); visibleIssue(target, args && args.ref, state); return target.comment(args.ref, args.body, author(state.user, "user", null)); },
+      listIssueFeedback: function (args) {
+        if (!isSession) throw new Error("Only the Project Driver can review issue comments.");
+        var state = current(); var target = openStore(state.status); var out = []; var feedbackLimit = args && args.limit === undefined ? 200 : Number(args.limit);
+        if (!Number.isInteger(feedbackLimit) || feedbackLimit < 1 || feedbackLimit > 200) throw new Error("Feedback limit must be between 1 and 200.");
+        var position = { issueCursor: null, issueIndex: 0, commentOffset: 0 };
+        if (args && args.cursor) {
+          try {
+            if (/^\d+$/.test(String(args.cursor))) position.issueCursor = String(args.cursor);
+            else position = JSON.parse(Buffer.from(String(args.cursor), "base64url").toString("utf8"));
+          } catch (e) { throw new Error("Invalid issue feedback cursor."); }
+          if (!position || (position.issueCursor !== null && typeof position.issueCursor !== "string") || !Number.isInteger(position.issueIndex) || position.issueIndex < 0 || !Number.isInteger(position.commentOffset) || position.commentOffset < 0) throw new Error("Invalid issue feedback cursor.");
+        }
+        var nextCursor = null; var scanned = 0;
+        while (out.length < feedbackLimit && scanned < 500) {
+          var result = target.list(scopedOptions(state, { limit: 50, cursor: position.issueCursor }));
+          if (!result.issues.length) break;
+          scanned += result.issues.length;
+          var firstIssueIndex = position.issueIndex;
+          if (firstIssueIndex >= result.issues.length) throw new Error("Invalid issue feedback cursor.");
+          for (var i = firstIssueIndex; i < result.issues.length && out.length < feedbackLimit; i++) {
+            var entry = visibleIssue(target, result.issues[i].ref, state);
+            var waiting = (entry.comments || []).filter(function (item) { return item.status === "pending"; });
+            var start = i === position.issueIndex ? position.commentOffset : 0;
+            var j = start;
+            for (; j < waiting.length && out.length < feedbackLimit; j++) out.push({ ref: entry.ref, title: entry.title, commentId: waiting[j].id, body: waiting[j].body, author: waiting[j].author, at: waiting[j].at });
+            if (out.length >= feedbackLimit) {
+              if (j < waiting.length) nextCursor = Buffer.from(JSON.stringify({ issueCursor: position.issueCursor, issueIndex: i, commentOffset: j })).toString("base64url");
+              else if (i + 1 < result.issues.length) nextCursor = Buffer.from(JSON.stringify({ issueCursor: position.issueCursor, issueIndex: i + 1, commentOffset: 0 })).toString("base64url");
+              else if (result.nextCursor) nextCursor = Buffer.from(JSON.stringify({ issueCursor: result.nextCursor, issueIndex: 0, commentOffset: 0 })).toString("base64url");
+            }
+          }
+          if (nextCursor || !result.nextCursor) break;
+          if (scanned >= 500) {
+            nextCursor = Buffer.from(JSON.stringify({ issueCursor: result.nextCursor, issueIndex: 0, commentOffset: 0 })).toString("base64url");
+            break;
+          }
+          position.issueCursor = result.nextCursor; position.issueIndex = 0; position.commentOffset = 0;
+        }
+        return { feedback: out, total: out.length, nextCursor: nextCursor, truncated: !!nextCursor };
+      },
+      reviewIssueComment: function (args) {
+        if (!isSession) throw new Error("Only the Project Driver can review issue comments.");
+        var state = current(); var target = openStore(state.status); var entry = visibleIssue(target, args && args.ref, state);
+        if (args.action === "incorporate") {
+          if (!Number.isInteger(args.expectedRevision)) throw new Error("expectedRevision is required to incorporate a comment.");
+          var data = cleanPublic(args, { ref: true, expectedRevision: true, commentId: true, action: true, response: true, commitSha: true }, true);
+          if (data.status === "resolved") throw new Error("Use update_issue with verified commit evidence before resolving this Issue.");
+          return target.incorporate(entry.ref, args.commentId, data, args.expectedRevision, args.response, author(state.user, "session", state.session));
+        }
+        return target.review(entry.ref, args.commentId, args.action, args.response, author(state.user, "session", state.session));
+      },
+      removeIssue: function (args) {
+        var state = current();
+        if (!state.principal.isProjectOwner) throw new Error("Only the project owner can delete Issues.");
+        var target = openStore(state.status); var entry = visibleIssue(target, args && args.ref, state);
+        if (!Number.isInteger(args && args.expectedRevision) || entry.revision !== args.expectedRevision) throw new Error("Issue revision conflict.");
+        return target.remove(entry.ref, author(state.user, "user", null), args.expectedRevision);
+      },
+      createIssue: function (args) {
+        if (!isSession) throw new Error("People cannot create issues directly. Ask the Project Driver to create one.");
+        var data = cleanPublic(args, { commitSha: true }, true);
+        var status = data.status === undefined ? "open" : data.status;
+        if (schema.STATUSES.indexOf(status) === -1) throw new Error("Invalid status.");
+        var state = current();
+        if (status !== "resolved") return Promise.resolve(openStore(state.status).create(data,
+          author(state.user, state.session ? "session" : "user", state.session), issueContext(state.status)));
+        if (typeof data.resolutionSummary !== "string" || !data.resolutionSummary.trim()) throw new Error("resolutionSummary is required when resolving an issue.");
+        var before = operation(state, true);
+        return evidence(before, args.commitSha).then(function (proof) {
+          var after = recheck(before, true);
+          return openStore(after.status).create(data, before.actor, before.recordContext, proof);
+        });
+      },
+      updateIssue: function (args) {
+        var data = cleanPublic(args, { ref: true, expectedRevision: true, commitSha: true }, true);
+        if (!Number.isInteger(args.expectedRevision)) throw new Error("expectedRevision is required.");
+        if (data.status !== undefined && schema.STATUSES.indexOf(data.status) === -1) throw new Error("Invalid status.");
+        var ref = args.ref;
+        var expectedRevision = args.expectedRevision;
+        var state = current();
+        var target = openStore(state.status);
+        var existing = visibleIssue(target, ref, state);
+        if (existing.revision !== expectedRevision) throw new Error("Issue revision conflict.");
+        if (data.status !== "resolved") return Promise.resolve(target.update(ref, data, expectedRevision,
+          author(state.user, state.session ? "session" : "user", state.session)));
+        if (typeof data.resolutionSummary !== "string" || !data.resolutionSummary.trim()) throw new Error("resolutionSummary is required when resolving an issue.");
+        var before = operation(state, true);
+        return evidence(before, args.commitSha).then(function (proof) {
+          var after = recheck(before, true);
+          var afterStore = openStore(after.status);
+          visibleIssue(afterStore, ref, after);
+          return afterStore.update(ref, data, expectedRevision, before.actor, null, proof);
+        });
+      },
+    };
+  }
+
+  return { bindUser: function (source) { return bind(source, false); },
+    bindProjectSession: function (source) { return bind(source, true); },
+    issueScopeIdForKnowledgeId: issuesStore.issueScopeIdForKnowledgeId };
+}
+
+module.exports = { attachIssuesService: attachIssuesService };

package/lib/issues-store.js

@@ -0,0 +1,210 @@
+// Append-only Issue records, stored beside but separately from Project Logs.
+
+var crypto = require("crypto");
+var recordStore = require("./knowledge-record-store");
+var schema = require("./issues-schema");
+var issueComments = require("./issues-comments");
+
+var REF = /^issue:[A-Za-z0-9_-]{24}$/;
+var MAX_PAGE = 50;
+
+function issueScopeIdForKnowledgeId(id) {
+  if (typeof id !== "string" || !/^[A-Za-z0-9_-]{1,120}$/.test(id)) throw new Error("Invalid project knowledge id.");
+  return "project/" + id + "/issues";
+}
+
+function createIssuesStore(options) {
+  var opts = options || {};
+  var knowledgeId = opts.projectKnowledgeId;
+  var scopeId = issueScopeIdForKnowledgeId(knowledgeId);
+  var records = recordStore.createRecordStore({ scopeId: scopeId, baseDir: opts.baseDir });
+
+  function ref() {
+    return "issue:" + crypto.randomBytes(18).toString("base64url").substring(0, 24);
+  }
+  function chainFor(id) {
+    var all = records.all();
+    var out = [];
+    for (var i = 0; i < all.length; i++) if (all[i].rootId === id) out.push(all[i]);
+    return out;
+  }
+  function snapshotFor(chain, revision) {
+    var current = null;
+    for (var i = 0; i < chain.length; i++) {
+      if ((chain[i].op === "revision" || chain[i].op === "incorporate") && (!revision || chain[i].revision <= revision)) current = chain[i].snapshot;
+    }
+    return current ? schema.clone(current) : null;
+  }
+  function project(id, includeBody, includeDeleted) {
+    var chain = chainFor(id);
+    var revisions = chain.filter(function (record) { return record.op === "revision" || record.op === "incorporate"; });
+    if (!revisions.length) return null;
+    var latest = revisions[revisions.length - 1];
+    var current = schema.clone(latest.snapshot);
+    var deleted = chain.some(function (record) { return record.op === "delete"; });
+    if (deleted && !includeDeleted) return null;
+    var result = {
+      ref: id, revision: latest.revision, title: current.title, summary: current.summary,
+      resolutionSummary: current.resolutionSummary || "",
+      type: current.type, priority: current.priority, status: current.status,
+      createdAt: revisions[0].at, updatedAt: latest.at, createdBy: revisions[0].author,
+      updatedBy: latest.author, context: current.context, linkedWorkSessions: current.linkedWorkSessions,
+      resolutionHistory: current.resolutionHistory,
+      comments: issueComments.comments(chain), deleted: deleted,
+    };
+    if (deleted) { var tombstone = chain.filter(function (record) { return record.op === "delete"; }).pop(); result.deletedAt = tombstone.at; result.deletedBy = tombstone.author; }
+    if (current.verifiedCommit) result.verifiedCommit = current.verifiedCommit;
+    if (current.closeReason) result.closeReason = current.closeReason;
+    if (includeBody) result.body = current.body;
+    return result;
+  }
+  function append(id, operation, snapshot, revision, author) {
+    records.append({ id: recordStore.newRecordId(), rootId: id, op: operation, scope: scopeId,
+      revision: revision, snapshot: schema.clone(snapshot), author: schema.clone(author), at: Date.now() });
+  }
+  function create(data, author, context, verifiedCommit) {
+    var id = ref();
+    var input = Object.assign({}, data || {});
+    input.status = input.status === undefined ? "open" : input.status;
+    input.context = schema.normalizeContext(context);
+    if (input.status === "resolved") {
+      if (!verifiedCommit) throw new Error("resolved issues require verified commit evidence.");
+      if (typeof input.resolutionSummary !== "string" || !input.resolutionSummary.trim()) throw new Error("resolutionSummary is required when resolving an issue.");
+      input.verifiedCommit = verifiedCommit;
+    }
+    var snap = schema.snapshot(input);
+    if (snap.status === "resolved") {
+      snap.resolutionHistory = [{ status: "resolved", resolutionSummary: snap.resolutionSummary, verifiedCommit: snap.verifiedCommit, at: Date.now() }];
+    }
+    append(id, "revision", snap, 1, author);
+    return project(id, true);
+  }
+  function update(id, data, expectedRevision, author, context, verifiedCommit) {
+    var current = project(id, true);
+    if (!current) throw new Error("Issue not found.");
+    if (expectedRevision !== current.revision) throw new Error("Issue revision conflict.");
+    var input = Object.assign({}, data || {});
+    input.context = schema.clone(current.context || null);
+    if (input.status === "resolved") {
+      if (!verifiedCommit) throw new Error("resolved issues require verified commit evidence.");
+      input.verifiedCommit = verifiedCommit;
+    }
+    if (input.status === "open" || input.status === "in_progress") {
+      input.resolutionHistory = current.resolutionHistory || [];
+      delete input.verifiedCommit;
+      delete input.resolutionSummary;
+    }
+    var snap = schema.snapshot(input, current);
+    if (input.status === "resolved") {
+      snap.resolutionHistory = (current.resolutionHistory || []).concat([{ status: "resolved", resolutionSummary: snap.resolutionSummary, verifiedCommit: snap.verifiedCommit, at: Date.now() }]);
+    }
+    append(id, "revision", snap, current.revision + 1, author);
+    return project(id, true);
+  }
+  function comment(id, body, author) {
+    var located = { rootId: id, chain: chainFor(id) };
+    if (!project(id, false)) throw new Error("Issue not found.");
+    var value = schema.text(body, "comment", 4000, true);
+    var current = project(id, true);
+    if ((current.comments || []).length >= 200) throw new Error("This issue already has the maximum of 200 comments.");
+    records.append({ id: recordStore.newRecordId(), rootId: located.rootId, op: "comment", scope: scopeId,
+      body: value, author: schema.clone(author), at: Date.now() });
+    return project(id, true);
+  }
+  function review(id, commentId, action, response, author, revision) {
+    var current = project(id, true);
+    if (!current) throw new Error("Issue not found.");
+    if (issueComments.ACTIONS.indexOf(action) === -1) throw new Error("Invalid issue comment action.");
+    var exists = (current.comments || []).some(function (item) { return item.id === commentId && item.status === issueComments.STATUS_PENDING; });
+    if (!exists) throw new Error("Issue comment is no longer awaiting review.");
+    records.append({ id: recordStore.newRecordId(), rootId: id, op: "review", scope: scopeId,
+      commentId: commentId, action: action, response: schema.text(response || "", "response", 4000, action !== "incorporate"), revision: revision || null,
+      author: schema.clone(author), at: Date.now() });
+    return project(id, true);
+  }
+  function incorporate(id, commentId, data, expectedRevision, response, author) {
+    var current = project(id, true);
+    if (!current) throw new Error("Issue not found.");
+    if (current.revision !== expectedRevision) throw new Error("Issue revision conflict.");
+    if (issueComments.ACTIONS.indexOf("incorporate") === -1) throw new Error("Invalid issue comment action.");
+    if (!(current.comments || []).some(function (item) { return item.id === commentId && item.status === issueComments.STATUS_PENDING; })) throw new Error("Issue comment is no longer awaiting review.");
+    var input = Object.assign({}, data || {}); input.context = schema.clone(current.context || null);
+    var reviewResponse = schema.text(response || "", "response", 4000, false);
+    var snapshot = schema.snapshot(input, current);
+    var unchanged = snapshotFor(chainFor(id), current.revision);
+    if (JSON.stringify(snapshot) === JSON.stringify(unchanged)) throw new Error("Issue incorporation must change the canonical Issue.");
+    records.append({ id: recordStore.newRecordId(), rootId: id, op: "revision", scope: scopeId, snapshot: schema.clone(snapshot),
+      review: { commentId: commentId, action: "incorporate", response: reviewResponse, revision: current.revision + 1 }, revision: current.revision + 1,
+      author: schema.clone(author), at: Date.now() });
+    return project(id, true);
+  }
+  function remove(id, author, expectedRevision) {
+    var current = project(id, false);
+    if (!current) throw new Error("Issue not found.");
+    if (!Number.isInteger(expectedRevision)) throw new Error("expectedRevision is required.");
+    if (current.revision !== expectedRevision) throw new Error("Issue revision conflict.");
+    records.append({ id: recordStore.newRecordId(), rootId: id, op: "delete", scope: scopeId, author: schema.clone(author), at: Date.now() });
+    return project(id, true, true);
+  }
+  function visible(options) {
+    var opts2 = options || {};
+    if (opts2.type !== undefined && schema.TYPES.indexOf(opts2.type) === -1) throw new Error("Invalid issue type filter.");
+    if (opts2.status !== undefined && schema.STATUSES.indexOf(opts2.status) === -1) throw new Error("Invalid issue status filter.");
+    if (opts2.priority !== undefined && schema.PRIORITIES.indexOf(opts2.priority) === -1) throw new Error("Invalid issue priority filter.");
+    var all = records.all();
+    var ids = {}; var order = [];
+    for (var i = 0; i < all.length; i++) if ((all[i].op === "revision" || all[i].op === "incorporate") && !ids[all[i].rootId]) { ids[all[i].rootId] = true; order.push(all[i].rootId); }
+    var out = [];
+    for (var j = 0; j < order.length; j++) {
+      var item = project(order[j], false);
+      if (!item) continue;
+      if (opts2.type && item.type !== opts2.type) continue;
+      if (opts2.priority && item.priority !== opts2.priority) continue;
+      if (opts2.status && item.status !== opts2.status) continue;
+      if (opts2.changeSetId && (!item.context || item.context.changeSetId !== opts2.changeSetId)) continue;
+      if (opts2.query) {
+        var full = project(order[j], true);
+        if ((full.title + " " + full.summary + " " + full.body).toLowerCase().indexOf(String(opts2.query).toLowerCase()) === -1) continue;
+      }
+      out.push(item);
+    }
+    out.sort(function (a, b) { return b.updatedAt - a.updatedAt || a.ref.localeCompare(b.ref); });
+    var limit = Number(opts2.limit);
+    if (!Number.isInteger(limit)) limit = 20;
+    if (limit < 1 || limit > MAX_PAGE) throw new Error("Issue page limit must be between 1 and 50.");
+    var offset = opts2.cursor === undefined || opts2.cursor === null || opts2.cursor === "" ? 0 : Number(opts2.cursor);
+    if (!Number.isInteger(offset) || offset < 0) throw new Error("Invalid issue page cursor.");
+    return { issues: out.slice(offset, offset + limit), total: out.length, nextCursor: offset + limit < out.length ? String(offset + limit) : null };
+  }
+  function read(id, includeDeleted) { if (!REF.test(id)) throw new Error("Invalid issue reference."); var result = project(id, true, includeDeleted === true); if (!result) throw new Error("Issue not found."); return result; }
+  function history(id) {
+    var chain = chainFor(id); if (!chain.length) throw new Error("Issue not found.");
+    var previous = null;
+    var revisions = chain.filter(function (r) { return r.op === "revision" || r.op === "incorporate"; }).map(function (r) {
+      var keys = {};
+      Object.keys(previous || {}).concat(Object.keys(r.snapshot || {})).forEach(function (key) { keys[key] = true; });
+      var changed = Object.keys(keys).filter(function (key) {
+        return JSON.stringify(previous && previous[key]) !== JSON.stringify(r.snapshot && r.snapshot[key]);
+      });
+      previous = r.snapshot;
+      var item = { revision: r.revision, at: r.at, author: schema.clone(r.author), status: r.snapshot.status, changed: changed };
+      if (r.review) item.review = schema.clone(r.review);
+      return item;
+    });
+    var deleted = chain.filter(function (r) { return r.op === "delete"; }).pop();
+    if (deleted) revisions.push({ revision: revisions.length + 1, op: "delete", at: deleted.at, author: schema.clone(deleted.author), changed: [] });
+    return { ref: id, revisions: revisions, deleted: !!deleted };
+  }
+  function readRevision(id, revision) {
+    if (!REF.test(id)) throw new Error("Invalid issue reference.");
+    var chain = chainFor(id); var target = Number(revision); var found = null;
+    for (var i = 0; i < chain.length; i++) if ((chain[i].op === "revision" || chain[i].op === "incorporate") && chain[i].revision === target) found = chain[i];
+    if (!found) throw new Error("Issue revision not found.");
+    var result = schema.clone(found.snapshot); result.ref = id; result.revision = target; result.author = schema.clone(found.author); result.at = found.at;
+    if (found.review) result.review = schema.clone(found.review);
+    return result;
+  }
+  return { scopeId: scopeId, filePath: records.filePath, create: create, update: update, comment: comment, review: review, incorporate: incorporate, remove: remove, list: visible, search: visible, read: read, history: history, readRevision: readRevision, records: records };
+}
+
+module.exports = { issueScopeIdForKnowledgeId: issueScopeIdForKnowledgeId, createIssuesStore: createIssuesStore, REF: REF };

package/lib/model-entry.js

@@ -0,0 +1,15 @@
+// Small dependency-free model catalog helpers shared by server resolvers.
+
+function modelEntryValue(entry) {
+  if (!entry) return "";
+  if (typeof entry === "string") return entry;
+  return entry.value || entry.id || "";
+}
+
+function modelEntryMatches(entry, value) {
+  if (!entry || !value) return false;
+  if (typeof entry === "string") return entry === value;
+  return entry.value === value || entry.id === value || entry.resolvedModel === value;
+}
+
+module.exports = { modelEntryValue: modelEntryValue, modelEntryMatches: modelEntryMatches };

package/lib/project-capsule-turn.js

@@ -41,6 +41,7 @@ function attachCapsuleTurn(ctx) {
       ownerId: principal.userId || null,
       vendor: selection.vendor,
       model: selection.model,
+      effort: selection.effort || null,
     });
     session.title = (options.toolName || options.toolId) + " game";
     session.capsuleGame = { toolId: options.toolId };

package/lib/project-connection.js

@@ -96,6 +96,7 @@ function attachConnection(ctx) {
   var getProject = ctx.getProject;
   var warmup = ctx.warmup;
   var scheduledMessages = ctx.scheduledMessages;
+  var sendCursorSharingState = ctx.sendCursorSharingState;
 
   // Adapters are initialized lazily: the first websocket connection into
   // this project triggers warmup. Without this guard we would either keep
@@ -178,6 +179,7 @@ function attachConnection(ctx) {
     }
     var initialModels = (sm.modelsByVendor && sm.modelsByVendor[initialVendor]) || sm.availableModels || [];
     sendTo(ws, { type: "info", cwd: cwd, slug: slug, project: title || project, version: currentVersion, debug: !!debug, dangerouslySkipPermissions: dangerouslySkipPermissions, osUsers: osUsers, lanHost: lanHost, projectCount: _filteredProjects.length, projects: _filteredProjects, projectOwnerId: projectOwnerId, ownerLocked: ownerLocked, vendors: yoke.VENDOR_REGISTRY });
+    if (typeof sendCursorSharingState === "function") sendCursorSharingState(ws);
     // Update notifications are pushed on a scheduled interval (see
     // scheduleUpdateBroadcast). We no longer push on connect to avoid
     // re-triggering the banner on every page refresh.

package/lib/project-delegated-session.js

@@ -15,6 +15,7 @@ function attachDelegatedSession(ctx) {
       sessionVisibility: "private",
       vendor: selection.vendor,
       model: selection.model,
+      effort: selection.effort || null,
     });
     session.title = metadata.title;
     session.assignment = {