clay-server 4.0.0-beta.15 → 4.0.0-beta.17

package/lib/project-capsule-turn.js

@@ -0,0 +1,96 @@
+// Delivers a Capsule turn prompt into this Mate project.
+//
+// A Capsule game against a Mate needs the Mate to actually take its turns:
+// when Logic passes the turn to the mate seat, this module wakes the Mate
+// with a prompt telling it to snapshot the game and act. One session hosts
+// the whole game (found again by session.capsuleGame.toolId), so the user
+// watches a single running conversation of the Mate playing rather than a
+// new session per turn. The prompt is recorded as an internal user message,
+// the same shape the debate engine uses, so the transcript shows the nudge
+// without pretending the human typed it.
+//
+// This module only carries words to the Mate. Every actual game mutation the
+// Mate then makes goes through the same clay_tool_act pipeline as always.
+
+function attachCapsuleTurn(ctx) {
+  var sm = ctx.sm;
+
+  function ownsSession(session, principal) {
+    if (ctx.isMultiUser()) return !!principal.userId && session.ownerId === principal.userId;
+    return !session.ownerId;
+  }
+
+  function findGameSession(principal, toolId) {
+    var found = null;
+    sm.sessions.forEach(function (session) {
+      if (found || !session || session.hidden || session.destroying) return;
+      if (!session.capsuleGame || session.capsuleGame.toolId !== toolId) return;
+      if (!ownsSession(session, principal)) return;
+      found = session;
+    });
+    return found;
+  }
+
+  async function createGameSession(principal, options) {
+    var selection = await ctx.resolveModel(principal);
+    if (!selection || selection.status !== "ready" || !selection.vendor || !selection.model) {
+      throw new Error(selection && selection.error ? selection.error : "No configured model is available for the Mate.");
+    }
+    var create = typeof sm.createSessionRaw === "function" ? sm.createSessionRaw : sm.createSession;
+    var session = create.call(sm, {
+      ownerId: principal.userId || null,
+      vendor: selection.vendor,
+      model: selection.model,
+    });
+    session.title = (options.toolName || options.toolId) + " game";
+    session.capsuleGame = { toolId: options.toolId };
+    return session;
+  }
+
+  async function deliverCapsuleTurn(principal, options) {
+    if (!principal || !options || !options.toolId || !options.text) {
+      throw new Error("A bound owner, toolId, and turn text are required.");
+    }
+    var sdk = ctx.getSdk();
+    if (!sdk || typeof sdk.startQuery !== "function") throw new Error("Mate project runtime is unavailable.");
+    var session = findGameSession(principal, options.toolId);
+    var created = false;
+    if (!session) {
+      session = await createGameSession(principal, options);
+      created = true;
+    }
+    // Recorded as a dedicated event, not a user message: the transcript shows
+    // a short system note (see historyToHomeChat) instead of pretending the
+    // human typed the delivery prompt. The full prompt still reaches the
+    // model through the query below.
+    sm.sendAndRecord(session, {
+      type: "capsule_turn",
+      text: options.text,
+      toolId: options.toolId,
+      toolName: options.toolName || options.toolId,
+      kind: options.kind || "turn",
+    });
+    session.isProcessing = true;
+    session.lastActivity = Date.now();
+    sm.broadcastSessionList();
+    try {
+      var delivered = typeof sdk.pushMessage === "function" ? sdk.pushMessage(session, options.text) : false;
+      if (!delivered) await Promise.resolve(sdk.startQuery(session, options.text, undefined, ctx.getLinuxUserForSession(session)));
+    } catch (error) {
+      session.isProcessing = false;
+      sm.sendAndRecord(session, { type: "error", text: "Capsule turn could not start: " + (error && error.message ? error.message : String(error)) });
+      sm.broadcastSessionList();
+      throw error;
+    }
+    // The reference shape the home chat surface opens sessions by.
+    return {
+      session: session,
+      created: created,
+      reference: (typeof session.cliSessionId === "string" && session.cliSessionId) || "local:" + session.localId,
+    };
+  }
+
+  return { deliverCapsuleTurn: deliverCapsuleTurn };
+}
+
+module.exports = { attachCapsuleTurn: attachCapsuleTurn };

package/lib/project-log-context.js

@@ -0,0 +1,171 @@
+// Stable project knowledge and Git worktree change-set identities.
+//
+// Existing projects freeze their current path-derived scope so every opaque
+// log ref remains valid. New projects receive a path-independent id. A linked
+// worktree stores its generated change-set marker in Git's administrative
+// directory, which survives daemon restarts and branch renames but disappears
+// with the worktree itself; the durable log records retain the id afterward.
+
+var crypto = require("crypto");
+var fs = require("fs");
+var path = require("path");
+var execFileSync = require("child_process").execFileSync;
+var logsRoot = require("./project-logs-root");
+var utils = require("./utils");
+
+var ID_PATTERN = /^[A-Za-z0-9_-]{1,120}$/;
+
+function newId(prefix) {
+  return prefix + "_" + crypto.randomBytes(16).toString("base64url");
+}
+
+function validId(value, prefix) {
+  return typeof value === "string" && ID_PATTERN.test(value) && (!prefix || value.indexOf(prefix + "_") === 0);
+}
+
+function legacyKnowledgeId(cwd) {
+  return utils.encodeCwd(logsRoot.resolveProjectRoot(cwd));
+}
+
+function ensureProjectKnowledgeId(project) {
+  if (!project || typeof project !== "object") return false;
+  if (validId(project.projectKnowledgeId)) return false;
+  project.projectKnowledgeId = project.path ? legacyKnowledgeId(project.path) : newId("pk");
+  return true;
+}
+
+function initializeProjectKnowledge(config) {
+  var changed = false;
+  var projects = config && Array.isArray(config.projects) ? config.projects : [];
+  for (var i = 0; i < projects.length; i++) {
+    if (ensureProjectKnowledgeId(projects[i])) changed = true;
+  }
+  return changed;
+}
+
+function createProjectKnowledgeId() {
+  return newId("pk");
+}
+
+function git(cwd, args) {
+  return execFileSync("git", args, {
+    cwd: cwd,
+    encoding: "utf8",
+    timeout: 5000,
+    stdio: ["pipe", "pipe", "pipe"],
+  }).trim();
+}
+
+function commit(cwd, ref) {
+  try { return git(cwd, ["rev-parse", ref || "HEAD"]); }
+  catch (e) { return null; }
+}
+
+function markerPath(cwd) {
+  try {
+    var gitDir = git(cwd, ["rev-parse", "--git-dir"]);
+    return path.join(path.resolve(cwd, gitDir), "clay-change-set.json");
+  } catch (e) {
+    return null;
+  }
+}
+
+function readMarker(filePath, knowledgeId) {
+  if (!filePath) return null;
+  try {
+    var parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    if (!parsed || parsed.projectKnowledgeId !== knowledgeId || !validId(parsed.changeSetId, "cs")) return null;
+    return parsed;
+  } catch (e) {
+    return null;
+  }
+}
+
+function deterministicFallback(knowledgeId, cwd) {
+  var digest = crypto.createHash("sha256").update(knowledgeId + "\u0000" + logsRoot.canonicalPath(cwd)).digest("base64url");
+  return "cs_" + digest.substring(0, 22);
+}
+
+function resolveWorktreeContext(cwd, knowledgeId, details) {
+  var input = details || {};
+  var filePath = markerPath(cwd);
+  var marker = readMarker(filePath, knowledgeId);
+  if (!marker) {
+    marker = {
+      projectKnowledgeId: knowledgeId,
+      changeSetId: newId("cs"),
+      baseCommit: input.baseCommit || null,
+      createdAt: Date.now(),
+    };
+    if (filePath) {
+      try {
+        fs.writeFileSync(filePath, JSON.stringify(marker, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+      } catch (e) {
+        marker = readMarker(filePath, knowledgeId) || marker;
+      }
+    }
+  }
+  if (!filePath || !readMarker(filePath, knowledgeId)) {
+    marker.changeSetId = deterministicFallback(knowledgeId, cwd);
+  }
+  return {
+    kind: "worktree",
+    changeSetId: marker.changeSetId,
+    branch: input.branch || null,
+    baseCommit: marker.baseCommit || input.baseCommit || null,
+    headCommit: commit(cwd, "HEAD"),
+    status: "active",
+  };
+}
+
+function isMerged(parentCwd, worktreeCwd) {
+  var head = commit(worktreeCwd, "HEAD");
+  if (!head) return false;
+  try {
+    execFileSync("git", ["merge-base", "--is-ancestor", head, "HEAD"], {
+      cwd: parentCwd,
+      timeout: 5000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function cleanCommit(value) {
+  return typeof value === "string" && /^[0-9a-f]{7,64}$/i.test(value) ? value : null;
+}
+
+function cleanBranch(value) {
+  if (typeof value !== "string") return null;
+  var cleaned = value.trim().substring(0, 200);
+  return cleaned && cleaned.indexOf("\n") === -1 && cleaned.indexOf("\r") === -1 ? cleaned : null;
+}
+
+function normalizeRecordContext(value) {
+  if (!value || value.kind !== "worktree" || !validId(value.changeSetId, "cs")) {
+    return { kind: "project", changeSetId: null, branch: null, baseCommit: null, headCommit: null, status: "active" };
+  }
+  return {
+    kind: "worktree",
+    changeSetId: value.changeSetId,
+    branch: cleanBranch(value.branch),
+    baseCommit: cleanCommit(value.baseCommit),
+    headCommit: cleanCommit(value.headCommit),
+    status: value.status === "merged" || value.status === "archived" ? value.status : "active",
+  };
+}
+
+module.exports = {
+  ID_PATTERN: ID_PATTERN,
+  validId: validId,
+  legacyKnowledgeId: legacyKnowledgeId,
+  ensureProjectKnowledgeId: ensureProjectKnowledgeId,
+  initializeProjectKnowledge: initializeProjectKnowledge,
+  createProjectKnowledgeId: createProjectKnowledgeId,
+  resolveWorktreeContext: resolveWorktreeContext,
+  commit: commit,
+  isMerged: isMerged,
+  normalizeRecordContext: normalizeRecordContext,
+};

package/lib/project-log-feedback-delivery.js

@@ -1,6 +1,6 @@
-// Deliver new Project Log comments to the exact live session responsible for
-// the canonical entry. Comments remain durable in the ledger when that session
-// is gone; this module never guesses another session or creates one.
+// Deliver new Project Log comments to the session responsible for the
+// canonical entry. A busy Driver gets an isolated hidden reviewer so feedback
+// never waits behind unrelated work in the visible conversation.
 
 function attachProjectLogFeedbackDelivery(ctx) {
   var sm = ctx.sm;
@@ -8,8 +8,7 @@ function attachProjectLogFeedbackDelivery(ctx) {
   var onProcessingChanged = ctx.onProcessingChanged || function () {};
   var getLinuxUserForSession = ctx.getLinuxUserForSession || function () { return null; };
 
-  function findAuthorSession(entry) {
-    var author = entry && entry.updatedBy;
+  function sessionForAuthor(author) {
     if (!author || author.type !== "session" || !author.sessionKey) return null;
     var match = null;
     sm.sessions.forEach(function (session) {
@@ -22,6 +21,48 @@ function attachProjectLogFeedbackDelivery(ctx) {
     return match;
   }
 
+  function findAuthorSession(entry) {
+    return sessionForAuthor(entry && entry.updatedBy) || sessionForAuthor(entry && entry.createdBy);
+  }
+
+  function startImmediateReviewer(source, entry, text, sdk) {
+    if (!sm.createSessionRaw || !sm.deleteSessionQuiet) return false;
+    var reviewer = sm.createSessionRaw({
+      ownerId: source.ownerId || null,
+      sessionVisibility: "private",
+      vendor: source.vendor || null,
+      model: source.model || null,
+      effort: source.effort || null,
+      permissionMode: source.permissionMode || null,
+    });
+    reviewer.hidden = true;
+    reviewer.title = "Project Log review";
+    reviewer.singleTurn = true;
+    reviewer.projectLogReview = { ref: entry.ref };
+    reviewer.isProcessing = true;
+    reviewer.sentToolResults = {};
+    reviewer.onQueryComplete = function () {
+      setImmediate(function () { sm.deleteSessionQuiet(reviewer.localId); });
+    };
+    sm.sendAndRecord(reviewer, {
+      type: "user_message",
+      text: text,
+      _internal: true,
+      projectLogFeedback: true,
+      projectLogRef: entry.ref,
+    });
+    Promise.resolve(sdk.startQuery(reviewer, text, null, getLinuxUserForSession(reviewer))).catch(function (error) {
+      reviewer.isProcessing = false;
+      sm.sendAndRecord(reviewer, {
+        type: "error",
+        text: "Could not review Project Log feedback: " + (error.message || String(error)),
+        _internal: true,
+      });
+      sm.deleteSessionQuiet(reviewer.localId);
+    });
+    return true;
+  }
+
   function feedbackPrompt(entry) {
     return "[Project Log feedback]\n" +
       "A user added a comment to " + entry.ref + ". Review the pending feedback now with list_log_feedback, " +
@@ -37,6 +78,7 @@ function attachProjectLogFeedbackDelivery(ctx) {
     var sdk = getSdk();
     if (!session || !sdk) return false;
     var text = feedbackPrompt(entry);
+    if (session.isProcessing && startImmediateReviewer(session, entry, text, sdk)) return true;
     sm.sendAndRecord(session, {
       type: "user_message",
       text: text,

package/lib/project-logs-context-state.js

@@ -0,0 +1,42 @@
+// Append-only lifecycle projection for worktree-scoped Project Log entries.
+
+var recordStore = require("./knowledge-record-store");
+var logContext = require("./project-log-context");
+
+function attachContextState(store, scopeId) {
+  function states() {
+    var out = {};
+    var records = store.all();
+    for (var i = 0; i < records.length; i++) {
+      var record = records[i];
+      if (record.op !== "context-state" || !record.changeSetId) continue;
+      if (record.status !== "archived" && record.status !== "merged" && record.status !== "active") continue;
+      out[record.changeSetId] = record.status;
+    }
+    return out;
+  }
+
+  function set(context, status) {
+    var normalized = logContext.normalizeRecordContext(context);
+    if (!normalized.changeSetId) return false;
+    if (status !== "active" && status !== "archived" && status !== "merged") {
+      throw new Error("Invalid Project Log change-set status.");
+    }
+    if (states()[normalized.changeSetId] === status) return false;
+    store.append({
+      id: recordStore.newRecordId(),
+      rootId: "context-" + normalized.changeSetId,
+      op: "context-state",
+      scope: scopeId,
+      changeSetId: normalized.changeSetId,
+      status: status,
+      context: normalized,
+      at: Date.now(),
+    });
+    return true;
+  }
+
+  return { states: states, set: set };
+}
+
+module.exports = { attachContextState: attachContextState };

package/lib/project-logs-mcp-server.js

@@ -12,14 +12,15 @@ var logsSchema = require("./project-logs-schema");
 var logsComments = require("./project-logs-comments");
 
 var LOGS_CONTRACT =
-  "Project Logs are this project's durable record of decisions and work, written the way a good Git history reads. " +
+  "Project Logs are this project's durable work-continuity record, written so a newly created Driver can understand what the user asked for, what happened, and what remains without reading the previous chat. " +
   "You are the only author: connected people read the log and may add comments, but they cannot create or revise entries. That makes accuracy your responsibility. " +
-  "Write an entry when the project gains something worth knowing weeks from now: a decision and the reasoning behind it, a security finding, an investigation's outcome, an incident and its resolution, an operational runbook, a durable reference, or real progress. " +
-  "Every entry needs a concise meaningful title, a one or two sentence summary explaining what was decided or done and why, and a category. Set priority when an entry genuinely outranks routine work. " +
+  "Log every concrete user work instruction that changes, diagnoses, designs, or verifies project state, not only unusually important work. Create or identify one entry for the coherent task, then revise that same entry as work progresses instead of creating one entry per turn. " +
+  "The entry must preserve the user's requested outcome and material constraints, followed by what was changed, discovered, or decided, the affected area, verification, and the current result. If work is incomplete or blocked, state the remaining work and next action explicitly. For a small task, one completed entry is enough; for longer work, create it when the task starts and update it at meaningful milestones and completion. " +
+  "Every entry needs a concise meaningful title, a one or two sentence summary that combines the request with the current outcome, and a category. Set priority when an entry genuinely outranks routine work; routine work still belongs in the ledger at normal priority. " +
   "Categories are this project's own evolving vocabulary rather than a fixed list: list or search first, reuse an established category when one fits, and coin a new concise one only when the project needs a durable distinction it lacks. " +
   "Prefer updating an existing entry over creating a near-duplicate: when a decision supersedes an earlier one, revise that entry so its history shows the change. " +
-  "Do not log conversation summaries, task narration, restatements of the request, completed-work announcements, speculation, or anything the repository and its history already record. " +
-  "Every write is attributed and permanently revision-tracked, so keep entries short, concrete, and true.";
+  "Do not paste raw conversation transcripts, log command-by-command narration, trivial confirmations, or speculation. Repository history may show the code change but usually does not preserve the user's intent, constraints, verification, or unfinished state, so it is not a substitute for the work log. " +
+  "Every write is attributed and permanently revision-tracked, so keep entries concise, concrete, and true while retaining enough context for a clean Driver handoff.";
 
 // User learning moments are a durable project asset, so capturing them is a
 // default rather than an option. This category is about a change in the user's
@@ -75,8 +76,9 @@ var CATEGORY_DESCRIPTION = "Record category: a short lowercase hyphen-separated
   "Common starting points are " + logsSchema.SEED_CATEGORIES.join(", ") + ". A category is dry metadata, never a persona or an identifier. " +
   "Use `learning` only for a user learning moment described by the learning contract, never for knowledge or lessons acquired by the Driver.";
 var PRIORITY_DESCRIPTION = "How much this outranks routine work: " + logsSchema.PRIORITIES.join(", ") + ". Defaults to normal. Priority is independent of category, so an urgent decision is both.";
-var SUMMARY_DESCRIPTION = "One or two sentences explaining what was decided or done and why. This is what a reader sees in the ledger, so it must stand alone. For a learning entry, identify the concept the user engaged with plainly enough that the row itself teaches it.";
+var SUMMARY_DESCRIPTION = "One or two sentences combining the user's requested outcome with the current result or status. This is what a new Driver sees in the ledger, so it must stand alone. For a learning entry, identify the concept the user engaged with plainly enough that the row itself teaches it.";
 var REF_DESCRIPTION = "Opaque log reference returned by list_logs, search_logs, or create_log.";
+var CONTEXT_DESCRIPTION = "Optional logical scope: current includes project-wide entries plus this worktree's change set, project shows only project-wide entries, and all includes archived and merged worktree changes. Defaults to current in a worktree and project otherwise.";
 
 function textResult(value) {
   return Promise.resolve({ content: [{ type: "text", text: JSON.stringify(value) }] });
@@ -113,6 +115,7 @@ function projectTools(bound) {
         kind: { type: "string", description: "Optional category filter, matched exactly against this project's vocabulary. The response lists the categories currently in use." },
         priority: { type: "string", enum: logsSchema.PRIORITIES, description: "Optional priority filter." },
         tag: { type: "string", description: "Optional single tag filter." },
+        contextMode: { type: "string", enum: ["current", "project", "all"], description: CONTEXT_DESCRIPTION },
         cursor: { type: "string", description: "Opaque pagination cursor from a previous response." },
         limit: { type: "number", description: "Page size, from 1 to " + logsStore.MAX_PAGE + "." },
       }),
@@ -125,6 +128,7 @@ function projectTools(bound) {
         query: { type: "string", description: "Search query." },
         kind: { type: "string", description: "Optional category filter, matched exactly against this project's vocabulary. The response lists the categories currently in use." },
         priority: { type: "string", enum: logsSchema.PRIORITIES, description: "Optional priority filter." },
+        contextMode: { type: "string", enum: ["current", "project", "all"], description: CONTEXT_DESCRIPTION },
         cursor: { type: "string", description: "Opaque pagination cursor from a previous response." },
         limit: { type: "number", description: "Page size, from 1 to " + logsStore.MAX_PAGE + "." },
       }, ["query"]),
@@ -148,27 +152,27 @@ function projectTools(bound) {
     },
     {
       name: "create_log",
-      description: LOGS_CONTRACT + " " + LEARNING_CONTRACT + " Create a log entry in this project. Apply the test first: will someone need this fact weeks from now, and is it not already recorded? If it supersedes an existing entry, revise that entry instead of adding a new one.",
+      description: LOGS_CONTRACT + " " + LEARNING_CONTRACT + " Create a log entry for a new coherent user-directed task or durable project record. Search first; if the task already has an entry, revise it instead of adding a duplicate.",
       inputSchema: buildShape({
         kind: { type: "string", description: CATEGORY_DESCRIPTION },
         priority: { type: "string", enum: logsSchema.PRIORITIES, description: PRIORITY_DESCRIPTION },
         title: { type: "string", description: "Short factual title, plain text, written like a good commit subject." },
         summary: { type: "string", description: SUMMARY_DESCRIPTION },
-        body: { type: "string", description: "The durable facts, context, and outcome in Markdown. No narration of your own activity. For a learning entry, cover the user's original wording or mental model, the precise concept, how it applies here, and any boundary or misconception." },
+        body: { type: "string", description: "The concise continuity record in Markdown: requested outcome and constraints, work/result, affected area, verification, current status, and next action when unfinished. Omit raw transcripts and command-by-command narration. For a learning entry, cover the user's original wording or mental model, the precise concept, how it applies here, and any boundary or misconception." },
         tags: { type: "string", description: "Optional JSON array of short tag strings." },
       }, ["kind", "title", "summary"]),
       handler: handler(bound, "createLog"),
     },
     {
       name: "update_log",
-      description: LOGS_CONTRACT + " " + LEARNING_CONTRACT + " Revise an existing log entry, including when a later decision supersedes it, or when new learning refines an existing learning entry. The previous revision, its title, and its summary are all retained in the entry history.",
+      description: LOGS_CONTRACT + " " + LEARNING_CONTRACT + " Revise the coherent task entry when work progresses, completes, becomes blocked, or a later decision supersedes it. Also revise when new learning refines an existing learning entry. The previous revision, its title, and its summary are all retained in the entry history.",
       inputSchema: buildShape({
         ref: { type: "string", description: REF_DESCRIPTION },
         kind: { type: "string", description: CATEGORY_DESCRIPTION },
         priority: { type: "string", enum: logsSchema.PRIORITIES, description: PRIORITY_DESCRIPTION },
         title: { type: "string", description: "Replacement title. The previous title stays in the entry's history." },
         summary: { type: "string", description: "Replacement summary. The previous summary stays in the entry's history." },
-        body: { type: "string", description: "Replacement record body in Markdown." },
+        body: { type: "string", description: "Replacement continuity record body in Markdown, including the request, current result, verification, and any remaining next action." },
         tags: { type: "string", description: "Optional JSON array of short tag strings, replacing the current tags." },
       }, ["ref"]),
       handler: handler(bound, "updateLog"),
@@ -238,6 +242,7 @@ function globalTools(bound) {
         kind: { type: "string", description: "Optional category filter, matched exactly against this project's vocabulary. The response lists the categories currently in use." },
         priority: { type: "string", enum: logsSchema.PRIORITIES, description: "Optional priority filter." },
         tag: { type: "string", description: "Optional single tag filter." },
+        contextMode: { type: "string", enum: ["project", "all"], description: CONTEXT_DESCRIPTION },
         cursor: { type: "string", description: "Opaque pagination cursor from a previous response." },
         limit: { type: "number", description: "Page size, from 1 to " + logsStore.MAX_PAGE + "." },
       }, ["projectSlug"]),
@@ -251,6 +256,7 @@ function globalTools(bound) {
         query: { type: "string", description: "Search query." },
         kind: { type: "string", description: "Optional category filter, matched exactly against this project's vocabulary. The response lists the categories currently in use." },
         priority: { type: "string", enum: logsSchema.PRIORITIES, description: "Optional priority filter." },
+        contextMode: { type: "string", enum: ["project", "all"], description: CONTEXT_DESCRIPTION },
         cursor: { type: "string", description: "Opaque pagination cursor from a previous response." },
         limit: { type: "number", description: "Page size, from 1 to " + logsStore.MAX_PAGE + "." },
       }, ["projectSlug", "query"]),

package/lib/project-logs-query.js

@@ -62,6 +62,19 @@ function page(items, args) {
   };
 }
 
+function contextMode(options) {
+  var value = options && options.contextMode;
+  return value === "all" || value === "current" || value === "project" ? value : "all";
+}
+
+function matchesContext(entry, options) {
+  var mode = contextMode(options);
+  var changeSetId = entry && entry.context && entry.context.changeSetId;
+  if (mode === "all") return true;
+  if (mode === "project") return !changeSetId;
+  return !changeSetId || changeSetId === options.currentChangeSetId;
+}
+
 function listEntries(entries, args, cleanLine, validateKind) {
   var options = args || {};
   var kind = options.kind ? validateKind(options.kind, null) : null;
@@ -73,6 +86,7 @@ function listEntries(entries, args, cleanLine, validateKind) {
     if (kind && entry.category !== kind) return false;
     if (priority && entry.priority !== priority) return false;
     if (tag && entry.tags.indexOf(tag) === -1) return false;
+    if (!matchesContext(entry, options)) return false;
     return true;
   });
   var result = page(filtered, options);
@@ -116,6 +130,7 @@ function summarize(entry) {
     // How many comments still await Driver review. A count only: the ledger
     // never carries comment bodies.
     pendingFeedbackCount: entry.pendingFeedbackCount || 0,
+    context: entry.context || null,
   };
 }
 
@@ -128,6 +143,7 @@ function searchEntries(entries, args, cleanLine, validateKind) {
   var candidates = entries.filter(function (entry) {
     if (kind && entry.category !== kind) return false;
     if (priority && entry.priority !== priority) return false;
+    if (!matchesContext(entry, options)) return false;
     return true;
   });
 
@@ -161,6 +177,8 @@ module.exports = {
   encodeCursor: encodeCursor,
   decodeCursor: decodeCursor,
   page: page,
+  contextMode: contextMode,
+  matchesContext: matchesContext,
   summarize: summarize,
   listEntries: listEntries,
   searchEntries: searchEntries,

package/lib/project-logs-root.js

@@ -60,8 +60,16 @@ function scopeIdForRoot(root) {
   return "project/" + utils.encodeCwd(root);
 }
 
+function scopeIdForKnowledgeId(knowledgeId) {
+  if (typeof knowledgeId !== "string" || !/^[A-Za-z0-9_-]{1,120}$/.test(knowledgeId)) {
+    throw new Error("Invalid project knowledge id.");
+  }
+  return "project/" + knowledgeId;
+}
+
 module.exports = {
   resolveProjectRoot: resolveProjectRoot,
   scopeIdForRoot: scopeIdForRoot,
+  scopeIdForKnowledgeId: scopeIdForKnowledgeId,
   canonicalPath: canonicalPath,
 };