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

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/loop-cron.js

@@ -0,0 +1,47 @@
+var validateCron = require("./schedule-validation").validateCron;
+
+function parseField(field, min, max) {
+  var values = [];
+  var parts = field.split(",");
+  for (var i = 0; i < parts.length; i++) {
+    var part = parts[i].trim();
+    if (part.indexOf("/") !== -1) {
+      var slash = part.split("/");
+      var step = parseInt(slash[1], 10);
+      var range = slash[0] === "*" ? [min, max] : slash[0].split("-").map(function (value) { return parseInt(value, 10); });
+      if (range.length === 1) range.push(range[0]);
+      for (var stepped = range[0]; stepped <= range[1]; stepped += step) values.push(stepped);
+    } else if (part === "*") {
+      for (var any = min; any <= max; any++) values.push(any);
+    } else if (part.indexOf("-") !== -1) {
+      var bounds = part.split("-");
+      for (var ranged = parseInt(bounds[0], 10); ranged <= parseInt(bounds[1], 10); ranged++) values.push(ranged);
+    } else values.push(parseInt(part, 10));
+  }
+  return values;
+}
+
+function parse(expr) {
+  if (!validateCron(expr).ok) return null;
+  var fields = expr.trim().split(/\s+/);
+  return { minutes: parseField(fields[0], 0, 59), hours: parseField(fields[1], 0, 23), daysOfMonth: parseField(fields[2], 1, 31), months: parseField(fields[3], 1, 12), daysOfWeek: parseField(fields[4], 0, 6) };
+}
+
+function matches(parsed, date) {
+  return parsed.minutes.indexOf(date.getMinutes()) !== -1 && parsed.hours.indexOf(date.getHours()) !== -1 &&
+    parsed.daysOfMonth.indexOf(date.getDate()) !== -1 && parsed.months.indexOf(date.getMonth() + 1) !== -1 && parsed.daysOfWeek.indexOf(date.getDay()) !== -1;
+}
+
+function nextRunTime(expr, after) {
+  var parsed = parse(expr);
+  if (!parsed) return null;
+  var date = new Date(after || Date.now());
+  date.setSeconds(0, 0); date.setMinutes(date.getMinutes() + 1);
+  for (var i = 0; i < 366 * 24 * 60; i++) {
+    if (matches(parsed, date)) return date.getTime();
+    date.setMinutes(date.getMinutes() + 1);
+  }
+  return null;
+}
+
+module.exports = { nextRunTime: nextRunTime };

package/lib/loop-durable-schedule.js

@@ -0,0 +1,159 @@
+var crypto = require("crypto");
+
+function identity(prefix, projectId, scheduleIdentity, scheduleEpoch, occurrenceAt) {
+  var raw = projectId + "\n" + scheduleIdentity + "\n" + scheduleEpoch + "\n" + occurrenceAt;
+  return prefix + crypto.createHash("sha256").update(raw).digest("hex");
+}
+
+function attachLoopDurableSchedule(ctx) {
+  var scheduler = ctx.scheduler;
+  var registry = ctx.registry;
+  var type = "loop-occurrence:" + ctx.projectId;
+  var unregister = null;
+  var syncing = false;
+
+  function isMultiUser() { return typeof ctx.isMultiUser === "function" ? ctx.isMultiUser() : !!ctx.isMultiUser; }
+
+  function ownerFor(record) {
+    if (!isMultiUser()) return "local-user";
+    return typeof record.ownerId === "string" && record.ownerId ? record.ownerId : null;
+  }
+
+  function jobsFor(recordId) {
+    return scheduler.listJobs().filter(function (job) {
+      return job.type === type && job.projectId === ctx.projectId && job.target && job.target.id === recordId;
+    });
+  }
+
+  function queuedFor(recordId) {
+    var jobs = jobsFor(recordId);
+    for (var i = jobs.length - 1; i >= 0; i--) if (jobs[i].state === "queued") return jobs[i];
+    return null;
+  }
+
+  function spec(record, ownerId) {
+    var dueAt = record.nextRunAt;
+    var occurrenceKey = identity("occurrence:", ctx.projectId, record.scheduleIdentity, record.scheduleEpoch, dueAt);
+    return {
+      idempotencyKey: "loop-" + occurrenceKey,
+      type: type,
+      ownerId: ownerId,
+      projectId: ctx.projectId,
+      target: { kind: "loop-record", id: record.id },
+      payload: { recordId: record.id, occurrenceAt: dueAt, occurrenceKey: occurrenceKey, scheduleIdentity: record.scheduleIdentity, scheduleEpoch: record.scheduleEpoch, recordRevision: Number(record.updatedAt || 0) },
+      runAt: dueAt,
+    };
+  }
+
+  function matchesOccurrence(job, record) {
+    return job && job.payload && job.payload.scheduleIdentity === record.scheduleIdentity &&
+      Number(job.payload.scheduleEpoch) === Number(record.scheduleEpoch) && job.payload.occurrenceAt === record.nextRunAt;
+  }
+
+  function cancelQueued(recordId, reason) {
+    var jobs = jobsFor(recordId);
+    for (var i = 0; i < jobs.length; i++) {
+      if (jobs[i].state === "queued") scheduler.cancel(jobs[i].id, reason);
+    }
+  }
+
+  function syncRecord(record) {
+    var related = jobsFor(record.id);
+    var persistedDueOwned = related.some(function (job) {
+      return ["queued", "claimed", "running"].indexOf(job.state) !== -1 && matchesOccurrence(job, record);
+    });
+    var terminal = null;
+    for (var ti = related.length - 1; ti >= 0; ti--) {
+      if (["completed", "failed", "interrupted"].indexOf(related[ti].state) !== -1 && matchesOccurrence(related[ti], record)) { terminal = related[ti]; break; }
+    }
+    if (terminal && record.enabled && Number.isFinite(record.nextRunAt)) {
+      if (!registry.reconcileDurableOccurrence(record.id, record.nextRunAt)) throw new Error("The interrupted occurrence could not be reconciled.");
+      record = registry.getById(record.id); related = jobsFor(record.id); persistedDueOwned = false;
+    }
+    if (!persistedDueOwned) {
+      record = registry.normalizeDurableOccurrence(record.id, Date.now());
+      if (!record) throw new Error("The scheduled occurrence could not be normalized.");
+      related = jobsFor(record.id);
+    }
+    var queued = queuedFor(record.id);
+    var ownerId = ownerFor(record);
+    if (isMultiUser() && !ownerId) {
+      if (queued) scheduler.cancel(queued.id, "record_requires_owner");
+      registry.markNeedsOwner(record.id);
+      return;
+    }
+    if (!record.enabled || !Number.isFinite(record.nextRunAt)) {
+      if (queued) scheduler.cancel(queued.id, "record_disabled_or_unscheduled");
+      return;
+    }
+    var wanted = spec(record, ownerId);
+    if (queued) {
+      if (matchesOccurrence(queued, record)) {
+        scheduler.replaceQueued(queued.id, wanted);
+        return;
+      }
+      scheduler.cancel(queued.id, "record_schedule_changed");
+    }
+    for (var i = related.length - 1; i >= 0; i--) {
+      if ((related[i].state === "claimed" || related[i].state === "running") && matchesOccurrence(related[i], record)) return;
+      if (related[i].state === "cancelled" && matchesOccurrence(related[i], record)) return;
+    }
+    scheduler.enqueue(wanted);
+  }
+
+  function sync() {
+    if (syncing) return;
+    syncing = true;
+    try {
+      var records = registry.getAll();
+      var present = Object.create(null);
+      for (var i = 0; i < records.length; i++) {
+        present[records[i].id] = true;
+        syncRecord(records[i]);
+      }
+      var jobs = scheduler.listJobs();
+      for (var ji = 0; ji < jobs.length; ji++) {
+        if (jobs[ji].type === type && jobs[ji].state === "queued" && !present[jobs[ji].target.id]) {
+          scheduler.cancel(jobs[ji].id, "record_deleted");
+        }
+      }
+    } finally { syncing = false; }
+  }
+
+  function canRun(job) {
+    var record = registry.getById(job.target.id);
+    if (!record || !record.enabled || !matchesOccurrence(job, record)) return true;
+    if (ownerFor(record) !== job.ownerId) return true;
+    if (ctx.authorize && !ctx.authorize(record, job.ownerId)) return false;
+    return !ctx.canRun || ctx.canRun(record);
+  }
+
+  function dispatch(job, execution) {
+    var record = registry.getById(job.target.id);
+    if (!record) throw new Error("The scheduled record was deleted.");
+    if (!record.enabled || !matchesOccurrence(job, record)) throw new Error("The scheduled occurrence is stale.");
+    if (ownerFor(record) !== job.ownerId) throw new Error("The scheduled record owner changed.");
+    if (ctx.authorize && !ctx.authorize(record, job.ownerId)) throw new Error("The scheduled record owner is no longer authorized.");
+    execution.recordMetadata({ projectId: ctx.projectId, recordId: record.id, occurrenceAt: job.payload.occurrenceAt, recordRevision: Number(record.updatedAt || 0) });
+    var prepared = registry.prepareDurableOccurrence(record.id, job.payload.occurrenceAt);
+    if (!prepared || prepared.ok === false) throw new Error(prepared && prepared.error || "The scheduled occurrence could not be reserved.");
+    execution.recordReceipt({ state: "dispatching", projectId: ctx.projectId, recordId: record.id, occurrenceAt: job.payload.occurrenceAt, recordedAt: Date.now() });
+    var triggerError = null;
+    try { registry.triggerDurableOccurrence(record.id, prepared.value); }
+    catch (error) { triggerError = error; }
+    if (!registry.completeDurableOccurrence(record.id, job.payload.occurrenceAt)) throw new Error("The next scheduled occurrence could not be stored after dispatch.");
+    if (triggerError) throw triggerError;
+    return { dispatched: true, recordId: record.id, occurrenceAt: job.payload.occurrenceAt };
+  }
+
+  unregister = scheduler.registerHandler(type, dispatch, { canRun: canRun });
+  sync();
+  return {
+    sync: sync,
+    wake: function () { try { scheduler.tick(); } catch (error) {} },
+    shutdown: function () { if (unregister) { unregister(); unregister = null; } },
+    type: type,
+  };
+}
+
+module.exports = { attachLoopDurableSchedule: attachLoopDurableSchedule };

package/lib/loop-guidance.js

@@ -0,0 +1,35 @@
+var MAX_CONTEXT = 12000;
+
+function bounded(value) {
+  return typeof value === "string" ? value.substring(0, MAX_CONTEXT) : "";
+}
+
+function commonGuidance() {
+  return "Begin by clarifying any missing goal, scope, constraints, or target files. Inspect the relevant project code and tests before drafting. Produce a self-contained, goal-oriented brief that names the intended outcome, boundaries, and concrete evidence-based completion checks; every check must identify an observable artifact, behavior, or test result, never vague quality language. Review the brief with the user and refine it before any Start or file write. Do not claim completion without the stated evidence.";
+}
+
+function structuredQuestionGuidance() {
+  return "When clarification is needed, prefer the available structured question capability: AskUserQuestion, request_user_input, or Clay ask_user_questions (including its namespaced fallback). Ask only the minimum necessary, at most 1-3 concise questions per turn; provide 2-6 choices for bounded decisions and use a freeform question when choices would constrain the answer. Do not repeat information already established. Use plain chat only when no structured question capability is available.";
+}
+
+function interviewPrompt() {
+  return commonGuidance() + " " + structuredQuestionGuidance() + " Use the current chat and repository context. This is the built-in interactive Loop interview: after review, call propose_loop with the bounded objective, criteria, and limits. Do not execute, arm permissions, invoke /clay-ralph, require skills, use plan mode, create PROMPT.md/JUDGE.md, or start a run; wait for the human Start action.";
+}
+
+function legacyCraftPrompt(options) {
+  var opts = options || {};
+  var task = bounded(opts.task);
+  var directory = bounded(opts.directory);
+  var filePlan = opts.simple ? "Create only PROMPT.md; this Simple Loop has no judge." : opts.userJudge ? "Create only PROMPT.md; preserve the user's JUDGE.md and do not replace or edit it." : opts.judgeOnly ? "Create only JUDGE.md for the existing PROMPT.md; do not create or modify PROMPT.md." : "Create PROMPT.md and, when this is a judged Loop, JUDGE.md.";
+  return commonGuidance() + " " + structuredQuestionGuidance() + " This is legacy scheduled Loop file crafting. " +
+    "The files are the durable handoff to a future fresh session: that session starts from the target directory and reads the files from disk, so make each file self-contained and do not rely on this chat's transient context. " +
+    "Respect any user-provided files and the target directory; inspect existing files before writing and never overwrite a user-provided file. " + filePlan + " " +
+    "A separate judge is applicable only for judged Loops; it evaluates observable evidence from the fresh execution session and must not perform the task itself. Never make an automatic commit.\n\n" +
+    "## Task\n" + task + "\n\n## Loop Directory\n" + directory;
+}
+
+module.exports = {
+  commonGuidance: commonGuidance,
+  interviewPrompt: interviewPrompt,
+  legacyCraftPrompt: legacyCraftPrompt,
+};

package/lib/loop-registry-occurrence.js

@@ -0,0 +1,76 @@
+var recordRevision = require("./record-revision");
+
+function attachLoopRegistryOccurrence(ctx) {
+  function normalize(id, now) {
+    var rec = ctx.getById(id);
+    if (!rec || !rec.enabled || !rec.scheduleRule || !rec.nextRunAt || rec.nextRunAt > now - 60000) return rec;
+    var next = ctx.nextRecordRunTime(rec, now - 60000);
+    if (Number(next) === Number(rec.nextRunAt)) return rec;
+    var previous = JSON.parse(JSON.stringify(rec));
+    rec.nextRunAt = next;
+    if (!next) rec.enabled = false;
+    if (!ctx.save()) { recordRevision.restoreRecord(rec, previous); return null; }
+    ctx.changed();
+    return rec;
+  }
+
+  function markNeedsOwner(id) {
+    var rec = ctx.getById(id);
+    if (!rec || rec.needsOwner === true) return false;
+    var previous = JSON.parse(JSON.stringify(rec));
+    rec.needsOwner = true;
+    rec.setupRequired = "owner";
+    rec.enabled = false;
+    rec.nextRunAt = null;
+    rec.scheduleEpoch = Math.max(1, Number(rec.scheduleEpoch) || 1) + 1;
+    rec.updatedAt = recordRevision.nextRevision(rec);
+    if (!ctx.save()) { recordRevision.restoreRecord(rec, previous); return false; }
+    ctx.changed();
+    return true;
+  }
+
+  function prepare(id, occurrenceAt) {
+    var rec = ctx.getById(id);
+    if (!rec || !rec.enabled || Number(rec.nextRunAt) !== Number(occurrenceAt)) return { ok: false, error: "The scheduled occurrence is stale." };
+    var previous = JSON.parse(JSON.stringify(rec));
+    var prepared = ctx.prepareTrigger ? ctx.prepareTrigger(rec) : null;
+    if (prepared && prepared.ok === false) return prepared;
+    ctx.scheduledRuns.prepareRecord(rec, prepared);
+    if (!ctx.save()) { recordRevision.restoreRecord(rec, previous); return { ok: false, error: ctx.lastSaveError() || "The occurrence reservation could not be stored." }; }
+    ctx.changed();
+    return { ok: true, value: prepared };
+  }
+
+  function trigger(id, prepared) {
+    var rec = ctx.getById(id);
+    if (!rec) throw new Error("The scheduled record was deleted.");
+    if (ctx.onTrigger) ctx.onTrigger(rec, prepared);
+  }
+
+  function advance(id, occurrenceAt, result) {
+    var rec = ctx.getById(id);
+    if (!rec || Number(rec.nextRunAt) !== Number(occurrenceAt)) return false;
+    var previous = JSON.parse(JSON.stringify(rec));
+    var now = Date.now();
+    rec.lastRunAt = result === "interrupted" ? occurrenceAt : now;
+    if (result) rec.lastRunResult = result;
+    if (rec.scheduleRule) ctx.scheduleRule.recordScheduleStartState(rec, occurrenceAt);
+    if (rec.cron || rec.scheduleRule) {
+      rec.nextRunAt = ctx.nextRecordRunTime(rec, now);
+      if (rec.scheduleRule && !rec.nextRunAt) rec.enabled = false;
+    } else {
+      rec.nextRunAt = null;
+      rec.enabled = false;
+    }
+    if (!ctx.save()) { recordRevision.restoreRecord(rec, previous); return false; }
+    ctx.changed();
+    return true;
+  }
+
+  function complete(id, occurrenceAt) { return advance(id, occurrenceAt, null); }
+  function reconcile(id, occurrenceAt) { return advance(id, occurrenceAt, "interrupted"); }
+
+  return { normalize: normalize, markNeedsOwner: markNeedsOwner, prepare: prepare, trigger: trigger, complete: complete, reconcile: reconcile };
+}
+
+module.exports = { attachLoopRegistryOccurrence: attachLoopRegistryOccurrence };

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 };